IPIP-280: App Conventions for HTTP Gateway Detection by markg85 · Pull Request #280 · ipfs/specs

markg85 · 2022-05-13T19:34:41Z

This should help other application developers to have an idea of what's needed to add IPFS support to their application.

cc @Stebalien and @autonome Conversations with mainly you two have led to this spec being implemented as is written here in ffmpeg.

closes Easy-to-implement gateway-less IPFS URLs #192

This should help other application developers to have an idea of what's needed to add IPFS support to their application.

markg85 · 2022-07-23T15:47:49Z

Ping. What's still required for this document to get merged?
Do note that the document is called INTEGRATION.md because it's intended to be used by those "integrating" IPFS support in their applications.

Don't confuse this with the document the add the gateway file in the IPFS data folder. While this document "sort of refers" to it in terms of functionality, it doesn't spec - nor should it - how that file is created. That detail should be of no concern to those integrating IPFS support.

pimterry · 2022-08-16T11:16:44Z

Hi @markg85, two quick comments on this from some related discussion in ipfs/in-web-browsers#197:

Could we extend this just slightly, to also specify gateway detection for browser JS environments? This is a common use case, which I think could easily closely match what you're suggesting here, by using a global window.IPFS_GATEWAY env var to allow browser and browser extensions to inject gateway configuration into JS apps. Similarly, those apps should use that configuration if available, or use the fallback gateway if not.
This spec covers gateways only, but that's not the only way people may want to integrate IPFS into their applications. There's many interesting use cases where 3rd-party applications might want to interact with the network more generally, by embedding a full IPFS node. When doing so, it would be useful to provide very similar mechanisms to detect a user's preferred network configuration (particularly for web applications - see As a user, there is no mechanism to control the IPFS networking of a webapp I use in-web-browsers#197 for lots more context). Of course I don't want to derail this PR, which can happily proceed ignoring all that, but I think this would fit well as an extension to this 'Integration' guide later on. Do you think that makes sense? How about if I open up a PR against your branch here to start discussion on that too, but independently?

ipfs/specs#280 License: MIT Signed-off-by: Marcin Rataj <lidel@lidel.org>

* Using async-await * feat: support IPFS_GATEWAY env ipfs/specs#280 Signed-off-by: Marcin Rataj <lidel@lidel.org> Signed-off-by: Marcin Rataj <lidel@lidel.org> Co-authored-by: Marcin Rataj <lidel@lidel.org>

lidel

@markg85 time to revisit this, now that we have IPIP process. some pointers below :)

markg85 · 2022-11-19T15:38:03Z

Hi @markg85, two quick comments on this from some related discussion in ipfs/in-web-browsers#197:

Could we extend this just slightly, to also specify gateway detection for browser JS environments? This is a common use case, which I think could easily closely match what you're suggesting here, by using a global window.IPFS_GATEWAY env var to allow browser and browser extensions to inject gateway configuration into JS apps. Similarly, those apps should use that configuration if available, or use the fallback gateway if not.

I get the mindset here and it would help a lot! Not just with apps using IPFS but also with js libraries (think for example video.js) where we'd like to have IPFS integration in at some point in time too. Having a window.IPFS_GATEWAY would surely help!

But.. how?

When IPFS Companion is used, injecting a variable is doable.
But for IPFS integration in brave, that would be a code change on the brave side.

The downside is another point of metric collection to profile people. And for that reason alone i don't think this variable would be accepted. Even if we would all like it and add it to the spec, the browser security minded folks would probably have an issue with it.

@lidel do you have an opinion on this?

This spec covers gateways only, but that's not the only way people may want to integrate IPFS into their applications. There's many interesting use cases where 3rd-party applications might want to interact with the network more generally, by embedding a full IPFS node. When doing so, it would be useful to provide very similar mechanisms to detect a user's preferred network configuration (particularly for web applications - see As a user, there is no mechanism to control the IPFS networking of a webapp I use in-web-browsers#197 for lots more context). Of course I don't want to derail this PR, which can happily proceed ignoring all that, but I think this would fit well as an extension to this 'Integration' guide later on. Do you think that makes sense? How about if I open up a PR against your branch here to start discussion on that too, but independently?

