canic_core/
lib.rs

1//! Core Canic library used inside canisters.
2//!
3//! Canister roles should depend on the `canic` facade crate, which exposes the
4//! supported API/DTO/ID surfaces and the common entrypoint macros:
5//! - `canic::build!` (in `build.rs`) to validate/embed `canic.toml`
6//! - `canic::start!` (in `lib.rs`) to wire lifecycle hooks and export endpoints
7//!
8//! ## Layering
9//!
10//! Canic is organized to keep endpoint code thin and coordination centralized:
11//! - `access/` contains access expressions, predicates, and metrics for boundary enforcement.
12//! - `workflow/` implements orchestration and lifecycle workflows.
13//! - `domain/policy/pure/` contains pure policy decisions invoked by workflow.
14//! - `ops/` provides deterministic state access, conversion, and approved single-step effects.
15//! - `model/` owns authoritative runtime state and storage invariants.
16//! - `storage/` contains passive persisted schemas and stable-memory representations.
17//! - `view/` exposes internal read-only projections over stored/runtime state.
18//! - macro entrypoints live in the `canic` facade crate.
19//!
20//! Endpoints call workflow, which may call policy and ops independently.
21//! Ops may call model; policy never calls ops.
22
23#[doc(hidden)]
24pub mod access;
25pub mod api;
26#[doc(hidden)]
27pub mod bootstrap;
28#[doc(hidden)]
29pub mod cdk;
30#[doc(hidden)]
31pub mod control_plane_support;
32pub mod diagnostics;
33#[doc(hidden)]
34pub mod dispatch;
35pub mod dto;
36#[doc(hidden)]
37mod error;
38mod format;
39pub mod ids;
40#[doc(hidden)]
41pub mod ingress;
42pub mod log;
43pub mod memory;
44mod memory_macros;
45pub mod perf;
46pub mod protocol;
47pub mod replay_policy;
48#[doc(hidden)]
49pub mod role_contract;
50#[doc(hidden)]
51pub mod shared_support;
52#[doc(hidden)]
53pub mod state_contract;
54#[cfg(test)]
55pub mod test;
56
57pub(crate) mod config;
58pub(crate) mod domain;
59pub(crate) mod infra;
60pub(crate) mod lifecycle;
61pub(crate) mod model;
62pub(crate) mod ops;
63pub(crate) mod storage;
64pub(crate) mod view;
65pub(crate) mod workflow;
66
67pub(crate) use error::InternalError;
68
69/// Internal re-exports required for macro expansion.
70/// Not part of the public API.
71#[doc(hidden)]
72pub mod __reexports {
73    pub use ::ic_memory;
74    pub use ::ic_memory::__reexports::ctor;
75}
76
77///
78/// Consts
79///
80
81pub const VERSION: &str = env!("CARGO_PKG_VERSION");
82// Canonical hardcoded 1 MiB chunk size for Canic wasm staging/install flows.
83// The management canister wasm chunk store rejects larger payloads.
84pub const CANIC_WASM_CHUNK_BYTES: usize = 1_048_576;
85/// Existing byte-lane envelope, including bounded publication metadata.
86pub const CANIC_WASM_CHUNK_REQUEST_MAX_BYTES: usize = CANIC_WASM_CHUNK_BYTES + 64 * 1024;
87
88crate::ic_memory_range!(
89    authority = CANIC_CORE_MEMORY_AUTHORITY,
90    start = role_contract::allocation::CANIC_CORE_MIN_ID,
91    end = role_contract::allocation::CANIC_CORE_LOWER_MAX_ID,
92);
93crate::ic_memory_range!(
94    authority = CANIC_CORE_MEMORY_AUTHORITY,
95    start = role_contract::allocation::CANIC_CORE_UPPER_MIN_ID,
96    end = role_contract::allocation::CANIC_CORE_MAX_ID,
97);
98ic_memory_range!(
99    authority = CANIC_CORE_MEMORY_AUTHORITY,
100    start = role_contract::allocation::CANIC_CORE_AUTH_MIN_ID,
101    end = role_contract::allocation::CANIC_CORE_AUTH_MAX_ID,
102);
103
104#[cfg(test)]
105const _: () = {
106    fn __canic_memory_test_bootstrap() {
107        crate::api::runtime::MemoryRuntimeApi::bootstrap_registry()
108            .expect("test stable-memory bootstrap");
109    }
110
111    #[crate::__reexports::ctor::ctor(
112        unsafe,
113        anonymous,
114        crate_path = crate::__reexports::ctor
115    )]
116    fn __canic_install_memory_test_bootstrap_hook() {
117        crate::memory::runtime::install_test_bootstrap_hook(__canic_memory_test_bootstrap);
118    }
119};
120
121#[macro_export]
122macro_rules! perf {
123    ($($label:tt)*) => {{
124        $crate::perf::PERF_LAST.with(|last| {
125            let now = $crate::perf::perf_counter();
126            let then = *last.borrow();
127            let delta = now.saturating_sub(then);
128
129            *last.borrow_mut() = now;
130
131            let label = format!($($label)*);
132            $crate::perf::record_checkpoint(module_path!(), &label, delta);
133        });
134    }};
135}
136
137#[cfg(test)]
138#[macro_export]
139macro_rules! assert_err_variant {
140    ($err:expr, $pat:pat $(if $guard:expr)? $(,)?) => {{
141        match $err {
142            $pat $(if $guard)? => {}
143            other => panic!("unexpected error variant: {other:?}"),
144        }
145    }};
146}
147
148#[cfg(test)]
149mod memory_bootstrap_tests {
150    #[test]
151    fn installs_host_test_bootstrap_hook() {
152        assert!(crate::memory::runtime::has_test_bootstrap_hook());
153    }
154}
canic_core/lib.rs

canic_core/
lib.rs
