footing 0.1.19

Feature-gated foundations for Rust backend services
Documentation
//! Small worker runtime primitives.
//!
//! Applications provide job acquisition and processing through [`Worker`].
//! Configuration, outbox processing, leasing, and loop orchestration live in
//! focused private modules and are re-exported as one feature-gated API.
//!
//! ```rust
//! use std::time::Duration;
//! use footing::worker::{BackoffConfig, RetryBackoff};
//!
//! let mut backoff = RetryBackoff::new(BackoffConfig::default());
//! assert_eq!(backoff.record_failure(), Duration::from_secs(1));
//! backoff.reset();
//! ```
//!
//! Queue jobs choose [`WorkerSchedule::Continue`] when another batch may be
//! ready, or [`WorkerSchedule::WaitForWork`] when idle. Ordinary workers keep
//! polling unless they explicitly choose a different schedule. Scheduling never
//! infers backlog from processed counts, and failure backoff cannot be woken.
//!
//! For the built-in outbox adapter, opt in with [`OutboxJob::with_queue_scheduling`]:
//!
//! ```no_run
//! use footing::worker::{
//!     BatchWorker, OutboxHandler, OutboxItem, OutboxJob, OutboxStore,
//!     ShutdownToken, WorkerConfig, WorkerRunError, WorkerRunOptions, WorkerWakeup,
//!     run_worker_until_shutdown_with_options,
//! };
//!
//! async fn serve_queue<S, H, I>(
//!     job: OutboxJob<S, H, I>,
//!     wakeup: WorkerWakeup,
//!     shutdown: ShutdownToken,
//! ) -> Result<(), WorkerRunError>
//! where
//!     S: OutboxStore<I>,
//!     H: OutboxHandler<I>,
//!     I: OutboxItem,
//! {
//!     // Enqueue producers retain a clone and call notify() after commit.
//!     let options = WorkerRunOptions::new().with_wakeup(wakeup);
//!     let worker = BatchWorker::new(job.with_queue_scheduling());
//!     run_worker_until_shutdown_with_options(
//!         worker, WorkerConfig::default(), shutdown, options,
//!     ).await?;
//!     Ok(())
//! }
//! ```
//!
//! Notifications are hints to check durable storage. Stores must enforce due
//! times and claims even when a notification arrives early. A new runner checks
//! the queue after its startup delay; idle polling also covers lost notifications
//! and retries outside the last batch. External listeners should subscribe before
//! checking existing work and repeat that check after reconnecting.

use std::error::Error;

use async_trait::async_trait;

mod config;
mod lease;
mod outbox;
mod runner;
mod schedule;

pub use config::{BackoffConfig, RetryBackoff, WorkerConfig, WorkerConfigError, WorkerLeaseConfig};
pub use config::{BackoffSettings, WorkerLeaseSettings, WorkerSettings};
pub use lease::{LocalWorkerLeaseStore, WorkerLease, WorkerLeaseError, WorkerLeaseStore};
pub use outbox::OutboxWorkerSettings;
pub use outbox::{
    BatchRunSummary, BatchWorker, BatchWorkerJob, OutboxBatchError, OutboxClaim,
    OutboxFailureClass, OutboxHandler, OutboxItem, OutboxItemState, OutboxJob, OutboxRetryPolicy,
    OutboxStore, OutboxWorkerConfig,
};
pub use runner::{
    ShutdownToken, ShutdownTrigger, WorkerRunError, WorkerRunOptions, WorkerRunState,
    WorkerRunSummary, WorkerTick, WorkerTickOutcome, run_worker_until_shutdown,
    run_worker_until_shutdown_with_metrics, run_worker_until_shutdown_with_options,
    shutdown_channel,
};
pub use schedule::{WorkerSchedule, WorkerWakeup};

/// Boxed worker errors used by the generic worker trait.
pub type BoxWorkerError = Box<dyn Error + Send + Sync + 'static>;

/// Maximum supported worker name length.
pub const MAX_WORKER_NAME_LENGTH: usize = 128;
/// Maximum supported worker lease owner length.
pub const MAX_WORKER_LEASE_OWNER_LENGTH: usize = 128;

/// One unit of repeatable background work.
///
/// Execution is at-least-once. A tick may be cancelled during shutdown or
/// repeated after an ambiguous failure or lease loss. Implementations must be
/// cancellation-safe and make externally visible effects idempotent. A worker
/// lease coordinates runners but cannot fence effects unless the application
/// propagates and enforces its fencing token at the protected resource.
#[async_trait]
pub trait Worker: Send + Sync + 'static {
    /// Human-readable worker name used in logs and metrics.
    fn name(&self) -> &str;

    /// Runs one worker tick.
    async fn run_once(&self) -> Result<WorkerTick, BoxWorkerError>;
}

#[cfg(test)]
use runner::ensure_worker_lease;
#[cfg(test)]
mod schedule_tests;
#[cfg(test)]
mod tests;