Usually i'd say "yes, go for it!" but in this case, waiting is probably the smarter move. If you'd go for that you'd have a spec wip branch on top of my wip branch. That's a little too much wip. Wait till this spec lands (it's mostly there) before you consider making a spec on top of this one.

markg85 · 2022-11-19T15:39:49Z

@markg85 time to revisit this, now that we have IPIP process. some pointers below :)

Sweet!
Will update it all in the next couple days. Thank you for all the pointers, much appreciated!

Co-authored-by: Marcin Rataj <lidel@lidel.org>

lidel

Quick feedback:

make this Kubo-agnostic
document configuration location on MS Windows and macOS
ensure manually added entries are not removed by starting/stopping local node
allow for multiple local gateways to co-exist, and not "steal" traffic

lidel

Thanks for ping. This spec documents something that's already working in the wild (curl, ffmpeg, kubo's $IPFS_PATH/gateway), which is valuable, and ratification feels like a formality:

Project	Reads `IPFS_GATEWAY`	Reads `gateway` file	Writes `gateway` file
Kubo	-	-	Yes (since v0.15)
curl	Yes	Yes (`~/.ipfs/gateway`)	-
ffmpeg	Yes	Yes (`$IPFS_PATH/gateway` or `~/.ipfs/gateway`)	-

I've pushed some cosmetic changes, but would like second set of eyes on this before we merge (@markg85 / @2color ?)

IIUC this spec documents existing behavior that's already shipping in curl and ffmpeg, and having it written down helps future implementers (especially when LLMs are reading and likely prioritizing specification documents for best-practices when code generating).

markg85 · 2025-12-17T00:26:25Z

Hi @lidel,

Thank you for your updates, that's much appreciated!

I just went over the text and it looks oke to me. I can't give an approve as I'm the author (not allowed in the ui) but consider this my stamp of approval ✔️

lidel · 2025-12-17T15:45:58Z

Thank you. Let's keep this open over holidays in case someone wants to provide late feedback. Ok to merge in January when we are back from a break.

2color · 2025-12-18T14:46:55Z

I'll give this a more thorough review.

I should also mention that this IPIP is already implemented in https://github.com/fsspec/ipfsspec.

2color · 2025-12-18T14:53:32Z

+
+## Introduction
+
+This document defines conventions for how applications can identify available


Suggested change

This document defines conventions for how applications can identify available

This document defines conventions for how applications can identify an available

2color · 2025-12-18T14:53:41Z

+## Introduction
+
+This document defines conventions for how applications can identify available
+IPFS gateway, and how IPFS gateway implementations can signal own endpoint to


Suggested change

IPFS gateway, and how IPFS gateway implementations can signal own endpoint to

IPFS Gateway, and how IPFS Gateway implementations can signal their own endpoint to

2color · 2025-12-18T14:54:38Z

+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


Suggested change

2. Check if a valid `gateway` file is present at one of well-known filesystem paths

2. Check if a valid `gateway` file is present at one of the well-known filesystem paths

2color · 2025-12-18T14:55:18Z

+
+### `IPFS_GATEWAY` Environment Variable
+
+When `IPFS_GATEWAY` environment variable is set, the value SHOULD be interpreted


Suggested change

When `IPFS_GATEWAY` environment variable is set, the value SHOULD be interpreted

When the `IPFS_GATEWAY` environment variable is set, the value SHOULD be interpreted

2color · 2025-12-18T14:55:31Z

+### `IPFS_GATEWAY` Environment Variable
+
+When `IPFS_GATEWAY` environment variable is set, the value SHOULD be interpreted
+as URL of IPFS Gateway application to use.


Suggested change

as URL of IPFS Gateway application to use.

as the URL of the IPFS Gateway to use.

2color · 2025-12-18T14:57:04Z

+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


Suggested change

user-preferred IPFS gateways within applications, enabling seamless

user-preferred IPFS Gateways within applications, enabling seamless

2color · 2025-12-18T15:05:55Z

+
+## Specification
+
+There are two ways of hinting user-preferred gateway URL:


Suggested change

There are two ways of hinting user-preferred gateway URL:

There are two ways of hinting the user-preferred gateway URL:

2color · 2025-12-18T15:07:31Z

+
+### Security
+
+Applications that integrate IPFS support via HTTP gateway:


Suggested change

Applications that integrate IPFS support via HTTP gateway:

Applications that integrate IPFS support via HTTP gateways:

