aptriever 0.1.0__py3-none-any.whl

aptriever/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

aptriever/addresses.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import contextvars
+import socket
+from ipaddress import IPv4Address, IPv4Network, IPv6Address, IPv6Network, ip_address
+from pathlib import Path
+
+# Outbound address policy (#89): whether an address about to be dialed — a DNS answer, a redirect target, a literal origin — may be dialed at all, decided at the dial so that no parser routes around it.
+# Trust comes from provenance, never from the address itself: a configured mirror may name any address but link-local (a private company mirror, a LAN instance to chain to), while a listed mirror and a client-named origin may name no internal address, so neither a listed host, nor its DNS, nor a client can make aptriever dial the operator's networks.
+# The internal classes are listed explicitly — loopback, link-local, RFC 1918 private, shared address space, unique-local and the deprecated site-local, unspecified, multicast — and everything else is permitted, documentation, benchmarking and other reserved ranges included: the threat is reaching the operator's networks, and those ranges reach nobody.
+# Not ipaddress.is_global or is_private: both classify the documentation ranges as non-global and private, which says more than the threat model does and would refuse the TEST-NET addresses the test suite's resolvers answer with.
+# Link-local (169.254.0.0/16, fe80::/10) is refused whatever the provenance: the IPv4 cloud metadata address 169.254.169.254 lives there and no mirror does.
+# A metadata endpoint in another class is covered by that class rather than by name — AWS's opt-in IPv6 endpoint fd00:ec2::254 is unique-local, Alibaba's 100.100.100.200 is shared address space — so both are refused for untrusted provenance and dialable through a configured mirror, which is the operator's own trust, and the policy stays a list of classes rather than of addresses.
+# An IPv4-mapped address and one under a NAT64 prefix take the embedded IPv4's verdict: a translator delivers a wrapped 10.0.0.5 or 169.254.169.254 all the same, and ipaddress sees nothing link-local through a NAT64 prefix; the unwrap decodes the /96 layout only, so an address under the /48 prefix in one of RFC 6052's shorter layouts keeps its IPv4 above the low 32 bits, which read as unspecified (/48, /56) or as one stray byte of it (/64), and a network-specific prefix is not recognized at all.
+# Other IPv4-in-IPv6 embeddings — 6to4 (2002::/16), Teredo (2001::/32), ISATAP, the deprecated IPv4-compatible and SIIT forms — were considered and left alone: a DNS answer cannot create the tunnel interface such an address would need.
+# A string that does not parse as an address is refused: the policy vouches only for what it can classify.
+
+NAT64_PREFIXES = (IPv6Network("64:ff9b::/96"), IPv6Network("64:ff9b:1::/48"))  # RFC 6052's well-known prefix and RFC 8215's local-use prefix: under both the embedded IPv4 is the low 32 bits
+INTERNAL_NETWORKS = (  # the internal classes ipaddress has no predicate of its own for, named as the log line reports them; loopback, link-local, unspecified and multicast come from its predicates
+    ("private", IPv4Network("10.0.0.0/8")),
+    ("private", IPv4Network("172.16.0.0/12")),
+    ("private", IPv4Network("192.168.0.0/16")),
+    ("shared", IPv4Network("100.64.0.0/10")),
+    ("unique-local", IPv6Network("fc00::/7")),
+    ("site-local", IPv6Network("fec0::/10")),
+)
+
+
+def _unwrapped(ip: str) -> IPv4Address | IPv6Address | None:
+    # The address the verdict is about — the embedded IPv4 of a mapped or NAT64 address — or None for a string that is not an address.
+    try:
+        address = ip_address(ip)
+    except ValueError:
+        return None
+    if isinstance(address, IPv6Address):
+        if address.ipv4_mapped is not None:
+            return address.ipv4_mapped
+        if any(address in prefix for prefix in NAT64_PREFIXES):
+            return IPv4Address(int(address) & 0xFFFFFFFF)
+    return address
+
+
+def refusal(ip: str, trusted: bool) -> str | None:
+    # The class this address is refused under, None when it may be dialed. trusted: the provenance vouches for every internal class but link-local; otherwise for none of them.
+    address = _unwrapped(ip)
+    if address is None:
+        return "unparsable"
+    if address.is_link_local:
+        return "link-local"
+    if trusted:
+        return None
+    if address.is_loopback:
+        return "loopback"
+    if address.is_unspecified:
+        return "unspecified"
+    if address.is_multicast:
+        return "multicast"
+    return next((name for name, network in INTERNAL_NETWORKS if address in network), None)
+
+
+def permitted(ip: str, trusted: bool) -> bool:
+    return refusal(ip, trusted) is None
+
+
+IF_INET6 = Path("/proc/net/if_inet6")  # every IPv6 address the kernel holds, one line each: address as 32 hex digits, interface index, prefix length, scope and flags as two hex digits each, interface name — the format ifconfig has read since Linux 2.2 (spec: egress address)
+GLOBAL_UNICAST = IPv6Network("2000::/3")  # RFC 4291's global unicast, which is what a provider delegates; ipaddress's is_global would also refuse the documentation prefix the tests use, and the scope byte alone admits unique-local addresses (spec: egress address)
+# linux/if_addr.h; the low byte is all the proc file prints and all this needs: a temporary address rotates and a deprecated one is what a withdrawn or unrouted prefix leaves behind (RFC 4862 section 5.5.4; spec: egress address)
+IFA_F_TEMPORARY, IFA_F_DADFAILED, IFA_F_DEPRECATED, IFA_F_TENTATIVE = 0x01, 0x08, 0x20, 0x40
+ROUTE_PROBE = ("2606:4700:4700::1111", 9)  # any global address does: a datagram connect() is a route lookup that sends nothing, and on a host with no IPv6 default it fails, which is the no-egress-address answer (spec: egress address)
+
+
+def egress_addresses(table: str, default_source: str | None) -> list[str]:
+    # spec: egress address — the global, stable, preferred addresses on the interface the kernel's default source sits on, in the table's order; nothing without a default source, or with one the table does not list.
+    rows: list[tuple[str, int, str]] = []
+    for line in table.splitlines():
+        parts = line.split()
+        if len(parts) != 6:
+            continue  # not a row of this file: skipped, never fatal, like every other system-provided text the daemon reads
+        try:
+            rows.append((str(IPv6Address(bytes.fromhex(parts[0]))), int(parts[4], 16), parts[5]))
+        except ValueError:
+            continue
+    interface = next((ifname for address, _, ifname in rows if address == default_source), None)
+    if interface is None:
+        return []
+    return [address for address, flags, ifname in rows if ifname == interface and IPv6Address(address) in GLOBAL_UNICAST and not flags & (IFA_F_TEMPORARY | IFA_F_DADFAILED | IFA_F_DEPRECATED | IFA_F_TENTATIVE)]
+
+
+def default_source() -> str | None:
+    # The address the kernel would send from to a global destination, hence the interface egress addresses sit on; None when nothing routes there, or the host has no IPv6 at all (spec: egress address).
+    try:
+        with socket.socket(socket.AF_INET6, socket.SOCK_DGRAM) as sock:
+            sock.connect(ROUTE_PROBE)
+            return sock.getsockname()[0]
+    except OSError:
+        return None
+
+
+def system_egress_addresses() -> list[str]:
+    # The default `egress` seam of a MirrorSet: read fresh on every call, 27 µs measured, never cached, so a new prefix is dialed by the next seat and a withdrawn one skipped by the next pass (spec: egress address).
+    try:
+        return egress_addresses(IF_INET6.read_text(), default_source())
+    except OSError:
+        return []  # no such file: not Linux, or a sandbox — no egress address, every dial stays unbound as before
+
+
+bound_egress: contextvars.ContextVar[str] = contextvars.ContextVar("bound_egress", default="")  # the egress address the dials of the current task bind, set by open_upstream around its request loop; "" binds nothing (spec: dial)
+
+
+def bound_socket(addr_info: tuple) -> socket.socket:
+    # aiohttp's socket_factory (the connector in server.py): every socket the connector dials with passes through here, so one session serves every egress address (spec: dial). A bind that fails — the address gone between seating and dialing — raises out of the factory, which aiohappyeyeballs turns into the connect failure open_upstream already classifies.
+    family, type_, proto, _, _ = addr_info
+    sock = socket.socket(family, type_, proto)
+    egress = bound_egress.get()
+    if egress and (family == socket.AF_INET6) == (":" in egress):  # a redirect hop into the other family dials unbound: the family rule applied per hop, since an address of one family can never be bound to a socket of the other (spec: dial)
+        try:
+            sock.bind((egress, 0))
+        except OSError:
+            sock.close()  # the factory owns the socket until it hands it over
+            raise
+    return sock

