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

// file: crates/ksp-worker-raw-transaction-ingest-lib/src/settings.rs
// version: 5

/// 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(10);
/// 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> {
        if let std::result::Result::Err(error) = 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",
        ) {
            return std::result::Result::Err(error);
        }
        if let std::result::Result::Err(error) = validate_inclusive_usize(
            persistence_concurrency,
            crate::MIN_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
            crate::MAX_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
            "persistence_concurrency",
        ) {
            return std::result::Result::Err(error);
        }
        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;