footing 0.1.19

Feature-gated foundations for Rust backend services
Documentation
//! Bounded in-memory idempotency storage.

use std::{
    collections::HashMap,
    fmt,
    sync::{Arc, Mutex},
    time::{Duration, Instant},
};

use async_trait::async_trait;

use crate::clock::{SharedClock, system_clock};

use super::model::{
    DEFAULT_MAX_IDEMPOTENCY_RECORDS, DEFAULT_MAX_IDEMPOTENCY_STORED_HEADER_BYTES,
    DEFAULT_MAX_IDEMPOTENCY_STORED_RESPONSE_BYTES, IdempotencyKey, IdempotencyLease,
    IdempotencyRequestHash, IdempotencyReservation, IdempotencyStore, IdempotencyStoreError,
    StoredIdempotencyResponse,
};

#[derive(Debug, Clone)]
pub(super) struct IdempotencyEntry {
    pub(super) request_hash: IdempotencyRequestHash,
    pub(super) state: EntryState,
    pub(super) expires_at: Instant,
}

#[derive(Debug, Clone)]
pub(super) enum EntryState {
    Processing {
        lease: IdempotencyLease,
        reserved_response_bytes: usize,
    },
    Completed(StoredIdempotencyResponse),
}

#[derive(Clone)]
#[non_exhaustive]
/// Storage abstraction for memory idempotency.
pub struct MemoryIdempotencyStore {
    pub(super) state: Arc<Mutex<MemoryIdempotencyState>>,
    clock: SharedClock,
    max_records: usize,
    max_stored_response_bytes: usize,
    pub(super) max_response_bytes_per_record: usize,
}

#[derive(Debug, Default)]
pub(super) struct MemoryIdempotencyState {
    pub(super) records: HashMap<IdempotencyKey, IdempotencyEntry>,
    pub(super) stored_response_bytes: usize,
    pub(super) reserved_response_bytes: usize,
}

