ic_backup/workflow/ic_snapshot_restore/
mod.rs

1//! One original same-ID load/start with fresh safety and independently qualified settlement.
2
3use crate::{
4    model::{
5        attempt_journal::MutationReceiptRequest,
6        execution_workflow::ExecutionStagePredecessorRecord,
7        ic_mutation::{IcMutationAcknowledgement, IcMutationRequest, IcMutationRequestError},
8        operation_plan::OperationPlanRecord,
9        restore_safety::{RestoreSafetyObservation, RestoreSafetyRequest},
10    },
11    ops::persistence::{
12        AttemptJournalError, AttemptJournalGuard, BackupLayoutGuard,
13        ExecutionProgressPersistenceError, ExecutionStageCheckpointError, ExecutionStageGuard,
14        ExecutionWorkflowPersistenceError, RestoreSafetyPersistenceError,
15        read_restore_safety_requirement,
16    },
17    policy::{
18        ic_mutation::{IcMutationAssociationError, IcMutationReplyView, validate_acknowledgement},
19        restore_safety::{RestoreSafetyError, validate},
20    },
21    ports::ic_mutation::{IcMutationProvider, IcMutationProviderError},
22};
23use thiserror::Error;
24
25/// Execute and checkpoint one exact singleton original load or start stage.
26///
27/// Retain the complete original stage/journals, source plan, safety requirement and
28/// source references first; hold no attempt guards. `safety` binds the exact original
29/// load/start bytes and a fresh integration-owned challenge. Read the requirement
30/// under both layouts before spending and recheck it across admission and settlement.
31/// No source is reconstructed, uploaded, replaced or released by this function.
32///
33/// After durable reservation, mandatory `admit` must qualify current authenticated
34/// control, snapshot-origin permissions, complete uploaded source, application safety,
35/// stable byte/command custody and proof of no prior dispatch. Return actual fresh
36/// safety observations; the existing policy checks exact context/inventory/selection,
37/// original lane/fence and load/start preconditions before one provider invocation.
38/// All remote preflight/qualification calls need separate prior accounting. There is
39/// no default no-external-effects lane or automatic stopped/load-success inference.
40///
41/// Mandatory `qualify` independently authenticates original successful attribution
42/// and durably retains exact request/reply evidence before its explicit Applied
43/// receipt. Record through the existing journal owner under exclusion, then release
44/// the lock and checkpoint canonical request/raw-reply evidence. Load settlement
45/// does not establish application acceptance for a later start: qualify that afresh.
46/// Pending/Applied stages never invoke callbacks/providers again. Checkpoint replay
47/// stays local; failure preserves spending, replies, obligations and references.
48/// This is one bounded step, not complete restore, terminal or fence/reference release.
49/// Admission, submission and independent qualification are awaited under the
50/// selected journal lock. Cancellation retains its current pending/Applied state
51/// and grants no repeat invocation. Qualification must durably retain returned
52/// bytes before awaiting work that could be cancelled; in-memory replies do not
53/// survive cancellation. The core imposes no executor or `Send` requirement.
54/// # Errors
55/// Rejects changed/non-singleton originals, retained source/requirement failures,
56/// spending, fresh admission/safety, provider/association, qualification/receipt or
57/// checkpoint failure. Returned bounded replies survive post-reply rejection.
58pub async fn restore_snapshot<E: std::error::Error + 'static>(
59    stage: &ExecutionStageGuard<'_>,
60    source_layout: &BackupLayoutGuard,
61    source_plan: &OperationPlanRecord,
62    safety: &RestoreSafetyRequest<'_>,
63    provider: &mut impl IcMutationProvider,
64    admit: impl AsyncFnOnce(
65        &IcMutationRequest<'_>,
66        &RestoreSafetyRequest<'_>,
67    ) -> Result<RestoreSafetyObservation, E>,
68    qualify: impl AsyncFnOnce(
69        &IcMutationRequest<'_>,
70        &IcMutationAcknowledgement,
71    ) -> Result<MutationReceiptRequest, E>,
72) -> Result<(IcMutationAcknowledgement, ExecutionStagePredecessorRecord), IcRestoreExecutionError<E>>
73{
74    let plan = stage.plan();
75    let sequence = safety.binding().operation_sequence();
76    if plan.operations().len() != 1 || plan.operations()[0].operation_sequence() != sequence {
77        return Err(IcRestoreExecutionError::OriginalMismatch);
78    }
79    let retain = || {
80        read_restore_safety_requirement(
81            stage.layout()?,
82            source_layout,
83            plan,
84            source_plan,
85            &safety.requirement().digest(),
86        )?;
87        Ok::<_, IcRestoreReplyError<E>>(())
88    };
89    retain()?;
90    let authority = plan
91        .attempt_authority(sequence)
92        .map_err(IcMutationRequestError::from)?;
93    safety
94        .wire()
95        .validate_mutation_binding(authority.binding())
96        .map_err(IcMutationRequestError::from)?;
97    let mut journal = AttemptJournalGuard::open(stage.layout()?, &authority)?;
98    journal.reserve_planned_mutation(&plan.digest())?;
99    let request = IcMutationRequest::new(plan, sequence, journal.record()?, safety.wire())?;
100    let observation = admit(&request, safety)
101        .await
102        .map_err(IcRestoreExecutionError::Admission)?;
103    validate(safety, &observation)?;
104    retain()?;
105    let acknowledgement = provider
106        .submit_mutation(&request, journal.record()?)
107        .await?;
108    let settle = async || {
109        let admitted = validate_acknowledgement(&request, journal.record()?, &acknowledgement)?;
110        retain()?;
111        super::qualified_receipt::AppliedReceiptRecorder {
112            journal: &mut journal,
113            expected_attempt: request.mutation_attempt(),
114            expected_request: safety.wire().digest().hash(),
115        }
116        .record_applied(
117            &request,
118            &acknowledgement,
119            qualify,
120            IcRestoreReplyError::Qualification,
121            || IcRestoreReplyError::ReceiptRequired,
122            retain,
123        )
124        .await?;
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.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    /// Original stage/ancestor/layout admission failed.
194    #[error(transparent)]
195    Stage(#[from] ExecutionWorkflowPersistenceError),
196    /// Existing original source/requirement admission failed.
197    #[error(transparent)]
198    Retention(#[from] RestoreSafetyPersistenceError),
199    /// Existing selected journal/receipt admission failed.
200    #[error(transparent)]
201    Journal(#[from] AttemptJournalError),
202    /// Existing bounded original acknowledgement association failed.
203    #[error(transparent)]
204    Association(#[from] IcMutationAssociationError),
205    /// Authentication/attribution or durable original-byte retention failed.
206    #[error("restore reply qualification failed: {0}")]
207    Qualification(#[source] E),
208    /// Require an explicit qualified exact original Applied receipt.
209    #[error("restore requires an explicit original Applied receipt")]
210    ReceiptRequired,
211    /// Existing checkpoint failed; Applied and occupied evidence remain.
212    #[error(transparent)]
213    Checkpoint(#[from] ExecutionStageCheckpointError),
214}
215
216#[cfg(test)]
217mod tests;
ic_backup/workflow/ic_snapshot_restore/mod.rs

ic_backup/workflow/ic_snapshot_restore/
mod.rs
