rust_web_server/
lib.rs

1//! # rust-web-server
2//!
3//! A static file web server and HTTP toolkit written in Rust.
4//! Supports HTTP/3 (QUIC), HTTP/2, and HTTP/1.1.
5//!
6//! ## Use as a library
7//!
8//! Add to `Cargo.toml`:
9//!
10//! ```toml
11//! [dependencies]
12//! rust-web-server = "17"
13//! ```
14//!
15//! ## Quick start: add a custom route
16//!
17//! ```rust,no_run
18//! use rust_web_server::controller::Controller;
19//! use rust_web_server::request::{METHOD, Request};
20//! use rust_web_server::response::{Response, STATUS_CODE_REASON_PHRASE};
21//! use rust_web_server::range::Range;
22//! use rust_web_server::mime_type::MimeType;
23//! use rust_web_server::server::ConnectionInfo;
24//!
25//! pub struct PingController;
26//!
27//! impl Controller for PingController {
28//!     fn is_matching(request: &Request, _: &ConnectionInfo) -> bool {
29//!         request.method == METHOD.get && request.request_uri == "/ping"
30//!     }
31//!
32//!     fn process(_: &Request, mut response: Response, _: &ConnectionInfo) -> Response {
33//!         response.status_code = *STATUS_CODE_REASON_PHRASE.n200_ok.status_code;
34//!         response.reason_phrase = STATUS_CODE_REASON_PHRASE.n200_ok.reason_phrase.to_string();
35//!         response.content_range_list = vec![
36//!             Range::get_content_range(b"pong".to_vec(), MimeType::TEXT_PLAIN.to_string())
37//!         ];
38//!         response
39//!     }
40//! }
41//! ```
42//!
43//! See [DEVELOPER.md](https://github.com/bohdaq/rust-web-server/blob/main/DEVELOPER.md)
44//! for the full building blocks reference and use case examples.
45
46// Allows `::rust_web_server::…` paths to resolve from within this crate's own
47// tests, which is required by proc-macro derive output that uses that prefix.
48extern crate self as rust_web_server;
49
50pub mod app;
51#[cfg(feature = "auth")]
52pub mod auth;
53
54#[cfg(feature = "macros")]
55pub use rws_macros::{delete, get, patch, post, put, route, Config, FromRequest, Validate};
56#[cfg(all(feature = "macros", any(feature = "model-sqlite", feature = "model-postgres", feature = "model-mysql")))]
57pub use rws_macros::Model;
58#[cfg(feature = "http2")]
59pub mod async_state;
60#[cfg(feature = "http2")]
61pub(crate) mod async_bridge;
62pub mod session;
63// Socket-coupled — see spec/WASM_SHIM.md for what a wasm32-wasip2 build
64// excludes and why (no OS threads, no raw TCP/TLS in a WASI guest).
65#[cfg(not(target_arch = "wasm32"))]
66pub(crate) mod redis_protocol;
67pub mod sse;
68pub mod compression;
69pub mod cookie;
70pub mod error;
71pub mod extract;
72pub mod ip_filter;
73pub mod macros;
74pub mod blocklist;
75pub mod cache;
76pub mod config_reload;
77pub mod server_config;
78pub mod feature;
79pub mod maintenance;
80pub mod metrics;
81pub mod mcp;
82pub mod request_log;
83pub mod request_id;
84#[cfg(not(target_arch = "wasm32"))]
85pub mod otel;
86#[cfg(feature = "acme")]
87pub mod acme;
88pub mod middleware;
89pub mod rate_limit;
90pub mod router;
91pub mod state;
92pub mod test_client;
93pub mod application;
94pub mod body;
95pub mod client_hint;
96pub mod controller;
97pub mod core;
98pub mod cors;
99pub mod entry_point;
100pub mod ext;
101pub mod header;
102pub mod http;
103pub mod json;
104pub mod language;
105#[cfg(not(target_arch = "wasm32"))]
106pub mod log;
107pub mod mime_type;
108pub mod null;
109pub mod range;
110pub mod request;
111pub mod response;
112pub mod server;
113pub mod symbol;
114#[cfg(not(target_arch = "wasm32"))]
115pub mod thread_pool;
116pub mod url;
117pub mod pagination;
118#[cfg(not(target_arch = "wasm32"))]
119pub mod proxy;
120pub mod rewrite;
121pub mod scheduler;
122#[cfg(not(target_arch = "wasm32"))]
123pub mod tcp_proxy;
124#[cfg(not(target_arch = "wasm32"))]
125pub mod udp_proxy;
126#[cfg(not(target_arch = "wasm32"))]
127pub mod ws_proxy;
128#[cfg(not(target_arch = "wasm32"))]
129pub mod canary;
130#[cfg(not(target_arch = "wasm32"))]
131pub mod circuit_breaker;
132#[cfg(not(target_arch = "wasm32"))]
133pub mod service_discovery;
134pub mod config_binding;
135pub mod di;
136#[cfg(not(target_arch = "wasm32"))]
137pub mod proxy_config;
138#[cfg(not(target_arch = "wasm32"))]
139pub mod ingress;
140#[cfg(feature = "tera")]
141pub mod template;
142pub mod validate;
143pub mod virtual_host;
144#[cfg(any(feature = "model-sqlite", feature = "model-postgres", feature = "model-mysql"))]
145pub mod model;
146#[cfg(not(target_arch = "wasm32"))]
147pub mod websocket;
148#[cfg(not(target_arch = "wasm32"))]
149pub mod http_client;
150#[cfg(feature = "crypto")]
151pub mod crypto;
152#[cfg(feature = "csrf")]
153pub mod csrf;
154#[cfg(feature = "sso")]
155pub mod sso;
156#[cfg(feature = "mailer")]
157pub mod mailer;
158#[cfg(feature = "jobs")]
159pub mod jobs;
160// Also compiled under `secrets` — `secrets::aws_secrets_manager`/`azure_key_vault`
161// reuse `StorageError` and the SigV4/Managed-Identity credential helpers from here.
162#[cfg(any(feature = "storage-local", feature = "storage-s3", feature = "storage-azure", feature = "secrets"))]
163pub mod storage;
164#[cfg(feature = "openapi")]
165pub mod openapi;
166#[cfg(feature = "webhook")]
167pub mod webhook;
168#[cfg(feature = "secrets")]
169pub mod secrets;
170// Runs wrapped work on a background OS thread to bound wait time — needs
171// `std::thread::spawn`, unavailable on wasm32-wasip2. See spec/WASM_SHIM.md.
172#[cfg(not(target_arch = "wasm32"))]
173pub mod timeout;
174pub mod prelude;
175
176#[cfg(feature = "http2")]
177#[doc(hidden)]
178pub mod tls;
179
180#[cfg(feature = "http2")]
181#[doc(hidden)]
182pub mod h2_handler;
183
184#[cfg(feature = "http3")]
185#[doc(hidden)]
186pub mod h3_handler;
187
188/// Shared infrastructure for tests that write process-wide environment variables.
189///
190/// Tests that call `override_environment_variables_from_config` or
191/// `CommandLineArgument::set_environment_variable` must hold this lock for
192/// their entire duration so they don't race with other tests reading the
193/// same variables.
194#[cfg(test)]
195pub mod test_env {
196    use std::sync::{Mutex, OnceLock};
197    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
198    pub fn lock() -> std::sync::MutexGuard<'static, ()> {
199        LOCK.get_or_init(|| Mutex::new(()))
200            .lock()
201            .unwrap_or_else(|e| e.into_inner())
202    }
203}
rust_web_server/lib.rs

rust_web_server/
lib.rs
