rws_server/maintenance/mod.rs
1//! Maintenance mode middleware.
2//!
3//! Set `MAINTENANCE_MODE` to `true` at runtime to return `503 Service
4//! Unavailable` for all requests except `/healthz` and `/readyz`. Clear it to
5//! resume normal traffic.
6//!
7//! # Example
8//!
9//! ```rust,no_run
10//! # extern crate rws_server as rust_web_server;
11//! use rust_web_server::app::App;
12//! use rust_web_server::core::New;
13//! use rust_web_server::maintenance::{MAINTENANCE_MODE, MaintenanceLayer};
14//! use std::sync::atomic::Ordering;
15//!
16//! let app = App::new().wrap(MaintenanceLayer);
17//!
18//! // Enable maintenance mode at runtime.
19//! MAINTENANCE_MODE.store(true, Ordering::SeqCst);
20//! ```
21
22#[cfg(test)]
23mod tests;
24
25use std::sync::atomic::{AtomicBool, Ordering};
26
27use crate::application::Application;
28use crate::middleware::Middleware;
29use crate::request::Request;
30use crate::response::{Response, STATUS_CODE_REASON_PHRASE};
31use crate::server::ConnectionInfo;
32
33/// Flip to `true` to activate maintenance mode; back to `false` to resume.
34pub static MAINTENANCE_MODE: AtomicBool = AtomicBool::new(false);
35
36/// The maintenance response: problem details (unchanged for API clients)
37/// or, for a browser, the HTML page with `[maintenance] message`; with
38/// `Retry-After` (`[maintenance] retry_after_secs`, default 120) since 18.37.0.
39fn service_unavailable(request: &Request) -> Response {
40 let mut response = crate::error::problem::problem_with_text(STATUS_CODE_REASON_PHRASE.n503_service_unavailable, "maintenance", "Service Temporarily Unavailable");
41 let retry = crate::error::page::maintenance_retry_after();
42 if retry > 0 {
43 response.headers.push(crate::header::Header { name: "Retry-After".into(), value: retry.to_string().into() });
44 }
45 crate::error::page::negotiated(response, request)
46}
47
48/// Middleware that returns `503` when [`MAINTENANCE_MODE`] is `true`.
49///
50/// Health probe paths (`/healthz`, `/readyz`) always pass through so that
51/// load balancers can still detect the pod is alive.
52pub struct MaintenanceLayer;
53
54impl Middleware for MaintenanceLayer {
55 /// Headers only: a streamed body passes through untouched.
56 fn accepts_streamed_body(&self, _request: &Request, _connection: &ConnectionInfo) -> bool {
57 true
58 }
59
60
61 fn handle(
62 &self,
63 request: &Request,
64 connection: &ConnectionInfo,
65 next: &dyn Application,
66 ) -> Result<Response, String> {
67 if MAINTENANCE_MODE.load(Ordering::Relaxed) {
68 let path = request.request_uri.split('?').next().unwrap_or(&request.request_uri);
69 if path != "/healthz" && path != "/readyz" {
70 return Ok(service_unavailable(request));
71 }
72 }
73 next.execute(request, connection)
74 }
75
76 /// In-memory only: safe on the event loop.
77 fn runs_inline(&self, _request: &Request, _connection: &ConnectionInfo) -> bool {
78 true
79 }
80
81 /// Off, it does nothing: config-driven proxy routes keep their
82 /// non-blocking forwarder (since 18.10.0, when the binary added this
83 /// layer to proxy mode for the admin API's maintenance switch).
84 fn is_passthrough(&self, _request: &Request, _connection: &ConnectionInfo) -> bool {
85 !MAINTENANCE_MODE.load(Ordering::Relaxed)
86 }
87}