reliar_outbox/

settings.rs

//! The outbox feature's settings, with an opt-in environment loader (ADR 0019).
//!
//! **The library never reads the environment implicitly.** No constructor, `Default` or builder
//! method touches [`std::env`] — only [`OutboxSettings::from_env`] does, and only when called.

use std::env::VarError;
use std::num::NonZeroU32;
use std::time::Duration;

use reliar_core::SettingsError;

use crate::retry::ExponentialBackoff;
use crate::worker::WorkerId;

/// The one settings struct for the outbox feature. Env prefix `RELIAR_OUTBOX_` by convention;
/// [`OutboxSettings::from_env`] takes whatever prefix the caller passes.
///
/// ```
/// use reliar_outbox::{DispatcherSettings, OutboxSettings};
///
/// let settings = OutboxSettings::default()
///     .dispatcher(DispatcherSettings::default().batch_size(50));
/// assert_eq!(settings.dispatcher.batch_size, 50);
/// ```
#[derive(Clone, Debug, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(default, deny_unknown_fields))]
#[non_exhaustive]
pub struct OutboxSettings {
    /// Worker-loop tunables.
    pub dispatcher: DispatcherSettings,

    /// Purge tunables.
    pub retention: RetentionSettings,
}

impl OutboxSettings {
    /// Sets [`Self::dispatcher`].
    ///
    /// ```
    /// use reliar_outbox::{DispatcherSettings, OutboxSettings};
    /// let settings = OutboxSettings::default().dispatcher(DispatcherSettings::default());
    /// assert_eq!(settings.dispatcher.batch_size, 100);
    /// ```
    #[must_use]
    pub fn dispatcher(mut self, dispatcher: DispatcherSettings) -> Self {
        self.dispatcher = dispatcher;

        self
    }

    /// Sets [`Self::retention`].
    ///
    /// ```
    /// use std::num::NonZeroU32;
    /// use reliar_outbox::{OutboxSettings, RetentionSettings};
    /// let batch_size = NonZeroU32::new(500).unwrap();
    /// let settings = OutboxSettings::default()
    ///     .retention(RetentionSettings::default().purge_batch_size(batch_size));
    /// assert_eq!(settings.retention.purge_batch_size, batch_size);
    /// ```
    #[must_use]
    pub fn retention(mut self, retention: RetentionSettings) -> Self {
        self.retention = retention;

        self
    }
}

/// Worker-loop tunables — the struct the outbox defaults table and the drain rule refer to.
///
/// ```
/// use reliar_outbox::DispatcherSettings;
/// use std::time::Duration;
///
/// let settings = DispatcherSettings::default().batch_size(50).lease(Duration::from_secs(60));
/// assert_eq!(settings.batch_size, 50);
/// assert_eq!(settings.lease, Duration::from_secs(60));
/// ```
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(default, deny_unknown_fields))]
#[non_exhaustive]
pub struct DispatcherSettings {
    /// The maximum number of rows one `acquire` **statement** claims. `BATCH_SIZE`. Default
    /// 100.
    ///
    /// **`max_in_flight` is the real ceiling on rows this worker holds leased at once —
    /// `batch_size` only caps a single claim.** The dispatcher claims only while
    /// `outstanding < max_in_flight`, asking for `min(batch_size, max_in_flight - outstanding)`,
    /// so the largest claim this dispatcher will ever issue is `min(batch_size, max_in_flight)`
    /// — the **effective batch**. With the accepted defaults (100 / 16) that is 16, so
    /// `batch_size` does not bind. Raise it only alongside `max_in_flight` if a single worker is
    /// meant to hold more rows leased at once.
    pub batch_size: u32,

