docs(trustless-gateway): Add p2p usage section #520
Conversation
🚀 Build Preview on IPFS ready
|
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.
|
|
||
| :::note | ||
|
|
||
| Blocks larger than 2MiB can cause memory pressure on resource-constrained clients and increase the window for incomplete transfers. Since blocks must be validated as a unit, smaller blocks allow for more granular verification and easier retries on failure. |
There was a problem hiding this comment.
As alluded to above there are a whole host of issues beyond just these, some of which are bigger deals. Notably, working with larger blocks is in general, unfortunately, not yet ecosystem-safe. If you don't know what you're doing (i.e. you fall under the category of overriding the RECOMMEND / SHOULD) you're likely to cause yourself problems by virtue of building tooling that doesn't work with much else in the ecosystem.
Also, the DoS risks, and latency / excessive bandwidth consumption tradeoffs generally become more difficult.
There was a problem hiding this comment.
Given how often large block discussion comes up, improved this :::note with extra context you suggest + added link to https://discuss.ipfs.tech/t/supporting-large-ipld-blocks/15093/ in 41a766d
| Trustless Gateways serve two primary deployment models: | ||
|
|
||
| 1. **Verifiable bridges**: Gateways that provide trustless access from HTTP clients into IPFS networks, where the gateway operator is distinct from content providers | ||
| 2. **P2P retrieval endpoints**: Gateways embedded within P2P networks where they serve as HTTP interfaces to peer-operated block stores |
There was a problem hiding this comment.
nit: I get we're stuck with this phrasing to some extent, but IMO if we can shy away from referring to implementations of the non-recursive trustless IPFS HTTP gateway API used in a p2p network as gateways that'd be great. They're not really gateways into the network as much as part of it 😅.
There was a problem hiding this comment.
I've been using "HTTP providers" while talking with FIL folks, to make it clear when I mean non-recursive gateway, maybe introduce that term here?
Pushed in 5fabd52
|
|
||
| To work around this limitation, clients must open multiple parallel TCP connections to achieve concurrent requests. However, each additional connection incurs significant overhead: TCP handshake latency, memory buffers, bandwidth competition, and increased implementation complexity. Browsers limit concurrent connections per origin (typically 6-8) to manage these costs, but this limitation affects all HTTP/1.1 clients, not just browsers, as the overhead of maintaining many connections becomes prohibitive. | ||
|
|
||
| When fetching a DAG that requires many block requests, HTTP/1.1's lack of multiplexing creates a critical bottleneck. Clients face a difficult trade-off: either serialize requests (severely limiting throughput) or maintain many parallel connections (incurring substantial overhead). Users may experience acceptable performance with small test cases, but real-world IPFS content with deep DAG structures will encounter significant slowdowns. HTTP/2's stream multiplexing (:cite[rfc9113]) eliminates this bottleneck by allowing many concurrent requests over a single connection without head-of-line blocking at the application layer. |
There was a problem hiding this comment.
This is true, but even if not relying on block requests (e.g. CARs with queries sufficient to describe what the client needs) there are other constraints within p2p networks that can cause issues here too (e.g. optimistic queries which also eat up requests).
|
|
||
| Trustless Gateways operating in P2P contexts SHOULD NOT recursively search for content. | ||
|
|
||
| In P2P networks, gateways typically serve as block stores for specific peers or content, rather than attempting to locate content across the entire network. Recursive content discovery is handled by the P2P layer (e.g., Amino DHT, IPFS routing), not by individual HTTP gateways. |
There was a problem hiding this comment.
Recursive content discovery
This isn't quite right. Recursion implies it happens again (e.g. a gateway that returns data itself doing data lookups, or a routing endpoint itself doing routing lookups), the Amino DHT, etc. don't do that. Additionally, as this is sort of longer justification it should probably move into the note section as well,
Does this sentence need to exist given the note below seems to cover the same content anyway?
- fix block size rationale: UnixFS → Bitswap/ecosystem, add link to discuss.ipfs.tech thread on large blocks - broaden HTTP/2 multiplexing examples to include CAR queries and optimistic HEAD/GET probes - fix "recursive" terminology in content discovery paragraph
move rationale from main body to note, keeping only normative SHOULD statements in main body for scannability
clarify that P2P retrieval endpoints are network participants, not bridges, addressing review feedback about "gateway" semantics
…ty section - clarify h2c as "HTTP/2 over cleartext TCP, without TLS" - rename section headers to "HTTP Servers" and "HTTP Clients" - add explicit MUST/SHOULD to each security requirement for testability - transport security is MUST, block validation is MUST, rest are SHOULD
There was a problem hiding this comment.
@aschmahmann pushed some final editorials based on feedback, take a look.
If looks fine, we can merge.
Clarify caveats around utilizing trustless gateways within p2p networks.
Closes #519
cc @lidel