web_net/
lib.rs

1//! # web_net
2//!
3//! The web layer on serve-net: what a site is written in.
4//!
5//! A request runs one fixed path, and each step either answers or hands on:
6//!
7//! 1. **site**: the `Host` picks the site (unknown hosts get 421, aliases a
8//!    redirect to the canonical host), and its base path is removed, so a
9//!    site works installed in a folder.
10//! 2. **url**: the path is decoded once, dot segments are removed, empty
11//!    segments collapse, and the trailing-slash policy applies. A path that
12//!    was not spelled canonically is redirected to the spelling that is, so
13//!    two spellings never reach different routes. An encoded slash, an
14//!    encoded backslash, a control character, or bytes that are not UTF-8
15//!    are refused with 400.
16//! 3. **authenticate**: the [`Gate`] says who is asking (or the caller did,
17//!    with [`App::respond_identified`]).
18//! 4. **route**: a trie compiled at build time matches the path (404 when
19//!    nothing does).
20//! 5. **method**: `HEAD` follows `GET`, `OPTIONS` is answered for every
21//!    route, anything else the route does not take is a 405 with `Allow`.
22//! 6. **authorize**: the route's rule, checked by the gate. Every route
23//!    declares its access, [`public`](Route::public) or
24//!    [`allow`](Route::allow); a route without one stops the build.
25//! 7. **hooks and handler**: registered [`Hook`]s for this route, then the
26//!    handler, which receives a [`Cx`]: proof the request passed its gate.
27//! 8. **render**: a [`Render`] engine writes the page from a typed [`View`],
28//!    no JSON in between.
29//! 9. **errors**: every refusal and error is answered by one function, with
30//!    the site's error template or a built-in page, and reported through
31//!    [`Events`].
32//!
33//! ```
34//! use web_net::{App, Fields, Value, get};
35//!
36//! let app = App::builder()
37//!     .host("example.com")
38//!     .alias("www.example.com")
39//!     .base("/blog")
40//!     .route(get("/", |cx| { cx.html(200, "<h1>Blog</h1>"); Ok(()) }).public())
41//!     .route(get("/posts/:slug", |cx| {
42//!         let slug = cx.param("slug").unwrap_or_default();
43//!         cx.text(200, &slug);
44//!         Ok(())
45//!     }).public())
46//!     .build()?;
47//!
48//! use serve_net::testing::respond;
49//! let r = respond(&app, b"GET /blog/posts/hello HTTP/1.1\r\nHost: example.com\r\n\r\n");
50//! assert_eq!((r.status, r.text()), (200, "hello"));
51//!
52//! let r = respond(&app, b"GET /blog/./posts//hello/ HTTP/1.1\r\nHost: example.com\r\n\r\n");
53//! assert_eq!((r.status, r.header("location")), (301, Some(&b"/blog/posts/hello"[..])));
54//!
55//! let r = respond(&app, b"GET /blog HTTP/1.1\r\nHost: www.example.com\r\n\r\n");
56//! assert_eq!(r.header("location"), Some(&b"http://example.com/blog/"[..]));
57//!
58//! let r = respond(&app, b"GET / HTTP/1.1\r\nHost: other.example\r\n\r\n");
59//! assert_eq!(r.status, 421);
60//! # Ok::<(), web_net::BuildError>(())
61//! ```
62//!
63//! On a server: `serve_net::Server::builder()...serve(app)`, or
64//! `serve_net::http("127.0.0.1:8080", ...)` for a quick start with a closure.
65
66#![doc(html_root_url = "https://docs.rs/web-net")]
67#![cfg_attr(docsrs, feature(doc_cfg))]
68#![forbid(unsafe_code)]
69#![deny(missing_docs)]
70
71mod app;
72mod assets;
73mod cx;
74mod error;
75mod events;
76mod gate;
77mod headers;
78mod render;
79mod request;
80mod route;
81mod router;
82mod url;
83
84pub use app::{App, Builder, Classified, DEFAULT_PAGE_LIMIT, Hook, RouteId, Routes};
85pub use assets::{Assets, INLINE_LIMIT, mime_for};
86pub use cx::Cx;
87pub use error::{BuildError, Error, Problem, Result};
88pub use events::{Checkpoint, Event, EventKind, Events, NoEvents, Stage};
89pub use gate::{Denial, DenialKind, Gate, Guest, Identity, NoRule, Open};
90pub use headers::{DEFAULT_CSP, SecurityHeaders};
91pub use render::{
92    Fields, Key, List, Output, Render, RenderError, SafeHtml, Shape, ShapeId, TemplateId, Value,
93    View,
94};
95pub use request::{Ambiguous, Request, RequestId};
96pub use route::{Group, Handler, Route, delete, get, patch, post, put};
97pub use router::MAX_PARAMS;
98pub use url::{TrailingSlash, UrlError};
99
100/// cookie-net, at the version web-net uses, for [`Cx::set_cookie`].
101pub use cookie_net;
102
103/// Crate version string, populated by Cargo at build time.
104pub const VERSION: &str = env!("CARGO_PKG_VERSION");
105
106#[cfg(test)]
107mod tests {
108    use super::VERSION;
109
110    #[test]
111    fn version_matches_manifest() {
112        assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
113        assert_eq!(VERSION.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
114    }
115}
web_net/lib.rs

web_net/
lib.rs
