IPIP-280: App Conventions for HTTP Gateway Detection

src/http-gateways/gateway-detection.md

@@ -0,0 +1,107 @@
+---
+title: Detecting User-Preferred IPFS Gateway
+description: >
+  Specification of the rules and standards for detecting and identifying
+  user-preferred IPFS gateways within applications, enabling seamless
+  integration and user control.
+date: 2025-12-16
+maturity: reliable
+editors:
+  - name: Mark Gaiser
+    github: markg85
+  - name: Marcin Rataj
+    github: lidel
+    url: https://lidel.org/
+    affiliation:
+        name: Shipyard
+        url: https://ipshipyard.com
+tags: ['httpGateways', 'integratingHttpGateways']
+order: 99
+---
+
+
+## Introduction
+
+This document defines conventions for how applications can identify available
+IPFS gateway, and how IPFS gateway implementations can signal own endpoint to
+client applications.
+
+## Specification
+
+There are two ways of hinting user-preferred gateway URL:
+
+- Setting the `IPFS_GATEWAY` environment variable
+- Creating a `gateway` file at a well-known path
+
+Applications SHOULD evaluate these hints in order and stop on the first match:
+
+1. Check if a valid `IPFS_GATEWAY` environment variable is set
+2. Check if a valid `gateway` file is present at one of well-known filesystem paths
+
+
+### `IPFS_GATEWAY` Environment Variable
+
+When `IPFS_GATEWAY` environment variable is set, the value SHOULD be interpreted
+as URL of IPFS Gateway application to use.
+
+This variable SHOULD override gateway selection done by all other means, including
+internal application configuration.
+
+### The `gateway` Configuration File
+
+Client application SHOULD check if file is present at specific filesystem paths, in order:
+
+1. If `IPFS_PATH` is set, try `$IPFS_PATH/gateway`
+2. If `HOME` is set, try `$HOME/.ipfs/gateway`
+3. Try OS-specific paths:
+   - Linux/Unix:
+     1. `$XDG_CONFIG_HOME/ipfs/gateway` (only if `XDG_CONFIG_HOME` is set)
+     2. `$HOME/.config/ipfs/gateway` (default XDG location)
+     3. `/etc/ipfs/gateway` (system-wide)
+   - Windows:
+     1. `%LOCALAPPDATA%/ipfs/gateway` (local user)
+     2. `%APPDATA%/ipfs/gateway` (roaming user)
+     3. `%PROGRAMDATA%/ipfs/gateway` (system-wide)
+   - macOS:
+     1. `$HOME/Library/Application Support/ipfs/gateway` (user)
+     2. `/Library/Application Support/ipfs/gateway` (system-wide)
+
+When `gateway` file is present, the file contents MUST be interpreted as an
+ASCII text file with one URL per line (separated by `\n` or `\r\n`).
+
+The first line MUST be a valid `http://` or `https://` URL without a path
+(e.g., `http://127.0.0.1:8080`). The gateway at this URL MUST support
+:cite[trustless-gateway], SHOULD support :cite[path-gateway] when deserialized
+responses are required, and SHOULD support :cite[subdomain-gateway] when Origin
+isolation is required.
+
+Implementations MAY support additional lines for gateway pools or failover.
+Implementations that do not support multiple URLs SHOULD read only the first
+line and ignore the rest of the file.
+
+### Security
+
+Applications that integrate IPFS support via HTTP gateway:
+
+MUST NOT hard-code non-localhost URL as a default fallback. Instead, SHOULD ask
+user to define preferred IPFS gateway using one of methods defined in this
+document.
+
+SHOULD either warn user when non-localhost gateway is used for deserialized
+responses (warning about the risk of MITM), or (preferred) limit HTTP use
+outside of localhost to verifiable response types defined in
+:cite[trustless-gateway].
+
+### Privacy and User Control
+
+Applications SHOULD never default to public gateways. Instead, suggest to the
+user how to run a local node.
+
+### Compatibility and Testing
+
+Implementers SHOULD test against implementations mentioned in :cite[ipip-0280]
+as the baseline for making decisions around maximizing interoperability.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

src/http-gateways/index.html

@@ -19,6 +19,8 @@ <h3>Web</h3>
     <a href="https://en.wikipedia.org/wiki/Same-origin_policy">origin-based security model</a>.
   </p>
   {% include 'list.html', posts: collections.webHttpGateways %}
+  <h3>Integration</h3>
+  {% include 'list.html', posts: collections.integratingHttpGateways %}
 </main>
 
 {% include 'footer.html' %}

src/http-gateways/libp2p-gateway.md

@@ -19,7 +19,7 @@ xref:
   - http-routing-v1
   - path-gateway
   - trustless-gateway
-tags: ['httpGateways', 'lowLevelHttpGateways', 'exchange', 'transport']
+tags: ['httpGateways', 'integratingHttpGateways', 'exchange', 'transport']
 order: 3
 ---
 

src/index.html

