ic_backup/ops/persistence/inventory/
mod.rs

1//! Immutable bounded inventory publication and exact local declared-identity admission.
2
3use super::json::check_json_size;
4use super::{
5    BackupLayoutGuard, JournalLock, JournalLockError, PersistenceError, create_json_durable,
6    read_json,
7};
8use crate::model::{
9    artifacts::ArtifactChecksumRecord,
10    inventory::{InventoryRecord, MAX_INVENTORY_BYTES},
11};
12use thiserror::Error;
13
14/// Durably create `inventory.json` under held layout exclusion without replacing evidence.
15///
16/// # Errors
17/// Rejects excessive canonical bytes, existing/unsafe entries, replaced roots and IO/lock failures.
18pub fn create_inventory(
19    layout: &BackupLayoutGuard,
20    record: &InventoryRecord,
21) -> Result<(), InventoryError> {
22    layout.check_root()?;
23    let path = layout.root().join("inventory.json");
24    let _lock = JournalLock::acquire(&path)?;
25    check_json_size(record, MAX_INVENTORY_BYTES)?;
26    create_json_durable(&path, record)?;
27    Ok(())
28}
29
30/// Read bounded validated local inventory under its original expected canonical digest.
31///
32/// This observes no remote membership or state. A failed/lost creation response
33/// may be reconciled by reading the exact declared digest, never overwriting it.
34///
35/// # Errors
36/// Rejects unsafe/missing/oversized records, invalid declarations, digest mismatch and locks.
37pub fn read_inventory(
38    layout: &BackupLayoutGuard,
39    expected: &ArtifactChecksumRecord,
40) -> Result<InventoryRecord, InventoryError> {
41    layout.check_root()?;
42    let path = layout.root().join("inventory.json");
43    let _lock = JournalLock::acquire(&path)?;
44    let record: InventoryRecord = read_json(&path, MAX_INVENTORY_BYTES)?;
45    check_json_size(&record, MAX_INVENTORY_BYTES)?;
46    if &record.digest() != expected {
47        return Err(InventoryError::DigestMismatch);
48    }
49    Ok(record)
50}
51
52/// Typed exact declared-identity or durable local inventory admission failure.
53#[derive(Debug, Error)]
54pub enum InventoryError {
55    /// Canonical retained declaration differs from its original selected digest.
56    #[error("inventory digest mismatch")]
57    DigestMismatch,
58    /// Exclusive layout/journal ownership failed.
59    #[error(transparent)]
60    Lock(#[from] JournalLockError),
61    /// Bounded JSON, model admission or durable filesystem access failed.
62    #[error(transparent)]
63    Persistence(#[from] PersistenceError),
64}
65
66#[cfg(all(test, unix))]
67mod tests;
ic_backup/ops/persistence/inventory/mod.rs

ic_backup/ops/persistence/inventory/
mod.rs
