docs(trustless-gateway): Add p2p usage section #520
Conversation
🚀 Build Preview on IPFS ready
|
| Gateways serving data to non-LAN peers SHOULD support HTTPS and HTTP/2 or greater. | ||
| Similarly, it is RECOMMENDED that clients restrict to HTTPS and HTTP/2 or greater. |
There was a problem hiding this comment.
Note: Technically #519 asks for "why is http/2 recommended" rather than just documenting that it's the case. IIUC generally we don't specify rationale within the spec document, but if it makes sense we can.
As I was quoted in the above issue my understanding for how we ended up with http/2 as required within boxo (and recommended in general) is:
- HTTP/1.1 does not have multiplexing which means that if we clients want to send many downloading requests (e.g. for various resources, to handle parallel block requests, optimistic queries to avoid having to round-trip through the content routing system, etc.) this will be quite painful
- Browsers in particular have a limited number of concurrent requests they can make at a time with http 1.1 to a given origin (6-8 iirc). This means that supporting http/1.1 would mean users would sometimes see reasonable performance but frequently get pretty bad performance
- The result is it seemed better to not support http/1.1 at all then put users in the patchwork "but it works on my small test, oh well I guess ipfs is just slow" regime
Note: "Recommended" is present in the spec because sometimes the developer understands the caveats present and decides to support HTTP/1.1 anyway. For example, within browsers there's no control over which HTTP versions are used so the client will support them all anyway even if a server using HTTP/1.1 ultimately performs poorly. Similarly, in LAN environments getting a TLS certificate setup with which to use HTTPS may be painful, h2c may not be easily accessible across platforms / languages, and performance criteria are more controllable which makes the downsides more manageable.
There was a problem hiding this comment.
Thanks for adding this. Rationale sgtm, but should be in the document imo: I've pushed b155d57 which expands the P2P usage section with detailed rationale for HTTP/2 and TLS requirements. Since this is in "Appendix: Notes for implementers", I think it is fine to provide extra context (as :::note) explaining WHY these are SHOULD requirements:
- HTTP/2: explain head-of-line blocking, connection overhead, and impact on DAG fetching with many block requests
- TLS: clarify privacy vs integrity (multihash provides integrity, TLS provides confidentiality and is required for HTTP/2 in browsers)
- Add security considerations for both gateway operators and clients
- Include practical defaults (30s timeout, 2MiB blocks)
- Reference RFC 9113 for HTTP/2 specifications
If not for humans, this "WHY" will be even more important for LLMs that will generate client/server code for this spec.
@aschmahmann @BigLep thoughts?
Clarify caveats around utilizing trustless gateways within p2p networks
aschmahmann
force-pushed
the
feat/trustless-gateway-p2p-notes
branch
from
ab86146 to
f7daba8
Compare
…nale Expand the P2P usage section with detailed rationale for HTTP/2 and TLS requirements. Since this is in "Appendix: Notes for implementers", we provide extra context explaining why these are SHOULD requirements: - HTTP/2: explain head-of-line blocking, connection overhead, and impact on DAG fetching with many block requests - TLS: clarify privacy vs integrity (multihash provides integrity, TLS provides confidentiality and is required for HTTP/2 in browsers) - Add security considerations for both gateway operators and clients - Include practical defaults (30s timeout, 2MiB blocks) - Reference RFC 9113 for HTTP/2 specifications Addresses #519 request to document why HTTP/2 is recommended rather than just stating the requirement.
Clarify caveats around utilizing trustless gateways within p2p networks.
Closes #519
cc @lidel