ic-backup 0.64.1

//! One freshly reserved capture update under exact original stage evidence.

use crate::policy::ic_mutation::IcMutationReplyView;
use crate::ports::IcProviderError;
use crate::{
    model::{
        artifacts::ArtifactChecksumRecord,
        attempt_journal::MutationReceiptRequest,
        ic_mutation::{IcMutationAcknowledgement, IcMutationRequest, IcMutationRequestError},
        ic_request::{IcManagementMethodRecord, IcManagementRequestRecord},
        operation_plan::OperationPlanError,
    },
    ops::persistence::{
        AttemptJournalError, ExecutionStageGuard, ExecutionWorkflowPersistenceError,
    },
    policy::ic_mutation::{IcMutationAssociationError, validate_acknowledgement},
    ports::ic_mutation::IcMutationProvider,
};
use thiserror::Error;

/// Durably reserve an original capture, freshly admit it and submit one exact update.
///
/// Hold no attempt guards on entry. Only `TakeCanisterSnapshot` is accepted, with
/// canonical original target/wire binding checked before spending. The existing
/// journal is opened, never created, and complete original-plan admission owns its
/// durable reservation. Keep the selected journal locked through fresh admission,
/// one provider invocation and bounded passive acknowledgement association.
/// Retained stage/ancestor checks bracket dispatch. Pending or Applied attempts
/// cannot invoke admission or dispatch again; reopening grants no recapture.
///
/// The mandatory fallible `admit` callback must qualify fresh actual context/control,
/// original capture consistency, quiescence/fence obligations and exclusive
/// never-dispatched command custody. Any remote preflight calls need their own prior
/// accounting. There is no default permission, provider or application consistency
/// lane. The existing provider retains its authenticated single-update contract.
/// Admission and submission are awaited while the selected journal stays locked.
/// Cancellation releases that lock while retaining pending or recorded Applied spending;
/// even cancellation before dispatch grants no repeat callback or submission.
///
/// `qualify` must independently authenticate original attribution and durably retain
/// exact request/reply bytes before returning its explicit Applied receipt. It runs
/// under the same journal lock; retain bytes before any cancellable await. Remote
/// qualification requires separate prior accounting. Only this exact qualified
/// receipt is recorded. Success returns the acknowledgement and canonical capture
/// reply digest for the workflow owner to checkpoint after journal exclusion ends.
/// An ID or matching wire reply alone supplies no outcome or release authority.
/// # Errors
/// Rejects noncapture/changed payloads, original evidence, spending, fresh admission,
/// provider/association, qualification or receipt failure. Typed post-reply errors
/// retain the bounded acknowledgement. No failure permits retry or refund.
pub async fn capture_snapshot<E: std::error::Error + 'static>(
    stage: &ExecutionStageGuard<'_>,
    operation_sequence: u64,
    payload: &IcManagementRequestRecord,
    provider: &mut impl IcMutationProvider,
    admit: impl AsyncFnOnce(&IcMutationRequest<'_>) -> Result<(), E>,
    qualify: impl AsyncFnOnce(
        &IcMutationRequest<'_>,
        &IcMutationAcknowledgement,
    ) -> Result<MutationReceiptRequest, E>,
) -> Result<(IcMutationAcknowledgement, ArtifactChecksumRecord), IcSnapshotCaptureExecutionError<E>>
{
    if payload.method() != IcManagementMethodRecord::TakeCanisterSnapshot {
        return Err(IcSnapshotCaptureExecutionError::CaptureRequired);
    }
    let plan = stage.plan();
    let authority = plan.attempt_authority(operation_sequence)?;
    let (acknowledgement, admission) = super::ic_mutation::submit_with(
        stage,
        &authority,
        payload,
        provider,
        async |request| {
            admit(request)
                .await
                .map_err(IcSnapshotCaptureExecutionError::Admission)?;
            stage
                .layout()
                .map_err(super::ExecutionReservationError::from)?;
            Ok::<_, IcSnapshotCaptureExecutionError<E>>(())
        },
        async |journal, request, acknowledgement| {
            let admitted = validate_acknowledgement(request, journal.record()?, acknowledgement)?;
            stage.layout()?;
            let receipt = qualify(request, acknowledgement)
                .await
                .map_err(IcSnapshotCaptureReplyError::Qualification)?;
            super::qualified_receipt::record_applied(
                journal,
                receipt,
                request.mutation_attempt(),
                payload.digest().hash(),
                IcSnapshotCaptureReplyError::ReceiptRequired,
                || {
                    stage.layout()?;
                    Ok(())
                },
            )?;
            stage.layout()?;
            let IcMutationReplyView::Capture(reply) = admitted.reply() else {
                return Err(IcSnapshotCaptureReplyError::ReceiptRequired);
            };
            Ok::<_, IcSnapshotCaptureReplyError<E>>(reply.digest())
        },
    )
    .await?;
    let admitted = admission;
    super::qualified_receipt::retain_reply(acknowledgement, admitted, |source, acknowledgement| {
        IcSnapshotCaptureExecutionError::AfterReply {
            source,
            acknowledgement,
        }
    })
}

/// Capture-step failures retain original spending and any bounded returned acknowledgement.
#[derive(Debug, Error)]
pub enum IcSnapshotCaptureExecutionError<E: std::error::Error + 'static> {
    /// Shared original-stage, journal or durable reservation admission failed.
    #[error(transparent)]
    Reservation(#[from] super::ExecutionReservationError),
    /// Only the original capture method may enter this coordinator.
    #[error("snapshot capture requires take_canister_snapshot")]
    CaptureRequired,
    /// Original operation authority cannot be derived.
    #[error(transparent)]
    Plan(#[from] OperationPlanError),
    /// Canonical original mutation binding or current reservation differs.
    #[error(transparent)]
    Request(#[from] IcMutationRequestError),
    /// Fresh integration-owned admission rejected after reservation.
    #[error("fresh snapshot capture admission failed: {0}")]
    Admission(#[source] E),
    /// The single provider call failed; spending remains pending.
    #[error(transparent)]
    Provider(#[from] IcProviderError),
    /// Admission after a reply failed, retaining its complete bounded evidence.
    #[error("snapshot capture reply rejected: {source}")]
    AfterReply {
        /// Typed original admission failure.
        source: IcSnapshotCaptureReplyError<E>,
        /// Complete returned passive evidence, without settlement authority.
        acknowledgement: Box<IcMutationAcknowledgement>,
    },
}

/// Admission failure after a returned snapshot capture reply.
#[derive(Debug, Error)]
pub enum IcSnapshotCaptureReplyError<E: std::error::Error + 'static> {
    /// Independent attribution or durable reply retention failed.
    #[error("snapshot capture qualification failed: {0}")]
    Qualification(#[source] E),
    /// Explicit receipt differs from this original Applied capture.
    #[error("snapshot capture requires an explicit original Applied receipt")]
    ReceiptRequired,
    /// Original selected journal cannot be re-admitted.
    #[error(transparent)]
    Journal(#[from] AttemptJournalError),
    /// Passive exact reply association failed.
    #[error(transparent)]
    Association(#[from] IcMutationAssociationError),
    /// Original stage or ancestor evidence cannot be re-admitted.
    #[error(transparent)]
    Stage(#[from] ExecutionWorkflowPersistenceError),
}

#[cfg(all(test, unix))]
mod tests;