withcache 0.13.0__tar.gz → 0.13.2__tar.gz

{withcache-0.13.0 → withcache-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.13.0
+Version: 0.13.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>
@@ -68,14 +68,16 @@ disk.
 
 | Path                          | What it is                                                  |
 |-------------------------------|-------------------------------------------------------------|
-| `src/withcache/server.py`     | The cache-host: blob store + miss table + **background download manager** + operator UI (Bootstrap 5 + Bootstrap Icons + HTMX) |
+| `src/withcache/server.py`     | The cache-host: blob store + miss table + **background download manager** + events log |
+| `src/withcache/_app.py`       | FastAPI app factory + operator UI wiring (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]` |
 | `deploy/Containerfile`, `deploy/compose.yml` | Single Podman/Docker host deploy             |
 
-The cache-host and the Python shims are **stdlib-only** (no third-party runtime
-deps); the native shim is a dependency-free static binary.
+The cache-host runs on FastAPI + Jinja + Bootstrap (matching bty +
+nbdmux for one trio-consistent chrome); the shims (Python and
+native) are dependency-free so they drop into any environment.
 
 ## Install
 
@@ -245,11 +247,11 @@ Notes & limits (all degrade gracefully; worst case is "no caching, curl still wo
 
 `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.
-- **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.
+- **Dashboard** (landing): catalog + cache + activity summary, health checklist, and the last N audit events.
+- **Catalog**: image catalog fetched from a nosi-style `catalog.toml` (URL configured on Settings > Catalog source). Add entries via the subnav's inline "Add ORAS" / "Add HTTPS" forms or "Fetch default" button, then **Download** each entry. Rows carry hits, size, download progress (live), and cached/failed pills.
 - **Misses**: URLs clients asked for that aren't downloaded yet. Each with **Fetch** (promotes to a catalog entry AND downloads it) and **Dismiss** (forget 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" or "Add HTTPS entry" forms, then **Download** each entry.
-- **Settings**: identity + storage paths + catalog source + logging (uvicorn level) + auth.
+- **Events**: append-only audit log with a free-text filter and per-page pagination. Failure rows carry an ack button; the dashboard's Health tripwire flags unacknowledged failures.
+- **Settings**: identity + storage paths + catalog source (editable) + logging (uvicorn level) + auth.
 
 ## Auth
 

{withcache-0.13.0 → withcache-0.13.2}/README.md

@@ -45,14 +45,16 @@ disk.
 
 | Path                          | What it is                                                  |
 |-------------------------------|-------------------------------------------------------------|
-| `src/withcache/server.py`     | The cache-host: blob store + miss table + **background download manager** + operator UI (Bootstrap 5 + Bootstrap Icons + HTMX) |
+| `src/withcache/server.py`     | The cache-host: blob store + miss table + **background download manager** + events log |
+| `src/withcache/_app.py`       | FastAPI app factory + operator UI wiring (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]` |
 | `deploy/Containerfile`, `deploy/compose.yml` | Single Podman/Docker host deploy             |
 
-The cache-host and the Python shims are **stdlib-only** (no third-party runtime
-deps); the native shim is a dependency-free static binary.
+The cache-host runs on FastAPI + Jinja + Bootstrap (matching bty +
+nbdmux for one trio-consistent chrome); the shims (Python and
+native) are dependency-free so they drop into any environment.
 
 ## Install
 
@@ -222,11 +224,11 @@ Notes & limits (all degrade gracefully; worst case is "no caching, curl still wo
 
 `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.
-- **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.
+- **Dashboard** (landing): catalog + cache + activity summary, health checklist, and the last N audit events.
+- **Catalog**: image catalog fetched from a nosi-style `catalog.toml` (URL configured on Settings > Catalog source). Add entries via the subnav's inline "Add ORAS" / "Add HTTPS" forms or "Fetch default" button, then **Download** each entry. Rows carry hits, size, download progress (live), and cached/failed pills.
 - **Misses**: URLs clients asked for that aren't downloaded yet. Each with **Fetch** (promotes to a catalog entry AND downloads it) and **Dismiss** (forget 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" or "Add HTTPS entry" forms, then **Download** each entry.
-- **Settings**: identity + storage paths + catalog source + logging (uvicorn level) + auth.
+- **Events**: append-only audit log with a free-text filter and per-page pagination. Failure rows carry an ack button; the dashboard's Health tripwire flags unacknowledged failures.
+- **Settings**: identity + storage paths + catalog source (editable) + logging (uvicorn level) + auth.
 
 ## Auth
 

{withcache-0.13.0 → withcache-0.13.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.13.0",
+    .version = "0.13.2",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.13.0 → withcache-0.13.2}/src/withcache/__init__.py

@@ -22,6 +22,6 @@ inherit the framework floor.
 from . import oras
 from .client import blob_url, cache_base, is_cached, serve_url
 
-__version__ = "0.13.0"
+__version__ = "0.13.2"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

{withcache-0.13.0 → withcache-0.13.2}/src/withcache/_api.py

@@ -22,9 +22,11 @@ v0.11.0) promotes a missed URL to a catalog entry + enqueues the
 Download in one click.
 
 Streaming shape: FastAPI ``StreamingResponse`` with a generator
