IPIP-0461: Ipfs-Path-Affinity on Gateways

Author: lidel

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.

src/http-gateways/trustless-gateway.md

@@ -88,6 +88,15 @@ 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`)
+
 ## Request Query Parameters
 
 ### :dfn[dag-scope] (request query parameter)

src/ipips/ipip-0461.md

@@ -0,0 +1,80 @@
+---
+title: "IPIP-0461: 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: 461
+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.
+
+Not every CID is announced today, some providers limit announcements to
+top-level root CIDs due to time and cost.
+
+What this mean for ecosystem? It should adapt. Over time, both clients and
+servers should leverage the concept of "affinity".
+
+## 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.
+
+Gateway being 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 internal blocks are not announced.
+
+### Compatibility
+
+This is an optional HTTP header which makes it backward-compatible with
+existing ecosystem of HTTP clients and IPGS Gateways.
+
+### Security
+
+The client is in control when the affinity information is sent in the header,
+and implementation SHOULD allow end user to disable it in context where parent
+content path information is considered sensitive information.
+
+### Alternatives
+
+N/A
+
+## Test fixtures
+
+N/A
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).