ic_backup/workflow/ic_snapshot_restore/
mod.rs

1//! One original same-ID load/start with fresh safety and independently qualified settlement.
2
3mod source;
4pub use source::{IcRestoreSource, IcRestoreSourceError};
5
6use crate::{
7    model::{
8        attempt_journal::MutationReceiptRequest,
9        execution_workflow::ExecutionStagePredecessorRecord,
10        ic_mutation::{IcMutationAcknowledgement, IcMutationRequest, IcMutationRequestError},
11        restore_safety::{RestoreSafetyObservation, RestoreSafetyRequest},
12    },
13    ops::persistence::{
14        AttemptJournalError, AttemptJournalGuard, ExecutionProgressPersistenceError,
15        ExecutionStageCheckpointError, ExecutionStageGuard, ExecutionWorkflowPersistenceError,
16        RestoreSafetyPersistenceError, read_restore_safety_requirement,
17    },
18    policy::{
19        ic_mutation::{IcMutationAssociationError, IcMutationReplyView, validate_acknowledgement},
20        restore_safety::{RestoreSafetyError, validate},
21    },
22    ports::ic_mutation::{IcMutationProvider, IcMutationProviderError},
23};
24use thiserror::Error;
25
26/// Execute and checkpoint one exact singleton original load or start stage.
27///
28/// Retain the complete original stage/journals, source plan, safety requirement and
29/// source references first; hold no attempt guards. `source` explicitly binds an
30/// existing snapshot or the complete original upload destination independently of
31/// the load plan. Re-admit that provenance across all boundaries. `safety` binds the exact original
32/// load/start bytes and a fresh integration-owned challenge. Read the requirement
33/// under both layouts before spending and recheck it across admission and settlement.
34/// No source is reconstructed, uploaded, replaced or released by this function.
35///
36/// After durable reservation, mandatory `admit` must qualify current authenticated
37/// control, snapshot-origin permissions, complete uploaded source, application safety,
38/// stable byte/command custody and proof of no prior dispatch. Return actual fresh
39/// safety observations; the existing policy checks exact context/inventory/selection,
40/// original lane/fence and load/start preconditions before one provider invocation.
41/// All remote preflight/qualification calls need separate prior accounting. There is
42/// no default no-external-effects lane or automatic stopped/load-success inference.
43///
44/// Mandatory `qualify` independently authenticates original successful attribution
45/// and durably retains exact request/reply evidence before its explicit Applied
46/// receipt. Record through the existing journal owner under exclusion, then release
47/// the lock and checkpoint canonical request/raw-reply evidence. Load settlement
48/// does not establish application acceptance for a later start: qualify that afresh.
49/// Pending/Applied stages never invoke callbacks/providers again. Checkpoint replay
50/// stays local; failure preserves spending, replies, obligations and references.
51/// This is one bounded step, not complete restore, terminal or fence/reference release.
52/// Admission, submission and independent qualification are awaited under the
53/// selected journal lock. Cancellation retains its current pending/Applied state
54/// and grants no repeat invocation. Qualification must durably retain returned
55/// bytes before awaiting work that could be cancelled; in-memory replies do not
56/// survive cancellation. The core imposes no executor or `Send` requirement.
57/// # Errors
58/// Rejects changed/non-singleton originals, retained source/requirement failures,
59/// spending, fresh admission/safety, provider/association, qualification/receipt or
60/// checkpoint failure. Returned bounded replies survive post-reply rejection.
61pub async fn restore_snapshot<E: std::error::Error + 'static>(
62    stage: &ExecutionStageGuard<'_>,
63    source: IcRestoreSource<'_>,
64    safety: &RestoreSafetyRequest<'_>,
65    provider: &mut impl IcMutationProvider,
66    admit: impl AsyncFnOnce(
67        &IcMutationRequest<'_>,
68        &RestoreSafetyRequest<'_>,
69    ) -> Result<RestoreSafetyObservation, E>,
70    qualify: impl AsyncFnOnce(
71        &IcMutationRequest<'_>,
72        &IcMutationAcknowledgement,
73    ) -> Result<MutationReceiptRequest, E>,
74) -> Result<(IcMutationAcknowledgement, ExecutionStagePredecessorRecord), IcRestoreExecutionError<E>>
75{
76    let plan = stage.plan();
77    let sequence = safety.binding().operation_sequence();
78    if plan.operations().len() != 1 || plan.operations()[0].operation_sequence() != sequence {
79        return Err(IcRestoreExecutionError::OriginalMismatch);
80    }
81    let retain = || {
82        source.validate(stage, safety.wire())?;
83        read_restore_safety_requirement(
84            stage.layout()?,
85            source.layout,
86            plan,
87            source.plan,
88            &safety.requirement().digest(),
89        )?;
90        Ok::<_, IcRestoreReplyError<E>>(())
91    };
92    retain()?;
93    let authority = plan
94        .attempt_authority(sequence)
95        .map_err(IcMutationRequestError::from)?;
96    safety
97        .wire()
98        .validate_mutation_binding(authority.binding())
99        .map_err(IcMutationRequestError::from)?;
100    let mut journal = AttemptJournalGuard::open(stage.layout()?, &authority)?;
101    journal.reserve_planned_mutation(&plan.digest())?;
102    let request = IcMutationRequest::new(plan, sequence, journal.record()?, safety.wire())?;
103    let observation = admit(&request, safety)
104        .await
105        .map_err(IcRestoreExecutionError::Admission)?;
106    validate(safety, &observation)?;
107    retain()?;
108    let acknowledgement = provider
109        .submit_mutation(&request, journal.record()?)
110        .await?;
111    let settle = async || {
112        let admitted = validate_acknowledgement(&request, journal.record()?, &acknowledgement)?;
113        retain()?;
114        let receipt = qualify(&request, &acknowledgement)
115            .await
116            .map_err(IcRestoreReplyError::Qualification)?;
117        let receipt = super::qualified_receipt::admit_applied(
118            receipt,
119            request.mutation_attempt(),
120            safety.wire().digest().hash(),
121        )
122        .ok_or(IcRestoreReplyError::ReceiptRequired)?;
123        retain()?;
124        journal.record_mutation(receipt)?;
125        retain()?;
126        let IcMutationReplyView::Lifecycle(reply) = admitted.reply() else {
127            return Err(IcRestoreReplyError::ReceiptRequired);
128        };
129        Ok(reply.digest())
130    };
131    let evidence = match settle().await {
132        Ok(evidence) => evidence,
133        Err(source) => {
134            return Err(IcRestoreExecutionError::AfterReply {
135                source,
136                acknowledgement: Box::new(acknowledgement),
137            });
138        }
139    };
140    drop(journal);
141    match stage.reconcile_checkpoint(evidence) {
142        Ok(predecessor) => Ok((acknowledgement, predecessor)),
143        Err(source) => Err(IcRestoreExecutionError::AfterReply {
144            source: IcRestoreReplyError::Checkpoint(source),
145            acknowledgement: Box::new(acknowledgement),
146        }),
147    }
148}
149
150/// Original restore-step failure; no variant authorizes reissue or cleanup.
151#[derive(Debug, Error)]
152pub enum IcRestoreExecutionError<E: std::error::Error + 'static> {
153    /// Only an exact singleton original load/start stage is admitted.
154    #[error("restore requires an exact singleton original load/start stage")]
155    OriginalMismatch,
156    /// Original workflow/stage/ancestor admission failed.
157    #[error(transparent)]
158    Stage(#[from] ExecutionWorkflowPersistenceError),
159    /// Existing journal admission failed.
160    #[error(transparent)]
161    Journal(#[from] AttemptJournalError),
162    /// Complete original progress/prerequisites or reservation failed.
163    #[error(transparent)]
164    Progress(#[from] ExecutionProgressPersistenceError),
165    /// Exact original mutation binding failed.
166    #[error(transparent)]
167    Request(#[from] IcMutationRequestError),
168    /// Original source/requirement retention failed before reply.
169    #[error(transparent)]
170    Retention(#[from] IcRestoreReplyError<E>),
171    /// Integration-owned fresh admission failed after reservation.
172    #[error("fresh restore admission failed: {0}")]
173    Admission(#[source] E),
174    /// Existing current restore-safety policy rejected before dispatch.
175    #[error(transparent)]
176    Safety(#[from] RestoreSafetyError),
177    /// Exactly one provider call failed; original spending stays pending.
178    #[error(transparent)]
179    Provider(#[from] IcMutationProviderError),
180    /// Failure after reply retains its original bounded acknowledgement.
181    #[error("restore reply settlement failed: {source}")]
182    AfterReply {
183        /// Existing evidence/qualification/persistence rejection.
184        source: IcRestoreReplyError<E>,
185        /// Exact original bounded reply without an inferred outcome.
186        acknowledgement: Box<IcMutationAcknowledgement>,
187    },
188}
189
190/// Post-reply restore rejection, preserving original receipts and pending spending.
191#[derive(Debug, Error)]
192pub enum IcRestoreReplyError<E: std::error::Error + 'static> {
193    /// Existing snapshot or complete uploaded destination no longer matches.
194    #[error(transparent)]
195    Source(#[from] IcRestoreSourceError),
196    /// Original stage/ancestor/layout admission failed.
197    #[error(transparent)]
198    Stage(#[from] ExecutionWorkflowPersistenceError),
199    /// Existing original source/requirement admission failed.
200    #[error(transparent)]
201    Retention(#[from] RestoreSafetyPersistenceError),
202    /// Existing selected journal/receipt admission failed.
203    #[error(transparent)]
204    Journal(#[from] AttemptJournalError),
205    /// Existing bounded original acknowledgement association failed.
206    #[error(transparent)]
207    Association(#[from] IcMutationAssociationError),
208    /// Authentication/attribution or durable original-byte retention failed.
209    #[error("restore reply qualification failed: {0}")]
210    Qualification(#[source] E),
211    /// Require an explicit qualified exact original Applied receipt.
212    #[error("restore requires an explicit original Applied receipt")]
213    ReceiptRequired,
214    /// Existing checkpoint failed; Applied and occupied evidence remain.
215    #[error(transparent)]
216    Checkpoint(#[from] ExecutionStageCheckpointError),
217}
218
219#[cfg(test)]
220mod tests;
ic_backup/workflow/ic_snapshot_restore/mod.rs

ic_backup/workflow/ic_snapshot_restore/
mod.rs
