Fail fast on Steam launch, add job desktop env

Steam launch: _wait_for_cdp_ready watches the launched Popen and raises
"Steam exited during startup (exit code N)" instead of polling 45 s, and
launching is refused when no X display is up.

Non-root jobs: desktop_user_cmd prefixes DISPLAY/XAUTHORITY/XDG_RUNTIME_DIR
via env, so a web-job Steam launch reaches the display.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWYNS1qAMRdgAtbr5Rq
This commit is contained in:
Krzysztof Rudnicki 2026-11-16 09:42:45 +01:00
parent f804a4987f
commit 4424a26dbe
11 changed files with 409 additions and 48 deletions

View File

@ -76,6 +76,9 @@ unfixable = []
[tool.ruff.lint.per-file-ignores]
"**/tests/**/*.py" = ["ARG", "D", "PLC0415", "PLR2004", "S101", "SLF001"]
"**/test_*.py" = ["ARG", "D", "PLC0415", "PLR2004", "S101", "SLF001"]
# libX11 puts local display sockets in /tmp/.X11-unix; the path is not ours to
# move to a private temp dir (and `# noqa` is banned by pre-commit).
"steam_backlog_enforcer/_desktop_env.py" = ["S108"]
[tool.ruff.lint.pydocstyle]
convention = "google"

View File

