apimock_server/
control.rs

1//! Stage-1 control/introspection API for the server.
2//!
3//! # Scope (5.0.0)
4//!
5//! Per the brief (§4.3, §5.3, §7), the server crate exposes:
6//!
7//! - A minimal handle the embedder can hold.
8//! - A "state" enum the embedder can poll.
9//! - A reload-hint type.
10//!
11//! Critically, **the server does not restart itself**. When a config
12//! edit would need the listener rebuilt, the server-side code only
13//! emits a hint; an external control layer (GUI / supervisor) decides
14//! whether to restart. That's the brief's §7 rule and the shape here
15//! reflects it.
16//!
17//! Implementation of actual shutdown / reload wiring is stage-2 work.
18//! In 5.0.0 these types exist with placeholder methods so downstream
19//! code can start coding against them.
20
21use serde::Serialize;
22
23/// Handle an embedder holds to interact with a running server.
24///
25/// # Why it doesn't expose a `.restart()`
26///
27/// The brief is specific: "restart は server crate の内部責務にしない"
28/// (restart is not a server-crate responsibility). A `ServerHandle`
29/// carries read-only introspection and a shutdown signal — nothing
30/// more. If a change requires the listener to rebind a new port, the
31/// embedder tears the server down and constructs a fresh one.
32#[derive(Clone, Debug)]
33#[non_exhaustive]
34pub struct ServerHandle {
35    /// Address the HTTP listener is bound to, if any.
36    pub http_addr: Option<std::net::SocketAddr>,
37    /// Address the HTTPS listener is bound to, if any.
38    pub https_addr: Option<std::net::SocketAddr>,
39    /// Hot-reload handle for TLS certificates (RFC 020).
40    ///
41    /// `Some` when an HTTPS listener is active with a reloadable cert.
42    /// `None` for HTTP-only servers.
43    pub cert_reloader: Option<std::sync::Arc<crate::tls::ReloadableCertResolver>>,
44}
45
46impl ServerHandle {
47    /// Reload the TLS certificate and private key from the given PEM files.
48    ///
49    /// Returns `Ok(())` if the swap succeeded; the new cert is used for all
50    /// TLS handshakes started after this call. On error, the old cert remains
51    /// active.
52    ///
53    /// # Errors
54    ///
55    /// Returns an error string if:
56    /// - No HTTPS listener is active (`cert_reloader` is `None`).
57    /// - The new cert or key fails to parse.
58    pub fn reload_tls_certs(&self, cert_path: &str, key_path: &str) -> Result<(), String> {
59        match &self.cert_reloader {
60            Some(reloader) => reloader
61                .reload_from_paths(cert_path, key_path)
62                .map_err(|e| e.to_string()),
63            None => Err("no HTTPS listener active; cert reload not available".to_owned()),
64        }
65    }
66}
67
68/// Small control surface for the embedder.
69///
70/// 5.0.0 ships this as a placeholder; stage-2 adds the actual
71/// shutdown-signal channel + reload trigger implementation.
72#[derive(Clone, Debug, Default)]
73#[non_exhaustive]
74pub struct ServerControl {}
75
76impl ServerControl {
77    pub fn new() -> Self {
78        Self {}
79    }
80}
81
82/// What the server is doing right now.
83#[derive(Clone, Copy, Debug, Serialize)]
84pub enum ServerState {
85    /// The listener is being brought up.
86    Starting,
87    /// Requests are being served normally.
88    Running,
89    /// Shutdown has been requested; drains are in flight.
90    ShuttingDown,
91    /// The listener is no longer accepting connections.
92    Stopped,
93}
94
95/// How much of the server needs to restart after a config change.
96///
97/// # Why this lives here alongside `apimock_config::ReloadHint`
98///
99/// The config crate carries the same concept as a `view::ReloadHint`
100/// struct because it's what an `ApplyResult` / `SaveResult` carries;
101/// GUIs consume it from the config layer without pulling server.
102/// The server-side mirror is an enum for more ergonomic pattern
103/// matching on the server's own code paths. The `From` impls below
104/// bridge the two.
105#[derive(Clone, Copy, Debug, Serialize)]
106pub enum ReloadHint {
107    /// No reload required.
108    None,
109    /// Rule sets / middlewares need to reload.
110    Reload,
111    /// Listener configuration changed; need a full restart.
112    Restart,
113}
114
115impl From<apimock_config::ReloadHint> for ReloadHint {
116    fn from(value: apimock_config::ReloadHint) -> Self {
117        // `Restart` implies `Reload`, so restart wins if both flags are set.
118        if value.requires_restart {
119            ReloadHint::Restart
120        } else if value.requires_reload {
121            ReloadHint::Reload
122        } else {
123            ReloadHint::None
124        }
125    }
126}
127
128impl From<ReloadHint> for apimock_config::ReloadHint {
129    fn from(value: ReloadHint) -> Self {
130        match value {
131            ReloadHint::None => apimock_config::ReloadHint::none(),
132            ReloadHint::Reload => apimock_config::ReloadHint::reload(),
133            ReloadHint::Restart => apimock_config::ReloadHint::restart(),
134        }
135    }
136}
apimock_server/control.rs

apimock_server/
control.rs
