rust_web_server/
lib.rs

1//! # rust-web-server
2//!
3//! An HTTP/1.1, HTTP/2, and HTTP/3 (QUIC) server, reverse proxy, and
4//! application framework in one crate. HTTP/1.1 parsing, routing, middleware,
5//! JSON, WebSocket, and SSE are implemented in-crate; HTTP/2 and HTTP/3
6//! framing use the `h2` and `quinn`/`h3` crates, and TLS uses `rustls`.
7//!
8//! ## Use as a library
9//!
10//! Add to `Cargo.toml`:
11//!
12//! ```toml
13//! [dependencies]
14//! rust-web-server = "17"
15//! ```
16//!
17//! ## Quick start
18//!
19//! ```rust,no_run
20//! use rust_web_server::prelude::*;
21//!
22//! fn hello(_: &Request, _: &PathParams, _: &ConnectionInfo, _: &()) -> Response {
23//!     Response::text(STATUS_CODE_REASON_PHRASE.n200_ok, "Hello, world!")
24//! }
25//!
26//! fn main() {
27//!     let app = App::with_state(()).get("/hello", hello);
28//!     let (listener, pool) = Server::setup().unwrap();
29//!     Server::run(listener, pool, app);
30//! }
31//! ```
32//!
33//! See [DEVELOPER.md](https://github.com/bohdaq/rust-web-server/blob/main/DEVELOPER.md)
34//! for the full building blocks reference and use case examples.
35
36// Allows `::rust_web_server::…` paths to resolve from within this crate's own
37// tests, which is required by proc-macro derive output that uses that prefix.
38extern crate self as rust_web_server;
39
40pub mod app;
41#[cfg(feature = "auth")]
42pub mod auth;
43
44#[cfg(feature = "macros")]
45pub use rws_macros::{delete, get, patch, post, put, route, Config, FromRequest, JsonSchema, Validate};
46#[cfg(all(feature = "macros", any(feature = "model-sqlite", feature = "model-postgres", feature = "model-mysql")))]
47pub use rws_macros::Model;
48#[cfg(feature = "http2")]
49pub mod async_state;
50#[cfg(feature = "http2")]
51pub(crate) mod async_bridge;
52pub mod session;
53// Socket-coupled — see spec/WASM_SHIM.md for what a wasm32-wasip2 build
54// excludes and why (no OS threads, no raw TCP/TLS in a WASI guest).
55#[cfg(not(target_arch = "wasm32"))]
56pub(crate) mod redis_protocol;
57pub mod sse;
58pub mod compression;
59pub mod cookie;
60pub mod error;
61pub mod extract;
62pub mod ip_filter;
63pub mod macros;
64pub mod blocklist;
65pub mod cache;
66pub mod config_reload;
67#[cfg(not(target_arch = "wasm32"))]
68pub mod config_watch;
69pub mod config_check;
70/// RSA public keys and RS256 / rsa-sha256 signature verification (no `rsa` crate).
71#[cfg(any(feature = "auth-asymmetric", feature = "sso"))]
72pub mod rsa_key;
73pub mod server_config;
74pub mod feature;
75pub mod maintenance;
76pub mod metrics;
77pub mod mcp;
78pub mod request_log;
79pub mod request_id;
80#[cfg(not(target_arch = "wasm32"))]
81pub mod otel;
82#[cfg(feature = "acme")]
83pub mod acme;
84pub mod middleware;
85pub mod rate_limit;
86pub mod router;
87pub mod schema;
88pub mod state;
89pub mod test_client;
90pub mod application;
91pub mod body;
92pub mod client_hint;
93pub mod controller;
94pub mod core;
95pub mod cors;
96pub mod entry_point;
97pub mod ext;
98pub mod header;
99pub mod http;
100pub mod json;
101pub mod language;
102#[cfg(not(target_arch = "wasm32"))]
103pub mod log;
104pub mod mime_type;
105pub mod null;
106pub mod range;
107pub mod request;
108pub mod response;
109pub mod server;
110pub mod symbol;
111#[cfg(not(target_arch = "wasm32"))]
112pub mod thread_pool;
113pub mod url;
114pub mod pagination;
115#[cfg(not(target_arch = "wasm32"))]
116pub mod proxy;
117pub mod rewrite;
118pub mod scheduler;
119#[cfg(not(target_arch = "wasm32"))]
120pub mod tcp_proxy;
121#[cfg(not(target_arch = "wasm32"))]
122pub mod udp_proxy;
123#[cfg(not(target_arch = "wasm32"))]
124pub mod ws_proxy;
125#[cfg(not(target_arch = "wasm32"))]
126pub mod canary;
127#[cfg(not(target_arch = "wasm32"))]
128pub mod circuit_breaker;
129// `BackendPool`/`DiscoverySource` (DNS/etcd/Consul/Docker) are native-only —
130// gated internally in service_discovery/mod.rs, not at this declaration —
131// because `json_lite` (a plain JSON parser, no sockets) must stay available
132// for `secrets`'s Vault/AWS-SM/Key-Vault backends on every target.
133pub mod service_discovery;
134/// DNS wire format, shared by the SRV service discovery and ACME's DNS-01.
135pub(crate) mod dns;
136pub mod config_binding;
137pub mod di;
138#[cfg(not(target_arch = "wasm32"))]
139pub mod proxy_config;
140#[cfg(not(target_arch = "wasm32"))]
141pub mod ingress;
142#[cfg(feature = "tera")]
143pub mod template;
144pub mod validate;
145pub mod virtual_host;
146#[cfg(any(feature = "model-sqlite", feature = "model-postgres", feature = "model-mysql"))]
147pub mod model;
148#[cfg(not(target_arch = "wasm32"))]
149pub mod websocket;
150// Has both a native (TcpStream/rustls) and a wasm32 (wasi:http outgoing-handler)
151// backend behind Client::send() — see the #[cfg(target_arch = "wasm32")]
152// `send_once` in this module. spec/WASM_SHIM.md Phase 2 item 7.
153pub mod http_client;
154#[cfg(feature = "crypto")]
155pub mod crypto;
156#[cfg(feature = "csrf")]
157pub mod csrf;
158#[cfg(feature = "sso")]
159pub mod sso;
160// SMTP is a raw-TCP protocol with no wasi:http equivalent (unlike
161// http_client, which the host can proxy via outgoing-handler) — genuinely
162// can't work in a wasi:http guest, not just ungated. spec/WASM_SHIM.md.
163#[cfg(all(feature = "mailer", not(target_arch = "wasm32")))]
164pub mod mailer;
165#[cfg(feature = "jobs")]
166pub mod jobs;
167// Also compiled under `secrets` — `secrets::aws_secrets_manager`/`azure_key_vault`
168// reuse `StorageError` and the SigV4/Managed-Identity credential helpers from here.
169#[cfg(any(feature = "storage-local", feature = "storage-s3", feature = "storage-azure", feature = "secrets"))]
170pub mod storage;
171#[cfg(feature = "openapi")]
172pub mod openapi;
173#[cfg(feature = "tower")]
174pub mod tower;
175#[cfg(feature = "gateway-api")]
176pub mod gateway_api;
177#[cfg(feature = "webhook")]
178pub mod webhook;
179#[cfg(feature = "secrets")]
180pub mod secrets;
181// Runs wrapped work on a background OS thread to bound wait time — needs
182// `std::thread::spawn`, unavailable on wasm32-wasip2. See spec/WASM_SHIM.md.
183#[cfg(not(target_arch = "wasm32"))]
184pub mod timeout;
185pub mod prelude;
186
187#[cfg(feature = "http2")]
188#[doc(hidden)]
189pub mod tls;
190
191#[cfg(feature = "http2")]
192#[doc(hidden)]
193pub mod h2_server;
194
195#[cfg(feature = "http3")]
196#[doc(hidden)]
197pub mod h3_handler;
198
199/// Shared infrastructure for tests that write process-wide environment variables.
200///
201/// Tests that call `override_environment_variables_from_config` or
202/// `CommandLineArgument::set_environment_variable` must hold this lock for
203/// their entire duration so they don't race with other tests reading the
204/// same variables.
205#[cfg(test)]
206mod stack_depth_tests;
207
208/// A rustls client-config builder with this crate's crypto provider
209/// (aws-lc-rs) named explicitly. `rustls::ClientConfig::builder()` uses the
210/// process-wide default provider and panics when none is installed and more
211/// than one is compiled in — which happens as soon as any dependency enables
212/// rustls's `ring` backend (e.g. sqlx). Every outbound TLS client in the
213/// crate starts here.
214#[cfg(all(any(feature = "http-client", feature = "http2"), not(target_arch = "wasm32")))]
215pub(crate) fn tls_client_builder() -> rustls::ConfigBuilder<rustls::ClientConfig, rustls::WantsVerifier> {
216    rustls::ClientConfig::builder_with_provider(std::sync::Arc::new(rustls::crypto::aws_lc_rs::default_provider()))
217        .with_safe_default_protocol_versions()
218        .expect("aws-lc-rs supports rustls's default protocol versions")
219}
220
221#[cfg(test)]
222pub mod test_env {
223    use std::sync::{Mutex, OnceLock};
224    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
225    pub fn lock() -> std::sync::MutexGuard<'static, ()> {
226        LOCK.get_or_init(|| Mutex::new(()))
227            .lock()
228            .unwrap_or_else(|e| e.into_inner())
229    }
230
231    /// A per-process path under the OS temp dir that is deleted (file or
232    /// directory) when dropped — so a test cleans up even when an assertion
233    /// fails before its last line.
234    pub struct TempPath(std::path::PathBuf);
235
236    impl TempPath {
237        pub fn new(name: &str) -> Self {
238            TempPath(std::env::temp_dir().join(format!("rws_test_{}_{}", std::process::id(), name)))
239        }
240
241        /// The same in the working directory (the static-file root), for
242        /// tests that need a file the server would serve.
243        pub fn new_in_cwd(name: &str) -> Self {
244            TempPath(std::env::current_dir().expect("working directory").join(format!("rws_test_{}_{}", std::process::id(), name)))
245        }
246
247        pub fn as_str(&self) -> &str {
248            self.0.to_str().expect("temp dir path is UTF-8")
249        }
250    }
251
252    impl std::ops::Deref for TempPath {
253        type Target = std::path::Path;
254        fn deref(&self) -> &std::path::Path {
255            &self.0
256        }
257    }
258
259    impl Drop for TempPath {
260        fn drop(&mut self) {
261            // A symlink is removed itself, never followed (a test may link
262            // to a system directory).
263            let is_link = std::fs::symlink_metadata(&self.0).is_ok_and(|m| m.file_type().is_symlink());
264            if is_link {
265                let _ = std::fs::remove_file(&self.0);
266            } else if self.0.is_dir() {
267                let _ = std::fs::remove_dir_all(&self.0);
268            } else {
269                let _ = std::fs::remove_file(&self.0);
270            }
271        }
272    }
273}
274
275/// Entry points for `fuzz/` targets that reach crate-private parsers.
276/// Compiled only under `--cfg fuzzing`, which `cargo fuzz` sets — never part
277/// of the public API.
278#[cfg(fuzzing)]
279#[doc(hidden)]
280pub mod fuzz_api {
281    /// Proxy route-matching normalization of a request target (#50): any
282    /// input, and normalizing twice changes nothing.
283    pub fn proxy_normalize_target(data: &[u8]) {
284        let Ok(target) = std::str::from_utf8(data) else { return };
285        let once = crate::proxy_config::normalize_request_target(target).into_owned();
286        let twice = crate::proxy_config::normalize_request_target(&once).into_owned();
287        assert_eq!(once, twice, "normalization is not idempotent for {:?}", target);
288    }
289
290    /// Static-file request-path decoding (#55). Must never panic; the
291    /// decoded path never carries a `..` segment past the web-root check.
292    pub fn static_path_decode(data: &[u8]) {
293        let Ok(path) = std::str::from_utf8(data) else { return };
294        if let Ok(fs_path) = crate::app::controller::static_resource::static_fs_path(path) {
295            let relative = &fs_path[crate::app::controller::static_resource::working_directory().len()..];
296            assert!(!relative.split(['/', '\\']).any(|segment| segment == ".."), "{:?} -> {:?}", path, fs_path);
297        }
298    }
299
300    /// `Accept-Encoding` negotiation (#7): any header value; the choice is
301    /// always one of the offered codings, and a coding the value refuses
302    /// (its first `q=` parameter is 0) is never chosen.
303    pub fn accept_encoding(data: &[u8]) {
304        let Ok(value) = std::str::from_utf8(data) else { return };
305        let request = crate::request::Request {
306            method: "GET".to_string(),
307            request_uri: "/".to_string(),
308            http_version: "HTTP/1.1".to_string(),
309            headers: vec![crate::header::Header::new(crate::header::Header::_ACCEPT_ENCODING, value.to_string())],
310            body: Default::default(),
311        };
312        for preference in [crate::compression::DYNAMIC_PREFERENCE, crate::compression::STATIC_PREFERENCE] {
313            if let Some(chosen) = crate::compression::negotiate(&request, preference) {
314                assert!(preference.contains(&chosen));
315                // Refused: the coding's first `q=` parameter is exactly 0.
316                let refused = value.split(',').any(|c| {
317                    let mut parts = c.split(';');
318                    parts.next().unwrap_or("").trim().eq_ignore_ascii_case(chosen.token())
319                        && parts
320                            .map(str::trim)
321                            .find(|p| p.as_bytes().get(..2).is_some_and(|b| b.eq_ignore_ascii_case(b"q=")))
322                            .is_some_and(|q| q[2..].trim().parse::<f32>() == Ok(0.0))
323                });
324                let listed_once = value.split(',').filter(|c| c.split(';').next().unwrap_or("").trim().eq_ignore_ascii_case(chosen.token())).count() == 1;
325                assert!(!(refused && listed_once), "{value:?} refused {chosen:?}");
326            }
327        }
328    }
329
330    /// An upstream MCP server's reply as the gateway reads it (#62): a JSON
331    /// body or an event stream, then the response's tools. Must never panic.
332    pub fn mcp_gateway_reply(data: &[u8]) {
333        for content_type in ["application/json", "text/event-stream"] {
334            if let Ok(result) = crate::mcp::gateway::parse_reply(content_type, data, 1) {
335                let _ = crate::mcp::gateway::fuzzing::tools(&result);
336            }
337        }
338    }
339
340    /// A WebSocket frame from a client (#8): any bytes; a frame never holds
341    /// more payload than the limit allows. Must never panic.
342    #[cfg(not(target_arch = "wasm32"))]
343    pub fn websocket_frame(data: &[u8]) {
344        let mut cursor = std::io::Cursor::new(data);
345        while let Ok(frame) = crate::websocket::WebSocket::read_frame_limited(&mut cursor, 4096) {
346            let len = match &frame {
347                crate::websocket::Frame::Text(t) => t.len(),
348                crate::websocket::Frame::Binary(b) | crate::websocket::Frame::Ping(b) | crate::websocket::Frame::Pong(b) => b.len(),
349                crate::websocket::Frame::Continuation { data, .. } => data.len(),
350                crate::websocket::Frame::Close(_, reason) => reason.len() + 2,
351            };
352            assert!(len <= 4096 + 2);
353        }
354    }
355
356    /// A DNS response read for SRV records (#8). Must never panic.
357    #[cfg(not(target_arch = "wasm32"))]
358    pub fn dns_srv_response(data: &[u8]) {
359        let id = data.get(..2).map_or(0, |b| u16::from_be_bytes([b[0], b[1]]));
360        let _ = crate::service_discovery::dns_srv::parse_response(data, id);
361    }
362
363    /// A DNS message: the shared parser (SRV discovery, ACME DNS-01), TXT
364    /// values and, with `acme`, a DNS UPDATE reply. Must never panic.
365    /// A certificate's subjectAltNames, as a BackendTLSPolicy checks a
366    /// backend's (untrusted) certificate. Must never panic.
367    pub fn x509_subject_alt_names(data: &[u8]) {
368        let _ = crate::core::x509::subject_alt_names(data);
369    }
370
371    pub fn dns_message(data: &[u8]) {
372        if let Ok(message) = crate::dns::parse(data) {
373            for record in message.answers.iter().chain(&message.authority).chain(&message.additional) {
374                let _ = crate::dns::txt_value(&data[record.rdata.clone()]);
375            }
376        }
377        #[cfg(feature = "acme")]
378        let _ = crate::acme::dns01::check_update_reply(data, 0);
379    }
380
381    /// A Redis (RESP) reply (#8). Must never panic.
382    #[cfg(not(target_arch = "wasm32"))]
383    pub fn redis_reply(data: &[u8]) {
384        let _ = crate::redis_protocol::read_reply(&mut std::io::Cursor::new(data));
385    }
386
387    /// A `Cookie` request header (#8): every parsed cookie has a name.
388    pub fn cookie_header(data: &[u8]) {
389        let Ok(value) = std::str::from_utf8(data) else { return };
390        let jar = crate::cookie::CookieJar::parse(value);
391        assert!(jar.cookies.iter().all(|c| !c.name.is_empty()));
392    }
393
394    /// A W3C `baggage` header (#25): members survive a round trip through
395    /// the header. Must never panic.
396    #[cfg(not(target_arch = "wasm32"))]
397    pub fn otel_baggage(data: &[u8]) {
398        let Ok(value) = std::str::from_utf8(data) else { return };
399        let baggage = crate::otel::Baggage::parse(value);
400        assert!(baggage.len() <= crate::otel::baggage::MAX_MEMBERS);
401        let again = crate::otel::Baggage::parse(&baggage.to_header());
402        for (key, value) in baggage.iter() {
403            if let Some(round_tripped) = again.get(key) {
404                assert_eq!(value, round_tripped);
405            }
406        }
407    }
408
409    /// What ACME renewal parses from the CA (#1): certificate DER (validity,
410    /// serial, Authority Key Identifier), renewalInfo windows (RFC 3339) and
411    /// directory profile names. Must never panic.
412    #[cfg(feature = "acme")]
413    pub fn acme_renewal(data: &[u8]) {
414        let _ = crate::acme::fuzzing::cert_info_from_der(data);
415        if let Ok(text) = std::str::from_utf8(data) {
416            let _ = crate::acme::fuzzing::parse_suggested_window(text);
417            let _ = crate::acme::fuzzing::parse_rfc3339(text);
418            let _ = crate::acme::fuzzing::json_object_keys(text, "profiles");
419        }
420    }
421
422    /// The SAML XML parser (`sso::saml::xml`), fed IdP-supplied documents.
423    #[cfg(feature = "sso-saml")]
424    pub fn saml_xml_parse(xml: &str) {
425        let _ = crate::sso::saml::xml_parse_for_fuzzing(xml);
426    }
427
428    /// HTTP/1.1 request framing (`server::framing`) over a raw connection
429    /// buffer: head detection, body framing, and the chunked body decoder,
430    /// fed in two pieces split at the first byte to mimic separate reads.
431    pub fn http1_framing(data: &[u8]) {
432        use crate::server::framing::{self, BodyFraming, ChunkedBody, HeadScan};
433        let mut pending = data.to_vec();
434        framing::skip_leading_empty_lines(&mut pending);
435        let HeadScan::Complete(head_len) = framing::scan_head(&pending) else { return };
436        assert!(head_len <= pending.len() && head_len <= framing::MAX_HEAD_SIZE);
437        let Ok(request) = crate::request::Request::parse(&pending[..head_len]) else { return };
438        for header in &request.headers {
439            let _ = crate::http::date::parse(&header.value);
440        }
441        let _ = framing::validate_head(&pending[..head_len], &request);
442        let _ = framing::keep_alive(&request);
443        let body = &pending[head_len..];
444        if let Ok(BodyFraming::Chunked) = framing::body_framing(&request) {
445            let split = data.first().map_or(0, |&b| b as usize).min(body.len());
446            let mut decoder = ChunkedBody::new(1 << 20);
447            let mut buffer = body[..split].to_vec();
448            for next in [&body[split..], &[][..]] {
449                match decoder.feed(&buffer) {
450                    Ok((consumed, _)) => {
451                        assert!(consumed <= buffer.len());
452                        buffer.drain(..consumed);
453                    }
454                    Err(_) => return,
455                }
456                buffer.extend_from_slice(next);
457            }
458            assert!(decoder.body.len() <= 1 << 20);
459        }
460    }
461}
462
463
464/// Compiles the README's Rust example as a doctest, so it can't drift from the API.
465#[cfg(all(doctest, feature = "http3"))]
466#[doc = include_str!("../README.md")]
467pub struct ReadmeDoctests;
rust_web_server/lib.rs

rust_web_server/
lib.rs
