footing 0.1.12

Feature-gated foundations for Rust backend services
Documentation
use std::{
    collections::HashMap,
    fmt,
    sync::{
        Mutex,
        atomic::{AtomicU64, Ordering},
    },
    time::{Duration, Instant},
};

use async_trait::async_trait;
use thiserror::Error;

use crate::{
    clock::{SharedClock, system_clock},
    result::{ClassifyError, ErrorKind},
};

use super::config::{validate_lease_owner, validate_worker_name};
use super::{WorkerConfigError, WorkerLeaseConfig};

#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
/// Represents worker lease.
pub struct WorkerLease {
    worker: String,
    owner: String,
    token: u64,
    expires_at: Instant,
}

impl WorkerLease {
    /// Creates a new instance.
    pub fn new(
        worker: impl Into<String>,
        owner: impl Into<String>,
        token: u64,
        expires_at: Instant,
    ) -> Result<Self, WorkerLeaseError> {
        let worker = worker.into();
        let owner = owner.into();
        validate_worker_name(&worker).map_err(WorkerLeaseError::InvalidConfig)?;
        validate_lease_owner(&owner).map_err(WorkerLeaseError::InvalidConfig)?;
        Ok(Self::from_valid_parts(worker, owner, token, expires_at))
    }

    fn from_valid_parts(worker: String, owner: String, token: u64, expires_at: Instant) -> Self {
        Self {
            worker,
            owner,
            token,
            expires_at,
        }
    }

    #[must_use]
    /// Returns the worker.
    pub fn worker(&self) -> &str {
        &self.worker
    }

    #[must_use]
    /// Returns the owner.
    pub fn owner(&self) -> &str {
        &self.owner
    }

    #[must_use]
    /// Returns the token.
    pub const fn token(&self) -> u64 {
        self.token
    }

    #[must_use]
    /// Returns the expires at.
    pub const fn expires_at(&self) -> Instant {
        self.expires_at
    }

    #[must_use]
    /// Returns whether the lease is inside its pre-expiry renewal window.
    pub fn should_renew(&self, now: Instant, renew_before: Duration) -> bool {
        now.checked_add(renew_before)
            .is_none_or(|renew_at| renew_at >= self.expires_at)
    }
}

#[derive(Error)]
#[non_exhaustive]
/// Errors that can occur while handling worker lease.
pub enum WorkerLeaseError {
    #[error("worker lease store lock is poisoned")]
    /// Indicates lock poisoned.
    LockPoisoned,
    #[error("invalid worker lease configuration")]
    /// The config is invalid.
    InvalidConfig(#[from] WorkerConfigError),
    #[error("worker lease store is unavailable")]
    /// An external lease backend failed; the original cause is retained.
    Store(#[source] crate::result::BoxError),
}

impl fmt::Debug for WorkerLeaseError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::LockPoisoned => formatter.write_str("LockPoisoned"),
            Self::InvalidConfig(error) => {
                formatter.debug_tuple("InvalidConfig").field(error).finish()
            }
            Self::Store(_) => formatter.debug_tuple("Store").field(&"[REDACTED]").finish(),
        }
    }
}

impl ClassifyError for WorkerLeaseError {
    fn error_kind(&self) -> ErrorKind {
        match self {
            Self::LockPoisoned | Self::Store(_) => ErrorKind::Unavailable,
            Self::InvalidConfig(source) => source.error_kind(),
        }
    }

    fn error_code(&self) -> crate::result::ErrorCode {
        match self {
            Self::LockPoisoned | Self::Store(_) => {
                crate::result::ErrorCode::internal("worker_lease_unavailable")
            }
            Self::InvalidConfig(source) => source.error_code(),
        }
    }
}

#[async_trait]
/// Storage abstraction for worker leases.
///
/// Implementations must make every method cancellation-safe because the worker
/// runtime drops acquire/renew futures at their configured operation deadline or
/// during shutdown. Every new acquisition must issue a fencing token greater
/// than all tokens previously issued for that worker. Renewal must preserve the
/// current token, and both renewal and release must condition mutations on the
/// exact owner and token.
///
/// A lease only coordinates scheduling. It cannot revoke an already-running
/// external side effect, so workers remain at-least-once and must use idempotency
/// keys or propagate the fencing token to protected resources.
pub trait WorkerLeaseStore: Send + Sync + 'static {
    /// Attempts to acquire a worker lease using a fresh fencing token.
    async fn try_acquire(
        &self,
        worker: &str,
        owner: &str,
        config: WorkerLeaseConfig,
    ) -> Result<Option<WorkerLease>, WorkerLeaseError>;

    /// Renews only the exact unexpired owner/token pair.
    async fn renew(
        &self,
        lease: &WorkerLease,
        config: WorkerLeaseConfig,
    ) -> Result<Option<WorkerLease>, WorkerLeaseError>;

    /// Releases a lease if the exact owner/token pair is still current.
    async fn release(&self, lease: &WorkerLease) -> Result<(), WorkerLeaseError>;
}

