Skip to content

Commit

Permalink
Edits
Browse files Browse the repository at this point in the history
  • Loading branch information
@ElPaisano
ElPaisano committed Sep 25, 2023
1 parent b395dba commit 3ed7743
Showing 1 changed file with 25 additions and 24 deletions.
49 changes: 25 additions & 24 deletions docs/how-to/detect-ipfs-on-web.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,24 @@
# Discover IPFS content from web2
---
title: Discover IPFS content from Web2
description: Learn how to add support for content-addressed IPFS resources in web browsers and other user agents.
---

Below is the suggested heuristic for detecting content-addressed resources on the web, and presenting additional user interface for interacting with that content.
# Discover IPFS content from Web2

The goal of this page is to provide some suggestions and best practices for web browsers and other [user agents](https://en.wikipedia.org/wiki/User_agent) that are interested in adding support for [content-addressed resources on the Web](/how-to/address-ipfs-on-web).
The goal of this page is to provide some suggestions and best practices for Web 2 web browsers and other [user agents](https://en.wikipedia.org/wiki/User_agent) that are interested in adding support for [content-addressed resources](/how-to/address-ipfs-on-web).

## Detecting content-addressed resources

In many cases IPFS resources can be detected just by looking at the URI, especially if it is an HTTP URL pointing at a public gateway. This allows a browser to upgrade the transport protocol to IPFS, and remove the need for sending an HTTP request to a remote server.
In many cases, IPFS resources can be detected just by looking at the URI, especially if it is an HTTP URL pointed at a public gateway. This allows a browser to upgrade the transport protocol to IPFS, and removes the need to send an HTTP request to a remote server.

The high level heuristic is to check, in order:
- Does the `URL` follow [path or subdomain gateway](/how-to/address-ipfs-on-web/) convention?
- If not, does [DNSLink](/concepts/dnslink/) with an IPFS path exist for `URL.hostname`?
### Methodology

If any of the above is true, a user agent should be able to find a content path that can be used for data retrieval over IPFS. See the illustration below.
To determine if a resource is an IPFS resource, answer the following questions in order:

1. Does the `URL` follow [path or subdomain gateway](/how-to/address-ipfs-on-web/) convention?
1. If not, does [DNSLink](/concepts/dnslink/) with an IPFS path exist for `URL.hostname`?

If you answered yes to either of the above questions, a user agent should be able to find a content path that can be used for data retrieval over IPFS, as described in the illustration below:

```mermaid
flowchart TD
Expand Down Expand Up @@ -77,7 +83,9 @@ flowchart TD
PathFromHeader --> PotentialContentPath
```

## What to do with detected paths?
## What to do with detected paths

What you do with the detected IPFS resource path depends on the type of path.

### Immutable `/ipfs/cid/..`

Expand All @@ -101,27 +109,20 @@ flowchart TD

## FAQ

- What if a browser does not support `ipfs://` and `ipns://` natively?
- Implementation can use a [HTTP Gateway](/reference/http/gateway/) as a fallback: convert them to `//gatewayhost/ipxs/id/..` paths, or leverage the built-in URI router at `//gatewayhost/ipfs/?uri=%s`
- Why should `?query` or `#hash` from the original HTTP URL be preserved?
- Link could point at specific `#section` of a longer article. It is also common for JS running on a page to use `?query` and `#hash` for navigation and ad-hoc storage for some state.
- Should user agent redirect when URL does not match gateway convention, `URL.hostname` does not have a valid DNSLink, but `X-Ipfs-Path` is present in HTTP response AND points at immutable `/ipfs/cid`?
- This is an edge case, and we've seen that it is often a misconfiguration caused by invalid/missing DNSLink that could lead to bad UX when automatic redirect is involved: user ends up on immutable copy of a website, bookmark it or keep tab open, and miss updates when DNSLink setup is fixed.
- It is suggested to not redirect this edge case, or provide a setting that controls this type of redirect. Usually, showing "Open via IPFS" in the user interface is enough for this case.
**What if a browser does not support `ipfs://` and `ipns://` natively?** Implementations can use an [HTTP Gateway](/reference/http/gateway/) as a fallback, convert ththe path to `//gatewayhost/ipxs/id/..`-type paths, or leverage the built-in URI router at `//gatewayhost/ipfs/?uri=%s`

**Why should `?query` or `#hash` from the original HTTP URL be preserved?** The link could point at specific `#section` of a longer article. It is also common for JavaScript running on a page to use the `?query` and `#hash` for navigation and ad-hoc storage of some state.

**Should a user agent redirect when the URL does not match gateway convention, `URL.hostname` does not have a valid DNSLink, but `X-Ipfs-Path` is present in HTTP response AND points at an immutable `/ipfs/cid`?** This is an edge case, and we've seen that it is often a misconfiguration caused by an invalid or missing DNSLink that could lead to bad UX when automatic redirect is involved. The user ends up on an immutable copy of a website, bookmarks it or keeps tabs open, and misses updates when DNSLink setup is fixed. It is suggested to not redirect this edge case, or provide a setting that controls this type of redirect. Usually, showing "Open via IPFS" in the user interface is enough for this case.

## Implementation examples

### Brave

[IPFS is supported in Brave since 2021](https://brave.com/brave-integrates-ipfs/). Current features include `ipfs://` and `ipns://` URI support, ability to resolve them using a public or local gateway, opt-in Gateway and DNSLink redirects, and "Open via IPFS" button in the address bar:
[Brave has supported IPFS since 2021](https://brave.com/brave-integrates-ipfs/). Current features include `ipfs://` and `ipns://` URI support, ability to resolve this type of address using a public / local gateway, opt-in Gateway and/or DNSLink redirects, and an **Open via IPFS** button in the address bar:

> ![Open via IPFS in Brave addressbar](https://user-images.githubusercontent.com/157609/110859368-9a0d7300-82bb-11eb-934d-4e38718dbacb.png)
> ![Open via IPFS in Brave address bar](https://user-images.githubusercontent.com/157609/110859368-9a0d7300-82bb-11eb-934d-4e38718dbacb.png)
### IPFS Companion

Firefox and Chromium-based browsers such as Google Chrome, Microsoft Edge can be augumented with [IPFS Companion](/install/ipfs-companion/) browser extension.

It provides detection of IPFS resources, redirect functionality, and a handy UI:

> ![Quick runthrough of basic IPFS Companion features](https://gateway.ipfs.io/ipfs/QmSsGphTN1eWMhkFFNFb23jWTXyhNbo47PF9FbmC6ZaRNg)
Firefox and Chromium-based browsers such as Google Chrome or Microsoft Edge can be augumented with [IPFS Companion](/install/ipfs-companion/) browser extension, which allows them to detect IPFS content.

0 comments on commit 3ed7743

Please sign in to comment.