impl MemoryIdempotencyStore {
    #[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 {
            state: Arc::new(Mutex::new(MemoryIdempotencyState::default())),
            clock,
            max_records: DEFAULT_MAX_IDEMPOTENCY_RECORDS,
            max_stored_response_bytes: DEFAULT_MAX_IDEMPOTENCY_STORED_RESPONSE_BYTES,
            max_response_bytes_per_record: DEFAULT_MAX_IDEMPOTENCY_STORED_RESPONSE_BYTES,
        }
    }

    /// Creates for response body limit.
    pub fn for_response_body_limit(
        max_response_body_bytes: usize,
    ) -> Result<Self, IdempotencyStoreError> {
        if max_response_body_bytes == 0 {
            return Err(IdempotencyStoreError::InvalidCapacity);
        }
        let per_record_bytes = max_response_body_bytes
            .checked_add(DEFAULT_MAX_IDEMPOTENCY_STORED_HEADER_BYTES)
            .ok_or(IdempotencyStoreError::InvalidCapacity)?;
        if per_record_bytes == 0 || per_record_bytes > DEFAULT_MAX_IDEMPOTENCY_STORED_RESPONSE_BYTES
        {
            return Err(IdempotencyStoreError::InvalidCapacity);
        }
        Self::with_clock_and_limits_and_reservation(
            system_clock(),
            DEFAULT_MAX_IDEMPOTENCY_RECORDS,
            DEFAULT_MAX_IDEMPOTENCY_STORED_RESPONSE_BYTES,
            per_record_bytes,
        )
    }

    /// Configures clock and maximum records and returns the updated value.
    pub fn with_clock_and_max_records(
        clock: SharedClock,
        max_records: usize,
    ) -> Result<Self, IdempotencyStoreError> {
        if max_records == 0 {
            return Err(IdempotencyStoreError::InvalidCapacity);
        }
        Self::with_clock_and_limits(
            clock,
            max_records,
            DEFAULT_MAX_IDEMPOTENCY_STORED_RESPONSE_BYTES,
        )
    }

    pub(super) fn with_clock_and_limits(
        clock: SharedClock,
        max_records: usize,
        max_stored_response_bytes: usize,
    ) -> Result<Self, IdempotencyStoreError> {
        Self::with_clock_and_limits_and_reservation(
            clock,
            max_records,
            max_stored_response_bytes,
            max_stored_response_bytes,
        )
    }

    pub(super) fn with_clock_and_limits_and_reservation(
        clock: SharedClock,
        max_records: usize,
        max_stored_response_bytes: usize,
        max_response_bytes_per_record: usize,
    ) -> Result<Self, IdempotencyStoreError> {
        if max_records == 0
            || max_stored_response_bytes == 0
            || max_response_bytes_per_record == 0
            || max_response_bytes_per_record > max_stored_response_bytes
        {
            return Err(IdempotencyStoreError::InvalidCapacity);
        }
        Ok(Self {
            state: Arc::new(Mutex::new(MemoryIdempotencyState::default())),
            clock,
            max_records,
            max_stored_response_bytes,
            max_response_bytes_per_record,
        })
    }

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

    #[must_use]
    /// Returns the maximum records.
    pub const fn max_records(&self) -> usize {
        self.max_records
    }

    #[must_use]
    /// Returns the maximum stored response bytes.
    pub const fn max_stored_response_bytes(&self) -> usize {
        self.max_stored_response_bytes
    }

    /// Records count.
    pub fn record_count(&self) -> Result<usize, IdempotencyStoreError> {
        self.state
            .lock()
            .map(|state| state.records.len())
            .map_err(|_| IdempotencyStoreError::LockPoisoned)
    }

    /// Returns the stored response bytes.
    pub fn stored_response_bytes(&self) -> Result<usize, IdempotencyStoreError> {
        self.state
            .lock()
            .map(|state| state.stored_response_bytes)
            .map_err(|_| IdempotencyStoreError::LockPoisoned)
    }

    /// Returns the reserved response bytes.
    pub fn reserved_response_bytes(&self) -> Result<usize, IdempotencyStoreError> {
        self.state
            .lock()
            .map(|state| state.reserved_response_bytes)
            .map_err(|_| IdempotencyStoreError::LockPoisoned)
    }

    /// Returns the prune expired.
    pub fn prune_expired(&self) -> Result<usize, IdempotencyStoreError> {
        let now = self.clock.now();
        let mut state = self
            .state
            .lock()
            .map_err(|_| IdempotencyStoreError::LockPoisoned)?;
        Ok(prune_expired_records(&mut state, now))
    }
}

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

impl fmt::Debug for MemoryIdempotencyStore {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let state = self.state.lock().ok();
        formatter
            .debug_struct("MemoryIdempotencyStore")
            .field(
                "record_count",
                &state.as_ref().map(|state| state.records.len()),
            )
            .field(
                "stored_response_bytes",
                &state.as_ref().map(|state| state.stored_response_bytes),
            )
            .field(
                "reserved_response_bytes",
                &state.as_ref().map(|state| state.reserved_response_bytes),
            )
            .field("max_records", &self.max_records)
            .field("max_stored_response_bytes", &self.max_stored_response_bytes)
            .field(
                "max_response_bytes_per_record",
                &self.max_response_bytes_per_record,
            )
            .finish_non_exhaustive()
    }
}

#[async_trait]
impl IdempotencyStore for MemoryIdempotencyStore {
    async fn reserve(
        &self,
        key: IdempotencyKey,
        request_hash: IdempotencyRequestHash,
        processing_ttl: Duration,
        response_capacity_bytes: usize,
    ) -> Result<IdempotencyReservation, IdempotencyStoreError> {
        if response_capacity_bytes == 0
            || response_capacity_bytes > self.max_response_bytes_per_record
        {
            return Err(IdempotencyStoreError::CapacityExceeded);
        }

        let now = self.clock.now();
        let mut state = self
            .state
            .lock()
            .map_err(|_| IdempotencyStoreError::LockPoisoned)?;
        prune_expired_records(&mut state, now);

        let expires_at = expiry_after(now, processing_ttl)?;
        match state.records.get(&key) {
            Some(record) if record.request_hash != request_hash => {
                Ok(IdempotencyReservation::Conflict)
            }
            Some(record) => Ok(match &record.state {
                EntryState::Processing { .. } => IdempotencyReservation::Processing,
                EntryState::Completed(response) => IdempotencyReservation::Replay(response.clone()),
            }),
            None => {
                if state.records.len() >= self.max_records {
                    return Err(IdempotencyStoreError::CapacityExceeded);
                }
                let allocated_bytes = state
                    .stored_response_bytes
                    .checked_add(state.reserved_response_bytes)
                    .and_then(|bytes| bytes.checked_add(response_capacity_bytes))
                    .ok_or(IdempotencyStoreError::CapacityExceeded)?;
                if allocated_bytes > self.max_stored_response_bytes {
                    return Err(IdempotencyStoreError::CapacityExceeded);
                }
                state.reserved_response_bytes += response_capacity_bytes;
                let lease = IdempotencyLease::new();
                state.records.insert(
                    key,
                    IdempotencyEntry {
                        request_hash,
                        state: EntryState::Processing {
                            lease,
                            reserved_response_bytes: response_capacity_bytes,
                        },
                        expires_at,
                    },
                );
                Ok(IdempotencyReservation::Reserved(lease))
            }
        }
    }

