From 0eacf6a60bc5627d895b70ee4a5602af7f4a79e1 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Thu, 6 Jul 2023 20:16:41 +0200
Subject: [PATCH 1/2] ipip-425: Signaling Features on HTTP Gateways

Initial version to kick-off discussion
---
 src/http-gateways/path-gateway.md | 40 ++++++++++++++
 src/ipips/ipip-0425.md            | 92 +++++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+)
 create mode 100644 src/ipips/ipip-0425.md

diff --git a/src/http-gateways/path-gateway.md b/src/http-gateways/path-gateway.md
index 61aa6b568..6440cd60d 100644
--- a/src/http-gateways/path-gateway.md
+++ b/src/http-gateways/path-gateway.md
@@ -542,6 +542,46 @@ Optional, present in certain response types:
   non-executable binary response types are not used in `<script>` and `<style>`
   HTML tags.
 
+### `Ipfs-Gateway-Features` (response header)
+
+Optional, this header SHOULD be only returned in response to HTTP `OPTIONS` request.
+
+The value is a list of key-value pairs, as specified by the 5.6.1. Lists section of :cite[rfc9110].
+
+Each feature is indicated by a key and optional value. When more than one value is supported, `|` is used as a separator.
+For example:
+
+```
+Ipfs-Gateway-Features: foo, bar=1, buzz=a|b|c
+```
+
+A Gateway SHOULD use this header to communicate support for specific Gateway feeatures, enabling clients to make better decisions on how to retrieve data.
+
+A Gateway MAY define and return their own features.
+
+A Client MUST send HTTP OPTIONS request to inspect this header before performaning any more expensive feature-detection.
+
+#### Canonical Ipfs-Features values
+
+- `trustless-gateway` for :cite[trustless-gateway]
+  - `path-proof` indicates support for returning parent blocks up to the terminus element
+  - `car-version=1|2` indicates CAR support
+  - `dag-scope=block|entity|all` from :cite[ipip-0402]
+  - `entity-bytes` from :cite[ipip-0402], implies support for `dag-scope=entity` as well
+  - `car-block-order=dfs` from :cite[ipip-0412]
+  - `car-block-dupes=y|n`  from :cite[ipip-0412]
+- `path-gateway` for deserialized responses defined by :cite[path-gateway]
+- `subdomain-gateway=example.com` for :cite[subdomain-gateway] support based on `Host` header
+- `dnslink-gateway` for :cite[dnslink-gateway] support based on `Host` header
+- `ipns` indicating :cite[ipns-record] support on `/ipns/` content paths
+- `dnslink` indicating [DNSLink](https://dnslink.dev) support on `/ipns/` content paths
+
+<!-- TODO do we want these too?
+- `multibase` list of prefixes, indicates which multibase encoding are supported in CIDs
+- `multihash` indicates which hash functions are supported in CIDs
+- `multicodec` indicates which codecs are supported in CIDs
+-->
+
 ### `Server-Timing` (response header)
 
 Optional. Implementations MAY use this header to communicate one or more
diff --git a/src/ipips/ipip-0425.md b/src/ipips/ipip-0425.md
new file mode 100644
index 000000000..3c96b01d1
--- /dev/null
+++ b/src/ipips/ipip-0425.md
@@ -0,0 +1,92 @@
+---
+title: "IPIP-0425: Signaling Features on HTTP Gateways"
+date: 2023-07-06
+ipip: proposal
+editors:
+  - name: Marcin Rataj
+    github: lidel
+    url: https://lidel.org/
+relatedIssues:
+  - https://github.com/ipfs/specs/pull/402#pullrequestreview-1396116569
+  - https://github.com/ipfs/specs/pull/412#pullrequestreview-1427137365
+order: 425
+tags: ['ipips']
+---
+
+## Summary
+
+Add ability to query HTTP Gateway for an explicit list of supported features.
+
+## Motivation
+
+A Gateway always ships with an opinionated set of supported hash functions and
+IPLD codecs, and the differences between implementations will grow over time.
+
+For example, some legacy gateways may not support newly added features like
+`dag-scope` and `entity-bytes` from :cite[ipip-0402] or the ability to get some
+block ordering guarantees introduced in :cite[ipip-0412]. Future IPIPs may add
+more features and response formats.
+
+We need a light mechanism for clients to detect which gateway supports partial CARs
+
+## Detailed design
+
+This IPIP introduces a set of HTTP headers returned in response to `OPTIONS` request:
+
+The `Ipfs-Gateway-Features` header is used for signalling support for specific Gateway features to the client.
+
+The lack of the header, or missing key-value pair within the header means support status is unknown.
+
+Initial list of key-value pairs is documented in `Ipfs-Gateway-Features` section of :cite[path-gateway]
+
+## Design rationale
+
+There is a good prior art for this in web browsers where HTTP `OPTIONS` method
+is used in [CORS Preflight request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request)
+that checks if the CORS protocol is understood and a server is aware using
+specific methods and headers.
+
+The `OPTIONS` request if often sent by web browser anyway, so we would not be
+introducing much overhead.
+
+### User benefit
+
+Reduced cost for both client and gateway. Sending `OPTIONS` request will be
+very inexpensive, especially when compared with current status quo where a
+client has to send at least one request to probe a specific feature like
+support forp Blake3 hash function or `dag-scope` or `entity-bytes`.
+
+This translates to decreased latency and ability to choose the best retrieval
+strategy faster.
+
+### Compatibility
+
+This IPIP is fully backward-compatible with browsers and existing IPFS
+ecosystem. Gateways already return CORS headers with `OPTIONS` responses, we
+will simply return additional headers with the same responses.
+
+:::issue
+
+For JavaScript running on web pages to be able to read `Ipfs-Gateway-Features`
+header it MUST be safelisted via `Access-Control-Expose-Headers`.
+
+:::
+
+### Security
+
+This IPIP does not introduce any new security concerns. Probing gateway for
+supported features and hash functions is already possible via regular `GET`
+requests.
+
+### Alternatives
+
+- Exposing the list of suported features via `GET /.well-known/ipfs/gateway/features-TBD` would also work, but:
+  - introduces surface for path-related deployment bugs, where Nginx is only exposing `/ipfs` namespace – in such case signaling endpoint would not be exposed to the public internet
+
+## Test fixtures
+
+TODO
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

From 9cfc305a30b8e9e368c0a314aa2f29185fbf187a Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Tue, 11 Jul 2023 15:10:00 +0200
Subject: [PATCH 2/2] ipip-425: explain why not .well-known path

---
 src/ipips/ipip-0425.md | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/ipips/ipip-0425.md b/src/ipips/ipip-0425.md
index 3c96b01d1..b29be8700 100644
--- a/src/ipips/ipip-0425.md
+++ b/src/ipips/ipip-0425.md
@@ -80,8 +80,29 @@ requests.
 
 ### Alternatives
 
-- Exposing the list of suported features via `GET /.well-known/ipfs/gateway/features-TBD` would also work, but:
-  - introduces surface for path-related deployment bugs, where Nginx is only exposing `/ipfs` namespace – in such case signaling endpoint would not be exposed to the public internet
+- Exposing the list of suported features via `GET
+  /.well-known/ipfs/gateway/features-TBD` would also work, but:
+  - `/.well-known` is an additional top-level namespace than needs to be
+    explicitly exposed
+    - this introduces surface for path-related deployment bugs, where Nginx is
+      only exposing `/ipfs` namespace – in such case signaling endpoint would
+      not be exposed to the public internet
+    - this is a real problem, as all legacy deployments expose `/ipfs` and
+      `/ipns` and even when Kubo or other implementation adds `/.well-known` it
+      will not be exposed to the internet, breaking the feature detection
+      scheme, and making the gateway look like a legacy one
+  - requires additional HTTP GET, while in some cases HTTP OPTIONS is already
+    sent (e.g., [browser's preflight
+    requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#preflighted_requests)),
+    and would not  introduce no overhead
+    - if we have different services running on the same Origin, with
+      `.well-known` we need to make multiple GET requests for different
+      `.well-known/..` paths, vs sending a single HTTP OPTIONS and getting all
+      headers related to pre-existing path
+  - HTTP headers can be added as the rrqueest passes via reverse proxies, CDNs
+    and load balancers, allowing different services to announce support for
+    different features. this "just works" while mutating response  body for
+    `.well-known` manifest introduces the need for additional middleware.
 
 ## Test fixtures