    /// How long a claim holds the lease before it may be reclaimed. `LEASE_MS`. Default 30 s.
    #[cfg_attr(
        feature = "serde",
        serde(rename = "lease_ms", with = "reliar_core::serde_millis::millis")
    )]
    pub lease: Duration,

    /// The maximum number of publishes running concurrently — **the ceiling that actually
    /// binds**: every claim asks for at most this many rows, and every startup check that
    /// reasons about a claim's size (see [`Self::batch_size`]) is computed against it, not
    /// against `batch_size` alone. `MAX_IN_FLIGHT`. Default 16.
    pub max_in_flight: usize,

    /// How long one publish is allowed to run before it counts as a timeout (classified
    /// [`crate::FailureKind::Transient`]). `PUBLISH_TIMEOUT_MS`. Default 10 s. **Must be greater
    /// than zero** ([`crate::ConfigError::ZeroPublishTimeout`]) — a zero timeout would fail every
    /// publish before the publisher could ever run.
    #[cfg_attr(
        feature = "serde",
        serde(
            rename = "publish_timeout_ms",
            with = "reliar_core::serde_millis::millis"
        )
    )]
    pub publish_timeout: Duration,

    /// How long the loop waits after a claim that came back **partially filled** — the store
    /// had work, but less than this worker asked for (ADR 0039). A claim that fills its request
    /// (`records.len() == want`) is followed **immediately** by the next one, with no wait at
    /// all; an empty claim — including one made entirely of poisoned rows — waits
    /// [`Self::idle_poll_interval`] instead. `POLL_INTERVAL_MS`. Default 500 ms. **Must be
    /// greater than zero** ([`crate::ConfigError::ZeroPollInterval`]) — it also seeds the
    /// outcome-write retry pacing (`outcome_retry_interval`), so a zero value would re-enable a
    /// CPU-speed spin on both paths.
    #[cfg_attr(
        feature = "serde",
        serde(
            rename = "poll_interval_ms",
            with = "reliar_core::serde_millis::millis"
        )
    )]
    pub poll_interval: Duration,

    /// How often the loop polls once it has seen an empty claim (ADR 0039) — the only pacing
    /// left once a busy dispatcher no longer waits `poll_interval` between full claims. This
    /// bounds the worst-case pickup latency for a row enqueued while the worker is idle;
    /// lowering it is the supported way to cut that latency (this release has no
    /// `LISTEN/NOTIFY`). `IDLE_POLL_INTERVAL_MS`. Default 5 s. **Must be greater than zero**
    /// ([`crate::ConfigError::ZeroPollInterval`]) — a zero value would poll an idle store at CPU
    /// speed instead of backing off.
    #[cfg_attr(
        feature = "serde",
        serde(
            rename = "idle_poll_interval_ms",
            with = "reliar_core::serde_millis::millis"
        )
    )]
    pub idle_poll_interval: Duration,

    /// The maximum time `run()` spends draining in-flight publishes after cancellation.
    /// `DRAIN_TIMEOUT_MS`. Default 30 s.
    ///
    /// With the defaults, worst-case shutdown is roughly **`drain_timeout + store_timeout`**,
    /// not just `drain_timeout`: the drain loop itself is bounded by `drain_timeout`, and the one
    /// best-effort outcome-write attempt made right after it is separately bounded by
    /// `store_timeout` — the two budgets are not nested, they are sequential.
    #[cfg_attr(
        feature = "serde",
        serde(
            rename = "drain_timeout_ms",
            with = "reliar_core::serde_millis::millis"
        )
    )]
    pub drain_timeout: Duration,

    /// A client-side bound on **every** `OutboxStore` call `run` makes — without it a hung
    /// statement (a lost connection with no server-side `statement_timeout`, a saturated pool)
    /// makes `drain_timeout` unenforceable. A timeout is treated as a transient store error.
    ///
    /// **Must be greater than zero** ([`crate::ConfigError::ZeroStoreTimeout`]) — a zero timeout
    /// would fail every claim, outcome write, lease renewal and stats poll immediately.
    ///
    /// **Must be shorter than half the lease** (`store_timeout < lease / 2`,
    /// [`crate::ConfigError::StoreTimeoutTooLong`]): `run`'s outcome-write retry races the
    /// lease-renewal tick inside the same `select!`, so a `store_timeout` any longer could let
    /// one hung `complete`/`fail` attempt occupy an entire tick gap and starve renewal.
    /// `STORE_TIMEOUT_MS`. Default 10 s (comfortably under half the default 30 s lease's 15 s).
    #[cfg_attr(
        feature = "serde",
        serde(
            rename = "store_timeout_ms",
            with = "reliar_core::serde_millis::millis"
        )
    )]
    pub store_timeout: Duration,

    /// How often `stats()` is polled for the lag/dead-count gauges. `STATS_INTERVAL_MS`.
    /// Default 15 s.
    ///
    /// # Cost
    ///
    /// The poll is `O(claimable backlog)`, not `O(table)` — a host that lets the backlog reach
    /// millions of rows should raise this interval, or set it to [`Duration::ZERO`] to disable
    /// the tick entirely (opt-in gauges) and call [`crate::OutboxStore::stats`] on its own
    /// schedule instead.
    #[cfg_attr(
        feature = "serde",
        serde(
            rename = "stats_interval_ms",
            with = "reliar_core::serde_millis::millis"
        )
    )]
    pub stats_interval: Duration,

    /// The retry/backoff policy. `RETRY_BASE_MS`, `RETRY_MAX_DELAY_MS`,
    /// `RETRY_MAX_ATTEMPTS`, `RETRY_JITTER`.
    pub retry: ExponentialBackoff,

    /// Overrides the generated [`WorkerId`]. `WORKER_ID`. Default: generated.
    pub worker_id: Option<WorkerId>,
}

