fix(r2): return source digest/size for mounted blob HEAD responses

[mushanyoung]

Title

fix(r2): return source digest/size for mounted blob HEAD responses

Summary

Mounted layers in the R2 backend are stored as lightweight "symlink" objects (body like <repo>/blobs/<digest>).
HEAD /v2/:name/blobs/:digest could return metadata from that symlink object instead of the mounted source blob.

This caused invalid blob metadata in HEAD responses for mounted layers, including:

• incorrect Docker-Content-Digest
• very small Content-Length values (commonly around path-string length such as 86)

Those headers are consumed by OCI clients during push/pull validation and can surface as unauthorized/manifest-corruption style failures in downstream workflows.

Root Cause

Two pieces combined into the bug:

1. mountExistingLayer stores a symlink object whose checksum represents the symlink payload bytes (the path string), not the mounted source blob digest.
2. The blob HEAD route read R2 object metadata directly (env.REGISTRY.head(...)), bypassing symlink resolution logic.

Result: for mounted blobs, HEAD returned symlink metadata instead of source blob metadata.

Changes

1) Persist source metadata on new symlink objects

File: src/registry/r2.ts

• Added custom metadata keys:
  • X-Serverless-Registry-Symlink-Digest
  • X-Serverless-Registry-Symlink-Size
• When mounting, write these fields from the source layer response.

2) Resolve symlinks in layerExists (including old symlinks)

File: src/registry/r2.ts

• Detect symlink objects by:
  • explicit symlink metadata, or
  • checksum mismatch between requested digest and stored object checksum.
• Fast path (new symlinks): use stored digest/size metadata.
• Backward compatibility (old symlinks): read symlink body, parse <repo>/blobs/<digest>, then recursively query layerExists on the source target.
• Added safety fallback for malformed payloads and self-reference.

3) Route blob HEAD through layerExists

File: src/router.ts

• Updated HEAD /v2/:name+/blobs/:tag to use env.REGISTRY_CLIENT.layerExists(name, tag) for local lookups.
• Keeps existing remote-registry fallback behavior when local blob does not exist.

4) Add regression assertions

File: test/index.test.ts

• Extended recursive layer mounting test to assert mounted blob HEAD returns:
  • Docker-Content-Digest == layer digest
  • Content-Length == source blob byte length

Reproduction (before this patch)

1. Push image to repoA.
2. Push another image to repoB that mounts the same layer from repoA.
3. Run HEAD /v2/repoB/blobs/<mounted-layer-digest>.
4. Observe mismatch:
   • digest/header can reflect symlink object checksum
   • Content-Length can be tiny (e.g. path-length values such as 86)

Behavior After Patch

For mounted blobs, HEAD now returns source blob metadata (digest + size), including for previously-created symlink objects.

Compatibility and Risk

• Backward compatible with existing symlink objects already present in R2.
• New symlinks gain metadata for O(1) HEAD resolution.
• Main behavior change is correctness of blob HEAD metadata for mounted layers.

Test Plan

Executed:

• npm test -- test/index.test.ts -t "Upload manifests with recursive layer mounting"
• npm test -- test/index.test.ts

Both pass.

[m-ferrero]

While running this against the OCI distribution-spec conformance suite I hit a defect in the symlink checksum-mismatch check — res.checksums.sha256 is an ArrayBuffer, so comparing it directly to the hex expectedDigest (in layerExists) doesn't type-check and is always true, which routes every digest-addressed blob through symlink resolution. Converting both sides to a full sha256:… string (via hexToDigest) fixes it.

I opened #139 that builds on your approach with that fix plus regression tests — full credit to you for the design. Happy for you to cherry-pick just the fix here instead if you'd rather keep ownership; whatever's easiest for the maintainers.

[mushanyoung]

Thanks @m-ferrero, good catch. I agree the previous mismatch check was comparing the R2 checksum ArrayBuffer directly against the hex digest string, which made the mismatch path fire for every digest-addressed blob.

I ported your #139 fix back into this PR by normalizing both sides to full sha256:... digest strings before comparing. I also added the mounted-blob HEAD regression coverage from #139, plus an extra regression test for a regular blob whose body contains /blobs/ to ensure normal blobs do not get routed through symlink resolution.

Credit added in the follow-up commit with your Co-authored-by trailer. Validation run locally:

• pnpm test -- test/index.test.ts -t "HEAD of a cross-repo mounted blob returns source metadata|HEAD of a regular blob with /blobs/ in its body is not resolved as a symlink|Upload manifests with recursive layer mounting"
• pnpm test -- test/index.test.ts
• pnpm typecheck
• npx prettier --check src/registry/r2.ts test/index.test.ts