Struct Cx 

pub struct Cx<'r, I> { /* private fields */ }

The context a handler receives: proof that the request passed its route’s access check, the identity it carries, and the reply.

There is no public way to make one: web-net builds it only after the gate cleared the request.

Implementations

impl<'r, I> Cx<'r, I>

pub fn request(&self) -> &Request<'r>

The request.

pub fn method(&self) -> Method

The method.

pub fn path(&self) -> &'r str

The canonical path inside the site.

pub fn header(&self, name: &str) -> Option<&'r [u8]>

The first value of a request field.

pub fn identity(&self) -> &'r I

Who the request comes from: always present, possibly a guest.

pub fn id(&self) -> RequestId

The request’s reference, as shown on error pages.

pub fn param(&self, name: &str) -> Option<Cow<'r, str>>

A route parameter (:id or *rest), percent-decoded.

pub fn param_as<T: FromStr>(&self, name: &str) -> Result<T>

A route parameter parsed as T. A value that does not parse means the page does not exist (/users/abc for a numeric id): 404.

Errors

404 route.param when the parameter is missing or does not parse.

Examples found in repository

examples/hello.rs (line 32)

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(),
        )
        .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 query(&self, name: &str) -> Result<Option<Cow<'r, str>>>

The first value of a query parameter, decoded (+ is a space).

Errors

400 query.duplicate when the name appears twice (parameter pollution is refused, never resolved by picking one), 400 query.invalid when the value does not decode to UTF-8.

pub fn body(&self) -> Result<&'r [u8]>

The request body.

Errors

None today; reading the body is fallible so CSRF and body inspection can refuse it in later versions without changing handlers.

pub fn status(&mut self, status: u16) -> &mut Self

Sets the status (default 200).

pub fn set_header(&mut self, name: &str, value: impl AsRef<[u8]>) -> &mut Self

Adds a reply field. A name that is not a token, a value with a control character, or a framing field (content-length, …) turns the reply into a 500 when the handler returns.

pub fn body_bytes(&mut self, bytes: &[u8]) -> &mut Self

Sets the body.

pub fn html(&mut self, status: u16, html: &str) -> &mut Self

Status, content-type: text/html; charset=utf-8, and the HTML.

Examples found in repository

examples/hello.rs (lines 22-25)

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(),
        )
        .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 text(&mut self, status: u16, text: &str) -> &mut Self

Status, content-type: text/plain; charset=utf-8, and the text.

Examples found in repository

examples/hello.rs (line 33)

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(),
        )
        .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 set_cookie(&mut self, cookie: &SetCookie<'_>) -> &mut Self

Adds a Set-Cookie field built with cookie-net (re-exported as web_net::cookie_net).

use web_net::{App, get, cookie_net::SetCookie};

let app = App::builder()
    .route(get("/", |cx| {
        cx.set_cookie(&SetCookie::new("theme", "dark").map_err(|_| web_net::Error::internal("cookie"))?);
        cx.text(200, "ok");
        Ok(())
    }).public())
    .build()?;
let r = serve_net::testing::respond(&app, b"GET / HTTP/1.1\r\nHost: a\r\n\r\n");
assert!(r.header("set-cookie").is_some());

pub fn not_modified(&mut self, tag: &str) -> bool

The conditional fast path for a page: sets ETag: "<tag>" and, when the request’s If-None-Match matches it (a GET or HEAD), turns the reply into 304 Not Modified and returns true, so the handler returns before building the page.

tag is the opaque part (letters, digits, and -._~ are safe), for example a revision number. An unusable tag sets nothing and returns false.

use web_net::{App, get};

let app = App::builder()
    .route(get("/", |cx| {
        if cx.not_modified("rev-7") {
            return Ok(());
        }
        cx.html(200, "<h1>page</h1>");
        Ok(())
    }).public())
    .build()?;
let r = serve_net::testing::respond(&app, b"GET / HTTP/1.1\r\nHost: a\r\nIf-None-Match: \"rev-7\"\r\n\r\n");
assert_eq!(r.status, 304);

pub fn url(&self, path: &str) -> String

The site-relative path as a URL path: the site’s base path in front (/blog + /posts/1). Every link a page writes goes through this, so the site works installed in a folder.

Examples found in repository

examples/hello.rs (line 21)

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(),
        )
        .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 see_other(&mut self, path: &str) -> Result

303 See Other to a site-relative path: the answer to a form that was accepted, so a reload does not post it again.

Errors

500 redirect.not_local when path is not a local path (it must start with one /): redirects to other hosts are never built from a string a handler passes along.

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(),
        )
        .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 redirect(&mut self, status: u16, path: &str) -> Result

A redirect with status (301, 302, 303, 307, 308) to a site-relative path.

Errors

As see_other; 500 redirect.status for a status that is not a redirect.

pub fn render(&mut self, view: &dyn View) -> Result

Renders the route’s template (declared with Route::template) against view into the body. The status stays as set (200 by default); content-type is HTML unless the handler set one.

Errors

500 render.no_engine or render.no_template when nothing can render; the engine’s own RenderError as a 500; a checkpoint’s denial.

pub fn render_named(&mut self, name: &str, view: &dyn View) -> Result

Renders the template name against view. The name is resolved by the engine on every call; prefer render with a template declared on the route, resolved once at build.

Errors

As render.

Trait Implementations

impl<I> Debug for Cx<'_, I>

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

Formats the value using the given formatter.