2color · 2025-12-18T15:25:11Z

One tricky thing with this proposal is that IPFS_GATEWAY supports a single gateway and the gateway file supports multiple, so they aren't commensurate.

We should probably just make this clear in the spec.

2color · 2025-12-18T15:25:39Z

+
+## Summary
+
+This IPIP creates conventions for how applications can identify available IPFS gateway,


Suggested change

This IPIP creates conventions for how applications can identify available IPFS gateway,

This IPIP creates conventions for how applications can identify an available IPFS gateway,

2color · 2025-12-18T15:25:51Z

+## Summary
+
+This IPIP creates conventions for how applications can identify available IPFS gateway,
+and how IPFS gateway implementations can signal own endpoint.


Suggested change

and how IPFS gateway implementations can signal own endpoint.

and how IPFS gateway implementations can signal their own endpoint.

2color · 2026-01-30T11:39:01Z

@lidel When you get a chance, can you please give this another review.

Review suggestions from ipfs#280: missing articles, plural agreement, and IPFS Gateway capitalization in the spec and IPIP intros. Also credit the reviewer via thanks: frontmatter, bump date:, and collapse double blank lines flagged by markdownlint MD012. Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com>

Close gaps found by reviewing curl, ffmpeg, Kubo, and ipfsspec sources against the spec text. - gateway-detection: IPFS_GATEWAY holds a single URL and yields to explicit per-invocation input; invalid and missing hints defined; $HOME/.ipfs documented as the default IPFS_PATH location; gateway file URL format tightened (no path, query, or fragment); security requirements reformatted as a list and public-gateway fallback relaxed to SHOULD NOT; plainer description - ipip-0280: curl support dated to 8.4.0 (2023); version bounds made inclusive; ffmpeg precedence and IPFS_PATH trailing-slash quirk documented, dweb.link fallback removal linked; curl first-line parsing since 8.5.0 noted; ipfsspec added to compatibility; typos

Add everyone who left feedback on ipfs#280 to thanks: and drop the homepage URL from the editor entry.