impl Default for DispatcherSettings {
    fn default() -> Self {
        Self {
            batch_size: 100,
            lease: Duration::from_secs(30),
            max_in_flight: 16,
            publish_timeout: Duration::from_secs(10),
            poll_interval: Duration::from_millis(500),
            idle_poll_interval: Duration::from_secs(5),
            drain_timeout: Duration::from_secs(30),
            store_timeout: Duration::from_secs(10),
            stats_interval: Duration::from_secs(15),
            retry: ExponentialBackoff::default(),
            worker_id: None,
        }
    }
}

impl DispatcherSettings {
    /// Sets [`Self::batch_size`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// assert_eq!(DispatcherSettings::default().batch_size(50).batch_size, 50);
    /// ```
    #[must_use]
    pub const fn batch_size(mut self, batch_size: u32) -> Self {
        self.batch_size = batch_size;

        self
    }

    /// Sets [`Self::lease`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// use std::time::Duration;
    /// let lease = Duration::from_secs(60);
    /// assert_eq!(DispatcherSettings::default().lease(lease).lease, lease);
    /// ```
    #[must_use]
    pub const fn lease(mut self, lease: Duration) -> Self {
        self.lease = lease;

        self
    }

    /// Sets [`Self::max_in_flight`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// assert_eq!(DispatcherSettings::default().max_in_flight(32).max_in_flight, 32);
    /// ```
    #[must_use]
    pub const fn max_in_flight(mut self, max_in_flight: usize) -> Self {
        self.max_in_flight = max_in_flight;

        self
    }

    /// Sets [`Self::publish_timeout`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// use std::time::Duration;
    /// let timeout = Duration::from_secs(5);
    /// assert_eq!(DispatcherSettings::default().publish_timeout(timeout).publish_timeout, timeout);
    /// ```
    #[must_use]
    pub const fn publish_timeout(mut self, publish_timeout: Duration) -> Self {
        self.publish_timeout = publish_timeout;

        self
    }

    /// Sets [`Self::poll_interval`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// use std::time::Duration;
    /// let interval = Duration::from_millis(200);
    /// assert_eq!(DispatcherSettings::default().poll_interval(interval).poll_interval, interval);
    /// ```
    #[must_use]
    pub const fn poll_interval(mut self, poll_interval: Duration) -> Self {
        self.poll_interval = poll_interval;

        self
    }

    /// Sets [`Self::idle_poll_interval`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// use std::time::Duration;
    /// let interval = Duration::from_secs(2);
    /// assert_eq!(
    ///     DispatcherSettings::default().idle_poll_interval(interval).idle_poll_interval,
    ///     interval
    /// );
    /// ```
    #[must_use]
    pub const fn idle_poll_interval(mut self, idle_poll_interval: Duration) -> Self {
        self.idle_poll_interval = idle_poll_interval;

        self
    }

    /// Sets [`Self::drain_timeout`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// use std::time::Duration;
    /// let timeout = Duration::from_secs(15);
    /// assert_eq!(DispatcherSettings::default().drain_timeout(timeout).drain_timeout, timeout);
    /// ```
    #[must_use]
    pub const fn drain_timeout(mut self, drain_timeout: Duration) -> Self {
        self.drain_timeout = drain_timeout;

        self
    }

    /// Sets [`Self::store_timeout`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// use std::time::Duration;
    /// let timeout = Duration::from_secs(3);
    /// assert_eq!(DispatcherSettings::default().store_timeout(timeout).store_timeout, timeout);
    /// ```
    #[must_use]
    pub const fn store_timeout(mut self, store_timeout: Duration) -> Self {
        self.store_timeout = store_timeout;

        self
    }

