withcache 0.6.1__tar.gz → 0.6.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.6.1
+Version: 0.6.3
 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>
@@ -285,6 +285,20 @@ the probe records the miss and, in auto-fetch mode, enqueues the fill, so the
 next call flips to the cache. The encoding is shared with the shims and server,
 so consumers stay in lockstep with the cache-host.
 
+### Pull an `oras://` artifact (oras + client together)
+
+For a registry blob, pair `withcache.oras` (resolve the reference to a blob URL
++ bearer) with `client.serve_url` (prefer the cache when warm). A runnable
+example is in [`examples/pull_oras_blob.py`](examples/pull_oras_blob.py):
+
+```python
+from withcache import client, oras
+
+resolved = oras.resolve_ref("oras://ghcr.io/<owner>/<repo>@sha256:<digest>")
+url, headers = resolved.blob_url, dict(resolved.headers)
+url = client.serve_url(server, url, headers=headers) or url   # cache when warm
+```
+
 ## Tests
 
 ```sh

{withcache-0.6.1 → withcache-0.6.3}/README.md

@@ -267,6 +267,20 @@ the probe records the miss and, in auto-fetch mode, enqueues the fill, so the
 next call flips to the cache. The encoding is shared with the shims and server,
 so consumers stay in lockstep with the cache-host.
 
+### Pull an `oras://` artifact (oras + client together)
+
+For a registry blob, pair `withcache.oras` (resolve the reference to a blob URL
++ bearer) with `client.serve_url` (prefer the cache when warm). A runnable
+example is in [`examples/pull_oras_blob.py`](examples/pull_oras_blob.py):
+
+```python
+from withcache import client, oras
+
+resolved = oras.resolve_ref("oras://ghcr.io/<owner>/<repo>@sha256:<digest>")
+url, headers = resolved.blob_url, dict(resolved.headers)
+url = client.serve_url(server, url, headers=headers) or url   # cache when warm
+```
+
 ## Tests
 
 ```sh

{withcache-0.6.1 → withcache-0.6.3}/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.1",
+    .version = "0.6.3",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.6.1 → withcache-0.6.3}/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.1"
+__version__ = "0.6.3"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

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

@@ -22,6 +22,7 @@ admin password is set, the operator UI is left open (with a startup warning).
 
 import argparse
 import base64
+import contextlib
 import hashlib
 import hmac
 import html
@@ -40,6 +41,7 @@ import urllib.parse
 import urllib.request
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
+from typing import ClassVar
 
 from . import __version__, oras
 
@@ -304,10 +306,8 @@ class Store:
         """Drop a cached artifact (row + bytes). The manual half of eviction."""
         with _DB_WRITE_LOCK, self.conn() as c:
             c.execute("DELETE FROM blobs WHERE key=?", (key,))
-        try:
+        with contextlib.suppress(FileNotFoundError):
             os.remove(self.blob_path(key))
-        except FileNotFoundError:
-            pass
 
     def store_from_origin(
         self,
@@ -471,7 +471,6 @@ class Store:
 # --------------------------------------------------------------------------
 # Background download manager (thread pool; modelled on bty's job managers)
 # --------------------------------------------------------------------------
-JOB_STATES = ("queued", "running", "completed", "cancelled", "failed")
 PENDING_STATES = frozenset(("queued", "running"))
 
 
@@ -757,7 +756,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")
@@ -1004,7 +1011,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
         self.end_headers()
 
     # -- HTML --------------------------------------------------------------
-    STATUS_COLORS = {
+    STATUS_COLORS: ClassVar[dict[str, str]] = {
         "queued": "#888",
         "running": "var(--pico-primary, #0172ad)",
         "completed": "#2e7d32",
@@ -1093,11 +1100,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
@@ -1137,7 +1150,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()
@@ -1271,13 +1298,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>
@@ -1287,7 +1318,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>
@@ -1296,7 +1327,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">
@@ -1310,7 +1341,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.1 → withcache-0.6.3}/tests/test_differential.py

@@ -15,7 +15,7 @@ import unittest
 HERE = os.path.dirname(__file__)
 sys.path.insert(0, os.path.join(HERE, "..", "src"))
 
-from withcache import _shim  # noqa: E402
+from withcache import _shim
 
 SHIM = os.environ.get(
     "WITHCACHE_SHIM", os.path.join(HERE, "..", "shim", "zig-out", "bin", "withcache-shim")

{withcache-0.6.1 → withcache-0.6.3}/tests/test_oras.py

@@ -21,7 +21,7 @@ from unittest.mock import patch
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
-from withcache import oras, server  # noqa: E402
+from withcache import oras, server
 
 # A trimmed-down version of a real nosi manifest -- two layers (the
 # .img.gz and a .sha256 sidecar), one annotation each, OCI media types.
@@ -304,9 +304,11 @@ class TestResolveRef(unittest.TestCase):
         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")
+        with (
+            patch("urllib.request.urlopen", _failing),
+            self.assertRaisesRegex(oras.OrasError, "token fetch failed"),
+        ):
+            oras.resolve_ref("oras://ghcr.io/safl/nosi/debian-sysdev:latest")
 
 
 class TestIsOrasUrl(unittest.TestCase):
@@ -341,9 +343,11 @@ class TestUrlopenRetry(unittest.TestCase):
                 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)
+            with (
+                patch("urllib.request.urlopen", _notfound),
+                self.assertRaises(urllib.error.HTTPError),
+            ):
+                oras._urlopen_retry("https://x/y", timeout=5)
             self.assertEqual(calls["n"], 1)
 
     def test_exhausts_then_reraises(self):
@@ -354,9 +358,11 @@ class TestUrlopenRetry(unittest.TestCase):
                 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)
+            with (
+                patch("urllib.request.urlopen", _down),
+                self.assertRaises(urllib.error.HTTPError),
+            ):
+                oras._urlopen_retry("https://x/y", timeout=5)
             self.assertEqual(calls["n"], oras._RETRY_ATTEMPTS)
 
 

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

@@ -4,7 +4,9 @@ No third-party test deps; src/ is put on the path so the package imports
 without an install.
 """
 
+import contextlib
 import http.server
+import itertools
 import os
 import shutil
 import socket
@@ -18,11 +20,11 @@ import unittest
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
-import base64  # noqa: E402
-import urllib.error  # noqa: E402
-import urllib.request  # noqa: E402
+import base64
+import urllib.error
+import urllib.request
 
-from withcache import _shim, client, curlwithcache, server, wgetwithcache  # noqa: E402
+from withcache import _shim, client, curlwithcache, server, wgetwithcache
 
 
 # --------------------------------------------------------------------------
@@ -187,10 +189,8 @@ class _TruncatingOrigin(http.server.BaseHTTPRequestHandler):
         # close the underlying socket so urllib observes EOF before
         # Content-Length bytes arrive
         self.wfile.flush()
-        try:
+        with contextlib.suppress(OSError):
             self.connection.shutdown(socket.SHUT_RDWR)
-        except OSError:
-            pass
 
     def log_message(self, format, *args):
         pass
@@ -307,10 +307,8 @@ class _ResumableTruncatingOrigin(http.server.BaseHTTPRequestHandler):
             half = full // 2
             self.wfile.write(self.PAYLOAD[:half])
             self.wfile.flush()
-            try:
+            with contextlib.suppress(OSError):
                 self.connection.shutdown(socket.SHUT_RDWR)
-            except OSError:
-                pass
         else:
             # any non-ranged retry serves the whole thing (covers the
             # 200-on-Range fallback path: origin ignored Range, we
@@ -362,7 +360,7 @@ class TestRangeResumeOnTruncation(unittest.TestCase):
         # final report should be the full payload
         self.assertEqual(observed[-1][0], len(_ResumableTruncatingOrigin.PAYLOAD))
         # at no point did the byte counter regress
-        for prev, curr in zip(observed, observed[1:], strict=False):
+        for prev, curr in itertools.pairwise(observed):
             self.assertGreaterEqual(curr[0], prev[0])
         # the resume actually crossed the cut point: at least one
         # progress call lands above the half-mark (otherwise we
@@ -732,7 +730,7 @@ class TestAutoFetchOnMiss(unittest.TestCase):
             urllib.request.urlopen(_shim.blob_url(base, self.origin_url))
 
     def test_miss_schedules_pull_by_default(self):
-        httpd, store = _start_withcache(auto_fetch=True)
+        httpd, _store = _start_withcache(auto_fetch=True)
         try:
             self._miss(httpd)
             # the miss enqueued a background pull, no operator needed
@@ -1023,5 +1021,45 @@ class TestOrasTagRevalidation(unittest.TestCase):
         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)