    async fn commit(
        &self,
        key: &IdempotencyKey,
        lease: IdempotencyLease,
        response: StoredIdempotencyResponse,
        retention_ttl: Duration,
    ) -> Result<(), IdempotencyStoreError> {
        let now = self.clock.now();
        let expires_at = expiry_after(now, retention_ttl)?;
        let mut state = self
            .state
            .lock()
            .map_err(|_| IdempotencyStoreError::LockPoisoned)?;
        prune_expired_records(&mut state, now);
        let MemoryIdempotencyState {
            records,
            stored_response_bytes,
            reserved_response_bytes,
        } = &mut *state;
        let Some(record) = records.get_mut(key) else {
            return Err(IdempotencyStoreError::InconsistentRecord);
        };
        let EntryState::Processing {
            lease: current_lease,
            reserved_response_bytes: reserved_bytes,
        } = record.state
        else {
            return Err(IdempotencyStoreError::InconsistentRecord);
        };
        if current_lease != lease {
            return Err(IdempotencyStoreError::InconsistentRecord);
        }
        let response_bytes = stored_response_size(&response);
        if response_bytes > reserved_bytes {
            return Err(IdempotencyStoreError::CapacityExceeded);
        }
        // The response fits within capacity already charged by the reservation.
        record.state = EntryState::Completed(response);
        record.expires_at = expires_at;
        *stored_response_bytes += response_bytes;
        *reserved_response_bytes -= reserved_bytes;
        Ok(())
    }

    async fn abort(
        &self,
        key: &IdempotencyKey,
        lease: IdempotencyLease,
    ) -> Result<(), IdempotencyStoreError> {
        let mut state = self
            .state
            .lock()
            .map_err(|_| IdempotencyStoreError::LockPoisoned)?;
        if let Some(IdempotencyEntry {
            state:
                EntryState::Processing {
                    lease: current_lease,
                    reserved_response_bytes,
                },
            ..
        }) = state.records.get(key)
            && *current_lease == lease
        {
            let released = *reserved_response_bytes;
            state.records.remove(key);
            state.reserved_response_bytes -= released;
        }
        Ok(())
    }
}

fn expiry_after(now: Instant, ttl: Duration) -> Result<Instant, IdempotencyStoreError> {
    if ttl.is_zero() {
        return Err(IdempotencyStoreError::InvalidExpiry);
    }
    now.checked_add(ttl)
        .ok_or(IdempotencyStoreError::InvalidExpiry)
}

fn prune_expired_records(state: &mut MemoryIdempotencyState, now: Instant) -> usize {
    let before = state.records.len();
    state.records.retain(|_, record| {
        if record.expires_at > now {
            return true;
        }
        match &record.state {
            EntryState::Processing {
                reserved_response_bytes,
                ..
            } => {
                state.reserved_response_bytes -= reserved_response_bytes;
            }
            EntryState::Completed(response) => {
                state.stored_response_bytes -= stored_response_size(response);
            }
        }
        false
    });
    before - state.records.len()
}

pub(super) fn stored_response_size(response: &StoredIdempotencyResponse) -> usize {
    response.body.len()
        + response
            .headers
            .iter()
            .map(|(name, value)| name.len().saturating_add(value.len()))
            .sum::<usize>()
}