#[non_exhaustive]
/// Storage abstraction for local worker lease.
pub struct LocalWorkerLeaseStore {
    leases: Mutex<HashMap<String, WorkerLease>>,
    clock: SharedClock,
    next_token: AtomicU64,
}

impl LocalWorkerLeaseStore {
    #[must_use]
    /// Creates a new instance.
    pub fn new() -> Self {
        Self::with_clock(system_clock())
    }

    #[must_use]
    /// Configures clock and returns the updated value.
    pub fn with_clock(clock: SharedClock) -> Self {
        Self {
            leases: Mutex::new(HashMap::new()),
            clock,
            next_token: AtomicU64::new(1),
        }
    }

    #[must_use]
    /// Returns the clock.
    pub fn clock(&self) -> &SharedClock {
        &self.clock
    }

    fn next_token(&self) -> u64 {
        self.next_token.fetch_add(1, Ordering::Relaxed)
    }
}

impl fmt::Debug for LocalWorkerLeaseStore {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let lease_count = self.leases.lock().map(|leases| leases.len()).ok();
        formatter
            .debug_struct("LocalWorkerLeaseStore")
            .field("lease_count", &lease_count)
            .finish_non_exhaustive()
    }
}

impl Default for LocalWorkerLeaseStore {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl WorkerLeaseStore for LocalWorkerLeaseStore {
    async fn try_acquire(
        &self,
        worker: &str,
        owner: &str,
        config: WorkerLeaseConfig,
    ) -> Result<Option<WorkerLease>, WorkerLeaseError> {
        validate_worker_name(worker)?;
        validate_lease_owner(owner)?;

        let now = self.clock.now();
        let expires_at = worker_lease_expiry_after(now, config.lease_duration)?;
        let mut leases = self
            .leases
            .lock()
            .map_err(|_| WorkerLeaseError::LockPoisoned)?;

        // Acquisition creates a new fencing token. Even the same owner must use
        // `renew` while its current lease is live so concurrent tasks sharing an
        // owner cannot silently invalidate one another's token.
        if let Some(existing) = leases.get(worker)
            && existing.expires_at > now
        {
            return Ok(None);
        }

        let lease = WorkerLease::from_valid_parts(
            worker.trim().to_owned(),
            owner.trim().to_owned(),
            self.next_token(),
            expires_at,
        );
        leases.insert(worker.to_owned(), lease.clone());
        Ok(Some(lease))
    }

    async fn renew(
        &self,
        lease: &WorkerLease,
        config: WorkerLeaseConfig,
    ) -> Result<Option<WorkerLease>, WorkerLeaseError> {
        validate_worker_name(lease.worker())?;
        validate_lease_owner(lease.owner())?;

        let now = self.clock.now();
        let expires_at = worker_lease_expiry_after(now, config.lease_duration)?;
        let mut leases = self
            .leases
            .lock()
            .map_err(|_| WorkerLeaseError::LockPoisoned)?;

        let Some(existing) = leases.get_mut(lease.worker()) else {
            return Ok(None);
        };

        if existing.owner != lease.owner
            || existing.token != lease.token
            || existing.expires_at <= now
        {
            return Ok(None);
        }

        existing.expires_at = expires_at;
        Ok(Some(existing.clone()))
    }

    async fn release(&self, lease: &WorkerLease) -> Result<(), WorkerLeaseError> {
        let mut leases = self
            .leases
            .lock()
            .map_err(|_| WorkerLeaseError::LockPoisoned)?;

        if let Some(existing) = leases.get(lease.worker())
            && existing.owner == lease.owner
            && existing.token == lease.token
        {
            leases.remove(lease.worker());
        }

        Ok(())
    }
}

fn worker_lease_expiry_after(
    now: Instant,
    lease_duration: Duration,
) -> Result<Instant, WorkerLeaseError> {
    now.checked_add(lease_duration)
        .ok_or(WorkerLeaseError::InvalidConfig(
            WorkerConfigError::InvalidLeaseDuration,
        ))
}