footing 0.1.4

Feature-gated foundations for Rust backend services
Documentation
use std::{marker::PhantomData, time::Instant};

use async_trait::async_trait;
use tokio::time;

use super::super::{BoxWorkerError, Worker, WorkerTick};
use super::{
    BatchRunSummary, BatchWorkerJob, OutboxClaim, OutboxHandler, OutboxItem, OutboxItemState,
    OutboxRetryPolicy, OutboxStore, OutboxWorkerConfig,
};

/// Generic outbox batch job that can be wrapped in [`BatchWorker`].
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct OutboxJob<S, H, I> {
    name: String,
    store: S,
    handler: H,
    config: OutboxWorkerConfig,
    _item: PhantomData<I>,
}

impl<S, H, I> OutboxJob<S, H, I>
where
    I: OutboxItem,
{
    #[must_use]
    /// Creates a new instance.
    pub fn new(name: impl Into<String>, store: S, handler: H, config: OutboxWorkerConfig) -> Self {
        Self {
            name: name.into(),
            store,
            handler,
            config,
            _item: PhantomData,
        }
    }

    #[must_use]
    /// Configures config and returns the updated value.
    pub fn with_config(mut self, config: OutboxWorkerConfig) -> Self {
        self.config = config;
        self
    }

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

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

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

#[async_trait]
impl<S, H, I> BatchWorkerJob for OutboxJob<S, H, I>
where
    S: OutboxStore<I>,
    H: OutboxHandler<I>,
    I: OutboxItem,
{
    fn name(&self) -> &str {
        &self.name
    }

    async fn run_batch(&self) -> Result<BatchRunSummary, BoxWorkerError> {
        let claim = OutboxClaim::new(self.config.batch_size(), self.config.lease_duration());
        let items = self.store.claim_due(claim).await?;
        let mut summary = BatchRunSummary::new().with_claimed(items.len() as u64);
        let batch_started_at = Instant::now();

        for item in items {
            if let Some(batch_timeout) = self.config.batch_timeout()
                && batch_started_at.elapsed() >= batch_timeout
            {
                summary.record_batch_timeout();
                break;
            }

            let state = handle_outbox_item(&self.handler, &item, self.config).await;

            if self.store.record_state(&item, state.clone()).await.is_err() {
                summary.record_state_error();
                tracing::warn!(
                    worker = self.name(),
                    item_id = item.outbox_id(),
                    state = state.as_str(),
                    "outbox state update failed"
                );
                continue;
            }

            summary.record_item_state(&state);

            if let OutboxItemState::Failed { reason } = &state {
                match self.store.record_dead_letter(&item, reason).await {
                    Ok(()) => {
                        summary.record_dead_letter();
                    }
                    Err(_) => {
                        summary.record_dead_letter_error();
                        tracing::warn!(
                            worker = self.name(),
                            item_id = item.outbox_id(),
                            "outbox dead-letter hook failed"
                        );
                    }
                }
            }
        }

        Ok(summary)
    }
}

/// Worker adapter for outbox-like batch jobs.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct BatchWorker<J> {
    job: J,
    log_empty_batches: bool,
}

impl<J> BatchWorker<J> {
    #[must_use]
    /// Creates a new instance.
    pub const fn new(job: J) -> Self {
        Self {
            job,
            log_empty_batches: false,
        }
    }

    #[must_use]
    /// Configures empty batch logging and returns the updated value.
    pub const fn with_empty_batch_logging(mut self, enabled: bool) -> Self {
        self.log_empty_batches = enabled;
        self
    }

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

#[async_trait]
impl<J> Worker for BatchWorker<J>
where
    J: BatchWorkerJob,
{
    fn name(&self) -> &str {
        self.job.name()
    }

    async fn run_once(&self) -> Result<WorkerTick, BoxWorkerError> {
        let summary = self.job.run_batch().await?;
        if self.log_empty_batches || !summary.empty() {
            tracing::info!(
                worker = self.name(),
                claimed = summary.claimed(),
                succeeded = summary.succeeded(),
                retrying = summary.retrying(),
                failed = summary.failed(),
                skipped = summary.skipped(),
                dead_lettered = summary.dead_lettered(),
                state_errors = summary.state_errors(),
                dead_letter_errors = summary.dead_letter_errors(),
                batch_timed_out = summary.batch_timed_out(),
                handled = summary.handled(),
                "batch worker completed"
            );
        }

        let mut tick = WorkerTick::new(summary.handled());
        if let Some(delay) = summary.next_delay() {
            tick = tick.with_next_delay(delay);
        }
        Ok(tick)
    }
}

fn retry_or_fail_state(
    retry_policy: &OutboxRetryPolicy,
    prior_attempts: u32,
    reason: String,
) -> OutboxItemState {
    let attempts_after_current_try = prior_attempts.saturating_add(1);
    if retry_policy.should_retry(attempts_after_current_try) {
        OutboxItemState::retry(
            reason,
            retry_policy.delay_for_attempts(attempts_after_current_try),
        )
    } else {
        OutboxItemState::failed(reason)
    }
}

async fn handle_outbox_item<H, I>(
    handler: &H,
    item: &I,
    config: OutboxWorkerConfig,
) -> OutboxItemState
where
    H: OutboxHandler<I>,
    I: OutboxItem,
{
    let result = if let Some(timeout) = config.item_timeout() {
        match time::timeout(timeout, handler.handle(item)).await {
            Ok(result) => result,
            Err(_) => Err(format!("outbox item processing timed out after {timeout:?}").into()),
        }
    } else {
        handler.handle(item).await
    };

    match result {
        Ok(state) => state,
        Err(error) => retry_or_fail_state(
            &config.retry_policy(),
            item.outbox_attempts(),
            error.to_string(),
        ),
    }
}