canic-core 0.95.5

Canic — a canister orchestration and management toolkit for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

//! Module: workflow::cost_guard
//!
//! Responsibility: reserve cost permits with expiry scheduling and map public failures.
//! Does not own: quota accounting, cycle reservations, cleanup execution, or command policy.
//! Boundary: costed workflows reserve here before crossing external-effect boundaries.

use crate::{
    InternalError,
    dto::error::Error,
    model::replay::ReplayCostGuardSettlement,
    ops::cost_guard::{
        CostGuardOps, CostGuardPermit, CostGuardRequest, CostGuardReserveError,
        CostGuardReservePublicKind,
    },
    workflow::runtime::intent::IntentCleanupWorkflow,
};

/// Workflow authority that couples cost-intent mutation to finite-expiry scheduling.
pub struct CostGuardWorkflow;

impl CostGuardWorkflow {
    pub fn reserve(request: CostGuardRequest) -> Result<CostGuardPermit, CostGuardReserveError> {
        let permit = CostGuardOps::reserve(request)?;
        let settlement = permit.replay_settlement();
        IntentCleanupWorkflow::schedule_intent(settlement.quota_intent_id)
            .map_err(CostGuardReserveError::Store)?;
        IntentCleanupWorkflow::schedule_intent(settlement.reservation_intent_id)
            .map_err(CostGuardReserveError::Store)?;
        Ok(permit)
    }

    pub fn complete(permit: &CostGuardPermit, now_secs: u64) -> Result<(), InternalError> {
        let result = CostGuardOps::complete(permit, now_secs);
        Self::reconcile_after_success(&result);
        result
    }

    pub fn complete_replay_settlement(
        settlement: &ReplayCostGuardSettlement,
        now_secs: u64,
    ) -> Result<(), InternalError> {
        let result = CostGuardOps::complete_replay_settlement(settlement, now_secs);
        Self::reconcile_after_success(&result);
        result
    }

    pub fn recover(permit: &CostGuardPermit, now_secs: u64) -> Result<(), InternalError> {
        let result = CostGuardOps::recover(permit, now_secs);
        Self::reconcile_after_success(&result);
        result
    }

    #[must_use]
    pub fn recover_after_failure(
        permit: &CostGuardPermit,
        now_secs: u64,
        error: InternalError,
    ) -> InternalError {
        match Self::recover(permit, now_secs) {
            Ok(()) => error,
            Err(recovery_error) => error.with_diagnostic_context(format!(
                "cost guard recovery failed for reservation {}: {recovery_error}",
                permit.reservation_id
            )),
        }
    }

    fn reconcile_after_success(result: &Result<(), InternalError>) {
        if result.is_ok() {
            IntentCleanupWorkflow::reconcile_after_terminal();
        }
    }
}

#[must_use]
pub fn map_cost_guard_reserve_error(err: CostGuardReserveError) -> InternalError {
    match err.public_kind() {
        Some(CostGuardReservePublicKind::InvalidInput) => {
            InternalError::public(Error::invalid(err.to_string()))
        }
        Some(CostGuardReservePublicKind::ResourceExhausted) => {
            InternalError::public(Error::exhausted(err.to_string()))
        }
        None => err.into(),
    }
}