py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/cache_ledger.py

@@ -0,0 +1,355 @@
+"""The single cache seam: cache inputs -> key, plus freshness and error policy.
+
+ADR-0011 keeps three caches -- test results, coverage, format results -- and
+gives them one mechanism. Each cache is an *adapter*: it answers what enters its
+key (a :class:`CacheInputs`), how long an entry stays fresh (``ttl_seconds``)
+and where the entries live (``store_dir``). This module answers everything else,
+once:
+
+- **Key spelling** -- ``{namespace}_{sha256(parts)}``, the *full* digest. The
+  coverage cache used to truncate the digest to 16 characters; that truncation
+  is gone, so a key is as unique as the hash under it.
+- **Storage** -- atomic writes delegated to
+  :class:`~wl_cli.utils.cache_store.KeyedStore`.
+- **Freshness** -- :func:`~wl_cli.utils.cache_store.is_fresh` applied to the
+  entry's own ``timestamp`` field with the adapter's TTL. Nothing expires by
+  file mtime, and the TTL values are the adapters' policy, not a debt to unify:
+  test results are fresh for 24 hours, coverage and format results for 7 days.
+- **Error policy** -- a failed *read* is a cache miss (silent: not caching is
+  always safe), a failed *write* never interrupts the run but is logged with a
+  ``log_*_pair``, so the user can see why the next run is slow.
+
+The parts of a :class:`CacheInputs` are ordered and normalized by the adapter.
+Each part is length-prefixed before hashing, so ``("ab", "c")`` and
+``("a", "bc")`` cannot collide, and no part can smuggle in a delimiter that
+makes two different input sets hash alike.
+"""
+
+import hashlib
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .cache_store import KeyedStore, is_fresh
+from .logging import log_warning_pair
+
+#: Characters that would let a namespace escape the store directory (keys become
+#: file names, see :mod:`wl_cli.utils.cache_store`).
+_NAMESPACE_PATH_SEPARATORS = ("/", "\\")
+
+#: C0 control characters (including NUL) and DEL are rejected on every platform,
+#: matching the entry-key rule in :mod:`wl_cli.utils.cache_store`.
+_FIRST_PRINTABLE_CODEPOINT = 0x20
+_DELETE_CODEPOINT = 0x7F
+
+#: How much of a key a write-failure log line shows. A preview only -- the key
+#: itself is never truncated.
+_KEY_PREVIEW_LENGTH = 16
+
+
+@dataclass(frozen=True)
+class CacheInputs:
+    """What an adapter says decides its cache key.
+
+    A namespace (which cache this is) plus the ordered, already-normalized
+    fragments that must move the key when they change. The key is a *function*
+    of these inputs -- :func:`format_key` -- not a synonym for them.
+
+    Attributes:
+        namespace: Cache identity, e.g. ``"test"``, ``"coverage"``,
+            ``"format"``. Becomes the key's prefix, so it must be usable inside
+            a file name: non-empty, no path separator, no control character.
+        parts: The fragments, in the adapter's order. Each is hashed verbatim;
+            the adapter is responsible for normalizing it (path separators,
+            number formatting) so two processes agree.
+    """
+
+    namespace: str
+    parts: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        """Reject an unusable namespace or part at construction, once.
+
+        Validating here means a key can never be spelled from inputs that would
+        produce an illegal file name, so an adapter's mistake surfaces at the
+        call rather than as a silent cache miss later.
+        """
+        if not isinstance(self.namespace, str) or not self.namespace:
+            raise ValueError("Cache namespace must be a non-empty str")
+        if any(separator in self.namespace for separator in _NAMESPACE_PATH_SEPARATORS):
+            raise ValueError(
+                f"Cache namespace must not contain a path separator: {self.namespace!r}"
+            )
+        if any(
+            ord(character) < _FIRST_PRINTABLE_CODEPOINT
+            or ord(character) == _DELETE_CODEPOINT
+            for character in self.namespace
+        ):
+            raise ValueError(
+                f"Cache namespace must not contain control characters: "
+                f"{self.namespace!r}"
+            )
+
+        # The parts are typed ``tuple[str, ...]`` and every adapter spells them
+        # as strings; a wrong type is a programming error at the call site, not
+        # a runtime condition this value object should paper over.
+
+
+def _digest(parts: tuple[str, ...]) -> str:
+    """SHA-256 over the length-prefixed parts, as hexadecimal.
+
+    Length-prefixing is what makes the parts unambiguous: without it the
+    concatenation of ``("ab", "c")`` and ``("a", "bc")`` is the same bytes, and
+    two different input sets would share a key.
+    """
+    hasher = hashlib.sha256()
+    for part in parts:
+        encoded = part.encode("utf-8")
+        hasher.update(f"{len(encoded)}:".encode("ascii"))
+        hasher.update(encoded)
+    return hasher.hexdigest()
+
+
+def format_key(inputs: CacheInputs) -> str:
+    """Spell the key for *inputs*: ``{namespace}_{sha256(parts)}``.
+
+    A pure function of its input -- no clock, no environment, no file system --
+    so two processes that agree on the inputs agree on the key.
+
+    Args:
+        inputs: The adapter's cache inputs.
+
+    Returns:
+        The entry key: the full digest, never a truncated one.
+    """
+    return f"{inputs.namespace}_{_digest(inputs.parts)}"
+
+
+def _preview(key: object) -> str:
+    """Render a key for a log line: safe to print, shortened for reading."""
+    text = key if isinstance(key, str) else repr(key)
+    safe = text.encode("utf-8", "backslashreplace").decode("utf-8")
+    if len(safe) <= _KEY_PREVIEW_LENGTH:
+        return safe
+    return f"{safe[:_KEY_PREVIEW_LENGTH]}..."
+
+
+class CacheLedger:
+    """The cache mechanism every adapter shares.
+
+    Args:
+        store_dir: Directory holding the entries. The adapter decides it --
+            user-level for test and coverage results, project-level for format.
+        ttl_seconds: How long an entry stays fresh, for this adapter only.
+    """
+
+    def __init__(self, store_dir: Path, ttl_seconds: float) -> None:
+        self._store = KeyedStore(store_dir)
+        self._ttl_seconds = ttl_seconds
+
+    @property
+    def store_dir(self) -> Path:
+        """Directory holding the entries."""
+        return self._store.store_dir
+
+    @property
+    def store(self) -> KeyedStore:
+        """The underlying store, for maintenance and statistics.
+
+        Enumerating and measuring entries is a different concern from deciding
+        a key or judging freshness (``CacheMaintenance`` owns the test cache's
+        CLI statistics and purge; :meth:`purge_stale` is the per-adapter
+        housekeeping step). Key spelling and the error policy stay here --
+        callers must not write entries around the ledger.
+        """
+        return self._store
+
+    @property
+    def ttl_seconds(self) -> float:
+        """How long an entry stays fresh, in seconds."""
+        return self._ttl_seconds
+
+    def key(self, inputs: CacheInputs) -> str:
+        """Return the entry key for *inputs* (see :func:`format_key`)."""
+        return format_key(inputs)
+
+    def read(self, key: str) -> dict[str, Any] | None:
+        """Read the entry under *key* without judging freshness.
+
+        A read failure of any kind is a miss: the store already degrades an
+        unreadable, corrupt or non-object entry to ``None``, and an ``OSError``
+        escaping it (a permission change between the existence check and the
+        open) means the same thing -- there is no cache here.
+
+        Args:
+            key: Entry key.
+
+        Returns:
+            The stored dict, or ``None`` on any miss or read failure.
+        """
+        try:
+            return self._store.get(key)
+        except OSError:
+            return None
+
+    def get(self, key: str) -> dict[str, Any] | None:
+        """Read the entry under *key* if it is still fresh.
+
+        Args:
+            key: Entry key.
+
+        Returns:
+            The stored dict when it exists and its ``timestamp`` is within this
+            ledger's TTL; ``None`` otherwise.
+        """
+        entry = self.read(key)
+        if entry is None or not self.fresh(entry):
+            return None
+        return entry
+
+    def fresh(self, entry: Any, *, now: float | None = None) -> bool:
+        """Judge *entry* against this ledger's TTL.
+
+        Args:
+            entry: A stored entry, as returned by :meth:`read`.
+            now: Current epoch time; ``time.time()`` when omitted. Injectable
+                so a TTL boundary can be tested exactly.
+
+        Returns:
+            True when the entry's payload timestamp is younger than this
+            ledger's TTL.
+        """
+        return is_fresh(entry, self._ttl_seconds, now=now)
+
+    def put(self, key: str, payload: dict[str, Any]) -> bool:
+        """Write *payload* under *key*, stamped with the current time.
+
+        The entry's ``timestamp`` is the ledger's, always: freshness is judged
+        from it, so an adapter cannot accidentally write an entry that is born
+        stale or immortal.
+
+        A failed write never interrupts the caller. It is reported through the
+        return value and a bilingual warning, so the failure is visible instead
+        of silently costing the next run a full re-run.
+
+        Args:
+            key: Entry key.
+            payload: JSON-serializable fields to store beside the timestamp.
+
+        Returns:
+            True if the entry was written; False if the key is illegal (see
+            :class:`~wl_cli.utils.cache_store.KeyedStore`) or the write failed.
+        """
+        entry = {**payload, "timestamp": time.time()}
+        try:
+            written = self._store.put(key, entry)
+        except OSError:
+            # ``KeyedStore.put`` already degrades the failures it can see; this
+            # covers the ones that escape it (the store directory's parent is a
+            # file, so ``mkdir`` raises). A cache write must never break a run.
+            written = False
+
+        if not written:
+            preview = _preview(key)
+            log_warning_pair(
+                f"Could not write the cache entry {preview}; continuing without it",
+                f"无法写入缓存条目 {preview}；已跳过该条目，继续运行",
+            )
+        return written
+
+    def touch(self, key: str, *, now: float | None = None) -> bool:
+        """Renew a fresh entry's timestamp, reporting whether it was a hit.
+
+        A hit used to be a silent read, so an entry's age was counted from the
+        run that recorded it: a verdict served on every run still expired seven
+        days after it was first written. The old single-document format cache
+        re-stamped every entry it served when it saved, and this restores that
+        sliding window (#213 review LOW-3) -- a fresh entry being used again
+        stays fresh for another TTL.
+
+        A stale entry is **not** renewed: the caller is going to re-run and
+        record a new verdict, and resurrecting an expired one would turn a
+        failed re-run into a false hit.
+
+        The renewal is best effort and silent. A failed renewal leaves the
+        entry with its old timestamp, which can only make it expire sooner --
+        the same outcome as not touching it -- so it is not a cache-write
+        failure worth a warning on every hit (compare :meth:`put`, where the
+        entry would otherwise never exist).
+
+        Args:
+            key: Entry key.
+            now: Current epoch time; ``time.time()`` when omitted.
+
+        Returns:
+            True when the entry existed and was fresh; False on a miss or a
+            stale entry. A failed renewal still reports True -- the hit stands.
+        """
+        entry = self.read(key)
+        if entry is None or not self.fresh(entry, now=now):
+            return False
+
+        payload = {name: value for name, value in entry.items() if name != "timestamp"}
+        payload["timestamp"] = time.time() if now is None else now
+        try:
+            self._store.put(key, payload)
+        except OSError:
+            # ``KeyedStore.put`` degrades what it can see; this covers what
+            # escapes it, exactly as ``put`` does. See the docstring: a lost
+            # renewal is not a lost entry.
+            pass
+        return True
+
+    def purge_stale(self, *, now: float | None = None) -> int:
+        """Delete every entry that can no longer be a hit.
+
+        An entry is reclaimed when it is older than this ledger's TTL, or when
+        it cannot be read as a JSON object at all: neither can ever be served,
+        so both only cost disk. Per-entry files never expire on their own --
+        the format adapter's old single-document ``save`` was what implicitly
+        pruned them -- so this is the reclaim step that keeps the store bounded
+        (#213 review MEDIUM-2).
+
+        Deletion goes through ``invalidate_file`` rather than ``invalidate``:
+        ``iter_entry_files`` also yields files whose names are not legal keys,
+        and those deserve reclaiming too.
+
+        Leftover ``*.tmp`` files are deliberately left alone: a temp name is
+        unique per write (#213 review NIT-6), so a leftover may belong to a
+        concurrent writer that is about to rename it. ``remove_temp_files`` is
+        the explicit sweep for those.
+
+        Args:
+            now: Current epoch time; ``time.time()`` when omitted.
+
+        Returns:
+            Number of entry files deleted.
+        """
+        deleted = 0
+        for key, entry in self._store.iter_entry_files():
+            if entry is not None and self.fresh(entry, now=now):
+                continue
+            if self._store.invalidate_file(key):
+                deleted += 1
+        return deleted
+
+    def invalidate(self, key: str) -> bool:
+        """Drop the entry under *key*.
+
+        Returns:
+            True if an entry was deleted; False if there was nothing to delete
+            or the deletion failed.
+        """
+        try:
+            return self._store.invalidate(key)
+        except OSError:
+            return False
+
+    def clear(self) -> int:
+        """Drop every entry in this ledger's store.
+
+        Returns:
+            Number of files deleted.
+        """
+        return self._store.clear()