docs: HTTPS outcalls concept page

[marc0olo]

Summary

Concept page explaining how HTTPS outcalls work at the protocol level:

• Why HTTPS outcalls exist (replacing oracles)
• How consensus works: replicated requests, transform functions, 2/3 agreement
• Local vs mainnet testing caveat (single node doesn't exercise consensus)
• Transform function strategies (extract vs strip)
• Request types and idempotency (GET/HEAD/POST, idempotency keys)
• HEAD use case for determining response size
• Cycle cost model (request size + max_response_bytes)
• Limitations (HTTPS-only, 2MB, public endpoints, timeout, rate limiting, API key exposure with TEE mitigation)
• Comparison table: HTTPS outcalls vs oracles
• Future extensions (flexible quorum, multiple responses)

Sync recommendation

Informed by .sources/portal/docs/references/https-outcalls-how-it-works.mdx and .sources/portal/docs/building-apps/network-features/using-http/https-outcalls/overview.mdx. Hand-written synthesis — not directly synced.

[marc0olo]

Review: HTTPS Outcalls (Concept Page)

Must fix

• Consensus threshold wording: The page says "at least 2/3 of replicas (specifically 2f+1, where f is the number of faulty replicas tolerated)". This is correct per the portal source, but the parenthetical is potentially confusing — 2f+1 out of 3f+1 total nodes gives 2/3 + 1, which is more than 2/3. The page says "at least 2/3" and then the parenthetical contradicts with a stricter quorum. Suggest simplifying to: "requires at least 2/3 of replicas to produce the same transformed response" and dropping the 2f+1 detail (this is a concept page, not a protocol spec).

Suggestions

• Missing "coding recipe" from portal: The portal source has a practical 5-step recipe for developing an outcall (Step 1: manually curl twice, Step 2: diff responses, Step 3: implement transform, Step 4: determine max_response_bytes, Step 5: implement and test). This is exactly the kind of actionable developer guidance that bridges concept to practice. Consider adding a brief "How to develop an HTTPS outcall" section or at least summarizing the recipe and pointing to the guide. The content brief says "Focus on what developers need to know to use outcalls correctly" — this recipe fits that goal.

• Common errors section missing: The portal source lists several specific error messages developers will hit (SysFatal - URL needs to specify HTTPS scheme, SysFatal - Timeout expired, CanisterReject - http_request request sent with 0 cycles, etc.). While error reference may belong in the guide page, at least mentioning that timeouts typically indicate a bad transform function would help developers debug the most common failure mode.

• Local vs. mainnet behavior gap not called out: The portal source emphasizes: "If a specific type of canister HTTP request works in the local environment, it may still not work on ICP because the local environment only makes a single call to the remote server." The guide page (PR docs: HTTPS outcalls guide #10) covers this in its testing section, but since this is the concept page explaining how consensus works, it's a natural place to note that local testing doesn't exercise the consensus path. A one-liner would suffice.

• "Shared API keys are visible to all replicas" section could be stronger: The portal source goes further — a compromised replica can use stored credentials to make arbitrary unauthorized requests, not just the canister's intended ones. The current wording ("A compromised replica could use it to make unauthorized requests") captures this but could be more explicit about the scope: the replica can make entirely different requests to the server using your API key, not just replay the canister's request.

• HEAD method use case: The portal source mentions a practical use for HEAD: determining the response size before making the actual request (to set max_response_bytes accurately). The page mentions HEAD in the request types section but doesn't explain why it's useful. A brief note would add value.

• Future extensions omitted: The portal discusses flexible quorum (only 1 replica makes the request) and multiple responses (canister receives all responses instead of consensus). These are forward-looking but relevant for developers making architecture decisions today — e.g., knowing that reduced quorum for POST is coming might affect their design. Consider a brief mention.

• Learn Hub not linked: The stub lists Learn Hub: HTTPS Outcalls (https://learn.internetcomputer.org/hc/en-us/articles/34211194553492) as source material. The page doesn't link to it. If it covers complementary material, it's worth a "Further reading" link.

Verified

• All internal links resolve: ../guides/backends/https-outcalls.md, ../guides/chain-fusion/ethereum.md, ../reference/cycles-costs.md all exist
• No external URLs to verify (page has none beyond the sync comment)
• No CLI commands (correct for a Diataxis concept page)
• No code snippets (correct for a concept page — defers to the guide)
• No dfx references — clean
• No .mdx/JSX — plain markdown throughout
• Frontmatter complete and consistent with body
• Sync recommendation present and matches PR body
• Content brief coverage: ✅ why HTTP from blockchain is hard, ✅ transform function mechanism, ✅ cycle pricing, ✅ response size limits, ✅ limitations (no WebSocket, no streaming). All brief topics addressed.
• Cross-links from stub all included: ✅ guides/backends/https-outcalls, ✅ guides/chain-fusion/ethereum, ✅ reference/cycles-costs
• Technical claims (2MB limit, ~30s timeout, HTTPS-only, public endpoints only) verified against portal source and icskill
• Diataxis compliance: page is explanatory, avoids how-to steps, correctly defers practical guidance to the guide page
• Comparison table (HTTPS outcalls vs. oracles) is well-structured and accurately reflects the portal source's more verbose comparison

[marc0olo]

Feedback addressed:

• Simplified consensus threshold to "at least 2/3" — dropped the 2f+1 parenthetical
• Added local vs mainnet testing caveat (single node passes consensus trivially)
• Added timeout as common failure mode when transform is insufficient
• Explained HEAD use case for determining response size to set max_response_bytes
• Strengthened API key wording — compromised replica can make entirely different requests
• Added "Future extensions" section (flexible quorum, multiple responses) for architecture planning
• Added Learn Hub link to "Next steps"
• Skipped reproducing the 5-step coding recipe — it's how-to guidance that belongs in the guide page. The concept page bridges to the guide via existing links.
• Skipped specific error strings — the guide covers "no consensus" debugging, and execution-errors.md (reference, currently a stub) is the right home for the full error catalog. Added one sentence about timeout being the most common failure mode.