canic_core/api/rpc/
mod.rs

1mod capability;
2
3use crate::{
4    cdk::{candid::CandidType, types::Principal},
5    dto::{
6        capability::{
7            NonrootCyclesCapabilityEnvelopeV1, NonrootCyclesCapabilityResponseV1,
8            RootCapabilityEnvelopeV1, RootCapabilityResponseV1,
9        },
10        error::Error,
11        rpc::{
12            CreateCanisterParent, CreateCanisterResponse, CyclesResponse, UpgradeCanisterResponse,
13        },
14    },
15    ids::CanisterRole,
16    workflow::rpc::request::RpcRequestWorkflow,
17};
18
19///
20/// RpcApi
21///
22/// Public, user-callable wrappers for Canic's internal RPC workflows.
23///
24/// These functions:
25/// - form part of the public API surface
26/// - are safe to call from downstream canister `lib.rs` code
27/// - return [`Error`] suitable for IC boundaries
28///
29/// Internally, they delegate to workflow-level RPC implementations,
30/// preserving the layering:
31///
32///   user canister -> api -> workflow -> ops -> infra
33///
34/// Workflow returns internal [`InternalError`]; conversion to [`Error`]
35/// happens exclusively at this API boundary.
36///
37
38pub struct RpcApi;
39
40impl RpcApi {
41    /// Dispatch the full root capability envelope verifier/orchestrator path.
42    pub async fn response_capability_v1_root(
43        envelope: RootCapabilityEnvelopeV1,
44    ) -> Result<RootCapabilityResponseV1, Error> {
45        capability::response_capability_v1_root(envelope).await
46    }
47
48    /// Dispatch the non-root structural cycles capability path.
49    pub async fn response_capability_v1_nonroot(
50        envelope: NonrootCyclesCapabilityEnvelopeV1,
51    ) -> Result<NonrootCyclesCapabilityResponseV1, Error> {
52        capability::response_capability_v1_nonroot(envelope).await
53    }
54
55    pub async fn create_canister_request<A>(
56        canister_role: &CanisterRole,
57        parent: CreateCanisterParent,
58        extra: Option<A>,
59    ) -> Result<CreateCanisterResponse, Error>
60    where
61        A: CandidType + Send + Sync,
62    {
63        RpcRequestWorkflow::create_canister_request(canister_role, parent, extra)
64            .await
65            .map_err(Error::from)
66    }
67
68    pub async fn upgrade_canister_request(
69        canister_pid: Principal,
70    ) -> Result<UpgradeCanisterResponse, Error> {
71        RpcRequestWorkflow::upgrade_canister_request(canister_pid)
72            .await
73            .map_err(Error::from)
74    }
75
76    pub async fn request_cycles(cycles: u128) -> Result<CyclesResponse, Error> {
77        RpcRequestWorkflow::request_cycles(cycles)
78            .await
79            .map_err(Error::from)
80    }
81
82    pub async fn response_capability_v1(
83        envelope: RootCapabilityEnvelopeV1,
84    ) -> Result<RootCapabilityResponseV1, Error> {
85        capability::response_capability_v1_root(envelope).await
86    }
87}
canic_core/api/rpc/mod.rs

canic_core/api/rpc/
mod.rs