    /// Sets [`Self::stats_interval`].
    ///
    /// ```
    /// use reliar_outbox::DispatcherSettings;
    /// use std::time::Duration;
    /// assert_eq!(
    ///     DispatcherSettings::default().stats_interval(Duration::ZERO).stats_interval,
    ///     Duration::ZERO
    /// );
    /// ```
    #[must_use]
    pub const fn stats_interval(mut self, stats_interval: Duration) -> Self {
        self.stats_interval = stats_interval;

        self
    }

    /// Sets [`Self::retry`].
    ///
    /// ```
    /// use reliar_outbox::{DispatcherSettings, ExponentialBackoff};
    /// let retry = ExponentialBackoff::default().max_attempts(3);
    /// let settings = DispatcherSettings::default().retry(retry);
    /// assert_eq!(settings.retry.max_attempts, 3);
    /// ```
    #[must_use]
    pub const fn retry(mut self, retry: ExponentialBackoff) -> Self {
        self.retry = retry;

        self
    }

    /// Sets [`Self::worker_id`].
    ///
    /// ```
    /// use reliar_outbox::{DispatcherSettings, WorkerId};
    /// let worker = WorkerId::parse("worker-1").unwrap();
    /// let settings = DispatcherSettings::default().worker_id(worker.clone());
    /// assert_eq!(settings.worker_id, Some(worker));
    /// ```
    #[must_use]
    pub fn worker_id(mut self, worker_id: WorkerId) -> Self {
        self.worker_id = Some(worker_id);

        self
    }
}

/// Purge tunables.
///
/// ```
/// use reliar_outbox::RetentionSettings;
/// use std::time::Duration;
///
/// let settings = RetentionSettings::default().dead_retention(Some(Duration::from_secs(30 * 24 * 60 * 60)));
/// assert_eq!(settings.dead_retention, Some(Duration::from_secs(30 * 24 * 60 * 60)));
/// ```
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(default, deny_unknown_fields))]
#[non_exhaustive]
pub struct RetentionSettings {
    /// How long a published row is kept before `purge` deletes it. `PUBLISHED_RETENTION_MS`.
    /// Default 7 days.
    #[cfg_attr(
        feature = "serde",
        serde(
            rename = "published_retention_ms",
            with = "reliar_core::serde_millis::millis"
        )
    )]
    pub published_retention: Duration,

    /// How long a dead row is kept before `purge` deletes it. `None` keeps dead rows until an
    /// explicit purge. `DEAD_RETENTION_MS`. Default `None`.
    ///
    /// # Warning
    ///
    /// The default `None` means [`crate::PurgeRequest::from`] (built from these settings) also
    /// leaves `dead_retention` at `None` — a host that wants dead rows collected must set a
    /// value explicitly; deleting one is always a deliberate act.
    #[cfg_attr(
        feature = "serde",
        serde(
            rename = "dead_retention_ms",
            with = "reliar_core::serde_millis::optional_millis"
        )
    )]
    pub dead_retention: Option<Duration>,

    /// The maximum number of rows one purge pass deletes, per pass. `PURGE_BATCH_SIZE`.
    /// Default 1000. A `LIMIT 0` purge would delete nothing and could never make progress, so the
    /// type itself rules it out (ADR 0058 §2) — `NonZeroU32`'s own `Deserialize` rejects `0` with
    /// *invalid value: integer `0`, expected a nonzero u32*, and the JSON shape (a plain integer)
    /// is unchanged.
    pub purge_batch_size: NonZeroU32,
}

/// The default [`RetentionSettings::purge_batch_size`] (ADR 0058 §2).
const DEFAULT_PURGE_BATCH_SIZE: NonZeroU32 = NonZeroU32::new(1_000).unwrap();

impl Default for RetentionSettings {
    fn default() -> Self {
        Self {
            published_retention: Duration::from_secs(7 * 24 * 60 * 60),
            dead_retention: None,
            purge_batch_size: DEFAULT_PURGE_BATCH_SIZE,
        }
    }
}

impl RetentionSettings {
    /// Sets [`Self::published_retention`].
    ///
    /// ```
    /// use reliar_outbox::RetentionSettings;
    /// use std::time::Duration;
    /// let retention = Duration::from_secs(24 * 60 * 60);
    /// let settings = RetentionSettings::default().published_retention(retention);
    /// assert_eq!(settings.published_retention, retention);
    /// ```
    #[must_use]
    pub const fn published_retention(mut self, retention: Duration) -> Self {
        self.published_retention = retention;

        self
    }

