Struct Builder 

pub struct Builder<G: Gate> { /* private fields */ }

Declares an application. Every mistake is reported by build at once, before anything listens.

Implementations

impl<G: Gate> Builder<G>

pub fn csrf(self, csrf: Csrf) -> Self

CSRF protection with csrf-sec (re-exported as web_net::csrf_sec), built from a persisted 32-byte key. Required as soon as one route takes an unsafe method and is not exempt.

pub fn redirect_hosts(self, hosts: &[&str]) -> Self

Hosts that Cx::redirect_external may send a visitor to (accounts.example.com). Everything else is refused.

pub fn assets(self, assets: Assets) -> Self

Serves a folder of files under a mount path, before routing and without the gate (files are public).

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

A liveness path (/healthz): 200 ok whenever the process answers. Answered before routing and without the gate.

pub fn ready( self, path: &str, check: impl Fn() -> bool + Send + Sync + 'static, ) -> Self

A readiness path (/readyz): 200 ready when check says so, 503 not ready otherwise. Keep check to a flag read: it runs on the request path.

pub fn security_headers(self, policy: SecurityHeaders) -> Self

The security headers every reply carries (default SecurityHeaders::default).

pub fn route(self, route: Route<G::Identity, G::Rule>) -> Self

Adds a route.

Examples found in repository

examples/hello.rs (lines 19-29)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = App::builder()
        .host("127.0.0.1:8091")
        .development()
        .base("/app")
        .route(
            get("/", |cx| {
                let users = cx.url("/users/7");
                cx.html(
                    200,
                    &format!("<h1>Hello</h1><a href=\"{users}\">user 7</a>"),
                );
                Ok(())
            })
            .public(),
        )
        .route(
            get("/users/:id", |cx| {
                let id: u64 = cx.param_as("id")?;
                cx.text(200, &format!("user {id}"));
                Ok(())
            })
            .public(),
        )
        .route(
            Route::at("/contact")
                .get(|cx| {
                    cx.html(200, "<form method=post><button>Send</button></form>");
                    Ok(())
                })
                .post(|cx| cx.see_other("/"))
                .public()
                // A form that changes state gets Builder::csrf(..) and a gate
                // whose identities carry a CSRF binding instead.
                .csrf_exempt("demo: the POST changes nothing"),
        )
        .build()?;

    let server = serve_net::Server::builder()
        .listener(serve_net::ListenerSpec::tcp("web", "127.0.0.1:8091"))
        .serve(app)?;
    println!("listening on http://127.0.0.1:8091/app/");
    server.wait();
    Ok(())
}

pub fn group(self, group: Group<G::Identity, G::Rule>) -> Self

Adds a group’s routes.

pub fn hook<F>(self, hook: Hook, routes: Routes, f: F) -> Self

where F: Fn(&mut Cx<'_, G::Identity>) -> Result + Send + Sync + 'static,

Runs f at hook for the routes routes selects.

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

A host the site answers (example.com, or localhost:8080 with its port). The first one is canonical. With no host declared the site answers any host; with hosts declared, any other host gets 421.

Examples found in repository

examples/hello.rs (line 16)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = App::builder()
        .host("127.0.0.1:8091")
        .development()
        .base("/app")
        .route(
            get("/", |cx| {
                let users = cx.url("/users/7");
                cx.html(
                    200,
                    &format!("<h1>Hello</h1><a href=\"{users}\">user 7</a>"),
                );
                Ok(())
            })
            .public(),
        )
        .route(
            get("/users/:id", |cx| {
                let id: u64 = cx.param_as("id")?;
                cx.text(200, &format!("user {id}"));
                Ok(())
            })
            .public(),
        )
        .route(
            Route::at("/contact")
                .get(|cx| {
                    cx.html(200, "<form method=post><button>Send</button></form>");
                    Ok(())
                })
                .post(|cx| cx.see_other("/"))
                .public()
                // A form that changes state gets Builder::csrf(..) and a gate
                // whose identities carry a CSRF binding instead.
                .csrf_exempt("demo: the POST changes nothing"),
        )
        .build()?;

    let server = serve_net::Server::builder()
        .listener(serve_net::ListenerSpec::tcp("web", "127.0.0.1:8091"))
        .serve(app)?;
    println!("listening on http://127.0.0.1:8091/app/");
    server.wait();
    Ok(())
}

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

A host that is redirected (301, or 308 for unsafe methods) to the canonical host (www.example.com to example.com).

pub fn development(self) -> Self

A development instance: localhost, 127.0.0.1, [::1], and *.localhost are answered as the site (with any port), and HTTPS is not required for them. Never set this in production: it is the only way a Host: localhost is trusted.

Examples found in repository

