canic_core/
lib.rs

1//! Core Canic library used inside canisters.
2//!
3//! Most users should depend on the `canic` facade crate, which re-exports this crate
4//! under `canic::core` and exposes 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/` contains pure value and decision helpers.
14//! - `ops/` provides mechanical, reusable side-effecting operations.
15//! - `storage/` owns stable-memory-backed schemas and helpers.
16//! - `view/` exposes internal read-only projections over stored/runtime state.
17//! - macro entrypoints live in the `canic` facade crate.
18//!
19//! The default flow is: endpoints → workflow → domain/decision helpers → ops → storage.
20
21#[doc(hidden)]
22pub mod access;
23pub mod api;
24#[doc(hidden)]
25pub mod bootstrap;
26pub mod cdk;
27#[doc(hidden)]
28pub mod control_plane_support;
29#[doc(hidden)]
30pub mod dispatch;
31pub mod dto;
32#[doc(hidden)]
33pub mod error;
34mod format;
35pub mod ids;
36#[doc(hidden)]
37pub mod ingress;
38pub mod log;
39pub mod memory;
40mod memory_macros;
41pub mod perf;
42pub mod protocol;
43#[doc(hidden)]
44pub mod shared_support;
45#[cfg(test)]
46pub mod test;
47
48pub(crate) mod config;
49pub(crate) mod domain;
50pub(crate) mod infra;
51pub(crate) mod lifecycle;
52pub(crate) mod ops;
53pub(crate) mod storage;
54pub(crate) mod view;
55pub(crate) mod workflow;
56
57pub(crate) use error::{InternalError, InternalErrorClass, InternalErrorOrigin};
58
59/// Internal re-exports required for macro expansion.
60/// Not part of the public API.
61#[doc(hidden)]
62pub mod __reexports {
63    pub use ::ic_memory;
64    pub use ::ic_memory::__reexports::ctor;
65}
66
67///
68/// Consts
69///
70
71pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
72pub const VERSION: &str = env!("CARGO_PKG_VERSION");
73pub const CANIC_MEMORY_MIN: u8 = storage::stable::CANIC_MEMORY_MIN;
74pub const CANIC_MEMORY_MAX: u8 = storage::stable::CANIC_MEMORY_MAX;
75// Canonical hardcoded 1 MiB chunk size for Canic wasm staging/install flows.
76// The management canister wasm chunk store rejects larger payloads.
77pub const CANIC_WASM_CHUNK_BYTES: usize = 1_048_576;
78
79ic_memory::ic_memory_range!(
80    start = storage::stable::CANIC_MEMORY_MIN,
81    end = storage::stable::CANIC_MEMORY_MAX,
82);
83
84#[cfg(test)]
85const _: () = {
86    fn __canic_memory_test_bootstrap() {
87        crate::api::runtime::MemoryRuntimeApi::bootstrap_registry()
88            .expect("test stable-memory bootstrap");
89    }
90
91    #[crate::__reexports::ctor::ctor(
92        unsafe,
93        anonymous,
94        crate_path = crate::__reexports::ctor
95    )]
96    fn __canic_install_memory_test_bootstrap_hook() {
97        crate::memory::runtime::install_test_bootstrap_hook(__canic_memory_test_bootstrap);
98    }
99};
100
101#[macro_export]
102macro_rules! perf {
103    ($($label:tt)*) => {{
104        $crate::perf::PERF_LAST.with(|last| {
105            let now = $crate::perf::perf_counter();
106            let then = *last.borrow();
107            let delta = now.saturating_sub(then);
108
109            *last.borrow_mut() = now;
110
111            let label = format!($($label)*);
112            $crate::perf::record_checkpoint(module_path!(), &label, delta);
113        });
114    }};
115}
116
117#[cfg(test)]
118#[macro_export]
119macro_rules! assert_err_variant {
120    ($err:expr, $pat:pat $(if $guard:expr)? $(,)?) => {{
121        match $err {
122            $pat $(if $guard)? => {}
123            other => panic!("unexpected error variant: {other:?}"),
124        }
125    }};
126}
127
128#[cfg(test)]
129mod memory_bootstrap_tests {
130    #[test]
131    fn installs_host_test_bootstrap_hook() {
132        assert!(crate::memory::runtime::has_test_bootstrap_hook());
133    }
134}
canic_core/lib.rs

canic_core/
lib.rs
