withcache 0.9.1__tar.gz → 0.10.0__tar.gz

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

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

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

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

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

@@ -65,39 +65,36 @@ def _serve_blob(
 ) -> Response:
     """Shared implementation for GET and HEAD blob requests.
 
-    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.
+    Returns 400 when the origin URL couldn't be decoded, 404 on
+    cache miss (with a hint pointing at ``POST /catalog/entries/
+    {name}/download``), or 200 + a StreamingResponse on hit.
+
+    Since v0.10.0 there is no auto-fetch on miss: the operator
+    picks explicitly what to download on withcache's /ui/catalog
+    page. A miss here is either "not downloaded yet" (operator
+    action needed) or "hit an unlisted URL" (bug in the caller).
     """
     if not url:
         return PlainTextResponse("missing url\n", status_code=400)
 
     store = request.app.state.store
-    mgr = request.app.state.mgr
-    auto_fetch: bool = request.app.state.auto_fetch
     streams: StreamRegistry = request.app.state.streams
 
     row = store.get_blob(url)
     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.
+        # Tag re-pushed since we cached it: drop the stale bytes.
+        # The miss branch below turns this into a 404 the operator
+        # resolves by hitting Download / Redownload on /ui/catalog.
         store.delete_blob(row["key"])
         row = None
 
     if row is None:
         store.record_miss(url)
-        if auto_fetch and store.has_capacity():
-            # Forward the client's Authorization header onto the
-            # worker so a token-gated origin (fresh OCI bearer from
-            # bty at catalog import time) can be fetched. Narrow
-            # allowlist: Authorization only; /admin/fetch carries
-            # its own ``headers=`` payload for the curated path.
-            fwd_headers: dict[str, str] | None = None
-            auth_header = request.headers.get("Authorization")
-            if auth_header:
-                fwd_headers = {"Authorization": auth_header}
-            mgr.enqueue(url, headers=fwd_headers)
-        return PlainTextResponse("cache miss (recorded)\n", status_code=404)
+        return PlainTextResponse(
+            "cache miss: this URL hasn't been downloaded yet. "
+            "Pick the matching catalog entry on /ui/catalog and hit Download.\n",
+            status_code=404,
+        )
 
     path = store.blob_path(row["key"])
     headers = {
@@ -218,17 +215,29 @@ def register_api_routes(app: FastAPI) -> None:
         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).
