ic_backup/model/ic_snapshot_metadata/

mod.rs

//! Bounded snapshot metadata reads; decoded declarations do not prove transfer.

mod wire;

use super::{
    artifacts::ArtifactChecksumRecord,
    ic_request::{IcRequestError, admits_snapshot_id, encode_arguments, management_request_digest},
};
use ic_platform::Principal;
use ic_platform::management_canister_types::{
    ReadCanisterSnapshotMetadataArgs, ReadCanisterSnapshotMetadataResult,
};
use std::fmt;
use thiserror::Error;

/// Maximum raw metadata reply bytes, checked before decoding.
pub const MAX_IC_SNAPSHOT_METADATA_BYTES: usize = 1024 * 1024;
/// Local bound on ordered exported globals, including unavailable slots.
pub const MAX_IC_SNAPSHOT_GLOBALS: usize = 4096;
/// Local bound on distinct SHA-256 chunk-store entries.
pub const MAX_IC_SNAPSHOT_CHUNKS: usize = 1024;

/// Exact ephemeral metadata-read payload for one retained raw snapshot identity.
///
/// This separate transfer read leaves the six-method lifecycle/recovery record
/// unchanged. It carries no plan, reservation, signing, freshness or permissions.
/// Integrations own authenticated snapshot association and prior per-call accounting.
#[derive(Clone)]
pub struct IcSnapshotMetadataRequest {
    target: String,
    principal: Principal,
    snapshot_id: Vec<u8>,
    arguments: Vec<u8>,
}

impl IcSnapshotMetadataRequest {
    /// Normalize the target and encode the pinned upstream argument shape.
    ///
    /// # Errors
    /// Rejects malformed principals, empty/oversized raw identifiers, encoding
    /// failure or arguments exceeding the existing 4 KiB request bound.
    pub fn new(target: &str, snapshot_id: &[u8]) -> Result<Self, IcRequestError> {
        if !admits_snapshot_id(snapshot_id) {
            return Err(IcRequestError::InvalidSnapshotId);
        }
        let (target, principal) =
            super::principal::canonical_parts(target).ok_or(IcRequestError::InvalidTarget)?;
        let arguments = encode_arguments(ReadCanisterSnapshotMetadataArgs {
            canister_id: principal.into(),
            snapshot_id: snapshot_id.to_vec(),
        })?;
        Ok(Self {
            target,
            principal,
            snapshot_id: snapshot_id.to_vec(),
            arguments,
        })
    }

    pub(crate) const fn principal(&self) -> Principal {
        self.principal
    }

    /// Read the canonical effective routing target, also encoded in the arguments.
    #[must_use]
    pub fn target(&self) -> &str {
        &self.target
    }

    /// Read exact raw snapshot bytes, distinct from a generic backend token.
    #[must_use]
    pub fn snapshot_id(&self) -> &[u8] {
        &self.snapshot_id
    }

    /// Read exact Candid arguments; no transport or dispatch is installed.
    #[must_use]
    pub fn arguments(&self) -> &[u8] {
        &self.arguments
    }

    /// Read the fixed management receiver, separate from the routing target.
    #[must_use]
    pub const fn receiver(&self) -> &'static str {
        "aaaaa-aa"
    }

    /// Read the sole method, using replicated host update ingress.
    #[must_use]
    pub const fn method(&self) -> &'static str {
        "read_canister_snapshot_metadata"
    }

    /// Hash exact receiver/routing/update-mode/method/arguments with the existing owner.
    #[must_use]
    pub fn digest(&self) -> ArtifactChecksumRecord {
        management_request_digest(self.principal.as_slice(), self.method(), &self.arguments)
    }
}

impl fmt::Debug for IcSnapshotMetadataRequest {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("IcSnapshotMetadataRequest")
            .field("target", &self.target)
            .field("snapshot_id_bytes", &self.snapshot_id.len())
            .finish_non_exhaustive()
    }
}