-that reads chunks from the on-disk blob at 64 KiB reads;
-:class:`StreamRegistry` ticks progress per chunk so the operator
-Downloads page shows in-flight transfers as they run.
+that reads chunks from the on-disk blob at 64 KiB reads. The
+Downloads-page real-time progress tracker was retired in v0.12.0
+along with that page; per-entry download progress now folds into
+the Catalog page's Downloaded column, populated from the
+DownloadManager's job list directly.
 """
 
 from __future__ import annotations
@@ -254,9 +256,19 @@ def register_api_routes(app: FastAPI) -> None:
         """Insert one catalog entry.
 
         Body: ``{"name": "...", "src": "...", "format?", "arch?",
-        "sha256?", "size_bytes?", "resolved_src?", "description?"}``.
-        Only ``src`` is required; every other field is optional and
-        gets persisted through the ``catalog.toml`` round-trip.
+        "sha256?", "size_bytes?", "resolved_src?", "description?",
+        "netboot_ref?"}``. Only ``src`` is required; every other
+        field is optional and gets persisted through the
+        ``catalog.toml`` round-trip.
+
+        ``netboot_ref`` names another catalog entry (by ``name``)
+        whose bytes are a nosi netboot bundle (vmlinuz + initrd +
+        manifest) that nbdmux extracts at warm time so bty can
+        ramboot the image using its own kernel. Present iff the
+        entry is a disk image that has a matching netboot bundle;
+        the bundle entry itself never carries a ``netboot_ref``.
+        Withcache does not validate that the referenced entry
+        exists -- the sibling may be added in either order.
 
         409 when an entry with the same ``name`` already exists;
         rejecting on duplicate name (not src) because the display
@@ -276,6 +288,7 @@ def register_api_routes(app: FastAPI) -> None:
             "sha256",
             "size_bytes",
             "description",
+            "netboot_ref",
         }
         if not isinstance(body, dict):
             raise HTTPException(status_code=400, detail="body must be a JSON object")

{withcache-0.13.0 → withcache-0.13.2}/src/withcache/_app.py

@@ -20,7 +20,7 @@ import hashlib
 import os
 import sys
 import threading
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator
 from pathlib import Path
 from typing import Any
 
