withcache 0.6.5__tar.gz → 0.7.1__tar.gz

{withcache-0.6.5 → withcache-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.6.5
+Version: 0.7.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>
@@ -13,7 +13,7 @@ Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: System :: Archiving :: Mirroring
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 
 # withcache

{withcache-0.6.5 → withcache-0.7.1}/pyproject.toml

@@ -7,7 +7,7 @@ name = "withcache"
 dynamic = ["version"]  # single source of truth: src/withcache/__init__.py:__version__
 description = "Operator-curated, URL-keyed artifact cache for a small lab (CUDA/ROCm/DOCA/firmware)"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = { text = "BSD-3-Clause" }
 authors = [{ name = "Simon A. F. Lund", email = "safl@safl.dk" }]
 keywords = ["cache", "artifacts", "cuda", "rocm", "doca", "firmware", "lab"]
@@ -45,7 +45,7 @@ include = ["src/withcache", "shim", "README.md", "LICENSE", "deploy", "tests"]
 
 [tool.ruff]
 line-length = 100
-target-version = "py310"
+target-version = "py311"
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "UP", "B"]

{withcache-0.6.5 → withcache-0.7.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.6.5",
+    .version = "0.7.1",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.6.5 → withcache-0.7.1}/src/withcache/__init__.py

@@ -17,6 +17,6 @@ All modules are stdlib-only and self-contained.
 from . import oras
 from .client import blob_url, cache_base, is_cached, serve_url
 
-__version__ = "0.6.5"
+__version__ = "0.7.1"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

{withcache-0.6.5 → withcache-0.7.1}/src/withcache/server.py

@@ -37,11 +37,13 @@ import socketserver
 import sqlite3
 import threading
 import time
+import tomllib
+import urllib.error
 import urllib.parse
 import urllib.request
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from typing import ClassVar
+from datetime import UTC, datetime
+from typing import Any, ClassVar
 
 from . import __version__, oras
 
@@ -70,7 +72,7 @@ _DB_WRITE_LOCK = threading.Lock()
 
 
 def now_iso() -> str:
-    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
 def _age_human(started_at: float, *, now: float | None = None) -> str:
@@ -147,6 +149,84 @@ def resolve_secret(data_dir: str) -> bytes:
     return secret
 
 
+DEFAULT_CATALOG_URL = "https://github.com/safl/nosi/releases/latest/download/catalog.toml"
+
+
+@dataclass
+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).
+
+    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.
+    """
+
+    url: str
+    persist_path: str
+    entries: list[dict[str, Any]] = field(default_factory=list)
+    fetched_at: str = ""
+    last_error: str = ""
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def load_persisted(self) -> None:
+        """Best-effort: seed ``entries`` + ``fetched_at`` from the on-disk
+        ``catalog.toml`` if it exists. Never raises; a corrupt or missing
+        file leaves the state empty so the operator sees the "not
+        fetched yet" hint in the dashboard."""
+        if not os.path.isfile(self.persist_path):
+            return
+        try:
+            with open(self.persist_path, "rb") as f:
+                raw = f.read()
+            parsed = tomllib.loads(raw.decode("utf-8"))
+            mtime = os.path.getmtime(self.persist_path)
+            self.entries = list(parsed.get("images") or [])
+            self.fetched_at = datetime.fromtimestamp(mtime, UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+        except (OSError, ValueError, UnicodeDecodeError, tomllib.TOMLDecodeError) as e:
+            self.last_error = f"failed to load {self.persist_path}: {e}"
+
+    def fetch_now(self, *, timeout: float = 15.0) -> None:
+        """Fetch the catalog URL, parse, persist raw bytes, populate
+        ``entries``. On failure the previously-cached entries remain;
+        the error is recorded so the tab can surface it. Single-writer
+        via ``self._lock`` so a burst of clicks doesn't double-fetch."""
+        with self._lock:
+            try:
+                req = urllib.request.Request(self.url, headers={"User-Agent": USER_AGENT})
+                with urllib.request.urlopen(req, timeout=timeout) as resp:
+                    raw = resp.read()
+                # Validate before persisting -- a 500 from upstream that
+                # returns HTML must not clobber a previously-good
+                # catalog.toml on disk.
+                parsed = tomllib.loads(raw.decode("utf-8"))
+                entries = list(parsed.get("images") or [])
+                # Atomic write: tempfile + rename so a crash mid-write
+                # never leaves a half-written catalog.toml.
+                tmp = self.persist_path + ".tmp"
+                with open(tmp, "wb") as f:
+                    f.write(raw)
+                os.replace(tmp, self.persist_path)
+                self.entries = entries
+                self.fetched_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+                self.last_error = ""
+            except (
+                urllib.error.URLError,
+                OSError,
+                ValueError,
+                UnicodeDecodeError,
+                tomllib.TOMLDecodeError,
+            ) as e:
+                self.last_error = str(e)
+
+
 class Auth:
     COOKIE = "withcache-token"
     MAX_AGE = 7 * 24 * 3600  # cookie lifetime, seconds
@@ -745,6 +825,10 @@ class Handler(http.server.BaseHTTPRequestHandler):
     def streams(self) -> StreamRegistry:
         return self.server.streams  # type: ignore[attr-defined]
 
+    @property
+    def catalog(self) -> CatalogState:
+        return self.server.catalog  # type: ignore[attr-defined]
+
     def log_message(self, format, *args):  # quieter, single-line
         print(f"{self.address_string()} - {format % args}", flush=True)
 
@@ -793,6 +877,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
         "/admin/delete",
         "/admin/cancel",
         "/admin/clear",
+        "/admin/catalog_refresh",
     )
 
     def do_POST(self):
