2.2.1 dag-scope (request query parameter)
Optional, dag-scope=(block|entity|all) with default value all, only available for CAR requests.
Describes the shape of the DAG fetched the terminus of the specified path whose blocks
are included in the returned CAR file after the blocks required to traverse
path segments.
-
block - Only the root block at the end of the path is returned after blocks
required to verify the specified path segments.
-
entity - For queries that traverse UnixFS data, entity roughly means return
blocks needed to verify the terminating element of the requested content path.
For UnixFS, all the blocks needed to read an entire UnixFS file, or enumerate a UnixFS directory.
For all queries that reference non-UnixFS data, entity is equivalent to block
-
all - Transmit the entire contiguous DAG that begins at the end of the path
query, after blocks required to verify path segments
When present, returned Etag must include unique prefix based on the passed scope type.
2.2.2 entity-bytes (request query parameter)
The optional entity-bytes=from:to parameter is available only for CAR
requests.
It implies dag-scope=entity and serves as a trustless equivalent of an HTTP
Range Request.
When the terminating entity at the end of the specified content path:
-
can be interpreted as a continuous array of bytes (such as a UnixFS file), a
Gateway MUST return only the minimal set of blocks necessary to verify the
specified byte range of that entity.
- When dealing with a sharded UnixFS file (
dag-pb, 0x70) and a non-zero
from value, the UnixFS data and blocksizes determine the
corresponding starting block for a given from offset.
-
cannot be interpreted as a continuous array of bytes (such as a DAG-CBOR/JSON
map or UnixFS directory), the parameter MUST be ignored, and the request is
equivalent to dag-scope=entity.
Allowed values for from and to follow a subset of section 14.1.2 from
[rfc9110], where they are defined as offset integers that limit the
returned blocks to only those necessary to satisfy the range [from,to]:
from value gives the byte-offset of the first byte in a range.to value gives the byte-offset of the last byte in the range;
that is, the byte positions specified are inclusive.
The following additional values are supported:
* can be substituted for end-of-file
entity-bytes=0:* is the entire file (a verifiable version of HTTP request for Range: 0-)
- Negative numbers can be used for referring to bytes from the end of a file
entity-bytes=-1024:* is the last 1024 bytes of a file
(verifiable version of HTTP request for Range: -1024)- It is also permissible (unlike with HTTP Range Requests) to ask for the
range of 500 bytes from the beginning of the file to 1000 bytes from the
end:
entity-bytes=499:-1000
A Gateway MUST augment the returned Etag based on the passed entity-bytes.
A Gateway SHOULD return an HTTP 400 Bad Request error when the requested range
cannot be parsed as valid offset positions.
In more nuanced error scenarios, a Gateway MUST return a valid CAR response
that includes enough blocks for the client to understand why the requested
entity-bytes was incorrect or why only a part of the requested byte range was
returned:
-
If the requested entity-bytes resolves to a range that partially falls
outside of the entity's byte range, the response MUST include the subset of
blocks within the entity's bytes.
- This allows clients to request valid ranges of the entity without needing
to know its total size beforehand, and it does not require the Gateway to
buffer the entire entity before returning the response.
-
If the requested entity-bytes resolves to a zero-length range or falls
fully outside of the entity's bytes, the response is equivalent to
dag-scope=block.
- This allows client to produce a meaningful error (e.g, in case of UnixFS,
leverage
Data.blocksizes information present in the root dag-pb block).
-
In streaming scenarios, if a Gateway is capable of returning the root block
but lacks prior knowledge of the final component of the requested content
path being invalid or absent in the DAG, a Gateway SHOULD respond with HTTP 200.
- This behavior is a consequence of HTTP streaming limitations: blocks are
not buffered, by the time a related parent block is being parsed and
returned to the client, the HTTP status code has already been sent to the
client.
