Update gateways info #1531

ElPaisano · 2023-03-20T23:20:01Z

Incorporates some of the content from https://blog.ipfs.tech/2022-06-30-practical-explainer-ipfs-gateways-2/ into existing GW concepts and ref material

Since the blog + the existing https://docs.ipfs.tech/concepts/ipfs-gateway/ page both have alot of contents, this PR:

Prunes out best practice and troubleshooting type info from concepts/ipfs-gateway/
Puts some best practices in /how-to/gateway-best-practices/
Puts troubleshooting info in /how-to/gateway-troubleshooting/

2color

Thanks for bringing those into the docs. I left some comments on changes since the blog was published.

We should more strongly recommend using subdomain gateway resolution as it provides more security.

docs/concepts/ipfs-gateway.md

2color · 2023-03-23T09:34:14Z

docs/how-to/gateway-best-practices.md

+
+## When not to use a gateway
+
+### Delay-sensitive applications


Suggested change

### Delay-sensitive applications

### Latency-sensitive applications

Use latency, as that's the standard nomenclature.

docs/how-to/gateway-best-practices.md

docs/how-to/gateway-troubleshooting.md

docs/how-to/gateway-best-practices.md

Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com>

BigLep · 2023-03-24T14:59:04Z

FYI @lidel or @hacdias if you have anything you want to add here.

ElPaisano · 2023-03-24T16:05:08Z

Thanks for bringing those into the docs. I left some comments on changes since the blog was published.

We should more strongly recommend using subdomain gateway resolution as it provides more security.

@2color I think I addressed your comments in the updates

hacdias

I didn't have time yet to go over the whole document, but I noticed there aren't any mentions for the gateway specifications. I would add some mention that the specification for the different types and parts of the gateways are available at https://specs.ipfs.tech/http-gateways/ - that'd be great visibility with information for those who want to implement their own gateway.

hacdias · 2023-04-03T07:30:23Z

docs/concepts/ipfs-gateway.md


