rust_web_server/config_reload/mod.rs
1//! Hot configuration reload.
2//!
3//! Re-reads `rws.config.toml` without restarting the server. Non-binding
4//! settings — those that would require a new TCP socket (IP, port,
5//! thread count) or a new TLS acceptor (cert/key paths) — are logged as
6//! ignored. All other settings take effect on the next incoming request.
7//!
8//! # Triggering a reload
9//!
10//! * **Unix signal**: send `SIGHUP` to the server process.
11//! ```bash
12//! kill -HUP $(pidof rws)
13//! ```
14//! * **HTTP endpoint**: `POST /admin/config/reload` (no body required).
15//!
16//! # What is hot-reloadable
17//!
18//! | Setting | Env var |
19//! |---------|---------|
20//! | CORS — all fields | `RWS_CONFIG_CORS_*` |
21//! | Rate-limit thresholds | `RWS_CONFIG_RATE_LIMIT_MAX_REQUESTS`, `RWS_CONFIG_RATE_LIMIT_WINDOW_SECS` |
22//! | Log format | `RWS_CONFIG_LOG_FORMAT` |
23//! | Request allocation size | `RWS_CONFIG_REQUEST_ALLOCATION_SIZE_IN_BYTES` |
24//! | Max body size | `RWS_CONFIG_MAX_BODY_SIZE_IN_BYTES` |
25//! | Tera templates (`tera` feature, if `template::init()` was called) | re-read from disk — see [`crate::template`] |
26//!
27//! # What is NOT hot-reloadable (requires restart)
28//!
29//! | Setting | Why |
30//! |---------|-----|
31//! | IP / Port | Bound socket cannot be moved |
32//! | Thread count | Thread pool is fixed at startup |
33//! | TLS cert / key | TLS acceptor is built once at startup |
34
35#[cfg(test)]
36mod tests;
37
38use std::sync::{OnceLock, RwLock};
39use std::sync::atomic::AtomicBool;
40#[cfg(all(unix, feature = "http1"))]
41use std::sync::atomic::Ordering;
42
43use crate::entry_point::Config;
44use crate::entry_point::config_file::override_environment_variables_from_config;
45use crate::rate_limit;
46
47/// Global flag set by the SIGHUP signal handler.
48///
49/// The accept loop checks this between connections and calls [`reload`] when
50/// it is `true`, then resets it to `false`.
51pub static RELOAD_REQUESTED: AtomicBool = AtomicBool::new(false);
52
53/// Snapshot of all hot-reloadable configuration values at a point in time.
54///
55/// Obtain the current snapshot with [`current()`]. The snapshot is updated
56/// atomically every time [`reload()`] completes — no partial reads are possible.
57#[derive(Debug, Clone)]
58pub struct ConfigSnapshot {
59 /// `RWS_CONFIG_CORS_ALLOW_ALL`
60 pub cors_allow_all: bool,
61 /// `RWS_CONFIG_CORS_ALLOW_ORIGINS`
62 pub cors_allow_origins: String,
63 /// `RWS_CONFIG_CORS_ALLOW_CREDENTIALS`
64 pub cors_allow_credentials: String,
65 /// `RWS_CONFIG_CORS_ALLOW_METHODS`
66 pub cors_allow_methods: String,
67 /// `RWS_CONFIG_CORS_ALLOW_HEADERS`
68 pub cors_allow_headers: String,
69 /// `RWS_CONFIG_CORS_EXPOSE_HEADERS`
70 pub cors_expose_headers: String,
71 /// `RWS_CONFIG_CORS_MAX_AGE`
72 pub cors_max_age: String,
73 /// `RWS_CONFIG_RATE_LIMIT_MAX_REQUESTS`
74 pub rate_limit_max_requests: u32,
75 /// `RWS_CONFIG_RATE_LIMIT_WINDOW_SECS`
76 pub rate_limit_window_secs: u64,
77 /// `RWS_CONFIG_LOG_FORMAT`
78 pub log_format: String,
79 /// `RWS_CONFIG_REQUEST_ALLOCATION_SIZE_IN_BYTES`
80 pub request_allocation_size: i64,
81 /// `RWS_CONFIG_MAX_BODY_SIZE_IN_BYTES`
82 pub max_body_size: u64,
83}
84
85impl ConfigSnapshot {
86 fn from_env() -> Self {
87 let read = |key: &str| std::env::var(key).unwrap_or_default();
88 Self {
89 cors_allow_all: read(Config::RWS_CONFIG_CORS_ALLOW_ALL)
90 .eq_ignore_ascii_case("true"),
91 cors_allow_origins: read(Config::RWS_CONFIG_CORS_ALLOW_ORIGINS),
92 cors_allow_credentials: read(Config::RWS_CONFIG_CORS_ALLOW_CREDENTIALS),
93 cors_allow_methods: read(Config::RWS_CONFIG_CORS_ALLOW_METHODS),
94 cors_allow_headers: read(Config::RWS_CONFIG_CORS_ALLOW_HEADERS),
95 cors_expose_headers: read(Config::RWS_CONFIG_CORS_EXPOSE_HEADERS),
96 cors_max_age: read(Config::RWS_CONFIG_CORS_MAX_AGE),
97 rate_limit_max_requests: std::env::var("RWS_CONFIG_RATE_LIMIT_MAX_REQUESTS")
98 .ok()
99 .and_then(|v| v.parse().ok())
100 .unwrap_or(1000),
101 rate_limit_window_secs: std::env::var("RWS_CONFIG_RATE_LIMIT_WINDOW_SECS")
102 .ok()
103 .and_then(|v| v.parse().ok())
104 .unwrap_or(60),
105 log_format: read(Config::RWS_CONFIG_LOG_FORMAT),
106 request_allocation_size: std::env::var(
107 Config::RWS_CONFIG_REQUEST_ALLOCATION_SIZE_IN_BYTES,
108 )
109 .ok()
110 .and_then(|v| v.parse().ok())
111 .unwrap_or(*Config::RWS_DEFAULT_REQUEST_ALLOCATION_SIZE_IN_BYTES),
112 max_body_size: crate::entry_point::get_max_body_size(),
113 }
114 }
115}
116
117static SNAPSHOT: OnceLock<RwLock<ConfigSnapshot>> = OnceLock::new();
118
119fn global() -> &'static RwLock<ConfigSnapshot> {
120 SNAPSHOT.get_or_init(|| RwLock::new(ConfigSnapshot::from_env()))
121}
122
123/// Returns a clone of the current hot-reloadable configuration snapshot.
124///
125/// This takes a brief read lock and clones a handful of strings — safe to call
126/// on every request if needed.
127pub fn current() -> ConfigSnapshot {
128 global().read().unwrap().clone()
129}
130
131/// Re-read `rws.config.toml` and apply all hot-reloadable changes in-place.
132///
133/// Called automatically when [`RELOAD_REQUESTED`] is set (SIGHUP on Unix) or
134/// from the `POST /admin/config/reload` handler.
135///
136/// Settings that cannot be changed without a restart (IP, port, thread count,
137/// TLS cert/key) are silently ignored — they are re-parsed from the file but
138/// have no effect until the next process start.
139pub fn reload() {
140 // Re-parse rws.config.toml → updates process env vars for CORS, log format, etc.
141 // Only one thread ever calls this (the signal handler or admin endpoint),
142 // while workers only read env vars, so the single-writer / many-readers
143 // pattern is safe in practice on all supported platforms.
144 override_environment_variables_from_config(None);
145
146 let snapshot = ConfigSnapshot::from_env();
147
148 // Apply rate-limit changes to the live global limiter immediately.
149 rate_limit::global().set_limits(
150 snapshot.rate_limit_max_requests,
151 snapshot.rate_limit_window_secs,
152 );
153
154 // Publish the new snapshot atomically.
155 *global().write().unwrap() = snapshot.clone();
156
157 // Re-glob Tera templates from disk, if the `tera` feature is enabled and
158 // `template::init()` was actually called — a no-op otherwise.
159 #[cfg(feature = "tera")]
160 crate::template::reload_if_initialized();
161
162 println!(
163 "Config reloaded — cors_allow_all={} rate_limit={}/{} log_format={}",
164 snapshot.cors_allow_all,
165 snapshot.rate_limit_max_requests,
166 snapshot.rate_limit_window_secs,
167 snapshot.log_format,
168 );
169}
170
171/// Install a `SIGHUP` signal handler that sets [`RELOAD_REQUESTED`].
172///
173/// Call this once at server startup (before the accept loop). Safe to call
174/// on non-Unix platforms — it compiles to a no-op.
175///
176/// The handler itself does the minimum allowed in a signal context: it stores
177/// `true` into an `AtomicBool`. The actual [`reload()`] call happens on the
178/// main thread between connection accepts.
179pub fn install_sighup_handler() {
180 #[cfg(all(unix, feature = "http1"))]
181 // SAFETY: The handler only writes to a process-global AtomicBool which is
182 // async-signal-safe. No allocation, no locks, no I/O.
183 unsafe {
184 libc::signal(libc::SIGHUP, sighup_handler as *const () as libc::sighandler_t);
185 }
186}
187
188#[cfg(all(unix, feature = "http1"))]
189extern "C" fn sighup_handler(_: libc::c_int) {
190 RELOAD_REQUESTED.store(true, Ordering::SeqCst);
191}