steam-backlog-enforcer/steam_backlog_enforcer/_serve_guard.py
Krzysztof kuhy Rudnicki 47f77f5f1e
Some checks are pending
dependency freshness / dependencies on newest stable (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
pre-commit / pre-commit (push) Waiting to run
Tests / test (push) Waiting to run
Make serve re-runnable, and cover it to 100%
The serve rework was sitting untracked: a /proc-based port guard, the
start-or-defer decision, and a stale-bundle rebuild. It had no tests, and it
changed cmd_serve(_config, state) to cmd_serve(argv) without updating the one
test that called it, so the suite was red and coverage was 251 lines short.

Tests, all against fakes:
- _fake_proc builds a synthetic /proc. _NET_TCP is derived from _PROC at
  import time, so patch_proc redirects both; patching _PROC alone would have
  had these tests parse the host's real process table.
- _serve_guard is split across two test files to stay under the 250-line cap.
  os is replaced wholesale in every termination test, so no signal can reach a
  real process even if the guard's self-protection were removed.
- _web_build mocks subprocess entirely and redirects every path constant into
  tmp_path. _no_subprocess now blocks _web_build.subprocess.run too: an
  unguarded test would fire a real `npm run build`, rewriting web/dist and
  perturbing frontend_is_stale() for every later test in the run.

Source changes, both required rather than incidental:
- _serve_guard's wildcard match was a `# noqa: S104` on a "0.0.0.0" literal,
  which the no-noqa hook rejects outright. It is now the all-zero hex column
  /proc actually prints, so the dotted-quad literal never appears.
- main/__init__.py's serve dispatch arm was itself uncovered; it now has a
  test asserting the raw argv passes through unparsed.

Also drops the document.hidden guard from useBudgetPoll: it skipped the very
first load, so the budget panel sat on "Reading budget state…" forever in a
background tab, which is every tab under browser automation.

Verified: 1712 python tests, 100% branch coverage; 128 vitest, 100%. The
guard's /proc parser was checked read-only against a real listener on :8000
and resolved the same pid as `ss`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MKFzwzwRU1JD7SFLHtQBsz
2026-08-29 18:52:11 +02:00

249 lines
8.3 KiB
Python

"""Guard that makes ``serve`` safe to run twice.
Binding a second web server to the same port used to raise a bare
``OSError: [Errno 98]`` traceback. Instead of failing, this resolves *who*
owns the port and decides between three outcomes: an already-running server on
current code is reported and the caller exits 0; one running stale code is
terminated so a fresh process can take the port; anything else is a hard error
naming the owner.
Ownership is resolved through ``/proc`` rather than ``ss`` so the whole thing
stays importable, dependency-free and unit-testable against a fake ``/proc``.
"""
from __future__ import annotations
import contextlib
import os
from pathlib import Path
import signal
import socket
import time
_PROC = Path("/proc")
_NET_TCP = (_PROC / "net" / "tcp", _PROC / "net" / "tcp6")
# /proc/net/tcp state column: 0A is TCP_LISTEN. Anything else is a connection,
# not a bind, and must not be mistaken for the process owning the port.
_LISTEN_STATE = "0A"
# argv fragments that identify one of our own web servers.
_OWN_MODULE = "steam_backlog_enforcer.main"
_OWN_COMMAND = "serve"
# Package tree whose .py mtimes decide whether a running server is stale.
_PACKAGE_ROOT = Path(__file__).resolve().parent
# A wildcard IPv4 bind renders as an all-zero address column. Spelled as hex
# rather than _hex_v4("0.0.0.0") so the dotted-quad literal never appears: this
# module only ever *matches* that address, it must never bind it.
_WILDCARD_V4 = "0" * 8
# /proc/<pid>/stat after the comm field: fields[0] is state, fields[1] ppid.
_MIN_STAT_FIELDS_AFTER_COMM = 2
_TERM_WAIT_SECONDS = 5.0
_POLL_INTERVAL = 0.1
def _hex_port(port: int) -> str:
"""Render *port* the way /proc/net/tcp does (upper-case, 4 hex digits)."""
return f"{port:04X}"
def _hex_v4(host: str) -> str:
"""Render an IPv4 address the way /proc/net/tcp does (little-endian hex)."""
packed = socket.inet_pton(socket.AF_INET, host)
return f"{int.from_bytes(packed, 'little'):08X}"
def _hex_v6(host: str) -> str:
"""Render an IPv6 address the way /proc/net/tcp6 does.
The 16 bytes are four 32-bit words, each byte-swapped independently.
"""
packed = socket.inet_pton(socket.AF_INET6, host)
words = (packed[i : i + 4] for i in range(0, 16, 4))
return "".join(f"{int.from_bytes(word, 'little'):08X}" for word in words)
def _conflicting_addresses(host: str) -> frozenset[str]:
"""Address columns whose listener would block a bind on *host*.
Matching on the port alone is wrong: a listener on ``192.168.1.5:8000``
does not conflict with ``127.0.0.1:8000``, and reporting it as the owner
would name an innocent process. Conversely a wildcard bind (``0.0.0.0``,
``::``) or a v4-mapped one does conflict, and lives in tcp6 even when the
bind we want is IPv4 - which is why both files are scanned.
"""
return frozenset(
{
_hex_v4(host),
_WILDCARD_V4,
_hex_v6("::"),
_hex_v6(f"::ffff:{host}"),
}
)
def _listening_inodes(host: str, port: int) -> set[int]:
"""Collect socket inodes listening on an address that blocks *host*:*port*."""
suffix = ":" + _hex_port(port)
addresses = _conflicting_addresses(host)
inodes: set[int] = set()
for path in _NET_TCP:
try:
lines = path.read_text(encoding="utf-8").splitlines()[1:]
except OSError:
continue
for line in lines:
fields = line.split()
min_fields = 10
if len(fields) <= min_fields:
continue
local = fields[1]
if not local.endswith(suffix) or fields[3] != _LISTEN_STATE:
continue
if local[: -len(suffix)] not in addresses:
continue
with contextlib.suppress(ValueError):
inodes.add(int(fields[9]))
return inodes
def _pid_owns_inode(pid_dir: Path, targets: set[int]) -> bool:
"""Check whether any file descriptor of *pid_dir* is one of *targets*."""
wanted = {f"socket:[{inode}]" for inode in targets}
try:
fds = list((pid_dir / "fd").iterdir())
except OSError:
# A process we cannot inspect (other user, or exited mid-scan).
return False
for fd in fds:
try:
if fd.readlink().as_posix() in wanted:
return True
except OSError:
continue
return False
def find_port_owner(host: str, port: int) -> int | None:
"""Return the PID listening on *port*, or None if nothing is.
Only processes readable by this user can be attributed; a listener owned
by another user resolves to None, which callers must treat as "occupied by
something I cannot identify", never as "free".
"""
inodes = _listening_inodes(host, port)
if not inodes:
return None
for entry in _PROC.iterdir():
if not entry.name.isdigit():
continue
if _pid_owns_inode(entry, inodes):
return int(entry.name)
return None
def read_cmdline(pid: int) -> list[str]:
"""Return argv for *pid*, or an empty list if it cannot be read."""
try:
raw = (_PROC / str(pid) / "cmdline").read_bytes()
except OSError:
return []
return [part for part in raw.decode("utf-8", "replace").split("\0") if part]
def is_our_server(pid: int) -> bool:
"""Check whether *pid* is one of our own ``serve`` processes."""
argv = read_cmdline(pid)
return _OWN_MODULE in argv and _OWN_COMMAND in argv
def process_started_at(pid: int) -> float | None:
"""Return the start time of *pid* as an epoch float.
``/proc/<pid>`` itself is stamped with the process start time, which is
exactly the boundary we need: any source file newer than it was not the
file that process loaded.
"""
try:
return (_PROC / str(pid)).stat().st_mtime
except OSError:
return None
def newest_py_since(started_at: float) -> Path | None:
"""Return the newest ``.py`` in the package modified after *started_at*.
Returning the path rather than a bool is deliberate: the restart message
names the file, so the decision to kill a server is always auditable.
"""
newest: Path | None = None
newest_mtime = started_at
for path in _PACKAGE_ROOT.rglob("*.py"):
try:
mtime = path.stat().st_mtime
except OSError:
continue
if mtime > newest_mtime:
newest, newest_mtime = path, mtime
return newest
def _own_pid_chain() -> set[int]:
"""Return this process and its ancestors.
The process running this check matches :func:`is_our_server` by
construction, so a wrong owner lookup would otherwise have us kill
ourselves mid-startup.
"""
chain: set[int] = set()
pid: int | None = os.getpid()
while pid is not None and pid > 0 and pid not in chain:
chain.add(pid)
pid = _read_ppid(pid)
return chain
def _read_ppid(pid: int) -> int | None:
"""Return the parent PID of *pid* from ``/proc/<pid>/stat``."""
try:
stat = (_PROC / str(pid) / "stat").read_text(encoding="utf-8")
except OSError:
return None
# comm sits in parentheses and may contain spaces; ppid follows it.
_, _, rest = stat.partition(") ")
fields = rest.split()
if len(fields) < _MIN_STAT_FIELDS_AFTER_COMM:
return None
with contextlib.suppress(ValueError):
return int(fields[1])
return None
def port_is_free(host: str, port: int) -> bool:
"""Check whether *host*:*port* can actually be bound right now."""
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
try:
probe.bind((host, port))
except OSError:
return False
return True
def terminate(pid: int, host: str, port: int) -> bool:
"""Stop *pid*, escalating to SIGKILL, and wait for the port to free up."""
if pid in _own_pid_chain():
return False
for sig in (signal.SIGTERM, signal.SIGKILL):
with contextlib.suppress(ProcessLookupError, PermissionError):
os.kill(pid, sig)
deadline = time.monotonic() + _TERM_WAIT_SECONDS
while time.monotonic() < deadline:
if port_is_free(host, port):
return True
time.sleep(_POLL_INTERVAL)
return port_is_free(host, port)