ic_backup/model/ic_snapshot_transfer_read/
mod.rs

1//! Exact originally reserved metadata/data reads; no dispatch or transfer attestation.
2
3use crate::model::attempt_journal::MutationReservation;
4use crate::model::attempt_journal::MutationReservationError as Reservation;
5use crate::model::ic_update_response::IcUpdateResponseInput;
6use crate::model::{
7    artifacts::ArtifactChecksumRecord,
8    attempt_journal::{AttemptAuthorityRecord, AttemptJournalRecord},
9    ic_snapshot_data::{IcSnapshotDataRequest, MAX_IC_SNAPSHOT_DATA_REPLY_BYTES},
10    ic_snapshot_metadata::IcSnapshotMetadataRequest,
11    operation_plan::{OperationPlanError, OperationPlanRecord},
12};
13use std::fmt;
14use thiserror::Error;
15
16/// The existing two bounded replicated-update read payloads; no new encoder.
17#[derive(Clone, Copy, Debug)]
18pub enum IcSnapshotTransferReadPayload<'request, 'metadata> {
19    /// Read the exact original raw snapshot ID's metadata.
20    Metadata(&'request IcSnapshotMetadataRequest),
21    /// Read one metadata-bound range or known chunk hash.
22    Data(&'request IcSnapshotDataRequest<'metadata>),
23}
24
25impl<'request> IcSnapshotTransferReadPayload<'request, '_> {
26    pub(crate) fn validate_binding(
27        &self,
28        authority: &AttemptAuthorityRecord,
29    ) -> Result<(), IcSnapshotTransferReadError> {
30        if self.target() != authority.binding().target()
31            || self.digest().hash() != authority.binding().request()
32        {
33            return Err(IcSnapshotTransferReadError::PayloadMismatch);
34        }
35        Ok(())
36    }
37    /// Read the canonical effective routing target.
38    #[must_use]
39    pub fn target(&self) -> &'request str {
40        match self {
41            Self::Metadata(payload) => payload.target(),
42            Self::Data(payload) => payload.target(),
43        }
44    }
45    /// Read the management receiver; both methods use host replicated updates.
46    #[must_use]
47    pub const fn receiver(&self) -> &'static str {
48        match self {
49            Self::Metadata(payload) => payload.receiver(),
50            Self::Data(payload) => payload.receiver(),
51        }
52    }
53    /// Read the exact original method name.
54    #[must_use]
55    pub const fn method(&self) -> &'static str {
56        match self {
57            Self::Metadata(payload) => payload.method(),
58            Self::Data(payload) => payload.method(),
59        }
60    }
61    /// Read existing canonical bounded Candid bytes.
62    #[must_use]
63    pub fn arguments(&self) -> &'request [u8] {
64        match self {
65            Self::Metadata(payload) => payload.arguments(),
66            Self::Data(payload) => payload.arguments(),
67        }
68    }
69    /// Reuse the original nonrecursive wire digest; metadata evidence stays separate.
70    #[must_use]
71    pub fn digest(&self) -> ArtifactChecksumRecord {
72        match self {
73            Self::Metadata(payload) => payload.digest(),
74            Self::Data(payload) => payload.digest(),
75        }
76    }
77}
78
79/// Full original plan and already consumed update reservation for one transfer read.
80///
81/// A semantic read still uses replicated update ingress and the existing mutation
82/// reservation lane. It grants no fresh permission or proof of never-dispatched
83/// custody; reconstruction never permits repeating a lost read.
84#[derive(Debug)]
85pub struct IcSnapshotTransferReadRequest<'request, 'metadata> {
86    plan: &'request OperationPlanRecord,
87    payload: IcSnapshotTransferReadPayload<'request, 'metadata>,
88    reservation: MutationReservation,
89}
90
91impl<'request, 'metadata> IcSnapshotTransferReadRequest<'request, 'metadata> {
92    /// Bind exact original target/wire bytes and immutable original allowance.
93    /// # Errors
94    /// Rejects another plan/operation/payload, absent or changed update reservation,
95    /// or already pending recovery. Creates no journal and spends nothing.
96    pub fn new(
97        plan: &'request OperationPlanRecord,
98        operation_sequence: u64,
99        journal: &AttemptJournalRecord,
100        payload: IcSnapshotTransferReadPayload<'request, 'metadata>,
101    ) -> Result<Self, IcSnapshotTransferReadError> {
102        let authority = plan.attempt_authority_for_journal(
103            operation_sequence,
104            journal,
105            IcSnapshotTransferReadError::AuthorityMismatch,
106        )?;
107        payload.validate_binding(&authority)?;
108        let reservation = MutationReservation::new(authority, journal)?;
109        Ok(Self {
110            plan,
111            payload,
112            reservation,
113        })
114    }
115    /// Read full original context, inventory, graph and allowances.
116    #[must_use]
117    pub const fn plan(&self) -> &'request OperationPlanRecord {
118        self.plan
119    }
120    /// Read the exact metadata/data payload without reconstructing its bytes.
121    #[must_use]
122    pub const fn payload(&self) -> IcSnapshotTransferReadPayload<'request, 'metadata> {
123        self.payload
124    }
125    /// Read the full original operation authority.
126    #[must_use]
127    pub const fn authority(&self) -> &AttemptAuthorityRecord {
128        &self.reservation.authority
129    }
130    /// Read the already consumed replicated-update attempt.
131    #[must_use]
132    pub const fn mutation_attempt(&self) -> u32 {
133        self.reservation.mutation_attempt
134    }
135    /// Recheck original reservation before passive response association.
136    /// # Errors
137    /// Rejects changed authority, settled/replaced update or pending recovery.
138    pub fn validate_journal(
139        &self,
140        journal: &AttemptJournalRecord,
141    ) -> Result<(), IcSnapshotTransferReadError> {
142        self.reservation.validate(journal).map_err(Into::into)
143    }
144}
145
146/// Bounded immutable raw reply, with no receipt, persisted authority or default.
147#[derive(Clone)]
148pub struct IcSnapshotTransferReadResponse {
149    input: IcUpdateResponseInput,
150}
151
152impl IcSnapshotTransferReadResponse {
153    /// Admit the existing finite raw-data ceiling and original attempt range.
154    /// # Errors
155    /// Rejects invalid attempt, excessive bytes and invalid target principals.
156    pub fn new(mut input: IcUpdateResponseInput) -> Result<Self, IcSnapshotTransferReadError> {
157        input.admit(MAX_IC_SNAPSHOT_DATA_REPLY_BYTES)?;
158        Ok(Self { input })
159    }
160    /// Read exact retained claims and raw bytes; no mutable access is exposed.
161    #[must_use]
162    pub const fn input(&self) -> &IcUpdateResponseInput {
163        &self.input
164    }
165}
166
167impl fmt::Debug for IcSnapshotTransferReadResponse {
168    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
169        self.input
170            .fmt_redacted(formatter, "IcSnapshotTransferReadResponse")
171    }
172}
173
174/// Structural read rejection; every denial retains original accounting and evidence.
175#[derive(Debug, Error)]
176pub enum IcSnapshotTransferReadError {
177    /// Current journal differs from full original authority.
178    #[error("snapshot transfer read authority differs")]
179    AuthorityMismatch,
180    /// Original target or exact wire digest differs.
181    #[error("snapshot transfer read payload differs")]
182    PayloadMismatch,
183    /// No original replicated-update reservation is pending.
184    #[error("snapshot transfer read requires a pending original update")]
185    NoPendingMutation,
186    /// Original update was changed or settled.
187    #[error("snapshot transfer read original attempt differs")]
188    MutationMismatch,
189    /// Existing recovery observation remains pending.
190    #[error("snapshot transfer read recovery observation is pending")]
191    ObservationPending,
192    /// Attempt is outside the existing 1..=1,024 bound.
193    #[error("invalid snapshot transfer read attempt")]
194    InvalidAttempt,
195    /// Raw reply exceeds the existing 2 MiB data wire ceiling.
196    #[error("snapshot transfer read reply too large")]
197    ReplyTooLarge,
198    /// Claimed actual target is not a principal.
199    #[error("invalid snapshot transfer read target")]
200    InvalidTarget,
201    /// Original plan cannot derive this operation authority.
202    #[error(transparent)]
203    Plan(#[from] OperationPlanError),
204}
205
206impl From<crate::model::attempt_journal::MutationReservationError> for IcSnapshotTransferReadError {
207    fn from(error: crate::model::attempt_journal::MutationReservationError) -> Self {
208        match error {
209            Reservation::NoPendingMutation => Self::NoPendingMutation,
210            Reservation::AuthorityMismatch => Self::AuthorityMismatch,
211            Reservation::MutationMismatch => Self::MutationMismatch,
212            Reservation::ObservationPending => Self::ObservationPending,
213        }
214    }
215}
216
217impl From<crate::model::ic_update_response::UpdateResponseAdmissionError>
218    for IcSnapshotTransferReadError
219{
220    fn from(error: crate::model::ic_update_response::UpdateResponseAdmissionError) -> Self {
221        match error {
222            crate::model::ic_update_response::UpdateResponseAdmissionError::InvalidAttempt => {
223                Self::InvalidAttempt
224            }
225            crate::model::ic_update_response::UpdateResponseAdmissionError::ReplyTooLarge => {
226                Self::ReplyTooLarge
227            }
228            crate::model::ic_update_response::UpdateResponseAdmissionError::InvalidTarget => {
229                Self::InvalidTarget
230            }
231        }
232    }
233}
ic_backup/model/ic_snapshot_transfer_read/mod.rs

ic_backup/model/ic_snapshot_transfer_read/
mod.rs
