feat: Best-effort responses

spec/index.md

@@ -127,6 +127,10 @@ This specification may refer to certain constants and limits without specifying
 
  Maximum wall clock time spent on evaluation of a query call.
 
+- `MAX_CALL_TIMEOUT`
+
+ The maximum timeout (in seconds) for an inter-canister call.
+
 ### Principals {#principal}
 
 Principals are generic identifiers for canisters, users and possibly other concepts in the future. As far as most uses of the IC are concerned they are *opaque* binary blobs with a length between 0 and 29 bytes, and there is intentionally no mechanism to tell canister ids and user ids apart.
@@ -1008,6 +1012,8 @@ Rejection codes are member of the following enumeration:
 
 - `CANISTER_ERROR` (5): Canister error (e.g., trap, no response)
 
+- `SYS_UNKNOWN` (6): Response unknown; system stopped waiting for it (e.g., timed out, or system under high load).
+
 The symbolic names of this enumeration are used throughout this specification, but on all interfaces (HTTPS API, System API), they are represented as positive numbers as given in the list above.
 
 The error message is guaranteed to be a string, i.e. not arbitrary binary data.
@@ -1284,6 +1290,7 @@ The following sections describe various System API functions, also referred to a
  ic0.msg_reject_code : () -> i32; // Ry Rt CRy CRt
  ic0.msg_reject_msg_size : () -> i32; // Rt CRt
  ic0.msg_reject_msg_copy : (dst : i32, offset : i32, size : i32) -> (); // Rt CRt
+ ic0.msg_deadline : () -> i64; // U Ry Rt
 
  ic0.msg_reply_data_append : (src : i32, size : i32) -> (); // U Q CQ Ry Rt CRy CRt
  ic0.msg_reply : () -> (); // U Q CQ Ry Rt CRy CRt
@@ -1322,6 +1329,7 @@ The following sections describe various System API functions, also referred to a
  ) -> ();
  ic0.call_on_cleanup : (fun : i32, env : i32) -> (); // U CQ Ry Rt CRy CRt T
  ic0.call_data_append : (src : i32, size : i32) -> (); // U CQ Ry Rt CRy CRt T
+ ic0.call_with_best_effort_response : (timeout_seconds : i32) -> (); // U Ry Rt T
  ic0.call_cycles_add : (amount : i64) -> (); // U Ry Rt T
  ic0.call_cycles_add128 : (amount_high : i64, amount_low: i64) -> (); // U Ry Rt T
  ic0.call_perform : () -> ( err_code : i32 ); // U CQ Ry Rt CRy CRt T
@@ -1424,6 +1432,12 @@ The canister can access an argument. For `canister_init`, `canister_post_upgrade
 
  The reject message. Traps if there is no reject message (i.e. if `reject_code` is `0`).
 
+- `ic0.msg_deadline : () -> i64`
+
+ The deadline, in nanoseconds since 1970-01-01, after which the caller will stop waiting for a response.
+
+ For calls with best-effort responses, the deadline is computed based on the time the call was made, and the `timeout_seconds` parameter provided by the caller. For other calls, a deadline of 0 will be returned.
+
 ### Responding {#responding}
 
 Eventually, the canister will want to respond to the original call, either by replying (indicating success) or rejecting (signalling an error):
@@ -1550,6 +1564,16 @@ If this traps (e.g. runs out of cycles), the state changes from the `cleanup` fu
 
 There must be at most one call to `ic0.call_on_cleanup` between `ic0.call_new` and `ic0.call_perform`.
 
+- `ic0.call_with_best_effort_response : (timeout_seconds : i32) -> ()`
+
+ Relaxes the response delivery guarantee to be best effort, asking the system to respond at the latest after `timeout_seconds` have elapsed. The system can then also respond with a `SYS_UNKNOWN` reject code. This reject code signifies that the call **may or may not** have been processed by the callee; even if the callee produces a response, it will not be delivered to the caller.
+
+ The `timeout_seconds` is silently bounded from above by the `MAX_CALL_TIMEOUT` system constant; i.e., larger timeouts are treated as equivalent to `MAX_CALL_TIMEOUT` and do not cause an error. The reject callback may be executed (possibly significantly) later than the specified time, e.g., if the canister is under high load. The reject callback can also executed before timeout expiration, and possibly with a `SYS_UNKNOWN` code if the system is under load.
+
+ A caller that receives a `SYS_UNKNOWN` node, yet needs to learn the call outcome, must find an out-of-band way of doing so. For example, if the callee provides idempotent function calls, the caller can simply retry the call. Sample causes of `SYS_UNKNOWN` include the call not being delivered in time, call processing not completing in time, reply delivery taking too long, and the system shedding load.
+
+ This method can be called only in between `ic0.call_new` and `ic0.call_perform`, and at most once at that. Otherwise, it traps. A different timeout can be specified for each call.
+
 - `ic0.call_data_append : (src : i32, size : i32) -> ()`
 
  Appends the specified bytes to the argument of the call. Initially, the argument is empty. Traps if the total appended data exceeds the [maximum inter-canister call payload](https://internetcomputer.org/docs/current/developer-docs/backend/resource-limits#resource-constraints-and-limits).