withcache 0.5.2__tar.gz → 0.6.0__tar.gz

{withcache-0.5.2 → withcache-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.5.2
+Version: 0.6.0
 Summary: Operator-curated, URL-keyed artifact cache for a small lab (CUDA/ROCm/DOCA/firmware)
 Project-URL: Homepage, https://github.com/safl/withcache
 Author-email: "Simon A. F. Lund" <safl@safl.dk>

{withcache-0.5.2 → withcache-0.6.0}/shim/build.zig.zon

@@ -2,7 +2,7 @@
     .name = .withcache_shim,
     // Zig requires a literal here; keep it in lockstep with the project's
     // single source (src/withcache/__init__.py) via `make bump` / `make version-check`.
-    .version = "0.5.2",
+    .version = "0.6.0",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.5.2 → withcache-0.6.0}/src/withcache/__init__.py

@@ -6,12 +6,17 @@
 - ``withcache.client``: a tiny, stdlib-only library for other tools to consume
   a cache-host (build serve URLs, probe what's cached) without re-implementing
   the ``/b/`` URL scheme.
+- ``withcache.oras``: OCI registry adapter. Parses ``oras://...`` references
+  and resolves them to a plain HTTPS blob URL + bearer headers. The cache-host
+  uses it on a cold miss; library consumers (e.g. ``bty``) import it to
+  validate catalog entries and pre-resolve content digests.
 
 All modules are stdlib-only and self-contained.
 """
 
+from . import oras
 from .client import blob_url, cache_base, is_cached, serve_url
 
-__version__ = "0.5.2"
+__version__ = "0.6.0"
 
-__all__ = ["__version__", "blob_url", "cache_base", "is_cached", "serve_url"]
+__all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

withcache-0.6.0/src/withcache/oras.py

@@ -0,0 +1,543 @@
+"""ORAS / OCI registry adapter for fetching disk images and other artifacts.
+
+Resolves ``oras://`` references against an OCI v2 registry into a plain
+HTTPS blob URL plus the auth headers the registry expects. The cache-host
+(``withcache.server``) calls in here on a cold miss when the decoded
+origin URL is ``oras://...`` so the existing Range-resume fetch loop
+can stream the bytes; library consumers (e.g. ``bty``) import the same
+helpers to validate catalog entries and pre-resolve content digests.
+
+URL shape::
+
+    oras://<host>[:port]/<owner>/<repo>[/<extra>]:<tag>
+    oras://<host>[:port]/<owner>/<repo>[/<extra>]@sha256:<64-hex>
+
+Digest-pinned references skip the manifest fetch (the digest IS the
+address); tag references go through manifest resolution + layer pick.
+
+Why ``oras://`` and not ``ghcr:``
+---------------------------------
+
+The ORAS spelling disambiguates from container references. A reader
+who sees ``ghcr.io/safl/nosi/debian-sysdev:latest`` in a docs example
+might reach for ``docker pull`` or ``podman run`` -- which would
+fail and leave them confused, because nosi publishes disk-image
+artifacts, not runnable container images. ``oras://`` is the
+ecosystem term for OCI-Registry-As-Storage; an operator googling it
+lands at oras.land which explicitly explains "store arbitrary
+artifacts, not just containers". The ``://`` form also composes
+with other registries -- ``oras://quay.io/...``,
+``oras://registry.example.com:5000/...`` -- without per-registry
+schemes.
+
+.. _ORAS: https://oras.land/
+
+Auth
+----
+
+Spec-compliant OCI v2 registries (GHCR included) return 401 on every
+request even for public packages. Their ``/token`` endpoint
+mints anonymous tokens on a plain credential-less GET. So the flow
+is: hit ``https://<host>/token``, take the returned bearer, set
+``Authorization: Bearer`` on the manifest + blob requests. No
+registry login, no PAT, no secrets shipped.
+
+The token endpoint is built from the URL's host (``ghcr.io`` ->
+``https://ghcr.io/token``), which works for GHCR and any registry
+that follows the same convention. Registries with non-standard auth
+flows (private registries with custom realms, e.g.) would need the
+proper ``WWW-Authenticate`` challenge dance instead -- noted as
+future work; not needed for the homelab / nosi use case this module
+ships for.
+
+Layer picker
+------------
+
+A nosi manifest carries two layers: the ``.img.gz`` disk image and a
+``.sha256`` sidecar. The picker drops layers whose
+``org.opencontainers.image.title`` annotation ends in a known sidecar
+suffix (``.sha256``, ``.sha512``, ``.sig``, ``.asc``, ``.pem``,
+``.cert``, ``.sbom``, ``.att``, ``.json``), then takes the largest
+remaining layer by declared size. Manifests with no useful
+annotations fall through to the largest layer overall -- a reasonable
+bet that the image bytes dwarf any metadata sidecar.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+ORAS_SCHEME = "oras://"
+
+# Transient HTTP statuses worth retrying: 429 (rate limit, common on
+# GHCR / Docker Hub under load) plus the gateway/server-blip 5xx range.
+# Everything else (401/403 auth, 404 not-found, other 4xx) is permanent
+# and raised immediately, since retrying would just stall the caller.
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+_RETRY_ATTEMPTS = 3
+_RETRY_BACKOFF = 0.5  # seconds; exponential: 0.5, 1.0 between attempts
+
+# Defensive ceiling on the metadata-fetch response body. Real-world
+# OCI tokens are <2 KiB and manifests are <100 KiB; anything beyond
+# this is either a misconfigured registry or a deliberately hostile
+# response. Capping the read keeps a runaway registry from exhausting
+# the host process's RAM on a tag resolve. Blob bytes do NOT go
+# through this helper (they stream via the cache-host's resume loop
+# with its own bounds).
+_MAX_METADATA_BYTES = 10 * 1024 * 1024  # 10 MiB
+
+# Accept type covers OCI v1 + Docker v2 manifest media types so the
+# registry doesn't bounce us with a 406 if the package was originally
+# pushed as a Docker manifest.
+_MANIFEST_ACCEPT = (
+    "application/vnd.oci.image.manifest.v1+json,"
+    "application/vnd.docker.distribution.manifest.v2+json"
+)
+
+# Layer titles ending in any of these are non-image sidecars (sha
+# sums, signatures, attestations); skip them when picking the image
+# layer so a future ``oras attach`` on the same artifact doesn't
+# silently start being served.
+_SIDECAR_SUFFIXES = (
+    ".sha256",
+    ".sha512",
+    ".sig",
+    ".asc",
+    ".pem",
+    ".cert",
+    ".sbom",
+    ".att",
+    ".json",
+)
+
+# Layer mediaTypes that are NEVER disk images. A manifest whose largest
+# layer carries one of these is a Helm chart, a Cosign signature, an
+# in-toto attestation, a SPDX SBOM, etc. Without this filter
+# ``pick_image_layer`` would happily pick the Helm tarball or the
+# signature blob and downstream consumers (e.g. ``bty.flash``) would
+# write its bytes onto an operator's target disk (tar headers /
+# signature bytes into the MBR). An operator typing ``oras://`` at a
+# non-image artifact deserves a clear error, not corruption.
+_NON_IMAGE_LAYER_MEDIA_TYPES = (
+    # Helm OCI charts.
+    "application/vnd.cncf.helm.chart.v1.tar+gzip",
+    "application/vnd.cncf.helm.chart.provenance.v1.prov",
+    # Cosign signatures.
+    "application/vnd.dev.cosign.simplesigning.v1+json",
+    "application/vnd.dev.cosign.artifact.sig.v1+json",
+    # in-toto attestations.
+    "application/vnd.in-toto+json",
+    "application/vnd.dev.cosign.artifact.bundle.v1+json",
+    "application/vnd.dsse.envelope.v1+json",
+    # SBOMs.
+    "application/spdx+json",
+    "application/vnd.cyclonedx+json",
+    # OCI empty descriptor (used by artifact references with no payload).
+    "application/vnd.oci.empty.v1+json",
+)
+
+
+def _is_non_image_layer(layer: dict[str, Any]) -> bool:
+    media_type = layer.get("mediaType")
+    if not isinstance(media_type, str):
+        return False
+    return media_type in _NON_IMAGE_LAYER_MEDIA_TYPES
+
+
+class OrasError(OSError):
+    """Raised on parse / resolution / fetch errors against an OCI registry.
+
+    Inherits from :class:`OSError` so it's caught by callers that
+    handle remote-I/O failures generically -- semantically the same
+    family as :class:`urllib.error.URLError`, which also subclasses
+    :class:`OSError`. Code paths that need to distinguish ORAS-
+    specific failures from arbitrary network errors still can:
+    :class:`OrasError` is a strict subclass."""
+
+
+@dataclass(frozen=True)
+class OrasRef:
+    """Parsed ``oras://`` reference.
+
+    Exactly one of ``tag`` / ``digest`` is set. ``digest`` references
+    skip the manifest fetch (the digest is content-addressed, so the
+    blob URL is fully determined). ``tag`` references go through the
+    manifest to resolve a layer digest first.
+    """
+
+    host: str  # e.g. "ghcr.io" or "registry.example.com:5000"
+    repository: str  # e.g. "safl/nosi/debian-sysdev"
+    tag: str | None = None
+    digest: str | None = None
+
+    @property
+    def manifest_locator(self) -> str:
+        """Value used in the ``/manifests/<X>`` URL path."""
+        if self.digest is not None:
+            return self.digest
+        assert self.tag is not None, "OrasRef must have either tag or digest set"
+        return self.tag
+
+
+# Host: DNS hostname (or registry.example.com:5000 with optional port).
+# Repository: lowercase alnum + ``/_.-``, must contain at least one
+# ``/`` after the host (owner + repo). Tag: OCI tag charset (alnum +
+# ``._-``). Digest: only sha256 today; future algorithms would need
+# extending. Layout overall::
+#
+#     <host>[:port]/<repo>(:<tag>|@sha256:<hex>)
+#
+# applied to the body after stripping the ``oras://`` scheme.
+_REF_RE = re.compile(
+    r"^"
+    r"(?P<host>[a-zA-Z0-9][a-zA-Z0-9.-]*(?::[0-9]+)?)"
+    r"/"
+    r"(?P<repo>[a-z0-9][a-z0-9/_.-]*)"
+    r"(?:(?:@(?P<digest>sha256:[0-9a-f]{64}))"
+    r"|(?::(?P<tag>[A-Za-z0-9._-]+)))"
+    r"$"
+)
+
+
+def parse_ref(ref: str) -> OrasRef:
+    """Parse an ``oras://`` reference into a :class:`OrasRef`.
+
+    Accepts the two canonical forms::
+
+        oras://<host>/<owner>/<repo>[/<extra>]:<tag>
+        oras://<host>/<owner>/<repo>[/<extra>]@sha256:<64-hex>
+
+    Raises :class:`OrasError` on any malformed input. The repository
+    component must contain at least one ``/`` -- a bare top-level
+    path like ``oras://ghcr.io/nosi:latest`` is rejected because OCI's
+    URL scheme requires owner+repo under the host.
+    """
+    if not ref.startswith(ORAS_SCHEME):
+        raise OrasError(f"not an oras:// reference: {ref!r}")
+    body = ref[len(ORAS_SCHEME) :]
+    if not body:
+        raise OrasError(f"empty oras:// reference: {ref!r}")
+    match = _REF_RE.match(body)
+    if match is None:
+        raise OrasError(
+            f"malformed oras:// reference {ref!r}: "
+            f"expected oras://<host>/<owner>/<repo>:<tag> or "
+            f"oras://<host>/<owner>/<repo>@sha256:<hex>"
+        )
+    repo = match.group("repo")
+    if "/" not in repo:
+        raise OrasError(
+            f"oras:// reference must include <host>/<owner>/<repo>: "
+            f"{ref!r} (got bare repo {repo!r} after host)"
+        )
+    return OrasRef(
+        host=match.group("host"),
+        repository=repo,
+        tag=match.group("tag"),
+        digest=match.group("digest"),
+    )
+
+
+def _urlopen_retry(req: urllib.request.Request | str, *, timeout: float) -> bytes:
+    """GET ``req`` and return the body bytes, retrying transient
+    failures with exponential backoff.
+
+    Retries on :data:`_RETRYABLE_STATUS` (429 / 5xx) and on raw
+    connection errors / timeouts. Permanent HTTP errors (401/403/404,
+    other 4xx) raise immediately -- a retry can't fix an auth or
+    not-found failure, only delay the inevitable. After
+    :data:`_RETRY_ATTEMPTS` the last error is re-raised so the caller's
+    ``except`` (which wraps into :class:`OrasError`) still fires.
+    """
+    last: BaseException | None = None
+    for attempt in range(_RETRY_ATTEMPTS):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                # Cap the read: a registry that returns a 500 MiB
+                # "manifest" should fail loud, not silently consume
+                # process RAM. ``read(N)`` returns up to N bytes; we
+                # take N+1 and reject the response if it overflows.
+                data = bytes(resp.read(_MAX_METADATA_BYTES + 1))
+                if len(data) > _MAX_METADATA_BYTES:
+                    raise OrasError(f"oras metadata response exceeded {_MAX_METADATA_BYTES} bytes")
+                return data
+        except urllib.error.HTTPError as exc:
+            if exc.code not in _RETRYABLE_STATUS:
+                raise
+            last = exc
+        except (urllib.error.URLError, TimeoutError, ConnectionError, OSError) as exc:
+            last = exc
+        if attempt < _RETRY_ATTEMPTS - 1:
+            time.sleep(_RETRY_BACKOFF * (2**attempt))
+    assert last is not None  # loop ran at least once
+    raise last
+
+
+def parse_www_authenticate(header: str) -> dict[str, str]:
+    """Parse an OCI ``WWW-Authenticate: Bearer realm="...",service="...",
+    scope="..."`` challenge into a dict of its (lower-cased) params.
+
+    Returns ``{}`` for a non-Bearer or unparseable challenge so callers
+    can treat "no usable challenge" uniformly.
+    """
+    header = header.strip()
+    if header[:7].lower() != "bearer ":
+        return {}
+    return {m.group(1).lower(): m.group(2) for m in re.finditer(r'(\w+)="([^"]*)"', header[7:])}
+
+
+def _token_from_endpoint(url: str, host: str, repository: str, *, timeout: float) -> str:
+    """GET a token endpoint and extract the bearer. Raises OrasError."""
+    payload = json.loads(_urlopen_retry(url, timeout=timeout))
+    # OCI registries return ``token``; some spell it ``access_token``.
+    token = payload.get("token") or payload.get("access_token")
+    if not isinstance(token, str) or not token:
+        raise OrasError(
+            f"oras token response for {host}/{repository} did not contain "
+            f"a token (keys: {sorted(payload.keys())})"
+        )
+    return token
+
+
+def _discover_bearer_challenge(host: str, *, timeout: float) -> dict[str, str]:
+    """Probe ``GET https://{host}/v2/`` and return the parsed Bearer
+    challenge from the 401 response's ``WWW-Authenticate`` header.
+
+    The spec-compliant way to find a registry's token endpoint when it
+    isn't the GHCR-convention ``https://<host>/token`` (Docker Hub uses
+    ``auth.docker.io``, e.g.). Returns ``{}`` if the registry answers
+    200 (no auth) or sends no usable challenge."""
+    req = urllib.request.Request(f"https://{host}/v2/", method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout):
+            return {}  # 200: no auth challenge to discover
+    except urllib.error.HTTPError as exc:
+        if exc.code != 401 or exc.headers is None:
+            return {}
+        return parse_www_authenticate(exc.headers.get("WWW-Authenticate", ""))
+    except (urllib.error.URLError, TimeoutError, OSError):
+        return {}
+
+
+def fetch_anonymous_token(host: str, repository: str, *, timeout: float = 30.0) -> str:
+    """Grab an anonymous bearer token for ``repository:pull``.
+
+    Spec-compliant OCI v2 registries expose a token endpoint that mints
+    short-lived anonymous bearers for public packages (no creds, no
+    PAT). Two-step:
+
+    1. Try the GHCR / oras.land convention ``https://<host>/token`` --
+       one request for the common case.
+    2. If that fails, fall back to the spec discovery: ping
+       ``GET /v2/``, read the realm advertised in the ``WWW-Authenticate``
+       Bearer challenge, and fetch from there. This covers registries
+       whose token endpoint isn't ``<host>/token`` (Docker Hub ->
+       ``auth.docker.io``, Quay's custom realm, etc.).
+    """
+    scope = f"repository:{urllib.parse.quote(repository, safe='/')}:pull"
+    conv_url = f"https://{host}/token?service={host}&scope={scope}"
+    try:
+        return _token_from_endpoint(conv_url, host, repository, timeout=timeout)
+    except (OSError, json.JSONDecodeError, ValueError, OrasError) as conv_exc:
+        # Convention failed; try spec discovery before giving up.
+        challenge = _discover_bearer_challenge(host, timeout=timeout)
+        realm = challenge.get("realm")
+        if realm:
+            service = challenge.get("service", host)
+            disc_url = f"{realm}?service={urllib.parse.quote(service, safe='')}&scope={scope}"
+            try:
+                return _token_from_endpoint(disc_url, host, repository, timeout=timeout)
+            except (OSError, json.JSONDecodeError, ValueError, OrasError) as exc:
+                raise OrasError(
+                    f"oras token fetch failed for {host}/{repository} via discovered "
+                    f"realm {realm}: {exc}"
+                ) from exc
+        # No usable discovery; surface the original conventional error.
+        raise OrasError(
+            f"oras token fetch failed for {host}/{repository}: {conv_exc}"
+        ) from conv_exc
+
+
+def fetch_manifest(ref: OrasRef, token: str, *, timeout: float = 30.0) -> dict[str, Any]:
+    """Fetch the OCI manifest for ``ref`` using a previously-acquired token.
+
+    Returns the parsed JSON. Raises :class:`OrasError` on network or
+    parse failure. The caller is responsible for layer selection.
+    """
+    locator = urllib.parse.quote(ref.manifest_locator, safe=":")
+    url = f"https://{ref.host}/v2/{ref.repository}/manifests/{locator}"
+    request = urllib.request.Request(
+        url,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": _MANIFEST_ACCEPT,
+        },
+    )
+    try:
+        payload = json.loads(_urlopen_retry(request, timeout=timeout))
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        raise OrasError(
+            f"oras manifest fetch failed for "
+            f"{ref.host}/{ref.repository}:{ref.manifest_locator}: {exc}"
+        ) from exc
+    if not isinstance(payload, dict):
+        raise OrasError(
+            f"oras manifest for "
+            f"{ref.host}/{ref.repository}:{ref.manifest_locator} "
+            f"is not a JSON object"
+        )
+    return payload
+
+
+def _layer_title(layer: dict[str, Any]) -> str:
+    annotations = layer.get("annotations")
+    if not isinstance(annotations, dict):
+        return ""
+    title = annotations.get("org.opencontainers.image.title", "")
+    return title if isinstance(title, str) else ""
+
+
+def pick_image_layer(manifest: dict[str, Any]) -> dict[str, Any]:
+    """Pick the disk-image layer from a (possibly multi-layer) manifest.
+
+    Drops sidecar-looking layers by title-annotation suffix, then takes
+    the largest by declared ``size``. A manifest with no usable
+    annotations falls through to the largest layer overall -- the image
+    bytes will dwarf any metadata blob in practice.
+
+    Raises :class:`OrasError` if the manifest has no layers at all.
+    """
+    layers = manifest.get("layers")
+    if not isinstance(layers, list) or not layers:
+        # A multi-arch image *index* (``manifests`` instead of
+        # ``layers``) is a common cause: a rolling tag that resolves
+        # to an OCI index rather than a single artifact manifest. Name
+        # it so the operator points at a concrete manifest/digest
+        # instead of staring at "no layers".
+        if isinstance(manifest.get("manifests"), list) and manifest["manifests"]:
+            raise OrasError(
+                "oras ref resolved to a multi-arch image index, not a single "
+                "artifact manifest; reference a concrete platform manifest by "
+                "its @sha256:<digest> instead of the index tag"
+            )
+        raise OrasError("manifest has no layers")
+
+    # First pass: drop layers whose mediaType is definitively not a
+    # disk image (Helm chart, Cosign sig, SBOM, attestation, ...).
+    # Unlike title-suffix sidecars, these are never the right pick AND
+    # never get a fallback; flashing a Helm chart's tar+gzip into a
+    # disk's MBR is the data-loss scenario this guard exists for.
+    rejected_media_types: list[str] = []
+    image_candidates: list[dict[str, Any]] = []
+    for layer in layers:
+        if not isinstance(layer, dict):
+            continue
+        if _is_non_image_layer(layer):
+            mt = layer.get("mediaType")
+            if isinstance(mt, str):
+                rejected_media_types.append(mt)
+            continue
+        image_candidates.append(layer)
+    if not image_candidates:
+        if rejected_media_types:
+            unique = ", ".join(sorted(set(rejected_media_types)))
+            raise OrasError(
+                f"oras ref resolved to a non-disk-image artifact "
+                f"(layer mediaTypes: {unique}); refusing to serve "
+                f"signature / Helm chart / SBOM blobs as disk images"
+            )
+        raise OrasError("manifest has no usable layers")
+
+    # Second pass: among the image-eligible layers, prefer ones that
+    # DON'T look like title-annotation sidecars (.sha256 / .sig / ...
+    # filenames). If every remaining layer carries a sidecar-looking
+    # title, fall back to "pick the largest" so the resolver gets a
+    # chance to fail loudly downstream rather than this picker
+    # mis-classifying.
+    image_like: list[dict[str, Any]] = []
+    for layer in image_candidates:
+        title = _layer_title(layer)
+        if title and any(title.endswith(suffix) for suffix in _SIDECAR_SUFFIXES):
+            continue
+        image_like.append(layer)
+    candidates = image_like or image_candidates
+    return max(candidates, key=lambda layer: layer.get("size") or 0)
+
+
+@dataclass(frozen=True)
+class ResolvedBlob:
+    """Everything a fetcher needs to stream the image bytes.
+
+    ``blob_url`` is the final ``/v2/<repo>/blobs/sha256:<digest>``
+    endpoint. ``headers`` carries the bearer the registry expects. The
+    ``digest`` is what the fetcher should verify the downloaded bytes
+    against -- when the caller started from a tag, this is the digest
+    the registry resolved to right now, frozen for the rest of the
+    fetch.
+    """
+
+    blob_url: str
+    headers: dict[str, str]
+    digest: str
+    size: int | None
+    title: str | None
+
+
+def resolve_ref(ref: str | OrasRef, *, timeout: float = 30.0) -> ResolvedBlob:
+    """Resolve an ``oras://`` reference (or pre-parsed :class:`OrasRef`)
+    to a :class:`ResolvedBlob`.
+
+    For tag references: anonymous token -> manifest -> layer pick ->
+    ``ResolvedBlob`` with the layer's content-addressed digest. The
+    digest is frozen at resolve time so a tag that moves under us
+    between resolve and fetch still produces the bytes we committed to.
+
+    For digest-pinned references: anonymous token only; the blob URL is
+    fully determined by the digest, the manifest fetch is skipped, and
+    size / title come back as ``None`` (the descriptor's optional
+    ``size_bytes`` field can carry that info instead if known).
+    """
+    if isinstance(ref, str):
+        ref = parse_ref(ref)
+    token = fetch_anonymous_token(ref.host, ref.repository, timeout=timeout)
+    headers = {"Authorization": f"Bearer {token}"}
+
+    if ref.digest is not None:
+        digest = ref.digest
+        size: int | None = None
+        title: str | None = None
+    else:
+        manifest = fetch_manifest(ref, token, timeout=timeout)
+        layer = pick_image_layer(manifest)
+        raw_digest = layer.get("digest")
+        if not isinstance(raw_digest, str) or not raw_digest.startswith("sha256:"):
+            raise OrasError(
+                f"picked layer for "
+                f"{ref.host}/{ref.repository}:{ref.manifest_locator} "
+                f"has unusable digest {raw_digest!r}"
+            )
+        digest = raw_digest
+        layer_size = layer.get("size")
+        size = layer_size if isinstance(layer_size, int) else None
+        title = _layer_title(layer) or None
+
+    blob_url = f"https://{ref.host}/v2/{ref.repository}/blobs/{digest}"
+    return ResolvedBlob(
+        blob_url=blob_url,
+        headers=headers,
+        digest=digest,
+        size=size,
+        title=title,
+    )
+
+
+def is_oras_url(url: str) -> bool:
+    """True iff ``url`` is an ``oras://`` reference rather than http(s)://."""
+    return url.startswith(ORAS_SCHEME)

