web-net 0.4.0

Web layer on serve-net: URL normalization, sites and base paths, a compiled router with 404 and 405, gate checkpoints for authentication and authorization, hooks, error pages, and a render trait that reads typed views.
Documentation

Quick start

[dependencies]
web-net = "0.4"
serve-net = "0.7"

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = App::builder()
        .host("example.com")
        .alias("www.example.com")
        .base("/blog")
        .route(get("/", |cx| { cx.html(200, "<h1>Blog</h1>"); Ok(()) }).public())
        .route(get("/posts/:slug", |cx| {
            let slug = cx.param("slug").unwrap_or_default();
            cx.text(200, &slug);
            Ok(())
        }).public())
        .route(Route::at("/contact")
            .get(|cx| { cx.html(200, "<form method=post></form>"); Ok(()) })
            .post(|cx| cx.see_other("/"))
            .public()
            // Unsafe methods need Builder::csrf(..) or an exemption with a reason.
            .csrf_exempt("demo: the POST changes nothing"))
        .build()?;

    serve_net::Server::builder()
        .listener(serve_net::ListenerSpec::tcp("web", "127.0.0.1:8080"))
        .serve(app)?
        .wait();
    Ok(())
}

The request path

Step What happens Answers
site the host picks the site; the base path is removed 421 unknown host; 301 alias or HTTPS
url decoded once, one canonical spelling, dot and empty segments removed 400 refused; 301/308 to the canonical path
authenticate the gate says who is asking the gate's denial
route a trie compiled at build 404
method HEAD from GET, OPTIONS automatic 405 with Allow, 501
authorize the route's rule, unless it is public 303 to sign-in, 401, 403, 404
hooks, handler only the hooks registered for the route the handler's error
render the engine reads a typed view; no JSON 500
errors one function: the engine's error template or a built-in page

Plugging in

  • Authentication and authorization: implement Gate (authenticate, authorize) and Identity. App::with_gate(gate). A front layer that authenticates on its own calls App::respond_identified.
  • Templates: implement Render and read values through View. Engines live in their own crates; web-net depends on none.
  • Detection and logs: implement Events (every refusal, denial, failure, panic) and Checkpoint (in-flight revocation).

Built in: static files (Assets: validators, ranges, precompressed variants, no escape from the folder), health and readiness paths, strict security headers by default (SecurityHeaders), cookies out through cookie-net, and a 304 fast path for pages (Cx::not_modified).

Forms and uploads through form-net (Cx::form, Cx::upload), CSRF through csrf-sec on every unsafe method (origin policy and a session-bound token; a route without either does not build unless it is exempt with a reason), allowlisted external redirects, and If-Match preconditions.

Coming next (see the roadmap): negotiation, CORS, compression, caching, and several sites (0.5).

Contributing

See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.