feat!: Handle rejected update calls after IC spec change.

CHANGELOG.md

@@ -7,6 +7,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+* Breaking Change: Enum variant `AgentError::ReplicaError` is now a tuple struct containing `RejectResponse`.
+* Handling rejected update calls where status code is 200. See IC-1462
+* Reject code type is changed from `u64` to enum `RejectCode`.
 
 * Support WASM targets in the browser via `wasm-bindgen`
 

ic-agent/Cargo.toml

@@ -34,6 +34,7 @@ ring = { workspace = true, features = ["std"] }
 serde = { workspace = true, features = ["derive"] }
 serde_bytes = { workspace = true }
 serde_cbor = "0.11.2"
+serde_repr = "0.1.12"
 sha2 = { workspace = true }
 simple_asn1 = "0.6.1"
 thiserror = { workspace = true }

ic-agent/src/agent/agent_error.rs

@@ -1,6 +1,10 @@
 //! Errors that can occur when using the replica agent.
 
-use crate::{agent::status::Status, RequestIdError};
+use crate::{
+    agent::{replica_api::RejectResponse, status::Status},
+    RequestIdError,
+};
+// use crate::{agent::status::Status, RequestIdError};
 use ic_certification::Label;
 use leb128::read;
 use std::{
@@ -49,13 +53,8 @@ pub enum AgentError {
     PrincipalError(#[from] crate::export::PrincipalError),
 
     /// The replica rejected the message.
-    #[error(r#"The Replica returned an error: code {reject_code}, message: "{reject_message}""#)]
-    ReplicaError {
-        /// The [reject code](https://smartcontracts.org/docs/interface-spec/index.html#reject-codes) returned by the replica.
-        reject_code: u64,
-        /// The rejection message.
-        reject_message: String,
-    },
+    #[error("The replica returned a replica error: {0}")]
+    ReplicaError(RejectResponse),
 
     /// The replica returned an HTTP error.
     #[error("The replica returned an HTTP Error: {0}")]
@@ -193,6 +192,15 @@ impl PartialEq for AgentError {
     }
 }
 
+impl Display for RejectResponse {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+        f.write_fmt(format_args!(
+            "Replica Error: reject code {:?}, reject message {}, error code {:?}",
+            self.reject_code, self.reject_message, self.error_code,
+        ))
+    }
+}
+
 /// A HTTP error from the replica.
 pub struct HttpErrorPayload {
     /// The HTTP status code.

ic-agent/src/agent/agent_test.rs

@@ -5,7 +5,7 @@ use self::mock::{assert_mock, mock};
 use crate::{
     agent::{
         http_transport::ReqwestTransport,
-        replica_api::{CallReply, QueryResponse},
+        replica_api::{CallReply, QueryResponse, RejectCode, RejectResponse},
         Status,
     },
     export::Principal,
@@ -85,10 +85,11 @@ async fn query_error() -> Result<(), AgentError> {
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
 #[cfg_attr(target_family = "wasm", wasm_bindgen_test)]
 async fn query_rejected() -> Result<(), AgentError> {
-    let response: QueryResponse = QueryResponse::Rejected {
-        reject_code: 1234,
+    let response: QueryResponse = QueryResponse::Rejected(RejectResponse {
+        reject_code: RejectCode::DestinationInvalid,
         reject_message: "Rejected Message".to_string(),
-    };
+        error_code: Some("Error code".to_string()),
+    });
 
     let (query_mock, url) = mock(
         "POST",
@@ -116,12 +117,10 @@ async fn query_rejected() -> Result<(), AgentError> {
     assert_mock(query_mock).await;
 
     match result {
-        Err(AgentError::ReplicaError {
-            reject_code: code,
-            reject_message: msg,
-        }) => {
-            assert_eq!(code, 1234);
-            assert_eq!(msg, "Rejected Message");
+        Err(AgentError::ReplicaError(replica_error)) => {
+            assert_eq!(replica_error.reject_code, RejectCode::DestinationInvalid);
+            assert_eq!(replica_error.reject_message, "Rejected Message");
+            assert_eq!(replica_error.error_code, Some("Error code".to_string()));
         }
         result => unreachable!("{:?}", result),
     }
@@ -151,6 +150,82 @@ async fn call_error() -> Result<(), AgentError> {
     Ok(())
 }
 
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test)]
+async fn call_rejected() -> Result<(), AgentError> {
+    let reject_body = RejectResponse {
+        reject_code: RejectCode::SysTransient,
+        reject_message: "Test reject message".to_string(),
+        error_code: Some("Test error code".to_string()),
+    };
+
+    let body = serde_cbor::to_vec(&reject_body).unwrap();
+
+    let (call_mock, url) = mock(
+        "POST",
+        "/api/v2/canister/aaaaa-aa/call",
+        200,
+        body,
+        Some("application/cbor"),
+    )
+    .await;
+
+    let agent = Agent::builder()
+        .with_transport(ReqwestTransport::create(&url)?)
+        .build()?;
+
+    let result = agent
+        .update(&Principal::management_canister(), "greet")
+        .with_arg([])
+        .call()
+        .await;
+
+    assert_mock(call_mock).await;
+
+    let expected_response = Err(AgentError::ReplicaError(reject_body));
+    assert_eq!(expected_response, result);
+
+    Ok(())
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test)]
+async fn call_rejected_without_error_code() -> Result<(), AgentError> {
+    let reject_body = RejectResponse {
+        reject_code: RejectCode::SysTransient,
+        reject_message: "Test reject message".to_string(),
+        error_code: None,
+    };
+
+    let body = serde_cbor::to_vec(&reject_body).unwrap();
+
+    let (call_mock, url) = mock(
+        "POST",
+        "/api/v2/canister/aaaaa-aa/call",
+        200,
+        body,
+        Some("application/cbor"),
+    )
+    .await;
+
+    let agent = Agent::builder()
+        .with_transport(ReqwestTransport::create(&url)?)
+        .build()?;
+
+    let result = agent
+        .update(&Principal::management_canister(), "greet")
+        .with_arg([])
+        .call()
+        .await;
+
+    assert_mock(call_mock).await;
+
+    let expected_response = Err(AgentError::ReplicaError(reject_body));
+    assert_eq!(expected_response, result);
+
+    Ok(())
+}
+
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
 #[cfg_attr(target_family = "wasm", wasm_bindgen_test)]
 async fn status() -> Result<(), AgentError> {

ic-agent/src/agent/http_transport/reqwest_transport.rs

@@ -17,6 +17,7 @@ use crate::{
     agent::{
         agent_error::HttpErrorPayload,
         http_transport::{IC0_DOMAIN, IC0_SUB_DOMAIN},
+        replica_api::RejectResponse,
         AgentFuture, Transport,
     },
     export::Principal,
@@ -236,7 +237,19 @@ impl ReqwestTransport {
             }
         }
 
-        if status.is_client_error() || status.is_server_error() {
+        // status == OK means we have an error message for call requests
+        // see https://internetcomputer.org/docs/current/references/ic-interface-spec#http-call
+        if status == StatusCode::OK && endpoint.ends_with("call") {
+            let cbor_decoded_body: Result<RejectResponse, serde_cbor::Error> =
+                serde_cbor::from_slice(&body);
+
+            let agent_error = match cbor_decoded_body {
+                Ok(replica_error) => AgentError::ReplicaError(replica_error),
+                Err(cbor_error) => AgentError::InvalidCborData(cbor_error),
+            };
+
+            Err(agent_error)
+        } else if status.is_client_error() || status.is_server_error() {
             Err(AgentError::HttpError(HttpErrorPayload {
                 status: status.into(),
                 content_type: headers

ic-agent/src/agent/mod.rs

@@ -15,6 +15,7 @@ pub use agent_error::AgentError;
 use backoff::{backoff::Backoff, ExponentialBackoffBuilder};
 pub use builder::AgentBuilder;
 pub use nonce::{NonceFactory, NonceGenerator};
+pub use replica_api::{RejectCode, RejectResponse};
 pub use response::{Replied, RequestStatusResponse};
 
 #[cfg(test)]
@@ -421,13 +422,9 @@ impl Agent {
             .await
             .and_then(|response| match response {
                 replica_api::QueryResponse::Replied { reply } => Ok(reply.arg),
-                replica_api::QueryResponse::Rejected {
-                    reject_code,
-                    reject_message,
-                } => Err(AgentError::ReplicaError {
-                    reject_code,
-                    reject_message,
-                }),
+                replica_api::QueryResponse::Rejected(response) => {
+                    Err(AgentError::ReplicaError(response))
+                }
             })
     }
 
@@ -445,13 +442,9 @@ impl Agent {
             .await
             .and_then(|response| match response {
                 replica_api::QueryResponse::Replied { reply } => Ok(reply.arg),
-                replica_api::QueryResponse::Rejected {
-                    reject_code,
-                    reject_message,
-                } => Err(AgentError::ReplicaError {
-                    reject_code,
-                    reject_message,
-                }),
+                replica_api::QueryResponse::Rejected(response) => {
+                    Err(AgentError::ReplicaError(response))
+                }
             })
     }
 
@@ -542,13 +535,8 @@ impl Agent {
                 reply: Replied::CallReplied(arg),
             } => Ok(PollResult::Completed(arg)),
 
-            RequestStatusResponse::Rejected {
-                reject_code,
-                reject_message,
-            } => Err(AgentError::ReplicaError {
-                reject_code,
-                reject_message,
-            }),
+            RequestStatusResponse::Rejected(response) => Err(AgentError::ReplicaError(response)),
+
             RequestStatusResponse::Done => Err(AgentError::RequestStatusDoneNoReply(String::from(
                 *request_id,
             ))),

ic-agent/src/agent/replica_api.rs

@@ -1,8 +1,9 @@
-use crate::export::Principal;
+use crate::{export::Principal, AgentError};
 use ic_certification::Label;
 use serde::{Deserialize, Serialize};
 
 pub use ic_certification::{Certificate, Delegation};
+use serde_repr::{Deserialize_repr, Serialize_repr};
 
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
@@ -146,8 +147,53 @@ pub enum QueryResponse {
     #[serde(rename = "replied")]
     Replied { reply: CallReply },
     #[serde(rename = "rejected")]
-    Rejected {
-        reject_code: u64,
-        reject_message: String,
-    },
+    Rejected(RejectResponse),
+}
+
+/// An IC execution error received from the replica.
+#[derive(Debug, Clone, Serialize, Deserialize, Ord, PartialOrd, Eq, PartialEq)]
+pub struct RejectResponse {
+    /// The [reject code](https://smartcontracts.org/docs/interface-spec/index.html#reject-codes) returned by the replica.
+    pub reject_code: RejectCode,
+    /// The rejection message.
+    pub reject_message: String,
+    /// The optional [error code](https://smartcontracts.org/docs/interface-spec/index.html#error-codes) returned by the replica.
+    #[serde(default)]
+    pub error_code: Option<String>,
+}
+
+/// See the [interface spec](https://smartcontracts.org/docs/interface-spec/index.html#reject-codes).
+#[derive(
+    Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize_repr, Deserialize_repr, Ord, PartialOrd,
+)]
+#[repr(u8)]
+pub enum RejectCode {
+    /// Fatal system error, retry unlikely to be useful
+    SysFatal = 1,
+    /// Transient system error, retry might be possible.
+    SysTransient = 2,
+    /// Invalid destination (e.g. canister/account does not exist)
+    DestinationInvalid = 3,
+    /// Explicit reject by the canister.
+    CanisterReject = 4,
+    /// Canister error (e.g., trap, no response)
+    CanisterError = 5,
+}
+
+impl TryFrom<u64> for RejectCode {
+    type Error = AgentError;
+
+    fn try_from(value: u64) -> Result<Self, AgentError> {
+        match value {
+            1 => Ok(RejectCode::SysFatal),
+            2 => Ok(RejectCode::SysTransient),
+            3 => Ok(RejectCode::DestinationInvalid),
+            4 => Ok(RejectCode::CanisterReject),
+            5 => Ok(RejectCode::CanisterError),
+            _ => Err(AgentError::MessageError(format!(
+                "Received an invalid reject code {}",
+                value
+            ))),
+        }
+    }
 }

ic-agent/src/agent/response.rs

@@ -1,3 +1,5 @@
+use super::replica_api::RejectResponse;
+
 /// The response of /api/v2/canister/<effective_canister_id>/read_state with "request_status" request type.
 ///
 /// See [the HTTP interface specification](https://smartcontracts.org/docs/interface-spec/index.html#http-call-overview) for more details.
@@ -15,12 +17,7 @@ pub enum RequestStatusResponse {
         reply: Replied,
     },
     /// The request has been rejected.
-    Rejected {
-        /// The [reject code](https://smartcontracts.org/docs/interface-spec/index.html#reject-codes) from the replica.
-        reject_code: u64,
-        /// The rejection message.
-        reject_message: String,
-    },
+    Rejected(RejectResponse),
     /// The call has been completed, and it has been long enough that the reply/reject data has been purged, but the call has not expired yet.
     Done,
 }