docs: update Xet spec to V2 reconstruction (v1.1.0)#2262
Conversation
- Replace V1 reconstruction with V2 as the primary endpoint
- Document /v2/reconstructions/{file_id} with multi-range fetching
- Add Accept-Encoding (gzip, zstd) header documentation
- Rewrite download protocol with V2 response format and examples
- Bump spec version to 1.1.0
XciD
changed the title
rajatarya
left a comment
rajatarya
left a comment
There was a problem hiding this comment.
These changes seem reasonable, but not sure if we should keep older docs and mark as deprecated as well. I think the examples should be complete - right now they are partial/pseudocode.
| }, | ||
| ... | ||
| "url": "https://transfer.xethub.hf.co/xorb/default/a1b2c3d4...?<signed-params>", | ||
| "ranges": [ |
There was a problem hiding this comment.
This example should be complete - meaning the ... should be removed and the need to be spelled out for the example.
| "start": 57980, | ||
| "end": 1433008 | ||
| } | ||
| "url": "https://transfer.xethub.hf.co/xorb/default/a1b2c3d4...?<signed-params>", |
There was a problem hiding this comment.
Example should be complete, readers/agents need to have something to confirm their client implementations against.
|
|
||
| - **Description**: Retrieves reconstruction information for a specific file, includes byte range support when `Range` header is set. | ||
| - **Path**: `/v1/reconstructions/{file_id}` | ||
| - **Description**: Retrieves reconstruction information for a specific file. Returns URLs optimized for multi-range fetching: multiple byte ranges for the same xorb are combined into a single URL. Supports byte range via the optional `Range` header. |
There was a problem hiding this comment.
Would we want to keep the existing docs for backwards compatibility (marked as deprecated maybe?)
There was a problem hiding this comment.
was wondering the same. wdyt @assafvayner ? no strong opinion on my side
|
@XciD : Can we close this for now? |
2 participants
Summary
/v2/reconstructions/{file_id}) as the primary documented endpointXorbMultiRangeFetchandXorbRangeDescriptortypesAccept-Encodingheader documentation (gzip + zstd supported)Related
Note
Medium Risk
Doc-only change but it updates the documented reconstruction endpoint and response shape (from
fetch_infotoxorbs) and introduces stricter multi-rangeRangeheader requirements; incorrect docs could break downstream client implementations.Overview
Updates the Xet protocol docs to treat
GET /v2/reconstructions/{file_id}as the primary reconstruction endpoint, including support for compressed JSON responses viaAccept-Encoding(gzip/zstd).Replaces the documented reconstruction response from per-term
fetch_infoto axorbsmap that provides signed multi-range fetch instructions, and rewrites the download protocol (examples, pseudocode, and sequence diagram) to download xorb ranges via a single multipartRangerequest per xorb fetch entry. The spec version is bumped from 1.0.0 to 1.1.0.Written by Cursor Bugbot for commit 7c001e6. This will update automatically on new commits. Configure here.