canic-core 0.100.29

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
117
118
119
120
121
122
123

//! Module: workflow::env
//!
//! Responsibility: validate and initialize runtime environment state from bootstrap args.
//! Does not own: endpoint authorization, stable env storage, or env policy rules.
//! Boundary: workflow layer between lifecycle bootstrap input, policy, and env ops.

pub mod query;

use crate::{
    InternalError, InternalErrorOrigin,
    config::ComponentTopologyError,
    domain::policy::pure::env::{EnvInput, EnvPolicyError, validate_or_default},
    dto::env::EnvBootstrapArgs,
    ids::{
        CanisterRole, ComponentBinding, ComponentChildBinding, FleetSubnetRootBinding,
        ManagedCanisterBinding,
    },
    model::env::ValidatedEnv,
    ops::{
        config::ConfigOps,
        ic::{IcOps, build_network::BuildNetworkOps},
        runtime::env::EnvOps,
    },
};

///
/// EnvWorkflow
///

pub struct EnvWorkflow;

impl EnvWorkflow {
    pub fn init_env_from_args(
        env_args: EnvBootstrapArgs,
        role: CanisterRole,
    ) -> Result<(), InternalError> {
        BuildNetworkOps::build_network().ok_or_else(|| {
            InternalError::invariant(
                InternalErrorOrigin::Workflow,
                "build network unavailable; set ICP_ENVIRONMENT=local|ic at build time".to_string(),
            )
        })?;

        let input = EnvInput {
            fleet_root_pid: env_args.fleet_root_pid,
            component_spec: env_args.component_spec,
            subnet_pid: env_args.subnet_pid,
            root_pid: env_args.root_pid,
            canister_role: Some(role),
            parent_pid: env_args.parent_pid,
        };

        let validated = match validate_or_default(input) {
            Ok(validated) => validated,
            Err(EnvPolicyError::MissingEnvFields(missing)) => {
                return Err(InternalError::invariant(
                    InternalErrorOrigin::Workflow,
                    format!("env args missing {missing}; local builds require explicit env fields"),
                ));
            }
        };

        EnvOps::import_validated(validated)
    }

    /// Initialize a top-level Component from exact root-issued Registry authority.
    pub fn init_component(
        root: &FleetSubnetRootBinding,
        binding: ComponentBinding,
        compiled_role: &CanisterRole,
    ) -> Result<(), InternalError> {
        let topology = ConfigOps::component_topology()?;
        topology
            .validate_component_binding(root, &binding)
            .map_err(map_binding_error)?;
        if &binding.role != compiled_role || binding.canister_id != IcOps::canister_self() {
            return Err(InternalError::invalid_input(
                "Component init authority differs from the compiled role or target Canister",
            ));
        }

        EnvOps::import_validated(ValidatedEnv {
            managed_binding: Some(ManagedCanisterBinding::Component(binding.clone())),
            fleet_root_pid: root.fleet_subnet_root,
            component_spec: Some(binding.component_spec),
            subnet_pid: root.fleet_subnet_root,
            root_pid: root.fleet_subnet_root,
            canister_role: binding.role,
            parent_pid: root.fleet_subnet_root,
        })
    }

    /// Initialize one Component descendant from exact root-issued Registry authority.
    pub fn init_component_child(
        root: &FleetSubnetRootBinding,
        binding: ComponentChildBinding,
        compiled_role: &CanisterRole,
    ) -> Result<(), InternalError> {
        let topology = ConfigOps::component_topology()?;
        topology
            .validate_component_child_binding(root, &binding)
            .map_err(map_binding_error)?;
        if &binding.role != compiled_role || binding.canister_id != IcOps::canister_self() {
            return Err(InternalError::invalid_input(
                "Component-child init authority differs from the compiled role or target Canister",
            ));
        }

        EnvOps::import_validated(ValidatedEnv {
            managed_binding: Some(ManagedCanisterBinding::ComponentChild(binding.clone())),
            fleet_root_pid: root.fleet_subnet_root,
            component_spec: Some(binding.component.component_spec),
            subnet_pid: root.fleet_subnet_root,
            root_pid: root.fleet_subnet_root,
            canister_role: binding.role,
            parent_pid: binding.parent_canister_id,
        })
    }
}

fn map_binding_error(error: ComponentTopologyError) -> InternalError {
    InternalError::invalid_input(format!("managed init authority is invalid: {error}"))
}