+        detect staleness. Every entry is enriched with a
+        ``downloaded_at`` field (or ``None``) so nbdmux + bty can
+        filter to only-downloaded entries without a second call. No
+        pagination -- the catalog is small (dozens of entries at
+        most).
         """
         cs: CatalogState = request.app.state.catalog
+        store = request.app.state.store
+        entries_out: list[dict[str, Any]] = []
+        for e in cs.entries:
+            enriched = dict(e)
+            fetch_url = e.get("resolved_src") or e.get("src") or ""
+            row = store.get_blob(fetch_url) if fetch_url else None
+            enriched["downloaded_at"] = row["fetched_at"] if row else None
+            enriched["downloaded_size"] = int(row["size"]) if row else None
+            entries_out.append(enriched)
         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],
+                "entries": entries_out,
             }
         )
 
@@ -290,6 +299,53 @@ def register_api_routes(app: FastAPI) -> None:
         _persist_catalog(cs)
         return JSONResponse(entry, status_code=201)
 
+    @app.post("/catalog/entries/{name}/download", status_code=202)
+    def download_catalog_entry(
+        name: str,
+        request: Request,
+        _auth: None = Depends(_bearer_or_session_authed),
+    ) -> JSONResponse:
+        """Fetch the entry's bytes into the local cache.
+
+        Since v0.10.0 auto-fetch on cache miss is gone: the operator
+        picks explicitly what to download. Nbdmux + bty's flash
+        chain both refuse to hand out /b/<url> URLs for entries
+        that haven't been downloaded, so this is the one-place
+        control for "make it servable."
+
+        Idempotent: enqueuing an entry that already has a live
+        download returns the existing job. Force-refetch is
+        ``POST /catalog/entries/{name}/download?force=1``.
+        """
+        cs: CatalogState = request.app.state.catalog
+        mgr = request.app.state.mgr
+        store = request.app.state.store
+
+        entry = next((e for e in cs.entries if e.get("name") == name), None)
+        if entry is None:
+            raise HTTPException(status_code=404, detail=f"no catalog entry with name={name!r}")
+        fetch_url = entry.get("resolved_src") or entry.get("src") or ""
+        if not fetch_url:
+            raise HTTPException(
+                status_code=400,
+                detail=f"catalog entry {name!r} has no ``src`` / ``resolved_src`` to fetch",
+            )
+        force = request.query_params.get("force") in ("1", "true", "yes")
+        if force:
+            existing = store.get_blob(fetch_url)
+            if existing is not None:
+                store.delete_blob(existing["key"])
+        job = mgr.enqueue(fetch_url)
+        return JSONResponse(
+            {
+                "name": name,
+                "src": fetch_url,
+                "job_id": job.id,
+                "status": job.status,
+            },
+            status_code=202,
+        )
+
     @app.delete("/catalog/entries", status_code=204)
     def delete_catalog_entry(
         request: Request,

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

@@ -74,7 +74,6 @@ def create_app(
     mgr: DownloadManager | None = None,
     streams: StreamRegistry | None = None,
     catalog: CatalogState | None = None,
-    auto_fetch: bool = True,
     keep_query: bool = False,
     max_bytes: int = 0,
     run_lifecycle: bool = False,
@@ -90,8 +89,8 @@ def create_app(
     stable bytes value so cookies stay valid across the fixture's
     lifetime without touching the disk.
 
-    ``store`` / ``mgr`` / ``streams`` / ``auto_fetch`` let tests
-    inject stubs / capture doubles without spawning the real
+    ``store`` / ``mgr`` / ``streams`` let tests inject stubs /
+    capture doubles without spawning the real
     :class:`DownloadManager` worker thread. :func:`server.main`
     passes real instances at daemon start.
     """
@@ -169,7 +168,6 @@ 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
     # 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