@@ -108,7 +108,7 @@ def create_app(
     jinja = _build_jinja(_TEMPLATES_DIR)
 
     @contextlib.asynccontextmanager
-    async def _lifespan(_app: FastAPI) -> AsyncIterator[None]:
+    async def _lifespan(_app: FastAPI) -> AsyncGenerator[None]:
         """Start-of-request-cycle wiring for the daemon path.
 
         Fires only when ``run_lifecycle=True`` (``server.main`` boots

{withcache-0.13.0 → withcache-0.13.2}/src/withcache/client.py

@@ -45,6 +45,7 @@ __all__ = [
     "cache_base",
     "delete_catalog_entry",
     "is_cached",
+    "is_healthy",
     "list_catalog",
     "serve_url",
 ]
@@ -121,6 +122,27 @@ def serve_url(
     return blob_url(server, origin) if is_cached(server, origin, timeout, headers=headers) else None
 
 
+def is_healthy(
+    server: str = "http://localhost:8081",
+    timeout: float = PROBE_TIMEOUT,
+) -> bool:
+    """True iff ``GET /healthz`` returns 200. Suitable for a startup
+    probe / reachability pill on a consumer's Settings page.
+
+    Bypasses :func:`_catalog_request` deliberately: the healthz body
+    is small JSON but we don't inspect it -- the status code is the
+    whole signal. Any transport / HTTP / OS failure returns
+    ``False`` so callers can treat a False as "not reachable" without
+    having to catch a family of exceptions.
+    """
+    url = f"{cache_base(server)}/healthz"
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:  # noqa: S310
+            return bool(resp.status == 200)
+    except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError, OSError):
+        return False
+
+
 def _resolve_password(password: str | None) -> str | None:
     """``password`` if given, else ``$WITHCACHE_ADMIN_PASSWORD``, else ``None``.
     Empty / whitespace values are treated as unset."""
@@ -199,7 +221,10 @@ def add_catalog_entry(
 
     ``entry`` must carry at least ``name`` + ``src``. Optional
     fields: ``format``, ``arch``, ``sha256``, ``size_bytes``,
-    ``resolved_src``, ``description``.
+    ``resolved_src``, ``description``, ``netboot_ref`` (name of
+    a sibling entry carrying the matching nosi netboot bundle;
+    consumed by nbdmux to serve vmlinuz + initrd alongside the
+    disk-image export).
 
     Raises :class:`WithcacheError` on any HTTP failure (409 if the
     entry name already exists; 401 if auth is enabled and no valid

{withcache-0.13.0 → withcache-0.13.2}/src/withcache/server.py

@@ -147,18 +147,31 @@ def _serialise_catalog(entries: list[dict[str, Any]]) -> bytes:
     row can't smuggle arbitrary TOML through.
 
     Scalar keys emitted: ``name``, ``src``, ``resolved_src``,
-    ``format``, ``arch``, ``sha256``, ``description``. Integer:
-    ``size_bytes``. ``resolved_src`` is the canonical fetch URL
-    (for ``oras://`` refs; equal to ``src`` for plain HTTPS);
-    bty needs it to render iPXE flash chains against the byte
-    URL directly. ``description`` is operator-supplied prose so
-    the /ui/images page has something better than the URL to
-    display.
+    ``format``, ``arch``, ``sha256``, ``description``,
+    ``netboot_ref``. Integer: ``size_bytes``. ``resolved_src`` is
+    the canonical fetch URL (for ``oras://`` refs; equal to
+    ``src`` for plain HTTPS); bty needs it to render iPXE flash
+    chains against the byte URL directly. ``description`` is
+    operator-supplied prose so the /ui/images page has something
+    better than the URL to display. ``netboot_ref`` names a
+    sibling catalog entry carrying the matching nosi netboot
+    bundle (kernel + initrd) so nbdmux can pair the disk image
+    with its own kernel at warm time; see the ``add_catalog_entry``
+    docstring in ``_api.py`` for the pairing story.
     """
     out: list[str] = ["version = 1", ""]
     for e in entries:
         out.append("[[images]]")
-        for key in ("name", "src", "resolved_src", "format", "arch", "sha256", "description"):
+        for key in (
+            "name",
+            "src",
+            "resolved_src",
+            "format",
+            "arch",
+            "sha256",
+            "description",
+            "netboot_ref",
+        ):
             val = e.get(key)
             if val is None or val == "":
                 continue
@@ -1053,9 +1066,10 @@ def main():
     mgr = DownloadManager(store, workers=args.workers)
     auth_password = os.environ.get("WITHCACHE_ADMIN_PASSWORD")
 
-    # Since v0.10.0 there is no auto-fetch on miss: the operator
-    # hits Download on /ui/catalog to enqueue a fetch. The daemon
-    # is always in "curate" mode; the --curate flag went with it.
+    # Withcache is operator-populated: cache misses return 404 (v0.10.0+)
+    # and the operator hits Download on /ui/catalog to enqueue a fetch.
+    # The v0.12.0 UI consolidation folded Cached + Downloads into the
+    # Catalog page's per-row status column and progress bar.
     print(
         f"withcache cache-host on http://{args.host}:{args.port}  "
         f"(data={store.data_dir}, keep_query={args.keep_query}, workers={args.workers}, "

{withcache-0.13.0 → withcache-0.13.2}/tests/test_fastapi_catalog_api.py

@@ -167,12 +167,28 @@ class AddCatalogEntryTests(_CatalogApiBase):
                 "sha256": "b" * 64,
                 "size_bytes": 2048,
                 "description": "Debian sysdev",
+                "netboot_ref": "debian-netboot",
             },
         )
         self.assertEqual(r.status_code, 201, r.text)
         stored = self.catalog.entries[0]
         self.assertEqual(stored["description"], "Debian sysdev")
         self.assertEqual(stored["resolved_src"], "https://example/debian.img.gz")