@@ -820,6 +905,8 @@ class Handler(http.server.BaseHTTPRequestHandler):
                     self.mgr.cancel(int(jid))
             elif parsed.path == "/admin/clear":
                 self.mgr.clear_finished()
+            elif parsed.path == "/admin/catalog_refresh":
+                self.catalog.fetch_now()
             self.respond_admin()
         else:
             self.send_text(404, "not found\n")
@@ -1049,6 +1136,13 @@ class Handler(http.server.BaseHTTPRequestHandler):
     _PRIMARY_RGB = "143, 27, 113"
 
     def _head(self, title: str) -> str:
+        """Emit the shared page prelude: Bootstrap + icons + htmx +
+        the full bty-family chrome CSS. Every service (bty, withcache,
+        nbdmux) uses this same block; the only per-service knob is the
+        primary hue (``--bs-primary`` and the derived button /
+        rgba() variants). See bty's ``_layout.html`` for the origin
+        of these class names -- kept identical here so operators
+        moving between consoles see one visual grammar."""
         primary = self._PRIMARY_HEX
         hover = self._PRIMARY_HOVER
         rgb = self._PRIMARY_RGB
@@ -1060,9 +1154,11 @@ class Handler(http.server.BaseHTTPRequestHandler):
 <link rel="stylesheet" href="/static/bootstrap-icons.min.css">
 <script src="/static/htmx.min.js"></script>
 <style>
-  /* Bootstrap 5 exposes --bs-primary + a matching -rgb triplet
-     used for translucent variants (alerts, focus rings, .bg-*-
-     subtle). Overriding both here re-tints every stock component
+  /* Palette anchor for the three-service trio (bty navy,
+     withcache dark-magenta, nbdmux magenta). Bootstrap 5
+     exposes --bs-primary + a matching -rgb triplet used for
+     translucent variants (alerts, focus rings, .bg-*-subtle).
+     Overriding both here re-tints every stock component
      without patching bootstrap.min.css. */
   :root {{
     --bs-primary: {primary};
@@ -1070,51 +1166,254 @@ class Handler(http.server.BaseHTTPRequestHandler):
     --bs-link-color: {primary};
     --bs-link-hover-color: {hover};
   }}
-  .btn-primary {{ --bs-btn-bg: {primary}; --bs-btn-border-color: {primary};
-                 --bs-btn-hover-bg: {hover}; --bs-btn-hover-border-color: {hover};
-                 --bs-btn-active-bg: {hover}; --bs-btn-active-border-color: {hover}; }}
+  .btn-primary {{
+    --bs-btn-bg: {primary};
+    --bs-btn-border-color: {primary};
+    --bs-btn-hover-bg: {hover};
+    --bs-btn-hover-border-color: {hover};
+    --bs-btn-active-bg: {hover};
+    --bs-btn-active-border-color: {hover};
+  }}
   .bg-primary {{ --bs-bg-opacity: 1; background-color: {primary} !important; }}
   .text-primary {{ --bs-text-opacity: 1; color: {primary} !important; }}
   .border-primary {{ --bs-border-opacity: 1; border-color: {primary} !important; }}