@@ -303,15 +301,41 @@ def create_app(
     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. Refresh + Set URL +
-        Add oras + Delete are on the subnav / row forms."""
+        Add oras + Download + Delete are on the subnav / row forms.
+
+        Every entry is enriched with ``downloaded_at`` from the
+        store (or ``None``) + an ``active_job_status`` flag from
+        the DownloadManager so the row's Downloaded pill shows
+        "-" / "queued" / "running" / "cached" without a separate
+        polling round-trip. Same shape ``GET /catalog`` returns to
+        the JSON clients.
+        """
         cs: CatalogState = app.state.catalog
+        store = app.state.store
+        mgr = app.state.mgr
+        # Map url -> latest job status for anything currently
+        # pending / running. Keeps the template cheap: it just
+        # renders a small pill without knowing the pipeline shape.
+        pending: dict[str, str] = {}
+        for job in mgr.list():
+            if job.status in ("queued", "running") and job.url not in pending:
+                pending[job.url] = job.status
+        enriched: list[dict[str, Any]] = []
+        for entry in cs.entries:
+            row = {**entry}
+            fetch_url = entry.get("resolved_src") or entry.get("src") or ""
+            blob = store.get_blob(fetch_url) if fetch_url else None
+            row["downloaded_at"] = blob["fetched_at"] if blob else None
+            row["downloaded_size"] = int(blob["size"]) if blob else None
+            row["active_job_status"] = pending.get(fetch_url)
+            enriched.append(row)
         return render(
             "ui/catalog.html",
             request,
             nav_active="catalog",
             catalog_url=cs.url,
             catalog_env_url=cs.env_url,
-            catalog_entries=cs.entries,
+            catalog_entries=enriched,
             catalog_fetched_at=cs.fetched_at,
             catalog_last_error=cs.last_error,
             catalog_last_info=cs.last_info,
@@ -491,6 +515,56 @@ def create_app(
         app.state.catalog.add_oras_entry(url or "")
         return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
 
+    @app.post("/admin/catalog_add_entry")
+    def ui_admin_catalog_add_entry(
+        name: str = Form(""),
+        src: str = Form(""),
+        sha256: str = Form(""),
+        format: str = Form(""),
+        arch: str = Form(""),
+        size_bytes: str = Form(""),
+        description: str = Form(""),
+        _auth_check: None = Depends(require_ui_auth),
+    ) -> RedirectResponse:
+        """Full-shape add-entry form for the browser. Reuses the same
+        allowlist as the JSON ``POST /catalog/entries`` endpoint;
+        empty fields are dropped so the emitter doesn't persist them.
+        Validation errors surface as ``catalog.last_error`` and the
+        Catalog page renders them; happy path 303s back to
+        /ui/catalog with the entry visible in the table."""
+        cs: CatalogState = app.state.catalog
+        _name = name.strip()
+        _src = src.strip()
+        if not _name or not _src:
+            cs.last_error = "name and src are required"
+            return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
+        if any(e.get("name") == _name for e in cs.entries):
+            cs.last_error = f"catalog entry with name={_name!r} already exists"
+            return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
+        entry: dict[str, Any] = {"name": _name, "src": _src}
+        for key, val in (
+            ("sha256", sha256.strip()),
+            ("format", format.strip()),
+            ("arch", arch.strip()),
+            ("description", description.strip()),
+        ):
+            if val:
+                entry[key] = val
+        sb = size_bytes.strip()
+        if sb:
+            try:
+                entry["size_bytes"] = int(sb)
+            except ValueError:
+                cs.last_error = f"size_bytes must be an integer, got {sb!r}"
+                return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
+        cs.entries.append(entry)
+        cs.last_error = None
+        # Persist to disk so the entry survives a restart.
+        from ._api import _persist_catalog
+
+        _persist_catalog(cs)
+        return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
+
     @app.post("/admin/catalog_delete_entry")
     def ui_admin_catalog_delete_entry(
         name: str = Form(""),
@@ -501,4 +575,34 @@ def create_app(
             app.state.catalog.last_error = msg
         return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
 
+    @app.post("/admin/catalog_download_entry")
+    def ui_admin_catalog_download_entry(
+        name: str = Form(""),
+        force: str = Form(""),
+        _auth_check: None = Depends(require_ui_auth),
+    ) -> RedirectResponse:
+        """Form-encoded sibling of ``POST /catalog/entries/{name}/download``.
+
+        Adds an enqueue for the named entry; a truthy ``force`` field
+        drops any existing cached bytes first so the redownload
+        replaces stale content instead of hitting the dedup-on-active
+        branch in :class:`DownloadManager`.
+        """
+        cs: CatalogState = app.state.catalog
+        entry = next((e for e in cs.entries if e.get("name") == (name or "").strip()), None)
+        if entry is None:
+            cs.last_error = f"no catalog entry with name={name!r}"
+            return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
+        fetch_url = entry.get("resolved_src") or entry.get("src") or ""
+        if not fetch_url:
+            cs.last_error = f"catalog entry {name!r} has no ``src`` / ``resolved_src`` to fetch"
+            return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
+        if force.strip().lower() in ("1", "true", "on", "yes"):
+            existing = app.state.store.get_blob(fetch_url)
+            if existing is not None:
+                app.state.store.delete_blob(existing["key"])
+        app.state.mgr.enqueue(fetch_url)
+        cs.last_error = ""
+        return RedirectResponse(url="/ui/catalog", status_code=status.HTTP_303_SEE_OTHER)
+
     return app

{withcache-0.9.1 → withcache-0.10.0}/src/withcache/_templates/ui/catalog.html

@@ -85,25 +85,94 @@
                 {% endif %}
             </div>
         </form>
-        {# Add oras: append a fresh oras:// entry to the in-memory
-           catalog. Useful for one-off pulls that aren't in the
-           upstream manifest. #}
+        {# Add oras: append a fresh oras:// entry. The manifest walk
+           populates sha256/format/size from the registry so the
+           operator doesn't have to type them. #}
         <form method="post" action="/admin/catalog_add_oras" class="mt-2 mb-0">
             <label for="catalog-add-oras-input" class="form-label small mb-1">
-                Add oras:// entry
+                Add oras:// entry (registry auto-resolves)
             </label>
             <div class="d-flex gap-2">
                 <input type="text" class="form-control form-control-sm font-monospace"
                        id="catalog-add-oras-input" name="url" required
                        placeholder="oras://ghcr.io/owner/repo:tag">
                 <button type="submit" class="btn btn-sm btn-outline-primary text-nowrap">
-                    <i class="bi bi-plus-circle me-1"></i>Add
+                    <i class="bi bi-plus-circle me-1"></i>Add oras
                 </button>
             </div>
         </form>
     </div>
 </div>
 
+<div class="card mb-3">
+    <div class="card-header bg-light fw-semibold py-2">
+        <i class="bi bi-plus-square me-1"></i>Add HTTPS entry
+    </div>
+    <div class="card-body small">
+        <p class="text-muted mb-2">
+            Add one https:// catalog entry. Operators typically fill
+            <em>name</em>, <em>src</em>, and <em>sha256</em>; other
+            fields are optional. For <em>oras://</em> entries use the
+            form above instead (the registry walk fills sha256 /
+            format / size automatically).
+        </p>
+        <form method="post" action="/admin/catalog_add_entry" class="mb-0">
+            <div class="row g-2 mb-2">
+                <div class="col-md-4">
+                    <label class="form-label small mb-1" for="ce-name">Name</label>
+                    <input type="text" class="form-control form-control-sm"
+                           id="ce-name" name="name" required
+                           placeholder="my-appliance-2026.W28">
+                </div>
+                <div class="col-md-8">
+                    <label class="form-label small mb-1" for="ce-src">Source URL</label>
+                    <input type="url" class="form-control form-control-sm font-monospace"
+                           id="ce-src" name="src" required
+                           placeholder="https://example.com/appliance.img.gz">
+                </div>
+            </div>
+            <div class="row g-2 mb-2">
+                <div class="col-md-6">
+                    <label class="form-label small mb-1" for="ce-sha256">SHA-256</label>
+                    <input type="text" class="form-control form-control-sm font-monospace"
+                           id="ce-sha256" name="sha256"
+                           pattern="[0-9a-fA-F]{64}"
+                           placeholder="64-hex, e.g. abcdef0123... (leave blank if unknown)">
+                </div>
+                <div class="col-md-3">
+                    <label class="form-label small mb-1" for="ce-format">Format</label>
+                    <input type="text" class="form-control form-control-sm"
+                           id="ce-format" name="format"
+                           placeholder="img.gz | img.zst | qcow2">
+                </div>
+                <div class="col-md-3">
+                    <label class="form-label small mb-1" for="ce-arch">Arch</label>
+                    <input type="text" class="form-control form-control-sm"
+                           id="ce-arch" name="arch"
+                           placeholder="x86_64 | aarch64">
+                </div>
+            </div>
+            <div class="row g-2 mb-2">
+                <div class="col-md-4">
+                    <label class="form-label small mb-1" for="ce-size">Size (bytes)</label>
+                    <input type="number" min="0" class="form-control form-control-sm"
+                           id="ce-size" name="size_bytes"
+                           placeholder="optional">
+                </div>
+                <div class="col-md-8">
+                    <label class="form-label small mb-1" for="ce-desc">Description</label>
+                    <input type="text" class="form-control form-control-sm"
+                           id="ce-desc" name="description"
+                           placeholder="Optional operator prose (shown on bty's /ui/images)">
+                </div>
+            </div>
+            <button type="submit" class="btn btn-sm btn-primary">
+                <i class="bi bi-plus-circle me-1"></i>Add entry
+            </button>
+        </form>
+    </div>
+</div>
+
 <div class="card mb-3">
     <div class="card-header bg-light fw-semibold py-2">
         <i class="bi bi-list-ul me-1"></i>Catalog entries ({{ catalog_entries|length }})
@@ -116,7 +185,8 @@
                     <th>Source</th>
                     <th>Format</th>
                     <th>SHA-256</th>
-                    <th class="text-end" style="width: 1%; white-space: nowrap;">Action</th>
+                    <th title="When withcache last fetched this entry's bytes to disk. bty's flash chain + nbdmux's export creation both refuse entries with no timestamp here.">Downloaded</th>
+                    <th class="text-end" style="width: 1%; white-space: nowrap;">Actions</th>
                 </tr>
             </thead>
             <tbody>
@@ -137,8 +207,45 @@
                     <td class="small font-monospace">
                         {% if e.get('sha256') %}{{ e.sha256[:12] }}...{% else %}<span class="text-muted">-</span>{% endif %}
                     </td>
+                    <td class="small">
+                        {% if e.get('active_job_status') %}
+                        <span class="badge bg-info text-dark" title="Download in flight">
+                            <i class="bi bi-arrow-down-circle me-1"></i>{{ e.active_job_status }}
+                        </span>
+                        {% elif e.get('downloaded_at') %}
+                        <span class="badge bg-success" title="{{ e.downloaded_at }}">
+                            <i class="bi bi-check-circle me-1"></i>cached
+                        </span>
+                        {% else %}
+                        <span class="text-muted">-</span>
+                        {% endif %}
+                    </td>
                     <td class="text-end text-nowrap">
-                        <form method="post" action="/admin/catalog_delete_entry" class="d-inline m-0"
+                        {# Download / Redownload: enqueue an explicit fetch
+                           of this entry's src into the local cache. The
+                           button label switches on ``downloaded_at`` so
+                           the operator sees whether the click will fill
+                           an empty slot or replace stale bytes. #}
+                        <form method="post" action="/admin/catalog_download_entry"
+                              class="d-inline m-0">
+                            <input type="hidden" name="name" value="{{ e.get('name', '') }}">
+                            {% if e.get('downloaded_at') %}
+                            <input type="hidden" name="force" value="1">
+                            <button type="submit" class="btn btn-sm btn-outline-primary"
+                                    title="Delete the cached bytes and refetch from origin"
+                                    {% if e.get('active_job_status') %}disabled{% endif %}>
+                                <i class="bi bi-arrow-repeat"></i> Redownload
+                            </button>
+                            {% else %}
+                            <button type="submit" class="btn btn-sm btn-primary"
+                                    title="Fetch this entry's bytes into the local cache"
+                                    {% if e.get('active_job_status') %}disabled{% endif %}>
+                                <i class="bi bi-download"></i> Download
+                            </button>
+                            {% endif %}
+                        </form>
+                        <form method="post" action="/admin/catalog_delete_entry"
+                              class="d-inline m-0"
                               onsubmit="return confirm('Delete catalog entry {{ e.get('name', '') }}?');">
                             <input type="hidden" name="name" value="{{ e.get('name', '') }}">
                             <button type="submit" class="btn btn-sm btn-outline-danger"
@@ -150,7 +257,7 @@
                 </tr>
                 {% endfor %}
                 {% if not catalog_entries %}
-                <tr><td colspan="5" class="text-muted text-center py-3">
+                <tr><td colspan="6" class="text-muted text-center py-3">
                     No catalog entries yet. The startup fetch will populate
                     this list; failures land in the source card above.
                 </td></tr>

{withcache-0.9.1 → withcache-0.10.0}/src/withcache/client.py

@@ -214,6 +214,35 @@ def add_catalog_entry(
     )
 
 
+def download_catalog_entry(
+    server: str,
+    name: str,
+    *,
+    force: bool = False,
+    timeout: float = CATALOG_TIMEOUT,
+    password: str | None = None,
+) -> dict[str, Any]:
+    """POST ``/catalog/entries/<name>/download``: enqueue an explicit
+    fetch of the entry's ``src`` into the local cache.
+
+    Since v0.10.0 withcache does no auto-fetch on cache miss, so
+    every downstream consumer (bty flash chain, nbdmux export
+    creation) refuses entries that haven't been downloaded. This is
+    the one-place control.
+
+    ``force=True`` deletes any existing cached bytes first so a
+    corrupted / stale entry can be replaced without a manual
+    intermediate delete. Returns the enqueued job's ``{id, status}``.
+
+    Raises :class:`WithcacheError` on 404 (no such entry) / 400
+    (entry has no fetchable src) / transport failure.
+    """
+    path = f"/catalog/entries/{urllib.parse.quote(name, safe='')}/download"
+    if force:
+        path += "?force=1"
+    return _catalog_request("POST", server, path, timeout=timeout, password=password)
+
+
 def delete_catalog_entry(
     server: str,
     name: str,

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

@@ -1022,12 +1022,6 @@ def main():
     ap.add_argument(
         "--workers", type=int, default=2, help="concurrent background download workers (default: 2)"
     )
-    ap.add_argument(
-        "--curate",
-        action="store_true",
-        help="require an operator to approve each pull (default: auto-fetch a "
-        "missed artifact in the background so the next request hits)",
-    )
     ap.add_argument(
         "--max-bytes",
         default="0",
@@ -1040,10 +1034,12 @@ def main():
     mgr = DownloadManager(store, workers=args.workers)
     auth_password = os.environ.get("WITHCACHE_ADMIN_PASSWORD")
 
+    # Since v0.10.0 there is no auto-fetch on miss: the operator
+    # hits Download on /ui/catalog to enqueue a fetch. The daemon
+    # is always in "curate" mode; the --curate flag went with it.
     print(
         f"withcache cache-host on http://{args.host}:{args.port}  "
         f"(data={store.data_dir}, keep_query={args.keep_query}, workers={args.workers}, "
-        f"mode={'curate' if args.curate else 'auto-fetch'}, "
         f"max_bytes={'unlimited' if not store.max_bytes else human_size(store.max_bytes)})",
         flush=True,
     )
@@ -1057,7 +1053,6 @@ def main():
         data_dir=store.data_dir,
         store=store,
         mgr=mgr,
-        auto_fetch=not args.curate,
         keep_query=args.keep_query,
         max_bytes=parse_size(args.max_bytes),
         run_lifecycle=True,

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

@@ -172,52 +172,27 @@ class BlobHeadTests(_BlobBase):
         self.assertEqual(r.status_code, 200)
 
 
-class BlobMissAutoFetchTests(_BlobBase):
-    def test_miss_enqueues_on_auto_fetch(self) -> None:
-        url = "https://example.invalid/enqueue.bin"
-        self.client.get("/blob", params={"url": url})
-        self.assertEqual(len(self.enqueue_calls), 1)
-        self.assertEqual(self.enqueue_calls[0][0], url)
-
-    def test_miss_forwards_authorization_header(self) -> None:
-        url = "https://example.invalid/token-gated.bin"
-        self.client.get(
-            "/blob",
-            params={"url": url},
-            headers={"Authorization": "Bearer xyz123"},
-        )
-        self.assertEqual(len(self.enqueue_calls), 1)
-        _, headers = self.enqueue_calls[0]
-        self.assertIsNotNone(headers)
-        self.assertEqual(headers["Authorization"], "Bearer xyz123")
-
-    def test_miss_no_authorization_no_headers_forwarded(self) -> None:
-        self.client.get("/blob", params={"url": "https://example.invalid/anon.bin"})
-        self.assertEqual(self.enqueue_calls[0][1], None)
-
-
-class BlobAutoFetchOffTests(_BlobBase):
-    def setUp(self) -> None:
-        super().setUp()
-        self.client.close()
-        outer = self
-
-        class _CaptureMgr:
-            def enqueue(self, url: str, headers: dict[str, str] | None = None) -> None:
-                outer.enqueue_calls.append((url, headers))
+class BlobMissTests(_BlobBase):
+    """Since v0.10.0 auto-fetch on miss is gone. A miss records the
+    request-count against the misses table (for the operator's
+    /ui/misses page) and returns 404 with a hint pointing at the
+    /ui/catalog Download button; no enqueue fires."""
 
-        self.app = create_app(
-            data_dir=self._tmpdir + "-curate",
-            secret_key=TEST_SECRET,
-            mgr=_CaptureMgr(),
-            auto_fetch=False,
-        )
-        self.client = TestClient(self.app, follow_redirects=False)
-
-    def test_miss_records_but_does_not_enqueue(self) -> None:
+    def test_miss_records_but_never_enqueues(self) -> None:
         pre = len(self.enqueue_calls)
         r = self.client.get("/blob", params={"url": "https://example.invalid/curated.bin"})
         self.assertEqual(r.status_code, 404)
+        self.assertIn("Download", r.text)
+        self.assertEqual(len(self.enqueue_calls), pre)
+
+    def test_miss_with_authorization_header_still_never_enqueues(self) -> None:
+        pre = len(self.enqueue_calls)
+        r = self.client.get(
+            "/blob",
+            params={"url": "https://example.invalid/token-gated.bin"},
+            headers={"Authorization": "Bearer xyz123"},
+        )
+        self.assertEqual(r.status_code, 404)
         self.assertEqual(len(self.enqueue_calls), pre)
 
 

{withcache-0.9.1 → withcache-0.10.0}/tests/test_fastapi_catalog_api.py

@@ -180,6 +180,73 @@ class AddCatalogEntryTests(_CatalogApiBase):
         self.assertEqual(r.status_code, 409)
 
 
+class DownloadCatalogEntryTests(_CatalogApiBase):
+    """POST /catalog/entries/{name}/download enqueues an explicit
+    fetch of the entry's src via the DownloadManager. Introduced
+    when auto-fetch on cache miss was retired; the operator (or a
+    sibling service) is the one who triggers a download now."""
+
+    def setUp(self) -> None:
+        super().setUp()
+        outer = self
+        self.enqueued: list[str] = []
+
+        class _CaptureMgr:
+            def enqueue(self, url: str, headers: dict[str, str] | None = None):  # type: ignore[no-untyped-def]
+                del headers
+                outer.enqueued.append(url)
+                return type("Job", (), {"id": len(outer.enqueued), "status": "queued"})()
+
+            def list(self):  # noqa: A003 - matching the DownloadManager API
+                return []
+
+        self.app.state.mgr = _CaptureMgr()
+
+    def test_download_enqueues_and_returns_job(self) -> None:
+        self.catalog.entries = [
+            {
+                "name": "demo",
+                "src": "https://example/demo.img.gz",
+                "resolved_src": "https://example/demo.img.gz",
+            }
+        ]
+        r = self.client.post("/catalog/entries/demo/download")
+        self.assertEqual(r.status_code, 202)
+        body = r.json()
+        self.assertEqual(body["name"], "demo")
+        self.assertEqual(body["status"], "queued")
+        self.assertEqual(self.enqueued, ["https://example/demo.img.gz"])
+
+    def test_download_unknown_entry_404s(self) -> None:
+        r = self.client.post("/catalog/entries/does-not-exist/download")
+        self.assertEqual(r.status_code, 404)
+        self.assertEqual(self.enqueued, [])
+
+    def test_download_entry_without_src_400s(self) -> None:
+        # Impossible via the JSON add path (src is required) but a
+        # hand-edited catalog.toml can produce this. Refuse rather
+        # than enqueue an empty URL.
+        self.catalog.entries = [{"name": "demo"}]
+        r = self.client.post("/catalog/entries/demo/download")
+        self.assertEqual(r.status_code, 400)
+        self.assertEqual(self.enqueued, [])
+
+    def test_download_prefers_resolved_src(self) -> None:
+        """oras:// entries carry a canonical HTTPS ``resolved_src``
+        (the blob URL the manifest walk produced). The download
+        target must be the resolved URL, not the raw ``oras://``
+        ref, so the fetch worker doesn't have to re-resolve."""
+        self.catalog.entries = [
+            {
+                "name": "demo",
+                "src": "oras://ghcr.io/owner/repo:tag",
+                "resolved_src": "https://ghcr.io/v2/owner/repo/blobs/sha256:abc",
+            }
+        ]
+        self.client.post("/catalog/entries/demo/download")
+        self.assertEqual(self.enqueued, ["https://ghcr.io/v2/owner/repo/blobs/sha256:abc"])
+
+
 class DeleteCatalogEntryTests(_CatalogApiBase):
     def test_delete_removes_entry(self) -> None:
         self.catalog.entries = [{"name": "demo", "src": "https://example/demo.img.gz"}]