@ -28,6 +28,39 @@ from __future__ import annotations
import os
from pathlib import Path
import pwd
import re
# Where local X servers put their sockets: fixed by libX11, not a scratch file
# (pyproject waives S108 for this module). A module constant so tests (and
# repro scripts) can point it at a scratch directory.
X_SOCKET_DIR = "/tmp/.X11-unix"
# ``:0``, ``:1.0`` and ``unix:0`` are local; ``host:0`` is not.
_LOCAL_DISPLAY = re.compile(r"(?:unix)?:(\d+)(?:\.\d+)?")
def desktop_display() -> str:
"""The X display for the desktop session: inherited, else the usual ``:0``."""
return os.environ.get("DISPLAY") or ":0"
def x_display_error() -> str | None:
"""Why a program launched now has no X display to open, or ``None``.
A Steam started without a reachable display logs "Unable to open X11
display" and exits within seconds, so launching it is pointless. A web
job (a user unit with no ``DISPLAY``) hit exactly that. Only local
displays are checked, by their socket: a ``host:N`` display cannot be
probed without connecting, so it is assumed up.
"""
display = desktop_display()
match = _LOCAL_DISPLAY.fullmatch(display)
if match is None:
return None
socket = Path(X_SOCKET_DIR) / f"X{match[1]}"
if socket.exists():
return None
origin = "DISPLAY" if os.environ.get("DISPLAY") else "DISPLAY unset, default"
return f"No X display for Steam: {origin} {display} is not up ({socket} missing)"
def desktop_runtime_dir(uid: int) -> str:
@ -66,7 +99,7 @@ def desktop_env_args(user: str, uid: int) -> list[str]:
dbus_addr = os.environ.get("DBUS_SESSION_BUS_ADDRESS", dbus_default)
xauth = os.environ.get("XAUTHORITY", f"/home/{user}/.Xauthority")
return [
f"DISPLAY={os.environ.get('DISPLAY', ':0')}",
f"DISPLAY={desktop_display()}",
f"XAUTHORITY={xauth}",
f"DBUS_SESSION_BUS_ADDRESS={dbus_addr}",
f"XDG_RUNTIME_DIR={runtime_dir}",
@ -112,23 +145,41 @@ def resolve_desktop_user() -> str | None:
)
def desktop_user_cmd(cmd: list[str], user: str | None) -> list[str]:
"""Wrap *cmd* so it runs as *user* when the caller is root.
def _process_owner() -> str | None:
"""The user this process runs as, or ``None`` without a passwd entry."""
try:
return pwd.getpwuid(os.geteuid()).pw_name
except KeyError:
return None
Returns *cmd* unchanged when already unprivileged or when no desktop user
resolves; otherwise prefixes ``sudo -u <user> env <session vars>``.
def desktop_user_cmd(cmd: list[str], user: str | None) -> list[str]:
"""Wrap *cmd* so it runs in the desktop session as *user*.
As root: prefixes ``sudo -u <user> env <session vars>``, or returns *cmd*
unchanged when no desktop user resolves. Unprivileged (a web job): there
is no one to switch to, but the session vars are still prefixed with a
plain ``env`` — a user unit has no ``DISPLAY``, and a bare ``steam`` then
dies with "Unable to open X11 display". The uid comes from the process
itself, not from the lookup that falls back to 1000.
This is argv construction only — deliberately no ``subprocess`` call, so
every spawn site stays in a module covered by the test suite's
``_no_subprocess`` guard.
"""
if os.geteuid() == 0 and user and user != "root":
return [
"sudo",
"-u",
user,
"env",
*desktop_env_args(user, desktop_uid(user)),
*cmd,
]
return cmd
euid = os.geteuid()
if euid == 0:
if user and user != "root":
return [
"sudo",
"-u",
user,
"env",
*desktop_env_args(user, desktop_uid(user)),
*cmd,
]
return cmd
owner = user or _process_owner()
if owner is None:
return cmd
return ["env", *desktop_env_args(owner, euid), *cmd]

View File

@ -9,7 +9,9 @@ from __future__ import annotations
import logging
from steam_backlog_enforcer._steam_launch import _resolve_desktop_user
from steam_backlog_enforcer._desktop_env import (
resolve_desktop_user as _resolve_desktop_user,
)
from steam_backlog_enforcer._steam_process import _run_as_user
logger = logging.getLogger(__name__)

View File

@ -24,6 +24,10 @@ from steam_backlog_enforcer._desktop_env import (
desktop_runtime_dir,
desktop_session_ready,
desktop_uid,
x_display_error,
)
from steam_backlog_enforcer._desktop_env import (
resolve_desktop_user as _resolve_desktop_user,
)
from steam_backlog_enforcer._steam_errors import (
DesktopSessionNotReadyError,
@ -78,11 +82,21 @@ def _steam_has_debug_port() -> bool:
return _get_shared_js_ws_url() is not None
def _wait_for_cdp_ready() -> bool:
"""Wait up to *_STEAM_STARTUP_WAIT* seconds for CDP to become ready."""
def _wait_for_cdp_ready(launched: subprocess.Popen[bytes] | None = None) -> bool:
"""Wait up to *_STEAM_STARTUP_WAIT* seconds for CDP to become ready.
Raises:
SteamUnavailableError: *launched* exited and no Steam is left to open
the port. A live client keeps the wait going: ``steam`` may fork
the real client and exit.
"""
for _ in range(_STEAM_STARTUP_WAIT):
if _get_shared_js_ws_url() is not None:
return True
code = None if launched is None else launched.poll()
if code is not None and not _is_steam_running():
msg = f"Steam exited during startup (exit code {code})"
raise SteamUnavailableError(msg)
time.sleep(1)
return False
@ -109,21 +123,6 @@ def _wait_for_collections_ready() -> bool:
return False
def _resolve_desktop_user() -> str | None:
"""Resolve which desktop user owns the Steam/X11 session.
Prefers the explicit STEAM_ENFORCER_DESKTOP_USER (set by the systemd
unit, which has no SUDO_USER/USER of its own since it is started
directly by systemd rather than via `sudo`), then falls back to
SUDO_USER/USER for interactive `sudo` invocations.
"""
return (
os.environ.get("STEAM_ENFORCER_DESKTOP_USER")
or os.environ.get("SUDO_USER")
or os.environ.get("USER")
)
def _shutdown_steam() -> None:
"""Send ``steam -shutdown`` and wait for the process to exit."""
real_user = _resolve_desktop_user()
@ -144,10 +143,10 @@ def _shutdown_steam() -> None:
time.sleep(1)
def _launch_steam_with_debug() -> None:
"""Launch Steam with CEF debugging enabled."""
def _launch_steam_with_debug() -> subprocess.Popen[bytes] | None:
"""Launch Steam with CEF debugging enabled; return the process if started."""
real_user = _resolve_desktop_user()
_run_as_user(
return _run_as_user(
[
"steam",
"-cef-enable-debugging",
@ -193,14 +192,18 @@ def ensure_steam_debug_port() -> None:
logger.info(msg)
raise DesktopSessionNotReadyError(msg)
# Before the shutdown: never close Steam only to find nowhere to restart it.
if (no_display := x_display_error()) is not None:
raise SteamUnavailableError(no_display)
logger.info("Steam CDP port not available — (re)starting Steam...")
if _is_steam_running():
assert_safe_to_restart()
_shutdown_steam()
_launch_steam_with_debug()
launched = _launch_steam_with_debug()
if not _wait_for_cdp_ready():
if not _wait_for_cdp_ready(launched):
msg = "Timed out waiting for Steam CDP port to become ready"
raise SteamUnavailableError(msg)
logger.info("Steam CDP port ready.")

View File

@ -53,13 +53,17 @@ def _reap_spawned() -> None:
_SPAWNED[:] = [proc for proc in _SPAWNED if proc.poll() is None]
def _run_as_user(cmd: list[str], user: str | None) -> None:
def _run_as_user(cmd: list[str], user: str | None) -> subprocess.Popen[bytes] | None:
"""Run a command, dropping to *user* if currently root.
Refuses to run at all when root and no desktop user resolves: the command
would otherwise execute *as root* on the user's session, which is how the
enforcer put a root Steam ("Cannot run as root user") on screen.
Failing closed costs one skipped pass; failing open costs a modal.
Returns:
The started process, so a caller that waits on it can notice it died;
``None`` when the launch was refused.
"""
_reap_spawned()
if os.geteuid() == 0 and (not user or user == "root"):
@ -68,7 +72,7 @@ def _run_as_user(cmd: list[str], user: str | None) -> None:
"(is STEAM_ENFORCER_DESKTOP_USER set?)",
cmd[0] if cmd else "<empty>",
)
return
full_cmd = desktop_user_cmd(cmd, user)
_SPAWNED.append(spawn_detached(full_cmd))
return None
proc = spawn_detached(desktop_user_cmd(cmd, user))
_SPAWNED.append(proc)
return proc

View File

@ -0,0 +1,30 @@
"""Autouse: the host's X display never decides a Steam-launch test.
``ensure_steam_debug_port`` refuses to launch when the X socket for ``DISPLAY``
(default ``:0``) is missing. That is a fact about the machine - a headless CI
box has none - so every test that reaches a launch would pass or fail by host.
Pinned "up" here; ``test_desktop_display`` tests the check itself and
``test_steam_launch_failfast`` patches it down for the refusal cases.
Split out of ``conftest.py`` like ``_no_systemd_run``; ``conftest`` imports the
fixture by name to register it.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
from unittest.mock import patch
import pytest
if TYPE_CHECKING:
from collections.abc import Iterator
@pytest.fixture(autouse=True)
def _x_display_up() -> Iterator[None]:
"""Report the X display as up to ``_steam_launch`` for one test."""
with patch(
"steam_backlog_enforcer._steam_launch.x_display_error", return_value=None
):
yield