    /// Sets [`Self::dead_retention`].
    ///
    /// ```
    /// use reliar_outbox::RetentionSettings;
    /// use std::time::Duration;
    /// let settings = RetentionSettings::default().dead_retention(Some(Duration::from_secs(60)));
    /// assert_eq!(settings.dead_retention, Some(Duration::from_secs(60)));
    /// ```
    #[must_use]
    pub const fn dead_retention(mut self, retention: Option<Duration>) -> Self {
        self.dead_retention = retention;

        self
    }

    /// Sets [`Self::purge_batch_size`].
    ///
    /// ```
    /// use std::num::NonZeroU32;
    /// use reliar_outbox::RetentionSettings;
    /// let batch_size = NonZeroU32::new(200).unwrap();
    /// assert_eq!(
    ///     RetentionSettings::default().purge_batch_size(batch_size).purge_batch_size,
    ///     batch_size
    /// );
    /// ```
    #[must_use]
    pub const fn purge_batch_size(mut self, purge_batch_size: NonZeroU32) -> Self {
        self.purge_batch_size = purge_batch_size;

        self
    }
}

impl OutboxSettings {
    /// Opt-in. Starts from [`Self::default`], overrides **only** the variables present under
    /// `prefix`, and returns `Err` for a present-but-unparseable or out-of-range value — never
    /// a silent fallback to the default. Env variable names are flat under `prefix` (e.g.
    /// `{prefix}LEASE_MS`), regardless of which nested settings struct they populate.
    ///
    /// # Errors
    ///
    /// Returns [`SettingsError::Parse`] for a present variable that cannot be parsed as its
    /// declared type (a bad UTF-8 value counts as unparseable), or
    /// [`SettingsError::OutOfRange`] for one that parses but violates a documented bound (a
    /// `RETRY_JITTER` outside `[0.0, 1.0)`, a `WORKER_ID` over its maximum length).
    ///
    /// ```
    /// use reliar_outbox::OutboxSettings;
    ///
    /// // A prefix with nothing set in the environment falls back to every documented default —
    /// // `from_env` never invents a value, it only overrides what is present.
    /// let settings = OutboxSettings::from_env("RELIAR_OUTBOX_DOCTEST_UNSET_").unwrap();
    /// assert_eq!(settings.dispatcher.batch_size, 100);
    /// ```
    pub fn from_env(prefix: &str) -> Result<Self, SettingsError> {
        let mut dispatcher = DispatcherSettings::default();
        let mut retention = RetentionSettings::default();

        if let Some(v) = env_u32(prefix, "BATCH_SIZE")? {
            dispatcher.batch_size = v;
        }

        if let Some(v) = env_duration_ms(prefix, "LEASE_MS")? {
            dispatcher.lease = v;
        }

        if let Some(v) = env_usize(prefix, "MAX_IN_FLIGHT")? {
            dispatcher.max_in_flight = v;
        }

        if let Some(v) = env_duration_ms(prefix, "PUBLISH_TIMEOUT_MS")? {
            dispatcher.publish_timeout = v;
        }

        if let Some(v) = env_duration_ms(prefix, "POLL_INTERVAL_MS")? {
            dispatcher.poll_interval = v;
        }

        if let Some(v) = env_duration_ms(prefix, "IDLE_POLL_INTERVAL_MS")? {
            dispatcher.idle_poll_interval = v;
        }

        if let Some(v) = env_duration_ms(prefix, "DRAIN_TIMEOUT_MS")? {
            dispatcher.drain_timeout = v;
        }

        if let Some(v) = env_duration_ms(prefix, "STORE_TIMEOUT_MS")? {
            dispatcher.store_timeout = v;
        }

        if let Some(v) = env_duration_ms(prefix, "STATS_INTERVAL_MS")? {
            dispatcher.stats_interval = v;
        }

        if let Some(v) = env_duration_ms(prefix, "RETRY_BASE_MS")? {
            dispatcher.retry.base = v;
        }

        if let Some(v) = env_duration_ms(prefix, "RETRY_MAX_DELAY_MS")? {
            dispatcher.retry.max_delay = v;
        }

        if let Some(v) = env_u32(prefix, "RETRY_MAX_ATTEMPTS")? {
            dispatcher.retry.max_attempts = v;
        }

        if let Some(v) = env_jitter(prefix, "RETRY_JITTER")? {
            dispatcher.retry.jitter = v;
        }

        if let Some(v) = env_worker_id(prefix, "WORKER_ID")? {
            dispatcher.worker_id = Some(v);
        }

        if let Some(v) = env_duration_ms(prefix, "PUBLISHED_RETENTION_MS")? {
            retention.published_retention = v;
        }

        if let Some(v) = env_duration_ms(prefix, "DEAD_RETENTION_MS")? {
            retention.dead_retention = Some(v);
        }

        if let Some(v) = env_u32(prefix, "PURGE_BATCH_SIZE")? {
            retention.purge_batch_size = NonZeroU32::new(v).ok_or_else(|| {
                SettingsError::out_of_range(
                    format!("{prefix}PURGE_BATCH_SIZE"),
                    "purge_batch_size must be greater than zero",
                )
            })?;
        }

        // The retired `{prefix}ENABLED` / `_ALLOWED_TYPES` / `_DISALLOWED_TYPES` keys are neither
        // read nor rejected here: an environment is an open namespace, so a retired-key deny-list
        // would be a permanent tax that could collide with a host's own variable (ADR 0036 §7).

        Ok(Self {
            dispatcher,
            retention,
        })
    }
}

