withcache 0.6.0__tar.gz → 0.6.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.6.0
+Version: 0.6.1
 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.6.0 → withcache-0.6.1}/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.6.0",
+    .version = "0.6.1",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

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

@@ -17,6 +17,6 @@ All modules are stdlib-only and self-contained.
 from . import oras
 from .client import blob_url, cache_base, is_cached, serve_url
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

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

@@ -669,6 +669,49 @@ def _set_progress(job: Job, done: int, total: int | None):
         job.bytes_total = total
 
 
+def _oras_tag_moved(url: str, cached_sha: str | None, *, resolve=oras.resolve_ref) -> bool:
+    """True iff ``url`` is an ``oras://`` *tag* whose layer the registry now
+    resolves to something other than ``cached_sha``.
+
+    The store keys on the ref string, not the resolved digest, so a mutable
+    tag that is re-pushed (e.g. a rolling weekly image tag) would otherwise
+    serve the first-cached bytes forever. Re-resolve the tag and compare its
+    current layer digest against the cached bytes' ``sha256`` -- which IS that
+    layer's content digest, so the comparison is exact.
+
+    Returns False (keep the cached copy) for anything we cannot prove has
+    moved: a non-oras URL, a digest-pinned ref (content-addressed, immutable),
+    a missing ``cached_sha``, or a registry/resolve error -- availability
+    beats freshness when the origin is unreachable, and a transient failure
+    must never nuke a good entry. Returns True only on a demonstrated move, so
+    the caller invalidates and re-fetches. ``resolve`` is injectable for tests.
+    """
+    if not oras.is_oras_url(url):
+        return False
+    try:
+        ref = oras.parse_ref(url)
+    except Exception:
+        return False
+    if ref.digest is not None:
+        return False  # digest-pinned: the ref already names the content
+    cached = (cached_sha or "").lower()
+    if not cached:
+        return False
+    try:
+        current = resolve(ref).digest.split(":", 1)[-1].lower()
+    except Exception as exc:
+        print(f"withcache: oras revalidate {url} failed: {exc}; serving cached copy", flush=True)
+        return False
+    if current == cached:
+        return False
+    print(
+        f"withcache: oras tag moved {url}: "
+        f"cached sha256:{cached[:12]} -> registry sha256:{current[:12]}; invalidating",
+        flush=True,
+    )
+    return True
+
+
 # --------------------------------------------------------------------------
 # HTTP handler
 # --------------------------------------------------------------------------
@@ -856,6 +899,13 @@ class Handler(http.server.BaseHTTPRequestHandler):
             self.send_text(400, "missing url\n")
             return
         row = self.store.get_blob(url)
+        if row is not None and _oras_tag_moved(url, row["sha256"]):
+            # The tag was re-pushed to a different layer since we cached it.
+            # Drop the stale bytes and fall through to the miss path so the
+            # current content is (auto-)fetched. Deleting first also frees the
+            # space the refill needs when the store is near --max-bytes.
+            self.store.delete_blob(row["key"])
+            row = None
         if row is None:
             self.store.record_miss(url)
             if self.auto_fetch and self.store.has_capacity():

{withcache-0.6.0 → withcache-0.6.1}/tests/test_withcache.py

@@ -13,6 +13,7 @@ import sys
 import tempfile
 import threading
 import time
+import types
 import unittest
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
@@ -961,5 +962,66 @@ class TestClientLibraryAuthForwarding(unittest.TestCase):
         )
 
 
+class TestOrasTagRevalidation(unittest.TestCase):
+    """server._oras_tag_moved: the store keys on the ref string, so a
+    re-pushed *mutable* tag must be detected and invalidated, while
+    digest-pinned refs and unreachable registries leave the cache intact."""
+
+    TAG = "oras://ghcr.io/safl/nosi/ubuntu-2604-headless:2026.W26"
+    HEX_A = "a" * 64
+    HEX_B = "b" * 64
+
+    @staticmethod
+    def _resolver(digest_hex):
+        def _r(_ref):
+            return types.SimpleNamespace(digest="sha256:" + digest_hex)
+
+        return _r
+
+    def test_moved_when_registry_digest_differs(self):
+        self.assertTrue(
+            server._oras_tag_moved(self.TAG, self.HEX_A, resolve=self._resolver(self.HEX_B))
+        )
+
+    def test_not_moved_when_digest_matches(self):
+        self.assertFalse(
+            server._oras_tag_moved(self.TAG, self.HEX_A, resolve=self._resolver(self.HEX_A))
+        )
+
+    def test_digest_match_is_case_insensitive(self):
+        self.assertFalse(
+            server._oras_tag_moved(self.TAG, self.HEX_A.upper(), resolve=self._resolver(self.HEX_A))
+        )
+
+    def test_digest_pinned_ref_never_revalidates(self):
+        pinned = "oras://ghcr.io/safl/nosi/x@sha256:" + self.HEX_A
+        calls = []
+
+        def _r(ref):
+            calls.append(ref)
+            return types.SimpleNamespace(digest="sha256:" + self.HEX_B)
+
+        self.assertFalse(server._oras_tag_moved(pinned, self.HEX_A, resolve=_r))
+        self.assertEqual(calls, [], "a digest-pinned ref must not hit the registry")
+
+    def test_non_oras_url_is_never_moved(self):
+        self.assertFalse(
+            server._oras_tag_moved(
+                "https://h/x.img.gz", self.HEX_A, resolve=self._resolver(self.HEX_B)
+            )
+        )
+
+    def test_missing_cached_sha_keeps_entry(self):
+        r = self._resolver(self.HEX_B)
+        self.assertFalse(server._oras_tag_moved(self.TAG, "", resolve=r))
+        self.assertFalse(server._oras_tag_moved(self.TAG, None, resolve=r))
+
+    def test_resolve_error_serves_cached(self):
+        def _boom(_ref):
+            raise OSError("registry unreachable")
+
+        self.assertFalse(server._oras_tag_moved(self.TAG, self.HEX_A, resolve=_boom))
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)