canic-core 0.86.3

Canic — a canister orchestration and management toolkit for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! Module: ops::storage::children
//!
//! Responsibility: expose deterministic direct-child cache reads and imports.
//! Does not own: topology cascade workflow, subnet registry truth, or endpoint DTOs.
//! Boundary: storage ops facade over child cache records.

mod mapper;

use crate::{
    dto::canister::CanisterInfo,
    ops::{
        ic::IcOps,
        prelude::*,
        runtime::env::EnvOps,
        storage::{children::mapper::CanisterRecordMapper, registry::subnet::SubnetRegistryOps},
    },
    storage::{
        canister::{CanisterEntryRecord, CanisterRecord},
        stable::children::{CanisterChildren, CanisterChildrenData},
    },
};

///
/// CanisterChildrenOps
///
/// Storage-ops facade for the direct-child cache.
///
/// Invariant: the children cache is updated only via the topology cascade workflow.
///

pub struct CanisterChildrenOps;

impl CanisterChildrenOps {
    // -------------------------------------------------------------------------
    // Lookup helpers
    // -------------------------------------------------------------------------

    #[must_use]
    pub fn get(pid: Principal) -> Option<CanisterRecord> {
        if EnvOps::is_root() {
            SubnetRegistryOps::get(pid)
        } else {
            CanisterChildren::get(pid)
        }
    }

    #[must_use]
    pub fn role_parent(pid: Principal) -> Option<(CanisterRole, Option<Principal>)> {
        Self::get(pid).map(|record| (record.role, record.parent_pid))
    }

    #[must_use]
    pub fn contains_pid(pid: &Principal) -> bool {
        if EnvOps::is_root() {
            SubnetRegistryOps::children(IcOps::canister_self())
                .iter()
                .any(|entry| &entry.pid == pid)
        } else {
            Self::data().entries.iter().any(|entry| &entry.pid == pid)
        }
    }

    #[must_use]
    pub fn infos() -> Vec<CanisterInfo> {
        Self::records()
            .into_iter()
            .map(|entry| CanisterRecordMapper::record_to_response(entry.pid, entry.record))
            .collect()
    }

    #[must_use]
    fn records() -> Vec<CanisterEntryRecord> {
        if EnvOps::is_root() {
            SubnetRegistryOps::children(IcOps::canister_self())
        } else {
            Self::data().entries
        }
    }

    #[must_use]
    pub fn pids() -> Vec<Principal> {
        Self::records().into_iter().map(|entry| entry.pid).collect()
    }

    // -------------------------------------------------------------------------
    // Canonical data access
    // -------------------------------------------------------------------------

    #[must_use]
    pub fn data() -> CanisterChildrenData {
        CanisterChildren::export()
    }

    pub(crate) fn import_direct_children(
        parent_pid: Principal,
        children: Vec<(Principal, CanisterRole)>,
    ) {
        // Cache entries omit module hash/created_at; canonical data lives in the registry.
        let data = CanisterChildrenData {
            entries: children
                .into_iter()
                .map(|(pid, role)| CanisterEntryRecord {
                    pid,
                    record: CanisterRecord {
                        role,
                        parent_pid: Some(parent_pid),
                        module_hash: None,
                        created_at: 0,
                    },
                })
                .collect(),
        };

        CanisterChildren::import(data);
    }
}