Struct DownloadJournalGuard 

pub struct DownloadJournalGuard<'a> { /* private fields */ }

Exclusive local lifecycle access borrowing the stable backup layout guard.

The caller owns backend artifact completeness and fresh remote authority. These operations never invoke a transport, remove staging or release references.

Implementations

impl DownloadJournalGuard<'_>

pub fn prepare_ic_snapshot_upload_metadata<'source>( &self, plan: &'source OperationPlanRecord, snapshot: &str, metadata: &'source IcSnapshotMetadataReply<'source>, ) -> Result<IcSnapshotUploadRequest<'source>, IcSnapshotUploadArtifactError>

Freshly verify an original published IC source and encode exact upload metadata.

Requires the full retained source plan, unchanged journal and complete Durable selection. Target remains the source canister and replacement stays absent. The payload must precede its separately retained original upload plan/reservation. Stable future bytes, authentic source, actual context/permissions and same-release restore obligations stay integration-owned. Nothing is written or dispatched.

Errors

Rejects original/byte/custody drift or unrepresentable original metadata.

pub fn prepare_ic_snapshot_upload_data<'source>( &self, plan: &OperationPlanRecord, snapshot: &str, metadata_upload: &IcSnapshotUploadRequest<'source>, snapshot_id: &[u8], source_kind: SnapshotDataKind, ) -> Result<IcSnapshotUploadRequest<'source>, IcSnapshotUploadArtifactError>

Read one bounded exact source extent/chunk and encode a distinct destination ID.

Fresh full IC-tree verification before/after descriptor-relative reading binds actual bytes to the original metadata/checksum and guarded source plan/journal. This is an explicit local byte operation, not resume or a transfer-completion view. Only one <=1 MiB chunk is buffered; no aggregate region or allowance is allocated. The caller qualifies destination allocation and retains the new exact data intent before its own reservation. No source/restore reference, journal or fence changes.

Errors

Rejects wrong source declaration, ranges/hash/IDs, changed/unsafe files or custody, short reads, encoding failures and mismatching retained original evidence.

impl DownloadJournalGuard<'_>

