withcache 0.6.4__tar.gz → 0.7.0__tar.gz

{withcache-0.6.4 → withcache-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.6.4
+Version: 0.7.0
 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
@@ -100,13 +100,13 @@ asserts the binary and the Python `plan()` rewrite argv identically.
 ```sh
 export WITHCACHE_ADMIN_PASSWORD=change-me    # protects the operator UI
 podman compose -f deploy/compose.yml up -d   # or: docker compose -f ...
-# operator UI:  http://withcache-server:3000/
+# operator UI:  http://withcache-server:8081/
 ```
 
 Or without containers:
 
 ```sh
-WITHCACHE_ADMIN_PASSWORD=change-me withcache-server --data-dir ./data --port 3000
+WITHCACHE_ADMIN_PASSWORD=change-me withcache-server --data-dir ./data --port 8081
 ```
 
 Data (blobs + `cache.db` + `session-secret`) lives in the `/data` volume (or
@@ -137,7 +137,7 @@ Nothing is renamed; you opt in per command. Good for trying it out or a script
 you can edit.
 
 ```sh
-export WITHCACHE_SERVER=http://withcache-server:3000
+export WITHCACHE_SERVER=http://withcache-server:8081
 curlwithcache -fsSL https://the/origin/cuda.tar.gz -o cuda.tar.gz
 wgetwithcache https://the/origin/rocm.tar.gz
 ```
@@ -152,7 +152,7 @@ mkdir -p ~/.withcache/bin
 ln -sf "$(command -v curlwithcache)" ~/.withcache/bin/curl
 ln -sf "$(command -v wgetwithcache)" ~/.withcache/bin/wget
 
-export WITHCACHE_SERVER=http://withcache-server:3000
+export WITHCACHE_SERVER=http://withcache-server:8081
 export PATH="$HOME/.withcache/bin:$PATH"
 hash -r                       # forget any cached curl/wget location
 
@@ -174,7 +174,7 @@ ln -sf "$(command -v wgetwithcache)" ~/.withcache/bin/wget
 cat >> ~/.bashrc <<'EOF'
 
 # withcache: transparent curl/wget caching
-export WITHCACHE_SERVER=http://withcache-server:3000
+export WITHCACHE_SERVER=http://withcache-server:8081
 export PATH="$HOME/.withcache/bin:$PATH"
 EOF
 ```
@@ -186,7 +186,7 @@ inside that directory.
 
 ```sh
 # .envrc
-export WITHCACHE_SERVER=http://withcache-server:3000
+export WITHCACHE_SERVER=http://withcache-server:8081
 PATH_add ~/.withcache/bin        # assumes the symlinks from approach 2/3 exist
 ```
 
@@ -204,7 +204,7 @@ sudo ln -sf "$(command -v wgetwithcache)" /usr/local/bin/wget
 
 # A login-shell env file (covers interactive logins; daemons started outside a
 # login shell won't see it; set WITHCACHE_SERVER in their unit if you need it).
-echo 'export WITHCACHE_SERVER=http://withcache-server:3000' \
+echo 'export WITHCACHE_SERVER=http://withcache-server:8081' \
   | sudo tee /etc/profile.d/withcache.sh >/dev/null
 ```
 
@@ -237,7 +237,7 @@ Notes & limits (all degrade gracefully; worst case is "no caching, curl still wo
 
 ## Operator UI
 
-`http://withcache-server:3000/` (Pico.css + HTMX, bundled offline) shows:
+`http://withcache-server:8081/` (Pico.css + HTMX, bundled offline) shows:
 - **Misses**: auto-fetched by default, or (under `--curate`) each with **Download** (queues a background pull) and **Dismiss**.
 - **Downloads**: live progress bars, `queued/running/completed/cancelled/failed`, **Cancel**, and **Clear finished**. Downloads run in a background worker pool, not in the request, so large pulls never block, modelled on [bty]'s job managers.
 - **Cached artifacts**: URL, size, **hits** (times served) and **misses** (times requested before it was cached), SHA-256, fetched-at, each with **Delete** to free space.
@@ -276,7 +276,7 @@ scheme. `withcache.client` is stdlib-only, so importing it adds no dependencies:
 from withcache import client
 
 # "use the cache when it's warm, the origin otherwise"
-url = client.serve_url("http://cache:3000", origin) or origin
+url = client.serve_url("http://cache:8081", origin) or origin
 ```
 
 `is_cached()` is a graceful `HEAD` (a miss, timeout, or unreachable cache all

{withcache-0.6.4 → withcache-0.7.0}/README.md

@@ -82,13 +82,13 @@ asserts the binary and the Python `plan()` rewrite argv identically.
 ```sh
 export WITHCACHE_ADMIN_PASSWORD=change-me    # protects the operator UI
 podman compose -f deploy/compose.yml up -d   # or: docker compose -f ...
-# operator UI:  http://withcache-server:3000/
+# operator UI:  http://withcache-server:8081/
 ```
 
 Or without containers:
 
 ```sh
-WITHCACHE_ADMIN_PASSWORD=change-me withcache-server --data-dir ./data --port 3000
+WITHCACHE_ADMIN_PASSWORD=change-me withcache-server --data-dir ./data --port 8081
 ```
 
 Data (blobs + `cache.db` + `session-secret`) lives in the `/data` volume (or
@@ -119,7 +119,7 @@ Nothing is renamed; you opt in per command. Good for trying it out or a script
 you can edit.
 
 ```sh
-export WITHCACHE_SERVER=http://withcache-server:3000
+export WITHCACHE_SERVER=http://withcache-server:8081
 curlwithcache -fsSL https://the/origin/cuda.tar.gz -o cuda.tar.gz
 wgetwithcache https://the/origin/rocm.tar.gz
 ```
@@ -134,7 +134,7 @@ mkdir -p ~/.withcache/bin
 ln -sf "$(command -v curlwithcache)" ~/.withcache/bin/curl
 ln -sf "$(command -v wgetwithcache)" ~/.withcache/bin/wget
 
-export WITHCACHE_SERVER=http://withcache-server:3000
+export WITHCACHE_SERVER=http://withcache-server:8081
 export PATH="$HOME/.withcache/bin:$PATH"
 hash -r                       # forget any cached curl/wget location
 
@@ -156,7 +156,7 @@ ln -sf "$(command -v wgetwithcache)" ~/.withcache/bin/wget
 cat >> ~/.bashrc <<'EOF'
 
 # withcache: transparent curl/wget caching
-export WITHCACHE_SERVER=http://withcache-server:3000
+export WITHCACHE_SERVER=http://withcache-server:8081
 export PATH="$HOME/.withcache/bin:$PATH"
 EOF
 ```
@@ -168,7 +168,7 @@ inside that directory.
 
 ```sh
 # .envrc
-export WITHCACHE_SERVER=http://withcache-server:3000
+export WITHCACHE_SERVER=http://withcache-server:8081
 PATH_add ~/.withcache/bin        # assumes the symlinks from approach 2/3 exist
 ```
 
@@ -186,7 +186,7 @@ sudo ln -sf "$(command -v wgetwithcache)" /usr/local/bin/wget
 
 # A login-shell env file (covers interactive logins; daemons started outside a
 # login shell won't see it; set WITHCACHE_SERVER in their unit if you need it).
-echo 'export WITHCACHE_SERVER=http://withcache-server:3000' \
+echo 'export WITHCACHE_SERVER=http://withcache-server:8081' \
   | sudo tee /etc/profile.d/withcache.sh >/dev/null
 ```
 
@@ -219,7 +219,7 @@ Notes & limits (all degrade gracefully; worst case is "no caching, curl still wo
 
 ## Operator UI
 
-`http://withcache-server:3000/` (Pico.css + HTMX, bundled offline) shows:
+`http://withcache-server:8081/` (Pico.css + HTMX, bundled offline) shows:
 - **Misses**: auto-fetched by default, or (under `--curate`) each with **Download** (queues a background pull) and **Dismiss**.
 - **Downloads**: live progress bars, `queued/running/completed/cancelled/failed`, **Cancel**, and **Clear finished**. Downloads run in a background worker pool, not in the request, so large pulls never block, modelled on [bty]'s job managers.
 - **Cached artifacts**: URL, size, **hits** (times served) and **misses** (times requested before it was cached), SHA-256, fetched-at, each with **Delete** to free space.
@@ -258,7 +258,7 @@ scheme. `withcache.client` is stdlib-only, so importing it adds no dependencies:
 from withcache import client
 
 # "use the cache when it's warm, the origin otherwise"
-url = client.serve_url("http://cache:3000", origin) or origin
+url = client.serve_url("http://cache:8081", origin) or origin
 ```
 
 `is_cached()` is a graceful `HEAD` (a miss, timeout, or unreachable cache all

{withcache-0.6.4 → withcache-0.7.0}/deploy/Containerfile

@@ -17,7 +17,7 @@ RUN useradd --create-home --uid 10001 app \
  && mkdir -p /data && chown app:app /data
 USER app
 
-EXPOSE 3000
+EXPOSE 8081
 VOLUME ["/data"]
 
 # Set WITHCACHE_ADMIN_PASSWORD at run time to protect the operator UI.
@@ -25,6 +25,6 @@ VOLUME ["/data"]
 # with WITHCACHE_SESSION_SECRET.
 
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
-  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:3000/healthz',timeout=2).status==200 else 1)"
+  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8081/healthz',timeout=2).status==200 else 1)"
 
-ENTRYPOINT ["withcache-server", "--host", "0.0.0.0", "--port", "3000", "--data-dir", "/data"]
+ENTRYPOINT ["withcache-server", "--host", "0.0.0.0", "--port", "8081", "--data-dir", "/data"]

{withcache-0.6.4 → withcache-0.7.0}/deploy/compose.yml

@@ -9,7 +9,7 @@ services:
     image: withcache:latest
     container_name: withcache
     ports:
-      - "3000:3000"
+      - "8081:8081"
     environment:
       # Protect the operator UI. Unset => UI is open (a warning is logged).
       - WITHCACHE_ADMIN_PASSWORD=${WITHCACHE_ADMIN_PASSWORD:-}

{withcache-0.6.4 → withcache-0.7.0}/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.4 → withcache-0.7.0}/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.4",
+    .version = "0.7.0",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.6.4 → withcache-0.7.0}/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.4"
+__version__ = "0.7.0"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

{withcache-0.6.4 → withcache-0.7.0}/src/withcache/_shim.py

@@ -26,7 +26,7 @@ _SCHEME = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.\-]*://")
 
 
 def cache_base(server: str) -> str:
-    """Accept 'host', 'host:3000', or 'http://withcache-server:3000'."""
+    """Accept 'host', 'host:8081', or 'http://withcache-server:8081'."""
     server = server.strip().rstrip("/")
     if "://" not in server:
         server = "http://" + server

{withcache-0.6.4 → withcache-0.7.0}/src/withcache/client.py

@@ -7,7 +7,7 @@ dependencies.
     from withcache import client
 
     # "use the cache when it's warm, the origin otherwise"
-    url = client.serve_url("http://cache:3000", origin) or origin
+    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
@@ -25,7 +25,7 @@ __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:3000', or 'http://host:3000'.
+#: Normalize a server value: accepts 'host', 'host:8081', or 'http://host:8081'.
 cache_base = _shim.cache_base
 
 

{withcache-0.6.4 → withcache-0.7.0}/src/withcache/curlwithcache.py

@@ -7,7 +7,7 @@ withcache cache-host and the artifact is cached there, the download is served
 from the cache; otherwise — server unset, not cached, or unreachable — your curl
 runs exactly as written. Existing scripts need no changes.
 
-    export WITHCACHE_SERVER=http://withcache-server:3000
+    export WITHCACHE_SERVER=http://withcache-server:8081
     curl -fsSL https://the/origin/cuda.tar.gz -o cuda.tar.gz   # cache hit -> local
 
 It wraps the system curl, so all curl flags keep working; on a miss it hands

{withcache-0.6.4 → withcache-0.7.0}/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")
@@ -1354,6 +1441,8 @@ class Handler(http.server.BaseHTTPRequestHandler):
         nstreams = len(streams)
         njobs = len(jobs)
 
+        catalog_rows = self._catalog_rows()
+
         return f"""
   <p class="text-muted small mb-2">{nblobs} cached ({used}){full}
     &middot; {nmisses} pending miss(es)</p>
@@ -1367,6 +1456,8 @@ class Handler(http.server.BaseHTTPRequestHandler):
         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>
+      <li class="nav-item"><a class="nav-link {_active("tab-catalog").lstrip()}"
+        href="#tab-catalog">Catalog ({len(self.catalog.entries)})</a></li>
     </ul>
   </nav>
 
@@ -1412,8 +1503,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
@@ -1471,7 +1634,7 @@ class ThreadingHTTPServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
 def main():
     ap = argparse.ArgumentParser(description="withcache cache-host")
     ap.add_argument("--host", default="0.0.0.0")
-    ap.add_argument("--port", type=int, default=3000)
+    ap.add_argument("--port", type=int, default=8081)
     ap.add_argument("--data-dir", default="./data")
     ap.add_argument(
         "--keep-query",
@@ -1506,6 +1669,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.4 → withcache-0.7.0}/src/withcache/wgetwithcache.py

@@ -6,7 +6,7 @@ The wget sibling of curlwithcache. Drop it on $PATH ahead of the real wget
 cache-host and the artifact is cached there, the download is served from the
 cache; otherwise your wget runs exactly as written.
 
-    export WITHCACHE_SERVER=http://withcache-server:3000
+    export WITHCACHE_SERVER=http://withcache-server:8081
     wget https://the/origin/cuda.tar.gz            # cache hit -> local, named cuda.tar.gz
 
 Because the cache URL is path-encoded with the real basename, a bare ``wget

{withcache-0.6.4 → withcache-0.7.0}/tests/test_differential.py

@@ -64,7 +64,7 @@ class TestDifferential(unittest.TestCase):
                 "WGETWITHCACHE_SERVER",
             )
         }
-        os.environ["WITHCACHE_SERVER"] = "http://cache:3000"
+        os.environ["WITHCACHE_SERVER"] = "http://cache:8081"
         os.environ["REAL_CURL"] = self.fake_hit  # Python find_real just needs an exe
         os.environ["REAL_WGET"] = self.fake_hit
         os.environ.pop("CURLWITHCACHE_SERVER", None)

{withcache-0.6.4 → withcache-0.7.0}/tests/test_withcache.py

@@ -481,8 +481,8 @@ class TestAgeHuman(unittest.TestCase):
 # --------------------------------------------------------------------------
 class TestShim(unittest.TestCase):
     def test_cache_base(self):
-        self.assertEqual(_shim.cache_base("box:3000"), "http://box:3000")
-        self.assertEqual(_shim.cache_base("https://box:3000/"), "https://box:3000")
+        self.assertEqual(_shim.cache_base("box:8081"), "http://box:8081")
+        self.assertEqual(_shim.cache_base("https://box:8081/"), "https://box:8081")
 
     def test_find_url_bare(self):
         self.assertEqual(
@@ -540,11 +540,11 @@ class TestShim(unittest.TestCase):
             for k in ("WITHCACHE_SERVER", "CURLWITHCACHE_SERVER", "WGETWITHCACHE_SERVER")
         }
         try:
-            os.environ["WITHCACHE_SERVER"] = "http://shared:3000"
-            os.environ["CURLWITHCACHE_SERVER"] = "http://curl-only:3000"
+            os.environ["WITHCACHE_SERVER"] = "http://shared:8081"
+            os.environ["CURLWITHCACHE_SERVER"] = "http://curl-only:8081"
             os.environ.pop("WGETWITHCACHE_SERVER", None)
-            self.assertEqual(_shim.env_server("curl"), "http://curl-only:3000")
-            self.assertEqual(_shim.env_server("wget"), "http://shared:3000")
+            self.assertEqual(_shim.env_server("curl"), "http://curl-only:8081")
+            self.assertEqual(_shim.env_server("wget"), "http://shared:8081")
         finally:
             for k, v in saved.items():
                 if v is None:
@@ -593,22 +593,22 @@ class TestShimPlan(unittest.TestCase):
             os.environ.pop(k, None) if v is None else os.environ.__setitem__(k, v)
 
     def test_hit_rewrites_only_the_url(self):
-        os.environ["WITHCACHE_SERVER"] = "http://cache:3000"
+        os.environ["WITHCACHE_SERVER"] = "http://cache:8081"
         argv = ["-fsSL", "https://h/p/cuda.tar.gz", "-o", "out"]
         real, final = _shim.plan("curl", lambda r, u: True, argv)
         self.assertEqual(real, self.dummy)
         self.assertEqual([final[0], final[2], final[3]], ["-fsSL", "-o", "out"])
-        self.assertTrue(final[1].startswith("http://cache:3000/b/"))
+        self.assertTrue(final[1].startswith("http://cache:8081/b/"))
         self.assertTrue(final[1].endswith("/cuda.tar.gz"))
 
     def test_miss_leaves_argv_untouched(self):
-        os.environ["WITHCACHE_SERVER"] = "http://cache:3000"
+        os.environ["WITHCACHE_SERVER"] = "http://cache:8081"
         argv = ["https://h/x", "-O"]
         _, final = _shim.plan("curl", lambda r, u: False, argv)
         self.assertEqual(final, argv)
 
     def test_unreachable_leaves_argv_untouched(self):
-        os.environ["WITHCACHE_SERVER"] = "http://cache:3000"
+        os.environ["WITHCACHE_SERVER"] = "http://cache:8081"
         argv = ["https://h/x"]
         _, final = _shim.plan("curl", lambda r, u: None, argv)
         self.assertEqual(final, argv)
@@ -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