-IPFS deployment seeks to include native support of IPFS in all popular browsers and tools. Gateways provide workarounds for applications that do not yet support IPFS natively. For example, errors occur when a browser that does not support IPFS attempts access to IPFS content in the canonical form of `ipfs://{CID}/{optional path to resource}`. Other tools that rely solely on HTTP encounter similar errors in accessing IPFS content in canonical form, such as [Curl](https://curl.haxx.se/) and [Wget](https://www.gnu.org/software/wget/).
+- **If the CID is not in the local cache**, the gateway will attempt to retrieve it from the network.


the gateway will attempt to retrieve it from the network

That is the default of Kubo. However, there might be gateways that only serve content that they have and/or want to provide. For example, a Kubo gateway with NoFetch enabled will not attempt to retrieve content from the network. I'm not sure if we should keep this, or remove it. Opinions?

docs/concepts/ipfs-gateway.md

Co-authored-by: Henrique Dias <hacdias@gmail.com>

ElPaisano · 2023-04-03T23:22:48Z

I didn't have time yet to go over the whole document, but I noticed there aren't any mentions for the gateway specifications. I would add some mention that the specification for the different types and parts of the gateways are available at https://specs.ipfs.tech/http-gateways/ - that'd be great visibility with information for those who want to implement their own gateway.

Thanks for reviewing @hacdias , much appreciated

I added the spec link in a few place that made sense. RE your first comment #1531 (comment), I added a note at the beginning of the lifecycle section calling out your point, so readers are aware of these nuances. See bb394f2.

If we need to refine this section, I'd prefer to do it in future PRs, as this one has been sitting for awhile now.

Unless anyone reeeeeeeally has any issues with this

cc @2color

2color · 2023-04-04T16:59:42Z

docs/how-to/gateway-best-practices.md

+
+
+
+## Avoiding centralization


This paragraph is too convoluted.

The tile could be much more specific and direct: avoid hardcoding a gateway URL, e.g. ipfs.io/ipfs/CID in places where possible! It must also acknowledge that it's not feasible in some situations, e.g. embedding image from IPFS on web and that can be worked around by owning the domain and proxying.

2color · 2023-04-04T17:00:00Z

docs/how-to/gateway-best-practices.md

+
+Trusting a specific gateway, in turn, requires you to trust the gateway's issuing Certificate Authorities and the security of the public key infrastructure employed by that gateway. Compromised certificate authorities or public-key infrastructure implementations may undermine the trustworthiness of the gateway.
+
+## Use subdomain gateway resolution for origin isolation


Should be the first one.

2color · 2023-04-04T17:00:57Z

docs/how-to/gateway-best-practices.md

+
+Similarly, the use of DNSLink resolution with `Alias` forces requests through the domain's chosen gateway, as specified in the `dnslink={value}` string within the DNS TXT record. If the specified gateway becomes overloaded, goes offline, or becomes compromised, all traffic with that content becomes deleted, disabled, or suspect.
+
+## Misplaced trust


This is not really a best practice.

I would remove or move to the bottom

2color

This is a great improvement. Wonderful to see the new specs page https://specs.ipfs.tech/http-gateways/ linked!

Besides some comments about the best practices, this is good to go.

docs/how-to/gateway-best-practices.md

Update gateways info

80eb915

ElPaisano self-assigned this Mar 20, 2023

ElPaisano added 2 commits March 21, 2023 13:20

more

0d15a22

Finish?

4417b09

ElPaisano marked this pull request as ready for review March 22, 2023 23:12

ElPaisano changed the title ~~(DRAFT) Update gateways info~~ Update gateways info Mar 22, 2023

ElPaisano requested a review from 2color March 22, 2023 23:19

ElPaisano added the status/ready Ready to be worked label Mar 23, 2023

2color reviewed Mar 23, 2023

View reviewed changes

docs/how-to/gateway-best-practices.md Outdated Show resolved Hide resolved

azimanuar5874 approved these changes Mar 23, 2023

View reviewed changes

ipfs deleted a comment from azimanuar5874 Mar 23, 2023

ElPaisano and others added 3 commits March 23, 2023 12:46

Apply changes requested

f633362

Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com>

edits based on feedback

ebd1c05

spellz

7326760

ElPaisano requested a review from 2color March 23, 2023 19:56

ElPaisano mentioned this pull request Mar 30, 2023

Document the HTTP Gateway features and functionality for developer users #708

Closed

ElPaisano requested a review from autonome March 30, 2023 17:08

BigLep requested a review from hacdias March 31, 2023 20:43

hacdias reviewed Apr 3, 2023

View reviewed changes

docs/concepts/ipfs-gateway.md Outdated Show resolved Hide resolved

ElPaisano and others added 2 commits April 3, 2023 17:05

comma

6c46582

Co-authored-by: Henrique Dias <hacdias@gmail.com>

Add spec links, call out default gw lifecycle

bb394f2

ElPaisano removed request for autonome and 2color April 3, 2023 23:25

ElPaisano requested a review from 2color April 3, 2023 23:26

2color reviewed Apr 4, 2023

View reviewed changes

2color approved these changes Apr 4, 2023

View reviewed changes

ElPaisano commented Apr 11, 2023

View reviewed changes

docs/how-to/gateway-best-practices.md Outdated Show resolved Hide resolved

Update best practice page per review

7aaefd7

ElPaisano merged commit dfdab1d into ipfs:main Apr 11, 2023

ElPaisano linked an issue Apr 11, 2023 that may be closed by this pull request

Document the HTTP Gateway features and functionality for developer users #708

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update gateways info #1531

Update gateways info #1531

ElPaisano commented Mar 20, 2023 •

edited

Loading

2color left a comment

2color Mar 23, 2023

BigLep commented Mar 24, 2023

ElPaisano commented Mar 24, 2023

hacdias left a comment

hacdias Apr 3, 2023

ElPaisano commented Apr 3, 2023 •

edited

Loading

2color Apr 4, 2023

2color Apr 4, 2023

2color Apr 4, 2023 •

edited

Loading

2color left a comment •

edited

Loading


		## When not to use a gateway

		### Delay-sensitive applications

	### Delay-sensitive applications
	### Latency-sensitive applications


		IPFS deployment seeks to include native support of IPFS in all popular browsers and tools. Gateways provide workarounds for applications that do not yet support IPFS natively. For example, errors occur when a browser that does not support IPFS attempts access to IPFS content in the canonical form of `ipfs://{CID}/{optional path to resource}`. Other tools that rely solely on HTTP encounter similar errors in accessing IPFS content in canonical form, such as [Curl](https://curl.haxx.se/) and [Wget](https://www.gnu.org/software/wget/).
		- If the CID is not in the local cache, the gateway will attempt to retrieve it from the network.


		Trusting a specific gateway, in turn, requires you to trust the gateway's issuing Certificate Authorities and the security of the public key infrastructure employed by that gateway. Compromised certificate authorities or public-key infrastructure implementations may undermine the trustworthiness of the gateway.

		## Use subdomain gateway resolution for origin isolation


		Similarly, the use of DNSLink resolution with `Alias` forces requests through the domain's chosen gateway, as specified in the `dnslink={value}` string within the DNS TXT record. If the specified gateway becomes overloaded, goes offline, or becomes compromised, all traffic with that content becomes deleted, disabled, or suspect.

		## Misplaced trust

Update gateways info #1531

Update gateways info #1531

Conversation

ElPaisano commented Mar 20, 2023 • edited Loading

2color left a comment

Choose a reason for hiding this comment

2color Mar 23, 2023

Choose a reason for hiding this comment

BigLep commented Mar 24, 2023

ElPaisano commented Mar 24, 2023

hacdias left a comment

Choose a reason for hiding this comment

hacdias Apr 3, 2023

Choose a reason for hiding this comment

ElPaisano commented Apr 3, 2023 • edited Loading

2color Apr 4, 2023

Choose a reason for hiding this comment

2color Apr 4, 2023

Choose a reason for hiding this comment

2color Apr 4, 2023 • edited Loading

Choose a reason for hiding this comment

2color left a comment • edited Loading

Choose a reason for hiding this comment

ElPaisano commented Mar 20, 2023 •

edited

Loading

ElPaisano commented Apr 3, 2023 •

edited

Loading

2color Apr 4, 2023 •

edited

Loading

2color left a comment •

edited

Loading