Struct RoutingModifiers 

pub struct RoutingModifiers<'a> { /* private fields */ }

The type returned by Blueprint::prefix and Blueprint::domain.

Customize routing behaviour for a subset of routes.

Implementations

impl<'a> RoutingModifiers<'a>

pub fn domain(self, domain: &str) -> Self

Only requests to the specified domain will be forwarded to routes nested under this condition.

Check out Blueprint::domain for more details.

pub fn prefix(self, prefix: &str) -> Self

Prepends a common prefix to all routes nested under this condition.

If a prefix has already been set, it will be overridden.

Check out Blueprint::prefix for more details.

pub fn nest(self, bp: Blueprint)

Nest a Blueprint, optionally applying a common prefix and a domain restriction to all its routes.

Nesting also has consequences when it comes to constructors’ visibility.

Constructors

Constructors registered against the parent blueprint will be available to the nested blueprint—they are inherited. Constructors registered against the nested blueprint will not be available to other sibling blueprints that are nested under the same parent—they are private.

Check out the example below to better understand the implications of nesting blueprints.

Visibility

use pavex::{blueprint::from, Blueprint};

fn app() -> Blueprint {
    let mut bp = Blueprint::new();
    bp.constructor(DB_CONNECTION_POOL);
    bp.nest(home_bp());
    bp.nest(user_bp());
    bp
}

/// All property-related routes and constructors.
fn home_bp() -> Blueprint {
    let mut bp = Blueprint::new();
    bp.import(from![crate::home]);
    bp.routes(from![crate::home]);
    bp
}

/// All user-related routes and constructors.
fn user_bp() -> Blueprint {
    let mut bp = Blueprint::new();
    bp.import(from![crate::user]);
    bp.routes(from![crate::user]);
    bp
}

#[pavex::singleton]
pub fn db_connection_pool() -> ConnectionPool {
    // [...]
}

pub mod home {
    // [...]
}

pub mod user {
    pub fn get_session() -> Session {
        // [...]
    }
    // [...]
}

In this example, we import two constructors:

• crate::user::get_session, for Session;
• crate::db_connection_pool, for ConnectionPool.

The constructors defined in the crate::user module are only imported by the user_bp blueprint. Since we are nesting the user_bp blueprint, those constructors will only be available to the routes declared in the user_bp blueprint. If a route declared in home_bp tries to inject a Session, Pavex will report an error at compile-time, complaining that there is no registered constructor for Session. In other words, all constructors imported in the user_bp blueprint are private and isolated from the rest of the application.

The db_connection_pool constructor, instead, is declared against the parent blueprint and will therefore be available to all routes declared in home_bp and user_bp—i.e. nested blueprints inherit all the constructors declared against their parent(s).

Precedence

If a constructor is declared against both the parent and one of its nested blueprints, the one declared against the nested blueprint takes precedence.

use pavex::{blueprint::from, Blueprint};

fn app() -> Blueprint {
    let mut bp = Blueprint::new();
    // These constructors are registered against the root blueprint and they're visible
    // to all nested blueprints.
    bp.import(from![crate::global]);
    bp.nest(user_bp());
    // [..]
    bp
}

fn user_bp() -> Blueprint {
    let mut bp = Blueprint::new();
    // They can be overridden by a constructor for the same type registered
    // against a nested blueprint.
    // All routes in `user_bp` will use `user::get_session` instead of `global::get_session`.
    bp.import(from![crate::user]);
    // [...]
    bp
}

pub mod global {
    pub fn get_session() -> Session {
        // [...]
    }
}

pub mod user {
    pub fn get_session() -> Session {
        // [...]
    }
}

Singletons

There is one exception to the precedence rule: singletons. Pavex guarantees that there will be only one instance of a singleton type for the entire lifecycle of the application. What should happen if two different constructors are registered for the same Singleton type by two nested blueprints that share the same parent? We can’t honor both constructors without ending up with two different instances of the same type, which would violate the singleton contract.

It goes one step further! Even if those two constructors are identical, what is the expected behaviour? Does the user expect the same singleton instance to be injected in both blueprints? Or does the user expect two different singleton instances to be injected in each nested blueprint?

To avoid this ambiguity, Pavex takes a conservative approach: a singleton constructor must be registered exactly once for each type. If multiple nested blueprints need access to the singleton, the constructor must be registered against a common parent blueprint—the root blueprint, if necessary.

pub fn routes(self, import: Import)

Register a group of routes.

Their path will be prepended with a common prefix if one was provided via .prefix(). They will be restricted to a specific domain if one was specified via .domain().

Example

use pavex::{Blueprint, blueprint::from};

let mut bp = Blueprint::new();
bp.prefix("/api").routes(from![crate::api]);