ic_backup/workflow/ic_snapshot_capture/
mod.rs

1//! One freshly reserved capture update under exact original stage evidence.
2
3use crate::{
4    model::{
5        ic_mutation::{IcMutationAcknowledgement, IcMutationRequest, IcMutationRequestError},
6        ic_request::{IcManagementMethodRecord, IcManagementRequestRecord},
7        operation_plan::OperationPlanError,
8    },
9    ops::persistence::{
10        AttemptJournalError, ExecutionProgressPersistenceError, ExecutionStageGuard,
11        ExecutionWorkflowPersistenceError,
12    },
13    policy::ic_mutation::{IcMutationAssociationError, validate_acknowledgement},
14    ports::ic_mutation::{IcMutationProvider, IcMutationProviderError},
15};
16use thiserror::Error;
17
18/// Durably reserve an original capture, freshly admit it and submit one exact update.
19///
20/// Hold no attempt guards on entry. Only `TakeCanisterSnapshot` is accepted, with
21/// canonical original target/wire binding checked before spending. The existing
22/// journal is opened, never created, and complete original-plan admission owns its
23/// durable reservation. Keep the selected journal locked through fresh admission,
24/// one provider invocation and bounded passive acknowledgement association.
25/// Retained stage/ancestor checks bracket dispatch. Pending or Applied attempts
26/// cannot invoke admission or dispatch again; reopening grants no recapture.
27///
28/// The mandatory fallible `admit` callback must qualify fresh actual context/control,
29/// original capture consistency, quiescence/fence obligations and exclusive
30/// never-dispatched command custody. Any remote preflight calls need their own prior
31/// accounting. There is no default permission, provider or application consistency
32/// lane. The existing provider retains its authenticated single-update contract.
33/// Admission and submission are awaited while the selected journal stays locked.
34/// Cancellation releases that lock while retaining its pending reservation;
35/// even cancellation before dispatch grants no repeat callback or submission.
36///
37/// Success returns a bounded passive acknowledgement and leaves spending pending.
38/// Integrations authenticate exact original attribution and explicitly record any
39/// qualified receipt using the existing journal owner. An ID or matching wire reply
40/// supplies no automatic outcome, complete capture/download, terminal or fence release.
41/// # Errors
42/// Rejects noncapture/changed payloads, original evidence, spending, fresh admission,
43/// provider failures or malformed/mismatched replies. All post-reservation failures
44/// retain consumption; returned acknowledgements survive later rejection in typed
45/// errors. No failure permits retry, recapture, refund, cleanup or automatic uncertainty.
46pub async fn capture_snapshot<E: std::error::Error + 'static>(
47    stage: &ExecutionStageGuard<'_>,
48    operation_sequence: u64,
49    payload: &IcManagementRequestRecord,
50    provider: &mut impl IcMutationProvider,
51    admit: impl AsyncFnOnce(&IcMutationRequest<'_>) -> Result<(), E>,
52) -> Result<IcMutationAcknowledgement, IcSnapshotCaptureExecutionError<E>> {
53    if payload.method() != IcManagementMethodRecord::TakeCanisterSnapshot {
54        return Err(IcSnapshotCaptureExecutionError::CaptureRequired);
55    }
56    let plan = stage.plan();
57    let authority = plan.attempt_authority(operation_sequence)?;
58    let (acknowledgement, admission) = super::ic_mutation::submit_with(
59        stage,
60        &authority,
61        payload,
62        provider,
63        async |request| {
64            admit(request)
65                .await
66                .map_err(IcSnapshotCaptureExecutionError::Admission)?;
67            stage.layout()?;
68            Ok::<_, IcSnapshotCaptureExecutionError<E>>(())
69        },
70        async |journal, request, acknowledgement| {
71            validate_acknowledgement(request, journal.record()?, acknowledgement)?;
72            stage.layout()?;
73            Ok::<_, IcSnapshotCaptureReplyError>(())
74        },
75    )
76    .await?;
77    match admission {
78        Ok(()) => Ok(acknowledgement),
79        Err(source) => Err(IcSnapshotCaptureExecutionError::AfterReply {
80            source,
81            acknowledgement: Box::new(acknowledgement),
82        }),
83    }
84}
85
86/// Capture-step failures retain original spending and any bounded returned acknowledgement.
87#[derive(Debug, Error)]
88pub enum IcSnapshotCaptureExecutionError<E: std::error::Error + 'static> {
89    /// Only the original capture method may enter this coordinator.
90    #[error("snapshot capture requires take_canister_snapshot")]
91    CaptureRequired,
92    /// Original operation authority cannot be derived.
93    #[error(transparent)]
94    Plan(#[from] OperationPlanError),
95    /// Workflow, stage or original ancestor evidence failed admission.
96    #[error(transparent)]
97    Stage(#[from] ExecutionWorkflowPersistenceError),
98    /// Original selected journal admission failed.
99    #[error(transparent)]
100    Journal(#[from] AttemptJournalError),
101    /// Complete original progress, prerequisites or durable reservation failed.
102    #[error(transparent)]
103    Progress(#[from] ExecutionProgressPersistenceError),
104    /// Canonical original mutation binding or current reservation differs.
105    #[error(transparent)]
106    Request(#[from] IcMutationRequestError),
107    /// Fresh integration-owned admission rejected after reservation.
108    #[error("fresh snapshot capture admission failed: {0}")]
109    Admission(#[source] E),
110    /// The single provider call failed; spending remains pending.
111    #[error(transparent)]
112    Provider(#[from] IcMutationProviderError),
113    /// Admission after a reply failed, retaining its complete bounded evidence.
114    #[error("snapshot capture reply rejected: {source}")]
115    AfterReply {
116        /// Typed original admission failure.
117        source: IcSnapshotCaptureReplyError,
118        /// Complete returned passive evidence, without settlement authority.
119        acknowledgement: Box<IcMutationAcknowledgement>,
120    },
121}
122
123/// Admission failure after a returned snapshot capture reply.
124#[derive(Debug, Error)]
125pub enum IcSnapshotCaptureReplyError {
126    /// Original selected journal cannot be re-admitted.
127    #[error(transparent)]
128    Journal(#[from] AttemptJournalError),
129    /// Passive exact reply association failed.
130    #[error(transparent)]
131    Association(#[from] IcMutationAssociationError),
132    /// Original stage or ancestor evidence cannot be re-admitted.
133    #[error(transparent)]
134    Stage(#[from] ExecutionWorkflowPersistenceError),
135}
136
137#[cfg(all(test, unix))]
138mod tests;
ic_backup/workflow/ic_snapshot_capture/mod.rs

ic_backup/workflow/ic_snapshot_capture/
mod.rs
