IPIP-280: App Conventions for HTTP Gateway Detection

src/http-gateways/gateway-detection.md

@@ -0,0 +1,102 @@
+---
+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: 2023-10-03
+maturity: reliable
+editors:
+  - name: Mark Gaiser
+    github: markg85
+  - name: Marcin Rataj
+    github: lidel
+    url: https://lidel.org/
+    affiliation:
+        name: Protocol Labs
+        url: https://protocol.ai/
+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-prefered 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 MUST 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. If `$XDG_CONFIG_HOME` is set, try `$XDG_CONFIG_HOME/ipfs/gateway`
+4. If `/etc` exists, try `/etc/ipfs/gateway`
+5. Try OS-specific paths
+   - Windows
+     1. `%LOCALAPPDATA%/ipfs/gateway` (local user)
+     2. `%APPDATA%/ipfs/gateway` (roaming user)
+     3. `%PROGRAMDATA%/ipfs/gateway` (global)
+   - macOS
+     1. `$HOME/Library/Application Support/ipfs/gateway` (user)
+     2. `/Library/Application Support/ipfs/gateway` (global)
+   - Linux
+     1. `$HOME/.config/ipfs/gateway` (user)
+     2. `/etc/ipfs/gateway` (global)
+
+When `gateway` file is present, the file contents MUST be interpreted as line
+separated (`\n` or `\r\n`) `text/plain` file.
+
+The first line of `gateway` file MUST be a valid `http://` or `https://` URL.
+
+Implementations that only need one URL SHOULD use the first one 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/index.html

@@ -93,6 +93,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="/ipns/">InterPlanetary Naming System</a></h3>

src/ipips/ipip-0280.md

@@ -0,0 +1,104 @@
+---
+title: "IPIP-0280: Conventions for HTTP Gateway Detection"
+date: 2023-10-03
+ipip: proposal
+editors:
+  - name: Mark Gaiser
+    github: markg85
+  - name: Marcin Rataj
+    github: lidel
+    url: https://lidel.org/
+    affiliation:
+        name: Protocol Labs
+        url: https://protocol.ai/
+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 aims to create conventions for how applications can identify available IPFS gateway,
+and how IPFS gateway implementations can signal own endpoint.
+
+## 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-prefered 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 prefered 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://blog.ipfs.tech/2022-08-01-ipfs-and-ffmpeg/>
+
+#### Curl
+
+Curl (>8.4.0, [curl#8805](https://github.com/curl/curl/pull/8805)) supports
+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
+
+N/A. This IPIP covers both environment variable and configuration file.
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).