ic_backup/workflow/ic_snapshot_metadata/

mod.rs

//! One original metadata stage, with explicit qualified receipt and learned evidence.

use crate::{
    model::{
        artifacts::ArtifactChecksumRecord,
        attempt_journal::MutationReceiptRequest,
        ic_snapshot_metadata::IcSnapshotMetadataRequest,
        ic_snapshot_transfer_read::{
            IcSnapshotTransferReadPayload, IcSnapshotTransferReadRequest,
            IcSnapshotTransferReadResponse,
        },
    },
    ops::persistence::{
        AttemptJournalError, AttemptJournalGuard, ExecutionStageGuard,
        ExecutionWorkflowPersistenceError,
    },
    policy::ic_snapshot_transfer_read::{IcSnapshotTransferReadReply, IcSnapshotTransferReadView},
    ports::ic_snapshot_transfer_read::IcSnapshotTransferReadProvider,
    workflow::ic_snapshot_transfer_read::{
        IcSnapshotTransferReadExecutionError, read_snapshot_with,
    },
};
use thiserror::Error;

/// Read one new exact singleton metadata stage and record its qualified receipt.
///
/// Prepare the original stage and complete journals first; hold no attempt guards on
/// entry. Reuse the canonical single-read owner for durable spending, mandatory fresh
/// admission and exactly one provider call. A pending or previously Applied read is
/// never dispatched again, including after interruption before checkpoint publication.
///
/// `admit` owns fresh read permission, raw-ID/application and never-dispatched custody.
/// `qualify` runs under the original journal lock and must independently authenticate
/// exact response attribution AND durably retain original request/reply bytes before
/// returning the explicit Applied receipt. There is no default qualification or byte
/// store. Opaque provider evidence and valid wire shape cannot substitute for it.
/// Account any remote qualification separately before its calls.
/// Admission, submission and independent qualification are async. Qualification
/// holds the same original journal continuously from dispatch, reuses its decoded
/// reply, and must retain the reply durably before
/// awaiting cancellable work. Cancellation keeps pending/Applied spending and denies
/// reentry; no executor or `Send` bound is imposed by the core.
///
/// Record the receipt through the sole spending owner, then return the response and
/// canonical request/raw-metadata digest. The workflow owner checkpoints that learned
/// evidence after journal exclusion ends. Direct callers use the same stage checkpoint
/// owner explicitly before binding successors. Preparing data stages remains separate.
/// No data calls, artifact, default authority, terminal proof or reference release follows.
/// # Errors
/// Rejects non-singleton or changed originals, spending, fresh admission, provider,
/// association, qualification and receipt failures without cleanup/refund.
pub async fn read_snapshot_metadata<E: std::error::Error + 'static>(
    stage: &ExecutionStageGuard<'_>,
    operation_sequence: u64,
    payload: &IcSnapshotMetadataRequest,
    provider: &mut impl IcSnapshotTransferReadProvider,
    admit: impl AsyncFnOnce(&IcSnapshotTransferReadRequest<'_, '_>) -> Result<(), E>,
    qualify: impl AsyncFnOnce(
        &IcSnapshotTransferReadRequest<'_, '_>,
        &IcSnapshotTransferReadResponse,
    ) -> Result<MutationReceiptRequest, E>,
) -> Result<
    (IcSnapshotTransferReadResponse, ArtifactChecksumRecord),
    IcSnapshotMetadataExecutionError<E>,
> {
    let operation = stage
        .plan()
        .singleton_operation(operation_sequence)
        .ok_or(IcSnapshotMetadataExecutionError::OriginalMismatch)?;
    if operation.request() != payload.digest().hash() {
        return Err(IcSnapshotMetadataExecutionError::OriginalMismatch);
    }
    let (response, settlement) = read_snapshot_with(
        stage,
        operation_sequence,
        IcSnapshotTransferReadPayload::Metadata(payload),
        provider,
        admit,
        async |journal, request, admitted| {
            settle_metadata(stage, journal, request, admitted, qualify).await
        },
    )
    .await?;
    super::qualified_receipt::retain_reply(response, settlement, |source, response| {
        IcSnapshotMetadataExecutionError::AfterReply { source, response }
    })
}

