withcache 0.13.0__tar.gz → 0.13.1__tar.gz

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

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

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

{withcache-0.13.0 → withcache-0.13.1}/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

{withcache-0.13.0 → withcache-0.13.1}/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.1}/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."""

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

@@ -1053,9 +1053,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.1}/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)