From 413697ee9dfe5bfee8dc29eb9216e1b62f2ae6db Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Tue, 5 May 2026 18:34:27 +0200 Subject: [PATCH] fix(refs): restore missing spec attachment files from portal Copies certificates.cddl, requests.cddl, and http-gateway.did from .sources/portal into public/references/_attachments/ so the download links in the IC interface spec and HTTP Gateway spec resolve correctly. Updates the three broken relative links to absolute paths. Adds the attachment files to the AGENTS.md portal bump checklist. Closes #191 --- AGENTS.md | 7 +- docs/references/http-gateway-spec.md | 2 +- .../ic-interface-spec/certification.md | 2 +- .../ic-interface-spec/https-interface.md | 2 +- .../references/_attachments/certificates.cddl | 30 +++++ .../references/_attachments/http-gateway.did | 49 ++++++++ public/references/_attachments/requests.cddl | 113 ++++++++++++++++++ 7 files changed, 201 insertions(+), 4 deletions(-) create mode 100644 public/references/_attachments/certificates.cddl create mode 100644 public/references/_attachments/http-gateway.did create mode 100644 public/references/_attachments/requests.cddl diff --git a/AGENTS.md b/AGENTS.md index 2f9c48c..7f7dfca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -331,16 +331,20 @@ grep -r "{#}" docs/references/ic-interface-spec/ | Local file | Source | Affects | |-----------|--------|---------| | `public/reference/ic.did` | `.sources/portal/docs/references/_attachments/ic.did` | Management canister reference — new/changed methods require updating `docs/references/management-canister.md` | +| `public/references/_attachments/certificates.cddl` | `.sources/portal/docs/references/_attachments/certificates.cddl` | Downloadable CDDL linked from `docs/references/ic-interface-spec/certification.md` | +| `public/references/_attachments/requests.cddl` | `.sources/portal/docs/references/_attachments/requests.cddl` | Downloadable CDDL linked from `docs/references/ic-interface-spec/https-interface.md` | +| `public/references/_attachments/http-gateway.did` | `.sources/portal/docs/references/_attachments/http-gateway.did` | Downloadable Candid interface linked from `docs/references/http-gateway-spec.md` | | `docs/references/ic-interface-spec/` | `.sources/portal/docs/references/ic-interface-spec.md` | IC interface spec split into 7 focused pages — apply portal diffs by section (see checklist below) | | `docs/references/http-gateway-spec.md` | `.sources/portal/docs/references/http-gateway-protocol-spec.md` | HTTP Gateway spec — apply portal diff as a patch on every bump | **Portal bump checklist (run on every portal bump):** -**Step 1 — `ic.did`:** +**Step 1 — `ic.did` and `_attachments/`:** 1. `diff public/reference/ic.did .sources/portal/docs/references/_attachments/ic.did` 2. If changed: `cp .sources/portal/docs/references/_attachments/ic.did public/reference/ic.did` 3. Review diff for new/changed/removed methods 4. Update `docs/references/management-canister.md` and any affected guides +5. For each of `certificates.cddl`, `requests.cddl`, `http-gateway.did`: `diff public/references/_attachments/ .sources/portal/docs/references/_attachments/` — if changed, copy the updated file to `public/references/_attachments/` **Step 2 — `ic-interface-spec/`:** The spec is now split into 7 files under `docs/references/ic-interface-spec/`. Each file maps to a section of the portal source: @@ -383,6 +387,7 @@ git -C .sources/portal show -- docs/references/ic-interface-spec.md | g git -C .sources/portal log --oneline .. -- docs/references/_attachments/interface-spec-changelog.md git -C .sources/portal log --oneline .. -- docs/references/http-gateway-protocol-spec.md git -C .sources/portal log --oneline .. -- docs/references/_attachments/ic.did +git -C .sources/portal log --oneline .. -- docs/references/_attachments/certificates.cddl docs/references/_attachments/requests.cddl docs/references/_attachments/http-gateway.did ``` ## Planning artifacts (`.docs-plan/`) diff --git a/docs/references/http-gateway-spec.md b/docs/references/http-gateway-spec.md index e67ece8..c67fe9f 100644 --- a/docs/references/http-gateway-spec.md +++ b/docs/references/http-gateway-spec.md @@ -432,7 +432,7 @@ service : { } ``` -You can also [download the file](./_attachments/http-gateway.did). +You can also [download the file](/references/_attachments/http-gateway.did). Not all of this interface is required. The following sections detail what can be optionally omitted depending on the requirements of the canister in question. diff --git a/docs/references/ic-interface-spec/certification.md b/docs/references/ic-interface-spec/certification.md index 3c1acba..53d108f 100644 --- a/docs/references/ic-interface-spec/certification.md +++ b/docs/references/ic-interface-spec/certification.md @@ -179,7 +179,7 @@ Delegations are *scoped*, i.e., they indicate which set of canister principals t ### Encoding of certificates {#certification-encoding} -The binary encoding of a certificate is a CBOR (see [CBOR](./index.md#cbor)) value according to the following CDDL (see [CDDL](./index.md#cddl)). You can also [download the file](_attachments/certificates.cddl). +The binary encoding of a certificate is a CBOR (see [CBOR](./index.md#cbor)) value according to the following CDDL (see [CDDL](./index.md#cddl)). You can also [download the file](/references/_attachments/certificates.cddl). The values in the [The system state tree](./index.md#state-tree) are encoded to blobs as follows: diff --git a/docs/references/ic-interface-spec/https-interface.md b/docs/references/ic-interface-spec/https-interface.md index eddb2a1..544a277 100644 --- a/docs/references/ic-interface-spec/https-interface.md +++ b/docs/references/ic-interface-spec/https-interface.md @@ -735,7 +735,7 @@ A typical request would be (written in [CBOR diagnostic notation](https://www.rf ### CDDL description of requests and responses {#api-cddl} -This section summarizes the format of the CBOR data passed to and from the entry points described above. You can also [download the file](_attachments/requests.cddl) and see [CDDL](./index.md#cddl) for more information. +This section summarizes the format of the CBOR data passed to and from the entry points described above. You can also [download the file](/references/_attachments/requests.cddl) and see [CDDL](./index.md#cddl) for more information. ### Ordering guarantees diff --git a/public/references/_attachments/certificates.cddl b/public/references/_attachments/certificates.cddl new file mode 100644 index 0000000..f5ed44d --- /dev/null +++ b/public/references/_attachments/certificates.cddl @@ -0,0 +1,30 @@ +certificate = tagged<{ + tree : hash-tree + signature : signature + ? delegation : delegation +}> + +hash-tree = + tree-empty / + tree-fork / + tree-labeled / + tree-leaf / + tree-pruned + +; Trees are represented as CBOR arrays instead of records with textual field +; labels, for conciseness +tree-empty = [ 0 ] +tree-fork = [ 1 hash-tree hash-tree ] +tree-labeled = [ 2 bytes hash-tree ] +tree-leaf = [ 3 bytes ] +tree-pruned = [ 4 hash ] + +delegation = { + subnet_id : bytes + certificate: bytes +} + +tagged = #6.55799(t) ; the CBOR tag + +hash = bytes +signature = bytes diff --git a/public/references/_attachments/http-gateway.did b/public/references/_attachments/http-gateway.did new file mode 100644 index 0000000..3ec2d9c --- /dev/null +++ b/public/references/_attachments/http-gateway.did @@ -0,0 +1,49 @@ +type HeaderField = record { text; text; }; + +type HttpRequest = record { + method: text; + url: text; + headers: vec HeaderField; + body: blob; + certificate_version: opt nat16; +}; + +type HttpUpdateRequest = record { + method: text; + url: text; + headers: vec HeaderField; + body: blob; +}; + +type HttpResponse = record { + status_code: nat16; + headers: vec HeaderField; + body: blob; + upgrade : opt bool; + streaming_strategy: opt StreamingStrategy; +}; + +// Each canister that uses the streaming feature gets to choose their concrete +// type; the HTTP Gateway will treat it as an opaque value that is only fed to +// the callback method + +type StreamingToken = record { + // application-specific type +}; + +type StreamingCallbackHttpResponse = record { + body: blob; + token: opt StreamingToken; +}; + +type StreamingStrategy = variant { + Callback: record { + callback: func (StreamingToken) -> (opt StreamingCallbackHttpResponse) query; + token: StreamingToken; + }; +}; + +service : { + http_request: (request: HttpRequest) -> (HttpResponse) query; + http_request_update: (request: HttpUpdateRequest) -> (HttpResponse); +} diff --git a/public/references/_attachments/requests.cddl b/public/references/_attachments/requests.cddl new file mode 100644 index 0000000..c479e37 --- /dev/null +++ b/public/references/_attachments/requests.cddl @@ -0,0 +1,113 @@ +; The "root type" of the CDDL file is a hack: We want to define multiple +; types in one file (to shared common definitions), but CDDL requires a single +; root type. So we just list the types defined here. This is a common CDDL idiom. +start = + call-request / + read-state-request / + query-request / + read-state-response / + query-response + +; common wrappers + +tagged = #6.55799(t) ; the CBOR tag + +envelope = tagged<{ + content: t + ? sender_pubkey: pubkey + ? sender_delegation: [*4 signed-delegation] + ? sender_sig: signature +}> + + +; A request as submitted to /api/v2/.../call +call-request = envelope +call-request-content = { + request_type: "call" + ? nonce : bytes + ingress_expiry : timestamp + sender : principal + canister_id : principal + method_name : text + arg : bytes + ? sender_info : sender-info +} + +; A request as submitted to /api/v2/.../read_state +read-state-request = envelope +read-state-content = { + request_type: "read_state" + ? nonce : bytes + ingress_expiry : timestamp + sender : principal + paths: [* state-path] +} + +state-path = [* path-label] +path-label = bytes + +; The response, as returned from /api/v2/.../read_state +read-state-response = tagged<{ + certificate: bytes +}> + +; A request as submitted to /api/v2/.../query +query-request = envelope +query-content = { + request_type: "query" + ? nonce : bytes + ingress_expiry : timestamp + sender : principal + canister_id : principal + method_name : text + arg : bytes + ? sender_info : sender-info +} + +; The response, as returned from /api/v2/.../query +query-response = tagged<{ + status: "replied" + reply: call-reply + signatures: [+ node-signature] + // + status: "rejected" + reject_code: unsigned + reject_message: text + ? error_code: text + signatures: [+ node-signature] +}> + +sender-info = { + info : bytes + signer : principal + sig : signature +} + +node-signature = { + timestamp: timestamp + signature: bytes + identity: principal +} + +; user delegations + +signed-delegation = { + delegation: { + pubkey: bytes + expiration: timestamp + ? targets: [* principal] + } + signature: bytes +} + +; some common data types + +call-reply = { + arg : bytes +} + +principal = bytes .size (0..29) + +pubkey = bytes +signature = bytes +timestamp = unsigned