Crate web_net

Expand description

§web_net

The web layer on serve-net: what a site is written in.

A request runs one fixed path, and each step either answers or hands on:

site: the Host picks the site (unknown hosts get 421, aliases a redirect to the canonical host), and its base path is removed, so a site works installed in a folder.
url: the path is decoded once, dot segments are removed, empty segments collapse, and the trailing-slash policy applies. A path that was not spelled canonically is redirected to the spelling that is, so two spellings never reach different routes. An encoded slash, an encoded backslash, a control character, or bytes that are not UTF-8 are refused with 400.
authenticate: the Gate says who is asking (or the caller did, with App::respond_identified).
route: a trie compiled at build time matches the path (404 when nothing does).
method: HEAD follows GET, OPTIONS is answered for every route, anything else the route does not take is a 405 with Allow.
authorize: the route’s rule, checked by the gate. Every route declares its access, public or allow; a route without one stops the build.
hooks and handler: registered Hooks for this route, then the handler, which receives a Cx: proof the request passed its gate.
render: a Render engine writes the page from a typed View, no JSON in between.
errors: every refusal and error is answered by one function, with the site’s error template or a built-in page, and reported through Events.

use web_net::{App, Fields, Value, get};

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())
    .build()?;

use serve_net::testing::respond;
let r = respond(&app, b"GET /blog/posts/hello HTTP/1.1\r\nHost: example.com\r\n\r\n");
assert_eq!((r.status, r.text()), (200, "hello"));

let r = respond(&app, b"GET /blog/./posts//hello/ HTTP/1.1\r\nHost: example.com\r\n\r\n");
assert_eq!((r.status, r.header("location")), (301, Some(&b"/blog/posts/hello"[..])));

let r = respond(&app, b"GET /blog HTTP/1.1\r\nHost: www.example.com\r\n\r\n");
assert_eq!(r.header("location"), Some(&b"http://example.com/blog/"[..]));

let r = respond(&app, b"GET / HTTP/1.1\r\nHost: other.example\r\n\r\n");
assert_eq!(r.status, 421);

On a server: serve_net::Server::builder()...serve(app), or serve_net::http("127.0.0.1:8080", ...) for a quick start with a closure.

Re-exports§

pub use cookie_net;
pub use csrf_sec;
pub use form_net;

Structs§

Ambiguous: A Cookie field held the name more than once, or the request carried more than one Cookie field. A gate treats this as no credential, or as an attack; it never picks one of the values.
App: A web application: one site, its routes, and its gate. Built once at start-up with App::builder or App::with_gate; immutable after.
Assets: A folder served under a mount path.
BuildError: Why Builder::build refused: every problem found, not only the first.
Builder: Declares an application. Every mistake is reported by build at once, before anything listens.
Classified: What App::classify tells a dispatcher before admission.
Compression: Response compression with gzip (compress-lib), for deployments where nothing in front compresses.
Cors: A CORS policy.
Cx: The context a handler receives: proof that the request passed its route’s access check, the identity it carries, and the reply.
Denial: A refusal from a gate: what the visitor sees, and a stable code for logs and events (never shown to the visitor).
Error: A handler error: a status, a stable code, and an optional source kept for the logs. The visitor sees the status, a generic message, and the request’s reference; never the code or the source.
ErrorPage: What an error page shows: the status, its generic title and message, and the request’s reference. Never the code or the cause.
Event: One event.
Fields: A ready-made view over a slice of named values, for small pages, error pages, and tests. Its shape is anonymous: names are looked up per render.
Group: Routes sharing a path prefix and a default access.
Guest: The identity of Open: everyone is a guest.
Key: A field or method of a view, resolved from a name by its Shape.
NoEvents: Reports nothing.
NoRender: The engine of an application without one: Cx::render answers 500 render.no_engine, and error pages are web-net’s own.
Open: The default gate: every visitor is a Guest, and only routes declared public can exist.
Output: Where an engine writes: the reply body, reused between requests, with a size budget.
Problem: One thing wrong with an application’s declaration.
RenderError: A render failure. The code is stable; the detail is for logs only.
Request: The request as gates and handlers read it: the parts web-net has checked (the host matched a site, the path is canonical) and the raw request underneath.
RequestId: A request’s reference: the connection id and the request’s number on it. Shown on error pages and carried by every event, so a visitor’s report finds the log line. Not a security token.
Route: A route: a path pattern, one handler per method, and who may use it.
RouteId: A declared route (one method of one pattern), numbered in declaration order.
Routes: Which routes a hook runs for.
SafeHtml: Markup that is trusted as it is: written without escaping. Making one is a visible, searchable step (SafeHtml::trusted), and the place to sanitize is where the markup was produced (when content is saved), not here.
SecurityHeaders: The security headers added to every reply web-net sends (pages, error pages, files, redirects), unless the handler set the same field itself.
Served: What App::serve reports with the outcome.
ShapeId: Identifies a shape so an engine can cache name resolutions per shape. ShapeId::ANONYMOUS says “do not cache”.
Sites: A table of applications, chosen per request by host and base path: an application that lists the request’s host (or an alias of it) wins over one that answers any host, and among those, the longest base path that holds the request’s path. A request no application claims goes to the first one added, which answers it by its own rules (421 for a host it does not serve, 404 outside its base).
TemplateId: A template the engine resolved at build time. Its meaning belongs to the engine.

Enums§

CachePolicy: How a route’s pages may be cached. Applied as Cache-Control unless the handler set one itself.
Cacheable: Whether a cache in front of web-net may keep this reply for guests.
DenialKind: What the visitor is told when a gate denies.
EventKind: What kind of thing happened.
Hook: A named point in the pipeline where registered code runs, only for the routes it registered for. A route with no hooks pays nothing.
NoRule: A rule that cannot be made: the rule type of Open, whose routes can only be public.
Stage: A point in web-net’s pipeline where a checkpoint runs.
TrailingSlash: What a site does with a trailing slash. One policy per site, so a page has one address.
UrlError: What a request path was refused for (answered with 400).
Value: One value read from a view.

Constants§

DEFAULT_CSP: The default content security policy.
DEFAULT_PAGE_LIMIT: The default budget for one rendered page.
INLINE_LIMIT: Files up to this size are read whole into the reply; larger ones are sent in parts.
MAX_PARAMS: The most parameters (named and wildcard) one route pattern may have.
VERSION: Crate version string, populated by Cargo at build time.

Traits§

Checkpoint: Revocation in flight: a ban, a revoked session, or a lockdown that arrives while a request is being handled. serve-net’s own checkpoint covers admission and the moment before the reply leaves; this one covers the points in between that only web-net knows.
Events: Where web-net reports. Every method has an empty default; the default implementation, NoEvents, reports nothing.
Gate: Authentication and authorization, the two checkpoints a request passes before a handler runs.
Handler: A request handler. Any Fn(&mut Cx<'_, I, E>) -> web_net::Result is one.
Identity: Who is asking. A request that reaches a handler always carries one, possibly a guest.
List: A sequence a template can loop over.
Render: A template engine.
Shape: The names a view answers.
View: What a template reads.

Functions§

delete: A route with a DELETE handler.
get: A route with a GET handler (and so HEAD).
mime_for: The media type for a file name, by extension. Text types carry UTF-8.
patch: A route with a PATCH handler.
post: A route with a POST handler.
put: A route with a PUT handler.

Type Aliases§

Result: The handler result.

Crate web_net

Crate web_net Copy item path

§web_net

Re-exports§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate web_net