Spec becomes 'User-Preferred Gateway Detection' (noun phrase like sibling specs, keeps the user-agency angle); IPIP becomes 'IPIP-0280: App Conventions for Gateway Detection' (the PR title minus the HTTP wording that mismatched the spec's IPFS Gateway terminology).

Add INTEGRATION document

d5673ca

This should help other application developers to have an idea of what's needed to add IPFS support to their application.

lidel mentioned this pull request Jun 7, 2022

Lightweight RFC Process #286

Closed

18 tasks

lidel changed the title ~~Add INTEGRATION document~~ IPIP: IPFS_GATEWAY integration strategy for apps Jul 4, 2022

lidel self-requested a review July 19, 2022 16:28

lidel mentioned this pull request Aug 5, 2022

feat: add $IPFS_PATH/gateway file ipfs/kubo#9156

Merged

lidel mentioned this pull request Aug 13, 2022

As a user, there is no mechanism to control the IPFS networking of a webapp I use ipfs/in-web-browsers#197

Closed

Jorropo self-assigned this Aug 30, 2022

Jorropo requested review from Jorropo and removed request for lidel August 30, 2022 16:46

lidel mentioned this pull request Sep 12, 2022

[EPIC] Kubo v0.15 Release ipfs/ipfs-docs#1261

Closed

3 tasks

lidel marked this pull request as draft September 15, 2022 19:00

lidel added a commit to whizzzkid/ipfs-geoip that referenced this pull request Oct 18, 2022

feat: support IPFS_GATEWAY env

95f9249

ipfs/specs#280 License: MIT Signed-off-by: Marcin Rataj <lidel@lidel.org>

lidel added a commit to whizzzkid/ipfs-geoip that referenced this pull request Oct 18, 2022

feat: support IPFS_GATEWAY env

d2e7139

ipfs/specs#280 License: MIT Signed-off-by: Marcin Rataj <lidel@lidel.org>

lidel changed the title ~~IPIP: IPFS_GATEWAY integration strategy for apps~~ IPIP-280: IPFS_GATEWAY integration strategy for apps Oct 26, 2022

lidel requested changes Nov 18, 2022

View reviewed changes

Comment thread INTEGRATION.md Outdated

Comment thread INTEGRATION.md Outdated

Comment thread INTEGRATION.md Outdated

Comment thread INTEGRATION.md Outdated

Comment thread INTEGRATION.md Outdated

lidel unassigned Jorropo Nov 18, 2022

markg85 and others added 4 commits November 21, 2022 14:56

Update INTEGRATION.md

9630240

Co-authored-by: Marcin Rataj <lidel@lidel.org>

Merge branch 'ipfs:main' into master

b23caf5

rewrote integration document

f956141

Remove drawio files, we're using mermaid now

8a65c2c

markg85 mentioned this pull request Nov 26, 2022

$IPFS_PATH/gateway for user choice of preferred gateway ipfs/kubo#8847

Closed

markg85 added 3 commits November 26, 2022 15:12

follow the template

0e8fa0d

linter fixes

81adfd0

a few more linter fixes

ed0fe22

lidel requested changes Nov 28, 2022

View reviewed changes

lidel added 4 commits December 17, 2025 00:06

fix: capitalize SHOULD for RFC 2119 consistency

e8581ce

chore: add libp2p-gateway to integratingHttpGateways

81e97eb

chore: mark IPIP as ratified (implemented since 2022)

22779d6

docs: add official ffmpeg docs reference

b4e73a2

lidel approved these changes Dec 16, 2025

View reviewed changes

github-project-automation Bot moved this from 🏃 In Progress to 🔍 Ready for Final Reviews in IPIP pipeline Dec 16, 2025

lidel self-assigned this Dec 16, 2025

2color reviewed Dec 18, 2025

View reviewed changes

lidel and others added 6 commits August 7, 2026 22:42

Merge remote-tracking branch 'origin/main'

fe6bbf5

spec: browser secure context and origin isolation

e2d56da

chore: credit reviewers in frontmatter

c732c43

Add everyone who left feedback on ipfs#280 to thanks: and drop the homepage URL from the editor entry.

lidel merged commit 7ed7984 into ipfs:main Aug 7, 2026
2 checks passed

github-project-automation Bot moved this from 🔍 Ready for Final Reviews to ✅ Ratified in IPIP pipeline Aug 7, 2026


		## Introduction

		This document defines conventions for how applications can identify available

	IPFS gateway, and how IPFS gateway implementations can signal own endpoint to
	IPFS Gateway, and how IPFS Gateway implementations can signal their own endpoint to

	2. Check if a valid `gateway` file is present at one of well-known filesystem paths
	2. Check if a valid `gateway` file is present at one of the well-known filesystem paths


		### `IPFS_GATEWAY` Environment Variable

		When `IPFS_GATEWAY` environment variable is set, the value SHOULD be interpreted

	When `IPFS_GATEWAY` environment variable is set, the value SHOULD be interpreted
	When the `IPFS_GATEWAY` environment variable is set, the value SHOULD be interpreted

	as URL of IPFS Gateway application to use.
	as the URL of the IPFS Gateway to use.

	user-preferred IPFS gateways within applications, enabling seamless
	user-preferred IPFS Gateways within applications, enabling seamless


		## Specification

		There are two ways of hinting user-preferred gateway URL:

	There are two ways of hinting user-preferred gateway URL:
	There are two ways of hinting the user-preferred gateway URL:


		### Security

		Applications that integrate IPFS support via HTTP gateway:


		## Summary

		This IPIP creates conventions for how applications can identify available IPFS gateway,

	and how IPFS gateway implementations can signal own endpoint.
	and how IPFS gateway implementations can signal their own endpoint.

Uh oh!

Conversation

markg85 commented May 13, 2022 • edited by lidel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markg85 commented Jul 23, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pimterry commented Aug 16, 2022

Uh oh!

lidel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

markg85 commented Nov 19, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markg85 commented Nov 19, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lidel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lidel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markg85 commented Dec 17, 2025

Uh oh!

lidel commented Dec 17, 2025

Uh oh!

2color commented Dec 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

2color Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

2color Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

2color commented Dec 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

2color commented Jan 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

markg85 commented May 13, 2022 •

edited by lidel

Loading

markg85 commented Jul 23, 2022 •

edited

Loading

markg85 commented Nov 19, 2022 •

edited

Loading

markg85 commented Nov 19, 2022 •

edited

Loading

lidel left a comment •

edited

Loading

2color Dec 18, 2025 •

edited

Loading

2color Dec 18, 2025 •

edited

Loading