Merge branch 'master' into exc-1519

spec/_attachments/ic.did

@@ -121,6 +121,12 @@ type snapshot = record {
   checksum: blob;   
 };
 
+type node_metrics = record {
+    node_id : principal;
+    num_blocks_total : nat64;
+    num_block_failures_total : nat64;
+};
+
 service ic : {
   create_canister : (record {
     settings : opt canister_settings;
@@ -235,6 +241,15 @@ service ic : {
   list_snapshots: (record {canister_id : canister_id}) -> (vec snapshot);
   delete_snapshot: (record {snapshot_id : snapshot_id}) -> ();
 
+  // metrics interface
+  node_metrics_history : (record {
+    subnet_id : principal;
+    start_at_timestamp_nanos: nat64;
+  }) -> (vec record {
+    timestamp_nanos : nat64;
+    node_metrics : vec node_metrics;
+  });
+
   // provisional interfaces for the pre-ledger world
   provisional_create_canister_with_cycles : (record {
     amount: opt nat;

spec/_attachments/interface-spec-changelog.md

@@ -4,6 +4,8 @@
 * The maximum length of a nonce in an ingress message is 32 bytes.
 * Update specification of responses from the endpoint `/api/v2/status`.
 * Stop canister calls might be rejected upon timeout.
+* The IC sends a `user-agent` header with the value `ic/1.0` in canister HTTPS outcalls if the canister does not provide one.
+* Add a management canister method for retrieving node metrics.
 
 ### 0.22.0 (2023-11-15) {#0_22_0}
 * Add metrics on subnet usage into the certified state tree and a new HTTP endpoint `/api/v2/subnet/<subnet_id>/read_state` for retrieving them.

spec/index.md

@@ -2127,7 +2127,11 @@ For this reason, the calling canister can supply a transformation function, whic
 
 Currently, the `GET`, `HEAD`, and `POST` methods are supported for HTTP requests.
 
-It is important to note the following for the usage of the `POST` method: - The calling canister must make sure that the remote server is able to handle idempotent requests sent from multiple sources. This may require, for example, to set a certain request header to uniquely identify the request. - There are no confidentiality guarantees on the request content. There is no guarantee that all sent requests are as specified by the canister. If the canister receives a response, then at least one request that was sent matched the canister's request, and the response was to that request.
+It is important to note the following for the usage of the `POST` method:
+
+- The calling canister must make sure that the remote server is able to handle idempotent requests sent from multiple sources. This may require, for example, to set a certain request header to uniquely identify the request.
+
+- There are no confidentiality guarantees on the request content. There is no guarantee that all sent requests are as specified by the canister. If the canister receives a response, then at least one request that was sent matched the canister's request, and the response was to that request.
 
 For security reasons, only HTTPS connections are allowed (URLs must start with `https://`). The IC uses industry-standard root CA lists to validate certificates of remote web servers.
 
@@ -2169,6 +2173,11 @@ The following additional limits apply to HTTP requests and HTTP responses from t
 
 -   the total number of bytes representing the header names and values must not exceed `48KiB`.
 
+If the request headers provided by the canister do not contain a `user-agent` header (case-insensitive),
+then the IC sends a `user-agent` header (case-insensitive) with the value `ic/1.0`
+in addition to the headers provided by the canister. Such an additional header does not contribute
+to the above limits on HTTP request headers.
+
 :::note
 
 Currently, the Internet Computer mainnet only supports URLs that resolve to IPv6 destinations (i.e., the domain has a `AAAA` DNS record) in HTTP requests.
@@ -2181,6 +2190,26 @@ If you do not specify the `max_response_bytes` parameter, the maximum of a `2MB`
 
 :::
 
+### IC method `node_metrics_history` {#ic-node-metrics-history}
+
+:::note
+
+The node metrics management canister API is considered EXPERIMENTAL. Canister developers must be aware that the API may evolve in a non-backward-compatible way.
+
+:::
+
+Given a subnet ID as input, this method returns a time series of node metrics (field `node_metrics`). The timestamps are represented as nanoseconds since 1970-01-01 (field `timestamp_nanos`) at which the metrics were sampled. The returned timestamps are all timestamps after (and including) the provided timestamp (field `start_at_timestamp_nanos`) for which node metrics are available. The maximum number of returned timestamps is 60 and no two returned timestamps belong to the same UTC day.
+
+Note that a sample will only include metrics for nodes whose metrics changed compared to the previous sample. This means that if a node disappears in one sample and later reappears its metrics will restart from 0 and consumers of this API need to adjust for these resets when aggregating over multiple samples.
+
+A single metric entry is a record with the following fields:
+
+- `node_id` (`principal`): the principal characterizing a node;
+
+- `num_blocks_total` (`nat64`): the number of blocks proposed by this node;
+
+- `num_block_failures_total` (`nat64`): the number of failed block proposals by this node.
+
 ### IC method `provisional_create_canister_with_cycles` {#ic-provisional_create_canister_with_cycles}
 
 As a provisional method on development instances, the `provisional_create_canister_with_cycles` method is provided. It behaves as `create_canister`, but initializes the canister's balance with `amount` fresh cycles (using `DEFAULT_PROVISIONAL_CYCLES_BALANCE` if `amount = null`). If `specified_id` is provided, the canister is created under this id. Note that canister creation using `create_canister` or `provisional_create_canister_with_cycles` with `specified_id = null` can fail after calling `provisional_create_canister_with_cycles` with provided `specified_id`. In that case, canister creation should be retried.
@@ -3271,7 +3300,7 @@ State after
 messages = Older_messages · Younger_messages  ·
   ResponseMessage {
       origin = CM.origin;
-      response = Reject (CANISTER_ERROR, "canister not running");
+      response = Reject (CANISTER_ERROR, <implementation-specific>);
       refunded_cycles = CM.transferred_cycles;
   }
 
@@ -3659,7 +3688,7 @@ S with
       S.messages ·
       ResponseMessage {
         origin = S.call_contexts[Ctxt_id].origin;
-        response = Reject (CANISTER_ERROR, "starvation");
+        response = Reject (CANISTER_ERROR, <implementation-specific>);
         refunded_cycles = S.call_contexts[Ctxt_id].available_cycles
       }
 
@@ -4407,7 +4436,7 @@ S with
       } ·
       [ ResponseMessage {
           origin = Ctxt.origin
-          response = Reject (CANISTER_REJECT, 'Canister has been uninstalled')
+          response = Reject (CANISTER_REJECT, <implementation-specific>)
           refunded_cycles = Ctxt.available_cycles
         }
       | Ctxt_id ↦ Ctxt ∈ S.call_contexts
@@ -4560,7 +4589,7 @@ S with
     messages = S.Messages ·
       ResponseMessage {
         origin = O
-        response = Reject (SYS_TRANSIENT, 'Stop canister request timed out')
+        response = Reject (SYS_TRANSIENT, <implementation-specific>)
         refunded_cycles = C
       }
 
@@ -4629,7 +4658,7 @@ S with
         } ·
         [ ResponseMessage {
             origin = O
-            response = Reject (CANISTER_ERROR, 'Canister has been restarted')
+            response = Reject (CANISTER_ERROR, <implementation-specific>)
             refunded_cycles = C
           }
         | (O, C) ∈ Origins
@@ -4744,6 +4773,44 @@ S with
 
 ```
 
+#### IC Management Canister: Node Metrics
+
+:::note
+
+The node metrics management canister API is considered EXPERIMENTAL. Canister developers must be aware that the API may evolve in a non-backward-compatible way.
+
+:::
+
+The management canister returns metrics for nodes on a given subnet. The definition of the metrics values
+is not captured in this formal semantics.
+
+Conditions
+
+```html
+
+S.messages = Older_messages · CallMessage M · Younger_messages
+(M.queue = Unordered) or (∀ msg ∈ Older_messages. msg.queue ≠ M.queue)
+M.callee = ic_principal
+M.method_name = 'node_metrics_history'
+M.arg = candid(A)
+R = <implementation-specific>
+
+```
+
+State after
+
+```html
+
+S with
+    messages = Older_messages · Younger_messages ·
+      ResponseMessage {
+        origin = M.origin
+        response = Reply (candid(R))
+        refunded_cycles = M.transferred_cycles
+      }
+
+```
+
 #### IC Management Canister: Canister creation with cycles
 
 This is a variant of `create_canister`, which sets the initial cycle balance based on the `amount` argument.
@@ -5030,7 +5097,7 @@ S with
     messages = S.messages ·
       [ ResponseMessage {
           origin = Ctxt.origin
-          response = Reject (CANISTER_REJECT, 'Canister has been uninstalled')
+          response = Reject (CANISTER_REJECT, <implementation-specific>)
           refunded_cycles = Ctxt.available_cycles
         }
       | Ctxt_id ↦ Ctxt ∈ S.call_contexts