aptriever/aliases.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from .mirrors import MirrorSet
+
+
+def resolve_pool_alias(mirror_sets: dict[str, MirrorSet], netloc: str, path: str) -> tuple[str, str] | None:
+    # Matches a request's host+path spelling against every configured archive's live pool (seed and geo arrivals alike) and returns (archive name, archive-relative remainder), or None (spec: docs/plans/2026-07-18-pool-mirror-aliases.md).
+    # A linear scan on purpose: it runs only for embedded requests and would-be-404s, and a live scan needs no invalidation wiring when the geo refresher appends mirrors.
+    want = netloc.lower()
+    best: tuple[str, str] | None = None
+    best_len = -1  # below zero so a bare-host mirror (prefix length 0) can still win the strict longest-match comparison
+    for archive, mirror_set in mirror_sets.items():
+        for mirror in mirror_set.mirrors:
+            # Scheme ignored: the client names a repository, and the pool fetches with its own configured schemes and redirect-upgrade memory. Netloc lowercased and port-inclusive: DNS names are case-insensitive, distinct ports are distinct servers.
+            mirror_netloc, prefix = mirror.alias_key
+            if mirror_netloc != want:
+                continue
+            if prefix:
+                # Segment-bounded prefix: the boundary slash is part of the match, so "ubuntu" never claims "ubuntu-ports/…"; a multi-segment mirror path consumes all its segments.
+                if not path.startswith(prefix + "/"):
+                    continue
+                remainder = path[len(prefix) + 1 :]
+            else:
+                # A bare-host mirror serves the repository at its root, so every path under that host is archive-relative as-is.
+                remainder = path
+            if not remainder:
+                continue  # the request names the repository root with nothing to fetch: no match
+            if len(prefix) > best_len:
+                # Strictly longer only: equal-length matches keep the first seen, so ties resolve in config order (dict iteration is [archives.*] order); equal-length prefixes of one path are the same string, so the tie can only be across archives.
+                best, best_len = (archive, remainder), len(prefix)
+    return best