/// Read-only pinned metadata and exact raw evidence under a declared request.
///
/// Optional source, unavailable globals and optional timer/hook fields retain
/// their actual presence. Missing information is not a default or upload input.
/// Floating globals retain their bits; globals and chunk rows retain wire order.
/// This evidence grants no complete transfer, authentic origin or effect outcome.
pub struct IcSnapshotMetadataReply<'request> {
    request: &'request IcSnapshotMetadataRequest,
    metadata: ReadCanisterSnapshotMetadataResult,
    payload_checksum: ArtifactChecksumRecord,
}

impl<'request> IcSnapshotMetadataReply<'request> {
    pub(crate) fn region_sizes(&self) -> [u64; 3] {
        [
            self.metadata.wasm_module_size,
            self.metadata.wasm_memory_size,
            self.metadata.stable_memory_size,
        ]
    }

    pub(crate) fn chunk_index(&self, hash: &[u8]) -> Option<usize> {
        self.metadata
            .wasm_chunk_store
            .iter()
            .position(|chunk| chunk.hash == hash)
    }

    /// Decode one bounded metadata argument without skipped fields or extra bytes.
    ///
    /// # Errors
    /// Rejects excessive raw bytes, malformed/unsupported wire values, sequence
    /// bounds, certified data above 32 bytes, non-SHA-256/duplicate chunk hashes
    /// and v128 globals outside their unsigned 128-bit range.
    pub fn decode(
        request: &'request IcSnapshotMetadataRequest,
        bytes: &[u8],
    ) -> Result<Self, IcSnapshotMetadataError> {
        if bytes.len() > MAX_IC_SNAPSHOT_METADATA_BYTES {
            return Err(IcSnapshotMetadataError::ReplyTooLarge);
        }
        let metadata = wire::decode(bytes)?;
        Ok(Self {
            request,
            metadata,
            payload_checksum: ArtifactChecksumRecord::from_bytes(bytes),
        })
    }

    /// Read the exact declared request; the reply wire authenticates no target.
    #[must_use]
    pub const fn request(&self) -> &'request IcSnapshotMetadataRequest {
        self.request
    }

    /// Read admitted pinned DTO values without mutation access.
    #[must_use]
    pub const fn metadata(&self) -> &ReadCanisterSnapshotMetadataResult {
        &self.metadata
    }

    /// Read SHA-256 of exact raw bytes, including optional fields and wire ordering.
    #[must_use]
    pub const fn payload_checksum(&self) -> &ArtifactChecksumRecord {
        &self.payload_checksum
    }

    /// Bind original request and raw reply checksums in the metadata evidence domain.
    #[must_use]
    pub fn digest(&self) -> ArtifactChecksumRecord {
        super::evidence_digest::reply(
            b"ic-backup/ic-snapshot-metadata-reply/v1\0",
            [&self.request.digest(), &self.payload_checksum],
        )
    }
}

impl fmt::Debug for IcSnapshotMetadataReply<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("IcSnapshotMetadataReply")
            .field("request", &self.request)
            .field("payload_checksum", &self.payload_checksum)
            .finish_non_exhaustive()
    }
}

/// Typed metadata admission errors, excluding raw bytes and decoder diagnostics.
#[derive(Debug, Error, Eq, PartialEq)]
pub enum IcSnapshotMetadataError {
    /// Input exceeded the local raw-byte bound before parsing.
    #[error("snapshot metadata exceeds {MAX_IC_SNAPSHOT_METADATA_BYTES} bytes")]
    ReplyTooLarge,
    /// Wire shape, finite work, sequence or certified-data bounds failed.
    #[error("invalid or unsupported snapshot metadata reply")]
    InvalidReply,
    /// A v128 value exceeded its unsigned 128-bit representation.
    #[error("snapshot v128 global exceeds 128 bits")]
    InvalidGlobal,
    /// Chunk identities must be distinct exact SHA-256 hashes.
    #[error("snapshot chunk hash is not a unique 32-byte identity")]
    InvalidChunkHash,
}

#[cfg(test)]
mod tests;