canic_core/api/rpc/
mod.rs

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

canic_core/api/rpc/
mod.rs
