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}
40
41/// Small control surface for the embedder.
42///
43/// 5.0.0 ships this as a placeholder; stage-2 adds the actual
44/// shutdown-signal channel + reload trigger implementation.
45#[derive(Clone, Debug, Default)]
46#[non_exhaustive]
47pub struct ServerControl {}
48
49impl ServerControl {
50    pub fn new() -> Self {
51        Self {}
52    }
53}
54
55/// What the server is doing right now.
56#[derive(Clone, Copy, Debug, Serialize)]
57pub enum ServerState {
58    /// The listener is being brought up.
59    Starting,
60    /// Requests are being served normally.
61    Running,
62    /// Shutdown has been requested; drains are in flight.
63    ShuttingDown,
64    /// The listener is no longer accepting connections.
65    Stopped,
66}
67
68/// How much of the server needs to restart after a config change.
69///
70/// # Why this lives here alongside `apimock_config::ReloadHint`
71///
72/// The config crate carries the same concept as a `view::ReloadHint`
73/// struct because it's what an `ApplyResult` / `SaveResult` carries;
74/// GUIs consume it from the config layer without pulling server.
75/// The server-side mirror is an enum for more ergonomic pattern
76/// matching on the server's own code paths. The `From` impls below
77/// bridge the two.
78#[derive(Clone, Copy, Debug, Serialize)]
79pub enum ReloadHint {
80    /// No reload required.
81    None,
82    /// Rule sets / middlewares need to reload.
83    Reload,
84    /// Listener configuration changed; need a full restart.
85    Restart,
86}
87
88impl From<apimock_config::ReloadHint> for ReloadHint {
89    fn from(value: apimock_config::ReloadHint) -> Self {
90        // `Restart` implies `Reload`, so restart wins if both flags are set.
91        if value.requires_restart {
92            ReloadHint::Restart
93        } else if value.requires_reload {
94            ReloadHint::Reload
95        } else {
96            ReloadHint::None
97        }
98    }
99}
100
101impl From<ReloadHint> for apimock_config::ReloadHint {
102    fn from(value: ReloadHint) -> Self {
103        match value {
104            ReloadHint::None => apimock_config::ReloadHint::none(),
105            ReloadHint::Reload => apimock_config::ReloadHint::reload(),
106            ReloadHint::Restart => apimock_config::ReloadHint::restart(),
107        }
108    }
109}
apimock_server/control.rs

apimock_server/
control.rs