+        self.assertEqual(stored["netboot_ref"], "debian-netboot")
+
+    def test_netboot_ref_persists_through_toml_round_trip(self) -> None:
+        """netboot_ref must survive the catalog.toml write-then-reload."""
+        self.client.post(
+            "/catalog/entries",
+            json={
+                "name": "debian",
+                "src": "https://example/debian.img.gz",
+                "netboot_ref": "debian-netboot",
+            },
+        )
+        toml_path = os.path.join(self._tmpdir, "catalog.toml")
+        content = open(toml_path, encoding="utf-8").read()
+        self.assertIn('netboot_ref = "debian-netboot"', content)
 
     def test_add_persists_to_disk(self) -> None:
         self.client.post(

{withcache-0.13.0 → withcache-0.13.2}/tests/test_withcache.py

@@ -967,5 +967,71 @@ class TestHumanSize(unittest.TestCase):
         self.assertIn("GiB", server.human_size(3 * 1024 * 1024 * 1024))
 
 
+# --------------------------------------------------------------------------
+# client.is_healthy: GET /healthz reachability probe consumed by bty's
+# Settings pill so a red URL is caught at render time instead of on first
+# flash.
+# --------------------------------------------------------------------------
+class _HealthzOK(http.server.BaseHTTPRequestHandler):
+    def do_GET(self):
+        if self.path == "/healthz":
+            body = b'{"status":"ok"}'
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def log_message(self, format, *args):
+        pass
+
+
+class _HealthzFail(http.server.BaseHTTPRequestHandler):
+    def do_GET(self):
+        self.send_response(503)
+        self.end_headers()
+
+    def log_message(self, format, *args):
+        pass
+
+
+class TestIsHealthy(unittest.TestCase):
+    def _serve(self, handler_cls):
+        httpd = socketserver.TCPServer(("127.0.0.1", 0), handler_cls)
+        port = httpd.server_address[1]
+        t = threading.Thread(target=httpd.serve_forever, daemon=True)
+        t.start()
+        return httpd, port
+
+    def test_is_healthy_true_on_200(self):
+        from withcache import client
+
+        httpd, port = self._serve(_HealthzOK)
+        try:
+            self.assertTrue(client.is_healthy(f"http://127.0.0.1:{port}", timeout=2.0))
+        finally:
+            httpd.shutdown()
+            httpd.server_close()
+
+    def test_is_healthy_false_on_non_2xx(self):
+        from withcache import client
+
+        httpd, port = self._serve(_HealthzFail)
+        try:
+            self.assertFalse(client.is_healthy(f"http://127.0.0.1:{port}", timeout=2.0))
+        finally:
+            httpd.shutdown()
+            httpd.server_close()
+
+    def test_is_healthy_false_when_unreachable(self):
+        from withcache import client
+
+        # 127.0.0.1:1 -- reserved and closed on any sane host.
+        self.assertFalse(client.is_healthy("http://127.0.0.1:1", timeout=0.5))
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)