Skip to content

Commit 5f5bf93

Browse files
authored
Merge branch 'main' into local-CAR-build
2 parents 5602391 + 0e5c2f7 commit 5f5bf93

File tree

2 files changed

+112
-19
lines changed

2 files changed

+112
-19
lines changed

src/http-gateways/path-gateway.md

+70-15
Original file line numberDiff line numberDiff line change
@@ -296,6 +296,8 @@ The request succeeded.
296296

297297
If the HTTP method was `GET`, then data is transmitted in the message body.
298298

299+
If the HTTP method was `HEAD`, then no body should be sent.
300+
299301
### `206` Partial Content
300302

301303
Partial Content: range request succeeded.
@@ -310,23 +312,35 @@ The new, canonical URL is returned in the [`Location`](#location-response-header
310312

311313
### `400` Bad Request
312314

313-
A generic client error returned when it is not possible to return a better one
315+
A generic client error returned when it is not possible to return a better
316+
one. For example, this can be used when the CID is malformed or its codec is
317+
unsupported.
314318

315319
### `404` Not Found
316320

317-
Error to indicate that request was formally correct, but traversal of the
318-
requested content path was not possible due to a invalid or missing DAG node.
321+
Error to indicate that request was formally correct but either:
322+
323+
* traversal of the requested content path was not possible due to a invalid or
324+
missing DAG node, or
325+
* the requested content is not retrievable from this gateway.
326+
327+
Gateways MUST use 404 to signal that content is not available, particularly
328+
when the gateway is [non recursive](#recursive-vs-non-recursive-gateways), and only provides access to a known
329+
dataset, so that it can assess that the requested content is not part of it.
319330

320331
### `410` Gone
321332

322333
Error to indicate that request was formally correct, but this specific Gateway
323-
refuses to return requested data.
334+
refuses to return requested data even though it would have normally provided
335+
it.
324336

325-
Particularly useful for implementing [deny lists](#denylists), in order to not serve malicious content.
337+
`410` is particularly useful to implement [deny lists](#denylists), in order to not serve blocked content.
326338
The name of deny list and unique identifier of blocked entries can be provided in the response body.
327339

328340
See: [Denylists](#denylists)
329341

342+
See also: [`451 Unavailable for Legal Reasons`](#451-unavailable-for-legal-reasons).
343+
330344
### `412` Precondition Failed
331345

332346
Error to indicate that request was formally correct, but Gateway is unable to
@@ -359,23 +373,45 @@ See: [Denylists](#denylists)
359373

360374
### `500` Internal Server Error
361375

362-
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.
363379

364380
### `502` Bad Gateway
365381

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.
368391

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.
370396

371397
### `504` Gateway Timeout
372398

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.
375406

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.
377410

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.
379415

380416
## Response Headers
381417

@@ -641,9 +677,13 @@ Optional, present in certain response types:
641677

642678
### `Retry-After` (response header)
643679

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).
645681

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+
```
647687

648688
See Section 10.2.3 of :cite[rfc9110].
649689

@@ -835,6 +875,21 @@ The usual optimizations involve:
835875
- The downside of this approach is that it will always be slower than
836876
skipping child block resolution.
837877

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
891+
by returning `404`.
892+
838893
[dag-pb-format]: https://ipld.io/specs/codecs/dag-pb/spec/#logical-format
839894
[dag-json]: https://ipld.io/specs/codecs/dag-json/spec/
840895
[dag-cbor]: https://ipld.io/specs/codecs/dag-cbor/spec/

src/http-gateways/trustless-gateway.md

+42-4
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,21 @@ description: >
44
The minimal subset of HTTP Gateway response types facilitates data retrieval
55
via CID and ensures integrity verification, all while eliminating the need to
66
trust the gateway itself.
7-
date: 2024-04-17
7+
date: 2025-03-06
88
maturity: reliable
99
editors:
1010
- name: Marcin Rataj
1111
github: lidel
12-
url: https://lidel.org/
12+
affiliation:
13+
name: Shipyard
14+
url: https://ipshipyard.com
1315
- name: Henrique Dias
1416
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
1622
xref:
1723
- url
1824
- path-gateway
@@ -47,10 +53,14 @@ Optional `path` is permitted for requests that specify CAR format (`?format=car`
4753

4854
For block requests (`?format=raw` or `Accept: application/vnd.ipld.raw`), only `GET /ipfs/{cid}[?{params}]` is supported.
4955

56+
Client and Server implementations SHOULD include support for the [`GET` probe path](#dedicated-probe-paths).
57+
5058
## `HEAD /ipfs/{cid}[/{path}][?{params}]`
5159

5260
Same as GET, but does not return any payload.
5361

62+
Client and Server implementations SHOULD include support for the [`HEAD` probe path](#dedicated-probe-paths).
63+
5464
## `GET /ipns/{key}[?{params}]`
5565

5666
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
233243

234244
# HTTP Response
235245

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.
237249

238250
## Response Headers
239251

@@ -438,3 +450,29 @@ returned as [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/
438450
A Client MUST confirm the record signature match `libp2p-key` from the requested IPNS Name.
439451

440452
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

Comments
 (0)