diff --git a/src/http-gateways/path-gateway.md b/src/http-gateways/path-gateway.md index 3c0e14af..ed9f7009 100644 --- a/src/http-gateways/path-gateway.md +++ b/src/http-gateways/path-gateway.md @@ -195,6 +195,10 @@ Gateway should refuse attempts to register a service worker for entire Requests to these paths with `Service-Worker: script` MUST be denied by returning HTTP 400 Bad Request error. +### `Ipfs-Path-Affinity` (request header) + +Optional content routing hint, see [`Ipfs-Path-Affinity`](https://specs.ipfs.tech/http-gateways/trustless-gateway/#ipfs-path-affinity-request-header) in :cite[trustless-gateway]. + ## Request Query Parameters All query parameters are optional. diff --git a/src/http-gateways/trustless-gateway.md b/src/http-gateways/trustless-gateway.md index 71ae1f30..240ab902 100644 --- a/src/http-gateways/trustless-gateway.md +++ b/src/http-gateways/trustless-gateway.md @@ -4,15 +4,21 @@ description: > The minimal subset of HTTP Gateway response types facilitates data retrieval via CID and ensures integrity verification, all while eliminating the need to trust the gateway itself. -date: 2023-06-20 +date: 2024-03-22 maturity: reliable editors: - name: Marcin Rataj github: lidel url: https://lidel.org/ + affiliation: + name: IP Shipyard + url: https://ipshipyard.com - name: Henrique Dias github: hacdias url: https://hacdias.com/ + affiliation: + name: IP Shipyard + url: https://ipshipyard.com xref: - url - path-gateway @@ -88,6 +94,30 @@ Below response types SHOULD be supported: A Gateway SHOULD return HTTP 400 Bad Request when running in strict trustless mode (no deserialized responses) and `Accept` header is missing. +### `Ipfs-Path-Affinity` (request header) + +Optional content routing hint for the server. Indicates that the requested +resource is a subset of a bigger DAG. + +A Client SHOULD use it to send a relevant parent content path when: +- fetching a big file block by block (`application/vnd.ipld.raw`) +- parallelizing DAG download by fetching each branch sub-DAG as a CAR (`application/vnd.ipld.car`) + +The value of `Ipfs-Path-Affinity` header SHOULD be percent-encoded +([ECMA262: `encodeURIComponent`](https://tc39.es/ecma262/multipage/global-object.html#sec-encodeuricomponent-uricomponent)) +unless it meets the following conditions: +- contains no path beyond the root identifier (`/ipfs/cid`) +- contains no whitespace characters +- contains no `:` characters +- contains no non-ASCII characters + +A gateway backend SHOULD leverage this hint to improve retrieval by querying +providers of additional content paths in addition to the requested one. + +Gateway implementation SHOULD support client requests with `Ipfs-Path-Affinity` +header being present more than once, but also SHOULD set a hard limit of hints +to process (e.g. 3) to avoid abuse. + ## Request Query Parameters ### :dfn[dag-scope] (request query parameter) diff --git a/src/ipips/ipip-0462.md b/src/ipips/ipip-0462.md new file mode 100644 index 00000000..99cb0800 --- /dev/null +++ b/src/ipips/ipip-0462.md @@ -0,0 +1,99 @@ +--- +title: "IPIP-0462: Ipfs-Path-Affinity on Gateways" +date: 2024-02-16 +ipip: proposal +editors: + - name: Marcin Rataj + github: lidel + url: https://lidel.org/ + affiliation: + name: IP Shipyard + url: https://ipshipyard.com +relatedIssues: + - https://github.com/ipfs/kubo/issues/10251 + - https://github.com/ipfs/kubo/issues/8676 +order: 462 +tags: ['ipips'] +--- + +## Summary + +This IPIP adds gateway support for optional `Ipfs-Path-Affinity` HTTP request header. + +## Motivation + +Endpoints that implement :cite[trustless-gateway] may receive requests for a +single block, or a CAR request sub-DAG of a biger tree. + +While every piece of data that is supposed to be able to be accessed +independently should be advertised on routing system, not every CID is today. +Some providers limit announcements to top-level root CIDs due to time, cost, or +misconfiguration. + +What does this mean for the ecosystem? It should adapt and ensure +implementations leverage all infromation provided by the end user. + +Over time, both clients and servers should leverage the concept of "affinity". + +The introduction of an optional `Ipfs-Path-Affinity` header aims to increase +the success rate of the gateway retrieving internal standalone blocks or byte +ranges, especially if the requested blocks are not announced on routing +systems, but belong to a bigger DAG, and only the root CID of that parent DAG +is announced. + +## Detailed design + +Introduce `Ipfs-Path-Affinity` HTTP request header to allow HTTP client to +inform gateway about the context of block/CAR request. + +Client asking gateway for a block SHOULD provide a hint about the DAG the block +belongs to, if such information is available. + +A gateway unable to find providers for internal block should be +able to leverage affinity information sent by client and use CIDs of parent +path segments as additional content routing lookup hints. + +## Design rationale + +### User benefit + +When supported by both client and server: + +- Light clients are able to use trustless HTTP gateway endpoints more + efficiently, resume downloads faster. +- Gateway operators are able to leverage the hint and save resources related to + provider lookup. +- Content providers are able to implement smarter announcement mechanisms, + without worrying that some internal blocks are not announced (intentionally or unintentionally). + +### Compatibility + +This is an optional HTTP header which makes it backward-compatible with +existing ecosystem of HTTP clients and IPFS Gateways. + +### Security + +The client is in control when the affinity information is sent in the header, +and an implementation SHOULD allow an end user to disable it in context where parent +content path information is considered sensitive information. + +Gateway implementation that supports `Ipfs-Path-Affinity` header being present +more than once MUST also set limit (e.g. max 3) to avoid abuse. + +### Alternatives + +- Why not just an arbitrary identifier the user could use to establish a + relationship between requests? + - Requires server to keep state, which breaks or complicates gateway + deployments with horizontal scaling. + - Does not help when client is sending requests for different blocks/sub-DAGs + to different trustless gateways, and none of them has the whole picture, + and majority of them do not know what is the parent content path. + +## Test fixtures + +N/A + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).