v0.3.11-pre.003

crates/ksp-worker-raw-transaction-ingest-lib/src/settings.rs

@@ -0,0 +1,127 @@
+// file: crates/ksp-worker-raw-transaction-ingest-lib/src/settings.rs
+// version: 3
+
+/// Default bounded admission queue capacity for one RAW transaction ingest Worker.
+pub const DEFAULT_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY: usize = 256;
+/// Default number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub const DEFAULT_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY: usize = 8;
+/// Default cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub const DEFAULT_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
+/// Maximum bounded admission queue capacity for one RAW transaction ingest Worker.
+pub const MAX_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY: usize = 65_536;
+/// Maximum number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub const MAX_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY: usize = 64;
+/// Maximum cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub const MAX_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+/// Minimum bounded admission queue capacity for one RAW transaction ingest Worker.
+pub const MIN_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY: usize = 1;
+/// Minimum number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub const MIN_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY: usize = 1;
+/// Minimum cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub const MIN_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_millis(100);
+
+/// Validated source-neutral runtime settings for one continuous RAW transaction ingest Worker.
+#[derive(Clone, Eq, PartialEq)]
+pub struct RawTransactionIngestSettings {
+    network: ksp_store_lib::RawNetworkId,
+    worker_id: ksp_worker_api::WorkerId,
+    admission_queue_capacity: usize,
+    persistence_concurrency: usize,
+    shutdown_drain_timeout: std::time::Duration,
+}
+
+impl crate::RawTransactionIngestSettings {
+    /// Creates settings from validated network/Worker identities and explicit bounded runtime limits.
+    pub fn new(
+        network: ksp_store_lib::RawNetworkId,
+        worker_id: ksp_worker_api::WorkerId,
+        admission_queue_capacity: usize,
+        persistence_concurrency: usize,
+        shutdown_drain_timeout: std::time::Duration,
+    ) -> ksp_core_lib::Result<Self> {
+        validate_inclusive_usize(
+            admission_queue_capacity,
+            crate::MIN_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY,
+            crate::MAX_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY,
+            "admission_queue_capacity",
+        )?;
+        validate_inclusive_usize(
+            persistence_concurrency,
+            crate::MIN_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
+            crate::MAX_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
+            "persistence_concurrency",
+        )?;
+        if !(crate::MIN_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT..=crate::MAX_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT)
+            .contains(&shutdown_drain_timeout)
+        {
+            return std::result::Result::Err(crate::settings_error("shutdown_drain_timeout"));
+        }
+        return std::result::Result::Ok(Self { network, worker_id, admission_queue_capacity, persistence_concurrency, shutdown_drain_timeout });
+    }
+
+    /// Creates settings using the stable V1 runtime defaults for one validated network and Worker identity.
+    #[must_use]
+    pub fn with_defaults(network: ksp_store_lib::RawNetworkId, worker_id: ksp_worker_api::WorkerId) -> Self {
+        return Self {
+            network,
+            worker_id,
+            admission_queue_capacity: crate::DEFAULT_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY,
+            persistence_concurrency: crate::DEFAULT_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
+            shutdown_drain_timeout: crate::DEFAULT_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT,
+        };
+    }
+
+    /// Returns the Store-compatible logical network binding.
+    #[must_use]
+    pub const fn network(&self) -> &ksp_store_lib::RawNetworkId {
+        return &self.network;
+    }
+
+    /// Returns the validated logical identity of this Worker instance.
+    #[must_use]
+    pub const fn worker_id(&self) -> &ksp_worker_api::WorkerId {
+        return &self.worker_id;
+    }
+
+    /// Returns the bounded central admission queue capacity.
+    #[must_use]
+    pub const fn admission_queue_capacity(&self) -> usize {
+        return self.admission_queue_capacity;
+    }
+
+    /// Returns the bounded maximum number of concurrent Store persistence operations.
+    #[must_use]
+    pub const fn persistence_concurrency(&self) -> usize {
+        return self.persistence_concurrency;
+    }
+
+    /// Returns the bounded cooperative shutdown drain deadline.
+    #[must_use]
+    pub const fn shutdown_drain_timeout(&self) -> std::time::Duration {
+        return self.shutdown_drain_timeout;
+    }
+}
+
+impl std::fmt::Debug for crate::RawTransactionIngestSettings {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter
+            .debug_struct("RawTransactionIngestSettings")
+            .field("network", &self.network)
+            .field("worker_id", &self.worker_id)
+            .field("admission_queue_capacity", &self.admission_queue_capacity)
+            .field("persistence_concurrency", &self.persistence_concurrency)
+            .field("shutdown_drain_timeout", &self.shutdown_drain_timeout)
+            .finish();
+    }
+}
+
+fn validate_inclusive_usize(value: usize, minimum: usize, maximum: usize, field: &'static str) -> ksp_core_lib::Result<()> {
+    if !(minimum..=maximum).contains(&value) {
+        return std::result::Result::Err(crate::settings_error(field));
+    }
+    return std::result::Result::Ok(());
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/settings.rs"]
+mod tests;