Skip to content

Commit 8bb2b23

Browse files
committed
ipip-402: clarify CarV1Header.roots
Rationale: #402 (comment)
1 parent addf7a3 commit 8bb2b23

File tree

1 file changed

+7
-40
lines changed

1 file changed

+7
-40
lines changed

src/http-gateways/trustless-gateway.md

Lines changed: 7 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -136,13 +136,13 @@ When present, returned `Etag` must include unique prefix based on the passed ran
136136

137137
Below MUST be implemented **in addition** to "HTTP Response" of :cite[path-gateway].
138138

139-
## HTTP Response Headers
139+
## Response Headers
140140

141141
### `Content-Disposition` (response header)
142142

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

145-
## HTTP Response Payload
145+
## Response Payload
146146

147147
### Block Response
148148

@@ -168,46 +168,13 @@ responses MAY be introduced in a future, see [IPIP-412](https://github.com/ipfs/
168168

169169
#### CAR version
170170

171-
Value returned in `CarV1Header.version` struct MUST match the `version`
172-
parameter returned in `Content-Type` header
171+
Value returned in
172+
[`CarV1Header.version`](https://ipld.io/specs/transport/car/carv1/#header)
173+
field MUST match the `version` parameter returned in `Content-Type` header.
173174

174175
#### CAR roots
175176

176-
:::issue
177-
178-
TODO: we need to specify expectations about what should be returned in
179-
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header).
180-
181-
##### Option A: always empty
182-
183-
If the response uses version 1 or 2 of the CAR spec, the
184-
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
185-
MUST be empty.
186-
187-
##### Option B: only CID of the terminating element
188-
189177
If the response uses version 1 or 2 of the CAR spec, the
190-
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
191-
MUST contain CID of the terminating entity.
178+
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) field
179+
MUST contain the CID of the terminating entity.
192180

193-
##### Option C: only CIDs of fully returned DAGs
194-
195-
If the response uses version 1 or 2 of the CAR spec, the
196-
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
197-
MUST be either empty, or only contain CIDs of complete DAGs present in the response.
198-
199-
CIDs from partial DAGs, such as parent nodes on the path, or terminating
200-
element returned with `dag-scope=block`, or UnixFS directory returned with
201-
`dag-scope=entity` MUST never be returned in the `CarV1Header.roots` list, as
202-
they may cause overfetching on systems that perform recursive pinning of DAGs
203-
listed in `CarV1Header.roots`.
204-
205-
##### Option D: CIDs for all logical path segments (same as X-Ipfs-Roots)
206-
207-
If the response uses version 1 or 2 of the CAR spec, the
208-
[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
209-
MUST contain all the logical roots related to the requested content path.
210-
211-
The CIDs here MUST be the same as ones in `X-Ipfs-Roots` header.
212-
213-
:::

0 commit comments

Comments
 (0)