canic/
lib.rs

1//! Canic facade crate.
2//!
3//! This crate is the recommended dependency for downstream canister projects. It
4//! re-exports the public Canic runtime surface and provides the common macro entry points:
5//!
6//! - `build!` / `build_root!` for `build.rs` (validate/embed `canic.toml`)
7//! - `start!` / `start_root!` for `lib.rs` (wire lifecycle hooks and export endpoints)
8//!
9//! For lower-level access, use the `api`, `cdk`, `memory`, and `utils` modules.
10//! Direct access to internal core modules is intentionally unsupported.
11
12mod macros; // private implementation boundary
13
14#[doc(hidden)]
15pub mod __internal {
16    // NOTE:
17    // This module exists ONLY for macro expansion.
18    // Do NOT re-export canic_core publicly.
19    pub use canic_core as core;
20}
21
22// -----------------------------------------------------------------------------
23// Public data contracts
24// -----------------------------------------------------------------------------
25// DTOs, IDs, and protocol definitions are stable, versioned contracts intended
26// for downstream use (candid, RPC, tests, tooling).
27pub use canic_core::{dto, ids, protocol};
28
29// -----------------------------------------------------------------------------
30// Sub-crates
31// -----------------------------------------------------------------------------
32pub use canic_cdk as cdk;
33pub use canic_dsl as dsl;
34pub use canic_memory as memory;
35pub use canic_utils as utils;
36
37// -----------------------------------------------------------------------------
38// Re-exports
39// -----------------------------------------------------------------------------
40pub use canic_core::dto::error::Error;
41pub use canic_dsl_macros::{canic_query, canic_update};
42pub use canic_memory::{
43    eager_init, eager_static, ic_memory, ic_memory_range, impl_storable_bounded,
44    impl_storable_unbounded,
45};
46
47// -----------------------------------------------------------------------------
48// Access predicates
49// -----------------------------------------------------------------------------
50pub mod access {
51    pub use crate::__internal::core::access::auth::authenticated;
52    pub use crate::__internal::core::access::{AccessError, app, auth, env};
53}
54
55// -----------------------------------------------------------------------------
56// Constants
57// -----------------------------------------------------------------------------
58
59pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
60pub const VERSION: &str = env!("CARGO_PKG_VERSION");
61
62// -----------------------------------------------------------------------------
63// Prelude
64// -----------------------------------------------------------------------------
65
66///
67/// Opinionated prelude for Canic canister crates.
68///
69/// Prefer importing from the prelude in your canister `lib.rs` to keep endpoint
70/// modules small and consistent. Library crates and shared modules should
71/// generally import from specific paths instead of pulling in the entire prelude.
72///
73
74pub mod prelude {
75    pub use crate::{
76        api::{
77            canister::CanisterRole,
78            ic::Call,
79            ops::{log, perf},
80            timer::{timer, timer_interval},
81        },
82        cdk::{
83            api::{canister_self, msg_caller},
84            candid::CandidType,
85            export_candid,
86        },
87    };
88
89    pub use canic_dsl_macros::{canic_query, canic_update};
90}
91
92///
93/// Structured public runtime API surface.
94///
95/// This module groups Canic’s runtime capabilities by intent (auth, calls,
96/// canister topology, observability, scheduling) rather than mirroring internal
97/// core layout.
98///
99
100pub mod api {
101
102    /// Delegation workflow helpers
103    pub mod auth {
104        pub use crate::__internal::core::api::auth::DelegationApi;
105    }
106
107    /// Environment queries
108    pub mod env {
109        pub use crate::__internal::core::api::env::EnvQuery;
110    }
111
112    /// IC primitives (calls, HTTP, crypto, network, system APIs)
113    pub mod ic {
114        pub use crate::__internal::core::api::ic::call::{
115            Call, CallBuilder, CallResult, IntentKey, IntentReservation,
116        };
117
118        pub mod http {
119            pub use crate::__internal::core::api::ic::http::HttpApi;
120        }
121
122        pub mod network {
123            pub use crate::__internal::core::api::ic::network::NetworkApi;
124        }
125    }
126
127    /// Canister lifecycle, placement, and topology
128    pub mod canister {
129        pub use crate::__internal::core::ids::CanisterRole;
130
131        pub mod children {
132            pub use crate::__internal::core::api::topology::children::CanisterChildrenApi;
133        }
134
135        pub mod directory {
136            pub use crate::__internal::core::api::topology::directory::{
137                AppDirectoryApi, SubnetDirectoryApi,
138            };
139        }
140
141        pub mod placement {
142            pub use crate::__internal::core::api::placement::{
143                scaling::ScalingApi, sharding::ShardingApi,
144            };
145        }
146
147        pub mod wasm {
148            pub use crate::__internal::core::api::wasm::WasmApi;
149        }
150    }
151
152    /// RPC abstractions (non-IC-specific)
153    pub mod rpc {
154        pub use crate::__internal::core::api::rpc::RpcApi;
155    }
156
157    /// Observability and operational helpers
158    pub mod ops {
159        pub use crate::__internal::core::{log, perf};
160    }
161
162    /// Protocol (protocol runtime services)
163    pub mod protocol {
164        pub mod icrc21 {
165            pub use crate::__internal::core::dispatch::icrc21::Icrc21Dispatcher;
166        }
167    }
168
169    /// Timers and scheduling helpers
170    pub mod timer {
171        pub use crate::{timer, timer_interval};
172    }
173}
canic/lib.rs

canic/
lib.rs
