feat: add /how-to/detect-ipfs-on-web #1295

lidel · 2022-09-29T00:04:30Z

This PR:

tweaks mermaid diagrams config to match IPFS brand book color guide and render a readable size, even on mobile
adds /how-to/detect-ipfs-on-web page with some best practices around detecting IPFS resources on the web, based on recent discussions with Brave team and our effort to streamline implementation there.
- Based on my experience with IPFS Companion browser extension and Brave, I aimed at a healthy balance between low level details and end user experience, but lmk if this is hard to follow or could be improved.
- cc @cypt4 @autonome @SgtPooki @meandavejustice @RangerMauve @fabricedesre @juliaxbow for visibility and additional feedback

As per usual, apologies for any grammar errors ;-)

PR preview

👉️ https://github.com/ipfs/ipfs-docs/blob/feat/how-to-implement-support-in-a-web-browser.md/docs/how-to/detect-ipfs-on-web.md

Website preview (static)

👉️ https://bafybeicp2oota2okffb4u6ta6gzx46jnpyyzxdrrzpzivtbo4xv6sfefim.on.fleek.co/how-to/detect-ipfs-on-web/

To see how the final docs.ipfs.tech version would look, see Fleek preview link in the CI section below.

filecorgi · 2022-09-29T00:07:11Z

Image optimization came back clean!
Vuepress build was successful!

autonome · 2022-09-29T07:40:17Z

docs/how-to/detect-ipfs-on-web.md

@@ -0,0 +1,127 @@
+# Detect IPFS on the Web


Title should probably be more general, because is not just about detection. eg "Handling IPFS Content in Web User Agents" or something in that direction.

We already have "Addressing IPFS on the Web" so I went with similar title, but not feeling strong either way.

It seems like this document helps to bridge the web2 -> web3 gap by showing web2 apps/services how to use ipfs.

Maybe "Discovering IPFS content from web2" or something?

autonome · 2022-09-29T07:41:44Z

docs/how-to/detect-ipfs-on-web.md

+
+```mermaid
+flowchart TD
+    Start[Top-level navigation event]


If diagram only handles top-level navigation events, should add a note because policy there is typically different than other load points. Maybe point also to the test page.

The path detection diagram is generic enough to be applied to subresource requests too – the usual limitations we experience are vendor specific (example: ipfs/ipfs-companion#1095).

TODO(note to self): think how to convey that. Probably change labels on diagram to be about all requests + add section explaining caveats around "top-level navigaton" and "subresource requests" on HTTP and ipfs://.

SgtPooki · 2022-11-10T19:34:46Z

docs/how-to/detect-ipfs-on-web.md

+- If "IPFS Gateway Redirect / Protocol Upgrade" feature is enabled, and the HTTP URL was a gateway one, redirect automatically to `ipfs://cid/path?query#hash`
+
+### Mutable `/ipns/key/..`
+- Display "Open via IPFS" button in UI
+  - Clicking it should open `ipns://key/path?query#hash` (preserving any `?query` or `#hash` from the original HTTP URL)
+- If "IPFS Gateway Redirect / Protocol Upgrade" is enabled, and the original HTTP URL was a gateway one, redirect automatically to `ipns://dnslink/path?query#hash`


It's not clear what "IPFS Gateway Redirect / Protocol Upgrade" is exactly, nor how I enable/disable it. Is this a companion feature, or a pseudo-docs feature that consumers of this document would want to implement? If necessary, can we link to more information?

SgtPooki · 2022-11-10T19:38:00Z

docs/how-to/detect-ipfs-on-web.md

+    IsCachedDNSLink ==>|YES| ValidDNSLink
+    IsCachedDNSLink -->|NO| IsHeaderPresent


I feel like "IsCachedDNSLink" is an unnecessary addition to the large flowchart that could be removed to clean things up a little bit. Mentioning that the resolved DNSLink could be cached is something that could be clearer given a separate description. There are pros and cons for users caching the resolved DNSLinks that could be mentioned in that separate description (or separate DNSLinks doc?)

SgtPooki · 2022-11-10T19:44:26Z

docs/how-to/detect-ipfs-on-web.md

@@ -0,0 +1,127 @@
+# Detect IPFS on the Web


It seems like this document helps to bridge the web2 -> web3 gap by showing web2 apps/services how to use ipfs.

Maybe "Discovering IPFS content from web2" or something?

docs/how-to/detect-ipfs-on-web.md

SgtPooki · 2022-11-10T19:52:18Z

docs/how-to/detect-ipfs-on-web.md

+
+- Display "Open via IPFS" button in UI
+  - Clicking it should open `ipns://dnslink/path?query#hash` (preserving `?query` or `#hash` from the original HTTP URL)
+- If "DNSLink Website Redirect / Protocol Upgrade" is enabled, redirect automatically to `ipns://dnslink/path?query#hash`


ditto. it may be useful to mention a list of "barebones features" that builders reading this doc may want to implement, describe a brief functionality, and then link to those from these items.

It would also clean up these sub-bullet points by centralizing them

SgtPooki · 2022-11-10T19:52:59Z

docs/how-to/detect-ipfs-on-web.md

+- It is a good practice to internally cache the fact that domain has a valid DNSLink.
+  - TTL from TXT record can be used as a hint when to expire cache entry.
+  - Performance can be improved further by using cached flag and revalidating it asynchronously, without blocking browser navigation.


we should put an asterisk in the flowchart when talking about getting DNSLink, and reference this part