@@ -107,6 +107,10 @@ <h3><a href="/http-gateways/">HTTP Gateways</a></h3>
           Web semantics (for website hosting and web browsers):
         </p>
         {% include 'list.html', posts: collections.webHttpGateways %}
+        <p>
+          Other integrations:
+        </p>
+        {% include 'list.html', posts: collections.integratingHttpGateways %}
       </section>
       <section>
         <h3><a href="/data-formats">Data Formats</a></h3>

src/ipips/ipip-0280.md

@@ -0,0 +1,123 @@
+---
+title: "IPIP-0280: Conventions for HTTP Gateway Detection"
+date: 2025-12-16
+ipip: ratified
+editors:
+  - name: Mark Gaiser
+    github: markg85
+  - name: Marcin Rataj
+    github: lidel
+    url: https://lidel.org/
+    affiliation:
+        name: Shipyard
+        url: https://ipshipyard.com
+relatedIssues:
+  - https://github.com/ipfs/kubo/issues/8847
+  - https://git.ffmpeg.org/gitweb/ffmpeg.git/commit/f889837e00d3b2388a24c0a9d075ad62f47da825
+  - https://github.com/curl/curl/pull/8805
+order: 280
+tags: ['ipips']
+---
+
+## Summary
+
+This IPIP creates conventions for how applications can identify available IPFS gateway,
+and how IPFS gateway implementations can signal own endpoint.
+
+This convention has been implemented and in use since 2022 (Kubo 0.15, ffmpeg, curl 8.4).
+
+## Motivation
+
+Applications wanting to leverage IPFS Gateways are, without a common
+convention, left to invent their own ways of finding a gateway, including naive
+approaches such as localhost port scanning.
+
+This IPIP introduces specification that defines how an application wanting to
+implement IPFS support can find a local or user-preferred gateways.
+
+## Detailed design
+
+We introduce two ways of hinting user-preferred gateway URL to cover
+the majority of runtimes and use cases:
+
+- `IPFS_GATEWAY` environment variable
+- `gateway` file and filesystem paths to look for it
+
+See: :cite[gateway-detection] for details.
+
+## Design rationale
+
+### User benefit
+
+End users can define their preferred gateway once, and benefit from
+opportunistic support in applications they use.
+
+Application developers save time as they only need to implement support for
+vendor-agnostic convention to be able to read user preferred gateway.
+
+### Compatibility
+
+#### Kubo
+
+Kubo ([>0.15.0](https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.15.md#-ipfs_pathgateway-file))
+creates a hint file in `$IPFS_PATH/gateway` (default being `$HOME/.ipfs/gateway`, see [kubo#8847](https://github.com/ipfs/kubo/issues/8847)).
+
+The file contains a single line being the local HTTP gateway URL. For example: `http://localhost:8080`.
+
+Every time `ipfs daemon` starts, it updates the the content of `$IPFS_PATH/gateway` or creates the file if it doesn't exist.
+
+#### IPFS Chromium
+
+ipfs-chromium uses `IPFS_GATEWAY` environment variable
+([ipfs-chrompium#29](https://github.com/little-bear-labs/ipfs-chromium/issues/29)).
+
+It can be a single URL, or a whitespace-separated URLs to be used as the initial gateway pool.
+
+Ref. <https://blog.ipfs.tech/2023-05-multigateway-chromium-client/>
+
+#### FFMPEG
+
+FFMPEG's libavformat supports both `$HOME/.ipfs/gateway` file and `IPFS_GATEWAY` environment variable
+([ffmpeg.git/commit/f889837](https://git.ffmpeg.org/gitweb/ffmpeg.git/commit/f889837e00d3b2388a24c0a9d075ad62f47da825)).
+
+
+Ref. <https://ffmpeg.org/ffmpeg-protocols.html#ipfs>, <https://blog.ipfs.tech/2022-08-01-ipfs-and-ffmpeg/>
+
+#### Curl
+
+Curl (>8.4.0, [curl#8805](https://github.com/curl/curl/pull/8805))
+will try the `IPFS_GATEWAY` environment variable first, and then look for
+`$IPFS_PATH/gateway` or `$HOME/.ipfs/gateway`, if present.
+
+It expects a single URL.
+
+Ref. <https://curl.se/docs/ipfs.html>
+
+### Security
+
+See "Security" section of :cite[gateway-detection].
+
+### Alternatives
+
+#### Browser Environment Detection
+
+Detection via browser APIs (e.g., `localStorage.getItem('IPFS_GATEWAY')`) was
+considered but is explicitly out of scope. Any JavaScript running on a page
+could overwrite such values and hijack gateway requests. Browser-based detection
+requires a separate IPIP with proper security review.
+
+#### Gateway Health Checking
+
+This specification does not mandate health checking of detected gateways.
+Implementations MAY verify that a gateway is responsive before using it,
+but the specific approach is left to implementers.
+
+#### Stale Gateway File Handling
+
+If a daemon crashes without removing the `gateway` file, it may contain a stale
+URL. This specification does not mandate specific handling. Implementations MAY
+implement timeout-based health checks or other recovery mechanisms.
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).