/// Reads one raw environment variable under `prefix`. `Ok(None)` when absent; a present but
/// non-UTF-8 value is treated as unparseable rather than panicking or silently skipping it.
fn env_raw(prefix: &str, suffix: &str) -> Result<Option<String>, SettingsError> {
    let key = format!("{prefix}{suffix}");

    match std::env::var(&key) {
        Ok(value) => Ok(Some(value)),
        Err(VarError::NotPresent) => Ok(None),
        Err(VarError::NotUnicode(_)) => Err(SettingsError::parse(key, "a UTF-8 string")),
    }
}

fn env_u32(prefix: &str, suffix: &str) -> Result<Option<u32>, SettingsError> {
    let Some(raw) = env_raw(prefix, suffix)? else {
        return Ok(None);
    };

    raw.trim()
        .parse::<u32>()
        .map(Some)
        .map_err(|_| SettingsError::parse(format!("{prefix}{suffix}"), "u32"))
}

fn env_usize(prefix: &str, suffix: &str) -> Result<Option<usize>, SettingsError> {
    let Some(raw) = env_raw(prefix, suffix)? else {
        return Ok(None);
    };

    raw.trim()
        .parse::<usize>()
        .map(Some)
        .map_err(|_| SettingsError::parse(format!("{prefix}{suffix}"), "usize"))
}

fn env_duration_ms(prefix: &str, suffix: &str) -> Result<Option<Duration>, SettingsError> {
    let Some(raw) = env_raw(prefix, suffix)? else {
        return Ok(None);
    };
    let ms = raw
        .trim()
        .parse::<u64>()
        .map_err(|_| SettingsError::parse(format!("{prefix}{suffix}"), "milliseconds"))?;

    Ok(Some(Duration::from_millis(ms)))
}

fn env_jitter(prefix: &str, suffix: &str) -> Result<Option<f64>, SettingsError> {
    let Some(raw) = env_raw(prefix, suffix)? else {
        return Ok(None);
    };
    let key = format!("{prefix}{suffix}");
    let value = raw
        .trim()
        .parse::<f64>()
        .map_err(|_| SettingsError::parse(key.clone(), "f64"))?;

    if !(0.0..1.0).contains(&value) {
        return Err(SettingsError::out_of_range(
            key,
            "jitter must be in the range [0.0, 1.0)",
        ));
    }

    Ok(Some(value))
}

fn env_worker_id(prefix: &str, suffix: &str) -> Result<Option<WorkerId>, SettingsError> {
    let Some(raw) = env_raw(prefix, suffix)? else {
        return Ok(None);
    };
    let key = format!("{prefix}{suffix}");

    WorkerId::parse(raw).map(Some).map_err(|err| match err {
        reliar_core::IdError::TooLong { .. } => {
            SettingsError::out_of_range(key, "worker id exceeds the maximum length")
        }
        _ => SettingsError::parse(key, "worker id"),
    })
}