pub fn verify_ic_snapshot_artifact( &self, plan: &OperationPlanRecord, snapshot: &str, metadata: &IcSnapshotMetadataReply<'_>, ) -> Result<ArtifactChecksumRecord, IcSnapshotArtifactError>

Explicitly verify one published IC tree against exact original metadata and intent.

Requires the retained full plan, unchanged held journal and complete Durable selected set. Only this target’s artifact bytes are read. The fixed format, original metadata/request hashes, region lengths, known bounded chunk hashes and closed direct-child tree must match the retained checksum. No metadata defaults, generic-token/raw-ID inference or progress reconstruction occurs.

Reads use no-follow descriptors and a bounded checksum buffer; journal and directory identities are rechecked at closing. These sequential observations cannot fence noncooperating writers or hold fresh byte custody after return. The returned checksum is passive local evidence. Integrations still qualify authentic complete transfer, token association, fresh permission/accounting, stable byte/command custody and upload/load/start safety. Nothing is written, spent, settled or released; ordinary resume never invokes this check.

Errors

Rejects wrong original evidence, incomplete selection, changed records/custody, missing/unsafe/extra children, wrong bounded lengths/hashes and IO failure.

impl<'layout> DownloadJournalGuard<'layout>

pub fn stage_ic_snapshot_artifact<'journal, 'metadata>( &'journal mut self, snapshot: &str, metadata: &'metadata IcSnapshotMetadataReply<'metadata>, raw_metadata: &[u8], ) -> Result<IcSnapshotArtifactWriter<'journal, 'layout, 'metadata>, IcSnapshotArtifactError>

Create private staging for an existing Created artifact and exact decoded metadata.

The exact generic backend token remains unchanged and is not parsed as a raw IC ID. The integration supplies their authoritative association. Target and timestamp must match the retained entry; its independently observed total snapshot size is preserved, never inferred from a sum of metadata regions. Exact original metadata wire bytes and request arguments are retained alongside fixed region/chunk files in a distinct v1 artifact layout. Existing staging/canonical destinations reject without adoption.

Errors

Rejects wrong identity/state/raw metadata, occupied or unsafe paths and IO failure. Failure retains partial bytes and leaves the original journal unchanged.

impl DownloadJournalGuard<'_>

pub fn verify_durable_artifacts<'a>( &'a self, plan: &'a OperationPlanRecord, ) -> Result<DurableDownloadView<'a>, DownloadIntegrityError>

Explicitly reverify every published artifact under the retained original plan.

Requires the exact persisted plan and unchanged held journal before and after no-follow checksumming. The returned view borrows journal/layout custody. This reads local bytes; ordinary journal reopen/resume remains effect-free and does not trigger verification. Nothing is written, pruned or released.

File checks are sequential observations, not an atomic filesystem snapshot. Integrations retain stable byte custody and qualify complete backend transfer, authentic snapshot/receipt identity and terminal/reference-release evidence.

Errors

Rejects unusable/replaced custody, missing/changed plans or journals, incomplete exact selected coverage, non-durable entries, unsafe/missing trees and changed bytes.

impl DownloadJournalGuard<'_>

pub fn publish_staged_local_restore_artifact<'a>( &'a self, restore_layout: &'a BackupLayoutGuard, restore: &'a OperationPlanRecord, source: &'a OperationPlanRecord, requirement: &'a RestoreSafetyRequirementRecord, operation_sequence: u64, ) -> Result<(LocalRestoreArtifactView<'a>, ArtifactCommitOutcome), LocalRestoreArtifactPublicationError>

Durably publish an exact staged restore artifact, or recover its canonical copy.

Re-admit the exact retained original plans/requirement/manifest/source journal, then reuse no-follow synchronization, checksum verification and atomic no-replace publication from restore-artifact-{sequence}.tmp to restore-artifact-{sequence}. The operation lock is shared with staging and verification. Both layouts and the source journal remain borrowed; original records are re-admitted after publication.

Returns the freshly checked canonical view and explicit Published/Recovered outcome. Recovery verifies and synchronizes the existing canonical tree, without copying or reading source artifact trees. Both paths present, neither present, changed/unsafe bytes or original metadata mismatch reject without replacement, repair or cleanup. Failure may leave publication complete; recover the exact paths before other work. No journal, attempt, fence, obligation or source reference changes.

Stable noncooperating parent/byte custody remains integration-owned. This local publication grants no complete backend transfer, authentic snapshot, signing, upload/load/start, application safety, terminal or fence/reference-release authority. Ordinary resume and terminal replay never invoke this explicit fresh operation.

Errors

Rejects unknown operation, original custody/identity drift, contention, missing or conflicting paths, unsafe/changed bytes, synchronization failure or lost IO replies.

pub fn verify_published_local_restore_artifact<'a>( &'a self, restore_layout: &'a BackupLayoutGuard, restore: &'a OperationPlanRecord, source: &'a OperationPlanRecord, requirement: &'a RestoreSafetyRequirementRecord, operation_sequence: u64, ) -> Result<LocalRestoreArtifactView<'a>, LocalRestoreArtifactError>

Freshly verify an exact retained canonical restore copy without republishing it.

Checks retained original metadata and canonical bytes under the same operation lock as staging/publication, without source-tree reads, copying or fsync. A path alone proves no earlier durable publication; this view is fresh local integrity. Ordinary resume/terminal replay performs no such verification. Failures retain all bytes, original spending, obligations and references without repair/cleanup.

Errors

Rejects missing/unsafe/changed canonical copies, original drift or contention.

impl DownloadJournalGuard<'_>

pub fn stage_local_restore_artifact<'a>( &'a self, restore_layout: &'a BackupLayoutGuard, restore: &'a OperationPlanRecord, source: &'a OperationPlanRecord, requirement: &'a RestoreSafetyRequirementRecord, operation_sequence: u64, ) -> Result<LocalRestoreArtifactView<'a>, LocalRestoreArtifactError>

Create an exact private artifact copy for one original selected restore operation.

Complete original source verification precedes descriptor-based no-follow copying to fixed restore-artifact-{sequence}.tmp directly under the held restore layout. Existing destinations are never adopted, replaced or deleted. Copy hash and fresh destination hash must equal the original artifact checksum; retained declarations are re-admitted before returning. Directories/files are private 0700/0600. This is staging, without fsync/durable publication or dispatch; explicit publication is a separate operation. Failures/drop retain partial bytes and all original spending/references. After a lost reply, explicitly verify the retained copy; an invalid partial copy needs operator-owned disposition. Stable noncooperating destination custody remains integration-owned. The operation sequence associates bytes, not effect authority.

Errors

Rejects unknown original operations, changed/unsafe source or copy, contention, existing destinations, lost IO replies and original record/custody mismatch.

pub fn verify_staged_local_restore_artifact<'a>( &'a self, restore_layout: &'a BackupLayoutGuard, restore: &'a OperationPlanRecord, source: &'a OperationPlanRecord, requirement: &'a RestoreSafetyRequirementRecord, operation_sequence: u64, ) -> Result<LocalRestoreArtifactView<'a>, LocalRestoreArtifactError>

Explicitly check a retained private copy against exact original declarations.

Reads retained original plans/requirement/manifest/journal and the copy’s bytes, without re-reading source trees or repeating a copy. Original source trees may be absent; exact retained metadata remains required. Missing/unsafe/incomplete or conflicting copies are retained, never repaired or recreated. This is fresh local copy verification, not ordinary resume/terminal replay or effect authority.

Errors

Rejects original identity/custody mismatch, unknown operations, unsafe/missing copies, checksum drift and contention without altering recovery evidence.

impl DownloadJournalGuard<'_>

