|
| 1 | +//! Library to mock HTTP outcalls on the Internet Computer leveraging the [`ic_canister_runtime`] crate's |
| 2 | +//! [`Runtime`] trait as well as [`PocketIc`]. |
| 3 | +
|
| 4 | +#![forbid(unsafe_code)] |
| 5 | +#![forbid(missing_docs)] |
| 6 | + |
| 7 | +mod mock; |
| 8 | + |
| 9 | +use async_trait::async_trait; |
| 10 | +use candid::{decode_one, encode_args, utils::ArgumentEncoder, CandidType, Principal}; |
| 11 | +use ic_canister_runtime::{IcError, Runtime}; |
| 12 | +use ic_cdk::call::{CallFailed, CallRejected}; |
| 13 | +use ic_error_types::RejectCode; |
| 14 | +pub use mock::{ |
| 15 | + json::{JsonRpcRequestMatcher, JsonRpcResponse}, |
| 16 | + CanisterHttpReject, CanisterHttpReply, CanisterHttpRequestMatcher, MockHttpOutcall, |
| 17 | + MockHttpOutcallBuilder, MockHttpOutcalls, MockHttpOutcallsBuilder, |
| 18 | +}; |
| 19 | +use pocket_ic::{ |
| 20 | + common::rest::{CanisterHttpRequest, CanisterHttpResponse, MockCanisterHttpResponse}, |
| 21 | + nonblocking::PocketIc, |
| 22 | + RejectResponse, |
| 23 | +}; |
| 24 | +use serde::de::DeserializeOwned; |
| 25 | +use std::{ |
| 26 | + sync::{Arc, Mutex}, |
| 27 | + time::Duration, |
| 28 | +}; |
| 29 | + |
| 30 | +const DEFAULT_MAX_RESPONSE_BYTES: u64 = 2_000_000; |
| 31 | +const MAX_TICKS: usize = 10; |
| 32 | + |
| 33 | +/// [`Runtime`] using [`PocketIc`] to mock HTTP outcalls. |
| 34 | +/// |
| 35 | +/// This runtime allows making calls to canisters through Pocket IC while verifying the HTTP |
| 36 | +/// outcalls made and mocking their responses. |
| 37 | +pub struct MockHttpRuntime { |
| 38 | + env: Arc<PocketIc>, |
| 39 | + caller: Principal, |
| 40 | + mocks: Mutex<MockHttpOutcalls>, |
| 41 | +} |
| 42 | + |
| 43 | +impl MockHttpRuntime { |
| 44 | + /// Create a new [`MockHttpRuntime`] with the given [`PocketIc`] and [`MockHttpOutcalls`]. |
| 45 | + /// All calls to canisters are made using the given caller identity. |
| 46 | + pub fn new(env: Arc<PocketIc>, caller: Principal, mocks: impl Into<MockHttpOutcalls>) -> Self { |
| 47 | + Self { |
| 48 | + env: env.clone(), |
| 49 | + caller, |
| 50 | + mocks: Mutex::new(mocks.into()), |
| 51 | + } |
| 52 | + } |
| 53 | +} |
| 54 | + |
| 55 | +#[async_trait] |
| 56 | +impl Runtime for MockHttpRuntime { |
| 57 | + async fn update_call<In, Out>( |
| 58 | + &self, |
| 59 | + id: Principal, |
| 60 | + method: &str, |
| 61 | + args: In, |
| 62 | + _cycles: u128, |
| 63 | + ) -> Result<Out, IcError> |
| 64 | + where |
| 65 | + In: ArgumentEncoder + Send, |
| 66 | + Out: CandidType + DeserializeOwned, |
| 67 | + { |
| 68 | + let message_id = self |
| 69 | + .env |
| 70 | + .submit_call( |
| 71 | + id, |
| 72 | + self.caller, |
| 73 | + method, |
| 74 | + encode_args(args).unwrap_or_else(panic_when_encode_fails), |
| 75 | + ) |
| 76 | + .await |
| 77 | + .unwrap(); |
| 78 | + self.execute_mocks().await; |
| 79 | + self.env |
| 80 | + .await_call(message_id) |
| 81 | + .await |
| 82 | + .map(decode_call_response) |
| 83 | + .map_err(parse_reject_response)? |
| 84 | + } |
| 85 | + |
| 86 | + async fn query_call<In, Out>( |
| 87 | + &self, |
| 88 | + id: Principal, |
| 89 | + method: &str, |
| 90 | + args: In, |
| 91 | + ) -> Result<Out, IcError> |
| 92 | + where |
| 93 | + In: ArgumentEncoder + Send, |
| 94 | + Out: CandidType + DeserializeOwned, |
| 95 | + { |
| 96 | + self.env |
| 97 | + .query_call( |
| 98 | + id, |
| 99 | + self.caller, |
| 100 | + method, |
| 101 | + encode_args(args).unwrap_or_else(panic_when_encode_fails), |
| 102 | + ) |
| 103 | + .await |
| 104 | + .map(decode_call_response) |
| 105 | + .map_err(parse_reject_response)? |
| 106 | + } |
| 107 | +} |
| 108 | + |
| 109 | +impl MockHttpRuntime { |
| 110 | + async fn execute_mocks(&self) { |
| 111 | + loop { |
| 112 | + let pending_requests = tick_until_http_requests(self.env.as_ref()).await; |
| 113 | + if let Some(request) = pending_requests.first() { |
| 114 | + let maybe_mock = { |
| 115 | + let mut mocks = self.mocks.lock().unwrap(); |
| 116 | + mocks.pop_matching(request) |
| 117 | + }; |
| 118 | + match maybe_mock { |
| 119 | + Some(mock) => { |
| 120 | + let mock_response = MockCanisterHttpResponse { |
| 121 | + subnet_id: request.subnet_id, |
| 122 | + request_id: request.request_id, |
| 123 | + response: check_response_size(request, mock.response), |
| 124 | + additional_responses: vec![], |
| 125 | + }; |
| 126 | + self.env.mock_canister_http_response(mock_response).await; |
| 127 | + } |
| 128 | + None => { |
| 129 | + panic!("No mocks matching the request: {:?}", request); |
| 130 | + } |
| 131 | + } |
| 132 | + } else { |
| 133 | + return; |
| 134 | + } |
| 135 | + } |
| 136 | + } |
| 137 | +} |
| 138 | + |
| 139 | +fn check_response_size( |
| 140 | + request: &CanisterHttpRequest, |
| 141 | + response: CanisterHttpResponse, |
| 142 | +) -> CanisterHttpResponse { |
| 143 | + if let CanisterHttpResponse::CanisterHttpReply(reply) = &response { |
| 144 | + let max_response_bytes = request |
| 145 | + .max_response_bytes |
| 146 | + .unwrap_or(DEFAULT_MAX_RESPONSE_BYTES); |
| 147 | + if reply.body.len() as u64 > max_response_bytes { |
| 148 | + // Approximate replica behavior since headers are not accounted for. |
| 149 | + return CanisterHttpResponse::CanisterHttpReject( |
| 150 | + pocket_ic::common::rest::CanisterHttpReject { |
| 151 | + reject_code: RejectCode::SysFatal as u64, |
| 152 | + message: format!("Http body exceeds size limit of {max_response_bytes} bytes.",), |
| 153 | + }, |
| 154 | + ); |
| 155 | + } |
| 156 | + } |
| 157 | + response |
| 158 | +} |
| 159 | + |
| 160 | +fn parse_reject_response(response: RejectResponse) -> IcError { |
| 161 | + CallFailed::CallRejected(CallRejected::with_rejection( |
| 162 | + response.reject_code as u32, |
| 163 | + response.reject_message, |
| 164 | + )) |
| 165 | + .into() |
| 166 | +} |
| 167 | + |
| 168 | +fn decode_call_response<Out>(bytes: Vec<u8>) -> Result<Out, IcError> |
| 169 | +where |
| 170 | + Out: CandidType + DeserializeOwned, |
| 171 | +{ |
| 172 | + decode_one(&bytes).map_err(|e| IcError::CandidDecodeFailed { |
| 173 | + message: e.to_string(), |
| 174 | + }) |
| 175 | +} |
| 176 | + |
| 177 | +fn panic_when_encode_fails(err: candid::error::Error) -> Vec<u8> { |
| 178 | + panic!("failed to encode args: {err}") |
| 179 | +} |
| 180 | + |
| 181 | +async fn tick_until_http_requests(env: &PocketIc) -> Vec<CanisterHttpRequest> { |
| 182 | + let mut requests = Vec::new(); |
| 183 | + for _ in 0..MAX_TICKS { |
| 184 | + requests = env.get_canister_http().await; |
| 185 | + if !requests.is_empty() { |
| 186 | + break; |
| 187 | + } |
| 188 | + env.tick().await; |
| 189 | + env.advance_time(Duration::from_nanos(1)).await; |
| 190 | + } |
| 191 | + requests |
| 192 | +} |
0 commit comments