aptriever/cache.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import asyncio
+import itertools
+import logging
+import os
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger("aptriever")
+
+PARTIAL_DIRNAME = "partial"  # holds only in-flight fills; startup_cleanup and sweep both key off this exact name
+
+
+def _urlsafe_key(archive: str, path: str) -> str:
+    # "/" is the only character archive/path legitimately contain that would otherwise create a nested directory under partial/; flattening it keeps every temp name one filesystem entry.
+    return f"{archive}/{path}".replace("/", "_")
+
+
+class FillCancelled(Exception):
+    # A cancelled fill's followers were not themselves cancelled: handing them the CancelledError would falsely propagate cancellation into their own control flow, so it is converted to this ordinary exception before being stored as the shared error.
+    pass
+
+
+def _reject_traversal(archive: str, path: str) -> None:
+    # Defense in depth: the server already collapses "." and rejects ".." before ever calling in, but this is the exact boundary that turns a client-controlled string into a filesystem path, so it re-checks rather than trusting the caller.
+    segments = archive.split("/") + path.split("/")
+    if ".." in segments or "." in segments:  # "." too: pathlib drops it, so pool/./a.deb and pool/a.deb would be one entry under two request paths, and a request ending in "/." would take a directory's name (#90)
+        raise ValueError(f"path traversal rejected: archive={archive!r} path={path!r}")
+    if archive.startswith("/") or path.startswith("/"):
+        raise ValueError(f"absolute segment rejected: archive={archive!r} path={path!r}")  # pathlib's / operator discards everything to its left when the right side is absolute, silently escaping root
+
+
+class CacheFill:
+    def __init__(self, cache: Cache, archive: str, path: str, start_fill: Callable[[], Awaitable[Any]]) -> None:
+        self.start_fill = start_fill
+        self.final_path = cache.file_path(archive, path)
+        serial = next(cache._fill_serial)
+        cache.partial_dir.mkdir(parents=True, exist_ok=True)  # here rather than in Cache.__init__: a fill is the only thing that needs the spool, so building a Cache to purge, clean or refuse one entry no longer creates a cache tree nothing has written to
+        # The urlsafe key alone is not enough: a failed fill and its retry share one key, so this cache-wide serial guarantees their temp names never collide even if the first fill's cleanup is still in flight.
+        self.temp_path = cache.partial_dir / f"{_urlsafe_key(archive, path)}.{serial}.tmp"
+        # Created now, synchronously, before any CacheReader can exist for this fill: a reader may start read() before the fill task first runs, and "not done implies the temp is openable" (CacheReader.read) needs the file to predate every reader; exist_ok=False turns a serial collision into a loud failure instead of silent data mixing.
+        self.temp_path.touch(exist_ok=False)
+        self.condition = asyncio.Condition()
+        self.bytes_written = 0
+        self.total: int | None = None
+        self.done = False
+        self.error: BaseException | None = None
+        self.task: asyncio.Task[None] | None = None  # set by Cache.fill_or_join right after construction
+
+    async def run(self, cache: Cache, key: tuple[str, str]) -> None:
+        result: Any = None
+        error: BaseException | None = None
+        drained = False
+        try:
+            result = await self.start_fill()
+            length = result.headers.get("Content-Length")
+            async with self.condition:
+                self.total = int(length) if length is not None else None
+                self.condition.notify_all()
+            with open(self.temp_path, "wb") as f:
+                async for chunk in result.body:
+                    f.write(chunk)
+                    f.flush()  # push past Python's own buffering into the OS now, not later: tail-followers read this file through their own fd and must see bytes as they land
+                    async with self.condition:
+                        self.bytes_written += len(chunk)
+                        self.condition.notify_all()
+                drained = True  # FetchResult.on_committed's contract, kept below: called once, if and only if the body's iteration ended without raising, and only after the terminal duties; set before the file closes so a failing close reaches it like a failing commit (#91)
+            # A missing Content-Length leaves total None and length verification impossible: aiohttp surfaces truncation of such transfers as body errors, and apt's hash check backstops the rest.
+            if self.total is not None and self.bytes_written != self.total:
+                raise ValueError(f"fill for {key!r} got {self.bytes_written} bytes, expected {self.total}")  # never escapes run: recorded as self.error below for the readers to raise, like every other fill failure
+        except asyncio.CancelledError:
+            # Followers were not themselves cancelled: storing the CancelledError as the shared error would inject cancellation into their unrelated control flow, so convert it to an ordinary exception first.
+            error = FillCancelled(f"fill for {key!r} was cancelled")
+            raise  # the finally below still runs its terminal duties, then cancellation keeps propagating so the task ends cancelled
+        except Exception as e:
+            error = e
+        finally:
+            async with self.condition:
+                try:
+                    if error is None:
+                        try:
+                            self.final_path.parent.mkdir(parents=True, exist_ok=True)
+                        except FileExistsError, NotADirectoryError:
+                            # A regular file stands where this fill needs a directory: a directory listing cached under the directory's own name, which a mirror's redirect from …/l to …/l/ can still land there (#90). The fetch that just completed proves upstream has a directory at that path, so the stale file gives way and the mkdir is retried once; a second failure is the fill's failure like any other.
+                            # Contained by construction: final_path is root/archive/path with traversal and absolute segments rejected, so this walk meets root before it can leave the cache, and the spool is a directory under a reserved archive name, never a regular file on a fill's path.
+                            for ancestor in self.final_path.parents:
+                                if ancestor == cache.root:
+                                    break
+                                if ancestor.is_file():
+                                    ancestor.unlink(missing_ok=True)  # missing_ok: a concurrent `aptriever cache clean` may beat this fill to the file
+                                    log.warning("fill for %r evicted %s: a file stood where the fill needs a directory, most likely a mirror's listing served under an object path (#90)", key, ancestor)  # WARNING so the self-heal shows in journald: the file was a cache entry some request created
+                                    break
+                            self.final_path.parent.mkdir(parents=True, exist_ok=True)
+                        # Deliberately no fsync: this is a cache, not an ACID database — ext4's data=ordered mode flushes file data before a rename committing it is observable, and the rare crash-corrupted entry is caught by apt's own hash verification (heal by deleting).
+                        # Inside the condition block on purpose: the rename and the done flag below flip atomically for condition-holding readers, so "not done" always implies "temp still openable".
+                        os.replace(self.temp_path, self.final_path)
+                except Exception as e:
+                    error = e  # a failed commit (mkdir/rename, e.g. disk full) is the fill's failure: recorded for late readers, while readers that already drained every advertised byte still complete cleanly
+                    log.warning("fill for %r could not be committed, the entry is not cached and every request re-fetches it: %s", key, e)  # WARNING like the other cache-side faults: a daemon-level fault, not per-request narration (#91)
+                finally:
+                    # Terminal duties, unskippable even when the commit above raised: without done+notify every waiting reader hangs forever, and without deregistration the dead fill stays joinable.
+                    self.error = error
+                    self.done = True
+                    cache._forget_fill(key, self)
+                    self.condition.notify_all()
+            if error is not None:
+                try:
+                    self.temp_path.unlink(missing_ok=True)
+                except OSError as e:
+                    log.warning("fill for %r could not remove its temporary file %s: %s", key, self.temp_path, e)  # WARNING like the other cache-side faults, and swallowed: this runs in a task nothing awaits, where a raise reaches nobody but asyncio's never-retrieved report
+                finally:
+                    if result is not None:
+                        # Non-complete path only: a fully-drained body has already released everything through FetchResult's own bookkeeping, so closing again on success would be a no-op we don't need.
+                        await result.close()
+        if drained and result.on_committed is not None:
+            # After the terminal block, so a written fill event implies done, deregistered, and either landed or failed for the reason it carries. Exactly once: the body wrapper writes the event itself when the iteration raised, and drained is True precisely when it did not (#91).
+            result.on_committed(error)
+        if error is None:
+            # Strictly after the terminal block above (done/notify/deregister already happened): eviction only ever runs when content was added, and a failed fill never grew the cache.
+            try:
+                # A directory walk per fill is fine at these request rates. TODO: revisit with an index when the LAN profile shows it in profiles.
+                cache.sweep()
+            except Exception as e:
+                log.warning("sweep after fill for %r failed: %s", key, e)
+
+
+class CacheReader:
+    # Independent per caller: each fill_or_join call gets its own CacheReader with its own file position, so one slow client can never block another from draining the fill.
+    def __init__(self, fill: CacheFill, cache_kind: str) -> None:
+        self._fill = fill
+        self.cache_kind = cache_kind
+
+    @property
+    def total(self) -> int | None:
+        return self._fill.total
+
+    async def read(self) -> AsyncIterator[bytes]:
+        fill = self._fill
+        # Opened lazily on first iteration, not in __init__: a reader that is constructed but never iterated must not hold (and eventually leak) an open file.
+        async with fill.condition:
+            if fill.done:
+                if fill.error is not None:
+                    raise fill.error  # the fill ended before this reader ever started and its temp is already unlinked: the recorded error is all it can serve
+                f = open(fill.final_path, "rb")  # the fill completed before this reader started: the temp was renamed into place, so the final file carries the identical content
+            else:
+                # Not done, observed under the condition, guarantees the temp still exists: rename and unlink both happen strictly on the done side of the terminal transition in CacheFill.run.
+                # This one fd is kept across the fill's later os.replace or unlink: POSIX rename and unlink only touch directory entries, an open fd keeps addressing the inode.
+                f = open(fill.temp_path, "rb")
+        try:
+            position = 0
+            while True:
+                async with fill.condition:
+                    while fill.bytes_written <= position and not fill.done:
+                        await fill.condition.wait()
+                    available = fill.bytes_written
+                    is_done = fill.done
+                    error = fill.error
+                    total = fill.total
+                if available > position:
+                    f.seek(position)
+                    chunk = f.read(available - position)
+                    position += len(chunk)
+                    yield chunk
+                if is_done and position >= available:
+                    # A reader that delivered exactly the advertised byte count completes cleanly even if the fill failed afterwards (e.g. at the rename): its own stream was byte-perfect, only the caching failed.
+                    if error is not None and not (total is not None and position == total):
+                        raise error
+                    return
+        finally:
+            f.close()
+
+
+@dataclass(frozen=True)
+class CachePolicy:
+    # All-None enforces nothing: sweep applies whichever limits are set. Deployed processes always carry at least one — config.resolve_cache_policy fills a mode default when the operator sets none.
+    cache_max_bytes: int | None = None  # absolute footprint cap; wins over cache_max_percent when both are set
+    cache_max_percent: float | None = None  # footprint cap as a percent of the filesystem's live total size
+    disk_high_water_percent: float | None = None  # evict while the whole filesystem (any cause, not just the cache) is fuller than this percent
+
+
+@dataclass(frozen=True)
+class CacheUsage:
+    fs_total: int
+    fs_used: int
+    fs_avail: int
+    cache_bytes: int
+    cache_cap: int | None
+    disk_high_water: int | None
+
+    @property
+    def headroom(self) -> int | None:
+        # Bytes the cache may still grow before some limit bites; None when no limit is in force.
+        margins = [m for m in (self.cache_cap - self.cache_bytes if self.cache_cap is not None else None, self.disk_high_water - self.fs_used if self.disk_high_water is not None else None) if m is not None]
+        return max(0, min(margins)) if margins else None
+
+
+class Cache:
+    def __init__(self, root: Path, policy: CachePolicy) -> None:
+        self.root = Path(root)
+        self.policy = policy
+        self.partial_dir = self.root / PARTIAL_DIRNAME
+        self._fills: dict[tuple[str, str], CacheFill] = {}
+        self._fill_serial = itertools.count()  # cache-wide, not per-key: only uniqueness matters, and one shared counter is simpler than tracking per-key state
+
+    def file_path(self, archive: str, path: str) -> Path:
+        _reject_traversal(archive, path)
+        return self.root / archive / path
+
+    def lookup(self, archive: str, path: str) -> Path | None:
+        p = self.file_path(archive, path)
+        if not p.is_file():
+            return None
+        # Hits bump mtime as the LRU signal: atime is unreliable under relatime (only advances if the old atime predated today or predated mtime), so mtime is repurposed here, at the cost that it no longer means "when this was downloaded."
+        os.utime(p, None)
+        return p
+
+    async def fill_or_join(self, archive: str, path: str, start_fill: Callable[[], Awaitable[Any]]) -> CacheReader:
+        key = (archive, path)
+        fill = self._fills.get(key)
+        if fill is not None:
+            return CacheReader(fill, "tail")
+        # No await above this line: two concurrent callers for the same key can never both see a miss, because asyncio only switches coroutines at an await point and this whole registration is one uninterrupted step.
+        fill = CacheFill(self, archive, path, start_fill)
+        self._fills[key] = fill
+        fill.task = asyncio.create_task(fill.run(self, key))
+        return CacheReader(fill, "miss")
+
+    def _forget_fill(self, key: tuple[str, str], fill: CacheFill) -> None:
+        if self._fills.get(key) is fill:
+            del self._fills[key]
+
+    def startup_cleanup(self) -> int:
+        if not self.partial_dir.is_dir():
+            return 0  # nothing has ever filled through this cache, so there is no spool and nothing stale in it
+        count = 0
+        for entry in self.partial_dir.iterdir():
+            if entry.is_file():
+                entry.unlink()
+                count += 1
+        return count
+
+    def clean(self) -> tuple[int, int, list[OSError]]:
+        # Wipes every completed entry (all re-fetchable); in-flight fills under partial/ stay untouched. Safe against a running server: POSIX keeps an unlinked-but-open file readable, and the next sweep re-derives sizes from the tree.
+        files = 0
+        freed = 0
+        skipped: list[OSError] = []  # every directory the walk could not read, an absent root among them, and every entry that would not unlink: without them a count of zero cannot be told from an unreadable tree (#109)
+        for dirpath, dirnames, filenames in os.walk(self.root, onerror=skipped.append):
+            if Path(dirpath) == self.root:
+                dirnames[:] = [d for d in dirnames if d != PARTIAL_DIRNAME]  # never touch in-flight fills
+            for name in filenames:
+                fp = Path(dirpath) / name
+                try:
+                    size = fp.stat().st_size
+                    fp.unlink()
+                except FileNotFoundError:
+                    continue  # vanished mid-walk (a concurrent sweep): already gone is the goal state
+                except OSError as e:
+                    skipped.append(e)  # a readable but unwritable directory: the rest of the tree still goes, and the caller reports this one
+                    continue
+                files += 1
+                freed += size
+        return files, freed, skipped
+
+    def _cache_cap(self, fs_total: int) -> int | None:
+        if self.policy.cache_max_bytes is not None:
+            return self.policy.cache_max_bytes
+        if self.policy.cache_max_percent is not None:
+            return int(self.policy.cache_max_percent / 100 * fs_total)  # the configured percent as the bytes every comparison here is in; truncated, so the cap never rounds past the share the operator named
+        return None
+
+    def _disk_high_water(self, fs_total: int) -> int | None:
+        if self.policy.disk_high_water_percent is not None:
+            return int(self.policy.disk_high_water_percent / 100 * fs_total)  # the same percent-to-bytes conversion against the same live total: sweep() holds fs_used to this mark and cache_bytes to the cap above, all four in bytes
+        return None
+
+    def _survey(self) -> tuple[CacheUsage, list[tuple[float, Path, int]]]:
+        # statvfs is re-read on every survey, never cached: disks resize (LXD volumes especially), so percent limits must resolve against the live total.
+        st = os.statvfs(self.root)
+        fs_total = st.f_frsize * st.f_blocks
+        fs_avail = st.f_frsize * st.f_bavail  # f_bavail, not f_bfree: the daemon runs unprivileged, so root's reserved blocks are not usable headroom
+        fs_used = fs_total - fs_avail
+        entries: list[tuple[float, Path, int]] = []
+        cache_bytes = 0
+        # One WARNING per unreadable directory per survey: only an operator can produce one under the daemon's own user, and the sweep under-counts cache_bytes and evicts nothing from that subtree until it is fixed, so repeating the line while it persists is the point (#109).
+        for dirpath, dirnames, filenames in os.walk(self.root, onerror=lambda e: log.warning("cache: survey cannot read %s: %s", e.filename, e.strerror)):
+            if Path(dirpath) == self.root:
+                dirnames[:] = [d for d in dirnames if d != PARTIAL_DIRNAME]  # never touch in-flight fills
+            for name in filenames:
+                fp = Path(dirpath) / name
+                try:
+                    stat = fp.stat()
+                except FileNotFoundError:
+                    continue  # vanished mid-walk (a concurrent `aptriever clean`): simply not part of this survey
+                cache_bytes += stat.st_size
+                entries.append((stat.st_mtime, fp, stat.st_size))
+        entries.sort(key=lambda e: e[0])  # oldest mtime first
+        return CacheUsage(fs_total=fs_total, fs_used=fs_used, fs_avail=fs_avail, cache_bytes=cache_bytes, cache_cap=self._cache_cap(fs_total), disk_high_water=self._disk_high_water(fs_total)), entries
+
+    def usage(self) -> CacheUsage:
+        usage, _ = self._survey()
+        return usage
+
+    def oversized(self, total_bytes: int) -> bool:
+        # An entry bigger than a cap in force could only land by evicting everything else and would still be over (issue #31's pathology): the server skips caching it and streams it straight to clients instead.
+        st = os.statvfs(self.root)
+        fs_total = st.f_frsize * st.f_blocks
+        caps = [c for c in (self._cache_cap(fs_total), self._disk_high_water(fs_total)) if c is not None]
+        return bool(caps) and total_bytes > min(caps)
+
+    def sweep(self) -> int:
+        usage, entries = self._survey()
+        cache_bytes, disk_used = usage.cache_bytes, usage.fs_used
+        log.debug("sweep: fs total=%d used=%d avail=%d cache=%d cap=%s high_water=%s", usage.fs_total, disk_used, usage.fs_avail, cache_bytes, usage.cache_cap, usage.disk_high_water)
+        freed = 0
+        for _, fp, size in entries:
+            if (usage.cache_cap is None or cache_bytes <= usage.cache_cap) and (usage.disk_high_water is None or disk_used <= usage.disk_high_water):
+                break
+            fp.unlink(missing_ok=True)  # missing_ok: a concurrent clean may beat this sweep to the file; the pass's accounting stays approximate either way
+            cache_bytes -= size
+            disk_used -= size
+            freed += size
+        else:
+            if usage.disk_high_water is not None and disk_used > usage.disk_high_water:
+                # Best-effort boundary: everything evictable is gone and the filesystem is still over the high-water — non-cache data holds the space, which only the operator can reclaim.
+                log.warning("disk use %d still over the %d high-water after evicting the entire cache", disk_used, usage.disk_high_water)
+        return freed