sourcelock 0.1.0__py3-none-any.whl

hc_source/cache.py

@@ -0,0 +1,664 @@
+"""On-disk caches, built so that a receipt cannot become a lie.
+
+Two caches, with deliberately different defaults, because they carry different
+risks.
+
+**The HTTP cache is on by default.** It never serves a body without asking
+upstream first: an entry is stored only when the response carried an ``ETag`` or
+a ``Last-Modified``, and a hit is a conditional request that came back ``304 Not
+Modified``. The bytes are therefore confirmed current by the source itself on
+every use. What it saves is the transfer, not the round trip -- which is the
+expensive part for the 15 MB LEIE file and the 32 MB MCD zip, and for an agent
+looping hundreds of MCP calls over the same release.
+
+**The tool-result cache is off by default.** It answers without asking anyone,
+so it trades freshness for latency, and that is an operator's decision rather
+than ours. Set ``HC_SOURCE_TOOL_CACHE_TTL`` to a number of seconds to enable it.
+
+The rule both obey, and the reason this module exists rather than a dict in each
+adapter:
+
+    **A cache hit reports the retrieval time of the bytes, never the time of
+    the hit.**
+
+Round-1 finding: ``build_receipt`` stamped ``utcnow()`` when the receipt was
+assembled, so anything served out of an adapter's process cache produced a
+receipt claiming it had just been to CMS. Wave 2 moved the stamp to the fetch
+boundary. A disk cache is the same bug waiting at a longer timescale, so
+``retrieved_at`` is stored with the entry and restored with it, ``cache_hit``
+says plainly that this answer came from a cache, and ``revalidated_at`` records
+when upstream last confirmed the bytes are still current.
+
+Configuration:
+
+============================== ===========================================
+``HC_SOURCE_CACHE_DIR``        Where to keep it. ``off``/``0`` disables both
+                               caches entirely. Default: ``$XDG_CACHE_HOME``
+                               (or ``~/.cache``) ``/sourcelock``.
+``HC_SOURCE_TOOL_CACHE_TTL``   Seconds a tool result may be reused. ``0``
+                               (the default) means the result cache is off.
+============================== ===========================================
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+__all__ = [
+    "CACHE_DIR_ENV",
+    "CachedResponse",
+    "TOOL_TTL_ENV",
+    "cache_dir",
+    "cache_stats",
+    "clear_cache",
+    "http_key",
+    "read_http",
+    "request_signature",
+    "read_tool",
+    "tool_key",
+    "tool_ttl",
+    "write_http",
+    "write_tool",
+]
+
+CACHE_DIR_ENV = "HC_SOURCE_CACHE_DIR"
+TOOL_TTL_ENV = "HC_SOURCE_TOOL_CACHE_TTL"
+
+_OFF = {"0", "off", "no", "false", "none", ""}
+
+#: Bump when the on-disk layout changes so that old entries are simply missed
+#: rather than misread. A cache that mis-parses an old entry is worse than a
+#: cold cache in exactly the way this product cannot afford.
+#:
+#: 2: the key and the stored entry cover the request's headers and its byte
+#: ceiling. A version-1 entry was keyed by URL alone, so a ranged probe's 206
+#: could be replayed to a caller that asked for the whole file -- see
+#: :func:`http_key`.
+#:
+#: 3: header VALUES enter the key verbatim. A version-2 key collapsed internal
+#: whitespace in them, so two requests that put different bytes on the wire
+#: could share an entry -- the ranged-vs-full replay again, one spelling down.
+#: See :func:`_key_headers`.
+#:
+#: 4: headers enter the key after HTTPX has encoded the defaults and caller
+#: values into the request's actual wire model. A version-3 key described the
+#: caller's pre-merge object instead, so it could be coarser than the request.
+LAYOUT_VERSION = "4"
+
+#: Request headers whose value must never be written to disk. The NAME still
+#: enters the key (asking as somebody is not the same request as asking as
+#: nobody) and so does a digest of the value, so two different tokens cannot
+#: share an entry -- but the token itself never lands in the cache directory.
+_SECRET_HEADERS = frozenset(
+    {
+        "authorization",
+        "proxy-authorization",
+        "cookie",
+        "authentication",
+        "x-api-key",
+        "api-key",
+        "x-auth-token",
+        "x-amz-security-token",
+    }
+)
+
+#: The transport's own ``If-None-Match``/``If-Modified-Since`` never reach the
+#: key, and not because they are filtered out: :func:`hc_source.http._read`
+#: keys on the fully merged base request and adds the stored validator
+#: afterwards. So revalidation still hits, and a conditional header already in
+#: that base request came from the caller, goes on the wire, and can change what
+#: comes back -- which is why there is no drop-list here. A key that ignores a
+#: header the request actually sends is a key coarser than its request.
+
+
+def cache_dir() -> Path | None:
+    """The cache root, or ``None`` when caching is switched off."""
+    raw = os.environ.get(CACHE_DIR_ENV)
+    if raw is not None:
+        if raw.strip().lower() in _OFF:
+            return None
+        return Path(raw).expanduser()
+    base = os.environ.get("XDG_CACHE_HOME")
+    root = Path(base).expanduser() if base else Path.home() / ".cache"
+    return root / "sourcelock"
+
+
+def tool_ttl() -> float:
+    """Seconds a tool result may be reused. ``0`` means the result cache is off."""
+    raw = os.environ.get(TOOL_TTL_ENV)
+    if raw is None:
+        return 0.0
+    try:
+        value = float(raw)
+    except ValueError:
+        return 0.0
+    return max(0.0, value)
+
+
+def _slot(kind: str, key: str) -> Path | None:
+    root = cache_dir()
+    if root is None:
+        return None
+    return root / LAYOUT_VERSION / kind / key[:2] / key
+
+
+def _write_atomic(path: Path, payload: bytes) -> None:
+    """Temp file plus rename, so an interrupted write leaves no half entry."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".tmp-")
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(payload)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# HTTP responses
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CachedResponse:
+    """A stored response body plus everything a receipt needs about it."""
+
+    url: str
+    status: int | None
+    body: bytes
+    sha256: str
+    headers: dict[str, str]
+    #: When the bytes were read from upstream. Restored, never re-stamped.
+    retrieved_at: datetime
+    #: When upstream last confirmed these bytes are current (a 304, or the
+    #: original 200). Distinct from ``retrieved_at`` on purpose: "you still have
+    #: the right bytes" and "these bytes are new" are different statements.
+    revalidated_at: datetime
+    #: The canonical description of the request that produced these bytes -- see
+    #: :func:`request_signature`. Stored beside the body and checked on read, so
+    #: a hash collision or a hand-edited cache directory cannot hand a caller a
+    #: representation it did not ask for.
+    request_signature: str = ""
+
+    @property
+    def etag(self) -> str | None:
+        return self.headers.get("etag")
+
+    @property
+    def last_modified(self) -> str | None:
+        return self.headers.get("last-modified")
+
+    def conditional_headers(self) -> dict[str, str]:
+        headers = {}
+        if self.etag:
+            headers["If-None-Match"] = self.etag
+        if self.last_modified:
+            headers["If-Modified-Since"] = self.last_modified
+        return headers
+
+
+def _header_items(headers: Any) -> list[tuple[bytes, bytes]]:
+    """Every HTTPX-encoded occurrence, in wire order and wire bytes.
+
+    HTTPX is the transport's header encoder, so its ``raw`` pairs are the
+    request model the key has to describe. Constructing ``Headers`` here also
+    means ``b"foo"`` and ``"b'foo'"`` stay as different wire values instead of
+    colliding through Python's ``str(bytes)`` representation. Repeated
+    occurrences stay repeated; folding them through ``items()`` would instead
+    describe one comma-joined line that the transport did not send.
+    """
+    if not headers:
+        return []
+    return httpx.Headers(headers).raw
+
+
+def _key_headers(headers: Any) -> list[list[str]]:
+    """Request headers as key material -- verbatim, with no secret written down.
+
+    Every header in the merged base request is included, defaults and caller
+    values alike, not a hand-picked list of the ones we currently think select
+    a representation. ``Range`` is the one that broke this product, but
+    ``Accept``, ``Accept-Language``, an API version pin and a tenant id all
+    change what comes back too, and a header we did not think of is exactly the
+    one an allow-list drops.
+
+    Values are encoded by HTTPX and copied from its raw byte pairs. Header NAMES
+    are case-insensitive per RFC 9110 and are lowered; values are not ours to
+    canonicalize, and an earlier version of this function canonicalized them
+    anyway -- it collapsed internal whitespace, so ``Range: bytes=0-2047`` and
+    ``Range: bytes=0-  2047``
+    produced one key while two different byte strings went on the wire. That is
+    the ranged-probe replay in a different spelling: a key coarser than the
+    request it stands for, and therefore a 304 for one representation that can
+    hand back another representation's body with an upstream-confirmed receipt
+    on it. Whitespace is the example; the rule is that no lossy step belongs
+    anywhere on this path.
+
+    Occurrences are a LIST of pairs in the order given, not a dict. A dict keyed
+    by the folded name remembers only the last of ``{"Accept": "text/csv",
+    "accept": "application/json"}`` while both go on the wire, and for a
+    repeated name the order is the meaning.
+
+    Secret-bearing headers are the one exception, and a lossless one: the value
+    is replaced by a digest of the RAW bytes, so two tokens stay distinguishable
+    and no token reaches the cache directory. The name-match is done on a
+    stripped name so that an odd spelling redacts rather than leaks; the
+    stripping decides redaction only and never touches key material.
+    """
+    pairs: list[list[str]] = []
+    for raw_name, raw_value in _header_items(headers):
+        name = raw_name.lower().decode("latin-1")
+        # latin-1 is deliberately a one-to-one rendering of arbitrary bytes,
+        # not a text normalization. JSON then gives the signature stable text.
+        value = raw_value.decode("latin-1")
+        if name.strip() in _SECRET_HEADERS:
+            value = "sha256:" + hashlib.sha256(raw_value).hexdigest()
+        pairs.append([name, value])
+    return pairs
+
+
+def request_signature(
+    url: str,
+    *,
+    params: Any = None,
+    scope: str = "",
+    headers: Any = None,
+    max_bytes: int | None = None,
+) -> str:
+    """Canonical text describing WHICH representation a request asked for.
+
+    The key is a digest of this; the entry stores it verbatim and
+    :func:`read_http` refuses an entry whose signature is not the one the caller
+    is asking under. Two channels rather than one because the failure this
+    guards against is silent by construction: a body served under the wrong
+    request is still a well-formed body, and the receipt would attest to it.
+
+    **The invariant: this function is injective with respect to what actually
+    goes on the wire.** Two requests that would send different bytes must not
+    produce the same text here, because the entry a signature names is a body,
+    and a 304 for one request replaying another request's body is the exact
+    failure the ranged probe caused. Distinguishing MORE than the wire does is
+    merely a cache miss; distinguishing less is a wrong answer with a receipt on
+    it, so every step on this path either preserves information or is a digest
+    (reversible enough: distinct inputs stay distinct). Nothing here trims,
+    case-folds a value, sorts away an occurrence, or drops an empty one.
+
+    ``default=str`` is not an exception: a parameter reaches the query string
+    through ``str`` too, so rendering it that way here matches the wire rather
+    than blurring it.
+    """
+    return json.dumps(
+        {
+            "url": url,
+            "params": _wire_stable(params),
+            "scope": scope,
+            "headers": _key_headers(headers),
+            "max_bytes": max_bytes,
+        },
+        sort_keys=True,
+        default=str,
+    )
+
+
+def http_key(
+    url: str,
+    *,
+    params: Any = None,
+    scope: str = "",
+    headers: Any = None,
+    max_bytes: int | None = None,
+) -> str:
+    """Cache key for one request.
+
+    ``scope`` is where a caller binds an entry to the version of the artifact it
+    is reading. The crosswalk bug this product had -- a cache keyed by a
+    constant URL but stamped with a freshly fetched schedule version, so week
+    N's rows were served claiming week N+1 -- is exactly what an empty scope
+    permits. When the identity of what you are fetching is decided by something
+    other than the URL, put it here.
+
+    ``headers`` and ``max_bytes`` are in the key because a URL does not name a
+    representation on its own. LEIE revalidates the 15 MB exclusion file with a
+    ``Range: bytes=0-2047`` probe; keyed by URL alone, that probe's 2 KB body
+    was stored under the full file's key, and the next full read got the first
+    two kilobytes back -- with ``cache_hit`` true, an upstream-confirmed
+    receipt, and an exclusion index missing 99.99% of its rows. A screen that
+    answers "not excluded" from that is the worst answer this product can give.
+    The byte ceiling is in the key for the same reason: bytes stored under a
+    30 MB allowance are not an answer to a call that declared a 16 MB one.
+    """
+    return hashlib.sha256(
+        request_signature(
+            url, params=params, scope=scope, headers=headers, max_bytes=max_bytes
+        ).encode("utf-8")
+    ).hexdigest()
+
+
+def _stable(value: Any) -> Any:
+    """Order-independent rendering, for keys whose identity is a parameter SET.
+
+    Right for :func:`tool_key`: ``valid_on(code=X, on=Y)`` is the same call
+    however the dict was built, and the same call has the same answer. Wrong for
+    a URL, which is why :func:`request_signature` does not use it -- see
+    :func:`_wire_stable`.
+    """
+    if isinstance(value, dict):
+        return {str(k): _stable(v) for k, v in sorted(value.items())}
+    if isinstance(value, (list, tuple)):
+        return [_stable(v) for v in value]
+    return value
+
+
+def _wire_stable(value: Any) -> Any:
+    """Query parameters as an ORDERED list of pairs rather than a mapping.
+
+    ``json.dumps(sort_keys=True)`` sorts every nested mapping it is handed, and
+    a sorted mapping is a lossy rendering of a query string: ``{"b": 2, "a": 1}``
+    and ``{"a": 1, "b": 2}`` are one signature and two different URLs. Pairs in
+    encounter order are what httpx will actually serialize, so a dict and the
+    equivalent sequence of pairs land on the same text -- they land on the same
+    wire bytes too, so that is agreement, not a collision.
+
+    Encoding is delegated to HTTPX, the same library that will serialize the
+    request, for the same reason the header key is copied from its raw byte
+    pairs: a signature that renders the request itself, rather than a private
+    guess at how it renders, cannot disagree with the wire. An earlier version
+    walked dicts by hand and returned anything else unchanged, so a mapping
+    that was not a ``dict`` -- the annotation says ``Mapping``, and
+    ``QueryParams`` and ``MappingProxyType`` are both mappings -- fell through
+    to ``json.dumps(default=str)``. Two mappings with one ``str()`` then shared
+    a signature while two different query strings went on the wire: the same
+    replay this file has now been rewritten for six times, wearing parameters
+    instead of headers.
+
+    Un-renderable parameters raise rather than degrade. A signature we cannot
+    compute honestly is not a cache miss, it is a request we do not understand,
+    and answering it from a directory keyed by a guess is how this fails.
+    """
+    if value is None:
+        return None
+    try:
+        return [[name, item] for name, item in httpx.QueryParams(value).multi_items()]
+    except (TypeError, ValueError, AttributeError) as exc:
+        raise TypeError(
+            f"query parameters cannot be rendered for a cache key: {type(value).__name__}"
+        ) from exc
+
+
+def read_http(key: str, *, signature: str | None = None) -> CachedResponse | None:
+    """The stored response for ``key``, or ``None``.
+
+    Any unreadable or unrecognised entry is a miss. A cache that guesses at a
+    corrupt entry hands back bytes nobody can vouch for, and the receipt would
+    attest to them.
+
+    ``signature`` is the caller's :func:`request_signature`. When it is given
+    and the entry does not carry the same one, the entry is a miss: the key
+    already covers the request, so a mismatch means the directory is not what
+    this build thinks it is, and the safe reading of that is "fetch it again".
+    """
+    slot = _slot("http", key)
+    if slot is None:
+        return None
+    meta_path, body_path = slot.with_suffix(".meta.json"), slot.with_suffix(".body")
+    try:
+        meta = json.loads(meta_path.read_text(encoding="utf-8"))
+        body = body_path.read_bytes()
+    except (OSError, ValueError):
+        return None
+
+    digest = hashlib.sha256(body).hexdigest()
+    if digest != meta.get("sha256"):
+        # The body on disk is not the body the entry describes. Treat it as a
+        # miss and let the next write replace it.
+        return None
+    if signature is not None and meta.get("request_signature") != signature:
+        return None
+    try:
+        return CachedResponse(
+            url=meta["url"],
+            status=meta["status"],
+            body=body,
+            sha256=digest,
+            headers=meta["headers"],
+            retrieved_at=datetime.fromisoformat(meta["retrieved_at"]),
+            revalidated_at=datetime.fromisoformat(meta["revalidated_at"]),
+            request_signature=meta.get("request_signature", ""),
+        )
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+_NO_VALIDATOR = "no ETag and no Last-Modified: nothing to revalidate against"
+
+#: 206 bodies are never stored. The key covers ``Range`` now, so a partial
+#: could only be replayed to a caller asking for the same range -- but a range
+#: request is a probe, its answer is a fragment of a file, and one server that
+#: ignores ``If-Range`` on the way back turns that fragment into a whole
+#: document as far as the parser is concerned. There is nothing to gain: the
+#: probes this product makes are 2 KB.
+_PARTIAL_CONTENT = (
+    "206 Partial Content: SourceLock does not store fragments, because a "
+    "fragment replayed as a whole document is a truncated parse with a "
+    "confident receipt on it"
+)
+
+
+def note_uncacheable(key: str, url: str, reason: str = _NO_VALIDATOR) -> None:
+    """Record that an endpoint cannot be cached, and why, for ``cache info``.
+
+    Without this, an operator who enables the cache and then sees ``0 entries``
+    has no way to tell "the cache is broken" from "CMS does not send validators
+    on that endpoint". The second is true of most of the Coverage API, and it is
+    a fact about upstream that nobody should have to discover with curl.
+    """
+    slot = _slot("uncacheable", key)
+    if slot is None:
+        return
+    try:
+        _write_atomic(
+            slot.with_suffix(".json"),
+            json.dumps(
+                {"url": url, "reason": reason, "seen_at": _utcnow().isoformat()},
+                sort_keys=True,
+            ).encode("utf-8"),
+        )
+    except OSError:
+        return
+
+
+def write_http(key: str, entry: CachedResponse) -> bool:
+    """Store a response. Returns False when nothing was stored.
+
+    A response with no ``ETag`` and no ``Last-Modified`` is NOT stored: without
+    a validator there is no way to ask upstream whether the bytes are still
+    current, and this cache never serves bytes it has not just re-confirmed.
+    Nor is anything but a plain ``200``: see :data:`_PARTIAL_CONTENT`.
+    """
+    slot = _slot("http", key)
+    if slot is None:
+        return False
+    if entry.status == 206:
+        note_uncacheable(key, entry.url, _PARTIAL_CONTENT)
+        return False
+    if entry.status is not None and entry.status != 200:
+        return False
+    if not (entry.etag or entry.last_modified):
+        note_uncacheable(key, entry.url)
+        return False
+    meta = {
+        "layout": LAYOUT_VERSION,
+        "url": entry.url,
+        "status": entry.status,
+        "sha256": entry.sha256,
+        "headers": entry.headers,
+        "retrieved_at": entry.retrieved_at.astimezone(timezone.utc).isoformat(),
+        "revalidated_at": entry.revalidated_at.astimezone(timezone.utc).isoformat(),
+        "request_signature": entry.request_signature,
+    }
+    try:
+        _write_atomic(slot.with_suffix(".body"), entry.body)
+        _write_atomic(
+            slot.with_suffix(".meta.json"),
+            json.dumps(meta, sort_keys=True).encode("utf-8"),
+        )
+    except OSError:
+        # A cache that cannot be written is a slow product, not a broken one.
+        return False
+    return True
+
+
+def touch_http(key: str, entry: CachedResponse, revalidated_at: datetime) -> None:
+    """Record that upstream just confirmed a stored entry is still current."""
+    slot = _slot("http", key)
+    if slot is None:
+        return
+    meta_path = slot.with_suffix(".meta.json")
+    try:
+        meta = json.loads(meta_path.read_text(encoding="utf-8"))
+        meta["revalidated_at"] = revalidated_at.astimezone(timezone.utc).isoformat()
+        _write_atomic(meta_path, json.dumps(meta, sort_keys=True).encode("utf-8"))
+    except (OSError, ValueError):
+        return
+
+
+def parse_http_date(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if parsed is None:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# tool results
+# ---------------------------------------------------------------------------
+
+
+def tool_key(tool: str, params: Any, *, lockfile_hash: str = "") -> str:
+    """Cache key for one tool call.
+
+    The lockfile hash is in the key because the lockfile is what pins the source
+    versions an answer was computed against. Re-pinning a source must not leave
+    yesterday's answers reachable under today's pins -- that would be a cached
+    answer citing a release it was never derived from.
+    """
+    material = json.dumps(
+        {"tool": tool, "params": _stable(params), "lock": lockfile_hash},
+        sort_keys=True,
+        default=str,
+    )
+    return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+
+def read_tool(key: str, ttl: float) -> tuple[Any, dict] | None:
+    """``(data, receipt_dict)`` for a live entry, or ``None``."""
+    if ttl <= 0:
+        return None
+    slot = _slot("tools", key)
+    if slot is None:
+        return None
+    path = slot.with_suffix(".json")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        stored_at = datetime.fromisoformat(payload["stored_at"])
+    except (OSError, ValueError, KeyError):
+        return None
+    if (_utcnow() - stored_at).total_seconds() > ttl:
+        return None
+    try:
+        return payload["data"], payload["receipt"]
+    except KeyError:
+        return None
+
+
+def write_tool(key: str, data: Any, receipt: dict) -> bool:
+    slot = _slot("tools", key)
+    if slot is None:
+        return False
+    payload = {
+        "layout": LAYOUT_VERSION,
+        "stored_at": _utcnow().isoformat(),
+        "data": data,
+        "receipt": receipt,
+    }
+    try:
+        _write_atomic(
+            slot.with_suffix(".json"),
+            json.dumps(payload, sort_keys=True, default=str).encode("utf-8"),
+        )
+    except (OSError, TypeError, ValueError):
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# housekeeping
+# ---------------------------------------------------------------------------
+
+
+def cache_stats() -> dict[str, Any]:
+    root = cache_dir()
+    stats: dict[str, Any] = {
+        "enabled": root is not None,
+        "path": str(root) if root else None,
+        "tool_cache_ttl_seconds": tool_ttl(),
+        "http_entries": 0,
+        "tool_entries": 0,
+        "bytes": 0,
+        # Endpoints seen that upstream serves without a validator. Not a
+        # failure: an honest fact about the source, and the answer to "why does
+        # this say 0 entries".
+        "uncacheable_urls": [],
+    }
+    if root is None or not root.exists():
+        return stats
+    uncacheable: set[str] = set()
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        try:
+            stats["bytes"] += path.stat().st_size
+        except OSError:
+            continue
+        if path.name.endswith(".meta.json"):
+            stats["http_entries"] += 1
+        elif path.suffix == ".json" and path.parent.parent.name == "tools":
+            stats["tool_entries"] += 1
+        elif path.suffix == ".json" and path.parent.parent.name == "uncacheable":
+            try:
+                uncacheable.add(json.loads(path.read_text(encoding="utf-8"))["url"])
+            except (OSError, ValueError, KeyError):
+                continue
+    stats["uncacheable_urls"] = sorted(uncacheable)
+    return stats
+
+
+def clear_cache() -> dict[str, Any]:
+    """Delete everything. Returns what was there before, for the operator."""
+    before = cache_stats()
+    root = cache_dir()
+    if root is not None and root.exists():
+        shutil.rmtree(root, ignore_errors=True)
+    before["cleared"] = root is not None
+    return before