View File

@ -42,6 +42,7 @@ from steam_backlog_enforcer.tests._no_subprocess import _block_real_subprocesses
from steam_backlog_enforcer.tests._no_systemd_run import _no_systemd_run
from steam_backlog_enforcer.tests._no_workout_http import _no_workout_http
from steam_backlog_enforcer.tests._research_fixtures import tm
from steam_backlog_enforcer.tests._x_display_up import _x_display_up
# Re-exported so ruff --fix does not delete the imports above: pytest
# registers autouse fixtures by name, so they look unused to the linter.
@ -63,6 +64,7 @@ __all__ = [
"_no_real_effects",
"_no_systemd_run",
"_no_workout_http",
"_x_display_up",
"tm",
]

View File

@ -0,0 +1,109 @@
"""Tests for the X display Steam is launched on, and the env it gets.
A web job (a user unit with no DISPLAY) used to run a bare ``steam`` that died
with "Unable to open X11 display". Every launch now carries the desktop env,
root or not, and no launch is attempted when the display is not up.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
from unittest.mock import MagicMock, patch
import pytest
from steam_backlog_enforcer import _desktop_env
from steam_backlog_enforcer._desktop_env import desktop_user_cmd, x_display_error
from steam_backlog_enforcer.tests._desktop_launch_patches import (
DESKTOP_ENV_PKG,
env_value,
)
if TYPE_CHECKING:
from pathlib import Path
@pytest.fixture(name="x_dir")
def _x_socket_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
"""An empty X socket dir, with DISPLAY unset."""
monkeypatch.setattr(_desktop_env, "X_SOCKET_DIR", str(tmp_path))
monkeypatch.delenv("DISPLAY", raising=False)
return tmp_path
class TestXDisplayError:
"""x_display_error: why Steam has no display to open, or None."""
def test_default_display_is_up(self, x_dir: Path) -> None:
"""Unset DISPLAY falls back to :0, whose socket exists."""
(x_dir / "X0").touch()
assert x_display_error() is None
def test_default_display_missing_names_it(self, x_dir: Path) -> None:
"""No socket for the default :0: the error names the display."""
message = x_display_error()
assert message is not None
assert ":0" in message
assert str(x_dir / "X0") in message
def test_explicit_display_with_screen_suffix(
self, x_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""DISPLAY=:1.0 checks the X1 socket and is named in the error."""
monkeypatch.setenv("DISPLAY", ":1.0")
message = x_display_error()
assert message is not None
assert ":1.0" in message
(x_dir / "X1").touch()
assert x_display_error() is None
def test_remote_display_is_not_checked(
self, x_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A host-qualified display has no local socket to look for."""
monkeypatch.setenv("DISPLAY", "localhost:10.0")
assert x_dir.is_dir()
assert x_display_error() is None
class TestNonRootGetsTheDesktopEnv:
"""desktop_user_cmd prefixes the session env even without sudo."""
def _cmd(self, user: str | None = "kuhy") -> list[str]:
owner = MagicMock(pw_name="kuhy")
with (
patch(f"{DESKTOP_ENV_PKG}.os.geteuid", return_value=1234),
patch(f"{DESKTOP_ENV_PKG}.pwd.getpwuid", return_value=owner),
):
return desktop_user_cmd(["steam", "-silent"], user)
def test_adds_env_without_sudo(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""The command runs under ``env`` with DISPLAY and the runtime dir."""
monkeypatch.delenv("DISPLAY", raising=False)
cmd = self._cmd()
assert cmd[0] == "env"
assert "sudo" not in cmd
assert cmd[-2:] == ["steam", "-silent"]
assert env_value(cmd, "DISPLAY") == ":0"
assert env_value(cmd, "XDG_RUNTIME_DIR") == "/run/user/1234"
def test_keeps_an_inherited_display(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""An explicit DISPLAY in the job's environment still wins."""
monkeypatch.setenv("DISPLAY", ":7")
assert env_value(self._cmd(), "DISPLAY") == ":7"
def test_nobody_to_name_leaves_the_command_alone(self) -> None:
"""No desktop user and no passwd entry for the process: no env prefix."""
with (
patch(f"{DESKTOP_ENV_PKG}.os.geteuid", return_value=1234),
patch(f"{DESKTOP_ENV_PKG}.pwd.getpwuid", side_effect=KeyError),
):
assert desktop_user_cmd(["steam"], None) == ["steam"]
def test_unresolved_user_is_the_process_owner(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""With no desktop user named, the job's own user is the desktop user."""
monkeypatch.delenv("XAUTHORITY", raising=False)
cmd = self._cmd(user=None)
assert env_value(cmd, "XAUTHORITY") == "/home/kuhy/.Xauthority"

View File

@ -70,10 +70,18 @@ class TestResolveDesktopUser:
class TestDesktopUserCmd:
"""Tests for desktop_user_cmd — all four branches."""
def test_non_root_returns_cmd_unchanged(self) -> None:
"""A non-root caller runs the command as is."""
def test_non_root_gets_the_env_without_sudo(self) -> None:
"""A non-root caller runs the command under the session env, no sudo.
The web server is a user unit with no DISPLAY; a bare ``steam`` from
a job died with "Unable to open X11 display".
"""
with patch(f"{ENV_PKG}.os.geteuid", return_value=1000):
assert desktop_user_cmd(["steam"], "kuhy") == ["steam"]
result = desktop_user_cmd(["steam"], "kuhy")
assert result[0] == "env"
assert result[-1] == "steam"
assert "sudo" not in result
assert _env_value(result, "XDG_RUNTIME_DIR") == "/run/user/1000"
def test_root_with_user_wraps_in_sudo(self) -> None:
"""Root with a desktop user wraps the command in sudo with the user env."""

View File

@ -141,7 +141,7 @@ class TestRunAsUser:
_SPAWNED.clear()
def test_non_root_runs_directly(self) -> None:
"""A non-root caller runs the command unchanged."""
"""A non-root caller runs the command itself, under the session env."""
with (
patch(f"{STEAM_PROCESS_PKG}.os.geteuid", return_value=1000),
patch(f"{STEAM_PROCESS_PKG}.subprocess.Popen") as mock_popen,
@ -149,7 +149,9 @@ class TestRunAsUser:
_run_as_user(["steam", "-shutdown"], "alice")
mock_popen.assert_called_once()
cmd = mock_popen.call_args[0][0]
assert cmd == ["steam", "-shutdown"]
assert cmd[0] == "env"
assert cmd[-2:] == ["steam", "-shutdown"]
assert "sudo" not in cmd
def test_root_drops_to_user(self) -> None:
"""Root launches through sudo -u as the desktop user."""

View File

@ -0,0 +1,147 @@
"""Tests for failing fast when a launched Steam cannot come up.
A web job once launched Steam with no DISPLAY: the client logged "Unable to
open X11 display" and exited after ~2 s, yet the CDP wait still polled all 45 s
while the job held the global mutating lock. These pin the fast failures: the
launched process died, or there is no X display to launch it on.
"""
from __future__ import annotations
from unittest.mock import MagicMock, patch
import pytest
from steam_backlog_enforcer._steam_errors import SteamUnavailableError
from steam_backlog_enforcer._steam_launch import (
_launch_steam_with_debug,
_wait_for_cdp_ready,
ensure_steam_debug_port,
)
from steam_backlog_enforcer._steam_process import _run_as_user
from steam_backlog_enforcer.tests._desktop_launch_patches import (
STEAM_LAUNCH_PKG,
STEAM_PROCESS_PKG,
launch_patches,
)
NO_DISPLAY = "No X display for Steam: :0 is not up"
def _proc(exit_code: int | None) -> MagicMock:
"""A launched process whose ``poll()`` reports *exit_code* (None = alive)."""
proc = MagicMock()
proc.poll.return_value = exit_code
return proc
class TestWaitForCdpReadyWatchesTheLaunch:
"""_wait_for_cdp_ready gives up as soon as the launched Steam is gone."""
def test_dead_launch_fails_on_the_first_poll(self) -> None:
"""A process that exited with no Steam left stops the wait at once."""
with (
patch(f"{STEAM_LAUNCH_PKG}._get_shared_js_ws_url", return_value=None),
patch(f"{STEAM_LAUNCH_PKG}._is_steam_running", return_value=False),
patch(f"{STEAM_LAUNCH_PKG}.time.sleep") as sleep,
pytest.raises(
SteamUnavailableError,
match=r"Steam exited during startup \(exit code 1\)",
),
):
_wait_for_cdp_ready(_proc(1))
assert sleep.call_count <= 1
def test_exited_launcher_with_a_live_client_keeps_waiting(self) -> None:
"""A launcher that handed off to a running client is not a failure.
``steam`` may fork the real client and exit; the port then opens a
few seconds later, so exit alone must not abort the wait.
"""
with (
patch(
f"{STEAM_LAUNCH_PKG}._get_shared_js_ws_url",
side_effect=[None, None, "ws://steam"],
),
patch(f"{STEAM_LAUNCH_PKG}._is_steam_running", return_value=True),
patch(f"{STEAM_LAUNCH_PKG}.time.sleep") as sleep,
):
assert _wait_for_cdp_ready(_proc(0)) is True
assert sleep.call_count == 2
def test_alive_launch_times_out_as_before(self) -> None:
"""A process that keeps running but never opens the port times out."""
with (
patch(f"{STEAM_LAUNCH_PKG}._get_shared_js_ws_url", return_value=None),
patch(f"{STEAM_LAUNCH_PKG}._STEAM_STARTUP_WAIT", 3),
patch(f"{STEAM_LAUNCH_PKG}.time.sleep") as sleep,
):
assert _wait_for_cdp_ready(_proc(None)) is False
assert sleep.call_count == 3
class TestEnsureFailsFast:
"""ensure_steam_debug_port stops early for a dead launch or no display."""
def test_dead_launch_raises_without_waiting_for_collections(self) -> None:
"""The whole call fails within a poll or two, naming the exit code."""
with (
launch_patches(
"_wait_for_collections_ready",
_launch_steam_with_debug=_proc(1),
_steam_has_debug_port=False,
_get_shared_js_ws_url=None,
_is_steam_running=False,
steam_is_installed=True,
x_display_error=None,
) as mocks,
patch(f"{STEAM_LAUNCH_PKG}.time.sleep") as sleep,
pytest.raises(SteamUnavailableError, match=r"exited during startup"),
):
ensure_steam_debug_port()
assert sleep.call_count <= 1
mocks["_wait_for_collections_ready"].assert_not_called()
def test_no_display_refuses_before_any_shutdown_or_launch(self) -> None:
"""No X display: Steam is neither shut down nor started."""
with (
launch_patches(
"_launch_steam_with_debug",
"_shutdown_steam",
_steam_has_debug_port=False,
_is_steam_running=True,
steam_is_installed=True,
x_display_error=NO_DISPLAY,
) as mocks,
pytest.raises(SteamUnavailableError, match="No X display"),
):
ensure_steam_debug_port()
mocks["_launch_steam_with_debug"].assert_not_called()
mocks["_shutdown_steam"].assert_not_called()
class TestLaunchHandsBackTheProcess:
"""The launched process reaches the wait instead of being discarded."""
def test_launch_returns_the_spawned_handle(self) -> None:
"""_launch_steam_with_debug returns what _run_as_user spawned."""
spawned = _proc(None)
with patch(f"{STEAM_LAUNCH_PKG}._run_as_user", return_value=spawned):
assert _launch_steam_with_debug() is spawned
def test_run_as_user_returns_the_popen(self) -> None:
"""_run_as_user hands back the Popen it started."""
with (
patch(f"{STEAM_PROCESS_PKG}.os.geteuid", return_value=1000),
patch(f"{STEAM_PROCESS_PKG}.subprocess.Popen") as popen,
):
assert _run_as_user(["steam"], "bob") is popen.return_value
def test_run_as_user_refusal_returns_none(self) -> None:
"""Root with no desktop user starts nothing and returns None."""
with (
patch(f"{STEAM_PROCESS_PKG}.os.geteuid", return_value=0),
patch(f"{STEAM_PROCESS_PKG}.subprocess.Popen") as popen,
):
assert _run_as_user(["steam"], None) is None
popen.assert_not_called()