ic_memory/runtime/
diagnostics.rs

1use super::{MemoryRuntime, RuntimeDiagnosticError, RuntimeLifecycle};
2use crate::{
3    AllocationLedger, AllocationPolicy, AllocationSlotDescriptor, DiagnosticCheck, DiagnosticCode,
4    DiagnosticDeclaration, DiagnosticExport, DiagnosticFailure, DiagnosticMemorySize,
5    DiagnosticRangeAuthority, DiagnosticRuntimeBinding, DiagnosticStableCell,
6    DiagnosticStableCellStatus, LedgerCommitError, LedgerPayloadEnvelopeError,
7    MemoryRuntimeDoctorReport, PolicyIdentity, RecoveredLedger, RuntimeBootstrapPolicy,
8    StableCellLedgerRecord,
9    physical::CommitStoreDiagnostic,
10    registry::{SealedDeclarationFingerprint, SealedDeclarationSnapshot},
11    slot::MEMORY_MANAGER_LEDGER_ID,
12    stable_cell::decode_stable_cell_ledger_record_from_memory,
13};
14use ic_stable_structures::Memory;
15use std::{borrow::Cow, fmt::Display};
16
17impl<M: Memory> MemoryRuntime<M> {
18    /// Export this runtime's recovered ledger and live virtual-memory sizes.
19    pub fn diagnostic_export(&self) -> Result<DiagnosticExport, RuntimeDiagnosticError> {
20        if !self.is_bootstrapped() {
21            return Err(RuntimeDiagnosticError::NotBootstrapped);
22        }
23        let record = self.ledger_record_from_memory()?;
24        let (recovered, commit_recovery) = record.store().recover_with_diagnostic();
25        let recovered = recovered?;
26        Ok(self.recovered_diagnostic_export(&recovered, Some(commit_recovery)))
27    }
28
29    /// Diagnose protected commit recovery from this runtime's ledger memory.
30    ///
31    /// This operation is available before bootstrap when the stable-cell
32    /// envelope is readable or the ledger memory is empty.
33    pub fn commit_recovery_diagnostic(
34        &self,
35    ) -> Result<CommitStoreDiagnostic, RuntimeDiagnosticError> {
36        let record = self.ledger_record_from_memory()?;
37        Ok(record.store().physical().diagnostic())
38    }
39
40    /// Build preflight and lifecycle diagnostics for this runtime.
41    ///
42    /// Validation checks the supplied declarations and allocation policy only.
43    /// It does not execute `prepare_bootstrap`, predict its completed set, or
44    /// certify consumer admission. Diagnostics never replay preparation.
45    #[must_use]
46    pub fn doctor_report<P>(
47        &self,
48        declarations: &SealedDeclarationSnapshot,
49        policy: &P,
50    ) -> MemoryRuntimeDoctorReport
51    where
52        P: RuntimeBootstrapPolicy,
53        P::Error: Display,
54    {
55        let stable_cell = self.stable_cell_diagnostic();
56        let (recovered, commit_recovery) = stable_cell
57            .record
58            .as_ref()
59            .map(|record| record.store().recover_with_diagnostic())
60            .map_or((None, None), |(recovered, diagnostic)| {
61                (Some(recovered), Some(diagnostic))
62            });
63        let recovered_for_export = recovered.as_ref().and_then(|result| result.as_ref().ok());
64        let ledger = recovered_for_export
65            .map(|recovered| self.recovered_diagnostic_export(recovered, commit_recovery));
66        let diagnostic_declarations = declarations
67            .registered_declarations()
68            .iter()
69            .map(|registration| {
70                DiagnosticDeclaration::new(
71                    registration.authority(),
72                    registration.declaration().clone(),
73                )
74            })
75            .collect();
76        let registered_records = declarations
77            .registered_ranges()
78            .iter()
79            .map(|registration| registration.record().clone())
80            .collect();
81        let range_authority = DiagnosticRangeAuthority::new(
82            registered_records,
83            declarations.range_authority().clone(),
84        );
85        let tested_policy_identity = policy
86            .runtime_bootstrap_identity()
87            .map_err(|err| DiagnosticFailure::new(DiagnosticCode::PolicyIdentity, err.to_string()));
88        let tested_declaration_fingerprint = declarations.fingerprint();
89        let established_bootstrap_binding = self.established_bootstrap_binding();
90        let bootstrap_binding = diagnostic_bootstrap_binding(
91            &tested_policy_identity,
92            tested_declaration_fingerprint,
93            established_bootstrap_binding.as_ref(),
94        );
95        let validation = match &tested_policy_identity {
96            Ok(_) => diagnostic_validation(declarations, policy, recovered.as_ref()),
97            Err(failure) => DiagnosticCheck::not_run(failure.code, failure.message.clone()),
98        };
99
100        MemoryRuntimeDoctorReport {
101            bootstrapped: self.is_bootstrapped(),
102            tested_policy_identity,
103            tested_declaration_fingerprint,
104            established_bootstrap_binding,
105            bootstrap_binding,
106            ledger_anchor: ledger_anchor_descriptor(),
107            stable_cell: stable_cell.diagnostic,
108            commit_recovery,
109            ledger,
110            registered_declarations: diagnostic_declarations,
111            range_authority,
112            validation,
113        }
114    }
115
116    fn recovered_diagnostic_export(
117        &self,
118        recovered: &RecoveredLedger,
119        commit_recovery: Option<CommitStoreDiagnostic>,
120    ) -> DiagnosticExport {
121        let mut export =
122            DiagnosticExport::from_ledger(recovered.ledger(), ledger_anchor_descriptor());
123        export.commit_recovery = commit_recovery;
124        for record in &mut export.records {
125            let id = record
126                .allocation
127                .slot()
128                .memory_manager_id()
129                .expect("recovered ledger slot");
130            record.memory_size = Some(DiagnosticMemorySize::from_wasm_pages(
131                self.memory(id).size(),
132            ));
133        }
134        export
135    }
136
137    fn established_bootstrap_binding(&self) -> Option<DiagnosticRuntimeBinding> {
138        match &self.lifecycle {
139            RuntimeLifecycle::Unbootstrapped => None,
140            RuntimeLifecycle::Bootstrapped { binding, .. } => Some(DiagnosticRuntimeBinding::new(
141                binding.policy_identity.clone(),
142                binding.source.fingerprint(),
143            )),
144        }
145    }
146
147    fn stable_cell_diagnostic(&self) -> StableCellDiagnostic {
148        let memory = self.memory(MEMORY_MANAGER_LEDGER_ID);
149        let memory_size = DiagnosticMemorySize::from_wasm_pages(memory.size());
150        match decode_stable_cell_ledger_record_from_memory(&memory) {
151            Ok(record) => StableCellDiagnostic {
152                diagnostic: DiagnosticStableCell::new(
153                    if memory_size.wasm_pages == 0 {
154                        DiagnosticStableCellStatus::Empty
155                    } else {
156                        DiagnosticStableCellStatus::Readable
157                    },
158                    memory_size,
159                ),
160                record: Some(record),
161            },
162            Err(err) => StableCellDiagnostic {
163                diagnostic: DiagnosticStableCell::new(
164                    DiagnosticStableCellStatus::Corrupt {
165                        failure: DiagnosticFailure::new(
166                            DiagnosticCode::StableCell,
167                            err.to_string(),
168                        ),
169                    },
170                    memory_size,
171                ),
172                record: None,
173            },
174        }
175    }
176}
177
178struct StableCellDiagnostic {
179    diagnostic: DiagnosticStableCell,
180    record: Option<StableCellLedgerRecord>,
181}
182
183const fn ledger_anchor_descriptor() -> AllocationSlotDescriptor {
184    AllocationSlotDescriptor::memory_manager_unchecked(MEMORY_MANAGER_LEDGER_ID)
185}
186
187fn diagnostic_validation<P: AllocationPolicy>(
188    declarations: &SealedDeclarationSnapshot,
189    custom_policy: &P,
190    recovered: Option<&Result<crate::RecoveredLedger, LedgerCommitError>>,
191) -> DiagnosticCheck
192where
193    P::Error: Display,
194{
195    let recovered = match diagnostic_validation_ledger(recovered) {
196        Ok(recovered) => recovered,
197        Err(failure) => return DiagnosticCheck::not_run(failure.code, failure.message),
198    };
199    let resolved = match declarations.resolve(recovered.ledger(), Vec::new()) {
200        Ok(resolved) => resolved,
201        Err(err) => {
202            return DiagnosticCheck::failed(DiagnosticCode::AllocationValidation, err.to_string());
203        }
204    };
205    let policy = super::policy::RuntimeMemoryManagerPolicy {
206        declarations: &resolved,
207        custom_policy,
208    };
209    match crate::validation::check_allocations(&recovered, resolved.allocation_snapshot(), &policy)
210    {
211        Ok(()) => DiagnosticCheck::passed(),
212        Err(err) => DiagnosticCheck::failed(DiagnosticCode::AllocationValidation, err.to_string()),
213    }
214}
215
216fn diagnostic_bootstrap_binding(
217    tested_policy_identity: &Result<PolicyIdentity, DiagnosticFailure>,
218    tested_declaration_fingerprint: SealedDeclarationFingerprint,
219    established: Option<&DiagnosticRuntimeBinding>,
220) -> DiagnosticCheck {
221    let tested_policy_identity = match tested_policy_identity {
222        Ok(identity) => identity,
223        Err(failure) => {
224            return DiagnosticCheck::not_run(failure.code, failure.message.clone());
225        }
226    };
227    let Some(established) = established else {
228        return DiagnosticCheck::not_run(
229            DiagnosticCode::RuntimeBinding,
230            "runtime has not completed bootstrap",
231        );
232    };
233    if &established.policy_identity == tested_policy_identity
234        && established.declaration_fingerprint == tested_declaration_fingerprint
235    {
236        return DiagnosticCheck::passed();
237    }
238    DiagnosticCheck::failed(
239        DiagnosticCode::RuntimeBinding,
240        format!(
241            "tested policy/declaration binding differs from established runtime binding: \
242             tested_policy={tested_policy_identity:?}, \
243             tested_declarations={tested_declaration_fingerprint:?}, \
244             established={established:?}"
245        ),
246    )
247}
248
249pub(super) fn diagnostic_validation_ledger(
250    recovered: Option<&Result<crate::RecoveredLedger, LedgerCommitError>>,
251) -> Result<Cow<'_, crate::RecoveredLedger>, DiagnosticFailure> {
252    if let Some(Ok(recovered)) = recovered {
253        return Ok(Cow::Borrowed(recovered));
254    }
255    if let Some(Err(err)) = recovered {
256        // Protected recovery returns NoValidGeneration only for two absent slots.
257        if matches!(
258            err,
259            LedgerCommitError::Recovery(crate::CommitRecoveryError::NoValidGeneration)
260        ) {
261            return Ok(Cow::Owned(RecoveredLedger::from_trusted_ledger(
262                AllocationLedger::empty_genesis(),
263            )));
264        }
265        let code = if matches!(
266            err,
267            LedgerCommitError::PayloadEnvelope(
268                LedgerPayloadEnvelopeError::UnsupportedFormat { .. }
269            )
270        ) {
271            DiagnosticCode::UnsupportedFormat
272        } else {
273            DiagnosticCode::LedgerRecovery
274        };
275        return Err(DiagnosticFailure::new(
276            code,
277            format!("protected ledger recovery: {err}"),
278        ));
279    }
280    Err(DiagnosticFailure::new(
281        DiagnosticCode::StableCell,
282        "stable-cell ledger record is not readable",
283    ))
284}
ic_memory/runtime/diagnostics.rs

ic_memory/runtime/
diagnostics.rs
