Skip to main content

hyprstream_workers/
config.rs

1//! Configuration types for hyprstream-workers
2//!
3//! Provides configuration for:
4//! - WorkerService (CRI runtime)
5//! - SandboxPool (warm VM management)
6//! - WorkflowService (orchestration)
7//! - RafsStore (image storage)
8
9use serde::{Deserialize, Serialize};
10use std::path::PathBuf;
11
12use crate::runtime::AdmissionConfig;
13
14/// Default value for [`WorkerConfig::backend`].
15///
16/// `"auto"` asks the runtime to pick the highest-priority *available* registered
17/// sandbox backend (see [`crate::runtime::resolve_backend`]).
18fn default_backend() -> String {
19    "auto".to_owned()
20}
21
22/// Top-level configuration for the workers crate
23#[derive(Debug, Clone, Serialize, Deserialize)]
24#[serde(default)]
25pub struct WorkerConfig {
26    /// Sandbox backend selection (operator-driven).
27    ///
28    /// A registered backend name or `"auto"`:
29    /// * `"auto"` (default) — pick the highest-priority *available* registered
30    ///   backend.
31    /// * `"kata"` — full VM isolation (only available in `kata-vm` builds).
32    /// * `"nspawn"` — systemd-nspawn lightweight container.
33    ///
34    /// Resolved fail-closed at startup against the inventory backend registry —
35    /// an unavailable or unknown name errors rather than silently downgrading
36    /// isolation. See [`crate::runtime::resolve_backend`].
37    #[serde(default = "default_backend")]
38    pub backend: String,
39
40    /// Pool configuration for VM management
41    pub pool: PoolConfig,
42
43    /// Image storage configuration
44    pub images: ImageConfig,
45
46    /// Workflow service configuration
47    pub workflow: WorkflowConfig,
48
49    /// Event bus configuration
50    pub events: EventConfig,
51
52    /// QUIC/WebTransport port. None = no QUIC, Some(0) = ephemeral, Some(N) = explicit.
53    #[serde(default)]
54    pub quic_port: Option<u16>,
55}
56
57impl Default for WorkerConfig {
58    fn default() -> Self {
59        Self {
60            backend: default_backend(),
61            pool: PoolConfig::default(),
62            images: ImageConfig::default(),
63            workflow: WorkflowConfig::default(),
64            events: EventConfig::default(),
65            quic_port: None,
66        }
67    }
68}
69
70/// Hypervisor type for VM management
71#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
72#[serde(rename_all = "kebab-case")]
73pub enum HypervisorType {
74    /// Cloud Hypervisor (recommended, requires cloud-hypervisor binary)
75    #[default]
76    CloudHypervisor,
77    /// Dragonball (built-in VMM, no external binary required)
78    #[cfg(feature = "dragonball")]
79    Dragonball,
80}
81
82impl std::fmt::Display for HypervisorType {
83    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
84        match self {
85            Self::CloudHypervisor => write!(f, "cloud-hypervisor"),
86            #[cfg(feature = "dragonball")]
87            Self::Dragonball => write!(f, "dragonball"),
88        }
89    }
90}
91
92/// Configuration for the sandbox pool (Kata VM management)
93#[derive(Debug, Clone, Serialize, Deserialize)]
94#[serde(default)]
95pub struct PoolConfig {
96    /// Hypervisor to use for VM management
97    pub hypervisor: HypervisorType,
98
99    /// Path to hypervisor binary (for cloud-hypervisor)
100    /// If empty, uses PATH lookup
101    pub hypervisor_path: PathBuf,
102
103    /// Maximum number of active sandboxes (VMs)
104    pub max_sandboxes: usize,
105
106    /// Number of pre-warmed sandboxes to keep ready
107    pub warm_pool_size: usize,
108
109    /// Path to the base VM image
110    pub vm_image: PathBuf,
111
112    /// Path to the VM kernel
113    pub kernel_path: PathBuf,
114
115    /// Path to cloud-init templates directory
116    pub cloud_init_dir: PathBuf,
117
118    /// Runtime directory for sandbox sockets and state
119    pub runtime_dir: PathBuf,
120
121    /// VM memory in MB
122    pub vm_memory_mb: u64,
123
124    /// VM CPUs
125    pub vm_cpus: u32,
126
127    /// Timeout for sandbox creation in seconds
128    pub create_timeout_secs: u64,
129
130    /// Timeout for sandbox stop in seconds
131    pub stop_timeout_secs: u64,
132
133    /// Admission control: per-Subject/per-group quotas, bounded wait-queue,
134    /// and declared local schedulable capacity for `SandboxPool::acquire`'s
135    /// decision engine (#525 P2).
136    ///
137    /// 🔒 See [`AdmissionConfig`]'s doc for the judgment calls this shape
138    /// bakes in (flagged for reviewer sign-off). Defaults are unconstrained,
139    /// so an operator who does not set this section gets exactly the
140    /// pre-#525 behavior (only `max_sandboxes` capacity is enforced).
141    pub admission: AdmissionConfig,
142}
143
144impl Default for PoolConfig {
145    fn default() -> Self {
146        Self {
147            hypervisor: HypervisorType::default(),
148            hypervisor_path: PathBuf::new(), // Use PATH lookup
149            max_sandboxes: 10,
150            warm_pool_size: 2,
151            vm_image: PathBuf::from("/var/lib/hyprstream/vm/rootfs.img"),
152            kernel_path: PathBuf::from("/var/lib/hyprstream/vm/vmlinux"),
153            cloud_init_dir: PathBuf::from("/var/lib/hyprstream/cloud-init"),
154            runtime_dir: crate::paths::sandboxes_dir(),
155            vm_memory_mb: 2048,
156            vm_cpus: 2,
157            create_timeout_secs: 60,
158            stop_timeout_secs: 30,
159            admission: AdmissionConfig::default(),
160        }
161    }
162}
163
164/// Configuration for image storage (Nydus RAFS)
165#[derive(Debug, Clone, Serialize, Deserialize)]
166#[serde(default)]
167pub struct ImageConfig {
168    /// Directory for chunk blobs (content-addressed)
169    pub blobs_dir: PathBuf,
170
171    /// Directory for RAFS bootstrap metadata
172    pub bootstrap_dir: PathBuf,
173
174    /// Directory for tag references
175    pub refs_dir: PathBuf,
176
177    /// Cache directory for nydus-storage blob cache
178    pub cache_dir: PathBuf,
179
180    /// Runtime directory for nydus daemon sockets
181    pub runtime_dir: PathBuf,
182
183    /// Dragonfly peer address for P2P blob fetching (e.g., "127.0.0.1:65001")
184    /// When set, blob fetches route through Dragonfly for P2P distribution
185    #[serde(default)]
186    pub dragonfly_peer: Option<String>,
187
188    /// Number of FUSE threads for nydus daemon
189    pub fuse_threads: usize,
190
191    /// Chunk size in bytes (default 1MB)
192    pub chunk_size: usize,
193
194    /// Enable lazy loading (on-demand chunk fetch)
195    pub lazy_loading: bool,
196
197    /// Maximum cache size in bytes
198    pub cache_size_bytes: u64,
199}
200
201impl Default for ImageConfig {
202    fn default() -> Self {
203        Self {
204            blobs_dir: PathBuf::from("/var/lib/hyprstream/images/blobs"),
205            bootstrap_dir: PathBuf::from("/var/lib/hyprstream/images/bootstrap"),
206            refs_dir: PathBuf::from("/var/lib/hyprstream/images/refs"),
207            cache_dir: PathBuf::from("/var/lib/hyprstream/images/cache"),
208            runtime_dir: crate::paths::nydus_dir(),
209            dragonfly_peer: None,
210            fuse_threads: 4,
211            chunk_size: 1024 * 1024, // 1MB
212            lazy_loading: true,
213            cache_size_bytes: 10 * 1024 * 1024 * 1024, // 10GB
214        }
215    }
216}
217
218/// Configuration for workflow service
219#[derive(Debug, Clone, Serialize, Deserialize)]
220#[serde(default)]
221pub struct WorkflowConfig {
222    /// Directory for workflow run logs
223    pub logs_dir: PathBuf,
224
225    /// Maximum concurrent workflow runs
226    pub max_concurrent_runs: usize,
227
228    /// Default timeout for workflow jobs in seconds
229    pub job_timeout_secs: u64,
230
231    /// Default timeout for workflow steps in seconds
232    pub step_timeout_secs: u64,
233
234    /// Enable automatic workflow discovery on repo events
235    pub auto_discover: bool,
236
237    /// Opt-in activation of the WorkflowService factory (#989).
238    ///
239    /// The engine is fully implemented but historically had no factory, so the
240    /// daemon never started it. First activation must not change daemon behavior
241    /// for everyone — `enabled = false` by default; an operator who wants the
242    /// workflow service sets `[worker.workflow] enabled = true`.
243    pub enabled: bool,
244}
245
246impl Default for WorkflowConfig {
247    fn default() -> Self {
248        Self {
249            logs_dir: PathBuf::from("/var/lib/hyprstream/workflows/logs"),
250            max_concurrent_runs: 10,
251            job_timeout_secs: 3600, // 1 hour
252            step_timeout_secs: 600, // 10 minutes
253            auto_discover: true,
254            // Default-off: the workflow engine is opt-in (#989). The factory
255            // bails unless an operator explicitly sets `enabled = true`.
256            enabled: false,
257        }
258    }
259}
260
261/// Configuration for the worker event bus.
262///
263/// The worker publishes lifecycle events over the moq-lite streaming plane
264/// (#167) via `hyprstream_rpc::events::EventPublisher`; there is no ZMQ socket
265/// to tune.
266/// The former ZMQ high-water-mark knobs (`publisher_hwm`/`subscriber_hwm`) were
267/// removed with the ZMQ stack (#138/#167) — moq back-pressure/QoS is governed by
268/// `hyprstream_rpc::moq_stream` `StreamOpt`, not per-socket HWMs here.
269#[derive(Debug, Clone, Default, Serialize, Deserialize)]
270#[serde(default)]
271pub struct EventConfig {
272    /// Enable event logging for debugging
273    pub log_events: bool,
274}
275
276#[cfg(test)]
277mod tests {
278    use super::*;
279
280    #[test]
281    fn test_default_config() {
282        let config = WorkerConfig::default();
283        assert_eq!(config.pool.max_sandboxes, 10);
284        assert_eq!(config.pool.warm_pool_size, 2);
285        assert!(config.images.lazy_loading);
286        assert!(config.workflow.auto_discover);
287    }
288
289    #[test]
290    fn test_config_serialization() -> Result<(), Box<dyn std::error::Error>> {
291        let config = WorkerConfig::default();
292        let yaml = serde_yaml::to_string(&config)?;
293        let parsed: WorkerConfig = serde_yaml::from_str(&yaml)?;
294        assert_eq!(parsed.pool.max_sandboxes, config.pool.max_sandboxes);
295        Ok(())
296    }
297
298    #[test]
299    fn test_worker_config_toml_roundtrips_at_defaults() -> Result<(), Box<dyn std::error::Error>> {
300        // F3 regression: the default `AdmissionConfig` used to set
301        // `max_per_subject`/`max_per_group` to `usize::MAX`, which is not a
302        // valid TOML i64 — `toml::to_string_pretty` errored, breaking any
303        // `Config::save()` that included a `[worker]` section. The unlimited
304        // quotas are now `Option<usize>` serialized as *absent*, so a default
305        // config must round-trip through TOML cleanly.
306        let config = WorkerConfig::default();
307        let toml_str = toml::to_string_pretty(&config)?;
308        // Unlimited quotas serialize as absent, never as a giant sentinel int.
309        assert!(
310            !toml_str.contains("max_per_subject"),
311            "unlimited per-subject quota must serialize as absent, got:\n{toml_str}"
312        );
313        assert!(!toml_str.contains("max_per_group"));
314        let parsed: WorkerConfig = toml::from_str(&toml_str)?;
315        assert_eq!(parsed.pool.admission.max_per_subject, None);
316        assert_eq!(parsed.pool.admission.max_per_group, None);
317        assert_eq!(parsed.pool.max_sandboxes, config.pool.max_sandboxes);
318        Ok(())
319    }
320
321    #[test]
322    fn test_worker_config_toml_roundtrips_with_explicit_quotas(
323    ) -> Result<(), Box<dyn std::error::Error>> {
324        // A set quota must round-trip as a normal integer.
325        let mut config = WorkerConfig::default();
326        config.pool.admission.max_per_subject = Some(4);
327        config.pool.admission.max_per_group = Some(16);
328        let toml_str = toml::to_string_pretty(&config)?;
329        let parsed: WorkerConfig = toml::from_str(&toml_str)?;
330        assert_eq!(parsed.pool.admission.max_per_subject, Some(4));
331        assert_eq!(parsed.pool.admission.max_per_group, Some(16));
332        Ok(())
333    }
334
335    #[test]
336    fn test_hypervisor_type_serialization() -> Result<(), Box<dyn std::error::Error>> {
337        // Test default (cloud-hypervisor)
338        let config = PoolConfig::default();
339        assert_eq!(config.hypervisor, HypervisorType::CloudHypervisor);
340
341        // Test serialization roundtrip
342        let yaml = serde_yaml::to_string(&config)?;
343        assert!(
344            yaml.contains("cloud-hypervisor"),
345            "YAML should contain kebab-case hypervisor"
346        );
347        let parsed: PoolConfig = serde_yaml::from_str(&yaml)?;
348        assert_eq!(parsed.hypervisor, HypervisorType::CloudHypervisor);
349
350        // Test parsing from string
351        let yaml_str = "hypervisor: cloud-hypervisor\nmax_sandboxes: 5";
352        let parsed: PoolConfig = serde_yaml::from_str(yaml_str)?;
353        assert_eq!(parsed.hypervisor, HypervisorType::CloudHypervisor);
354        assert_eq!(parsed.max_sandboxes, 5);
355        Ok(())
356    }
357
358    #[test]
359    fn test_hypervisor_type_display() {
360        assert_eq!(
361            HypervisorType::CloudHypervisor.to_string(),
362            "cloud-hypervisor"
363        );
364        #[cfg(feature = "dragonball")]
365        assert_eq!(HypervisorType::Dragonball.to_string(), "dragonball");
366    }
367
368    #[test]
369    fn test_backend_default_is_auto() {
370        // Default selection is "auto": pick the strongest *available* registered
371        // backend at startup (resolved fail-closed, never silent downgrade).
372        assert_eq!(WorkerConfig::default().backend, "auto");
373    }
374
375    #[test]
376    fn test_backend_string_parses_verbatim() -> Result<(), Box<dyn std::error::Error>> {
377        // `backend` is a free-form string matched against the registry by name;
378        // config parsing does not validate it (resolution does, fail-closed).
379        for name in ["auto", "kata", "nspawn", "anything"] {
380            let yaml = format!("backend: {name}\n");
381            let config: WorkerConfig = serde_yaml::from_str(&yaml)?;
382            assert_eq!(config.backend, name);
383        }
384        Ok(())
385    }
386
387    #[test]
388    fn test_backend_absent_defaults_to_auto() -> Result<(), Box<dyn std::error::Error>> {
389        // Missing `backend` key falls back to the field default ("auto"), not "".
390        let config: WorkerConfig = serde_yaml::from_str("pool:\n  max_sandboxes: 5\n")?;
391        assert_eq!(config.backend, "auto");
392        Ok(())
393    }
394}