IPIP-280: App Conventions for HTTP Gateway Detection #280

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.

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 <[email protected]>

* Using async-await * feat: support IPFS_GATEWAY env ipfs/specs#280 Signed-off-by: Marcin Rataj <[email protected]> Signed-off-by: Marcin Rataj <[email protected]> Co-authored-by: Marcin Rataj <[email protected]>

lidel

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

INTEGRATION.md

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 <[email protected]>

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

INTEGRATION.md

- fix "user-prefered" typo (3 occurrences) - clarify gateway file is ASCII (URLs are ASCII by definition)

- multiple lines are optional (MAY be supported) - if not supported, extra lines SHOULD be ignored - first line is always the primary URL

- browser detection requires separate IPIP (security concerns) - health checking left to implementers - stale file handling left to implementers

github-actions · 2025-12-16T22:48:14Z

🚀 Build Preview on IPFS ready

🔎 Commit: b4e73a2
🔏 CID bafybeic46p7uauu3yot2eg3c6irgkqdmntmfncql3dwc2v3xkex4zpchdi
📦 Preview:

- remove duplicate /etc/ipfs/gateway entries - properly handle XDG with explicit default path - group all OS-specific paths together - use consistent "system-wide" terminology

- update date to 2025-12-16 - update lidel affiliation to Shipyard - relax IPFS_GATEWAY interpretation from MUST to SHOULD

- URL must be without path (base URL only) - gateway must support trustless-gateway - gateway should support path-gateway for deserialized responses - gateway should support subdomain-gateway for Origin isolation

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