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 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;
26#[doc(hidden)]
27pub mod control_plane_support;
28#[doc(hidden)]
29pub mod dispatch;
30pub mod dto;
31#[doc(hidden)]
32pub mod error;
33mod format;
34pub mod ids;
35#[doc(hidden)]
36pub mod ingress;
37pub mod log;
38pub mod perf;
39pub mod protocol;
40#[doc(hidden)]
41pub mod shared_support;
42#[cfg(test)]
43pub mod test;
44
45pub(crate) mod config;
46pub(crate) mod domain;
47pub(crate) mod infra;
48pub(crate) mod lifecycle;
49pub(crate) mod ops;
50pub(crate) mod storage;
51pub(crate) mod view;
52pub(crate) mod workflow;
53
54pub use {
55    ::canic_cdk as cdk,
56    ::canic_memory as memory,
57    ::canic_memory::{eager_init, eager_static, ic_memory, ic_memory_range},
58};
59
60pub(crate) use error::{InternalError, InternalErrorClass, InternalErrorOrigin};
61
62/// Internal re-exports required for macro expansion.
63/// Not part of the public API.
64#[doc(hidden)]
65pub mod __reexports {
66    pub use ::ctor;
67}
68
69///
70/// Consts
71///
72
73pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
74pub const VERSION: &str = env!("CARGO_PKG_VERSION");
75pub const CANIC_MEMORY_MIN: u8 = storage::stable::CANIC_MEMORY_MIN;
76pub const CANIC_MEMORY_MAX: u8 = storage::stable::CANIC_MEMORY_MAX;
77// Canonical hardcoded 1 MiB chunk size for Canic wasm staging/install flows.
78// The management canister wasm chunk store rejects larger payloads.
79pub const CANIC_WASM_CHUNK_BYTES: usize = 1_048_576;
80
81#[cfg(test)]
82const _: () = {
83    use std::sync::Once;
84
85    fn __canic_memory_test_bootstrap() {
86        static ONCE: Once = Once::new();
87
88        ONCE.call_once(|| {
89            crate::api::runtime::MemoryRuntimeApi::bootstrap_registry()
90                .expect("test stable-memory bootstrap");
91        });
92    }
93
94    #[canic_memory::__reexports::ctor::ctor(
95        unsafe,
96        anonymous,
97        crate_path = canic_memory::__reexports::ctor
98    )]
99    fn __canic_install_memory_test_bootstrap_hook() {
100        canic_memory::runtime::install_test_bootstrap_hook(__canic_memory_test_bootstrap);
101    }
102};
103
104#[macro_export]
105macro_rules! perf {
106    ($($label:tt)*) => {{
107        $crate::perf::PERF_LAST.with(|last| {
108            let now = $crate::perf::perf_counter();
109            let then = *last.borrow();
110            let delta = now.saturating_sub(then);
111
112            *last.borrow_mut() = now;
113
114            let label = format!($($label)*);
115            $crate::perf::record_checkpoint(module_path!(), &label, delta);
116        });
117    }};
118}
119
120#[cfg(test)]
121#[macro_export]
122macro_rules! assert_err_variant {
123    ($err:expr, $pat:pat $(if $guard:expr)? $(,)?) => {{
124        match $err {
125            $pat $(if $guard)? => {}
126            other => panic!("unexpected error variant: {other:?}"),
127        }
128    }};
129}
130
131#[cfg(test)]
132mod memory_bootstrap_tests {
133    #[test]
134    fn installs_host_test_bootstrap_hook() {
135        assert!(canic_memory::runtime::has_test_bootstrap_hook());
136    }
137}
canic_core/lib.rs

canic_core/
lib.rs
