fluidattacks-agent 0.1.2__tar.gz → 0.2.0__tar.gz

{fluidattacks_agent-0.1.2 → fluidattacks_agent-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fluidattacks-agent
-Version: 0.1.2
+Version: 0.2.0
 Summary: In-process probe reporting what a Python workload imports and runs
 Project-URL: Homepage, https://fluidattacks.com
 Project-URL: Source, https://gitlab.com/fluidattacks/universe/-/tree/trunk/watches/agents/python
@@ -26,7 +26,7 @@ dependency inventory can say which of its findings are reachable at runtime and
 which are not.
 
 It is a library, not a service. It observes the interpreter it is installed in,
-writes what it saw, and does nothing else. It takes no dependencies: the
+sends what it saw, and does nothing else. It takes no dependencies: the
 standard library only, because it is installed into workloads we do not own.
 
 ## Installing
@@ -60,8 +60,8 @@ a workload's own first-party code produce no records.
 
 ## Where reports go
 
-By default, one file per report under `/tmp/.watches-exec`, for a collector to
-drain. Naming an endpoint sends them instead:
+Naming an endpoint is what makes the probe observe at all. A workload that
+names none starts nothing:
 
 | | |
 |---|---|
@@ -74,10 +74,9 @@ drain. Naming an endpoint sends them instead:
 A file is preferred over a variable because a file can be mode 400, while an
 environment variable is readable by any process of the same user.
 
-An endpoint named without enough beside it to reach is a misconfiguration, not a
-reason to fall back: the probe then holds nothing and counts every report it
-refused, so a half-configured deployment is loud rather than a directory filling
-up where nobody drains it.
+An endpoint named without enough beside it to reach — no credential, or not
+`https://` — is a misconfiguration, and the probe starts nothing rather than
+observe what it could never deliver.
 
 ## What travels, and what does not
 

{fluidattacks_agent-0.1.2 → fluidattacks_agent-0.2.0}/README.md

@@ -5,7 +5,7 @@ dependency inventory can say which of its findings are reachable at runtime and
 which are not.
 
 It is a library, not a service. It observes the interpreter it is installed in,
-writes what it saw, and does nothing else. It takes no dependencies: the
+sends what it saw, and does nothing else. It takes no dependencies: the
 standard library only, because it is installed into workloads we do not own.
 
 ## Installing
@@ -39,8 +39,8 @@ a workload's own first-party code produce no records.
 
 ## Where reports go
 
-By default, one file per report under `/tmp/.watches-exec`, for a collector to
-drain. Naming an endpoint sends them instead:
+Naming an endpoint is what makes the probe observe at all. A workload that
+names none starts nothing:
 
 | | |
 |---|---|
@@ -53,10 +53,9 @@ drain. Naming an endpoint sends them instead:
 A file is preferred over a variable because a file can be mode 400, while an
 environment variable is readable by any process of the same user.
 
-An endpoint named without enough beside it to reach is a misconfiguration, not a
-reason to fall back: the probe then holds nothing and counts every report it
-refused, so a half-configured deployment is loud rather than a directory filling
-up where nobody drains it.
+An endpoint named without enough beside it to reach — no credential, or not
+`https://` — is a misconfiguration, and the probe starts nothing rather than
+observe what it could never deliver.
 
 ## What travels, and what does not
 

{fluidattacks_agent-0.1.2 → fluidattacks_agent-0.2.0}/fluidattacks_agent/deliver.py

@@ -12,18 +12,18 @@ from typing import Final
 from fluidattacks_agent.batch import Batch, Batcher
 from fluidattacks_agent.outbox import Outbox
 from fluidattacks_agent.patience import TOPMOST, fraction, splay, standoff
-from fluidattacks_agent.post import TIMEOUT, Verdict, posted
+from fluidattacks_agent.post import TIMEOUT, Verdict, posted, prepared
 from fluidattacks_agent.settings import Delivery
-from fluidattacks_agent.sink import Stalled
+from fluidattacks_agent.sink import PARTING, Stalled
 
-# how old the centre's picture may be while nothing new is being found
+# how old the centre's picture may be: the period the window is folded on
 INTERVAL: Final = 15.0
 
-# what a workload's own exit may be delayed by while what is held goes out
-PARTING: Final = 2.0
-
 NAME: Final = "fluidattacks-agent"
 
+# before any fold, so the first wait to end folds whatever the probe holds
+NEVER: Final = float("-inf")
+
 
 @dataclass
 class Deliverer:
@@ -46,23 +46,27 @@ class Deliverer:
     guard: threading.Lock = field(default_factory=threading.Lock, repr=False)
     # one pass at a time: what is taken but not delivered lives in one place
     passing: threading.Lock = field(default_factory=threading.Lock, repr=False)
-    # told once a period went by with the far end in reach and nothing left to
-    # carry, so what the probe still holds goes out before it is any older
-    remind: Callable[[], None] = field(default=lambda: None, repr=False)
-    # when the probe was last reminded: a far end that refuses and then takes
-    # ends a wait every standoff, and a wait ending is not a period going by
-    reminded: float = 0.0
+    # what renders the probe's window into reports. Called here, on the
+    # carrier's own thread and clock, so a workload's threads render nothing
+    fold: Callable[[], None] = field(default=lambda: None, repr=False)
+    folded: float = NEVER
     leaving: bool = False
     delivered: int = 0
 
     def write(self, text: str) -> None:
         """Take a report for delivery, or refuse and be counted for it."""
+        # here, inside the fold that made the report, so what a post imports is
+        # imported under the lock a fork waits out and not on the pass after
+        prepared()
         if self.batcher.next(self.told, text, self.outbox.put) is None:
             raise Stalled(errno.ENOSPC, "nothing taken", len(text))
-        self._rouse()
+        # a fold of the carrier's own writes here, and its pass follows in the
+        # same turn: only another thread has a carrier to wake
+        if threading.current_thread() is not self.thread:
+            self.rouse()
 
-    def _rouse(self) -> None:
-        """Say there is something to carry, and find a carrier if there is none."""
+    def rouse(self) -> None:
+        """Start the carrier if there is none, and say there is something for it."""
         with self.guard:
             # a carrier that stopped takes delivery with it, and one is not
             # worth starting for a process already on its way out
@@ -81,23 +85,17 @@ class Deliverer:
         while not self.leaving:
             # a thread that dies takes delivery with it and tells nobody
             with contextlib.suppress(Exception):
-                roused = self.woken.wait(self._waiting())
+                self.woken.wait(self._waiting())
                 self.woken.clear()
-                if time.monotonic() < self.due:
+                now = time.monotonic()
+                if now < self.due:
                     continue
+                # on this clock and no other: a far end refusing and then taking
+                # ends a wait every standoff, and a wait ending is not a period
+                if now - self.folded >= self.interval:
+                    self.folded = now
+                    self.fold()
                 self.offering()
-                # a period, never a wake: a wake says there is something to
-                # carry, and asking for more on one made each flush bring the
-                # next. Nothing in hand, or the far end is still refusing
-                now = time.monotonic()
-                if (
-                    not roused
-                    and self.holding is None
-                    and not self.leaving
-                    and now - self.reminded >= self.interval
-                ):
-                    self.reminded = now
-                    self.remind()
 
     def parting(self) -> None:
         """Give whatever is held one bounded chance to travel, then give up."""
@@ -128,11 +126,15 @@ class Deliverer:
         # every worker of a pre-forking server was born in the same second
         self.due = 0.0
         self.tries = 0
-        self.reminded = 0.0
+        self.folded = NEVER
         # a child is not on its way out merely because its parent was
         self.leaving = False
         self.batcher.forked()
         self.outbox.forked()
+        # the clock is this thread's, and the child has none until it is
+        # started again. Safe here because threading's own fork handler, which
+        # registered first, has already run
+        self.rouse()
 
     def registered(self) -> None:
         """Ask the interpreter to say when this process has become two."""
@@ -173,6 +175,8 @@ class Deliverer:
         self.due = time.monotonic() + standoff(self.tries, self.share())
 
     def _waiting(self) -> float:
-        """Wait out a standoff if there is one, and otherwise a pass."""
-        left = self.due - time.monotonic()
-        return left if left > 0 else self.interval
+        """Wait out a standoff if there is one, and otherwise until the next fold."""
+        now = time.monotonic()
+        if self.due > now:
+            return self.due - now
+        return max(0.0, self.folded + self.interval - now)

{fluidattacks_agent-0.1.2 → fluidattacks_agent-0.2.0}/fluidattacks_agent/post.py

@@ -118,6 +118,16 @@ def targeted(path: str, query: str) -> str:
     return f"{path or '/'}?{query}" if query else path or "/"
 
 
+def prepared() -> None:
+    """Import what a post needs, where a fork cannot catch an import half done."""
+    # a fork taken while another thread holds a module's import lock leaves
+    # that lock held in the child forever, so these are taken under the fold's
+    # own lock, which a fork waits out, and never first on the thread that posts
+    import http.client  # noqa: F401, PLC0415
+    import ssl  # noqa: F401, PLC0415
+    import urllib.parse  # noqa: F401, PLC0415
+
+
 def proven() -> "ssl.SSLContext":
     """Give a context the far end has to prove itself on, hostname included."""
     import ssl  # noqa: PLC0415

{fluidattacks_agent-0.1.2 → fluidattacks_agent-0.2.0}/fluidattacks_agent/settings.py

@@ -91,15 +91,6 @@ def _credential(value: str | None) -> Secret | None:
     return Secret(named) if _readable(named) else None
 
 
-def asked(environ: Mapping[str, str] | None = None) -> bool:
-    """Say whether the workload asked for its reports to be delivered at all."""
-    try:
-        held = os.environ if environ is None else environ
-        return _setting(held, ENDPOINT) is not None or ENDPOINT in held
-    except Exception:  # noqa: BLE001
-        return False
-
-
 def delivery(environ: Mapping[str, str] | None = None) -> Delivery | None:
     """Read where reports go, or nothing at all if it cannot be read whole."""
     try:

fluidattacks_agent-0.2.0/fluidattacks_agent/sink.py

@@ -0,0 +1,16 @@
+"""Somewhere a report can go, and the refusal that says it did not."""
+
+from typing import Final, Protocol
+
+# what a workload's own exit may be delayed by while what is held goes out
+PARTING: Final = 2.0
+
+
+class Stalled(OSError):
+    """Nothing was taken, and what was not taken is still owed."""
+
+
+class Sink(Protocol):
+    """Somewhere a report can go, which may refuse it and must never lie."""
+
+    def write(self, text: str) -> None: ...

{fluidattacks_agent-0.1.2 → fluidattacks_agent-0.2.0}/fluidattacks_agent/startup.py

@@ -1,4 +1,4 @@
-"""Start the probe inside a workload and leave reports where the agent drains."""
+"""Start the probe inside a workload and hand its reports to what carries them."""
 
 import _thread
 import atexit
@@ -9,19 +9,19 @@ import time
 from collections.abc import Callable
 from dataclasses import dataclass, field, replace
 from types import CodeType, ModuleType
-from typing import Final
+from typing import TYPE_CHECKING, Final
 
 from fluidattacks_agent.distributions import Dist, distribution_map
 from fluidattacks_agent.executions import TOOL, TOOL_NAME, RunObserver, alone, available
 from fluidattacks_agent.loads import LoadObserver
 from fluidattacks_agent.observer import ImportObserver, install
 from fluidattacks_agent.report import Evidence, Record, Window, keyed, render
-from fluidattacks_agent.settings import Delivery, asked, delivery
-from fluidattacks_agent.sink import FileSink, Holding, Sink, Stalled
+from fluidattacks_agent.settings import Delivery, delivery
+from fluidattacks_agent.sink import PARTING, Sink, Stalled
 from fluidattacks_agent.switch import switched_on
 
-# first sightings between flushes. The carrier's clock brings the rest
-FLUSH_EVERY: Final = 128
+if TYPE_CHECKING:
+    from fluidattacks_agent.deliver import Deliverer
 
 # what a site directory is given so that installing the package starts the
 # probe. The agent writes the same line when it injects one it did not install
@@ -33,6 +33,10 @@ PTH_LINE: Final = "import fluidattacks_agent.gate\n"
 MS: Final = 1_000_000
 SECOND: Final = 1000
 
+# what a workload's fork may be delayed by while a fold under way ends: a fold
+# imports, and a lock held across a fork is held in the child forever
+FORKING: Final = 0.5
+
 START: Final = time.monotonic_ns()
 
 # the reader reads u= as milliseconds since the epoch. Taken once and advanced
@@ -47,9 +51,9 @@ def reached() -> int:
 
 @dataclass
 class Probe:
-    """An observer whose reports are left behind as the workload runs."""
+    """An observer whose reports are handed on as the workload runs."""
 
-    sink: Sink = field(default_factory=FileSink)
+    sink: Sink
     observer: ImportObserver = field(default_factory=ImportObserver)
     loads: LoadObserver = field(default_factory=LoadObserver)
     runs: RunObserver = field(default_factory=RunObserver)
@@ -63,8 +67,13 @@ class Probe:
     first: dict[tuple[str, str], int] = field(default_factory=dict)
     last: dict[tuple[str, str], int] = field(default_factory=dict)
     scanned: dict[str, Dist] | None = None
-    pending: int = 0
+    # set while a fold runs, with the thread running it: that thread's own
+    # reads and imports are the probe's, and every other thread's are the
+    # workload's, so a fold no longer costs anyone else their evidence
     flushing: bool = False
+    folder: int = 0
+    # whether a fork in progress holds the gate, so the parent gives it back
+    pausing: bool = False
     stalled: int = 0
     charged: int = 0
     # owed until a report states them: a flush can end after charging a record
@@ -72,16 +81,12 @@ class Probe:
     refused: int = 0
     undated: int = 0
     monitoring: bool = False
-    looking: bool = False
     # sampled when the events were armed, not when the report is written: the
     # later reading governs the next window rather than the one reported
     solitary: bool = False
-    # set off the workload's threads, acted on by the next sighting on one of
-    # them, since what is held is walked nowhere else
-    overdue: bool = False
-    # every thread sees overdue at once, so the flush is gated by a lock nothing
-    # waits on: a second caller finds it taken and returns. From _thread, which
-    # every interpreter start has already paid for, and threading is not
+    # one fold at a time: the carrier takes this without waiting, the exit with
+    # a bound. From _thread, which every interpreter start has already paid
+    # for, and threading is not
     gate: _thread.LockType = field(default_factory=_thread.allocate_lock, repr=False)
 
     def find_spec(
@@ -90,90 +95,92 @@ class Probe:
         _path: object = None,
         _target: ModuleType | None = None,
     ) -> None:
-        """Note the lookup, and leave a report once enough have piled up."""
-        held = self.looking
-        self.looking = True
-        try:
-            with contextlib.suppress(Exception):
-                self._looked(fullname)
-        finally:
-            self.looking = held
+        """Note the lookup, and claim nothing."""
+        with contextlib.suppress(Exception):
+            self._looked(fullname)
+
+    def _folding(self) -> bool:
+        # a fold of ours reads and imports on its own account, and none of that
+        # is the workload using anything. Its own thread only: the cost of
+        # asking is paid while a fold runs and at no other time
+        return self.flushing and _thread.get_ident() == self.folder
 
     def _looked(self, fullname: str) -> None:
-        if self.flushing:
+        if self._folding():
             return
         module = self.observer.note(fullname)
-        self._pile(0 if module is None else self._mark(Evidence.IMPORTED, module))
+        if module is not None:
+            self._mark(Evidence.IMPORTED, module)
 
     def read(self, path: str) -> None:
-        """Note a file the workload opened, and report as those pile up too."""
-        # a flush of ours reads and imports on its own account, and none of that
-        # is the workload using anything
-        if self.flushing:
+        """Note a file the workload opened."""
+        if self._folding():
             return
         package = self.loads.note(path)
         # tested here and not inside: the hook runs on every open the host
         # makes, and all but a few are not ours to stamp
-        self._pile(0 if package is None else self._mark(Evidence.READ, package))
+        if package is not None:
+            self._mark(Evidence.READ, package)
 
     def ran(self, filename: str, qualname: str) -> None:
-        """Note code starting, and report as first sightings pile up too."""
-        if self.flushing:
+        """Note code starting."""
+        if self._folding():
             return
         symbol = self.runs.note(filename, qualname)
-        self._pile(0 if symbol is None else self._mark(Evidence.EXECUTED, symbol))
+        if symbol is not None:
+            self._mark(Evidence.EXECUTED, symbol)
 
-    def _mark(self, evidence: Evidence, symbol: str) -> int:
-        """Stamp a sighting, saying whether it was the first of its symbol."""
+    def _mark(self, evidence: Evidence, symbol: str) -> None:
+        """Stamp a sighting: when its symbol was first reached, and this once."""
         key = keyed(evidence, symbol)
         seen = self.clock()
         self.last[key] = seen
-        if key in self.first:
-            return 0
-        self.first[key] = seen
-        return 1
-
-    def remind(self) -> None:
-        """Have the next sighting bring a flush, however few have piled up."""
-        # a flag and never a flush: the carrier's clock calls this from a
-        # thread of its own, and a flush runs on the workload's alone
-        self.overdue = True
-
-    def _pile(self, added: int) -> None:
-        # first sightings only: a flush re-arms every code object, so counting
-        # one seen again, or one with no room, made each flush bring the next
-        self.pending += added
-        if self.overdue or self.pending >= FLUSH_EVERY:
-            # cleared before the call, because monitoring reports the entry of
-            # flush itself and would otherwise pile up and call it again
-            self.pending = 0
-            self.flush()
+        self.first.setdefault(key, seen)
 
     def flush(self) -> None:
-        """Write what has not been reported, without ever raising at a caller."""
-        if not self.gate.acquire(blocking=False):
+        """Write what has not been reported, waiting out a fold under way."""
+        # the exit's: a fold under way is the last window being rendered, and
+        # what this renders after it is whatever that one had not
+        self._fold(self.gate.acquire(timeout=PARTING))
+
+    def fold(self) -> None:
+        """Write what has not been reported, unless a fold is already under way."""
+        # the carrier's: nothing here waits, since the next period comes
+        self._fold(self.gate.acquire(blocking=False))
+
+    def _fold(self, acquired: bool) -> None:
+        if not acquired:
             return
+        self.folder = _thread.get_ident()
         self.flushing = True
-        # spent here, so a reminder given while this runs brings one more flush
-        self.overdue = False
         try:
             with contextlib.suppress(Exception):
                 if self._sighted():
                     self._write_fresh(self._installed())
         finally:
-            self.pending = 0
             self.flushing = False
             self.gate.release()
             self._rearm()
 
+    def forking(self) -> None:
+        """Hold a fold under way until the fork is done, for as long as a fold takes."""
+        # bounded, because the fold may itself be waiting on an import the
+        # forking thread holds: past the bound the fork goes on as it would have
+        self.pausing = self.gate.acquire(timeout=FORKING)
+
+    def resumed(self) -> None:
+        """Let the parent fold again once its fork is done."""
+        if self.pausing:
+            self.pausing = False
+            self.gate.release()
+
     def forked(self) -> None:
-        """Leave a child able to flush, whatever its parent was doing at the fork."""
+        """Leave a child able to fold, whatever its parent was doing at the fork."""
         # a lock another thread held at the fork is held in the child forever,
         # and a flag it set stays set: the child has no thread left to clear it
         self.gate = _thread.allocate_lock()
         self.flushing = False
-        self.overdue = False
-        self.pending = 0
+        self.pausing = False
 
     def _owed(self) -> bool:
         """Say whether a count is waiting for a report that can state it."""
@@ -181,13 +188,15 @@ class Probe:
 
     def _sighted(self) -> bool:
         """Say whether this window holds anything a report could carry."""
+        # what moved and not what is held, since only that can be a record; and
+        # a copy of it, since the workload's threads add to it meanwhile
         return bool(
             self._owed()
-            or self.loads.seen
-            or self.runs.seen
+            or self.loads.moved
+            or self.runs.moved
             # a lookup that never became a module is dropped when the records are
             # folded, so on its own it is not cause to walk any metadata
-            or any(name in sys.modules for name in self.observer.seen)
+            or any(name in sys.modules for name in list(self.observer.moved))
             or any(self._beyond().values())
             or self.stalled != self.charged,
         )
@@ -202,11 +211,6 @@ class Probe:
     def _installed(self) -> dict[str, Dist]:
         if self.scanned is not None:
             return self.scanned
-        if self.looking:
-            # the walk imports, and a lookup of ours runs while the interpreter
-            # holds the lock every other import is waiting on. Not remembered,
-            # so the next flush outside one still reads it
-            return {}
         try:
             scanned = self.distributions()
         except ImportError:
@@ -382,58 +386,54 @@ def running() -> Probe | None:
     return None
 
 
-def start(sink: Sink | None = None) -> Probe | None:
+def start() -> Probe | None:
     """Put the probe on the import path, unless one is there or it is unwanted."""
     try:
-        return _start(sink)
+        return _start()
     except Exception:  # noqa: BLE001
         # every interpreter the workload runs reaches this line, and what runs
         # it prints whatever escapes to the host's stderr and carries on
         return None
 
 
-def chosen(remind: Callable[[], None]) -> Sink:
-    """
-    Give a workload what it asked for, and something loud if it asked badly.
-
-    ``remind`` is what a carrier calls, off the workload's threads, once a
-    period has gone by with the far end in reach and nothing left to carry.
-    """
-    if not asked():
-        return FileSink()
-    told = delivery()
-    if told is None:
-        # half configured must be loud, not indistinguishable from quiet
-        return Holding()
-    return carrier(told, remind)
-
-
-def carrier(told: Delivery, remind: Callable[[], None]) -> Sink:
-    """Build the one thing that carries reports out, and wire it to this process."""
+def carrier(told: Delivery) -> "Deliverer":
+    """Build the one thing that carries reports out, wired to nothing yet."""
     # imported here, so a workload that never asked pays for none of it
     from fluidattacks_agent.deliver import Deliverer  # noqa: PLC0415
 
-    held = Deliverer(told=told, remind=remind)
-    # before the flush handler, since exit handlers run in reverse order
-    atexit.register(held.parting)
-    held.registered()
-    return held
+    return Deliverer(told=told)
 
 
-def _start(sink: Sink | None) -> Probe | None:
+def _start() -> Probe | None:
     held = running()
     if held is not None:
         return held
     if not switched_on():
         return None
+    told = delivery()
+    if told is None:
+        # nowhere to deliver is nothing to observe for
+        return None
     sites = site_dirs()
-    probe = Probe(loads=LoadObserver(sites=sites), runs=RunObserver(sites=sites))
-    # after the probe, because what carries its reports is told what to remind
-    probe.sink = chosen(probe.remind) if sink is None else sink
-    if hasattr(os, "register_at_fork"):
-        os.register_at_fork(after_in_child=probe.forked)
+    carrying = carrier(told)
+    probe = Probe(sink=carrying, loads=LoadObserver(sites=sites), runs=RunObserver(sites=sites))
+    carrying.fold = probe.fold
     install(probe)
     sys.addaudithook(watch(probe))
     probe.monitoring = observe_runs(probe)
+    # last, because none of these can be taken back: everything above that a
+    # host could refuse has been refused or not by now. The carrier's parting
+    # goes before the flush, since exit handlers run in reverse order
+    atexit.register(carrying.parting)
+    carrying.registered()
+    if hasattr(os, "register_at_fork"):
+        os.register_at_fork(
+            before=probe.forking,
+            after_in_parent=probe.resumed,
+            after_in_child=probe.forked,
+        )
     atexit.register(probe.flush)
+    # the clock starts with the probe, so a worker that sees little still
+    # reports what it saw when the period ends
+    carrying.rouse()
     return probe

{fluidattacks_agent-0.1.2 → fluidattacks_agent-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fluidattacks-agent"
-version = "0.1.2"
+version = "0.2.0"
 description = "In-process probe reporting what a Python workload imports and runs"
 readme = "README.md"
 authors = [{ name = "Development", email = "development@fluidattacks.com" }]

fluidattacks_agent-0.1.2/fluidattacks_agent/sink.py

@@ -1,163 +0,0 @@
-"""Leave a report where something can pick it up, or refuse and say which."""
-
-import contextlib
-import errno
-import os
-import stat
-from dataclasses import dataclass, field
-from typing import Final, Protocol
-
-# the path is a contract with the agent that drains it
-REPORT_DIR: Final = "/tmp/.watches-exec"  # noqa: S108
-REPORT_SUFFIX: Final = ".report"
-STAGE_SUFFIX: Final = ".tmp"
-
-# reports of its own, bytes any report holds, and entries it will walk to count
-MAX_OUTSTANDING: Final = 64
-MAX_OUTSTANDING_BYTES: Final = 8 << 20
-MAX_ENTRIES: Final = 4096
-
-SHARED: Final = 0o077
-
-
-class Stalled(OSError):
-    """Nothing was taken, and what was not taken is still owed."""
-
-
-class Sink(Protocol):
-    """Somewhere a report can go, which may refuse it and must never lie."""
-
-    def write(self, text: str) -> None: ...
-
-
-def ours(status: os.stat_result) -> bool:
-    """Say whether what the status describes is ours alone to write."""
-    return status.st_uid == os.geteuid() and not status.st_mode & SHARED
-
-
-@dataclass(frozen=True)
-class Held:
-    """What one directory entry costs, and whether the sink left it there."""
-
-    size: int
-    mine: bool
-
-
-def _held(entry: os.DirEntry[str], stem: str) -> Held:
-    if not entry.name.endswith(REPORT_SUFFIX):
-        return Held(size=0, mine=False)
-    try:
-        status = entry.stat(follow_symlinks=False)
-    except OSError:
-        return Held(size=0, mine=False)
-    if not stat.S_ISREG(status.st_mode):
-        return Held(size=0, mine=False)
-    return Held(size=status.st_size, mine=entry.name.startswith(stem))
-
-
-class Holding:
-    """A sink for a workload that asked for delivery, which nothing yet does."""
-
-    def write(self, text: str) -> None:
-        """Take nothing, and be counted for it."""
-        raise Stalled(errno.ENOSYS, "nothing delivers yet", len(text))
-
-
-@dataclass
-class FileSink:
-    """Reports left in a directory of our own for the agent to drain."""
-
-    directory: str | os.PathLike[str] = REPORT_DIR
-    written: int = 0
-    # so a report of ours cannot be named by anything that did not write it,
-    # and a reused pid never counts its predecessor's against itself
-    token: str = field(default_factory=lambda: os.urandom(8).hex())
-
-    def write(self, text: str) -> None:
-        """Take a report, unless what is already here says to stop."""
-        directory = self._open_directory()
-        try:
-            # installed on its own nothing drains this, so the ceiling is ours
-            if self._piled(directory):
-                raise Stalled(errno.ENOSPC, "reports outstanding")
-            self._write_into(directory, text)
-        finally:
-            os.close(directory)
-
-    def _open_directory(self) -> int:
-        # every way this can fail is a flush that did not land, and one that
-        # said so as anything else was a mute nothing counted: a directory this
-        # cannot use costs an attacker one bit of its mode
-        try:
-            with contextlib.suppress(FileExistsError):
-                os.mkdir(self.directory, 0o700)  # noqa: PTH102
-            handle = os.open(self.directory, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
-        except OSError as refused:
-            raise Stalled(errno.EACCES, "no directory", str(self.directory)) from refused
-        # the mode a directory was made with says nothing about one that was
-        # already there, and the descriptor is what the answer has to be about
-        if ours(os.fstat(handle)):
-            return handle
-        os.close(handle)
-        raise Stalled(errno.EACCES, "not ours", str(self.directory))
-
-    def _piled(self, directory: int) -> bool:
-        mine = 0
-        bytes_held = 0
-        walked = 0
-        with os.scandir(directory) as entries:
-            for entry in entries:
-                walked += 1
-                # too full to keep writing into, whoever filled it
-                if walked > MAX_ENTRIES:
-                    return True
-                held = _held(entry, self._stem())
-                bytes_held += held.size
-                mine += int(held.mine)
-                if mine >= MAX_OUTSTANDING or bytes_held >= MAX_OUTSTANDING_BYTES:
-                    return True
-        return False
-
-    def _stem(self) -> str:
-        return f"{os.getpid()}-{self.token}-"
-
-    def _write_into(self, directory: int, text: str) -> None:
-        payload = text.encode()
-        stem = f"{self._stem()}{self.written}"
-        staged = stem + STAGE_SUFFIX
-        # spent the moment it is tried: what sits under a name is not always
-        # ours to clear, and coming back to one forever is how one silences us
-        self.written += 1
-        try:
-            self._stage(directory, staged, payload)
-            os.replace(
-                staged,
-                stem + REPORT_SUFFIX,
-                src_dir_fd=directory,
-                dst_dir_fd=directory,
-            )
-        except OSError as refused:
-            # nothing will ever read what a failed attempt staged, and the name
-            # it holds counts against the entries this is willing to walk
-            with contextlib.suppress(OSError):
-                os.unlink(staged, dir_fd=directory)
-            raise Stalled(errno.ENOSPC, "not taken", staged) from refused
-
-    def _stage(self, directory: int, name: str, payload: bytes) -> None:
-        handle = self._create(directory, name)
-        try:
-            written = os.write(handle, payload)
-        finally:
-            os.close(handle)
-        # os.write does not raise on a partial write, and the statement is the
-        # last line, so a truncation takes it first
-        if written != len(payload):
-            raise OSError(errno.ENOSPC, "short write", name)
-
-    def _create(self, directory: int, name: str) -> int:
-        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
-        try:
-            return os.open(name, flags, 0o600, dir_fd=directory)
-        except FileExistsError:
-            os.unlink(name, dir_fd=directory)
-            return os.open(name, flags, 0o600, dir_fd=directory)