Skip to content

Commit

Permalink
ipip-402: wip clarify car roots expectations
Browse files Browse the repository at this point in the history
  • Loading branch information
lidel committed Jun 6, 2023
1 parent 78e81e0 commit bfb5d3c
Showing 1 changed file with 70 additions and 0 deletions.
70 changes: 70 additions & 0 deletions src/http-gateways/trustless-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,3 +147,73 @@ For example: `Content-Type: application/vnd.ipld.car; version=1`
### `Content-Disposition` (response header)

MUST be returned and set to `attachment` to ensure requested bytes are not rendered by a web browser.

## HTTP Response Payload

### Block Response

An opaque bytes matching the requested block CID
([application/vnd.ipld.raw](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw)).

The Body hash MUST match the Multihash from the requested CID.

### CAR Response

A CAR stream
([application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car))
for the requested content type, path and optional `dag-scope` and `entity-bytes` URL parameters.

:::note

By default, block order in CAR response is not deterministic, blocks can
be returned in different order, depending on implementation choices (traversal,
speed at which blocks arrive from the network, etc). An opt-in ordered CAR
responses MAY be introduced in a future, see [IPIP-412](https://github.com/ipfs/specs/pull/412).

:::

#### CAR version

Value returned in `CarV1Header.version` struct MUST match the `version`
parameter returned in `Content-Type` header

#### CAR roots

:::issue

TODO: we need to specify expectations about what should be returned in
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header).

##### Option A: always empty

If the response uses version 1 or 2 of the CAR spec, the
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
MUST be empty.

##### Option B: only CID of the terminating element

If the response uses version 1 or 2 of the CAR spec, the
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
MUST contain CID of the terminating entity.

##### Option C: only CIDs of fully returned DAGs

If the response uses version 1 or 2 of the CAR spec, the
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
MUST be either empty, or only contain CIDs of complete DAGs present in the response.

CIDs from partial DAGs, such as parent nodes on the path, or terminating
element returned with `dag-scope=block`, or UnixFS directory returned with
`dag-scope=entity` MUST never be returned in the `CarV1Header.roots` list, as
they may cause overfetching on systems that perform recursive pinning of DAGs
listed in `CarV1Header.roots`.

##### Option D: CIDs for all logical path segments (same as X-Ipfs-Roots)

If the response uses version 1 or 2 of the CAR spec, the
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
MUST contain all the logical roots related to the requested content path.

The CIDs here MUST be the same as ones in `X-Ipfs-Roots` header.

:::

0 comments on commit bfb5d3c

Please sign in to comment.