dekopon-process 0.78.0

Script-tree budgets, cancellation, pipes, job vocabulary and exit codes for Dekopon frontends
Documentation
use std::{
    pin::Pin,
    sync::{
        Arc,
        atomic::{AtomicU32, AtomicU64, Ordering},
    },
    time::{Duration, Instant},
};

use crate::{CancelSignal, LimitExceeded, Limits, ShellThreads};
use tokio::time::Sleep;

#[derive(Clone, Debug)]
pub struct CallBudget {
    used: Arc<AtomicU32>,
    maximum: u32,
}

impl CallBudget {
    #[must_use]
    pub fn new(maximum: u32) -> Self {
        Self {
            used: Arc::new(AtomicU32::new(0)),
            maximum,
        }
    }

    #[must_use]
    pub fn used(&self) -> u32 {
        self.used.load(Ordering::Relaxed)
    }

    #[must_use]
    pub const fn maximum(&self) -> u32 {
        self.maximum
    }

    pub fn refund(&self) {
        self.used.fetch_sub(1, Ordering::Relaxed);
    }

    pub fn charge(&self) -> Result<(), LimitExceeded> {
        self.used
            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |used| {
                used.checked_add(1).filter(|next| *next <= self.maximum)
            })
            .map(|_| ())
            .map_err(|_used| LimitExceeded::CapabilityCalls {
                maximum: self.maximum,
            })
    }
}

#[derive(Clone, Debug)]
pub struct TreeContext {
    cancel: Vec<CancelSignal>,
    cancel_deadline: Option<Arc<Pin<Box<Sleep>>>>,
    deadline: Instant,
    calls: CallBudget,
    steps: Arc<AtomicU64>,
    retained: Arc<AtomicU64>,
    limits: Limits,
    threads: ShellThreads,
}

#[derive(Debug)]
#[must_use]
pub struct RetainedBytes {
    used: Arc<AtomicU64>,
    bytes: u64,
    maximum: u64,
}

impl RetainedBytes {
    pub fn bytes(&self) -> u64 {
        self.bytes
    }

    pub fn shrink(&mut self, bytes: u64) {
        debug_assert!(bytes <= self.bytes);
        self.bytes -= bytes;
        self.used.fetch_sub(bytes, Ordering::Relaxed);
    }

    pub fn grow(&mut self, bytes: u64) -> Result<(), LimitExceeded> {
        self.used
            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |used| {
                used.checked_add(bytes).filter(|next| *next <= self.maximum)
            })
            .map_err(|_used| LimitExceeded::ValueBytes {
                maximum: self.maximum,
            })?;
        self.bytes += bytes;
        Ok(())
    }
}

impl Drop for RetainedBytes {
    fn drop(&mut self) {
        self.used.fetch_sub(self.bytes, Ordering::Relaxed);
    }
}

impl TreeContext {
    #[must_use]
    pub fn new(limits: Limits, calls: CallBudget, threads: ShellThreads) -> Self {
        let started = Instant::now();
        Self {
            cancel: Vec::new(),
            cancel_deadline: None,
            deadline: started.checked_add(limits.timeout).unwrap_or(started),
            calls,
            steps: Arc::new(AtomicU64::new(0)),
            retained: Arc::new(AtomicU64::new(0)),
            limits,
            threads,
        }
    }

    pub fn with_cancel(mut self, cancel: Vec<CancelSignal>) -> Self {
        self.cancel = cancel;
        self
    }

    pub fn with_parent_cancel(mut self, cancel: CancelSignal) -> Self {
        self.cancel.push(cancel);
        self
    }

    pub fn with_script_timer(mut self, timer: Option<Pin<Box<Sleep>>>) -> Self {
        self.cancel_deadline = timer.map(Arc::new);
        self
    }

    pub fn is_cancelled(&self) -> bool {
        self.cancel.iter().any(CancelSignal::is_cancelled)
            || self
                .cancel_deadline
                .as_ref()
                .is_some_and(|timer| timer.is_elapsed())
    }

    pub fn charge_step(&self) -> Result<(), LimitExceeded> {
        if self.is_cancelled() {
            return Err(LimitExceeded::Cancelled);
        }
        self.steps
            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |used| {
                used.checked_add(1)
                    .filter(|next| *next <= self.limits.max_steps)
            })
            .map(|_| ())
            .map_err(|_used| LimitExceeded::Steps {
                maximum: self.limits.max_steps,
            })
    }

    pub fn retain(&self, bytes: u64) -> Result<RetainedBytes, LimitExceeded> {
        self.retained
            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |used| {
                used.checked_add(bytes)
                    .filter(|next| *next <= self.limits.max_value_bytes)
            })
            .map_err(|_used| LimitExceeded::ValueBytes {
                maximum: self.limits.max_value_bytes,
            })?;
        Ok(RetainedBytes {
            used: Arc::clone(&self.retained),
            bytes,
            maximum: self.limits.max_value_bytes,
        })
    }

    pub fn steps(&self) -> u64 {
        self.steps.load(Ordering::Relaxed)
    }

    pub fn value_bytes(&self) -> u64 {
        self.retained.load(Ordering::Relaxed)
    }

    pub fn check_deadline(&self) -> Result<(), LimitExceeded> {
        if Instant::now() >= self.deadline {
            Err(LimitExceeded::Deadline {
                timeout_ms: self.limits.timeout.as_millis(),
            })
        } else {
            Ok(())
        }
    }

    #[must_use]
    pub fn expired(&self) -> bool {
        Instant::now() >= self.deadline
    }

    #[must_use]
    pub fn remaining(&self) -> Duration {
        self.cancel_deadline.as_ref().map_or_else(
            || self.deadline.saturating_duration_since(Instant::now()),
            |timer| {
                timer
                    .deadline()
                    .saturating_duration_since(tokio::time::Instant::now())
            },
        )
    }

    #[must_use]
    pub const fn limits(&self) -> &Limits {
        &self.limits
    }

    #[must_use]
    pub fn calls(&self) -> &CallBudget {
        &self.calls
    }

    #[must_use]
    pub const fn shell_threads(&self) -> &ShellThreads {
        &self.threads
    }
}

#[cfg(test)]
mod tests {
    use super::{CallBudget, LimitExceeded, Ordering};

    #[test]
    fn exhausted_maximum_call_budget_returns_the_typed_error() {
        let budget = CallBudget::new(u32::MAX);
        budget.used.store(u32::MAX - 1, Ordering::Relaxed);

        assert_eq!(budget.charge(), Ok(()));
        assert_eq!(
            budget.charge(),
            Err(LimitExceeded::CapabilityCalls { maximum: u32::MAX })
        );
        assert_eq!(budget.used(), u32::MAX);
    }
}