New version (after feature review)

Author: oggy-dfin

docs/references/_attachments/ic.did

@@ -85,6 +85,29 @@ type http_request_result = record {
     body : blob;
 };
 
+type http_request_resource_report = record {
+  downloaded_bytes: opt variant { used: nat64; exceeded: reserved };
+  request_time_ms: opt variant { used: nat64; exceeded: reserved };
+  transform_instructions: opt variant { used: nat64; exceeded: reserved };
+  transformed_response_size: opt variant { used: nat64; exceeded: reserved };
+}
+
+multi_response_http_request_err = record {
+  cause: opt variant {
+    timeout : vec (principal, http_request_resource_report);
+    invalid_parameters: reserved;
+    limits_exceeded: vec (principal, http_request_resource_report);
+    out_of_cycles : vec (principal, http_request_resource_report);
+  };
+  message: text;
+}
+
+
+type multi_response_http_request_result = record {
+  ok: vec http_request_result;
+  err: multi_response_http_request_err;
+};
+
 type ecdsa_curve = variant {
     secp256k1;
 };
@@ -317,7 +340,7 @@ type http_request_args = record {
     };
 };
 
-type flexible_http_request_args = record {
+type multi_response_http_request_args = record {
     url : text;
     method : variant { get; head; post };
     headers : vec http_header;
@@ -326,9 +349,10 @@ type flexible_http_request_args = record {
         function : func(record { response : http_request_result; context : blob }) -> (http_request_result) query;
         context : blob;
     };
-    responses_from : variant {
-        all_replicas;
-        replica_count: nat32;
+    node_counts: opt record {
+      min_responses: nat64;
+      max_responses: nat64;
+      total_requests: nat64;
     };
 }
 
@@ -504,7 +528,7 @@ service ic : {
     deposit_cycles : (deposit_cycles_args) -> ();
     raw_rand : () -> (raw_rand_result);
     http_request : (http_request_args) -> (http_request_result);
-    flexible_http_request : (flexible_http_request_args) -> (vec http_request_result);
+    multi_response_http_request : (multi_response_http_request_args) -> multi_response_http_request_response;
 
     // Threshold ECDSA signature
     ecdsa_public_key : (ecdsa_public_key_args) -> (ecdsa_public_key_result);

docs/references/ic-interface-spec.md

@@ -1527,7 +1527,7 @@ defaulting to `I = i32` if the canister declares no memory.
 
     ic0.subnet_self_size : () -> I;                                                       // *
     ic0.subnet_self_copy : (dst : I, offset : I, size : I) -> ();                         // *
-    ic0.subnet_self_replica_count : () -> i32;                                            // *
+    ic0.subnet_self_node_count : () -> i32;                                            // *
 
     ic0.msg_method_name_size : () -> I;                                                   // F
     ic0.msg_method_name_copy : (dst : I, offset : I, size : I) -> ();                     // F
@@ -1570,8 +1570,6 @@ defaulting to `I = i32` if the canister declares no memory.
     ic0.cost_call : (method_name_size: i64, payload_size : i64, dst : I) -> ();           // * s
     ic0.cost_create_canister : (dst : I) -> ();                                           // * s
     ic0.cost_http_request : (request_size : i64, max_res_bytes : i64, dst : I) -> ();     // * s
-    ic0.cost_flexible_http_request :
-        (request_size : i64, replica_count: i32, dst : I) -> ();                          // * s
     ic0.cost_sign_with_ecdsa : (src : I, size : I, ecdsa_curve: i32, dst : I) -> i32;     // * s
     ic0.cost_sign_with_schnorr : (src : I, size : I, algorithm: i32, dst : I) -> i32;     // * s
     ic0.cost_vetkd_derive_key : (src : I, size : I, vetkd_curve: i32, dst : I) -> i32;  // * s
@@ -1752,9 +1750,9 @@ A canister can learn about its own identity:
 
 A canister can learn about the subnet it is running on:
 
--   `ic0.subnet_self_size : () → I`, `ic0.subnet_self_copy: (dst : I, offset : I, size : I) → ()`; `I ∈ {i32, i64}`, and `ic0.subnet_self_replica_count : () -> i32`
+-   `ic0.subnet_self_size : () → I`, `ic0.subnet_self_copy: (dst : I, offset : I, size : I) → ()`; `I ∈ {i32, i64}`, and `ic0.subnet_self_node_count : () -> i32`
 
-    These functions allow the canister to query the subnet id (as a blob) of the subnet on which the canister is running, and to retrieve the number of replicas that are currently on the subnet.
+    These functions allow the canister to query the subnet id (as a blob) of the subnet on which the canister is running, and to retrieve the number of nodes that are currently on the subnet.
 
 
 ### Canister status {#system-api-canister-status}
@@ -2168,10 +2166,6 @@ These system calls return costs in Cycles, represented by 128 bits, which will b
 
     `max_res_bytes` is the maximum response length the caller wishes to accept (the caller should provide the default value of `2,000,000` if no maximum response length is provided in the actual request to the management canister). 
 
--   `ic0.cost_flexible_http_request(request_size : i64, replica_count: i32, dst : I) -> ()`; `I ∈ {i32, i64}`
-
-    The cost of a canister http outcall via [`flexible_http_request`](#ic-flexible_http_request). The `request_size` is same as for `cost_http_request` and covers the url, headers, body and transform. The `replica_count` is the number to be used in the call to `flexible_http_request`.
-
 -   `ic0.cost_sign_with_ecdsa(src : I, size : I, ecdsa_curve: i32, dst : I) -> i32`; `I ∈ {i32, i64}`
 
 -   `ic0.cost_sign_with_schnorr(src : I, size : I, algorithm: i32, dst : I) -> i32`; `I ∈ {i32, i64}`
@@ -2828,15 +2822,15 @@ If you do not specify the `max_response_bytes` parameter, the maximum of a `2MB`
 
 :::
 
-### IC method `flexible_http_request` {#ic-flexible_http_request}
+### IC method `multi_response_http_request` {#ic-multi_response_http_request}
 
-This is a variant of the [`http_request`](#ic-http_request) method that allows the caller to select how many IC replicas issue the request, and returns potentially multiple responses instead of a single one, one from each replica issuing the request. Use cases include calling HTTP endpoints that provide rapidly changing information, calling non-idempotent endpoints (by issuing the request from a single replica only), calling endpoints that provide signed data whose authenticity can be checked without trusting the endpoint, and letting the user pick a trade-off between cheaper calls (fewer replicas responding) and stronger integrity guarantees (more replicas responding).
+This is a variant of the [`http_request`](#ic-http_request) method where nodes return their individual HTTP responses to the caller instead of trying to reach consensus on the response, letting the caller do its own HTTP response processing. Use cases include calling HTTP endpoints that provide rapidly changing information (where achieving consensus s unlikely) and letting the user pick a trade-off between cheaper calls (fewer replicas requesting/responding) and stronger integrity guarantees (more replicas requesting/responding).
 
 The arguments of the call are as for `http_request`, except that:
 
-- there is an additional argument `responses_from`, which can be set to either `all_replicas` or to a particular `replica_count` with a given (positive) number of replicas. The number of replicas must not exceed the subnet size.
+- there is an additional optional argument `node_counts`. When set, the caller can specify how many nodes should issue an HTTP outcall, the minimum number of HTTP responses from nodes in order for the outcall to succeed (`min_responses`), and the maximum number of HTTP responses the caller is willing to receive as the result of the outcall (`max_responses`). That is, a successful HTTP outcall is guaranteed to return between `min_responses` and `max_responses`. If `node_counts` are set, then the caller must ensure that `1 <= min_responses <= max_responses <= total_requests <= N`, where `N` is the number of the nodes on the caller's subnet, otherwise the call will fail. The caller may use the `ic0.subnet_self_node_count` System API call to determine `N`. If `node_count` is not provided, the defaults of `floor(2 / 3 * N) + 1`, `N` and `N` are used for `min_responses`, `max_responses` and `total_requests`.
 
-- `max_response_bytes` argument is not needed.
+- the deprecated `max_response_bytes` argument is not supported.
 
 The other arguments, `url`, `method`, `headers`, `body`, and `transform` are the same as for `http_request`. The result is a vector of responses, with each individual response having the same structure as a `http_request` response, providing `status`, `headers`, and `body` fields.