fix(core): a cold range that stops short of the end no longer stalls
ci / web (push) Successful in 1m36s
ci / check (push) Successful in 6m24s

Since #1 a ranged GET on a file the bucket does not hold streams its slice
from the tee instead of waiting for the whole transfer. For a range that
runs to the end of the file -- what a resumed `hf download` sends -- that
is exactly right, and it stays.

For a range that stops short of the end it is not enough. The slice
arrives quickly and then the *last chunk* is withheld until the manifest
write lands, which waits on every remaining byte, because the digest is
verified only once the whole file has passed. Measured against the live
service, asking for the first 1MiB of a 3.3GB shard:

    http=206 ttfb=1.040851s total=120.001638s bytes=1048169

1,048,169 of 1,048,576 bytes in about a second, then an idle connection
for the rest of the transfer. The client's read timeout ends it long
before, so in practice the request fails anyway -- slowly and with no
explanation.

The holdback is not the thing to change: releasing that tail early would
signal "durable and recorded" over bytes that are neither, which is
precisely what it exists to prevent. So answer 503 with Retry-After
instead, and let the fetch run on detached; the retry is served from the
bucket. `hf_transfer` splits every download into bounded ranged chunks, so
this shape is not hypothetical wherever it is enabled.

The existing ranged test now asserts the two-step behaviour and keeps its
guarantee that the bucket holds the whole file and never a fragment. A new
test pins that a resume to EOF is still served from the tee, so the fix for
#1 cannot be undone by this one.

Closes #4

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PqNtYNhov3fukx46KS9R7L
This commit is contained in:
2026-09-02 14:24:37 +03:00
co-authored by Claude Opus 5
parent b41964fae0
commit 9b35dfdc09
6 changed files with 139 additions and 19 deletions
+42 -4
View File
@@ -764,10 +764,48 @@ impl Registry {
// stays connected.
task.attach(lead);
let size = head.linked_size.or(head.content_length).unwrap_or(0);
// A ranged request is answered from the same tee,
// narrowed. The whole file is still fetched and stored
// -- a fragment must never reach the bucket -- but the
// client is not made to wait for that in silence.
// A range that stops short of the end cannot be
// completed from this transfer. Its bytes arrive
// quickly, but the last of them is withheld until the
// manifest write lands -- and that waits on the whole
// file, because the digest is only verified once every
// byte has passed. Releasing the tail early would
// signal "durable and recorded" over bytes that are
// neither, which is the one thing the holdback exists
// to prevent.
//
// So the client would receive its slice and then stall
// a few hundred bytes from the end for the length of a
// multi-gigabyte transfer. Say so instead. The fetch is
// already running and detached, so a retry is served
// from the bucket.
//
// A range that extends to the end of the file -- what a
// resumed `hf download` sends -- is not affected: its
// holdback releases at the natural end of the transfer.
if let Some(asked) = &range
&& asked.end != size
{
drop(rx);
warn!(
%repo_id, commit, path, ?asked, size,
"a bounded range on a file the bucket does not hold cannot be \
completed until the whole file is verified; answering 503 rather \
than stalling the client on its last chunk"
);
return Err(Error::FetchInProgress(format!(
"{repo_id}@{commit}/{path} is being fetched; a range that stops \
short of the end can only be served once it is stored. Retry \
shortly."
)));
}
// A range to the end of the file is answered from the
// same tee, narrowed. The whole file is still fetched
// and stored -- a fragment must never reach the bucket
// -- but the client is not made to wait for that in
// silence.
let len = match &range {
Some(range) => range.end - range.start,
None => size,