rust_supervisor/config/
configurable.rs

1//! Public configuration input model for supervisor users.
2//!
3//! The structs in this module are the single raw configuration surface used for
4//! YAML loading, template rendering, and JSON Schema generation.
5
6use confique::Config;
7use schemars::JsonSchema;
8use serde::{Deserialize, Serialize};
9use std::path::PathBuf;
10
11use crate::{
12    config::{
13        audit::AuditConfig,
14        ipc_security::IpcSecurityConfig,
15        policy::{
16            ChildStrategyOverrideConfig, DynamicSupervisorConfig, FailureWindowConfig, GroupConfig,
17            GroupDependencyConfig, GroupStrategyConfig, MeltdownConfig, RestartBudgetConfig,
18            SeverityDefaultConfig, SupervisionPipelineConfig,
19        },
20    },
21    spec::{
22        child_declaration::ChildDeclaration,
23        supervisor::{BackpressureConfig, EscalationPolicy, SupervisionStrategy},
24    },
25};
26
27/// Configuration file shape loaded from YAML.
28#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Config, JsonSchema)]
29pub struct SupervisorConfig {
30    /// Additional configuration files included by `rust-config-tree`.
31    #[config(default = [])]
32    #[serde(default)]
33    pub include: Vec<PathBuf>,
34
35    /// Root supervisor declaration values.
36    #[config(nested)]
37    pub supervisor: SupervisorRootConfig,
38    /// Runtime policy values.
39    #[config(nested)]
40    pub policy: PolicyConfig,
41    /// Shutdown budget values.
42    #[config(nested)]
43    pub shutdown: ShutdownConfig,
44    /// Observability switches and capacities.
45    #[config(nested)]
46    pub observability: ObservabilityConfig,
47    /// Command audit persistence configuration.
48    #[config(nested)]
49    #[serde(default)]
50    pub audit: AuditConfig,
51    /// Backpressure policy for observability event subscribers.
52    #[config(nested)]
53    #[serde(default)]
54    pub backpressure: BackpressureConfig,
55    /// Group-level restart budgets and membership declarations.
56    #[config(default = [])]
57    #[serde(default)]
58    pub groups: Vec<GroupConfig>,
59    /// Group-level strategy overrides.
60    #[config(default = [])]
61    #[serde(default)]
62    pub group_strategies: Vec<GroupStrategyConfig>,
63    /// Cross-group failure propagation dependencies.
64    #[config(default = [])]
65    #[serde(default)]
66    pub group_dependencies: Vec<GroupDependencyConfig>,
67    /// Child-level strategy overrides.
68    #[config(default = [])]
69    #[serde(default)]
70    pub child_strategy_overrides: Vec<ChildStrategyOverrideConfig>,
71    /// Default severity class per task role.
72    #[config(default = [])]
73    #[serde(default)]
74    pub severity_defaults: Vec<SeverityDefaultConfig>,
75    /// Optional target-side dashboard IPC configuration.
76    pub dashboard: Option<DashboardIpcConfig>,
77    /// Child declarations loaded from YAML children array.
78    #[config(default = [])]
79    #[serde(default)]
80    pub children: Vec<ChildDeclaration>,
81}
82
83impl rust_config_tree::ConfigSchema for SupervisorConfig {
84    /// Returns child configuration paths declared by one loaded layer.
85    ///
86    /// # Arguments
87    ///
88    /// - `layer`: Partially loaded supervisor configuration layer.
89    ///
90    /// # Returns
91    ///
92    /// Returns include paths declared by this configuration layer.
93    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
94        layer.include.clone().unwrap_or_default()
95    }
96}
97
98/// Root supervisor configuration.
99#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Config, JsonSchema)]
100pub struct SupervisorRootConfig {
101    /// Restart scope strategy for child failures.
102    pub strategy: SupervisionStrategy,
103    /// Optional supervisor-level escalation policy.
104    #[serde(default)]
105    pub escalation_policy: Option<EscalationPolicy>,
106    /// Runtime dynamic child acceptance policy.
107    #[config(nested)]
108    #[serde(default)]
109    pub dynamic_supervisor: DynamicSupervisorConfig,
110}
111
112/// Restart, backoff, and fuse configuration.
113#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Config, JsonSchema)]
114pub struct PolicyConfig {
115    /// Maximum child restarts within the child restart window.
116    pub child_restart_limit: u32,
117    /// Child restart window in milliseconds.
118    pub child_restart_window_ms: u64,
119    /// Maximum supervisor failures within the supervisor failure window.
120    pub supervisor_failure_limit: u32,
121    /// Supervisor failure window in milliseconds.
122    pub supervisor_failure_window_ms: u64,
123    /// Initial backoff in milliseconds.
124    pub initial_backoff_ms: u64,
125    /// Maximum backoff in milliseconds.
126    pub max_backoff_ms: u64,
127    /// Jitter ratio expressed as a fraction between zero and one.
128    pub jitter_ratio: f64,
129    /// Heartbeat interval in milliseconds.
130    pub heartbeat_interval_ms: u64,
131    /// Stale heartbeat threshold in milliseconds.
132    pub stale_after_ms: u64,
133    /// Restart budget used by the supervision pipeline.
134    #[config(nested)]
135    #[serde(default)]
136    pub restart_budget: RestartBudgetConfig,
137    /// Failure window used by the supervision pipeline.
138    #[config(nested)]
139    #[serde(default)]
140    pub failure_window: FailureWindowConfig,
141    /// Meltdown fuse limits for child, group, and supervisor scopes.
142    #[config(nested)]
143    #[serde(default)]
144    pub meltdown: MeltdownConfig,
145    /// Supervision pipeline capacities and concurrent restart limit.
146    #[config(nested)]
147    #[serde(default)]
148    pub supervision_pipeline: SupervisionPipelineConfig,
149}
150
151/// Shutdown coordination configuration.
152#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Config, JsonSchema)]
153pub struct ShutdownConfig {
154    /// Graceful drain timeout in milliseconds.
155    pub graceful_timeout_ms: u64,
156    /// Abort wait timeout in milliseconds.
157    pub abort_wait_ms: u64,
158}
159
160/// Observability configuration.
161#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Config, JsonSchema)]
162pub struct ObservabilityConfig {
163    /// Event journal capacity.
164    pub event_journal_capacity: usize,
165    /// Whether metrics recording is enabled.
166    pub metrics_enabled: bool,
167    /// Whether command audit recording is enabled.
168    pub audit_enabled: bool,
169}
170
171/// Optional target-side dashboard IPC configuration.
172#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Config, JsonSchema)]
173pub struct DashboardIpcConfig {
174    /// Whether the target process opens the local IPC endpoint.
175    pub enabled: bool,
176    /// Stable target process identifier sent to relay and UI.
177    pub target_id: Option<String>,
178    /// Local Unix domain socket path used by the target process.
179    pub path: Option<PathBuf>,
180    /// Socket file permission string such as `0600`.
181    pub permissions: Option<String>,
182    /// Socket bind behavior when the path already exists.
183    pub bind_mode: Option<DashboardIpcBindMode>,
184    /// Dynamic registration settings used after IPC is ready.
185    pub registration: Option<DashboardRegistrationConfig>,
186    /// Optional IPC security pipeline configuration (C1-C9).
187    #[serde(default)]
188    pub security_config: Option<IpcSecurityConfig>,
189}
190
191/// Socket bind behavior for target-side dashboard IPC.
192#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
193#[serde(rename_all = "snake_case")]
194pub enum DashboardIpcBindMode {
195    /// Fail when the socket path already exists.
196    CreateNew,
197    /// Remove a stale socket path before binding.
198    ReplaceStale,
199}
200
201/// Dynamic registration settings for a target process.
202#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Config, JsonSchema)]
203pub struct DashboardRegistrationConfig {
204    /// Whether the target process registers with relay after IPC is ready.
205    pub enabled: bool,
206    /// Local relay registration socket path.
207    pub relay_registration_path: Option<PathBuf>,
208    /// Human-readable name shown in the dashboard.
209    pub display_name: Option<String>,
210    /// Registration lease duration in seconds.
211    pub lease_seconds: Option<u64>,
212    /// Registration heartbeat interval in seconds.
213    pub registration_heartbeat_interval_seconds: Option<u64>,
214}
rust_supervisor/config/configurable.rs

rust_supervisor/config/
configurable.rs
