ic_mple_client 0.11.0

Simple client abstraction to interact with the Internet Computer canisters
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

use std::sync::Arc;

use candid::utils::ArgumentEncoder;
use candid::{CandidType, Decode, Principal};
use pocket_ic::common::rest::RawMessageId;
use pocket_ic::nonblocking::*;
use serde::de::DeserializeOwned;

use crate::{CanisterClient, CanisterClientResult};

/// A client for interacting with a canister inside dfinity's PocketIc test framework.
#[derive(Clone)]
pub struct PocketIcClient {
    client: Option<Arc<PocketIc>>,
    pub canister: Principal,
    pub caller: Principal,
}

impl PocketIcClient {
    /// Creates a new instance of a PocketIcClient.
    /// The new instance is independent and have no access to canisters of other instances.
    pub async fn new(canister: Principal, caller: Principal) -> Self {
        Self::from_client(PocketIc::new().await, canister, caller)
    }

    /// Crates new instance of PocketIcClient from an existing client instance.
    pub fn from_client<P: Into<Arc<PocketIc>>>(
        client: P,
        canister: Principal,
        caller: Principal,
    ) -> Self {
        Self {
            client: Some(client.into()),
            canister,
            caller,
        }
    }

    /// Returns the PocketIC client for the canister.
    pub fn client(&self) -> &PocketIc {
        self.client
            .as_ref()
            .expect("PocketIC client is not available")
    }

    /// Performs an update call with the given arguments.
    pub async fn update_call<T, R>(&self, method: &str, args: T) -> CanisterClientResult<R>
    where
        T: ArgumentEncoder + Send + Sync,
        R: DeserializeOwned + CandidType,
    {
        let args = candid::encode_args(args)?;

        let call_result = self
            .client()
            .update_call(self.canister, self.caller, method, args)
            .await?;

        let decoded = Decode!(&call_result, R)?;
        Ok(decoded)
    }

    /// Performs a query call with the given arguments.
    pub async fn query_call<T, R>(&self, method: &str, args: T) -> CanisterClientResult<R>
    where
        T: ArgumentEncoder + Send + Sync,
        R: DeserializeOwned + CandidType,
    {
        let args = candid::encode_args(args)?;

        let call_result = self
            .client()
            .query_call(self.canister, self.caller, method, args)
            .await?;

        let decoded = Decode!(&call_result, R)?;
        Ok(decoded)
    }

    /// Submit an update call (without executing it immediately).
    pub async fn submit_call<T>(&self, method: &str, args: T) -> CanisterClientResult<RawMessageId>
    where
        T: ArgumentEncoder + Send + Sync,
    {
        let args = candid::encode_args(args)?;

        let msg_id = self
            .client()
            .submit_call(self.canister, self.caller, method, args)
            .await?;

        Ok(msg_id)
    }

    /// Await an update call submitted previously by `submit_call`.
    pub async fn await_call<R>(&self, msg_id: RawMessageId) -> CanisterClientResult<R>
    where
        R: DeserializeOwned + CandidType,
    {
        let call_result = self.client().await_call(msg_id).await?;
        let decoded = Decode!(&call_result, R)?;
        Ok(decoded)
    }
}

impl CanisterClient for PocketIcClient {
    async fn update<T, R>(&self, method: &str, args: T) -> CanisterClientResult<R>
    where
        T: ArgumentEncoder + Send + Sync,
        R: DeserializeOwned + CandidType + Send,
    {
        PocketIcClient::update_call(self, method, args).await
    }

    async fn query<T, R>(&self, method: &str, args: T) -> CanisterClientResult<R>
    where
        T: ArgumentEncoder + Send + Sync,
        R: DeserializeOwned + CandidType + Send,
    {
        PocketIcClient::query_call(self, method, args).await
    }
}