withcache 0.6.0__tar.gz → 0.6.2__tar.gz

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

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

{withcache-0.6.0 → withcache-0.6.2}/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.2"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

{withcache-0.6.0 → withcache-0.6.2}/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
 # --------------------------------------------------------------------------
@@ -714,7 +757,15 @@ class Handler(http.server.BaseHTTPRequestHandler):
             if not self.is_authed():
                 self.send_text(401, "login required\n")
             else:
-                self.send_html(200, self.render_dash())
+                # The browser sends the current URL hash (the active
+                # tab id) via the ``X-Active-Tab`` request header on
+                # every 1 Hz refresh. Server bakes the matching
+                # ``.active-tab`` class directly into the rendered
+                # HTML so the htmx innerHTML swap doesn't visibly
+                # blink while the post-swap JS would otherwise
+                # re-apply the class. See render_dash().
+                active = (self.headers.get("X-Active-Tab") or "").strip()
+                self.send_html(200, self.render_dash(active_tab=active))
         elif parsed.path == "/":
             if not self.is_authed():
                 self.redirect("/ui/login")
@@ -856,6 +907,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():
@@ -1043,11 +1101,17 @@ class Handler(http.server.BaseHTTPRequestHandler):
        isn't wiped by the 1 Hz refresh. ``isCollapsed`` is true when
        there's no selection or the caret is a zero-width point; once
        the operator releases / clears the selection polling resumes
-       on the next 1 s tick. -->
+       on the next 1 s tick.
+       ``hx-headers`` sends the current URL hash (the active tab id)
+       as ``X-Active-Tab`` on every refresh so the server can bake
+       ``.active-tab`` into the rendered HTML -- eliminating the
+       visible flicker the post-swap JS-applied class would otherwise
+       cause when the new innerHTML lands without the class. -->
   <div id="dash" hx-get="/admin/dash"
        hx-trigger="load, every 1s [document.getSelection().isCollapsed]"
-       hx-swap="innerHTML">
-    {self.render_dash()}
+       hx-swap="innerHTML"
+       hx-headers='js:{{"X-Active-Tab": (location.hash || "").replace(/^#/, "")}}'>
+    {self.render_dash(active_tab=(self.headers.get("X-Active-Tab") or "").strip())}
   </div>
 
   <!-- Tab activation. Applies an ``active-tab`` class to the
