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 csrf;
74mod cx;
75mod error;
76mod events;
77mod gate;
78mod headers;
79mod render;
80mod request;
81mod route;
82mod router;
83mod url;
84
85pub use app::{App, Builder, Classified, DEFAULT_PAGE_LIMIT, Hook, RouteId, Routes};
86pub use assets::{Assets, INLINE_LIMIT, mime_for};
87pub use cx::Cx;
88pub use error::{BuildError, Error, Problem, Result};
89pub use events::{Checkpoint, Event, EventKind, Events, NoEvents, Stage};
90pub use gate::{Denial, DenialKind, Gate, Guest, Identity, NoRule, Open};
91pub use headers::{DEFAULT_CSP, SecurityHeaders};
92pub use render::{
93    Fields, Key, List, Output, Render, RenderError, SafeHtml, Shape, ShapeId, TemplateId, Value,
94    View,
95};
96pub use request::{Ambiguous, Request, RequestId};
97pub use route::{Group, Handler, Route, delete, get, patch, post, put};
98pub use router::MAX_PARAMS;
99pub use url::{TrailingSlash, UrlError};
100
101/// cookie-net, at the version web-net uses, for [`Cx::set_cookie`].
102pub use cookie_net;
103/// csrf-sec, at the version web-net uses, for [`Builder::csrf`].
104pub use csrf_sec;
105/// form-net, at the version web-net uses, for [`Cx::form`] and its `form!`
106/// macro.
107pub use form_net;
108
109/// Crate version string, populated by Cargo at build time.
110pub const VERSION: &str = env!("CARGO_PKG_VERSION");
111
112#[cfg(test)]
113mod tests {
114    use super::VERSION;
115
116    #[test]
117    fn version_matches_manifest() {
118        assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
119        assert_eq!(VERSION.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
120    }
121}
web_net/lib.rs

web_net/
lib.rs
