Skip to main content

tokeira_config/
embedded.rs

1//! Configuration for the in-process embedded engine.
2//!
3//! Embedded storage selection is deliberately separate from daemon infrastructure
4//! configuration. A connection endpoint must never imply permission to create AWS
5//! resources, and an invalid durable mode must never fall back to in-memory execution.
6
7use std::{
8    collections::BTreeMap,
9    path::{Path, PathBuf},
10};
11
12use serde::{Deserialize, Deserializer, Serialize};
13use thiserror::Error;
14
15use crate::{ConfigError, TokeiraConfig};
16
17const DEFAULT_STARTUP_TIMEOUT_MS: u64 = 900_000;
18const DEFAULT_MAX_CONNECTIONS: usize = 8;
19const DEFAULT_CONCURRENT_CONNECTION_CREATIONS: usize = 2;
20const DEFAULT_CONNECTION_RATE_PER_SECOND: f64 = 8.0;
21const DEFAULT_CONNECTION_BURST: u64 = 2;
22const MAX_EMBEDDED_CONNECTIONS: usize = 16;
23const MAX_CONCURRENT_CONNECTION_CREATIONS: usize = 4;
24const MAX_CONNECTION_RATE_PER_SECOND: f64 = 16.0;
25const MAX_CONNECTION_BURST: u64 = 4;
26
27/// Complete startup configuration for an in-process engine.
28#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
29#[serde(deny_unknown_fields)]
30pub struct EmbeddedEngineConfig {
31    /// Ordinary server/runtime policy reused by the embedded service stack.
32    pub server: TokeiraConfig,
33    /// Explicit embedded storage selection.
34    #[serde(default)]
35    pub storage: EmbeddedStorageConfig,
36    /// End-to-end budget shared by every embedded startup phase.
37    #[serde(default = "default_embedded_startup_timeout_ms")]
38    pub startup_timeout_ms: u64,
39}
40
41impl Default for EmbeddedEngineConfig {
42    fn default() -> Self {
43        Self {
44            server: TokeiraConfig::default(),
45            storage: EmbeddedStorageConfig::InMemory,
46            startup_timeout_ms: DEFAULT_STARTUP_TIMEOUT_MS,
47        }
48    }
49}
50
51impl EmbeddedEngineConfig {
52    /// Validate the server configuration and the selected embedded storage mode.
53    ///
54    /// Validation reports the selected mode's defect and never rewrites the mode or
55    /// substitutes in-memory storage.
56    pub fn validate(&self) -> Result<(), EmbeddedConfigError> {
57        self.server
58            .validate()
59            .map_err(EmbeddedConfigError::Server)?;
60
61        let mut errors = Vec::new();
62        if self.startup_timeout_ms == 0 {
63            errors.push(EmbeddedValidationError::new(
64                "startup_timeout_ms",
65                "must be positive",
66            ));
67        }
68
69        match &self.storage {
70            EmbeddedStorageConfig::InMemory => {}
71            EmbeddedStorageConfig::ManagedDsql(config) => {
72                validate_nonempty_path(
73                    &config.descriptor_path,
74                    "storage.descriptor_path",
75                    &mut errors,
76                );
77                validate_nonempty(&config.region, "storage.region", &mut errors);
78                validate_limits(&config.limits, &mut errors);
79            }
80            EmbeddedStorageConfig::ExistingDsql(config) => {
81                validate_nonempty(&config.region, "storage.region", &mut errors);
82                validate_nonempty(&config.cluster_id, "storage.cluster_id", &mut errors);
83                validate_nonempty(&config.cluster_arn, "storage.cluster_arn", &mut errors);
84                validate_nonempty(&config.endpoint, "storage.endpoint", &mut errors);
85                validate_limits(&config.limits, &mut errors);
86            }
87        }
88
89        if errors.is_empty() {
90            Ok(())
91        } else {
92            Err(EmbeddedConfigError::Validation(errors))
93        }
94    }
95
96    /// Return the effective migration policy after explicit storage intent validates.
97    ///
98    /// Managed DSQL alone defaults to automatic migration. Existing DSQL carries a
99    /// required policy in its serialized shape, while in-memory storage has none.
100    pub fn effective_migration_policy(&self) -> Option<DsqlMigrationPolicy> {
101        match &self.storage {
102            EmbeddedStorageConfig::InMemory => None,
103            EmbeddedStorageConfig::ManagedDsql(config) => Some(
104                config
105                    .migration_policy
106                    .unwrap_or(DsqlMigrationPolicy::Automatic),
107            ),
108            EmbeddedStorageConfig::ExistingDsql(config) => Some(config.migration_policy),
109        }
110    }
111}
112
113/// Closed set of storage modes supported by one embedded engine process.
114#[derive(Clone, Debug, Default, PartialEq, Serialize)]
115#[serde(tag = "mode", rename_all = "snake_case")]
116pub enum EmbeddedStorageConfig {
117    /// Preserve the existing ephemeral process-local behavior.
118    #[default]
119    InMemory,
120    /// Create or recover a dedicated single-Region Aurora DSQL cluster.
121    ManagedDsql(ManagedEmbeddedDsqlConfig),
122    /// Use an operator-supplied Aurora DSQL cluster without lifecycle mutation.
123    ExistingDsql(ExistingEmbeddedDsqlConfig),
124}
125
126impl<'de> Deserialize<'de> for EmbeddedStorageConfig {
127    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
128    where
129        D: Deserializer<'de>,
130    {
131        #[derive(Deserialize)]
132        struct TaggedStorage {
133            mode: String,
134            #[serde(flatten)]
135            fields: BTreeMap<String, serde_json::Value>,
136        }
137
138        let tagged = TaggedStorage::deserialize(deserializer)?;
139        if tagged.mode == "in_memory" {
140            if let Some(field) = tagged.fields.keys().next() {
141                return Err(serde::de::Error::unknown_field(field, &[]));
142            }
143            return Ok(Self::InMemory);
144        }
145
146        let fields = serde_json::Value::Object(tagged.fields.into_iter().collect());
147        match tagged.mode.as_str() {
148            "managed_dsql" => serde_json::from_value(fields)
149                .map(Self::ManagedDsql)
150                .map_err(serde::de::Error::custom),
151            "existing_dsql" => serde_json::from_value(fields)
152                .map(Self::ExistingDsql)
153                .map_err(serde::de::Error::custom),
154            other => Err(serde::de::Error::unknown_variant(
155                other,
156                &["in_memory", "managed_dsql", "existing_dsql"],
157            )),
158        }
159    }
160}
161
162/// Managed embedded DSQL configuration.
163#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
164#[serde(deny_unknown_fields)]
165pub struct ManagedEmbeddedDsqlConfig {
166    /// Explicit authority to create a missing descriptor or recover its cluster.
167    pub intent: ManagedClusterIntent,
168    /// Host-owned path to the crash-safe cluster descriptor.
169    pub descriptor_path: PathBuf,
170    /// AWS Region in which the dedicated cluster is managed.
171    pub region: String,
172    /// Managed mode defaults to automatic migration only after intent validation.
173    #[serde(default)]
174    pub migration_policy: Option<DsqlMigrationPolicy>,
175    /// Deliberately small process-local connection-creation envelope.
176    #[serde(default)]
177    pub limits: EmbeddedDsqlLimits,
178    /// Optional creation metadata; never used for discovery or identity.
179    #[serde(default)]
180    pub tags: BTreeMap<String, String>,
181}
182
183/// Explicit managed-cluster startup authority.
184#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
185#[serde(rename_all = "snake_case")]
186pub enum ManagedClusterIntent {
187    /// Create a cluster when no descriptor exists, otherwise recover its canonical ID.
188    CreateOrRecover,
189}
190
191/// Configuration for an operator-supplied embedded DSQL cluster.
192#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
193#[serde(deny_unknown_fields)]
194pub struct ExistingEmbeddedDsqlConfig {
195    /// AWS Region used for control-plane validation and authentication.
196    pub region: String,
197    /// Canonical Aurora DSQL cluster identifier.
198    pub cluster_id: String,
199    /// Canonical Aurora DSQL cluster ARN paired with `cluster_id`.
200    pub cluster_arn: String,
201    /// Caller-selected database hostname, including an AWS PrivateLink hostname.
202    ///
203    /// Used for connections, TLS verification, and IAM authentication throughout
204    /// one engine generation. AWS identity/status observations, including wake
205    /// refresh, never replace it. Change it in the next startup configuration to
206    /// select a new locator. It is never used as resource identity or as the
207    /// management API endpoint; Region, cluster ID, and ARN remain mandatory.
208    pub endpoint: String,
209    /// Explicit policy required for an operator-supplied cluster.
210    pub migration_policy: DsqlMigrationPolicy,
211    /// Deliberately small process-local connection-creation envelope.
212    #[serde(default)]
213    pub limits: EmbeddedDsqlLimits,
214}
215
216/// Schema migration policy selected at a DSQL startup boundary.
217#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
218#[serde(rename_all = "snake_case")]
219pub enum DsqlMigrationPolicy {
220    /// Validate the known schema and migrate idempotently to the release target.
221    Automatic,
222    /// Validate compatibility without changing schema state.
223    ValidateOnly,
224}
225
226/// Bounded connection resources available to one embedded DSQL process.
227#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
228#[serde(deny_unknown_fields)]
229pub struct EmbeddedDsqlLimits {
230    /// Maximum physical database connections.
231    pub max_connections: usize,
232    /// Maximum connection establishments simultaneously in flight.
233    pub concurrent_connection_creations: usize,
234    /// Maximum sustained connection-establishment rate.
235    pub connection_rate_per_second: f64,
236    /// Maximum connection-establishment token burst.
237    pub connection_burst: u64,
238}
239
240impl Default for EmbeddedDsqlLimits {
241    fn default() -> Self {
242        Self {
243            max_connections: DEFAULT_MAX_CONNECTIONS,
244            concurrent_connection_creations: DEFAULT_CONCURRENT_CONNECTION_CREATIONS,
245            connection_rate_per_second: DEFAULT_CONNECTION_RATE_PER_SECOND,
246            connection_burst: DEFAULT_CONNECTION_BURST,
247        }
248    }
249}
250
251/// Failure returned while validating an embedded engine configuration.
252#[derive(Debug, Error)]
253pub enum EmbeddedConfigError {
254    /// The reused server configuration is invalid.
255    #[error("embedded server configuration is invalid: {0}")]
256    Server(#[source] ConfigError),
257    /// One or more embedded-only fields are invalid.
258    #[error("embedded configuration validation failed:\n{}", .0.iter().map(ToString::to_string).collect::<Vec<_>>().join("\n"))]
259    Validation(Vec<EmbeddedValidationError>),
260}
261
262/// One field-level embedded configuration validation failure.
263#[derive(Clone, Debug, Error, PartialEq, Eq)]
264#[error("{field}: {message}")]
265pub struct EmbeddedValidationError {
266    /// Stable configuration field path.
267    pub field: String,
268    /// Actionable constraint description without the rejected value.
269    pub message: String,
270}
271
272impl EmbeddedValidationError {
273    fn new(field: &str, message: &str) -> Self {
274        Self {
275            field: field.to_owned(),
276            message: message.to_owned(),
277        }
278    }
279}
280
281fn default_embedded_startup_timeout_ms() -> u64 {
282    DEFAULT_STARTUP_TIMEOUT_MS
283}
284
285fn validate_nonempty(value: &str, field: &str, errors: &mut Vec<EmbeddedValidationError>) {
286    if value.trim().is_empty() {
287        errors.push(EmbeddedValidationError::new(field, "must not be empty"));
288    }
289}
290
291fn validate_nonempty_path(value: &Path, field: &str, errors: &mut Vec<EmbeddedValidationError>) {
292    if value.as_os_str().is_empty() {
293        errors.push(EmbeddedValidationError::new(field, "must not be empty"));
294    }
295}
296
297fn validate_limits(limits: &EmbeddedDsqlLimits, errors: &mut Vec<EmbeddedValidationError>) {
298    if !(1..=MAX_EMBEDDED_CONNECTIONS).contains(&limits.max_connections) {
299        errors.push(EmbeddedValidationError::new(
300            "storage.limits.max_connections",
301            "must be between 1 and 16 in embedded mode",
302        ));
303    }
304    if !(1..=MAX_CONCURRENT_CONNECTION_CREATIONS).contains(&limits.concurrent_connection_creations)
305    {
306        errors.push(EmbeddedValidationError::new(
307            "storage.limits.concurrent_connection_creations",
308            "must be between 1 and 4 in embedded mode",
309        ));
310    }
311    if limits.concurrent_connection_creations > limits.max_connections {
312        errors.push(EmbeddedValidationError::new(
313            "storage.limits.concurrent_connection_creations",
314            "must not exceed max_connections",
315        ));
316    }
317    if !limits.connection_rate_per_second.is_finite()
318        || limits.connection_rate_per_second <= 0.0
319        || limits.connection_rate_per_second > MAX_CONNECTION_RATE_PER_SECOND
320    {
321        errors.push(EmbeddedValidationError::new(
322            "storage.limits.connection_rate_per_second",
323            "must be finite and between 0 and 16 in embedded mode",
324        ));
325    }
326    if !(1..=MAX_CONNECTION_BURST).contains(&limits.connection_burst) {
327        errors.push(EmbeddedValidationError::new(
328            "storage.limits.connection_burst",
329            "must be between 1 and 4 in embedded mode",
330        ));
331    }
332}
333
334#[cfg(test)]
335mod tests {
336    use proptest::prelude::*;
337
338    use super::*;
339
340    #[test]
341    fn absent_storage_defaults_only_to_in_memory() {
342        let decoded: EmbeddedEngineConfig =
343            toml::from_str("[server]\n").expect("embedded configuration with default storage");
344
345        assert_eq!(decoded.storage, EmbeddedStorageConfig::InMemory);
346        assert_eq!(decoded.startup_timeout_ms, DEFAULT_STARTUP_TIMEOUT_MS);
347        assert_eq!(decoded.effective_migration_policy(), None);
348        decoded.validate().expect("default embedded configuration");
349    }
350
351    #[test]
352    fn exact_limit_defaults_and_maxima_validate() {
353        assert_eq!(
354            EmbeddedDsqlLimits::default(),
355            EmbeddedDsqlLimits {
356                max_connections: 8,
357                concurrent_connection_creations: 2,
358                connection_rate_per_second: 8.0,
359                connection_burst: 2,
360            }
361        );
362
363        let mut config = managed_config();
364        config.storage = EmbeddedStorageConfig::ManagedDsql(ManagedEmbeddedDsqlConfig {
365            limits: EmbeddedDsqlLimits {
366                max_connections: 16,
367                concurrent_connection_creations: 4,
368                connection_rate_per_second: 16.0,
369                connection_burst: 4,
370            },
371            ..managed_dsql_config()
372        });
373        config.validate().expect("maximum embedded envelope");
374    }
375
376    #[test]
377    fn managed_mode_requires_intent_and_defaults_migration_after_validation() {
378        let missing_intent = r#"
379            [server]
380            [storage]
381            mode = "managed_dsql"
382            descriptor_path = "cluster.json"
383            region = "us-east-1"
384        "#;
385        assert!(toml::from_str::<EmbeddedEngineConfig>(missing_intent).is_err());
386
387        let config = managed_config();
388        config.validate().expect("managed configuration");
389        assert_eq!(
390            config.effective_migration_policy(),
391            Some(DsqlMigrationPolicy::Automatic)
392        );
393    }
394
395    #[test]
396    fn existing_mode_requires_identity_and_explicit_migration_policy() {
397        let missing_policy = r#"
398            [server]
399            [storage]
400            mode = "existing_dsql"
401            region = "us-east-1"
402            cluster_id = "abcdefghijklmnopqrstuvwx12"
403            cluster_arn = "arn:aws:dsql:us-east-1:123456789012:cluster/abcdefghijklmnopqrstuvwx12"
404            endpoint = "example.dsql.us-east-1.on.aws"
405        "#;
406        assert!(toml::from_str::<EmbeddedEngineConfig>(missing_policy).is_err());
407
408        let config = EmbeddedEngineConfig {
409            storage: EmbeddedStorageConfig::ExistingDsql(ExistingEmbeddedDsqlConfig {
410                region: String::new(),
411                cluster_id: String::new(),
412                cluster_arn: String::new(),
413                endpoint: String::new(),
414                migration_policy: DsqlMigrationPolicy::ValidateOnly,
415                limits: EmbeddedDsqlLimits::default(),
416            }),
417            ..EmbeddedEngineConfig::default()
418        };
419        let error = config.validate().expect_err("empty identity must fail");
420        let EmbeddedConfigError::Validation(errors) = error else {
421            panic!("expected embedded validation errors");
422        };
423        let fields = errors
424            .into_iter()
425            .map(|error| error.field)
426            .collect::<Vec<_>>();
427        assert!(fields.contains(&"storage.region".to_owned()));
428        assert!(fields.contains(&"storage.cluster_id".to_owned()));
429        assert!(fields.contains(&"storage.cluster_arn".to_owned()));
430        assert!(fields.contains(&"storage.endpoint".to_owned()));
431    }
432
433    #[test]
434    fn unknown_fields_are_rejected_at_every_embedded_level() {
435        for document in [
436            "[server]\nunknown = true\n",
437            "[server]\n[storage]\nmode = \"in_memory\"\nunknown = true\n",
438            concat!(
439                "[server]\n[storage]\nmode = \"managed_dsql\"\n",
440                "intent = \"create_or_recover\"\ndescriptor_path = \"cluster.json\"\n",
441                "region = \"us-east-1\"\nunknown = true\n"
442            ),
443        ] {
444            assert!(
445                toml::from_str::<EmbeddedEngineConfig>(document).is_err(),
446                "unknown field accepted in {document}"
447            );
448        }
449    }
450
451    #[test]
452    fn validation_errors_name_fields_without_echoing_values() {
453        let sensitive_region = "secret-region-canary";
454        let sensitive_path = PathBuf::from("");
455        let mut config = managed_config();
456        let EmbeddedStorageConfig::ManagedDsql(managed) = &mut config.storage else {
457            panic!("managed fixture");
458        };
459        managed.region = String::new();
460        managed.descriptor_path = sensitive_path;
461        let message = config
462            .validate()
463            .expect_err("invalid managed fields")
464            .to_string();
465        assert!(message.contains("storage.region"), "{message}");
466        assert!(message.contains("storage.descriptor_path"), "{message}");
467        assert!(!message.contains(sensitive_region), "{message}");
468    }
469
470    // Feature: managed-embedded-dsql, Property 1: embedded configuration is explicit and closed
471    proptest! {
472        #![proptest_config(ProptestConfig::with_cases(100))]
473
474        #[test]
475        fn property_embedded_configuration_is_explicit_and_closed(
476            mode in 0u8..3,
477            max_connections in 0usize..20,
478            concurrent_creations in 0usize..8,
479            rate in -2.0f64..20.0,
480            burst in 0u64..8,
481            include_managed_policy in any::<bool>(),
482        ) {
483            let limits = EmbeddedDsqlLimits {
484                max_connections,
485                concurrent_connection_creations: concurrent_creations,
486                connection_rate_per_second: rate,
487                connection_burst: burst,
488            };
489            let config = EmbeddedEngineConfig {
490                storage: match mode {
491                    0 => EmbeddedStorageConfig::InMemory,
492                    1 => EmbeddedStorageConfig::ManagedDsql(ManagedEmbeddedDsqlConfig {
493                        migration_policy: include_managed_policy
494                            .then_some(DsqlMigrationPolicy::ValidateOnly),
495                        limits: limits.clone(),
496                        ..managed_dsql_config()
497                    }),
498                    _ => EmbeddedStorageConfig::ExistingDsql(ExistingEmbeddedDsqlConfig {
499                        region: "us-east-1".to_owned(),
500                        cluster_id: "abcdefghijklmnopqrstuvwx12".to_owned(),
501                        cluster_arn: "arn:aws:dsql:us-east-1:123456789012:cluster/abcdefghijklmnopqrstuvwx12".to_owned(),
502                        endpoint: "example.dsql.us-east-1.on.aws".to_owned(),
503                        migration_policy: DsqlMigrationPolicy::ValidateOnly,
504                        limits: limits.clone(),
505                    }),
506                },
507                ..EmbeddedEngineConfig::default()
508            };
509
510            let encoded = toml::to_string(&config).expect("serialize embedded config");
511            let decoded: EmbeddedEngineConfig =
512                toml::from_str(&encoded).expect("deserialize embedded config");
513            prop_assert_eq!(&decoded, &config);
514            prop_assert_eq!(
515                std::mem::discriminant(&decoded.storage),
516                std::mem::discriminant(&config.storage),
517            );
518
519            let limits_valid = (1..=16).contains(&limits.max_connections)
520                && (1..=4).contains(&limits.concurrent_connection_creations)
521                && limits.concurrent_connection_creations <= limits.max_connections
522                && limits.connection_rate_per_second.is_finite()
523                && limits.connection_rate_per_second > 0.0
524                && limits.connection_rate_per_second <= 16.0
525                && (1..=4).contains(&limits.connection_burst);
526            let expected_valid = mode == 0 || limits_valid;
527            prop_assert_eq!(decoded.validate().is_ok(), expected_valid);
528
529            let expected_policy = match mode {
530                0 => None,
531                1 if include_managed_policy => Some(DsqlMigrationPolicy::ValidateOnly),
532                1 => Some(DsqlMigrationPolicy::Automatic),
533                _ => Some(DsqlMigrationPolicy::ValidateOnly),
534            };
535            prop_assert_eq!(decoded.effective_migration_policy(), expected_policy);
536        }
537    }
538
539    fn managed_config() -> EmbeddedEngineConfig {
540        EmbeddedEngineConfig {
541            storage: EmbeddedStorageConfig::ManagedDsql(managed_dsql_config()),
542            ..EmbeddedEngineConfig::default()
543        }
544    }
545
546    fn managed_dsql_config() -> ManagedEmbeddedDsqlConfig {
547        ManagedEmbeddedDsqlConfig {
548            intent: ManagedClusterIntent::CreateOrRecover,
549            descriptor_path: PathBuf::from("cluster.json"),
550            region: "us-east-1".to_owned(),
551            migration_policy: None,
552            limits: EmbeddedDsqlLimits::default(),
553            tags: BTreeMap::new(),
554        }
555    }
556}