1use 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#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
29#[serde(deny_unknown_fields)]
30pub struct EmbeddedEngineConfig {
31 pub server: TokeiraConfig,
33 #[serde(default)]
35 pub storage: EmbeddedStorageConfig,
36 #[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 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 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#[derive(Clone, Debug, Default, PartialEq, Serialize)]
115#[serde(tag = "mode", rename_all = "snake_case")]
116pub enum EmbeddedStorageConfig {
117 #[default]
119 InMemory,
120 ManagedDsql(ManagedEmbeddedDsqlConfig),
122 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#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
164#[serde(deny_unknown_fields)]
165pub struct ManagedEmbeddedDsqlConfig {
166 pub intent: ManagedClusterIntent,
168 pub descriptor_path: PathBuf,
170 pub region: String,
172 #[serde(default)]
174 pub migration_policy: Option<DsqlMigrationPolicy>,
175 #[serde(default)]
177 pub limits: EmbeddedDsqlLimits,
178 #[serde(default)]
180 pub tags: BTreeMap<String, String>,
181}
182
183#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
185#[serde(rename_all = "snake_case")]
186pub enum ManagedClusterIntent {
187 CreateOrRecover,
189}
190
191#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
193#[serde(deny_unknown_fields)]
194pub struct ExistingEmbeddedDsqlConfig {
195 pub region: String,
197 pub cluster_id: String,
199 pub cluster_arn: String,
201 pub endpoint: String,
209 pub migration_policy: DsqlMigrationPolicy,
211 #[serde(default)]
213 pub limits: EmbeddedDsqlLimits,
214}
215
216#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
218#[serde(rename_all = "snake_case")]
219pub enum DsqlMigrationPolicy {
220 Automatic,
222 ValidateOnly,
224}
225
226#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
228#[serde(deny_unknown_fields)]
229pub struct EmbeddedDsqlLimits {
230 pub max_connections: usize,
232 pub concurrent_connection_creations: usize,
234 pub connection_rate_per_second: f64,
236 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#[derive(Debug, Error)]
253pub enum EmbeddedConfigError {
254 #[error("embedded server configuration is invalid: {0}")]
256 Server(#[source] ConfigError),
257 #[error("embedded configuration validation failed:\n{}", .0.iter().map(ToString::to_string).collect::<Vec<_>>().join("\n"))]
259 Validation(Vec<EmbeddedValidationError>),
260}
261
262#[derive(Clone, Debug, Error, PartialEq, Eq)]
264#[error("{field}: {message}")]
265pub struct EmbeddedValidationError {
266 pub field: String,
268 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 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}