docs: HTTP gateway spec reference

[marc0olo]

Summary

• 11-step request/response flow from HTTP client through canister and back
• Canister ID resolution: hostname mapping, static table, raw hostnames, custom domains
• HTTP request/response Candid interface with field documentation
• Response verification v2: certificate header, expression path, certificate expression header, hash calculations
• Response body streaming and upgrade to update calls
• Legacy v1 response verification
• Full and minimum canister HTTP Candid interfaces

Sync recommendation

informed by dfinity/portal — docs/references/http-gateway-protocol-spec.md

[marc0olo]

Review: HTTP Gateway Specification

Must fix

• Incomplete gateway-added headers list: The "HTTP Response Decoding" section notes that "HTTP Gateways may add headers such as access-control-allow-origin: * and x-cache-status: MISS." The source spec (.sources/portal/docs/references/http-gateway-protocol-spec.md) lists five headers the gateway may add: access-control-allow-origin: *, access-control-allow-methods: GET, POST, HEAD, OPTIONS, access-control-allow-headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Cookie, access-control-expose-headers: Content-Length,Content-Range, and x-cache-status: MISS. Omitting the other four is a meaningful gap for developers implementing or debugging gateways. Suggest either listing all five, or rephrasing to "headers including (but not limited to)" with the full list shown.

Suggestions

• Version 2 coverage description is slightly imprecise: The page states "Version 2 (current): covers request URL query params, request method, request headers, response status code, and response headers." In reality, these are optionally covered depending on what the canister certifies. The source says v2 "optionally" includes these parameters. A more accurate phrasing: "Version 2 (current): can optionally cover request URL query params, request method, request headers, response status code, and response headers."

• no_certification security note could cross-reference upgrade feature: The security note in the IC-CertificateExpression table says "use only for dynamic content where update-call latency is too high and a malicious response has a benign impact." The source explicitly adds "Dynamic content can be returned securely by making use of the upgrade to update feature." Adding a cross-reference link to Upgrade to update calls would strengthen the guidance for readers evaluating when no_certification is safe.

• Response Verification framing could clarify why query calls are less secure: "Query calls are fast but do not carry consensus-level security" is accurate but terse. A brief parenthetical — e.g., "(responses come from a single node without consensus verification)" — or a link to the IC Interface Spec would help developers new to IC understand the threat model without needing to look elsewhere.

Verified

• All Candid type definitions (HttpRequest, HttpResponse, HttpUpdateRequest, StreamingStrategy, StreamingCallbackHttpResponse, StreamingToken, HeaderField) exactly match the source spec in .sources/portal/docs/references/http-gateway-protocol-spec.md.
• All canister ID entries in the hardcoded hostname table match the source (rdmx6-jaaaa-aaaaa-aaadq-cai, qoctq-giaaa-aaaaa-aaaea-cai, h5aet-waaaa-aaaab-qaamq-cai, g3wsl-eqaaa-aaaan-aaaaa-cai).
• The full EBNF grammar for IC-CertificateExpression matches the source exactly.
• The Protocol Buffer 3 definition for ValidationArgs matches the source.
• The request hash and response hash calculation algorithms match the source spec step-for-step.
• The canister ID resolution rules (5 steps) match the source, including the raw-domain bypass logic and custom domain options (DNS TXT record and HEAD request).
• The response verification outline steps match the source.
• Certificate validation steps match the source.
• Expression path rules match the source.
• The response body streaming protocol description matches the source.
• The upgrade-to-update-calls behavior matches the source (ignores all other fields, passes HttpUpdateRequest without certificate_version, ignores upgrade in the update response).
• The legacy verification steps match the source (including the index.html fallback, SHA-256 hash of decoded body, streaming concatenation before decoding, Content-Encoding support for gzip and deflate).
• The version assertion behavior matches the source (request only made on downgrade, Absent lookup = gateway allows canister version, private section or rejected read_state = gateway must reject).
• Both internal links resolve: ic-interface-spec.md exists at docs/reference/ic-interface-spec.md; certification.md exists at docs/guides/frontends/certification.md.
• No dfx references, no mo:base imports, no banned external URLs.
• Frontmatter is complete and consistent (title, description, sidebar.order).
• <\!-- Upstream: --> comment is present at end of file.
• File uses .md extension, not .mdx (correct for a reference page without interactive components).
• No TODO or verification-flag comments present.
• API Gateway hostname icp-api.io matches the source.
• The minimum canister interface matches the source exactly.
• The composite query method alternative for http_request is correctly documented.
• Multiple CEL expression hashes and multiple response hashes per request hash sections correctly convey the security danger from the source spec.

[marc0olo]

<!-- feedback-addressed -->
Feedback addressed:

Changes applied

• Expanded gateway-added headers list (must fix): The "HTTP Response Decoding" section previously listed only access-control-allow-origin: * and x-cache-status: MISS. Updated to list all five headers that the gateway may add, matching the source spec in .sources/portal/docs/references/http-gateway-protocol-spec.md:

  • access-control-allow-origin: *
  • access-control-allow-methods: GET, POST, HEAD, OPTIONS
  • access-control-allow-headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Cookie
  • access-control-expose-headers: Content-Length,Content-Range
  • x-cache-status: MISS

• Clarified Version 2 coverage as optional (suggestion): Changed "covers request URL query params, request method, request headers, response status code, and response headers" to "can optionally cover ..." to match the source spec's wording ("optionally including the following extra parameters").

• Added parenthetical for query call security (suggestion): Added "(responses come from a single node without consensus verification)" after "Query calls are fast but do not carry consensus-level security" to help developers new to the IC understand the threat model.

• Added cross-reference in no_certification security note (suggestion): Added "Dynamic content can be returned securely by using the upgrade to update calls feature instead." to the no_certification table row, matching the source spec's explicit guidance and linking to the relevant section.

Items skipped

None — all feedback items were factually accurate and verified against .sources/portal/docs/references/http-gateway-protocol-spec.md.