withcache 0.9.0__tar.gz → 0.9.1__tar.gz

{withcache-0.9.0 → withcache-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.9.0
+Version: 0.9.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>

{withcache-0.9.0 → withcache-0.9.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.9.0",
+    .version = "0.9.1",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.9.0 → withcache-0.9.1}/src/withcache/__init__.py

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

{withcache-0.9.0 → withcache-0.9.1}/src/withcache/_api.py

@@ -22,11 +22,9 @@ stay byte-identical:
   the worker with the same credential.
 
 Streaming shape: FastAPI ``StreamingResponse`` with a generator
-that reads chunks from the on-disk blob. The pre-port stdlib
-handler chunked via ``self.wfile.write`` in a loop; the port
-preserves the same 64 KiB read size + the
-:class:`StreamRegistry` progress ticks so the operator dashboard
-shows the same numbers.
+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.
 """
 
 from __future__ import annotations
@@ -34,11 +32,12 @@ from __future__ import annotations
 import base64
 import urllib.parse
 from collections.abc import Iterator
+from typing import Any
 
-from fastapi import FastAPI, Request
-from fastapi.responses import PlainTextResponse, Response, StreamingResponse
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse, PlainTextResponse, Response, StreamingResponse
 
-from .server import CHUNK, StreamRegistry, _oras_tag_moved
+from .server import CHUNK, CatalogState, StreamRegistry, _oras_tag_moved, _serialise_catalog
 
 
 def _decode_blob_origin(path: str, query: str) -> str:
@@ -68,8 +67,7 @@ def _serve_blob(
 
     Returns 400 when the origin URL couldn't be decoded, 404 (with
     miss recording + optional fetch enqueue) on cache miss, or 200
-    + a StreamingResponse on hit. Same status codes and body shapes
-    the pre-port stdlib handler emitted.
+    + a StreamingResponse on hit.
     """
     if not url:
         return PlainTextResponse("missing url\n", status_code=400)
@@ -83,7 +81,6 @@ def _serve_blob(
     if row is not None and _oras_tag_moved(url, row["sha256"]):
         # Tag re-pushed since we cached it: drop the stale bytes so
         # the miss branch below re-fetches the current content.
-        # Same shape as the pre-port handler.
         store.delete_blob(row["key"])
         row = None
 
@@ -180,3 +177,154 @@ def register_api_routes(app: FastAPI) -> None:
         del name
         url = _decode_blob_origin(f"/b/{token}/x", "")
         return _serve_blob(request, url, head_only=True)
+
+    # ---------- Catalog JSON API -----------------------------------------
+    #
+    # Bty consumes the catalog through these endpoints: withcache is the
+    # single source of truth for what images exist. Read is open (mirrors
+    # /blob's LAN-only trust model); writes gate on the same Bearer
+    # pattern nbdmux uses -- an ``Authorization: Bearer <pw>`` header
+    # whose value matches ``$WITHCACHE_ADMIN_PASSWORD``, or a session
+    # cookie for browser-based operators.
+
+    def _bearer_or_session_authed(request: Request) -> None:
+        """Auth dependency for catalog writes.
+
+        - No password configured -> open (single-tenant LAN deploy).
+        - Session cookie present -> OK (browser path).
+        - Matching Bearer token -> OK (service-to-service path;
+          bty reads ``$WITHCACHE_ADMIN_PASSWORD`` and posts it).
+        - Otherwise -> 401.
+        """
+        auth = request.app.state.auth
+        if not auth.enabled:
+            return
+        # Session cookie check -- Starlette's SessionMiddleware
+        # stores the flag under ``withcache_authed`` in
+        # ``request.session``. Mirrors the flag ``_app.py`` sets.
+        if request.session.get("withcache_authed"):
+            return
+        header = request.headers.get("Authorization") or ""
+        if header.startswith("Bearer ") and auth.check_bearer(header[len("Bearer ") :]):
+            return
+        raise HTTPException(status_code=401, detail="auth required")
+
+    @app.get("/catalog")
+    def list_catalog(request: Request) -> JSONResponse:
+        """Return the current catalog as JSON.
+
+        Open route: bty polls this from a sibling container without a
+        session (mirrors the ``/blob`` byte-serving surface's trust
+        model -- LAN-only, no auth on reads). Returns a snapshot of
+        the in-process ``CatalogState.entries`` plus provenance
+        metadata (URL, env pin, fetch timestamps) so clients can
+        detect staleness. No pagination -- the catalog is small
+        (dozens of entries at most).
+        """
+        cs: CatalogState = request.app.state.catalog
+        return JSONResponse(
+            {
+                "url": cs.url,
+                "env_url": cs.env_url,
+                "fetched_at": cs.fetched_at,
+                "last_error": cs.last_error,
+                "entries": [dict(e) for e in cs.entries],
+            }
+        )
+
+    @app.post("/catalog/entries", status_code=201)
+    def add_catalog_entry(
+        body: dict[str, Any],
+        request: Request,
+        _auth: None = Depends(_bearer_or_session_authed),
+    ) -> JSONResponse:
+        """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.
+
+        409 when an entry with the same ``name`` already exists;
+        rejecting on duplicate name (not src) because the display
+        surface keys on name and two rows with the same name would
+        collide on the /ui/catalog table.
+
+        Rejects any unknown top-level key -- the emitter allowlists
+        keys anyway, but failing loud at the API boundary saves the
+        operator from wondering why their ``notes`` field vanished.
+        """
+        allowed = {
+            "name",
+            "src",
+            "resolved_src",
+            "format",
+            "arch",
+            "sha256",
+            "size_bytes",
+            "description",
+        }
+        if not isinstance(body, dict):
+            raise HTTPException(status_code=400, detail="body must be a JSON object")
+        unknown = set(body.keys()) - allowed
+        if unknown:
+            raise HTTPException(
+                status_code=400,
+                detail=f"unknown key(s) {sorted(unknown)}; allowed: {sorted(allowed)}",
+            )
+        name = body.get("name")
+        src = body.get("src")
+        if not isinstance(name, str) or not name.strip():
+            raise HTTPException(status_code=400, detail="name: non-empty string required")
+        if not isinstance(src, str) or not src.strip():
+            raise HTTPException(status_code=400, detail="src: non-empty string required")
+
+        cs: CatalogState = request.app.state.catalog
+        if any(e.get("name") == name for e in cs.entries):
+            raise HTTPException(
+                status_code=409,
+                detail=f"catalog entry with name={name!r} already exists",
+            )
+        entry = {k: v for k, v in body.items() if v is not None and v != ""}
+        cs.entries.append(entry)
+        _persist_catalog(cs)
+        return JSONResponse(entry, status_code=201)
+
+    @app.delete("/catalog/entries", status_code=204)
+    def delete_catalog_entry(
+        request: Request,
+        name: str | None = None,
+        _auth: None = Depends(_bearer_or_session_authed),
+    ) -> Response:
+        """Delete via ``?name=<name>`` query param (URL-safe;
+        avoids path-encoding TOML entry names).
+
+        204 on success. 404 when no entry with that name exists.
+        """
+        if not name or not name.strip():
+            raise HTTPException(status_code=400, detail="name: query param required")
+        cs: CatalogState = request.app.state.catalog
+        original = list(cs.entries)
+        cs.entries = [e for e in cs.entries if e.get("name") != name]
+        if len(cs.entries) == len(original):
+            raise HTTPException(
+                status_code=404,
+                detail=f"no catalog entry with name={name!r}",
+            )
+        _persist_catalog(cs)
+        return Response(status_code=204)
+
+
+def _persist_catalog(cs: CatalogState) -> None:
+    """Write the current in-memory catalog back to
+    ``<data_dir>/catalog.toml`` (when ``persist_path`` is set).
+
+    Silent no-op when ``persist_path`` is ``None`` -- tests inject
+    a stub CatalogState without disk backing and still exercise
+    the in-memory mutation."""
+    if cs.persist_path is None:
+        return
+    from pathlib import Path
+
+    Path(cs.persist_path).parent.mkdir(parents=True, exist_ok=True)
+    Path(cs.persist_path).write_bytes(_serialise_catalog(cs.entries))

{withcache-0.9.0 → withcache-0.9.1}/src/withcache/_app.py

@@ -1,18 +1,16 @@
-"""FastAPI app factory for withcache (v0.9.0 port).
+"""FastAPI app factory for withcache.
 
-Replaces the stdlib ``http.server``-based ``server.py`` request
-handler with a FastAPI application. Mirrors ``nbdmux._app`` in
-shape so the trio's three consoles share one testing + auth +
-chrome pattern; the eventual ``trio-common`` extraction rolls
-these into one library.
+Mirrors :mod:`nbdmux._app` in shape so the trio's three consoles
+share one testing + auth + chrome pattern; the eventual
+``trio-common`` extraction rolls these into one library.
 
 Hosts the operator UI (Cached / Downloads / Misses / Catalog /
 Settings), the byte-serving routes registered via
 :func:`._api.register_api_routes`, the admin form endpoints the
 UI action buttons post to, and the persistent-override Settings
-form for the Warming card's log level. The stdlib ``server.py``
-still holds the daemon entrypoint during the port; ``main()``
-there launches uvicorn against this factory.
+form for the Warming card's log level. :func:`withcache.server.main`
+constructs the runtime objects and launches uvicorn against this
+factory.
 """
 
 from __future__ import annotations
@@ -94,9 +92,8 @@ def create_app(
 
     ``store`` / ``mgr`` / ``streams`` / ``auto_fetch`` let tests
     inject stubs / capture doubles without spawning the real
-    :class:`DownloadManager` worker thread. The daemon path
-    (``server.main`` post-cut-over) passes real instances via a
-    lifespan hook.
+    :class:`DownloadManager` worker thread. :func:`server.main`
+    passes real instances at daemon start.
     """
     data_dir_str = str(data_dir)
     Path(data_dir_str).mkdir(parents=True, exist_ok=True)
@@ -118,9 +115,9 @@ def create_app(
         """
         if run_lifecycle:
             # Kick the startup catalog fetch when the on-disk
-            # persisted catalog is empty. Same shape the pre-port
-            # ``server.main`` had; daemon=True so a slow / broken
-            # upstream doesn't block ``uvicorn.run``'s serve loop.
+            # persisted catalog is empty. daemon=True so a slow /
+            # broken upstream doesn't block ``uvicorn.run``'s serve
+            # loop.
             if not _app.state.catalog.entries:
                 threading.Thread(
                     target=_app.state.catalog.fetch_now,
@@ -146,8 +143,8 @@ def create_app(
     )
 
     # SessionMiddleware signs a cookie with the same shape (name +
-    # HttpOnly + SameSite=Lax + Max-Age) the pre-port stdlib server
-    # emitted, so a rolling deploy doesn't invalidate existing
+    # HttpOnly + SameSite=Lax + Max-Age) as bty + nbdmux so a
+    # rolling deploy across the trio doesn't invalidate existing
     # browser sessions.
     app.add_middleware(
         SessionMiddleware,
@@ -173,11 +170,17 @@ def create_app(
     app.state.mgr = mgr if mgr is not None else DownloadManager(app.state.store)
     app.state.streams = streams if streams is not None else StreamRegistry()
     app.state.auto_fetch = auto_fetch
-    # CatalogState mirrors the pre-port ``server.main`` setup: env pin
-    # wins over on-disk override, on-disk override wins over the shipping
-    # default (nosi's rolling catalog manifest). ``load_persisted`` seeds
-    # entries from the last successful fetch so a restart doesn't wipe
-    # the cache. Tests pass a stub via ``catalog=`` to skip disk IO.
+    # Auth object exposed on app.state so :func:`register_api_routes`
+    # (which owns the JSON catalog write endpoints) can gate them on
+    # ``Authorization: Bearer <pw>``. The UI form + login flow read
+    # ``auth`` from this closure directly, but the register-routes
+    # pattern doesn't have the closure, so app.state is the bridge.
+    app.state.auth = auth
+    # CatalogState resolution: env pin wins over on-disk override,
+    # on-disk override wins over the shipping default (nosi's rolling
+    # catalog manifest). ``load_persisted`` seeds entries from the
+    # last successful fetch so a restart doesn't wipe the cache.
+    # Tests pass a stub via ``catalog=`` to skip disk IO.
     if catalog is not None:
         app.state.catalog = catalog
     else:
@@ -257,7 +260,7 @@ def create_app(
         request.session.clear()
         return RedirectResponse(url="/ui/login", status_code=status.HTTP_303_SEE_OTHER)
 
-    # ---------- Root redirect + placeholder pages -----------------------
+    # ---------- Root redirect + operator UI pages -----------------------
 
     @app.get("/")
     def _root() -> RedirectResponse:
@@ -299,9 +302,8 @@ def create_app(
     @app.get("/ui/catalog", response_class=HTMLResponse)
     def ui_catalog(request: Request, _auth_check: None = Depends(require_ui_auth)) -> HTMLResponse:
         """Catalog view: current URL + env pin + on-disk override
-        provenance, plus the entries table. Read-only for this pass;
-        Refresh + Set URL + Add oras + Delete land in the admin-forms
-        follow-up PR."""
+        provenance, plus the entries table. Refresh + Set URL +
+        Add oras + Delete are on the subnav / row forms."""
         cs: CatalogState = app.state.catalog
         return render(
             "ui/catalog.html",
@@ -399,12 +401,11 @@ def create_app(
 
     # ---------- Admin form endpoints ------------------------------------
     #
-    # Form-encoded siblings of the operator actions the pre-port
-    # ``server.Handler`` dispatched on ``self.ADMIN_POST``. Each 303s
-    # to a sensible /ui/* target so the browser flips to GET and the
-    # dashboard reflects the mutation. Auth-gated -- the JSON /blob
-    # + /b/ byte-serving routes stay open (bty polls from a sibling
-    # container) but writes gate on the session cookie.
+    # Form-encoded operator actions the UI action buttons post to.
+    # Each 303s to a sensible /ui/* target so the browser flips to
+    # GET and the dashboard reflects the mutation. Auth-gated -- the
+    # JSON /blob + /b/ byte-serving routes stay open (bty polls from
+    # a sibling container) but writes gate on the session cookie.
 
     @app.post("/admin/fetch")
     def ui_admin_fetch(
@@ -413,8 +414,8 @@ def create_app(
         _auth_check: None = Depends(require_ui_auth),
     ) -> RedirectResponse:
         """Enqueue a background fetch. Optional ``header`` field
-        carries a curated authorization payload -- format matches
-        the pre-port ``parse_headers`` helper."""
+        carries a curated authorization payload, parsed by
+        :func:`withcache.server.parse_headers`."""
         from .server import parse_headers
 
         u = (url or "").strip()

{withcache-0.9.0 → withcache-0.9.1}/src/withcache/_settings_store.py

@@ -9,10 +9,10 @@ to change without redeploying:
 - :data:`KEY_LOG_LEVEL` -- uvicorn / logging level.
   Env: :data:`ENV_LOG_LEVEL`. Default: ``info``.
 - :data:`KEY_CATALOG_URL_OVERRIDE` is intentionally NOT here --
-  :class:`CatalogState.set_url_override` already persists it to a
-  dedicated ``<data-dir>/catalog_url`` file so it round-trips
-  with the ``env_url`` precedence the pre-port code implemented.
-  Route Settings-page edits through that same helper.
+  :class:`CatalogState.set_url_override` persists it to a dedicated
+  ``<data-dir>/catalog_url`` file the daemon reads at startup, so
+  the Catalog page's Set-URL form remains the single source of
+  truth for that knob.
 
 Resolution order is always **override -> env -> default**, so
 operators can drop an env / systemd-unit config without hunting

{withcache-0.9.0 → withcache-0.9.1}/src/withcache/_templates/ui/cached.html

@@ -21,8 +21,8 @@
 <div class="alert alert-secondary small mb-3">
     Blobs bty flashes through withcache land here. Each row is a
     cached artifact keyed by the sha256 of its canonical source URL.
-    Delete + refresh actions land in a follow-up PR; today the page
-    is read-only.
+    Use the trash button to drop a blob; the next request for that
+    URL will refetch from origin.
 </div>
 {% endblock %}
 

{withcache-0.9.0 → withcache-0.9.1}/src/withcache/_templates/ui/misses.html

@@ -5,8 +5,8 @@
 <div class="alert alert-secondary small mb-3">
     Cache misses recorded on ``/blob`` / ``/b/<b64>/<name>`` requests.
     In auto-fetch mode withcache enqueues a fetch in the background;
-    in curate mode an operator triggers the pull manually. Dismiss +
-    Fetch actions land in the admin-forms follow-up PR.
+    in curate mode an operator triggers the pull manually. Per-row
+    Fetch enqueues the pull; Dismiss removes the recorded miss.
 </div>
 {% endblock %}
 

withcache-0.9.1/src/withcache/client.py

@@ -0,0 +1,237 @@
+"""A tiny client for consuming a withcache cache-host from other tools.
+
+Lets a consumer (e.g. bty) point downloads at withcache without re-implementing
+the ``/b/`` URL scheme, and also lets bty consume withcache's catalog as the
+single source of truth for what images are flashable. Stdlib only, so
+importing it pulls in no third-party dependencies.
+
+    from withcache import client
+
+    # Byte-serving: "use the cache when it's warm, the origin otherwise"
+    url = client.serve_url("http://cache:8081", origin) or origin
+
+    # Catalog: list what's flashable, add a new entry
+    entries = client.list_catalog("http://cache:8081")
+    client.add_catalog_entry(
+        "http://cache:8081",
+        {"name": "debian", "src": "https://.../debian.img.gz"},
+    )
+
+The ``/b/<urlsafe-b64(origin)>/<basename>`` encoding is shared with the shims
+and the server (one definition in :mod:`withcache._shim`), so consumers stay in
+lockstep with the cache-host automatically. Catalog reads are open (LAN-only
+trust model); writes gate on ``$WITHCACHE_ADMIN_PASSWORD`` -- the client picks
+it up from the env var by default so cross-container callers work out of the
+box on the bty deploy (which sets the password on both ends).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from . import _shim
+
+__all__ = [
+    "CATALOG_TIMEOUT",
+    "PROBE_TIMEOUT",
+    "WithcacheError",
+    "add_catalog_entry",
+    "blob_url",
+    "cache_base",
+    "delete_catalog_entry",
+    "is_cached",
+    "list_catalog",
+    "serve_url",
+]
+
+PROBE_TIMEOUT = 3.0  # seconds; never block the caller on a slow/unreachable cache
+CATALOG_TIMEOUT = 5.0  # seconds; catalog reads/writes are small, keep short
+
+
+class WithcacheError(Exception):
+    """Raised on a catalog-plane failure: network, HTTP error, parse error.
+
+    Inherits from :class:`Exception` (not :class:`OSError`) so callers can
+    opt-in to surfacing withcache failures distinctly from generic network
+    errors."""
+
+
+#: Normalize a server value: accepts 'host', 'host:8081', or 'http://host:8081'.
+cache_base = _shim.cache_base
+
+
+def blob_url(server: str, origin: str) -> str:
+    """The cache-host serve URL for ``origin``:
+    ``<server>/b/<urlsafe-b64(origin), unpadded>/<basename>``. The trailing
+    basename is cosmetic (so any downloader names the saved file after the
+    artifact); the cache keys on the decoded origin URL."""
+    return _shim.blob_url(_shim.cache_base(server), origin)
+
+
+def is_cached(
+    server: str,
+    origin: str,
+    timeout: float = PROBE_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> bool:
+    """True if the cache-host already holds ``origin`` (a ``HEAD`` on ``/b/``
+    returns 200). A miss (404), an unreachable host, a timeout, or any error
+    returns False, so a caller can safely fall back to the origin. The HEAD
+    also *warms* an auto-fetch cache-host: the miss is recorded and the
+    background fill enqueued, so a later probe flips to cached.
+
+    ``headers`` (optional) attaches request headers to the HEAD. The
+    cache-host forwards a client-supplied ``Authorization`` into its
+    background-fetch worker, so a consumer that has just minted an OCI
+    bearer (the typical use case: bty resolving an ``oras://`` catalog
+    entry to a ``ghcr.io`` blob URL at import time) can warm the cache
+    against that token-gated origin in one probe. Other entries in
+    ``headers`` round-trip the same way; only ``Authorization`` is
+    forwarded into the fetch on the server side.
+    """
+    req = urllib.request.Request(blob_url(server, origin), method="HEAD")
+    if headers:
+        for k, v in headers.items():
+            req.add_header(k, v)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return bool(resp.status == 200)
+    except urllib.error.HTTPError:
+        return False  # 404 miss (now recorded + enqueued by the cache-host)
+    except (urllib.error.URLError, OSError):
+        return False  # unreachable / timeout -> caller serves the origin itself
+
+
+def serve_url(
+    server: str,
+    origin: str,
+    timeout: float = PROBE_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> str | None:
+    """The cache-host serve URL for ``origin`` if the cache holds it, else
+    ``None`` -- the convenience form of "use the cache when warm":
+
+        url = client.serve_url(cache, origin) or origin
+
+    ``headers`` is passed through to :func:`is_cached` for the HEAD probe;
+    the returned serve URL never carries auth (cached bytes are served
+    without revisiting the origin).
+    """
+    return blob_url(server, origin) if is_cached(server, origin, timeout, headers=headers) else None
+
+
+def _resolve_password(password: str | None) -> str | None:
+    """``password`` if given, else ``$WITHCACHE_ADMIN_PASSWORD``, else ``None``.
+    Empty / whitespace values are treated as unset."""
+    if password:
+        return password
+    env = (os.environ.get("WITHCACHE_ADMIN_PASSWORD") or "").strip()
+    return env or None
+
+
+def _catalog_request(
+    method: str,
+    server: str,
+    path: str,
+    body: dict[str, Any] | None = None,
+    timeout: float = CATALOG_TIMEOUT,
+    password: str | None = None,
+) -> Any:
+    """Shared request wiring for the catalog JSON endpoints.
+
+    ``password`` -> ``Authorization: Bearer <pw>`` on writes. Reads
+    are open on the server side so ``password`` is a no-op there;
+    always sending it is fine (server ignores the header on reads).
+    """
+    url = f"{cache_base(server)}{path}"
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method)
+    if body is not None:
+        req.add_header("Content-Type", "application/json")
+    resolved_pw = _resolve_password(password)
+    if resolved_pw is not None:
+        req.add_header("Authorization", f"Bearer {resolved_pw}")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            if resp.status == 204:
+                return None
+            raw = resp.read()
+            if not raw:
+                return None
+            return json.loads(raw)
+    except urllib.error.HTTPError as exc:
+        try:
+            payload = json.loads(exc.read() or b"{}")
+            detail = payload.get("detail") if isinstance(payload, dict) else None
+        except (json.JSONDecodeError, ValueError):
+            detail = None
+        raise WithcacheError(f"{method} {path} -> HTTP {exc.code}: {detail or exc.reason}") from exc
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise WithcacheError(f"{method} {path} -> {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise WithcacheError(f"{method} {path} -> invalid JSON: {exc}") from exc
+
+
+def list_catalog(
+    server: str,
+    timeout: float = CATALOG_TIMEOUT,
+) -> dict[str, Any]:
+    """Return the catalog snapshot as ``{url, env_url, fetched_at,
+    last_error, entries: [...]}``. Open route: no password needed.
+
+    Raises :class:`WithcacheError` on any failure (network, HTTP,
+    parse). Callers typically want the ``entries`` field only:
+
+        entries = client.list_catalog(server)["entries"]
+    """
+    return _catalog_request("GET", server, "/catalog", timeout=timeout)
+
+
+def add_catalog_entry(
+    server: str,
+    entry: dict[str, Any],
+    *,
+    timeout: float = CATALOG_TIMEOUT,
+    password: str | None = None,
+) -> dict[str, Any]:
+    """POST one entry into the catalog.
+
+    ``entry`` must carry at least ``name`` + ``src``. Optional
+    fields: ``format``, ``arch``, ``sha256``, ``size_bytes``,
+    ``resolved_src``, ``description``.
+
+    Raises :class:`WithcacheError` on any HTTP failure (409 if the
+    entry name already exists; 401 if auth is enabled and no valid
+    password reached the server).
+    """
+    return _catalog_request(
+        "POST", server, "/catalog/entries", body=entry, timeout=timeout, password=password
+    )
+
+
+def delete_catalog_entry(
+    server: str,
+    name: str,
+    *,
+    timeout: float = CATALOG_TIMEOUT,
+    password: str | None = None,
+) -> None:
+    """DELETE the catalog entry with ``name=<name>``. 404 (no such
+    entry) is treated as success so the call is idempotent for the
+    operator's "make sure this is gone" intent, mirroring
+    :func:`nbdmux.client.remove_export`.
+
+    Raises :class:`WithcacheError` on transport failure but NOT on
+    404."""
+    path = f"/catalog/entries?name={urllib.parse.quote(name, safe='')}"
+    try:
+        _catalog_request("DELETE", server, path, timeout=timeout, password=password)
+    except WithcacheError as exc:
+        if "HTTP 404" in str(exc):
+            return
+        raise

{withcache-0.9.0 → withcache-0.9.1}/src/withcache/server.py

@@ -19,8 +19,8 @@ the parts of the daemon that stay stdlib:
   bty flashes against, persisted to
   ``<data-dir>/catalog.toml`` between restarts.
 - Helpers: ``resolve_secret``, ``parse_size``, ``parse_headers``,
-  ``now_iso``, ``_age_human``, ``human_size``, ``_b64e`` /
-  ``_b64d``, ``_serialise_catalog``, ``_oras_tag_moved``.
+  ``now_iso``, ``human_size``, ``_b64e`` / ``_b64d``,
+  ``_serialise_catalog``, ``_oras_tag_moved``.
 - ``main()``: CLI entrypoint that constructs Store + DownloadManager
   and hands them to :func:`withcache._app.create_app`, then boots
   uvicorn. SIGTERM / SIGINT handling is uvicorn's.
@@ -74,18 +74,6 @@ def now_iso() -> str:
     return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-def _age_human(started_at: float, *, now: float | None = None) -> str:
-    """Render seconds-since as a compact ``Ns`` / ``Nm`` / ``Nh`` string for
-    the streams table. ``now`` is injectable so tests don't need
-    monkeypatching ``time.time`` to assert formatting."""
-    elapsed = int(max(0.0, (now if now is not None else time.time()) - started_at))
-    if elapsed < 60:
-        return f"{elapsed}s"
-    if elapsed < 3600:
-        return f"{elapsed // 60}m{elapsed % 60:02d}s"
-    return f"{elapsed // 3600}h{(elapsed % 3600) // 60:02d}m"
-
-
 def human_size(n: int) -> str:
     f = float(n)
     for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
@@ -157,11 +145,21 @@ def _serialise_catalog(entries: list[dict[str, Any]]) -> bytes:
     ``tomli_w`` dep: the schema is flat so a hand-rolled emitter is
     safer than pulling in a write library. Only known scalar keys are
     emitted; unknown keys are dropped (silently) so an operator-added
-    row can't smuggle arbitrary TOML through."""
+    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.
+    """
     out: list[str] = ["version = 1", ""]
     for e in entries:
         out.append("[[images]]")
-        for key in ("name", "src", "format", "arch", "sha256"):
+        for key in ("name", "src", "resolved_src", "format", "arch", "sha256", "description"):
             val = e.get(key)
             if val is None or val == "":
                 continue
@@ -432,6 +430,19 @@ class Auth:
             return False
         return hmac.compare_digest(pw.encode("utf-8"), self.password.encode("utf-8"))
 
+    def check_bearer(self, token: str) -> bool:
+        """Constant-time compare a raw Bearer token against the
+        configured admin password. Used by the JSON control-plane's
+        service-to-service path (bty reads
+        ``$WITHCACHE_ADMIN_PASSWORD`` and sends it as
+        ``Authorization: Bearer <pw>``). Equivalent trust surface
+        to ``check_password`` -- both are password comparisons --
+        so callers can pick whichever channel their transport
+        supports."""
+        if not self.password:
+            return False
+        return hmac.compare_digest(token.encode("utf-8"), self.password.encode("utf-8"))
+
 
 # --------------------------------------------------------------------------
 # Storage

{withcache-0.9.0 → withcache-0.9.1}/tests/test_fastapi_admin_forms.py

@@ -20,8 +20,8 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
 try:
     from fastapi.testclient import TestClient  # noqa: E402
-except (ImportError, RuntimeError):  # pragma: no cover
-    raise unittest.SkipTest("fastapi + httpx not available (port scaffolding deps)") from None
+except ImportError:  # pragma: no cover
+    raise unittest.SkipTest("fastapi not installed") from None
 
 from withcache._app import create_app  # noqa: E402
 from withcache.server import CatalogState  # noqa: E402

{withcache-0.9.0 → withcache-0.9.1}/tests/test_fastapi_blob.py

@@ -23,8 +23,8 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
 try:
     from fastapi.testclient import TestClient  # noqa: E402
-except (ImportError, RuntimeError):  # pragma: no cover
-    raise unittest.SkipTest("fastapi + httpx not available (port scaffolding deps)") from None
+except ImportError:  # pragma: no cover
+    raise unittest.SkipTest("fastapi not installed") from None
 
 from withcache._app import create_app  # noqa: E402
 

withcache-0.9.1/tests/test_fastapi_catalog_api.py

@@ -0,0 +1,249 @@
+"""TestClient tests for the JSON catalog API.
+
+Pins the ``GET /catalog`` + ``POST /catalog/entries`` +
+``DELETE /catalog/entries`` surface that bty consumes as the
+single source of truth for what images are flashable. Mirrors the
+Bearer / session dual-auth pattern nbdmux uses on its write
+routes.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+try:
+    from fastapi.testclient import TestClient  # noqa: E402
+except ImportError:  # pragma: no cover
+    raise unittest.SkipTest("fastapi not installed") from None
+
+from withcache._app import create_app  # noqa: E402
+from withcache.server import CatalogState  # noqa: E402
+
+TEST_PASSWORD = "test-admin-pw"
+TEST_SECRET = b"test-secret-not-for-prod-use-32b_"
+
+
+class _CatalogApiBase(unittest.TestCase):
+    ENABLE_AUTH = False
+
+    def setUp(self) -> None:
+        self._tmpdir = tempfile.mkdtemp()
+        self._saved_pw = os.environ.get("WITHCACHE_ADMIN_PASSWORD")
+        self._saved_cat = os.environ.get("WITHCACHE_CATALOG_URL")
+        if self.ENABLE_AUTH:
+            os.environ["WITHCACHE_ADMIN_PASSWORD"] = TEST_PASSWORD
+        else:
+            os.environ.pop("WITHCACHE_ADMIN_PASSWORD", None)
+        os.environ.pop("WITHCACHE_CATALOG_URL", None)
+
+        self.catalog = CatalogState(
+            url="https://example.invalid/catalog.toml",
+            persist_path=os.path.join(self._tmpdir, "catalog.toml"),
+            env_url="",
+            url_override_path=os.path.join(self._tmpdir, "catalog_url"),
+        )
+
+        def _fake_fetch_now(**_kw: object) -> None:
+            pass
+
+        self.catalog.fetch_now = _fake_fetch_now  # type: ignore[assignment]
+
+        self.app = create_app(
+            data_dir=self._tmpdir,
+            secret_key=TEST_SECRET,
+            catalog=self.catalog,
+        )
+        self.client = TestClient(self.app, follow_redirects=False)
+
+    def tearDown(self) -> None:
+        self.client.close()
+        for key, saved in (
+            ("WITHCACHE_ADMIN_PASSWORD", self._saved_pw),
+            ("WITHCACHE_CATALOG_URL", self._saved_cat),
+        ):
+            if saved is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = saved
+        shutil.rmtree(self._tmpdir, ignore_errors=True)
+
+    def _login(self) -> None:
+        r = self.client.post("/ui/login", data={"password": TEST_PASSWORD}, follow_redirects=False)
+        self.assertEqual(r.status_code, 303, r.text)
+
+
+class ListCatalogTests(_CatalogApiBase):
+    def test_list_empty_returns_metadata_with_empty_entries(self) -> None:
+        r = self.client.get("/catalog")
+        self.assertEqual(r.status_code, 200)
+        body = r.json()
+        self.assertEqual(body["entries"], [])
+        self.assertEqual(body["url"], "https://example.invalid/catalog.toml")
+        self.assertIn("fetched_at", body)
+        self.assertIn("last_error", body)
+
+    def test_list_returns_seeded_entries(self) -> None:
+        self.catalog.entries = [
+            {
+                "name": "demo",
+                "src": "https://example/demo.img.gz",
+                "format": "img.gz",
+                "sha256": "a" * 64,
+                "size_bytes": 1024,
+                "description": "demo image",
+                "resolved_src": "https://example/demo.img.gz",
+            }
+        ]
+        r = self.client.get("/catalog")
+        self.assertEqual(r.status_code, 200)
+        entries = r.json()["entries"]
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(entries[0]["name"], "demo")
+        self.assertEqual(entries[0]["sha256"], "a" * 64)
+        self.assertEqual(entries[0]["description"], "demo image")
+
+
+class AddCatalogEntryTests(_CatalogApiBase):
+    def test_add_minimum_entry(self) -> None:
+        """Only ``name`` + ``src`` are required."""
+        r = self.client.post(
+            "/catalog/entries",
+            json={"name": "demo", "src": "https://example/demo.img.gz"},
+        )
+        self.assertEqual(r.status_code, 201, r.text)
+        body = r.json()
+        self.assertEqual(body["name"], "demo")
+        self.assertEqual(body["src"], "https://example/demo.img.gz")
+        # And it landed in the catalog state.
+        self.assertEqual(len(self.catalog.entries), 1)
+
+    def test_add_full_entry_round_trips_all_fields(self) -> None:
+        r = self.client.post(
+            "/catalog/entries",
+            json={
+                "name": "debian",
+                "src": "https://example/debian.img.gz",
+                "resolved_src": "https://example/debian.img.gz",
+                "format": "img.gz",
+                "arch": "x86_64",
+                "sha256": "b" * 64,
+                "size_bytes": 2048,
+                "description": "Debian sysdev",
+            },
+        )
+        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")
+
+    def test_add_persists_to_disk(self) -> None:
+        self.client.post(
+            "/catalog/entries", json={"name": "demo", "src": "https://example/demo.img.gz"}
+        )
+        toml_path = os.path.join(self._tmpdir, "catalog.toml")
+        self.assertTrue(os.path.exists(toml_path))
+        content = open(toml_path, encoding="utf-8").read()
+        self.assertIn('name = "demo"', content)
+
+    def test_add_rejects_missing_name(self) -> None:
+        r = self.client.post("/catalog/entries", json={"src": "https://example/demo.img.gz"})
+        self.assertEqual(r.status_code, 400)
+
+    def test_add_rejects_missing_src(self) -> None:
+        r = self.client.post("/catalog/entries", json={"name": "demo"})
+        self.assertEqual(r.status_code, 400)
+
+    def test_add_rejects_unknown_field(self) -> None:
+        """Unknown fields are refused at the API boundary so operators
+        catch typos loud (``notes`` → ``description``) instead of
+        watching them silently drop through the emitter."""
+        r = self.client.post(
+            "/catalog/entries",
+            json={"name": "demo", "src": "https://example/x", "notes": "typo"},
+        )
+        self.assertEqual(r.status_code, 400)
+        self.assertIn("notes", r.json()["detail"])
+
+    def test_add_duplicate_name_409s(self) -> None:
+        first = {"name": "demo", "src": "https://example/one.img.gz"}
+        self.client.post("/catalog/entries", json=first)
+        r = self.client.post(
+            "/catalog/entries",
+            json={"name": "demo", "src": "https://example/two.img.gz"},
+        )
+        self.assertEqual(r.status_code, 409)
+
+
+class DeleteCatalogEntryTests(_CatalogApiBase):
+    def test_delete_removes_entry(self) -> None:
+        self.catalog.entries = [{"name": "demo", "src": "https://example/demo.img.gz"}]
+        r = self.client.delete("/catalog/entries?name=demo")
+        self.assertEqual(r.status_code, 204)
+        self.assertEqual(self.catalog.entries, [])
+
+    def test_delete_unknown_returns_404(self) -> None:
+        r = self.client.delete("/catalog/entries?name=missing")
+        self.assertEqual(r.status_code, 404)
+
+    def test_delete_requires_name(self) -> None:
+        r = self.client.delete("/catalog/entries")
+        self.assertEqual(r.status_code, 400)
+
+
+class CatalogApiAuthTests(_CatalogApiBase):
+    ENABLE_AUTH = True
+
+    def test_get_catalog_open_even_with_auth(self) -> None:
+        """Bty polls the catalog from a sibling container without a
+        session; read stays open regardless of auth."""
+        r = self.client.get("/catalog")
+        self.assertEqual(r.status_code, 200)
+
+    def test_add_entry_401_without_auth(self) -> None:
+        r = self.client.post("/catalog/entries", json={"name": "demo", "src": "https://example/x"})
+        self.assertEqual(r.status_code, 401)
+
+    def test_add_entry_200_with_session(self) -> None:
+        self._login()
+        r = self.client.post("/catalog/entries", json={"name": "demo", "src": "https://example/x"})
+        self.assertEqual(r.status_code, 201)
+
+    def test_add_entry_200_with_bearer(self) -> None:
+        """Service-to-service path: bty reads WITHCACHE_ADMIN_PASSWORD
+        from env and sends it as ``Authorization: Bearer <pw>``."""
+        r = self.client.post(
+            "/catalog/entries",
+            json={"name": "demo", "src": "https://example/x"},
+            headers={"Authorization": f"Bearer {TEST_PASSWORD}"},
+        )
+        self.assertEqual(r.status_code, 201)
+
+    def test_add_entry_401_with_bearer_mismatch(self) -> None:
+        r = self.client.post(
+            "/catalog/entries",
+            json={"name": "demo", "src": "https://example/x"},
+            headers={"Authorization": "Bearer wrong-pw"},
+        )
+        self.assertEqual(r.status_code, 401)
+
+    def test_delete_entry_401_without_auth(self) -> None:
+        r = self.client.delete("/catalog/entries?name=demo")
+        self.assertEqual(r.status_code, 401)
+
+    def test_delete_entry_204_with_bearer(self) -> None:
+        self.catalog.entries = [{"name": "demo", "src": "https://example/x"}]
+        r = self.client.delete(
+            "/catalog/entries?name=demo",
+            headers={"Authorization": f"Bearer {TEST_PASSWORD}"},
+        )
+        self.assertEqual(r.status_code, 204)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

{withcache-0.9.0 → withcache-0.9.1}/tests/test_fastapi_scaffold.py

@@ -33,12 +33,8 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
 try:
     from fastapi.testclient import TestClient  # noqa: E402
-except (ImportError, RuntimeError):  # pragma: no cover
-    # ImportError -> fastapi absent; RuntimeError -> starlette's
-    # ``testclient`` raises when httpx isn't installed. Either way,
-    # skip so an unprepped CI runner reports a green skip rather
-    # than a red error.
-    raise unittest.SkipTest("fastapi + httpx not available (port scaffolding deps)") from None
+except ImportError:  # pragma: no cover
+    raise unittest.SkipTest("fastapi not installed") from None
 
 from withcache._app import create_app  # noqa: E402
 

{withcache-0.9.0 → withcache-0.9.1}/tests/test_fastapi_settings_persistence.py

@@ -26,8 +26,8 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
 try:
     from fastapi.testclient import TestClient  # noqa: E402
-except (ImportError, RuntimeError):  # pragma: no cover
-    raise unittest.SkipTest("fastapi + httpx not available (port scaffolding deps)") from None
+except ImportError:  # pragma: no cover
+    raise unittest.SkipTest("fastapi not installed") from None
 
 from withcache import _settings_store  # noqa: E402
 from withcache._app import create_app  # noqa: E402

{withcache-0.9.0 → withcache-0.9.1}/tests/test_fastapi_ui_pages.py

@@ -20,8 +20,8 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
 try:
     from fastapi.testclient import TestClient  # noqa: E402
-except (ImportError, RuntimeError):  # pragma: no cover
-    raise unittest.SkipTest("fastapi + httpx not available (port scaffolding deps)") from None
+except ImportError:  # pragma: no cover
+    raise unittest.SkipTest("fastapi not installed") from None
 
 from withcache._app import create_app  # noqa: E402
 from withcache.server import CatalogState  # noqa: E402

{withcache-0.9.0 → withcache-0.9.1}/tests/test_withcache.py

@@ -20,8 +20,6 @@ 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, server
 
@@ -115,6 +113,15 @@ class TestAuth(unittest.TestCase):
         a = server.Auth(b"k", None)
         self.assertFalse(a.enabled)
         self.assertFalse(a.check_password("anything"))
+        self.assertFalse(a.check_bearer("anything"))
+
+    def test_bearer_check(self):
+        """Bearer path uses constant-time compare against the same
+        admin password ``check_password`` gates the UI login on."""
+        a = server.Auth(b"k", "hunter2")
+        self.assertTrue(a.check_bearer("hunter2"))
+        self.assertFalse(a.check_bearer("nope"))
+        self.assertFalse(a.check_bearer(""))
 
 
 # --------------------------------------------------------------------------
@@ -508,30 +515,6 @@ class TestStreamRegistry(unittest.TestCase):
         self.assertEqual(reg.snapshot(), [])
 
 
-class TestAgeHuman(unittest.TestCase):
-    """``_age_human`` renders elapsed seconds into the compact form the
-    Streams table cell shows. Inject ``now`` so the test doesn't have
-    to monkeypatch ``time.time``."""
-
-    def test_seconds_only(self):
-        self.assertEqual(server._age_human(100.0, now=100.0), "0s")
-        self.assertEqual(server._age_human(100.0, now=159.0), "59s")
-
-    def test_minutes_pad_seconds(self):
-        self.assertEqual(server._age_human(100.0, now=160.0), "1m00s")
-        self.assertEqual(server._age_human(100.0, now=222.0), "2m02s")
-
-    def test_hours_pad_minutes(self):
-        self.assertEqual(server._age_human(0.0, now=3600.0), "1h00m")
-        self.assertEqual(server._age_human(0.0, now=3661.0), "1h01m")
-        self.assertEqual(server._age_human(0.0, now=7320.0), "2h02m")
-
-    def test_negative_clamps_to_zero(self):
-        # Started-at in the future (clock skew, replayed snapshot) renders
-        # as 0s rather than a confusing negative.
-        self.assertEqual(server._age_human(200.0, now=100.0), "0s")
-
-
 # --------------------------------------------------------------------------
 # _shim: URL detection, rewrite, real-tool resolution, env, path-encoding
 # --------------------------------------------------------------------------

withcache-0.9.0/src/withcache/client.py

@@ -1,89 +0,0 @@
-"""A tiny client for consuming a withcache cache-host from other tools.
-
-Lets a consumer (e.g. bty) point downloads at withcache without re-implementing
-the ``/b/`` URL scheme. Stdlib only, so importing it pulls in no third-party
-dependencies.
-
-    from withcache import client
-
-    # "use the cache when it's warm, the origin otherwise"
-    url = client.serve_url("http://cache:8081", origin) or origin
-
-The ``/b/<urlsafe-b64(origin)>/<basename>`` encoding is shared with the shims
-and the server (one definition in :mod:`withcache._shim`), so consumers stay in
-lockstep with the cache-host automatically.
-"""
-
-from __future__ import annotations
-
-import urllib.error
-import urllib.request
-
-from . import _shim
-
-__all__ = ["PROBE_TIMEOUT", "blob_url", "cache_base", "is_cached", "serve_url"]
-
-PROBE_TIMEOUT = 3.0  # seconds; never block the caller on a slow/unreachable cache
-
-#: Normalize a server value: accepts 'host', 'host:8081', or 'http://host:8081'.
-cache_base = _shim.cache_base
-
-
-def blob_url(server: str, origin: str) -> str:
-    """The cache-host serve URL for ``origin``:
-    ``<server>/b/<urlsafe-b64(origin), unpadded>/<basename>``. The trailing
-    basename is cosmetic (so any downloader names the saved file after the
-    artifact); the cache keys on the decoded origin URL."""
-    return _shim.blob_url(_shim.cache_base(server), origin)
-
-
-def is_cached(
-    server: str,
-    origin: str,
-    timeout: float = PROBE_TIMEOUT,
-    headers: dict[str, str] | None = None,
-) -> bool:
-    """True if the cache-host already holds ``origin`` (a ``HEAD`` on ``/b/``
-    returns 200). A miss (404), an unreachable host, a timeout, or any error
-    returns False, so a caller can safely fall back to the origin. The HEAD
-    also *warms* an auto-fetch cache-host: the miss is recorded and the
-    background fill enqueued, so a later probe flips to cached.
-
-    ``headers`` (optional) attaches request headers to the HEAD. The
-    cache-host forwards a client-supplied ``Authorization`` into its
-    background-fetch worker, so a consumer that has just minted an OCI
-    bearer (the typical use case: bty resolving an ``oras://`` catalog
-    entry to a ``ghcr.io`` blob URL at import time) can warm the cache
-    against that token-gated origin in one probe. Other entries in
-    ``headers`` round-trip the same way; only ``Authorization`` is
-    forwarded into the fetch on the server side.
-    """
-    req = urllib.request.Request(blob_url(server, origin), method="HEAD")
-    if headers:
-        for k, v in headers.items():
-            req.add_header(k, v)
-    try:
-        with urllib.request.urlopen(req, timeout=timeout) as resp:
-            return bool(resp.status == 200)
-    except urllib.error.HTTPError:
-        return False  # 404 miss (now recorded + enqueued by the cache-host)
-    except (urllib.error.URLError, OSError):
-        return False  # unreachable / timeout -> caller serves the origin itself
-
-
-def serve_url(
-    server: str,
-    origin: str,
-    timeout: float = PROBE_TIMEOUT,
-    headers: dict[str, str] | None = None,
-) -> str | None:
-    """The cache-host serve URL for ``origin`` if the cache holds it, else
-    ``None`` -- the convenience form of "use the cache when warm":
-
-        url = client.serve_url(cache, origin) or origin
-
-    ``headers`` is passed through to :func:`is_cached` for the HEAD probe;
-    the returned serve URL never carries auth (cached bytes are served
-    without revisiting the origin).
-    """
-    return blob_url(server, origin) if is_cached(server, origin, timeout, headers=headers) else None