pub fn verify_local_restore_source<'a>( &'a self, restore_layout: &'a BackupLayoutGuard, restore: &'a OperationPlanRecord, source: &'a OperationPlanRecord, requirement: &'a RestoreSafetyRequirementRecord, ) -> Result<LocalRestoreSourceView<'a>, LocalRestoreSourceError>

Freshly verify the complete original local source and project exact restore artifacts.

The source journal borrows its source layout; the returned view also borrows the restore layout, both plans and original safety requirement. Exact retained requirement/plans, manifest and journal are admitted before and after fresh no-follow verification of every original source artifact, including any outside a restore subset. Replay/ordinary resume never invoke this separate operation. No records, allowances, references or fences change; no provider is invoked. Integrations own stable noncooperating bytes, authenticated snapshot/transfer completeness and application subset safety. Success grants no upload/load, current permissions, signing, fence/reference release or terminal authority.

Errors

Rejects absent/unsafe/changed originals, another source digest, non-durable or incomplete selected sets, changed bytes, replaced custody and contention.

impl DownloadJournalGuard<'_>

pub fn read_download_manifest( &self, plan: &OperationPlanRecord, expected: &ArtifactChecksumRecord, ) -> Result<DownloadJournalRecord, DownloadManifestError>

Replay exact manifest evidence while borrowing the already-held original journal.

Requires the retained plan and unchanged guarded journal before/after admission, without acquiring a second journal lock or reading artifact trees. This grants no current byte, backend, application or effect authority.

Errors

Rejects unsafe/missing/changed originals, wrong identity and manifest contention.

pub fn publish_download_manifest( &self, plan: &OperationPlanRecord, ) -> Result<ArtifactChecksumRecord, DownloadManifestError>

Freshly verify and immutably publish the exact original durable download set.

Reuses the existing journal schema/identity owner and guarded no-follow byte verification. The private bounded file is never replaced. An existing file or lost publication reply requires explicit exact local replay. This changes no journal, spending or references and invokes no provider. Stable byte custody, complete transfer, authenticated snapshots and consistency remain integration-owned; this is not the full product backup manifest/terminal proof.

Errors

Rejects original/evidence/byte drift, incomplete sets, contention and publication failures.

impl DownloadJournalGuard<'_>

pub fn ic_snapshot_metrics(&self) -> IcSnapshotLocalMetrics

Read a copied local diagnostic snapshot without filesystem IO or fresh checks.

Sampling is per guard lifetime, including rejected calls; ordinary journal replay never supplies samples. Poison recovery is diagnostic only and cannot change an operation result. No labels, IDs, byte contents or global registry are retained. Host monotonic durations measure inclusive local work, not IC instructions/cycles, unique transfer progress or an authoritative receipt.

impl<'a> DownloadJournalGuard<'a>

pub fn create( layout: &'a BackupLayoutGuard, intent: &str, artifacts: Vec<DownloadArtifactRequest>, ) -> Result<Self, DownloadJournalError>

Exclusively create exact intent and snapshot identities without replacing evidence.

Errors

Rejects existing/unsafe journals, locked or replaced layouts and invalid/bounded records.

pub fn open( layout: &'a BackupLayoutGuard, expected_intent: &str, ) -> Result<Self, DownloadJournalError>

Open retained bounded v1 evidence under exact caller-supplied intent.

Reads only local journal evidence; it does not reverify artifacts or remote state.

Errors

Rejects missing/unsafe/corrupt journals, intent mismatch and locked/replaced layouts.

pub fn record(&self) -> Result<&DownloadJournalRecord, DownloadJournalError>

Read retained progress; failed publication requires reopening before further use.

Errors

Rejects an indeterminate write outcome or a replaced layout.

pub fn path(&self) -> PathBuf

Return the canonical journal location whose sidecar this guard owns.

pub fn record_downloaded( &mut self, canister: &str, snapshot: &str, ) -> Result<(), DownloadJournalError>

Retain the caller’s complete-download attestation for the exact snapshot.

Requires a safe existing staging directory. The caller must already have validated complete backend metadata/extent coverage and command quiescence; traversability alone does not establish IC transfer completeness.

Errors

Rejects identity/state conflicts, unsafe or missing staging and failed persistence.

pub fn verify_artifact( &mut self, canister: &str, snapshot: &str, ) -> Result<(), DownloadJournalError>

Verify staged bytes and durably retain their canonical checksum.

Errors

Rejects wrong identity/state, unsafe or missing bytes and failed persistence.

pub fn finalize_artifact( &mut self, canister: &str, snapshot: &str, ) -> Result<(), DownloadJournalError>

Publish exact verified bytes or adopt a matching tree after a lost response.

Leaves staging and retained intent intact on rejection. Durable state does not silently trigger fresh artifact verification; that is a distinct action.

Errors

Rejects wrong identity/state, changed bytes, unsafe paths and uncertain publication.

Trait Implementations

impl<'a> Debug for DownloadJournalGuard<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.