ElPaisano · 2023-04-14T00:10:02Z

@lidel @SgtPooki @autonome is this PR still needed? Cleaning out some old PRs now.

lidel · 2023-04-21T15:11:53Z

@ElPaisano Yes, this is still needed, just had no bandwidth to land it :(

FYSA had some related discussions during IPFS Thing and alternative long term home for things like this could be "Integrations" section at https://specs.ipfs.tech (to be added), where we would have this flow, and also have things like ipfs/specs#360.
Then, on docs.ipfs.tech we would have a simplified version, without caching details, as noted by @SgtPooki above.

We could merge this as-is, so at least we have something, and then move to specs, once we have “integrations” section there, and only have a simplified diagram in docs.

BigLep · 2023-04-26T22:21:46Z

+1 on merging so we have something, and the moving to specs when it's ready to house it. Can you tackle this please @ElPaisano ?

aschmahmann · 2023-05-08T13:33:06Z

from @lidel: This is fine to merge, but also ok to keep as a draft until we have time to move this to the specs repo.

docs/how-to/detect-ipfs-on-web.md

This adds a page with some best practices around detecting IPFS resources on the web, based on recent discussions with Brave team and our effort to streamline implmenetation there.

ElPaisano · 2023-09-25T23:08:06Z

@lidel this is ready for review. Made some adjustments

Main thing that is not clear to me is this section https://bafybeiblvih4yq6cbkxd7tauokc6qaxvvsvraftj7wa6sza6qyt5ggdbha.on.fleek.co/how-to/detect-ipfs-on-web/#what-to-do-with-detected-paths (starting on line 88)

Given that "The goal of this page is to provide some suggestions and best practices for Web 2 web browsers and other user agents that are interested in adding support for content-addressed resources.", do you mean that any browsers supporting IPFS should implement an "Open via IPFS" button that displays one of the various path types listed? I think SgtPooki had similar comments.

Also, #1295 (comment) is still not clear to me

lidel requested a review from TMoMoreau September 29, 2022 00:04

autonome approved these changes Sep 29, 2022

View reviewed changes

lidel mentioned this pull request Sep 30, 2022

wip: document browser heuristics ipfs/in-web-browsers#200

Closed

lidel mentioned this pull request Oct 18, 2022

Disable redirect on X-Ipfs-Path without DNSLink on the root document ipfs/ipfs-companion#1052

Open

SgtPooki reviewed Nov 14, 2022

View reviewed changes

ElPaisano added the need/discussion label Apr 14, 2023

aschmahmann marked this pull request as draft May 8, 2023 13:31

lidel mentioned this pull request Jun 19, 2023

Purple "IPFS badge" displays for non-"IPFS" sites brave/brave-browser#31145

Closed

ElPaisano reviewed Aug 25, 2023

View reviewed changes

docs/how-to/detect-ipfs-on-web.md Outdated Show resolved Hide resolved

ElPaisano reviewed Aug 25, 2023

View reviewed changes

docs/how-to/detect-ipfs-on-web.md Outdated Show resolved Hide resolved

ElPaisano removed the request for review from TMoMoreau August 29, 2023 20:22

feat: /how-to/detect-ipfs-on-web

5020d3b

This adds a page with some best practices around detecting IPFS resources on the web, based on recent discussions with Brave team and our effort to streamline implmenetation there.

ElPaisano force-pushed the feat/how-to-implement-support-in-a-web-browser.md branch from 3ed7743 to 5020d3b Compare September 25, 2023 22:48

ElPaisano added 2 commits September 25, 2023 16:58

Fixes

695389a

typo

75308dd

ElPaisano marked this pull request as ready for review September 25, 2023 23:03

ElPaisano self-assigned this Sep 25, 2023

ElPaisano added status/in-progress In progress and removed need/discussion labels Sep 25, 2023

BigLep mentioned this pull request Nov 9, 2023

Release 0.24 ipfs/kubo#10043

Closed

11 tasks

BigLep unassigned ElPaisano Jan 3, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add /how-to/detect-ipfs-on-web #1295

feat: add /how-to/detect-ipfs-on-web #1295

lidel commented Sep 29, 2022 •

edited

filecorgi commented Sep 29, 2022

autonome Sep 29, 2022

lidel Sep 29, 2022

SgtPooki Nov 10, 2022

autonome Sep 29, 2022

lidel Sep 29, 2022

SgtPooki Nov 10, 2022

SgtPooki Nov 10, 2022

SgtPooki Nov 10, 2022

SgtPooki Nov 10, 2022

SgtPooki Nov 10, 2022

ElPaisano commented Apr 14, 2023

lidel commented Apr 21, 2023 •

edited

BigLep commented Apr 26, 2023

aschmahmann commented May 8, 2023

ElPaisano commented Sep 25, 2023

		IsCachedDNSLink ==>\|YES\| ValidDNSLink
		IsCachedDNSLink -->\|NO\| IsHeaderPresent

feat: add /how-to/detect-ipfs-on-web #1295

Are you sure you want to change the base?

feat: add /how-to/detect-ipfs-on-web #1295

Conversation

lidel commented Sep 29, 2022 • edited

PR preview

Website preview (static)

filecorgi commented Sep 29, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ElPaisano commented Apr 14, 2023

lidel commented Apr 21, 2023 • edited

BigLep commented Apr 26, 2023

aschmahmann commented May 8, 2023

ElPaisano commented Sep 25, 2023

lidel commented Sep 29, 2022 •

edited

lidel commented Apr 21, 2023 •

edited