{withcache-0.5.2 → withcache-0.6.0}/src/withcache/server.py

@@ -41,7 +41,7 @@ import urllib.request
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 
-from . import __version__
+from . import __version__, oras
 
 CHUNK = 64 * 1024
 USER_AGENT = f"withcache-cache/{__version__}"
@@ -316,6 +316,7 @@ class Store:
         cancel=None,
         headers=None,
         max_resume_attempts: int = RESUME_MAX_ATTEMPTS,
+        fetch_resolver=None,
     ) -> sqlite3.Row:
         """Operator-triggered: pull the artifact from origin and store it.
 
@@ -326,6 +327,15 @@ class Store:
         bearer token bty pre-resolved for an oras blob). Raises :class:`CacheFull`
         if the cache is already at --max-bytes.
 
+        ``fetch_resolver`` is an optional zero-arg callable that returns
+        ``(fetch_url, fetch_headers)`` for the current attempt. When set,
+        every resume attempt re-invokes it -- so an ``oras://...`` cache key
+        can be backed by a fresh registry bearer + fresh signed CDN URL on
+        each retry (both have short TTLs the resume loop will otherwise blow
+        through). When unset, every attempt hits ``url`` directly. The
+        ``fetch_headers`` are layered under the caller-supplied ``headers``,
+        so an operator-provided override wins.
+
         Resume-on-truncation: if the upstream stream ends before its
         declared Content-Length, the partial bytes are kept and the
         next attempt requests ``Range: bytes=<got>-`` so the fetch
@@ -346,23 +356,32 @@ class Store:
         normalized = self.normalize(url)
         key = self.key_of(normalized)
         tmp = os.path.join(self.tmp_dir, key + ".part")
-        base_headers = {"User-Agent": USER_AGENT}
-        if headers:
-            base_headers.update(headers)
         sha = hashlib.sha256()
         size = 0
         total: int | None = None
         content_type: str | None = None
         try:
             for _ in range(max_resume_attempts):
-                req_headers = dict(base_headers)
+                # Resolve fetch URL + headers afresh per attempt: for
+                # oras://, the bearer + signed CDN URL each have short
+                # TTLs the prior attempt may have blown through; for
+                # plain HTTP the resolver is unset and we fetch ``url``
+                # with a stable header set.
+                if fetch_resolver is not None:
+                    fetch_url, resolved_headers = fetch_resolver()
+                else:
+                    fetch_url = url
+                    resolved_headers = {}
+                req_headers = {"User-Agent": USER_AGENT, **resolved_headers}
+                if headers:
+                    req_headers.update(headers)
                 if size > 0:
                     # Resume from where the previous attempt cut.
                     # A 206 response continues the stream; a 200
                     # means the origin ignored Range (e.g. a dumb
                     # static server) and we restart from 0.
                     req_headers["Range"] = f"bytes={size}-"
-                req = urllib.request.Request(url, headers=req_headers)
+                req = urllib.request.Request(fetch_url, headers=req_headers)
                 with urllib.request.urlopen(req, timeout=120) as resp:
                     status = getattr(resp, "status", None) or resp.getcode()
                     if content_type is None:
@@ -605,11 +624,26 @@ class DownloadManager:
                 job.status = "running"
                 job.started_at = time.time()
             try:
+                # For oras://, the cache key stays the original ref but
+                # the actual request goes through a freshly-minted
+                # bearer + resolved blob URL. The resolver runs per
+                # resume attempt so a long fetch survives bearer /
+                # signed-URL TTL expiry mid-stream (the same kind of
+                # cut the surrounding Range-resume loop was built for).
+                fetch_resolver: object = None
+                if oras.is_oras_url(job.url):
+
+                    def _oras_resolve(_url: str = job.url) -> tuple[str, dict[str, str]]:
+                        resolved = oras.resolve_ref(_url)
+                        return resolved.blob_url, dict(resolved.headers)
+
+                    fetch_resolver = _oras_resolve
                 row = self.store.store_from_origin(
                     job.url,
                     progress=lambda done, total, j=job: _set_progress(j, done, total),
                     cancel=job._cancel.is_set,
                     headers=job.headers,
+                    fetch_resolver=fetch_resolver,
                 )
                 with self._lock:
                     job.status = "completed"

withcache-0.6.0/tests/test_oras.py

@@ -0,0 +1,480 @@
+"""Stdlib-only tests for withcache.oras (the OCI registry adapter).
+
+Parser tests are pure; resolver tests mock ``urllib.request.urlopen`` so
+they run on offline CI and don't hit a real registry. Mirrors the test
+matrix that lived at ``bty/tests/test_oras.py`` before withcache took
+over OCI handling.
+"""
+
+import http.server
+import io
+import json
+import os
+import socketserver
+import sys
+import tempfile
+import threading
+import unittest
+import urllib.error
+from typing import Any
+from unittest.mock import patch
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from withcache import oras, server  # noqa: E402
+
+# A trimmed-down version of a real nosi manifest -- two layers (the
+# .img.gz and a .sha256 sidecar), one annotation each, OCI media types.
+_NOSI_MANIFEST: dict[str, Any] = {
+    "schemaVersion": 2,
+    "mediaType": "application/vnd.oci.image.manifest.v1+json",
+    "artifactType": "application/vnd.nosi.disk-image.v1+gzip",
+    "layers": [
+        {
+            "mediaType": "application/vnd.nosi.disk-image.layer.v1+gzip",
+            "digest": "sha256:" + "aa" * 32,
+            "size": 1923658046,
+            "annotations": {"org.opencontainers.image.title": "nosi-debian-sysdev-x86_64.img.gz"},
+        },
+        {
+            "mediaType": "text/plain",
+            "digest": "sha256:" + "bb" * 32,
+            "size": 130,
+            "annotations": {
+                "org.opencontainers.image.title": "nosi-debian-sysdev-x86_64.img.gz.sha256"
+            },
+        },
+    ],
+}
+
+
+class _BytesResp(io.BytesIO):
+    def __enter__(self) -> "_BytesResp":
+        return self
+
+    def __exit__(self, *_a: object) -> None:
+        return None
+
+
+def _http_error(code: int) -> urllib.error.HTTPError:
+    return urllib.error.HTTPError("https://x/y", code, f"err {code}", {}, None)  # type: ignore[arg-type]
+
+
+def _make_urlopen_mock(token: str = "anon-token-xyz"):
+    """urlopen replacement returning a token payload for /token and the
+    nosi manifest for any /manifests/ URL."""
+
+    def _fake_urlopen(req, timeout=None):
+        url = req if isinstance(req, str) else req.full_url
+        if "/token" in url:
+            return _BytesResp(json.dumps({"token": token}).encode())
+        if "/manifests/" in url:
+            return _BytesResp(json.dumps(_NOSI_MANIFEST).encode())
+        raise AssertionError(f"unexpected URL in test: {url}")
+
+    return _fake_urlopen
+
+
+class TestParseRef(unittest.TestCase):
+    def test_tag_form(self):
+        ref = oras.parse_ref("oras://ghcr.io/safl/nosi/debian-sysdev:latest")
+        self.assertEqual(ref.host, "ghcr.io")
+        self.assertEqual(ref.repository, "safl/nosi/debian-sysdev")
+        self.assertEqual(ref.tag, "latest")
+        self.assertIsNone(ref.digest)
+        self.assertEqual(ref.manifest_locator, "latest")
+
+    def test_digest_form(self):
+        digest = "sha256:" + "ab" * 32
+        ref = oras.parse_ref(f"oras://ghcr.io/safl/nosi/debian-sysdev@{digest}")
+        self.assertEqual(ref.host, "ghcr.io")
+        self.assertEqual(ref.repository, "safl/nosi/debian-sysdev")
+        self.assertIsNone(ref.tag)
+        self.assertEqual(ref.digest, digest)
+        self.assertEqual(ref.manifest_locator, digest)
+
+    def test_owner_repo_minimum(self):
+        """Two-segment owner/repo under the host is the minimum."""
+        ref = oras.parse_ref("oras://ghcr.io/owner/repo:v1")
+        self.assertEqual(ref.host, "ghcr.io")
+        self.assertEqual(ref.repository, "owner/repo")
+
+    def test_accepts_host_with_port(self):
+        """Private registries on non-443 ports preserve host:port verbatim."""
+        ref = oras.parse_ref("oras://registry.example.com:5000/foo/bar:v1")
+        self.assertEqual(ref.host, "registry.example.com:5000")
+        self.assertEqual(ref.repository, "foo/bar")
+
+    def test_rejects_bare_repo_after_host(self):
+        with self.assertRaisesRegex(oras.OrasError, r"host.*owner.*repo"):
+            oras.parse_ref("oras://ghcr.io/nosi:latest")
+
+    def test_rejects_missing_scheme(self):
+        with self.assertRaisesRegex(oras.OrasError, "not an oras://"):
+            oras.parse_ref("ghcr.io/safl/nosi:latest")
+
+    def test_rejects_empty_body(self):
+        with self.assertRaisesRegex(oras.OrasError, "empty"):
+            oras.parse_ref("oras://")
+
+    def test_rejects_missing_tag_and_digest(self):
+        """Tagless / digestless refs aren't pullable."""
+        with self.assertRaisesRegex(oras.OrasError, "malformed"):
+            oras.parse_ref("oras://ghcr.io/safl/nosi/debian-sysdev")
+
+    def test_rejects_short_digest(self):
+        """sha256 must be 64 hex chars; partial digests would mis-address."""
+        with self.assertRaisesRegex(oras.OrasError, "malformed"):
+            oras.parse_ref("oras://ghcr.io/safl/nosi/debian-sysdev@sha256:abc123")
+
+
+class TestPickImageLayer(unittest.TestCase):
+    def test_skips_sha256_sidecar(self):
+        layer = oras.pick_image_layer(_NOSI_MANIFEST)
+        title = layer["annotations"]["org.opencontainers.image.title"]
+        self.assertEqual(title, "nosi-debian-sysdev-x86_64.img.gz")
+        self.assertFalse(title.endswith(".sha256"))
+
+    def test_picks_largest_when_no_sidecar(self):
+        manifest: dict[str, Any] = {
+            "layers": [
+                {"digest": "sha256:" + "11" * 32, "size": 100, "annotations": {}},
+                {"digest": "sha256:" + "22" * 32, "size": 1_000_000, "annotations": {}},
+            ]
+        }
+        self.assertEqual(oras.pick_image_layer(manifest)["size"], 1_000_000)
+
+    def test_raises_on_empty_layers(self):
+        with self.assertRaisesRegex(oras.OrasError, "no layers"):
+            oras.pick_image_layer({"layers": []})
+
+    def test_raises_on_non_list_layers(self):
+        with self.assertRaisesRegex(oras.OrasError, "no layers"):
+            oras.pick_image_layer({"layers": "not-a-list"})
+
+    def test_skips_non_dict_layer_entries(self):
+        manifest: dict[str, Any] = {
+            "layers": [
+                None,
+                "garbage",
+                {"digest": "sha256:" + "33" * 32, "size": 4096, "annotations": {}},
+            ]
+        }
+        self.assertEqual(oras.pick_image_layer(manifest)["size"], 4096)
+
+    def test_names_multiarch_index(self):
+        """A multi-arch image index gets a specific error pointing the
+        operator at a concrete digest, not the generic 'no layers'."""
+        index = {
+            "mediaType": "application/vnd.oci.image.index.v1+json",
+            "manifests": [
+                {"digest": "sha256:" + "aa" * 32, "platform": {"architecture": "amd64"}},
+                {"digest": "sha256:" + "bb" * 32, "platform": {"architecture": "arm64"}},
+            ],
+        }
+        with self.assertRaisesRegex(oras.OrasError, "multi-arch image index"):
+            oras.pick_image_layer(index)
+
+    def test_refuses_helm_chart(self):
+        """Helm tarball mediaType must be refused: flashing tar+gzip
+        bytes onto a target disk is data-loss territory."""
+        helm: dict[str, Any] = {
+            "layers": [
+                {
+                    "digest": "sha256:" + "55" * 32,
+                    "size": 4_096,
+                    "mediaType": "application/vnd.cncf.helm.chart.v1.tar+gzip",
+                },
+                {
+                    "digest": "sha256:" + "66" * 32,
+                    "size": 256,
+                    "mediaType": "application/vnd.cncf.helm.chart.provenance.v1.prov",
+                },
+            ]
+        }
+        with self.assertRaisesRegex(oras.OrasError, "non-disk-image artifact"):
+            oras.pick_image_layer(helm)
+
+    def test_refuses_cosign_sig(self):
+        cosign: dict[str, Any] = {
+            "layers": [
+                {
+                    "digest": "sha256:" + "77" * 32,
+                    "size": 512,
+                    "mediaType": "application/vnd.dev.cosign.simplesigning.v1+json",
+                },
+            ]
+        }
+        with self.assertRaisesRegex(oras.OrasError, "non-disk-image artifact"):
+            oras.pick_image_layer(cosign)
+
+    def test_picks_image_alongside_provenance(self):
+        """One real image layer + a non-image sidecar still resolves
+        to the image; only all-non-image manifests get refused."""
+        mixed: dict[str, Any] = {
+            "layers": [
+                {
+                    "digest": "sha256:" + "aa" * 32,
+                    "size": 256,
+                    "mediaType": "application/vnd.in-toto+json",
+                },
+                {
+                    "digest": "sha256:" + "bb" * 32,
+                    "size": 2_000_000,
+                    "annotations": {"org.opencontainers.image.title": "appliance.img.gz"},
+                },
+            ]
+        }
+        self.assertEqual(oras.pick_image_layer(mixed)["size"], 2_000_000)
+
+    def test_falls_back_when_all_look_like_sidecars(self):
+        """If every layer is annotated with a sidecar-suffix title,
+        fall back to picking the largest (the resolver fails downstream
+        rather than silently mis-classifying)."""
+        manifest: dict[str, Any] = {
+            "layers": [
+                {
+                    "digest": "sha256:" + "33" * 32,
+                    "size": 50,
+                    "annotations": {"org.opencontainers.image.title": "a.sha256"},
+                },
+                {
+                    "digest": "sha256:" + "44" * 32,
+                    "size": 500,
+                    "annotations": {"org.opencontainers.image.title": "b.sha256"},
+                },
+            ]
+        }
+        self.assertEqual(oras.pick_image_layer(manifest)["size"], 500)
+
+
+class TestResolveRef(unittest.TestCase):
+    def test_tag_resolves_to_layer_digest(self):
+        with patch("urllib.request.urlopen", _make_urlopen_mock()):
+            resolved = oras.resolve_ref("oras://ghcr.io/safl/nosi/debian-sysdev:latest")
+        self.assertEqual(resolved.digest, "sha256:" + "aa" * 32)
+        self.assertEqual(resolved.size, 1923658046)
+        self.assertEqual(resolved.title, "nosi-debian-sysdev-x86_64.img.gz")
+        self.assertEqual(
+            resolved.blob_url,
+            f"https://ghcr.io/v2/safl/nosi/debian-sysdev/blobs/sha256:{'aa' * 32}",
+        )
+        self.assertEqual(resolved.headers, {"Authorization": "Bearer anon-token-xyz"})
+
+    def test_digest_skips_manifest(self):
+        """Digest-pinned references skip the manifest fetch entirely."""
+
+        def _strict_urlopen(req, timeout=None):
+            url = req if isinstance(req, str) else req.full_url
+            if "/manifests/" in url:
+                raise AssertionError("digest-pinned ref should not fetch manifest")
+            return _BytesResp(json.dumps({"token": "pinned-token"}).encode())
+
+        digest = "sha256:" + "cd" * 32
+        with patch("urllib.request.urlopen", _strict_urlopen):
+            resolved = oras.resolve_ref(f"oras://ghcr.io/safl/nosi/debian-sysdev@{digest}")
+        self.assertEqual(resolved.digest, digest)
+        self.assertIsNone(resolved.size)
+        self.assertIsNone(resolved.title)
+        self.assertEqual(
+            resolved.blob_url, f"https://ghcr.io/v2/safl/nosi/debian-sysdev/blobs/{digest}"
+        )
+
+    def test_uses_host_from_url_in_token_endpoint(self):
+        """Token endpoint URL must follow the ref's host (not hardcoded
+        to ghcr.io). Verifies cross-registry support."""
+        seen: list[str] = []
+
+        def _capturing(req, timeout=None):
+            url = req if isinstance(req, str) else req.full_url
+            seen.append(url)
+            if "/token" in url:
+                return _BytesResp(json.dumps({"token": "tok"}).encode())
+            return _BytesResp(json.dumps(_NOSI_MANIFEST).encode())
+
+        with patch("urllib.request.urlopen", _capturing):
+            oras.resolve_ref("oras://registry.example.com:5000/foo/bar:v1")
+
+        self.assertTrue(
+            any(u.startswith("https://registry.example.com:5000/token") for u in seen),
+            f"expected custom-host token URL in {seen}",
+        )
+
+    def test_propagates_token_failure(self):
+        def _failing(req, timeout=None):
+            raise OSError("network unreachable")
+
+        with patch("urllib.request.urlopen", _failing):
+            with self.assertRaisesRegex(oras.OrasError, "token fetch failed"):
+                oras.resolve_ref("oras://ghcr.io/safl/nosi/debian-sysdev:latest")
+
+
+class TestIsOrasUrl(unittest.TestCase):
+    def test_recognises_only_oras_scheme(self):
+        self.assertTrue(oras.is_oras_url("oras://ghcr.io/safl/nosi/debian-sysdev:latest"))
+        self.assertFalse(oras.is_oras_url("https://ghcr.io/v2/safl/nosi/debian-sysdev/blobs/sha:x"))
+        self.assertFalse(oras.is_oras_url("https://example.invalid/x.img.gz"))
+        # ``ghcr:`` is NOT recognised; the explicit ``oras://`` form is required.
+        self.assertFalse(oras.is_oras_url("ghcr:safl/nosi/debian-sysdev:latest"))
+
+
+class TestUrlopenRetry(unittest.TestCase):
+    def test_retries_transient_then_succeeds(self):
+        with patch.object(oras.time, "sleep", lambda *_a: None):
+            calls = {"n": 0}
+
+            def _flaky(req, timeout=None):
+                calls["n"] += 1
+                if calls["n"] == 1:
+                    raise _http_error(503)
+                return _BytesResp(b"ok")
+
+            with patch("urllib.request.urlopen", _flaky):
+                self.assertEqual(oras._urlopen_retry("https://x/y", timeout=5), b"ok")
+            self.assertEqual(calls["n"], 2)
+
+    def test_does_not_retry_permanent(self):
+        with patch.object(oras.time, "sleep", lambda *_a: None):
+            calls = {"n": 0}
+
+            def _notfound(req, timeout=None):
+                calls["n"] += 1
+                raise _http_error(404)
+
+            with patch("urllib.request.urlopen", _notfound):
+                with self.assertRaises(urllib.error.HTTPError):
+                    oras._urlopen_retry("https://x/y", timeout=5)
+            self.assertEqual(calls["n"], 1)
+
+    def test_exhausts_then_reraises(self):
+        with patch.object(oras.time, "sleep", lambda *_a: None):
+            calls = {"n": 0}
+
+            def _down(req, timeout=None):
+                calls["n"] += 1
+                raise _http_error(503)
+
+            with patch("urllib.request.urlopen", _down):
+                with self.assertRaises(urllib.error.HTTPError):
+                    oras._urlopen_retry("https://x/y", timeout=5)
+            self.assertEqual(calls["n"], oras._RETRY_ATTEMPTS)
+
+
+class TestFetchAnonymousToken(unittest.TestCase):
+    def test_rides_through_transient_503(self):
+        with patch.object(oras.time, "sleep", lambda *_a: None):
+            calls = {"n": 0}
+
+            def _flaky(req, timeout=None):
+                calls["n"] += 1
+                if calls["n"] == 1:
+                    raise _http_error(503)
+                return _BytesResp(json.dumps({"token": "tok"}).encode())
+
+            with patch("urllib.request.urlopen", _flaky):
+                self.assertEqual(oras.fetch_anonymous_token("ghcr.io", "owner/repo"), "tok")
+            self.assertEqual(calls["n"], 2)
+
+    def test_discovers_realm_when_convention_fails(self):
+        """Conventional <host>/token 404s -> read the /v2/ Bearer
+        challenge's realm and fetch from there (Docker-Hub style)."""
+        with patch.object(oras.time, "sleep", lambda *_a: None):
+            realm = "https://auth.example.io/token"
+
+            def _fake(req, timeout=None):
+                url = req if isinstance(req, str) else req.full_url
+                if url.startswith("https://reg.example.io/token"):
+                    raise _http_error(404)
+                if url == "https://reg.example.io/v2/":
+                    raise urllib.error.HTTPError(
+                        url,
+                        401,
+                        "unauthorized",
+                        {"WWW-Authenticate": f'Bearer realm="{realm}",service="reg.example.io"'},  # type: ignore[arg-type]
+                        None,
+                    )
+                if url.startswith(realm):
+                    return _BytesResp(json.dumps({"token": "disc-tok"}).encode())
+                raise AssertionError(f"unexpected URL in test: {url}")
+
+            with patch("urllib.request.urlopen", _fake):
+                self.assertEqual(
+                    oras.fetch_anonymous_token("reg.example.io", "owner/repo"), "disc-tok"
+                )
+
+
+class TestParseWwwAuthenticate(unittest.TestCase):
+    def test_bearer(self):
+        params = oras.parse_www_authenticate(
+            'Bearer realm="https://a/token",service="svc",scope="repository:x:pull"'
+        )
+        self.assertEqual(params["realm"], "https://a/token")
+        self.assertEqual(params["service"], "svc")
+        self.assertEqual(params["scope"], "repository:x:pull")
+
+    def test_ignores_non_bearer(self):
+        self.assertEqual(oras.parse_www_authenticate('Basic realm="x"'), {})
+        self.assertEqual(oras.parse_www_authenticate(""), {})
+
+
+# --------------------------------------------------------------------------
+# Integration: Store.store_from_origin with a fetch_resolver
+# --------------------------------------------------------------------------
+_BLOB_PAYLOAD = b"oras-blob-bytes-" * 64  # 1 KiB
+
+
+class _BlobOrigin(http.server.BaseHTTPRequestHandler):
+    """Fake registry CDN: serves the blob bytes on any GET, no auth check."""
+
+    def do_GET(self):
+        self.send_response(200)
+        self.send_header("Content-Type", "application/octet-stream")
+        self.send_header("Content-Length", str(len(_BLOB_PAYLOAD)))
+        self.end_headers()
+        self.wfile.write(_BLOB_PAYLOAD)
+
+    def log_message(self, format, *args):
+        pass
+
+
+class TestStoreFromOriginWithResolver(unittest.TestCase):
+    """The contract that makes oras work end-to-end: the cache key is
+    the original ``url`` (the ``oras://`` ref), but the actual HTTP
+    request is sent to whatever the ``fetch_resolver`` callback hands
+    back. A subsequent ``get_blob(oras_url)`` must hit -- not require
+    re-resolving."""
+
+    def setUp(self):
+        self.httpd = socketserver.TCPServer(("127.0.0.1", 0), _BlobOrigin)
+        self.port = self.httpd.server_address[1]
+        self.t = threading.Thread(target=self.httpd.serve_forever, daemon=True)
+        self.t.start()
+        self.store = server.Store(tempfile.mkdtemp(), keep_query=False)
+
+    def tearDown(self):
+        self.httpd.shutdown()
+        self.httpd.server_close()
+
+    def test_cache_key_is_oras_url_fetch_goes_through_resolver(self):
+        oras_url = "oras://ghcr.io/safl/nosi/sample:latest"
+        cdn_url = f"http://127.0.0.1:{self.port}/blobs/sha256:fake"
+
+        calls = {"n": 0}
+
+        def _resolver():
+            calls["n"] += 1
+            return cdn_url, {"Authorization": "Bearer test-bearer"}
+
+        row = self.store.store_from_origin(oras_url, fetch_resolver=_resolver)
+        self.assertEqual(row["size"], len(_BLOB_PAYLOAD))
+        # Resolver called at least once (a clean fetch is one attempt).
+        self.assertGreaterEqual(calls["n"], 1)
+        # Cache key is bound to the oras:// ref, not the CDN URL.
+        hit = self.store.get_blob(oras_url)
+        self.assertIsNotNone(hit)
+        # The CDN URL is NOT directly looked up: clients only know the oras ref.
+        self.assertIsNone(self.store.get_blob(cdn_url))
+
+
+if __name__ == "__main__":
+    unittest.main()