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!` / `canic::build_root!` (in `build.rs`) to validate/embed `canic.toml`
6//! - `canic::start!` / `canic::start_root!` (in `lib.rs`) to wire lifecycle hooks and export endpoints
7//!
8//! ## Layering
9//!
10//! Canic is organized to keep endpoint code thin and policies centralized:
11//! - `access/` contains access expressions, predicates, and metrics for boundary enforcement.
12//! - `workflow/` implements orchestration and lifecycle workflows.
13//! - `policy/` owns deterministic decision rules.
14//! - `ops/` provides mechanical, reusable side-effecting operations.
15//! - `model/` owns storage (stable memory) and in-process registries/caches.
16//! - macro entrypoints live in the `canic` facade crate.
17//!
18//! The default flow is: endpoints → workflow → policy → ops → model.
19
20#[doc(hidden)]
21pub mod __control_plane_core;
22#[doc(hidden)]
23pub mod access;
24pub mod api;
25#[doc(hidden)]
26pub mod bootstrap;
27#[doc(hidden)]
28pub mod dispatch;
29pub mod dto;
30#[doc(hidden)]
31pub mod error;
32mod format;
33pub mod ids;
34pub mod log;
35pub mod perf;
36pub mod protocol;
37#[cfg(test)]
38pub mod test;
39
40pub(crate) mod config;
41pub(crate) mod domain;
42pub(crate) mod infra;
43pub(crate) mod lifecycle;
44pub(crate) mod ops;
45pub(crate) mod storage;
46pub(crate) mod view;
47pub(crate) mod workflow;
48
49pub use {
50    ::canic_cdk as cdk,
51    ::canic_memory as memory,
52    ::canic_memory::{eager_init, eager_static, ic_memory, ic_memory_range},
53};
54
55pub(crate) use error::{InternalError, InternalErrorClass, InternalErrorOrigin};
56
57/// Internal re-exports required for macro expansion.
58/// Not part of the public API.
59#[doc(hidden)]
60pub mod __reexports {
61    pub use ::ctor;
62}
63
64///
65/// Consts
66///
67
68pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
69pub const VERSION: &str = env!("CARGO_PKG_VERSION");
70pub const CANIC_MEMORY_MIN: u8 = storage::stable::CANIC_MEMORY_MIN;
71pub const CANIC_MEMORY_MAX: u8 = storage::stable::CANIC_MEMORY_MAX;
72// Canonical hardcoded 1 MiB chunk size for Canic wasm staging/install flows.
73// The management canister wasm chunk store rejects larger payloads.
74pub const CANIC_WASM_CHUNK_BYTES: usize = 1_048_576;
75
76#[macro_export]
77macro_rules! perf {
78    ($($label:tt)*) => {{
79        $crate::perf::PERF_LAST.with(|last| {
80            let now = $crate::perf::perf_counter();
81            let then = *last.borrow();
82            let delta = now.saturating_sub(then);
83
84            *last.borrow_mut() = now;
85
86            let label = format!($($label)*);
87            $crate::perf::record_checkpoint(module_path!(), &label, delta);
88        });
89    }};
90}
91
92#[cfg(test)]
93#[macro_export]
94macro_rules! assert_err_variant {
95    ($err:expr, $pat:pat $(if $guard:expr)? $(,)?) => {{
96        match $err {
97            $pat $(if $guard)? => {}
98            other => panic!("unexpected error variant: {other:?}"),
99        }
100    }};
101}
canic_core/lib.rs

canic_core/
lib.rs
