steam-backlog-enforcer/steam_installer/runlog.py
Krzysztof kuhy Rudnicki a76e726e36 Merge steam-game-installer into the repo
The installer ships as the steam_installer package beside
steam_backlog_enforcer, with its tests, docs and Proton lock. The
enforcer's fast install now starts the installer from this checkout.

Both appinfo.vdf readers share one key-value decoder
(steam_installer.appinfo_kv), and the duplicated test fixtures and
helpers are folded into conftest and _cli_helpers so the whole-tree
duplicate-code check is clean. check_requirements_sync treats sibling
packages as first-party.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWZCxnNWLtpVwFLVk9w
2026-11-22 20:25:39 +01:00

234 lines
7.7 KiB
Python

"""Per-run logging.
Everything a run does lands in one file the user can copy-paste verbatim when
something goes wrong. The first version of this tool had no logging at all, and
when a run failed the evidence was gone: Steam owns appmanifest_<appid>.acf and
had already overwritten the manifest we wrote by the time anyone looked. So the
log records the manifest *verbatim, before and after* every write, alongside the
full output of every subprocess.
Subprocess output is teed through a pty rather than captured with
`capture_output=True`. depotdownloader prompts for a password (and possibly a
Steam Guard code) on stdin; prompt text written to a captured/buffered pipe never
reaches the terminal, so the process looks hung with no visible request for
input. A pty keeps it in line-buffered interactive mode and lets us
mirror every byte to both the terminal and the log.
"""
from __future__ import annotations
from dataclasses import dataclass
import errno
import io
import logging
import os
from pathlib import Path
import pty
import select
import shlex
import subprocess
import sys
import time
LOG_DIR = Path.home() / ".local/state/steam-game-installer"
LOGGER_NAME = "steam_installer"
_CONSOLE_FORMAT = "%(message)s"
_FILE_FORMAT = "%(asctime)s %(levelname)-7s %(name)s: %(message)s"
# Read granularity for the pty relay. Large enough that depotdownloader's
# progress spam doesn't cost a syscall per line, small enough to stay responsive.
_READ_CHUNK = 65536
@dataclass
class RunLog:
"""A single run's log file, plus the `latest.log` symlink pointing at it."""
path: Path
logger: logging.Logger
def section(self, title: str) -> None:
"""A visual divider so a pasted log is skimmable."""
self.logger.debug("=" * 72)
self.logger.debug(title)
self.logger.debug("=" * 72)
def file_contents(self, label: str, path: Path) -> None:
"""Record a file verbatim. Used for manifests before/after every write."""
self.section(f"{label}: {path}")
try:
self.logger.debug("\n%s", path.read_text())
except OSError as exc:
self.logger.debug("(unreadable: %s)", exc)
def setup(appid: int | None, *, verbose: bool = False) -> RunLog:
"""Start a run log. Console stays terse; the file gets everything at DEBUG."""
LOG_DIR.mkdir(parents=True, exist_ok=True)
stamp = time.strftime("%Y%m%d-%H%M%S")
path = LOG_DIR / f"run-{stamp}-{appid if appid is not None else 'noappid'}.log"
logger = logging.getLogger(LOGGER_NAME)
logger.setLevel(logging.DEBUG)
logger.propagate = False
# A second setup() in the same process (tests) must not double-log.
for handler in list(logger.handlers):
logger.removeHandler(handler)
handler.close()
file_handler = logging.FileHandler(path, encoding="utf-8")
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(logging.Formatter(_FILE_FORMAT))
logger.addHandler(file_handler)
console = logging.StreamHandler(sys.stdout)
console.setLevel(logging.DEBUG if verbose else logging.INFO)
console.setFormatter(logging.Formatter(_CONSOLE_FORMAT))
logger.addHandler(console)
_point_latest_at(path)
return RunLog(path=path, logger=logger)
def _point_latest_at(path: Path) -> None:
"""Best-effort `latest.log` symlink -- a stale symlink must never fail a run."""
latest = LOG_DIR / "latest.log"
try:
if latest.is_symlink() or latest.exists():
latest.unlink()
latest.symlink_to(path.name)
except OSError:
pass
def _spawn_on_pty(
cmd: list[str], master_fd: int, slave_fd: int
) -> subprocess.Popen[bytes]:
"""Start `cmd` with its output on the pty; close both ends if it won't start."""
try:
return subprocess.Popen(
cmd,
stdout=slave_fd,
stderr=slave_fd,
stdin=_stdin_for_child(slave_fd),
close_fds=True,
)
except OSError:
os.close(master_fd)
os.close(slave_fd)
raise
def run_logged(
cmd: list[str],
logger: logging.Logger,
timeout: float | None = None,
) -> tuple[int, str]:
"""Run `cmd` on a pty, mirroring output to both the terminal and the log.
Returns (returncode, combined_output). stdin stays attached to the real
terminal so interactive prompts (depotdownloader's password / Steam Guard) work
exactly as they do without logging.
"""
logger.debug("$ %s", shlex.join(cmd))
started = time.monotonic()
master_fd, slave_fd = pty.openpty()
chunks: list[bytes] = []
process = _spawn_on_pty(cmd, master_fd, slave_fd)
# The child owns the slave end now; holding it open here would keep the
# master readable forever and hang the relay after the child exits.
os.close(slave_fd)
try:
_relay(master_fd, chunks, process, timeout, started)
except subprocess.TimeoutExpired as exc:
# Record what the child managed to say before it hung, then re-raise.
# Losing it here defeats the whole point of the log in precisely the
# case where it matters most -- a download hung until its timeout.
output = _log_output(logger, chunks, started, returncode=None)
process.wait()
exc.output = output.encode()
raise
finally:
os.close(master_fd)
returncode = process.wait()
output = _log_output(logger, chunks, started, returncode)
return returncode, output
def _log_output(
logger: logging.Logger,
chunks: list[bytes],
started: float,
returncode: int | None,
) -> str:
output = b"".join(chunks).decode("utf-8", errors="replace")
elapsed = time.monotonic() - started
logger.debug("--- output (%d bytes) ---\n%s", len(output), output)
if returncode is None:
logger.debug("TIMED OUT after %.1fs", elapsed)
else:
logger.debug("exit=%d elapsed=%.1fs", returncode, elapsed)
return output
def _read_pty(fd: int, size: int) -> bytes:
"""Read from the pty; an indirection so tests can fault-inject it.
Tests use it instead of patching the global `os.read`, which subprocess
itself uses during spawn.
"""
return os.read(fd, size)
def _stdin_for_child(slave_fd: int) -> int:
"""The child's stdin: the real terminal when there is one, else the pty.
depotdownloader needs a readable stdin to prompt for a password, but `sys.stdin`
is not always a real file descriptor -- under pytest's capture, systemd, or
a piped invocation it has no fileno(). Falling back to the pty's slave end
keeps the child on a terminal-like stdin instead of crashing.
"""
try:
return sys.stdin.fileno()
except AttributeError, ValueError, OSError, io.UnsupportedOperation:
return slave_fd
def _relay(
master_fd: int,
chunks: list[bytes],
process: subprocess.Popen[bytes],
timeout: float | None,
started: float,
) -> None:
"""Pump pty output to stdout and `chunks` until the child closes it."""
while True:
if timeout is not None and time.monotonic() - started > timeout:
process.kill()
raise subprocess.TimeoutExpired(process.args, timeout)
try:
ready, _, _ = select.select([master_fd], [], [], 0.2)
except OSError:
break
if not ready:
# No output pending; the child may still have exited.
if process.poll() is not None:
break
continue
try:
data = _read_pty(master_fd, _READ_CHUNK)
except OSError as exc:
# EIO is the normal "child closed the pty" signal on Linux.
if exc.errno == errno.EIO:
break
raise
if not data:
break
chunks.append(data)
sys.stdout.buffer.write(data)
sys.stdout.buffer.flush()