examples/hello.rs (line 17)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = App::builder()
        .host("127.0.0.1:8091")
        .development()
        .base("/app")
        .route(
            get("/", |cx| {
                let users = cx.url("/users/7");
                cx.html(
                    200,
                    &format!("<h1>Hello</h1><a href=\"{users}\">user 7</a>"),
                );
                Ok(())
            })
            .public(),
        )
        .route(
            get("/users/:id", |cx| {
                let id: u64 = cx.param_as("id")?;
                cx.text(200, &format!("user {id}"));
                Ok(())
            })
            .public(),
        )
        .route(
            Route::at("/contact")
                .get(|cx| {
                    cx.html(200, "<form method=post><button>Send</button></form>");
                    Ok(())
                })
                .post(|cx| cx.see_other("/"))
                .public()
                // A form that changes state gets Builder::csrf(..) and a gate
                // whose identities carry a CSRF binding instead.
                .csrf_exempt("demo: the POST changes nothing"),
        )
        .build()?;

    let server = serve_net::Server::builder()
        .listener(serve_net::ListenerSpec::tcp("web", "127.0.0.1:8091"))
        .serve(app)?;
    println!("listening on http://127.0.0.1:8091/app/");
    server.wait();
    Ok(())
}

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

The path the site is installed under (/blog). It is removed before routing and added back by Cx::url, so routes and links are written as if the site were at /. Requests outside it get 404.

Examples found in repository

examples/hello.rs (line 18)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = App::builder()
        .host("127.0.0.1:8091")
        .development()
        .base("/app")
        .route(
            get("/", |cx| {
                let users = cx.url("/users/7");
                cx.html(
                    200,
                    &format!("<h1>Hello</h1><a href=\"{users}\">user 7</a>"),
                );
                Ok(())
            })
            .public(),
        )
        .route(
            get("/users/:id", |cx| {
                let id: u64 = cx.param_as("id")?;
                cx.text(200, &format!("user {id}"));
                Ok(())
            })
            .public(),
        )
        .route(
            Route::at("/contact")
                .get(|cx| {
                    cx.html(200, "<form method=post><button>Send</button></form>");
                    Ok(())
                })
                .post(|cx| cx.see_other("/"))
                .public()
                // A form that changes state gets Builder::csrf(..) and a gate
                // whose identities carry a CSRF binding instead.
                .csrf_exempt("demo: the POST changes nothing"),
        )
        .build()?;

    let server = serve_net::Server::builder()
        .listener(serve_net::ListenerSpec::tcp("web", "127.0.0.1:8091"))
        .serve(app)?;
    println!("listening on http://127.0.0.1:8091/app/");
    server.wait();
    Ok(())
}

pub fn trailing_slash(self, policy: TrailingSlash) -> Self

The trailing-slash policy (default TrailingSlash::Strip).

pub fn lowercase_paths(self) -> Self

Paths are lower case: one with an upper-case letter is redirected.

pub fn https_only(self) -> Self

Plain HTTP is redirected to HTTPS on the canonical host (behind a TLS proxy, serve-net must trust the proxy’s scheme). Needs a host.

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

The site-relative sign-in page. A Denial::sign_in on a GET or HEAD is then answered with a 303 to it, the page asked for passed as next; without it, or for other methods, the answer is 401.

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

The WWW-Authenticate challenge sent with a 401 (default Session).

pub fn render(self, engine: impl Render) -> Self

The template engine.

pub fn events(self, events: impl Events) -> Self

Where refusals, denials, and failures are reported.

pub fn checkpoint(self, checkpoint: impl Checkpoint) -> Self

The in-flight revocation check at web-net’s stages.

pub fn page_limit(self, bytes: usize) -> Self

The budget for one rendered page (default 8 MiB).

pub fn wipe_buffers(self) -> Self

Zero the reply buffers web-net reuses after every request, so one visitor’s page never lingers in memory another request reuses. Costs one pass over the bytes written.

pub fn build(self) -> Result<App<G>, BuildError>

Compiles the application.

Errors

A BuildError listing every problem: a route without declared access, a malformed pattern, two handlers for one method of one path, an unknown template, a malformed host or base path.

Examples found in repository

examples/hello.rs (line 50)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = App::builder()
        .host("127.0.0.1:8091")
        .development()
        .base("/app")
        .route(
            get("/", |cx| {
                let users = cx.url("/users/7");
                cx.html(
                    200,
                    &format!("<h1>Hello</h1><a href=\"{users}\">user 7</a>"),
                );
                Ok(())
            })
            .public(),
        )
        .route(
            get("/users/:id", |cx| {
                let id: u64 = cx.param_as("id")?;
                cx.text(200, &format!("user {id}"));
                Ok(())
            })
            .public(),
        )
        .route(
            Route::at("/contact")
                .get(|cx| {
                    cx.html(200, "<form method=post><button>Send</button></form>");
                    Ok(())
                })
                .post(|cx| cx.see_other("/"))
                .public()
                // A form that changes state gets Builder::csrf(..) and a gate
                // whose identities carry a CSRF binding instead.
                .csrf_exempt("demo: the POST changes nothing"),
        )
        .build()?;

    let server = serve_net::Server::builder()
        .listener(serve_net::ListenerSpec::tcp("web", "127.0.0.1:8091"))
        .serve(app)?;
    println!("listening on http://127.0.0.1:8091/app/");
    server.wait();
    Ok(())
}

Trait Implementations

impl<G: Gate> Debug for Builder<G>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.