pub struct DownloadJournalGuard<'a> { /* private fields */ }Expand description
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§
Source§impl DownloadJournalGuard<'_>
impl DownloadJournalGuard<'_>
Sourcepub fn verify_durable_artifacts<'a>(
&'a self,
plan: &'a OperationPlanRecord,
) -> Result<DurableDownloadView<'a>, DownloadIntegrityError>
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.
Source§impl DownloadJournalGuard<'_>
impl DownloadJournalGuard<'_>
Sourcepub 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>
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.
Sourcepub 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>
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.
Source§impl DownloadJournalGuard<'_>
impl DownloadJournalGuard<'_>
Sourcepub 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>
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.
Sourcepub 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>
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.
Source§impl DownloadJournalGuard<'_>
impl DownloadJournalGuard<'_>
Sourcepub 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>
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.
Source§impl DownloadJournalGuard<'_>
impl DownloadJournalGuard<'_>
Sourcepub fn read_download_manifest(
&self,
plan: &OperationPlanRecord,
expected: &ArtifactChecksumRecord,
) -> Result<DownloadJournalRecord, DownloadManifestError>
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.
Sourcepub fn publish_download_manifest(
&self,
plan: &OperationPlanRecord,
) -> Result<ArtifactChecksumRecord, DownloadManifestError>
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.
Source§impl<'a> DownloadJournalGuard<'a>
impl<'a> DownloadJournalGuard<'a>
Sourcepub fn create(
layout: &'a BackupLayoutGuard,
intent: &str,
artifacts: Vec<DownloadArtifactRequest>,
) -> Result<Self, DownloadJournalError>
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.
Sourcepub fn open(
layout: &'a BackupLayoutGuard,
expected_intent: &str,
) -> Result<Self, DownloadJournalError>
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.
Sourcepub fn record(&self) -> Result<&DownloadJournalRecord, DownloadJournalError>
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.
Sourcepub fn path(&self) -> PathBuf
pub fn path(&self) -> PathBuf
Return the canonical journal location whose sidecar this guard owns.
Sourcepub fn record_downloaded(
&mut self,
canister: &str,
snapshot: &str,
) -> Result<(), DownloadJournalError>
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.
Sourcepub fn verify_artifact(
&mut self,
canister: &str,
snapshot: &str,
) -> Result<(), DownloadJournalError>
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.
Sourcepub fn finalize_artifact(
&mut self,
canister: &str,
snapshot: &str,
) -> Result<(), DownloadJournalError>
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.