Skip to main content

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}