withcache 0.8.0__tar.gz → 0.8.2__tar.gz

{withcache-0.8.0 → withcache-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.8.0
+Version: 0.8.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>
@@ -61,7 +61,7 @@ optional **operator-curated** model (`--curate`: a miss queue a human approves).
 
 | Path                          | What it is                                                  |
 |-------------------------------|-------------------------------------------------------------|
-| `src/withcache/server.py`     | The cache-host: blob store + miss table + **background download manager** + operator UI (Pico.css + HTMX) |
+| `src/withcache/server.py`     | The cache-host: blob store + miss table + **background download manager** + operator UI (Bootstrap 5 + Bootstrap Icons + HTMX) |
 | `src/withcache/_shim.py`      | Shared shim core (find URL → probe → rewrite → exec)        |
 | `src/withcache/curlwithcache.py` / `wgetwithcache.py` | The Python `curl` / `wget` shims    |
 | `shim/shim.zig`               | The native shim: one static binary, both tools via `argv[0]` |
@@ -237,11 +237,13 @@ Notes & limits (all degrade gracefully; worst case is "no caching, curl still wo
 
 ## Operator UI
 
-`http://withcache-server:8081/` (Pico.css + HTMX, bundled offline) shows:
+`http://withcache-server:8081/` (Bootstrap 5 + Bootstrap Icons + HTMX, bundled
+offline; matches bty's chrome for a consistent trio) is a five-page dashboard:
+- **Cached** (landing): URL, size, **hits** (times served) and **misses** (times requested before it was cached), SHA-256, fetched-at, each with **Delete** to free space.
+- **Streams**: in-flight stream-through-and-store fetches serving bytes to a client while writing to disk.
+- **Downloads**: live progress bars, `queued/running/completed/cancelled/failed`, **Cancel**, and **Clear finished**. Downloads run in a background worker pool, not in the request, so large pulls never block, modelled on [bty]'s job managers. The subnav Fetch form pre-seeds an artifact before anyone misses it.
 - **Misses**: auto-fetched by default, or (under `--curate`) each with **Download** (queues a background pull) and **Dismiss**.
-- **Downloads**: live progress bars, `queued/running/completed/cancelled/failed`, **Cancel**, and **Clear finished**. Downloads run in a background worker pool, not in the request, so large pulls never block, modelled on [bty]'s job managers.
-- **Cached artifacts**: URL, size, **hits** (times served) and **misses** (times requested before it was cached), SHA-256, fetched-at, each with **Delete** to free space.
-- **Add from URI**: pre-seed an artifact before anyone misses it.
+- **Catalog**: image catalog fetched from a nosi-style `catalog.toml` (URL configurable via `$WITHCACHE_CATALOG_URL` or the subnav Set&fetch input); pre-seed by URL via the "Add image from oras" input.
 
 ## Auth
 

{withcache-0.8.0 → withcache-0.8.2}/README.md

@@ -43,7 +43,7 @@ optional **operator-curated** model (`--curate`: a miss queue a human approves).
 
 | Path                          | What it is                                                  |
 |-------------------------------|-------------------------------------------------------------|
-| `src/withcache/server.py`     | The cache-host: blob store + miss table + **background download manager** + operator UI (Pico.css + HTMX) |
+| `src/withcache/server.py`     | The cache-host: blob store + miss table + **background download manager** + operator UI (Bootstrap 5 + Bootstrap Icons + HTMX) |
 | `src/withcache/_shim.py`      | Shared shim core (find URL → probe → rewrite → exec)        |
 | `src/withcache/curlwithcache.py` / `wgetwithcache.py` | The Python `curl` / `wget` shims    |
 | `shim/shim.zig`               | The native shim: one static binary, both tools via `argv[0]` |
@@ -219,11 +219,13 @@ Notes & limits (all degrade gracefully; worst case is "no caching, curl still wo
 
 ## Operator UI
 
-`http://withcache-server:8081/` (Pico.css + HTMX, bundled offline) shows:
+`http://withcache-server:8081/` (Bootstrap 5 + Bootstrap Icons + HTMX, bundled
+offline; matches bty's chrome for a consistent trio) is a five-page dashboard:
+- **Cached** (landing): URL, size, **hits** (times served) and **misses** (times requested before it was cached), SHA-256, fetched-at, each with **Delete** to free space.
+- **Streams**: in-flight stream-through-and-store fetches serving bytes to a client while writing to disk.
+- **Downloads**: live progress bars, `queued/running/completed/cancelled/failed`, **Cancel**, and **Clear finished**. Downloads run in a background worker pool, not in the request, so large pulls never block, modelled on [bty]'s job managers. The subnav Fetch form pre-seeds an artifact before anyone misses it.
 - **Misses**: auto-fetched by default, or (under `--curate`) each with **Download** (queues a background pull) and **Dismiss**.
-- **Downloads**: live progress bars, `queued/running/completed/cancelled/failed`, **Cancel**, and **Clear finished**. Downloads run in a background worker pool, not in the request, so large pulls never block, modelled on [bty]'s job managers.
-- **Cached artifacts**: URL, size, **hits** (times served) and **misses** (times requested before it was cached), SHA-256, fetched-at, each with **Delete** to free space.
-- **Add from URI**: pre-seed an artifact before anyone misses it.
+- **Catalog**: image catalog fetched from a nosi-style `catalog.toml` (URL configurable via `$WITHCACHE_CATALOG_URL` or the subnav Set&fetch input); pre-seed by URL via the "Add image from oras" input.
 
 ## Auth
 

{withcache-0.8.0 → withcache-0.8.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.8.0",
+    .version = "0.8.2",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.8.0 → withcache-0.8.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.8.0"
+__version__ = "0.8.2"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

{withcache-0.8.0 → withcache-0.8.2}/src/withcache/server.py

@@ -6,7 +6,7 @@ their origin URL. By default a cache miss is auto-fetched: it is recorded in the
 miss table and pulled from origin in the background, so the next request hits
 (the client falls through to origin on the first miss). Run with `--curate` to
 require an operator to approve each pull via a small web UI instead; either way
-you can pre-seed an artifact with the "Add from URI" form.
+you can pre-seed an artifact with the Downloads-page Fetch form.
 
 This is the only component that needs internet egress (and any vendor creds).
 Clients never write to it.
@@ -180,17 +180,18 @@ def _serialise_catalog(entries: list[dict[str, Any]]) -> bytes:
 class CatalogState:
     """Live state of the fetched image catalog.
 
-    withcache does not run a background poller. The catalog is
-    fetched at process start (best-effort, persisted result from
-    the last successful fetch survives a restart), refetched
-    lazily when the dashboard renders and the in-memory copy is
-    older than :data:`CATALOG_CACHE_TTL`, and force-refetched by
-    the operator via the Refresh button (POST /admin/catalog_refresh).
+    withcache does not run a background poller and does not refetch
+    on a TTL. The catalog is fetched at process start (best-effort;
+    a persisted result from the last successful fetch survives a
+    restart) and force-refetched by the operator via the Refresh
+    button on the Catalog page (POST /admin/catalog_refresh); every
+    other render reads whatever is currently in memory.
 
     The raw TOML bytes are persisted to ``<data_dir>/catalog.toml``
-    so a restart doesn't wipe the last known good catalog and the
-    same file can be re-served verbatim to consumers on a future
-    ``GET /catalog.toml`` route.
+    so a restart doesn't wipe the last known good catalog. There is
+    no HTTP route that serves the file back verbatim; consumers
+    resolve entries by name through the dashboard or by reading
+    ``entries`` in-process.
 
     ``env_url`` records the value pinned via ``$WITHCACHE_CATALOG_URL``
     (empty if unset). The operator can override the effective URL at
@@ -1690,13 +1691,16 @@ class Handler(http.server.BaseHTTPRequestHandler):
         subnav_html: str,
         body_html: str,
     ) -> str:
+        brand_cls = "navbar-brand fw-semibold"
+        if nav_active == "cached":
+            brand_cls += " brand-active"
         return f"""{self._head(title)}
 <body class="bg-light">
 <div class="sticky-header">
 <div class="brand-accent"></div>
 <nav class="navbar navbar-expand-md bg-dark navbar-dark py-2">
     <div class="container">
-        <a class="navbar-brand fw-semibold" href="/ui/cached">
+        <a class="{brand_cls}" href="/ui/cached">
             <i class="bi bi-database brand-icon me-1"></i>WITHCACHE
         </a>
         <div class="d-flex flex-grow-1 align-items-center flex-wrap">
@@ -1884,7 +1888,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
             '<input class="form-control form-control-sm" type="url" name="url" '
             'style="width: 22rem;" '
             'placeholder="https://origin/path/artifact.tar.gz" required>'
-            '<button class="btn btn-sm btn-primary" type="submit" title="Add from URI"'
+            '<button class="btn btn-sm btn-primary" type="submit" title="Fetch URI"'
             ">Fetch</button>"
             "</form>"
         )

{withcache-0.8.0 → withcache-0.8.2}/tests/test_withcache.py

@@ -22,6 +22,7 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
 import base64
 import urllib.error
+import urllib.parse
 import urllib.request
 
 from withcache import _shim, client, curlwithcache, server, wgetwithcache
@@ -1062,10 +1063,10 @@ class TestMultiPageNavigation(unittest.TestCase):
                 self.assertIn(f'id="{key}-fragment"', body)
                 self.assertIn('class="nav-btn active"', body)
 
-    def test_downloads_subnav_has_add_from_uri(self):
+    def test_downloads_subnav_has_fetch_form(self):
         body = self._get("/ui/downloads")
         self.assertIn('hx-post="/admin/fetch"', body)
-        self.assertIn("Add from URI", body)
+        self.assertIn(">Fetch</button>", body)
 
     def test_catalog_subnav_has_url_and_oras_forms(self):
         body = self._get("/ui/catalog")
@@ -1088,5 +1089,178 @@ class TestMultiPageNavigation(unittest.TestCase):
         self.assertNotIn("navbar-brand", body)
 
 
+# --------------------------------------------------------------------------
+# /admin/catalog_* -- the four operator-facing catalog control endpoints
+# --------------------------------------------------------------------------
+class _CatalogOrigin(http.server.BaseHTTPRequestHandler):
+    """Serves a fixed valid catalog.toml to catalog_refresh tests."""
+
+    PAYLOAD = (
+        b'[[images]]\nname = "demo"\nsrc = "https://example/demo.img.zst"\n'
+        b'format = "img.zst"\n\n'
+        b'[[images]]\nname = "other"\nsrc = "https://example/other.img.zst"\n'
+    )
+
+    def do_GET(self):
+        if self.path.endswith("/broken.toml"):
+            self.send_response(200)
+            self.send_header("Content-Length", "10")
+            self.end_headers()
+            self.wfile.write(b"not a toml")
+            return
+        self.send_response(200)
+        self.send_header("Content-Type", "application/toml")
+        self.send_header("Content-Length", str(len(self.PAYLOAD)))
+        self.end_headers()
+        self.wfile.write(self.PAYLOAD)
+
+    def log_message(self, format, *args):
+        pass
+
+
+class TestCatalogAdminEndpoints(unittest.TestCase):
+    """Cover the four catalog-admin endpoints
+    (/admin/catalog_refresh, /admin/catalog_set_url,
+    /admin/catalog_add_oras, /admin/catalog_delete_entry).
+
+    Only the shape assertions (form present + subnav layout) were
+    covered before; the wire behaviour -- POST validates, updates
+    state, and 303s back to the Catalog page -- had zero coverage.
+    """
+
+    def setUp(self):
+        self.origin = socketserver.TCPServer(("127.0.0.1", 0), _CatalogOrigin)
+        threading.Thread(target=self.origin.serve_forever, daemon=True).start()
+        origin_port = self.origin.server_address[1]
+        self.catalog_url = f"http://127.0.0.1:{origin_port}/catalog.toml"
+        self.httpd, self.store = _start_withcache()
+        # Re-point the catalog at the local origin so /admin/catalog_refresh
+        # hits something predictable.
+        self.httpd.catalog.url = self.catalog_url
+        self.base = f"http://127.0.0.1:{self.httpd.server_address[1]}"
+
+    def tearDown(self):
+        self.origin.shutdown()
+        self.origin.server_close()
+        self.httpd.shutdown()
+        self.httpd.server_close()
+
+    def _post(self, path, form):
+        body = urllib.parse.urlencode(form).encode()
+        req = urllib.request.Request(
+            self.base + path,
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            method="POST",
+        )
+        return urllib.request.urlopen(req)
+
+    def test_catalog_refresh_populates_entries(self):
+        self.assertEqual(self.httpd.catalog.entries, [])
+        with self._post("/admin/catalog_refresh", {}) as r:
+            self.assertEqual(r.status, 200)
+        names = [e["name"] for e in self.httpd.catalog.entries]
+        self.assertEqual(names, ["demo", "other"])
+        self.assertEqual(self.httpd.catalog.last_error, "")
+
+    def test_catalog_refresh_bad_toml_keeps_previous_entries(self):
+        # Seed the catalog with a known good entry, then re-point at
+        # a broken TOML endpoint and refresh; entries must survive.
+        self.httpd.catalog.entries = [{"name": "keeper", "src": "https://x/y"}]
+        origin_port = self.origin.server_address[1]
+        self.httpd.catalog.url = f"http://127.0.0.1:{origin_port}/broken.toml"
+        with self._post("/admin/catalog_refresh", {}) as r:
+            self.assertEqual(r.status, 200)
+        names = [e["name"] for e in self.httpd.catalog.entries]
+        self.assertEqual(names, ["keeper"])
+        self.assertTrue(self.httpd.catalog.last_error)
+
+    def test_catalog_set_url_persists_override_and_fetches(self):
+        # No env pin, no persist path -> the URL update takes effect
+        # in-process and an immediate fetch fires.
+        with self._post("/admin/catalog_set_url", {"url": self.catalog_url}) as r:
+            self.assertEqual(r.status, 200)
+        self.assertEqual(self.httpd.catalog.url, self.catalog_url)
+        # fetch_now already ran -> entries populated.
+        self.assertEqual([e["name"] for e in self.httpd.catalog.entries], ["demo", "other"])
+
+    def test_catalog_set_url_rejects_empty(self):
+        with self._post("/admin/catalog_set_url", {"url": "  "}) as r:
+            self.assertEqual(r.status, 200)
+        self.assertIn("empty", self.httpd.catalog.last_error)
+
+    def test_catalog_set_url_rejects_non_http_scheme(self):
+        with self._post("/admin/catalog_set_url", {"url": "ftp://x/y"}) as r:
+            self.assertEqual(r.status, 200)
+        self.assertIn("http", self.httpd.catalog.last_error)
+
+    def test_catalog_set_url_rejects_when_env_pinned(self):
+        self.httpd.catalog.env_url = "https://env-pinned/catalog.toml"
+        pinned_url = self.httpd.catalog.url
+        override_attempt = "https://different/catalog.toml"
+        with self._post("/admin/catalog_set_url", {"url": override_attempt}) as r:
+            self.assertEqual(r.status, 200)
+        self.assertIn("pinned", self.httpd.catalog.last_error)
+        # URL was not overridden -- stays at whatever it was before.
+        self.assertEqual(self.httpd.catalog.url, pinned_url)
+
+    def test_catalog_add_oras_rejects_non_oras_url(self):
+        with self._post("/admin/catalog_add_oras", {"url": "https://example/x"}) as r:
+            self.assertEqual(r.status, 200)
+        self.assertIn("oras://", self.httpd.catalog.last_error)
+        self.assertEqual(self.httpd.catalog.entries, [])
+
+    def test_catalog_add_oras_registers_entry_even_when_layer_probe_fails(self):
+        # A well-formed oras URL that will fail the layer-probe fetch
+        # (unreachable registry). The entry still lands per the
+        # add_oras_entry contract; last_info records the reason.
+        oras_url = "oras://127.0.0.1:1/safl/nosi/demo:v1"
+        with self._post("/admin/catalog_add_oras", {"url": oras_url}) as r:
+            self.assertEqual(r.status, 200)
+        entries = self.httpd.catalog.entries
+        self.assertEqual(len(entries), 1, f"expected 1 entry, got {entries!r}")
+        self.assertEqual(entries[0]["src"], oras_url)
+        self.assertEqual(self.httpd.catalog.last_error, "")
+
+    def test_catalog_delete_entry_removes_matching_row(self):
+        self.httpd.catalog.entries = [
+            {"name": "a", "src": "https://x/a"},
+            {"name": "b", "src": "https://x/b"},
+        ]
+        with self._post("/admin/catalog_delete_entry", {"name": "a"}) as r:
+            self.assertEqual(r.status, 200)
+        self.assertEqual([e["name"] for e in self.httpd.catalog.entries], ["b"])
+
+    def test_catalog_delete_entry_unknown_name_is_reported(self):
+        self.httpd.catalog.entries = [{"name": "a", "src": "https://x/a"}]
+        with self._post("/admin/catalog_delete_entry", {"name": "ghost"}) as r:
+            self.assertEqual(r.status, 200)
+        self.assertIn("ghost", self.httpd.catalog.last_error)
+
+    def test_admin_endpoints_require_auth_when_password_set(self):
+        # Fresh httpd with auth enabled.
+        httpd2, _ = _start_withcache()
+        httpd2.auth = server.Auth(b"k", "letmein")
+        base = f"http://127.0.0.1:{httpd2.server_address[1]}"
+        for path in (
+            "/admin/catalog_refresh",
+            "/admin/catalog_set_url",
+            "/admin/catalog_add_oras",
+            "/admin/catalog_delete_entry",
+        ):
+            with self.subTest(path=path):
+                req = urllib.request.Request(
+                    base + path,
+                    data=b"",
+                    headers={"Content-Type": "application/x-www-form-urlencoded"},
+                    method="POST",
+                )
+                with self.assertRaises(urllib.error.HTTPError) as cm:
+                    urllib.request.urlopen(req)
+                self.assertEqual(cm.exception.code, 401)
+        httpd2.shutdown()
+        httpd2.server_close()
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)