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 guard/auth/rule helpers 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//! - `macros/` provides public macro entrypoints and endpoint bundles.
17//!
18//! The default flow is: endpoints → workflow → policy → ops → model.
19
20// -----------------------------------------------------------------------------
21// Phase 0: path coherence re-exports (no behavior change)
22// -----------------------------------------------------------------------------
23
24pub mod access; // todo - potentially could be pub(crate) but custom errors would have to change
25pub mod api;
26#[doc(hidden)]
27pub mod dispatch;
28pub mod domain;
29pub mod dto;
30pub mod ids;
31pub mod log;
32pub mod macros;
33pub mod perf;
34pub mod protocol;
35#[cfg(test)]
36pub mod test;
37
38pub(crate) mod config;
39pub(crate) mod infra;
40pub(crate) mod lifecycle;
41pub(crate) mod ops;
42pub(crate) mod storage;
43pub(crate) mod workflow;
44
45pub use {
46    ::canic_cdk as cdk,
47    ::canic_memory as memory,
48    ::canic_memory::{eager_init, eager_static, ic_memory, ic_memory_range},
49    ::canic_utils as utils,
50    dto::error::{Error as PublicError, ErrorCode},
51    thiserror::Error as ThisError,
52};
53
54/// Internal re-exports required for macro expansion.
55/// Not part of the public API.
56#[doc(hidden)]
57pub mod __reexports {
58    pub use ::ctor;
59}
60
61///
62/// Crate Version
63///
64
65pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
66pub const VERSION: &str = env!("CARGO_PKG_VERSION");
67
68///
69/// Error
70///
71/// Internal, structured error type.
72///
73/// This error:
74/// - is NOT Candid-exposed
75/// - is NOT stable across versions
76/// - may evolve freely
77///
78/// All canister endpoints must convert this into a public error envelope
79/// defined in dto/.
80///
81
82#[derive(Debug, ThisError)]
83pub(crate) enum Error {
84    #[error(transparent)]
85    Access(#[from] access::AccessError),
86
87    #[error(transparent)]
88    Config(#[from] config::ConfigError),
89
90    #[error(transparent)]
91    Domain(#[from] domain::DomainError),
92
93    #[error(transparent)]
94    Infra(#[from] infra::InfraError),
95
96    #[error(transparent)]
97    Ops(#[from] ops::OpsError),
98
99    #[error(transparent)]
100    Storage(#[from] storage::StorageError),
101
102    #[error(transparent)]
103    Workflow(#[from] workflow::WorkflowError),
104}
105
106// init and validate config
107// called from here as config is pub(crate)
108pub fn init_config(toml: &str) -> Result<(), String> {
109    config::Config::init_from_toml(toml)
110        .map(|_| ())
111        .map_err(|err| err.to_string())
112}
canic_core/lib.rs

canic_core/
lib.rs
