harmos_runtime/
config.rs

1/* ***
2 *
3 * Harmos
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * ***
8 */
9
10// Externally Supplied Runtime, Storage, Transport And Tooling Settings.
11
12/* === Modules === */
13
14/* === Re-Exports === */
15
16pub use harmos_domain::config::*;
17
18/* === Imports === */
19
20// Standard Library Imports
21#[cfg(feature = "plugin-guest")]
22use std::num::NonZeroU64;
23use std::num::NonZeroUsize;
24#[cfg(any(feature = "grpc", feature = "plugin"))]
25use std::time::Duration;
26
27// Third Party Imports
28
29// Local Imports
30pub use crate::storage::config::{StorageBudget, StorageRequestSettings, StorageResponseSettings, StorageSettings};
31pub use crate::storage::state::StorageStateSettings;
32use crate::{Error, Result};
33
34/* === Constants === */
35
36/* === Macros === */
37
38/* === Type Aliases === */
39
40/* === Structs === */
41
42#[cfg(feature = "grpc")]
43#[derive(Clone, Copy, Debug)]
44pub struct DecodeSettings {
45    pub message_bytes: NonZeroUsize,
46    pub retained_bytes: NonZeroUsize,
47}
48
49#[cfg(feature = "grpc")]
50#[derive(Clone, Copy, Debug)]
51pub struct EncodeSettings {
52    pub message_bytes: NonZeroUsize,
53    pub buffer_bytes: NonZeroUsize,
54}
55
56#[cfg(feature = "grpc")]
57#[derive(Clone, Copy, Debug)]
58pub struct GrpcServerSettings {
59    pub calls: std::num::NonZeroUsize,
60    pub decode: DecodeSettings,
61    pub encode: EncodeSettings,
62    pub input: crate::operations::StreamSettings,
63    pub output: crate::operations::StreamSettings,
64    pub opening_timeout: Duration,
65}
66
67#[cfg(feature = "grpc")]
68#[derive(Clone, Debug)]
69pub struct GrpcSettings {
70    pub address: std::net::SocketAddr,
71    pub operations: GrpcServerSettings,
72    pub reflection: bool,
73    pub web: bool,
74    // Exact browser origins allowed through the gRPC-Web listener.
75    // An empty list emits no CORS headers.
76    pub allowed_origins: Vec<crate::grpc::Origin>,
77    pub tls: Option<tonic::transport::ServerTlsConfig>,
78    pub connections: NonZeroUsize,
79    pub calls_per_connection: NonZeroUsize,
80    pub request_timeout: Duration,
81    pub shutdown_timeout: Duration,
82}
83
84#[derive(Clone, Debug)]
85pub struct ManagedStorageSettings {
86    pub replay: crate::storage::ReadLimits,
87    pub capture: crate::storage::ReadLimits,
88    pub snapshots: Option<crate::state::SnapshotPolicy>,
89    pub journal_tail: usize,
90}
91
92#[derive(Clone, Copy, Debug)]
93pub struct OperationSettings {
94    pub queued: NonZeroUsize,
95    pub lifecycle_queued: NonZeroUsize,
96    pub preparation_bytes: Option<NonZeroUsize>,
97}
98
99#[cfg(feature = "plugin")]
100#[derive(Clone, Debug)]
101pub struct PluginSettings {
102    pub configuration: Vec<u8>,
103    pub requires: Vec<harmos_domain::Requirement>,
104    pub host_operations: Vec<crate::Identifier>,
105    pub initialization_timeout: Duration,
106    pub shutdown_timeout: Duration,
107    pub encoding_memory_bytes: NonZeroUsize,
108    pub restart: PluginRestartSettings,
109}
110
111#[cfg(feature = "plugin")]
112#[derive(Clone, Copy, Debug, PartialEq, Eq)]
113pub struct PluginRestartSettings {
114    // Automatic Restarts Allowed Per Explicit Activation Cycle.
115    pub retries: u32,
116    pub backoff_base: Duration,
117    pub backoff_cap: Duration,
118}
119
120#[cfg(feature = "plugin-sidecar")]
121#[derive(Clone, Debug)]
122pub struct PluginSidecarSettings {
123    pub plugin: PluginSettings,
124    pub calls: NonZeroUsize,
125}
126
127#[cfg(feature = "plugin-guest")]
128#[derive(Clone, Copy, Debug)]
129pub struct PluginGuestSettings {
130    pub component_bytes: NonZeroUsize,
131    pub memory_bytes: NonZeroUsize,
132    pub fuel: NonZeroU64,
133    pub memories: NonZeroUsize,
134    pub table_elements: NonZeroUsize,
135    pub tables: NonZeroUsize,
136    pub instances: NonZeroUsize,
137}
138
139/* === Enums === */
140
141/* === Traits === */
142
143/* === Implementations === */
144
145#[cfg(feature = "plugin")]
146impl Default for PluginRestartSettings {
147    fn default() -> Self {
148        Self { retries: 0, backoff_base: Duration::from_millis(100), backoff_cap: Duration::from_secs(5) }
149    }
150}
151
152#[cfg(feature = "plugin")]
153impl PluginRestartSettings {
154    pub fn validate(&self) -> Result<()> {
155        if self.backoff_base.is_zero()
156            || self.backoff_cap < self.backoff_base
157            || std::time::Instant::now().checked_add(self.backoff_cap).is_none()
158        {
159            return Err(Error::InvalidInput {
160                field: "plugin restart backoff",
161                reason: "requires positive representable bounds with base no greater than cap",
162            });
163        }
164        Ok(())
165    }
166}
167
168#[cfg(feature = "plugin-sidecar")]
169impl Default for PluginSidecarSettings {
170    fn default() -> Self {
171        Self { plugin: PluginSettings::default(), calls: NonZeroUsize::new(4).unwrap() }
172    }
173}
174
175#[cfg(feature = "plugin")]
176impl Default for PluginSettings {
177    fn default() -> Self {
178        Self {
179            configuration: b"null".to_vec(),
180            requires: Vec::new(),
181            host_operations: Vec::new(),
182            initialization_timeout: Duration::from_secs(5),
183            shutdown_timeout: Duration::from_secs(30),
184            encoding_memory_bytes: NonZeroUsize::new(4096).unwrap(),
185            restart: PluginRestartSettings::default(),
186        }
187    }
188}
189
190#[cfg(feature = "plugin")]
191impl PluginSettings {
192    pub fn validate(&self) -> Result<()> {
193        self.restart.validate()?;
194        for timeout in [self.initialization_timeout, self.shutdown_timeout] {
195            if timeout.is_zero() || std::time::Instant::now().checked_add(timeout).is_none() {
196                return Err(Error::InvalidInput { field: "plugin lifecycle timeout", reason: "must be positive and representable" });
197            }
198        }
199        let grants: std::collections::BTreeSet<_> = self.host_operations.iter().collect();
200        if grants.len() != self.host_operations.len() {
201            return Err(Error::InvalidInput { field: "plugin host operations", reason: "grants must be unique" });
202        }
203        Ok(())
204    }
205}
206
207#[cfg(feature = "plugin-guest")]
208impl Default for PluginGuestSettings {
209    fn default() -> Self {
210        Self {
211            component_bytes: NonZeroUsize::new(64 * 1024 * 1024).unwrap(),
212            memory_bytes: NonZeroUsize::new(64 * 1024 * 1024).unwrap(),
213            fuel: NonZeroU64::new(10_000_000).unwrap(),
214            memories: NonZeroUsize::new(1).unwrap(),
215            table_elements: NonZeroUsize::new(65_536).unwrap(),
216            tables: NonZeroUsize::new(8).unwrap(),
217            instances: NonZeroUsize::new(8).unwrap(),
218        }
219    }
220}
221#[cfg(feature = "grpc")]
222impl Default for GrpcServerSettings {
223    fn default() -> Self {
224        let bytes = std::num::NonZeroUsize::new(16 * 1024 * 1024).unwrap();
225        let message = std::num::NonZeroUsize::new(4 * 1024 * 1024).unwrap();
226        let items = std::num::NonZeroUsize::new(16).unwrap();
227        Self {
228            calls: std::num::NonZeroUsize::new(64).unwrap(),
229            decode: DecodeSettings { message_bytes: message, retained_bytes: bytes },
230            encode: EncodeSettings { message_bytes: message, buffer_bytes: std::num::NonZeroUsize::new(8192).unwrap() },
231            input: crate::operations::StreamSettings { items, bytes },
232            output: crate::operations::StreamSettings { items, bytes },
233            opening_timeout: Duration::from_secs(5),
234        }
235    }
236}
237
238#[cfg(feature = "grpc")]
239impl Default for GrpcSettings {
240    fn default() -> Self {
241        Self {
242            address: ([127, 0, 0, 1], 0).into(),
243            operations: GrpcServerSettings::default(),
244            reflection: false,
245            web: false,
246            allowed_origins: Vec::new(),
247
248            tls: None,
249            connections: NonZeroUsize::new(64).unwrap(),
250            calls_per_connection: NonZeroUsize::new(32).unwrap(),
251            request_timeout: Duration::from_secs(60),
252            shutdown_timeout: Duration::from_secs(10),
253        }
254    }
255}
256
257impl OperationSettings {
258    pub(crate) fn validate(&self) -> Result<()> {
259        if self.queued.get() > tokio::sync::Semaphore::MAX_PERMITS || self.lifecycle_queued.get() > tokio::sync::Semaphore::MAX_PERMITS {
260            return Err(Error::InvalidInput { field: "operation queue capacity", reason: "capacity exceeds the semaphore claim limit" });
261        }
262        if self.preparation_bytes.is_some_and(|bytes| bytes.get() > tokio::sync::Semaphore::MAX_PERMITS || bytes.get() > u32::MAX as usize)
263        {
264            return Err(Error::InvalidInput {
265                field: "operation preparation bytes",
266                reason: "budget exceeds the semaphore byte-claim limit",
267            });
268        }
269        Ok(())
270    }
271}
272
273impl Default for OperationSettings {
274    fn default() -> Self {
275        Self {
276            queued: NonZeroUsize::new(256).expect("nonzero ordinary admission bound"),
277            lifecycle_queued: NonZeroUsize::new(256).expect("nonzero lifecycle admission bound"),
278            preparation_bytes: None,
279        }
280    }
281}
282
283/* === Public Functions === */
284
285/* === Private Functions === */
286
287/* === Tests === */
harmos_runtime/config.rs

harmos_runtime/
config.rs
