Struct Route 

pub struct Route<I, R> { /* private fields */ }

A route: a path pattern, one handler per method, and who may use it.

Patterns are made of literal segments, parameters (:id, one segment) and one wildcard at the end (*rest, the rest of the path). Literals are written decoded (/café); web-net compares them with the canonical request path.

use web_net::{App, get, Route};

let app = App::builder()
    .route(get("/", |cx| { cx.html(200, "<h1>Home</h1>"); Ok(()) }).public())
    .route(
        Route::at("/contact")
            .get(|cx| { cx.html(200, "<form method=post></form>"); Ok(()) })
            .post(|cx| { cx.see_other("/contact/thanks") })
            .public()
            // A real form gets CSRF protection: Builder::csrf and a gate
            // whose identities carry a binding.
            .csrf_exempt("example: the POST changes nothing"),
    )
    .build()?;

A closure that reads fields of a custom identity types its parameter, because the closure is checked before the builder fixes the type (a named fn handler needs nothing extra):

use web_net::{Cx, Route, get};

struct User { name: String }
impl web_net::Identity for User {
    fn is_guest(&self) -> bool { self.name.is_empty() }
}
enum Rule { SignedIn }

let account: Route<User, Rule> = get("/account", |cx: &mut Cx<'_, User>| {
    let name = cx.identity().name.clone();
    cx.text(200, &name);
    Ok(())
})
.allow(Rule::SignedIn);

Implementations

impl<I: 'static, R> Route<I, R>

pub fn at(pattern: impl Into<String>) -> Self

A route at pattern with no methods yet.

Examples found in repository

examples/hello.rs (line 39)

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 on(self, method: Method, handler: impl Handler<I>) -> Self

Adds a handler for method. HEAD follows GET unless it has its own; OPTIONS is answered for every route unless it has its own.

pub fn get<F>(self, f: F) -> Self

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

Adds a GET handler.

Examples found in repository

examples/hello.rs (lines 40-43)

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 post<F>(self, f: F) -> Self

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

Adds a POST handler.

Examples found in repository

examples/hello.rs (line 44)

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 put<F>(self, f: F) -> Self

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

Adds a PUT handler.

pub fn patch<F>(self, f: F) -> Self

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

Adds a PATCH handler.

pub fn delete<F>(self, f: F) -> Self

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

Adds a DELETE handler.

pub fn public(self) -> Self

Anyone may use the route, guests included. Public is a declaration, never a default: a route with neither public nor allow stops the build.

Examples found in repository

examples/hello.rs (line 28)

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 allow(self, rule: R) -> Self

Those rule allows may use the route; the gate’s authorize decides on every request.

pub fn name(self, name: &'static str) -> Self

A name for logs, events, and hooks.

pub fn work(self, work: WorkClass) -> Self

How the handlers behave: Quick (the default), Io, or Cpu. A dispatcher in front of web-net reads it through App::classify to move slow work off the connection’s worker.

pub fn csrf_exempt(self, reason: &'static str) -> Self

Takes the route out of CSRF protection, with the reason (a webhook signed by its sender, an API authenticated by a bearer token that a browser never sends on its own). The reason is required and must not be empty: an exemption is a decision, never a default.

Examples found in repository

examples/hello.rs (line 48)

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 form_limits(self, limits: Limits) -> Self

The budgets for reading this route’s forms (field count, sizes, files; default form_net::Limits::DEFAULT). Keep them to what the form needs: they bound what one request can make the server hold.

pub fn template(self, name: &'static str) -> Self

The template Cx::render uses. Resolved when the application is built: an unknown name stops the build.

Trait Implementations

impl<I, R> Debug for Route<I, R>

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

Formats the value using the given formatter.