You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A generic server error returned when it is not possible to return a better one.
376
+
A generic server error returned when it is not possible to return a better
377
+
one. An internal server error signals the general unavailability of the
378
+
gateway.
363
379
364
380
### `502` Bad Gateway
365
381
366
-
Returned immediately when Gateway was not able to produce response for a known reason.
367
-
For example, when gateway failed to find any providers for requested data.
382
+
Error that indicates that a Gateway was not able to produce response for a
383
+
known reason: for example, in the case of
384
+
[recursive gateways](#recursive-vs-non-recursive-gateways), in the event of
385
+
failure to find any providers for requested data. `502` indicates that the
386
+
request can be retried and is not a permanent failure.
387
+
388
+
This error response SHOULD include
389
+
[`Retry-After`](#retry-after-response-header) HTTP header to indicate how long
390
+
the client should wait before retrying.
368
391
369
-
This error response SHOULD include [`Retry-After`](#retry-after-response-header) HTTP header to indicate how long the client should wait before retrying.
392
+
Gateways SHOULD return `404` instead of `502` when the content is known to be
393
+
unretrievable: for example, when the Gateway is
394
+
[non-recursive](#recursive-vs-non-recursive-gateways) and the content is known
395
+
to not be available.
370
396
371
397
### `504` Gateway Timeout
372
398
373
-
Returned when Gateway was not able to produce response under set time limits.
374
-
For example, when gateway failed to retrieve data from a remote provider.
399
+
Error that indicates that the Gateway was not able to produce response under
400
+
set time limits: for example, when gateway failed to retrieve data from a
401
+
remote provider. `504` indicates that the request can be retried and is not a
402
+
permanent failure.
403
+
404
+
There is no generic timeout, Gateway implementations SHOULD set timeouts based
405
+
on specific use cases.
375
406
376
-
There is no generic timeout, Gateway implementations SHOULD set timeouts based on specific use cases.
407
+
This error response SHOULD include
408
+
[`Retry-After`](#retry-after-response-header) HTTP header to indicate how long
409
+
the client should wait before retrying.
377
410
378
-
This error response SHOULD include [`Retry-After`](#retry-after-response-header) HTTP header to indicate how long the client should wait before retrying.
411
+
Gateways SHOULD return `404` instead of `504` when the content is known to be
412
+
unretrievable: for example, when the Gateway is
413
+
[non-recursive](#recursive-vs-non-recursive-gateways) and the content is known
414
+
to not be available.
379
415
380
416
## Response Headers
381
417
@@ -641,9 +677,13 @@ Optional, present in certain response types:
641
677
642
678
### `Retry-After` (response header)
643
679
644
-
Gateway returns this header with error responses such as [`429 Too Many Requests`](#429-too-many-requests) or [`504 Gateway Timeout`](#504-gateway-timeout).
680
+
Gateway SHOULD return this header with error responses such as [`429 Too Many Requests`](#429-too-many-requests), [`504 Gateway Timeout`](#504-gateway-timeout) or `503` (server maintainance).
645
681
646
-
The "Retry-After" header indicates how long the user agent ought to wait before making a follow-up request.
682
+
The "Retry-After" header indicates how long the user agent ought to wait before making a follow-up request. It uses the following syntax:
683
+
684
+
```
685
+
Retry-After: <delay-seconds>
686
+
```
647
687
648
688
See Section 10.2.3 of :cite[rfc9110].
649
689
@@ -835,6 +875,21 @@ The usual optimizations involve:
835
875
- The downside of this approach is that it will always be slower than
836
876
skipping child block resolution.
837
877
878
+
## Recursive vs non-recursive gateways
879
+
880
+
A *recursive Gateway* is a gateway which generally attempts to fetch content
881
+
from a third party it does not control by triggering lookups and retrievals. A
882
+
recursive Gateway may not know in advance whether it can obtain and return a
883
+
piece of content as the availability of it is out of its control. It may also
884
+
suggest that clients retry failed requests later via `502` and `504` responses
885
+
status codes.
886
+
887
+
A *non-recursive Gateway* is gateway which accesses a known content-set and,
888
+
under normal operation conditions, knows with certainty whether content
889
+
requested can be obtained or not. Non-recursive gateways SHOULD prevent
890
+
unnecessary retries from clients when the content is known to be unavailable
Copy file name to clipboardexpand all lines: src/http-gateways/trustless-gateway.md
+42-4
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,21 @@ description: >
4
4
The minimal subset of HTTP Gateway response types facilitates data retrieval
5
5
via CID and ensures integrity verification, all while eliminating the need to
6
6
trust the gateway itself.
7
-
date: 2024-04-17
7
+
date: 2025-03-06
8
8
maturity: reliable
9
9
editors:
10
10
- name: Marcin Rataj
11
11
github: lidel
12
-
url: https://lidel.org/
12
+
affiliation:
13
+
name: Shipyard
14
+
url: https://ipshipyard.com
13
15
- name: Henrique Dias
14
16
github: hacdias
15
-
url: https://hacdias.com/
17
+
- name: Héctor Sanjuán
18
+
github: hsanjuan
19
+
affiliation:
20
+
name: Shipyard
21
+
url: https://ipshipyard.com
16
22
xref:
17
23
- url
18
24
- path-gateway
@@ -47,10 +53,14 @@ Optional `path` is permitted for requests that specify CAR format (`?format=car`
47
53
48
54
For block requests (`?format=raw` or `Accept: application/vnd.ipld.raw`), only `GET /ipfs/{cid}[?{params}]` is supported.
49
55
56
+
Client and Server implementations SHOULD include support for the [`GET` probe path](#dedicated-probe-paths).
57
+
50
58
## `HEAD /ipfs/{cid}[/{path}][?{params}]`
51
59
52
60
Same as GET, but does not return any payload.
53
61
62
+
Client and Server implementations SHOULD include support for the [`HEAD` probe path](#dedicated-probe-paths).
63
+
54
64
## `GET /ipns/{key}[?{params}]`
55
65
56
66
Downloads data at specified IPNS Key. Verifiable :cite[ipns-record] can be requested via `?format=ipns-record` or `Accept: application/vnd.ipfs.ipns-record`.
@@ -233,7 +243,9 @@ In case both are present in the request, the value from the [`Accept`](#accept-r
233
243
234
244
# HTTP Response
235
245
236
-
Below MUST be implemented **in addition** to "HTTP Response" of :cite[path-gateway].
246
+
Below MUST be implemented **in addition** to "HTTP Response" of
247
+
:cite[path-gateway], with special attention to the "Response Status Codes" and
248
+
the "Recursive vs non-recursive gateways" sections.
237
249
238
250
## Response Headers
239
251
@@ -438,3 +450,29 @@ returned as [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/
438
450
A Client MUST confirm the record signature match `libp2p-key` from the requested IPNS Name.
439
451
440
452
A Client MUST [perform additional record verification according to the IPNS specification](https://specs.ipfs.tech/ipns/ipns-record/#record-verification).
453
+
454
+
# Appendix: Notes for implementers
455
+
456
+
## Dedicated Probe Paths
457
+
458
+
Trustless gateways SHOULD provide probing endpoints as described below.
459
+
460
+
### `GET /ipfs/bafkqaaa`
461
+
462
+
`bafkqaaa` is the identity empty CID. This endpoint can be used to probe that
463
+
that the endpoint corresponds to a trustless gateway.
464
+
465
+
For block requests (signaled by `?format=raw` and `Accept: application/vnd.ipld.raw`), when supported, it MUST return `200 OK`
466
+
and an empty body.
467
+
468
+
For CAR requests (signaled by `?format=car` and `Accept: application/vnd.ipld.car`), when supported, it MUST return `200 OK` and a valid CAR file with CAR Header `roots` set to `bafkqaaa`. Identity block MAY be skipped in the CAR Data section.
469
+
470
+
This specific identity CID is special for probing. Other random
471
+
identity CIDs MAY not be handled.
472
+
473
+
### `HEAD /ipfs/bafkqaaa`
474
+
475
+
`bafkqaaa` is the identity empty CID. If this endpoint is enabled, the gateway
476
+
MUST support [`HEAD` requests](#head-ipfs-cid-path-params).
477
+
478
+
The response is the same as [`GET`](#get-ipfs-bafkqaaa) but without body and all headers are optional.
0 commit comments