canic_core/api/rpc/
mod.rs

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

canic_core/api/rpc/
mod.rs
