canic_core/api/rpc/
mod.rs

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

canic_core/api/rpc/
mod.rs
