#23875·harbor

Proxy cache: Range requests for uncached blobs are ignored, full blob returned as 200, breaking lazy-loading (nydus)

Author: IceCream-jyCreated Sep 9, 2026Updated Sep 14, 2026
Labelskind/requirementarea/proxy-cache

When Harbor is used as a pull-through cache (proxy cache project) and the requested blob is not yet cached locally, a blob GET carrying a Range header is not honored: Harbor drops the Range, pulls the entire blob from the upstream registry, and streams it back as a plain 200. This breaks image lazy-loading solutions that rely on ranged blob fetches (nydus).

Environment Harbor v2.15.2 (proxy-cache project) nydusd 2.x client

Impact

nydusd (nydus backend) issues Range: bytes=x-y chunk reads on demand. On a cold miss through a Harbor proxy project, the first chunk read degenerates into a full-blob transfer — and with the background cache fill the upstream sees the blob downloaded twice. Lazy loading effectively becomes an eager full download, with severe first-I/O latency for large blobs.

Would it be possible to make this change:

On a cache miss with a single-range Range header, forward the range to the upstream registry and relay the upstream response:

  • upstream 206 → relay 206 with Content-Range, Content-Length, Docker-Content-Digest, ETag
  • upstream 200 (Range support is optional for registries per the OCI distribution spec) → relay the full 200
  • multi-range / suffix-range / unparsable → fall back to today's full-pull path