@@ -1087,7 +1151,21 @@ class Handler(http.server.BaseHTTPRequestHandler):
   </script>
 </main></body></html>"""
 
-    def render_dash(self) -> str:
+    def render_dash(self, active_tab: str = "") -> str:
+        # Tab activation is baked into the rendered HTML so the htmx
+        # innerHTML swap doesn't strip `.active-tab` between the
+        # swap and the post-settle JS re-apply. The client sends
+        # the current hash via the ``X-Active-Tab`` header on each
+        # 1 Hz refresh (and on every operator click via the same
+        # script that watches hashchange). Unknown / empty value
+        # defaults to the first tab.
+        _TAB_IDS = ("tab-cached", "tab-streams", "tab-downloads", "tab-misses")
+        if active_tab not in _TAB_IDS:
+            active_tab = _TAB_IDS[0]
+
+        def _active(tab_id: str) -> str:
+            return " active-tab" if tab_id == active_tab else ""
+
         nblobs, nmisses = self.store.counts()
         jobs = self.mgr.list()
         misses = self.store.list_misses()
@@ -1221,13 +1299,17 @@ class Handler(http.server.BaseHTTPRequestHandler):
   <p><small>{nblobs} cached ({used}){full} &middot; {nmisses} pending miss(es)</small></p>
 {tab_style}
   <nav class="tabs"><ul>
-    <li><a href="#tab-cached">Cached ({nblobs})</a></li>
-    <li><a href="#tab-streams">Streams ({nstreams})</a></li>
-    <li><a href="#tab-downloads">Downloads ({njobs})</a></li>
-    <li><a href="#tab-misses">Misses ({nmisses})</a></li>
+    <li><a href="#tab-cached" class="{_active("tab-cached").lstrip()}"
+       >Cached ({nblobs})</a></li>
+    <li><a href="#tab-streams" class="{_active("tab-streams").lstrip()}"
+       >Streams ({nstreams})</a></li>
+    <li><a href="#tab-downloads" class="{_active("tab-downloads").lstrip()}"
+       >Downloads ({njobs})</a></li>
+    <li><a href="#tab-misses" class="{_active("tab-misses").lstrip()}"
+       >Misses ({nmisses})</a></li>
   </ul></nav>
 
-  <section id="tab-cached" class="tab">
+  <section id="tab-cached" class="tab{_active("tab-cached")}">
     <figure><table class="striped">
       <thead><tr>
         <th>URL</th><th>Size</th><th class="num">Hits</th><th class="num">Misses</th>
@@ -1237,7 +1319,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
     </table></figure>
   </section>
 
-  <section id="tab-streams" class="tab">
+  <section id="tab-streams" class="tab{_active("tab-streams")}">
     <figure><table class="striped">
       <thead><tr>
         <th>URL</th><th>Client</th><th>Progress</th><th>Age</th>
@@ -1246,7 +1328,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
     </table></figure>
   </section>
 
-  <section id="tab-downloads" class="tab">
+  <section id="tab-downloads" class="tab{_active("tab-downloads")}">
     <div class="row">
       <small>Auto-fetch workers feeding the cache.</small>
       <form hx-post="/admin/clear" hx-target="#dash" hx-swap="innerHTML" style="margin:0">
@@ -1260,7 +1342,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
     </table></figure>
   </section>
 
-  <section id="tab-misses" class="tab">
+  <section id="tab-misses" class="tab{_active("tab-misses")}">
     <figure><table class="striped">
       <thead><tr>
         <th>URL</th><th class="num">Misses</th><th>Last seen</th><th>Action</th>

{withcache-0.6.0 → withcache-0.6.2}/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,106 @@ 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))
+
+
+class TestDashActiveTabFromHeader(unittest.TestCase):
+    """``GET /admin/dash`` bakes ``.active-tab`` into the rendered HTML
+    based on the ``X-Active-Tab`` request header. The browser sends the
+    current URL hash on every refresh so the htmx innerHTML swap doesn't
+    visibly blink while a post-swap JS would otherwise re-apply the class.
+    """
+
+    def setUp(self):
+        self.httpd, self.store = _start_withcache()
+        self.base = f"http://127.0.0.1:{self.httpd.server_address[1]}"
+
+    def tearDown(self):
+        self.httpd.shutdown()
+        self.httpd.server_close()
+
+    def _dash(self, active_tab=None):
+        req = urllib.request.Request(self.base + "/admin/dash")
+        if active_tab is not None:
+            req.add_header("X-Active-Tab", active_tab)
+        return urllib.request.urlopen(req).read().decode("utf-8")
+
+    def test_default_tab_when_header_missing(self):
+        body = self._dash()
+        # tab-cached is the first tab and the no-header default
+        self.assertIn('<section id="tab-cached" class="tab active-tab">', body)
+        self.assertIn('<section id="tab-streams" class="tab">', body)
+
+    def test_header_picks_the_active_tab(self):
+        body = self._dash("tab-misses")
+        self.assertIn('<section id="tab-misses" class="tab active-tab">', body)
+        self.assertIn('<section id="tab-cached" class="tab">', body)
+
+    def test_unknown_header_value_falls_back_to_first(self):
+        """A hand-crafted X-Active-Tab with a bogus value must not echo
+        into the HTML; the renderer falls back to the first tab."""
+        body = self._dash("tab-totally-not-real")
+        self.assertIn('<section id="tab-cached" class="tab active-tab">', body)
+        self.assertNotIn("tab-totally-not-real", body)
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)