From 8ecfec12ee2a279c6414e78fc72c74b18711b3d3 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Fri, 16 Feb 2024 19:11:42 +0100
Subject: [PATCH] IPIP-0461: Ipfs-Path-Affinity on Gateways

---
 src/http-gateways/path-gateway.md      |  4 ++
 src/http-gateways/trustless-gateway.md |  9 +++
 src/ipips/ipip-0461.md                 | 80 ++++++++++++++++++++++++++
 3 files changed, 93 insertions(+)
 create mode 100644 src/ipips/ipip-0461.md

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..bbe96c41 100644
--- a/src/http-gateways/trustless-gateway.md
+++ b/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)
diff --git a/src/ipips/ipip-0461.md b/src/ipips/ipip-0461.md
new file mode 100644
index 00000000..da90f67a
--- /dev/null
+++ b/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/).