async fn settle_metadata<E: std::error::Error + 'static>(
    stage: &ExecutionStageGuard<'_>,
    journal: &mut AttemptJournalGuard<'_>,
    request: &IcSnapshotTransferReadRequest<'_, '_>,
    admitted: &IcSnapshotTransferReadView<'_, '_>,
    qualify: impl AsyncFnOnce(
        &IcSnapshotTransferReadRequest<'_, '_>,
        &IcSnapshotTransferReadResponse,
    ) -> Result<MutationReceiptRequest, E>,
) -> Result<ArtifactChecksumRecord, IcSnapshotMetadataSettlementError<E>> {
    let receipt = qualify(request, admitted.response())
        .await
        .map_err(IcSnapshotMetadataSettlementError::Qualification)?;
    let evidence = super::qualified_receipt::record_applied(
        journal,
        receipt,
        request.mutation_attempt(),
        request.payload().digest().hash(),
        IcSnapshotMetadataSettlementError::ReceiptRequired,
        || {
            let digest = match admitted.reply() {
                IcSnapshotTransferReadReply::Metadata(metadata) => metadata.digest(),
                IcSnapshotTransferReadReply::Data(_) => {
                    return Err(IcSnapshotMetadataSettlementError::ReceiptRequired);
                }
            };
            stage.layout()?;
            Ok(digest)
        },
    )?;
    stage.layout()?;
    Ok(evidence)
}

/// Metadata coordination failures retain exact original spending and returned evidence.
#[derive(Debug, Error)]
pub enum IcSnapshotMetadataExecutionError<E: std::error::Error + 'static> {
    /// The original plan is not exactly this single metadata operation.
    #[error("snapshot metadata requires an exact singleton original stage")]
    OriginalMismatch,
    /// Canonical single-read failure, including any bounded returned response.
    #[error(transparent)]
    Read(#[from] IcSnapshotTransferReadExecutionError<E>),
    /// Receipt qualification failed after a response; all originals remain retained.
    #[error("snapshot metadata reply settlement failed: {source}")]
    AfterReply {
        /// Exact original rejection; no retry or refund follows.
        source: IcSnapshotMetadataSettlementError<E>,
        /// Original bounded reply and passive claims.
        response: Box<IcSnapshotTransferReadResponse>,
    },
}

/// Rejection after one returned metadata reply; no second accounting owner.
#[derive(Debug, Error)]
pub enum IcSnapshotMetadataSettlementError<E: std::error::Error + 'static> {
    /// Actual authentication, attribution or durable original-byte retention failed.
    #[error("snapshot metadata qualification failed: {0}")]
    Qualification(#[source] E),
    /// Require an independently qualified exact original Applied receipt.
    #[error("snapshot metadata requires an explicit original Applied receipt")]
    ReceiptRequired,
    /// Original stage or retained ancestor admission failed.
    #[error(transparent)]
    Stage(#[from] ExecutionWorkflowPersistenceError),
    /// Original selected journal or receipt admission failed.
    #[error(transparent)]
    Journal(#[from] AttemptJournalError),
}

impl<E: std::error::Error + 'static> IcSnapshotMetadataExecutionError<E> {
    /// Borrow the bounded returned evidence carried by this error, including nested failures.
    /// Absence describes retained evidence only and grants no dispatch or retry authority.
    #[must_use]
    pub fn response(&self) -> Option<&IcSnapshotTransferReadResponse> {
        match self {
            Self::AfterReply { response, .. } => Some(response),
            Self::Read(source) => source.response(),
            Self::OriginalMismatch => None,
        }
    }
}

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