-  /* Brand strip: navy -> dark-magenta -> magenta gradient shared
-     across bty (navy), withcache (dark-magenta) and nbdmux
-     (magenta) so the trio reads as one product family from any
-     of the three consoles. */
-  .brand-accent {{ height: 3px;
-    background: linear-gradient(90deg, #0d3585 0%, #8f1b71 50%, #d63384 100%); }}
+  /* Brand strip: a thin gradient accent above the navbar.
+     Stable across themes; defined inline rather than in
+     bootstrap.min.css so it renders even when the CSS load
+     races the initial paint. Shared navy -> dark-magenta ->
+     magenta gradient across bty (navy), withcache
+     (dark-magenta) and nbdmux (magenta) so the trio reads as
+     one product family from any of the three consoles. */
+  .brand-accent {{
+    height: 3px;
+    background: linear-gradient(90deg, #0d3585 0%, #8f1b71 50%, #d63384 100%);
+  }}
+  /* The accent + navbar + sub-nav pin to the top as one unit so
+     the sub-nav jump links stay visible while scrolling. */
+  .sticky-header {{
+    position: sticky;
+    top: 0;
+    z-index: 1030;
+  }}
+  /* In-page ``#anchor`` jumps (the sub-nav tab pills) land below
+     the sticky header instead of under it. */
+  html {{
+    scroll-padding-top: 6.5rem;
+    scroll-behavior: smooth;
+  }}
+  /* Brand pill keeps the same padding + radius everywhere; the
+     ``brand-active`` variant lights up on the home page so the
+     brand doubles as a Home indicator. */
+  .navbar-brand {{
+    border-radius: 0.5rem;
+    padding-left: 0.6rem;
+    padding-right: 0.6rem;
+    margin-right: 0.25rem;
+    transition: background-color 0.15s;
+  }}
+  .navbar-brand.brand-active {{
+    background-color: rgba({rgb}, 0.85);
+  }}
+  .navbar-brand:hover {{
+    background-color: rgba(255, 255, 255, 0.06);
+  }}
+  .navbar-brand.brand-active:hover {{
+    background-color: rgba({rgb}, 0.95);
+  }}
+  /* Version sits in the navbar alongside the brand pill but
+     OUTSIDE it -- so the brand button stays a clean click target
+     and the version reads as adjacent metadata. */
+  .navbar-version {{
+    color: rgba(255, 255, 255, 0.55);
+    font-weight: 400;
+    font-size: 0.85rem;
+    align-self: center;
+    white-space: nowrap;
+  }}
+  .navbar-brand .brand-icon {{
+    /* Sized to match bty's mascot PNG (1.05rem tall). Using a
+       Bootstrap Icon rather than an image keeps the shell
+       stdlib-only. */
+    font-size: 1.05rem;
+    vertical-align: -0.05rem;
+  }}
+  .navbar .nav-btn {{
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.4rem 0.8rem;
+    margin-right: 0.25rem;
+    border-radius: 0.5rem;
+    color: rgba(255, 255, 255, 0.85);
+    text-decoration: none;
+    transition: background-color 0.15s;
+  }}
+  .navbar .nav-btn:hover {{
+    background-color: rgba(255, 255, 255, 0.10);
+    color: #fff;
+  }}
+  .navbar .nav-btn.active {{
+    background-color: {primary};
+    color: #fff;
+    box-shadow: 0 0 0 1px rgba({rgb}, 0.6);
+  }}
+  .navbar .nav-btn i {{
+    font-size: 1.05rem;
+  }}
+  /* User-bar: a single pill containing username + logout, with a
+     thin vertical divider between them. Visually one widget,
+     but two click targets and zero JavaScript. */
+  .user-bar {{
+    display: inline-flex;
+    align-items: stretch;
+    border-radius: 999px;
+    background-color: rgba(255, 255, 255, 0.08);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    overflow: hidden;
+    font-size: 0.85rem;
+  }}
+  .user-bar-name {{
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.35rem 0.8rem;
+    color: rgba(255, 255, 255, 0.92);
+  }}
+  .user-bar-name code {{
+    color: #fff;
+    background: transparent;
+    padding: 0;
+  }}
+  .user-bar-divider {{
+    width: 1px;
+    background-color: rgba(255, 255, 255, 0.18);
+  }}
+  .user-bar-action {{
+    display: inline-flex;
+    align-items: center;
+    padding: 0.35rem 0.7rem;
+    background: transparent;
+    border: none;
+    color: rgba(255, 255, 255, 0.85);
+    text-decoration: none;
+    transition: background-color 0.15s, color 0.15s;
+  }}
+  .user-bar-action:hover,
+  .user-bar-action:focus {{
+    background-color: rgba(255, 255, 255, 0.10);
+    color: #fff;
+    outline: none;
+  }}
+  .user-bar-action.active {{
+    background-color: rgba(255, 255, 255, 0.16);
+    color: #fff;
+  }}
+  /* Logout hover keeps the danger-red signal so it doesn't
+     look indistinguishable from the account action. */
+  .user-bar-logout:hover,
+  .user-bar-logout:focus {{
+    background-color: rgba(220, 53, 69, 0.65);
+    color: #fff;
+  }}
+  /* Sub-nav strip. Sits immediately below the main ``bg-dark``
+     navbar; coloured CLEARLY lighter so it reads as "second-tier
+     nav, still chrome". Same ``#495057`` (--bs-gray-700) bty
+     uses so the boundary is unambiguous regardless of theme. */
+  .subnav-strip {{
+    background-color: #495057;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.10);
+    padding-top: 0.25rem;
+    padding-bottom: 0.25rem;
+    font-size: 0.85rem;
+    line-height: 1.4;
+  }}
+  .subnav-strip > .container {{
+    min-height: 2rem;
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+  }}
+  .subnav-strip .form-control-sm,
+  .subnav-strip .btn-sm,
+  .subnav-strip a,
+  .subnav-strip label,
+  .subnav-strip .small,
+  .subnav-strip small {{
+    font-size: inherit;
+    line-height: inherit;
+  }}
+  .subnav-strip .form-control-sm,
+  .subnav-strip .btn-sm {{
+    padding-top: 0.15rem;
+    padding-bottom: 0.15rem;
+  }}
+  .subnav-strip .nav-pills {{
+    gap: 0.25rem;
+  }}
+  .subnav-strip .nav-pills .nav-link {{
+    color: rgba(255, 255, 255, 0.78);
+    padding: 0.15rem 0.55rem;
+  }}
+  .subnav-strip .nav-pills .nav-link:hover {{
+    color: #fff;
+    background-color: rgba(255, 255, 255, 0.10);
+  }}
+  .subnav-strip .nav-pills .nav-link.active-tab {{
+    color: #fff;
+    background-color: {primary};
+  }}
+  .subnav-strip .text-muted {{
+    color: rgba(255, 255, 255, 0.55) !important;
+  }}
+  .subnav-strip code {{
+    color: rgba(255, 255, 255, 0.85);
+    background-color: transparent;
+  }}
+  .subnav-strip a {{
+    color: rgba(255, 255, 255, 0.78);
+  }}
+  .subnav-strip a:hover {{
+    color: #fff;
+  }}
+  /* Withcache-specific bits kept minimal. Everything else
+     inherits from Bootstrap + the chrome above. */
   code {{ color: inherit; font-size: .85em; }}
   .url {{ word-break: break-all; }}
   .num {{ text-align: right; }}
   .mono {{ font-family: var(--bs-font-monospace); font-size: .85em; }}
   #spin {{ width: 7rem; height: .5rem; margin: 0; }}
-  /* Tabs: Bootstrap nav-tabs, tinted via the active class. The
-     content panels toggle visibility via ``section.tab.active-tab``
-     so the same 1 Hz htmx innerHTML swap that used to work with
-     the Pico shell keeps working here without changing the JS. */
-  nav.tabs .nav-link {{ color: var(--bs-secondary-color); border: none;
-    border-bottom: 2px solid transparent; padding: .45rem .9rem;
-    font-size: .9rem; margin-bottom: -1px; }}
-  nav.tabs .nav-link:hover {{ color: var(--bs-body-color); }}
-  nav.tabs .nav-link.active-tab {{ color: var(--bs-body-color);
-    border-bottom-color: var(--bs-primary); font-weight: 600; }}
-  section.tab {{ display: none; padding-top: .75rem; }}
+  /* Tab content panels: shown only when the section carries
+     ``.active-tab``. Same hook the previous nav-tabs code used;
+     unchanged so the existing htmx post-swap script keeps
+     working. */
+  section.tab {{ display: none; padding-top: .25rem; }}
   section.tab.active-tab {{ display: block; }}
 </style>
 </head>"""
 
     def render_login(self, error: str = "") -> str:
+        """The unauthenticated shell: accent strip + dark navbar with the
+        brand pill (no user-bar since there's no session), then a
+        centered login card. Same chrome the authenticated page uses,
+        so the operator sees continuity across the auth boundary."""
         err = f'<div class="alert alert-danger">{html.escape(error)}</div>' if error else ""
         return f"""{self._head("withcache - login")}
-<body>
+<body class="bg-light">
+<div class="sticky-header">
 <div class="brand-accent"></div>
-<main class="container py-5">
-  <div class="card mx-auto" style="max-width: 24rem;">
+<nav class="navbar navbar-expand-md bg-dark navbar-dark py-2">
+    <div class="container">
+        <a class="navbar-brand fw-semibold brand-active" href="/">
+            <i class="bi bi-database brand-icon me-1"></i>WITHCACHE
+        </a>
+        <span class="navbar-version">v{html.escape(__version__)}</span>
+    </div>
+</nav>
+</div>
+<main class="container">
+  <div class="card mx-auto mt-5" style="max-width: 24rem;">
     <div class="card-body">
-      <h3 class="card-title fw-bold text-primary">
-        <i class="bi bi-hdd-stack"></i> withcache
-        <small class="text-muted fs-6">v{html.escape(__version__)}</small>
-      </h3>
-      <p class="text-muted small mb-3">Operator login</p>
+      <h5 class="card-title mb-3">Operator login</h5>
       {err}
       <form method="post" action="/ui/login">
         <div class="mb-3">
@@ -1128,29 +1427,68 @@ class Handler(http.server.BaseHTTPRequestHandler):
 </main></body></html>"""
 
     def render_page(self) -> str:
-        logout = (
-            '<form method="post" action="/ui/logout" class="d-inline m-0">'
-            '<button type="submit" class="btn btn-sm btn-outline-secondary">'
-            "Log out</button></form>"
+        """The authenticated shell: sticky-header wrapping the accent
+        strip, the dark navbar (brand pill + version + user-bar), and
+        the subnav strip carrying the tab pills. Then main.container
+        with the "Add from URI" card and the htmx-swapped #dash
+        region. Same chrome bty uses; only ``--bs-primary`` differs."""
+        user_bar = (
+            '<div class="user-bar mt-2 mt-md-0" title="Operator session">'
+            '<span class="user-bar-name">'
+            '<i class="bi bi-person-circle"></i><code>operator</code>'
+            "</span>"
+            '<span class="user-bar-divider"></span>'
+            '<form action="/ui/logout" method="post" class="m-0 d-inline-flex">'
+            '<button type="submit" class="user-bar-action user-bar-logout" title="Sign out">'
+            '<i class="bi bi-box-arrow-right"></i>'
+            "</button></form>"
+            "</div>"
             if self.auth.enabled
             else ""
         )
         return f"""{self._head("withcache cache-host")}
-<body>
+<body class="bg-light">
+<!-- Sticky header: the accent strip, the main navbar, and the
+     sub-nav strip travel together and pin to the top so the tab
+     pills stay reachable while scrolling a long list. -->
+<div class="sticky-header">
 <div class="brand-accent"></div>
-<nav class="navbar navbar-expand navbar-light bg-light border-bottom">
-  <div class="container">
-    <a class="navbar-brand fw-bold text-primary" href="/">
-      <i class="bi bi-hdd-stack"></i> withcache
-      <span class="badge bg-primary bg-opacity-10 text-primary ms-1"
-        >v{html.escape(__version__)}</span>
-    </a>
-    <div class="d-flex align-items-center gap-3">
-      <progress id="spin" class="htmx-indicator"></progress>
-      {logout}
+<nav class="navbar navbar-expand-md bg-dark navbar-dark py-2">
+    <div class="container">
+        <a class="navbar-brand fw-semibold brand-active" href="/">
+            <i class="bi bi-database brand-icon me-1"></i>WITHCACHE
+        </a>
+        <div class="d-flex flex-grow-1 align-items-center flex-wrap">
+            <div class="me-auto d-flex flex-wrap">
+                <!-- withcache is a single-page dashboard: no middle
+                     nav-btns. me-auto pushes version + user-bar right. -->
+            </div>
+            <span class="navbar-version me-2">v{html.escape(__version__)}</span>
+            {user_bar}
+        </div>
     </div>
-  </div>
 </nav>
+
+<!-- Sub-nav strip. Carries the five tab pills below the main
+     navbar; visually attached (same sticky container, #495057
+     background) but rendered STATIC here so tab labels don't
+     flicker on the 1 Hz htmx dashboard swap. Per-tab counts live
+     in the summary line inside the dash content and update on
+     every swap. -->
+<div class="subnav-strip">
+  <div class="container">
+    <ul class="nav nav-pills flex-nowrap flex-md-wrap">
+      <li class="nav-item"><a class="nav-link" href="#tab-cached">Cached</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tab-streams">Streams</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tab-downloads">Downloads</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tab-misses">Misses</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tab-catalog">Catalog</a></li>
+      <span class="ms-auto"><progress id="spin" class="htmx-indicator"></progress></span>
+    </ul>
+  </div>
+</div>
+</div><!-- /.sticky-header -->
+
 <main class="container py-4">
   <div class="card mb-4">
     <div class="card-header"><i class="bi bi-cloud-download text-primary"></i> Add from URI</div>
@@ -1169,15 +1507,11 @@ class Handler(http.server.BaseHTTPRequestHandler):
 
   <!-- The hx-trigger gates polling on the user NOT having an active
        text selection, so highlight-and-copy a URL out of a table cell
-       isn't wiped by the 1 Hz refresh. ``isCollapsed`` is true when
-       there's no selection or the caret is a zero-width point; once
-       the operator releases / clears the selection polling resumes
-       on the next 1 s tick.
-       ``hx-headers`` sends the current URL hash (the active tab id)
-       as ``X-Active-Tab`` on every refresh so the server can bake
-       ``.active-tab`` into the rendered HTML -- eliminating the
-       visible flicker the post-swap JS-applied class would otherwise
-       cause when the new innerHTML lands without the class. -->
+       isn't wiped by the 1 Hz refresh. hx-headers sends the current
+       URL hash (the active tab id) as X-Active-Tab on every refresh
+       so the server can bake .active-tab into the rendered HTML,
+       eliminating the visible flicker the post-swap JS-applied class
+       would otherwise cause when the new innerHTML lands. -->
   <div id="dash" hx-get="/admin/dash"
        hx-trigger="load, every 1s [document.getSelection().isCollapsed]"
        hx-swap="innerHTML"
@@ -1185,16 +1519,15 @@ class Handler(http.server.BaseHTTPRequestHandler):
     {self.render_dash(active_tab=(self.headers.get("X-Active-Tab") or "").strip())}
   </div>
 
-  <!-- Tab activation. Applies an ``active-tab`` class to the
-       ``section.tab`` whose id matches the URL hash (defaulting to
-       the first section when no hash is set) and to the
-       corresponding ``nav.tabs a``. Runs on initial load, on every
-       click into a tab link (so the operator gets immediate
-       feedback before the next htmx tick), and on every
-       ``htmx:afterSettle`` so the class survives the 1 Hz
-       innerHTML replacement of ``#dash``. Without this the
-       previous ``:target``-based CSS would snap the operator back
-       to the first tab within a second of any click. -->
+  <!-- Tab activation: apply .active-tab to the section (inside
+       #dash) AND to the matching subnav pill (outside #dash) whose
+       id/hash matches the current URL hash. Runs on hashchange, on
+       click into a tab link, and on every htmx:afterSettle so the
+       class survives the 1 Hz innerHTML replacement of #dash.
+       Subnav pills live outside #dash so the JS-applied class on
+       them is not touched by the swap; sections inside #dash also
+       get the class baked server-side (via X-Active-Tab) so there
+       is no visible flicker between swap and JS re-apply. -->
   <script>
     (function () {{
       function applyActiveTab() {{
@@ -1206,7 +1539,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
         sections.forEach(function (s) {{
           s.classList.toggle('active-tab', s.id === hash);
         }});
-        document.querySelectorAll('#dash nav.tabs a').forEach(function (a) {{
+        document.querySelectorAll('.subnav-strip .nav-pills .nav-link').forEach(function (a) {{
           var target = (a.getAttribute('href') || '').replace(/^#/, '');
           a.classList.toggle('active-tab', target === hash);
         }});
@@ -1214,7 +1547,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
       window.addEventListener('hashchange', applyActiveTab);
       document.body.addEventListener('htmx:afterSettle', applyActiveTab);
       document.addEventListener('click', function (ev) {{
-        var a = ev.target.closest && ev.target.closest('#dash nav.tabs a');
+        var a = ev.target.closest && ev.target.closest('.subnav-strip .nav-pills .nav-link');
         if (a) setTimeout(applyActiveTab, 0);
       }});
       applyActiveTab();
@@ -1230,7 +1563,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
         # 1 Hz refresh (and on every operator click via the same
         # script that watches hashchange). Unknown / empty value
         # defaults to the first tab.
-        _TAB_IDS = ("tab-cached", "tab-streams", "tab-downloads", "tab-misses")
+        _TAB_IDS = ("tab-cached", "tab-streams", "tab-downloads", "tab-misses", "tab-catalog")
         if active_tab not in _TAB_IDS:
             active_tab = _TAB_IDS[0]
 
@@ -1354,21 +1687,23 @@ class Handler(http.server.BaseHTTPRequestHandler):
         nstreams = len(streams)
         njobs = len(jobs)
 
+        catalog_rows = self._catalog_rows()
+        ncatalog = len(self.catalog.entries)
+
+        # The per-tab count summary lives here (inside the htmx-swapped
+        # region) so it updates every second. Tab labels themselves
+        # live in the static sub-nav strip in ``render_page`` per bty
+        # convention -- labels are chrome, counts are content.
         return f"""
-  <p class="text-muted small mb-2">{nblobs} cached ({used}){full}
-    &middot; {nmisses} pending miss(es)</p>
-  <nav class="tabs border-bottom mb-2">
-    <ul class="nav">
-      <li class="nav-item"><a class="nav-link {_active("tab-cached").lstrip()}"
-        href="#tab-cached">Cached ({nblobs})</a></li>
-      <li class="nav-item"><a class="nav-link {_active("tab-streams").lstrip()}"
-        href="#tab-streams">Streams ({nstreams})</a></li>
-      <li class="nav-item"><a class="nav-link {_active("tab-downloads").lstrip()}"
-        href="#tab-downloads">Downloads ({njobs})</a></li>
-      <li class="nav-item"><a class="nav-link {_active("tab-misses").lstrip()}"
-        href="#tab-misses">Misses ({nmisses})</a></li>
-    </ul>
-  </nav>
+  <p class="text-muted small mb-3">
+    <span class="badge bg-primary bg-opacity-10 text-primary me-1">{nblobs} cached ({used}){
+            full
+        }</span>
+    <span class="badge bg-secondary bg-opacity-10 text-secondary me-1">{nstreams} streams</span>
+    <span class="badge bg-secondary bg-opacity-10 text-secondary me-1">{njobs} downloads</span>
+    <span class="badge bg-secondary bg-opacity-10 text-secondary me-1">{nmisses} misses</span>
+    <span class="badge bg-secondary bg-opacity-10 text-secondary">{ncatalog} catalog</span>
+  </p>
 
   <section id="tab-cached" class="tab{_active("tab-cached")}">
     <div class="table-responsive"><table class="table table-sm table-striped table-hover mb-0">
@@ -1412,8 +1747,80 @@ class Handler(http.server.BaseHTTPRequestHandler):
       </tr></thead>
       <tbody>{miss_rows}</tbody>
     </table></div>
+  </section>
+
+  <section id="tab-catalog" class="tab{_active("tab-catalog")}">
+    <div class="d-flex align-items-center justify-content-between mb-2 flex-wrap gap-2">
+      <div>
+        <div><small class="text-muted">source</small>
+          &nbsp;<code>{html.escape(self.catalog.url)}</code></div>
+        <div><small class="text-muted">fetched</small>
+          &nbsp;<code>{html.escape(self.catalog.fetched_at) or "never"}</code>
+          {
+            (
+                f'<span class="badge bg-danger-subtle text-danger ms-1">'
+                f"{html.escape(self.catalog.last_error)}</span>"
+            )
+            if self.catalog.last_error
+            else ""
+        }</div>
+      </div>
+      <form hx-post="/admin/catalog_refresh" hx-target="#dash" hx-swap="innerHTML"
+            hx-indicator="#spin" class="m-0">
+        <button class="btn btn-sm btn-primary" type="submit">Refresh</button>
+      </form>
+    </div>
+    <div class="table-responsive"><table class="table table-sm table-striped table-hover mb-0">
+      <thead class="table-light"><tr>
+        <th>Name</th><th>Format</th><th>Arch</th><th>Size</th><th>Source</th>
+      </tr></thead>
+      <tbody>{catalog_rows}</tbody>
+    </table></div>
   </section>"""
 
+    def _catalog_rows(self) -> str:
+        """One <tr> per catalog image. Cells: name, format, arch,
+        human-readable size, and a Source cell whose URL is the
+        withcache /b/ token (so a click through pulls via cache).
+        Empty catalog rows to a "not fetched yet" placeholder + a
+        hint about the Refresh button."""
+        entries = self.catalog.entries
+        if not entries:
+            hint = self.catalog.last_error or "click Refresh above to fetch the catalog manifest"
+            return (
+                '<tr><td colspan="5" class="text-center text-muted">'
+                f"<em>{html.escape(hint)}</em></td></tr>"
+            )
+        rows: list[str] = []
+        for entry in entries:
+            name = str(entry.get("name") or "")
+            src = str(entry.get("src") or "")
+            fmt = str(entry.get("format") or "")
+            arch = str(entry.get("arch") or "")
+            size_bytes = entry.get("size_bytes")
+            size = human_size(int(size_bytes)) if isinstance(size_bytes, int) else ""
+            # Route the Source column via /b/<token>/<name> so a
+            # click serves through withcache -- first hit fills the
+            # cache, subsequent hits serve from disk. Mirrors the
+            # blob-row rendering above.
+            if src.startswith(("http://", "https://", "oras://")):
+                token = base64.urlsafe_b64encode(src.encode("utf-8")).decode("ascii").rstrip("=")
+                filename = urllib.parse.urlsplit(src).path.rsplit("/", 1)[-1] or "download"
+                link = f"/b/{token}/{urllib.parse.quote(filename)}"
+                src_cell = f'<a href="{link}" title="{html.escape(src)}">{html.escape(src)}</a>'
+            else:
+                src_cell = html.escape(src)
+            rows.append(
+                f"<tr>"
+                f"<td>{html.escape(name)}</td>"
+                f'<td class="mono"><small>{html.escape(fmt)}</small></td>'
+                f'<td class="mono"><small>{html.escape(arch)}</small></td>'
+                f"<td>{html.escape(size)}</td>"
+                f'<td class="url">{src_cell}</td>'
+                "</tr>"
+            )
+        return "".join(rows)
+
     def _stream_progress_cell(self, s: Stream) -> str:
         """One progress cell for an active stream: a <progress> bar when the
         total is known (always for a cached blob, since the size came off
@@ -1506,6 +1913,25 @@ def main():
     httpd.mgr = mgr  # type: ignore[attr-defined]
     httpd.auto_fetch = not args.curate  # type: ignore[attr-defined]
     httpd.streams = StreamRegistry()  # type: ignore[attr-defined]
+    # Catalog state: env override, else the shipping default (nosi's
+    # rolling catalog manifest). Seeded from the last persisted
+    # catalog.toml on disk so a restart doesn't wipe the cache.
+    catalog_url = (os.environ.get("WITHCACHE_CATALOG_URL") or DEFAULT_CATALOG_URL).strip()
+    catalog = CatalogState(
+        url=catalog_url,
+        persist_path=os.path.join(store.data_dir, "catalog.toml"),
+    )
+    catalog.load_persisted()
+    httpd.catalog = catalog  # type: ignore[attr-defined]
+    # If no catalog is persisted yet, kick a single startup fetch
+    # in a daemon thread so the operator has something to look at
+    # without needing to click Refresh on their first visit.
+    # Failures record ``last_error`` in memory; the dashboard row
+    # shows it. Never blocks the serve loop.
+    if not catalog.entries:
+        threading.Thread(
+            target=catalog.fetch_now, name="withcache-catalog-init", daemon=True
+        ).start()
     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.6.5 → withcache-0.7.1}/tests/test_withcache.py

@@ -643,6 +643,14 @@ def _start_withcache(auto_fetch=False):
     httpd.mgr = server.DownloadManager(store, workers=1)
     httpd.auto_fetch = auto_fetch
     httpd.streams = server.StreamRegistry()
+    # Empty catalog with a bogus URL so the tab renders "click Refresh
+    # above to fetch the catalog manifest" instead of firing a real
+    # HTTP call. Tests that specifically exercise the catalog code
+    # can override this attribute after the helper returns.
+    httpd.catalog = server.CatalogState(
+        url="http://localhost/catalog.toml",
+        persist_path=os.path.join(store.data_dir, "catalog.toml"),
+    )
     threading.Thread(target=httpd.serve_forever, daemon=True).start()
     return httpd, store