fix(stream): expire stream tokens and order init before the services it patches

Two faults found by reading the live container, not the source.

The s6 oneshot that patches nginx and selkies had no ordering edge to
anything that consumes its work. On the running host selkies and nginx
started at 06:35:13 and init.sh finished writing at 06:35:21, so every
patch landed on disk with no effect on the processes already up: the
stream gate was absent from the live nginx (zero /verify hits, an
unauthenticated GET / answering 200) and both selkies fixes were inert,
which is why the gamepad INFO spam and the climbing EVDEV client count
survived a patch that reported success. init-services now depends on
init-pcsx2-config. The slow networked work moves to a new
init-pcsx2-deps that only svc-broker waits for, so apt and the
patches.zip download cannot delay the stream stack.

Stream tokens now carry an idle TTL, refreshed on every admitted
request, so an abandoned session stops holding the gate open. A re-issue
demotes the previous token instead of dropping it, keeping it valid for
a grace window: relaunching into an open tab meant the browser was still
replaying the old stream_sid while RomM navigated to the new URL, and
every one of those requests 403'd, which the client reports as a dropped
connection and retries in a loop. A query token that outranks a stale
cookie now re-cookies the browser so the tab moves across before the
window closes.

The gate's 403s now name their reason, which reaches stdout through the
existing error choke point, and /status reports the token only while it
is still live rather than handing back a dead one.

Author: LoneAngelFayt

README.md

@@ -122,6 +122,8 @@ Save states don't care about any of this. The requirement is only for memory-car
 | `PCSX2_LOG_PATH` | `/config/pcsx2-qt.log` | Captures pcsx2-qt stdout and stderr. Renderer and Vulkan failures show up here. Appended across launches. |
 | `BROKER_LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`. The xdotool window-found messages are DEBUG. |
 | `PUID` / `PGID` | `1000` | Standard LinuxServer UID/GID. Also used to chown files the broker writes for PCSX2, which runs as `abc` and has to overwrite them later. |
+| `STREAM_TOKEN_TTL` | `43200.0` | Idle seconds before a stream token stops working. Every admitted request slides it forward, so it only fires on a session nobody is watching. Stops an abandoned session leaving the stream gate open forever. |
+| `STREAM_TOKEN_GRACE` | `120.0` | How long the previous token keeps working after a relaunch mints a new one, so an already-open tab is not cut off mid-navigation. |
 
 ## API
 
@@ -226,6 +228,8 @@ It is refused while a game is running or a launch is in flight, because PCSX2 ho
 
 **RomM shows no play button.** Confirm `streaming.enabled: true`, confirm the platform slug matches, restart RomM after config changes, and check what RomM thinks it has: `curl http://romm:5000/api/streaming/config`.
 
+**"An error occurred, restarting stream", over and over.** The stream client says this whenever its WebSocket drops, so the useful signal is on the broker side: `docker logs pcsx2 | grep "/verify"`. A `403` there names the reason (`no stream token in the request`, `stream token expired`, `stream token superseded by a newer launch`), and the token is redacted so the line is safe to share. No `/verify` lines *at all* means the gate is not running: either the mod's init never patched nginx (`docker logs pcsx2 | grep broker-mod`), or your reverse proxy is reaching the ungated plain-HTTP vhost on port 3000 instead of the SSL vhost on 3001. Point it at 3001 and do not publish 3000: the gate is the only thing standing between the ROM library and anyone who finds the address.
+
 ## Development
 
 The broker is one stdlib Python file with a stdlib `unittest` suite. Nothing to install, which is the point: the container has no pip, so the broker cannot grow a dependency without breaking the image.
@@ -238,6 +242,8 @@ CI runs the same tests under pytest, plus `ruff check .` against the shared [ruf
 
 The suite covers what can be tested without a running emulator: save-file and memory-card archive handling (round trips, the last-write-wins mtime guard, path-traversal and subtree rejection, File-card refusal), `PCSX2.ini` patching, ROM path resolution, and the session state machine (crash-loop limiter, launch and card-op claims, deferred `load_slot` generation checks). Anything needing a real X display, PINE socket, or pcsx2-qt process is out of scope on purpose, because it is only provable on a live container.
 
+**Init ordering matters more than it looks.** The mod ships two s6 oneshots. `init-pcsx2-config` rewrites files that base-image services read exactly once at startup (selkies' `input_handler.py`, the nginx site config, labwc's autostart), so `init-services` is made to depend on it and the whole service stack waits. Drop that edge and the patches still land on disk while changing nothing about the processes already running, which fails silently: the log says "Applied nginx stream gate" and the live nginx has no gate. Keep that script fast and offline. `init-pcsx2-deps` holds the slow networked work (apt, `patches.zip`) and only `svc-broker` waits for it, so a GitHub timeout cannot stall the stream.
+
 Commits follow [Conventional Commits](https://www.conventionalcommits.org/) and releases are cut automatically on merge to `main`: `fix:` bumps the patch, `feat:` the minor, `feat!:` the major.
 
 ## Pinning a version

root/etc/s6-overlay/s6-rc.d/init-pcsx2-config/init.sh

@@ -1,5 +1,16 @@
 #!/usr/bin/with-contenv bash
 
+# Every patch below rewrites a file that a base-image service reads once, at
+# import or config-load time: selkies' input_handler.py, nginx's site config,
+# labwc's autostart. So init-services depends on this oneshot (see
+# init-services/dependencies.d/init-pcsx2-config), which puts the whole service
+# stack behind it. Without that edge s6 starts the services in parallel with
+# this script, they win the race by several seconds, and every patch here lands
+# on disk having no effect at all on the processes already running: the stream
+# gate is absent from the live nginx and the selkies fixes never load.
+# Keep this script fast and offline. Slow or networked work belongs in
+# init-pcsx2-deps, which only the broker waits for.
+
 # Clean up stale Wayland and X11 sockets to ensure the compositor starts on the
 # default display indices (wayland-0, :0) even if the container was killed
 # forcefully. Persistence of these lock files on the host-mapped /config
@@ -17,47 +28,6 @@ else
     echo "[broker-mod] Cleaned up stale display sockets."
 fi
 
-# Ensure python3 is available for the broker service, and libshaderc for
-# PCSX2's Vulkan renderer. The base image ships without it, so on a host
-# with a GPU the GS device fails shader compilation and pcsx2-qt exits
-# within a second of booting any game (the gameless dashboard never
-# initializes GS, masking the breakage until a game is launched).
-_pkgs=()
-command -v python3 &>/dev/null || _pkgs+=(python3)
-ldconfig -p | grep -q libshaderc.so.1 || _pkgs+=(libshaderc1)
-if [ ${#_pkgs[@]} -gt 0 ]; then
-    echo "[broker-mod] Installing: ${_pkgs[*]}"
-    apt-get update -qq && apt-get install -y -qq "${_pkgs[@]}" \
-        || echo "[broker-mod] ERROR: failed to install ${_pkgs[*]}"
-fi
-
-# Ubuntu's +dfsg PCSX2 package strips patches.zip from the resources dir,
-# so every game boot warns "Built-in game patches are not available" and
-# titles that rely on compatibility patches misbehave. Fetch the official
-# archive from the PCSX2 project. Non-fatal if offline: games still run.
-PATCHES_ZIP="/usr/share/PCSX2/resources/patches.zip"
-if [ ! -s "$PATCHES_ZIP" ]; then
-    echo "[broker-mod] Downloading PCSX2 patches.zip..."
-    # Download to a temp path and verify it is a well-formed zip before
-    # installing: the release URL floats ("latest"), so a checksum can't be
-    # pinned, but a truncated or non-zip response must never land in place.
-    # Bounded so an unresponsive GitHub can't stall container init for an
-    # optional file.
-    if curl -fsSL --connect-timeout 10 --max-time 60 -o "$PATCHES_ZIP.tmp" \
-        "https://github.com/PCSX2/pcsx2_patches/releases/latest/download/patches.zip" \
-        && python3 -c 'import sys, zipfile
-with zipfile.ZipFile(sys.argv[1]) as z:
-    sys.exit(1 if z.testzip() is not None or not z.namelist() else 0)' \
-            "$PATCHES_ZIP.tmp" 2>/dev/null; then
-        chmod 644 "$PATCHES_ZIP.tmp"
-        mv "$PATCHES_ZIP.tmp" "$PATCHES_ZIP"
-        echo "[broker-mod] patches.zip installed."
-    else
-        rm -f "$PATCHES_ZIP.tmp"
-        echo "[broker-mod] WARNING: patches.zip download failed or corrupt; built-in game patches unavailable."
-    fi
-fi
-
 # Lock down the sudoers rule so sudo accepts it (requires mode 0440).
 chmod 0440 /etc/sudoers.d/broker
 echo "[broker-mod] sudoers rule set."

root/etc/s6-overlay/s6-rc.d/init-pcsx2-deps/dependencies.d/init-config-end

@@ -0,0 +1,47 @@
+#!/usr/bin/with-contenv bash
+
+# Package and asset fetching, split out of init-pcsx2-config because it is slow
+# and networked. init-pcsx2-config gates the whole service stack (nginx, xorg,
+# selkies all wait on it), so anything that can spend a minute on apt-get or a
+# GitHub download has to live somewhere that only the broker waits for.
+
+# Ensure python3 is available for the broker service, and libshaderc for
+# PCSX2's Vulkan renderer. The base image ships without it, so on a host
+# with a GPU the GS device fails shader compilation and pcsx2-qt exits
+# within a second of booting any game (the gameless dashboard never
+# initializes GS, masking the breakage until a game is launched).
+_pkgs=()
+command -v python3 &>/dev/null || _pkgs+=(python3)
+ldconfig -p | grep -q libshaderc.so.1 || _pkgs+=(libshaderc1)
+if [ ${#_pkgs[@]} -gt 0 ]; then
+    echo "[broker-mod] Installing: ${_pkgs[*]}"
+    apt-get update -qq && apt-get install -y -qq "${_pkgs[@]}" \
+        || echo "[broker-mod] ERROR: failed to install ${_pkgs[*]}"
+fi
+
+# Ubuntu's +dfsg PCSX2 package strips patches.zip from the resources dir,
+# so every game boot warns "Built-in game patches are not available" and
+# titles that rely on compatibility patches misbehave. Fetch the official
+# archive from the PCSX2 project. Non-fatal if offline: games still run.
+PATCHES_ZIP="/usr/share/PCSX2/resources/patches.zip"
+if [ ! -s "$PATCHES_ZIP" ]; then
+    echo "[broker-mod] Downloading PCSX2 patches.zip..."
+    # Download to a temp path and verify it is a well-formed zip before
+    # installing: the release URL floats ("latest"), so a checksum can't be
+    # pinned, but a truncated or non-zip response must never land in place.
+    # Bounded so an unresponsive GitHub can't stall container init for an
+    # optional file.
+    if curl -fsSL --connect-timeout 10 --max-time 60 -o "$PATCHES_ZIP.tmp" \
+        "https://github.com/PCSX2/pcsx2_patches/releases/latest/download/patches.zip" \
+        && python3 -c 'import sys, zipfile
+with zipfile.ZipFile(sys.argv[1]) as z:
+    sys.exit(1 if z.testzip() is not None or not z.namelist() else 0)' \
+            "$PATCHES_ZIP.tmp" 2>/dev/null; then
+        chmod 644 "$PATCHES_ZIP.tmp"
+        mv "$PATCHES_ZIP.tmp" "$PATCHES_ZIP"
+        echo "[broker-mod] patches.zip installed."
+    else
+        rm -f "$PATCHES_ZIP.tmp"
+        echo "[broker-mod] WARNING: patches.zip download failed or corrupt; built-in game patches unavailable."
+    fi
+fi

root/etc/s6-overlay/s6-rc.d/init-pcsx2-deps/init.sh

@@ -0,0 +1 @@
+oneshot

root/etc/s6-overlay/s6-rc.d/init-pcsx2-deps/type

@@ -0,0 +1 @@
+/etc/s6-overlay/s6-rc.d/init-pcsx2-deps/init.sh

root/etc/s6-overlay/s6-rc.d/init-pcsx2-deps/up

@@ -167,6 +167,19 @@ def _gpu_env() -> dict[str, str]:
 RESUME_LOAD_WAIT   = float(os.environ.get("RESUME_LOAD_WAIT",   "90.0"))
 RESUME_LOAD_SETTLE = float(os.environ.get("RESUME_LOAD_SETTLE", "3.0"))
 
+# Stream token lifetime. The TTL is idle time, not absolute: every admitted
+# request slides it forward, so it only fires on a session nobody is watching.
+# Without it a token minted by /launch stays valid until an explicit release,
+# and a container that loses its RomM side (crash, network partition, a user
+# who just closes the tab) leaves the gate open indefinitely.
+STREAM_TOKEN_TTL   = float(os.environ.get("STREAM_TOKEN_TTL",   "43200.0"))
+# How long the superseded token keeps working after a re-issue. Relaunching
+# into an already-open tab means the browser is still replaying the old
+# stream_sid cookie while RomM navigates the iframe to the new URL; without
+# this window every one of those in-flight requests 403s and the stream client
+# reports a dropped connection and retries in a loop.
+STREAM_TOKEN_GRACE = float(os.environ.get("STREAM_TOKEN_GRACE", "120.0"))
+
 logging.basicConfig(
     level=getattr(logging, os.environ.get("BROKER_LOG_LEVEL", "INFO").upper(), logging.INFO),
     format="%(asctime)s [broker] %(levelname)s %(message)s",
@@ -231,35 +244,86 @@ def _gpu_env() -> dict[str, str]:
     # survives game exit so RomM can still pull after the session ends.
     "save_baseline":    None,
     # Random per-session token gating the stream proxy on port 3001. Minted on
-    # /launch, swapped for a cookie by the browser, cleared on release.
-    "stream_token":     None,
+    # /launch, swapped for a cookie by the browser, cleared on release. The
+    # expiry is a monotonic deadline refreshed on every admitted request; the
+    # prev_* pair holds the token a re-issue replaced, valid for a short grace
+    # window so an already-open tab is not cut off mid-relaunch.
+    "stream_token":         None,
+    "stream_expires":       0.0,
+    "stream_prev_token":    None,
+    "stream_prev_expires":  0.0,
 }
 
 # ── Helpers ───────────────────────────────────────────────────────────────────
 
 def _issue_stream_token() -> str:
-    """Mint a fresh stream token and bind it to the current session."""
+    """Mint a fresh stream token and bind it to the current session.
+
+    The token being replaced is demoted rather than dropped: it stays usable
+    for STREAM_TOKEN_GRACE seconds so requests already in flight from an open
+    tab still land. See STREAM_TOKEN_GRACE for why that matters.
+    """
     token = secrets.token_urlsafe(32)
+    now = time.monotonic()
     with _session_lock:
+        previous = _session["stream_token"]
+        if previous:
+            _session["stream_prev_token"] = previous
+            _session["stream_prev_expires"] = now + STREAM_TOKEN_GRACE
         _session["stream_token"] = token
+        _session["stream_expires"] = now + STREAM_TOKEN_TTL
     return token
 
 
-def _check_stream_token(token: str) -> bool:
-    """Constant-time check of token against the live session token."""
+def _check_stream_token(token: str) -> str | None:
+    """Judge token against the live session token, then the superseded one.
+
+    Returns None when the token is good, otherwise a short reason for the log.
+    A hit on the live token slides its expiry forward: the TTL exists to close
+    an abandoned session, not to interrupt someone who is still playing.
+    """
     if not token:
-        return False
+        return "no stream token in the request"
+    now = time.monotonic()
     with _session_lock:
         current = _session["stream_token"]
-    if not current:
-        return False
-    return hmac.compare_digest(token, current)
+        if not current:
+            return "no stream session is open"
+        if hmac.compare_digest(token, current):
+            if now >= _session["stream_expires"]:
+                return "stream token expired after %.0fs idle" % STREAM_TOKEN_TTL
+            _session["stream_expires"] = now + STREAM_TOKEN_TTL
+            return None
+        previous = _session["stream_prev_token"]
+        if previous and hmac.compare_digest(token, previous):
+            if now < _session["stream_prev_expires"]:
+                return None
+            _session["stream_prev_token"] = None
+            _session["stream_prev_expires"] = 0.0
+            return "stream token superseded by a newer launch"
+    return "stream token does not match the open session"
 
 
 def _clear_stream_token() -> None:
     """Drop the stream token so the gate rejects everything until next launch."""
     with _session_lock:
         _session["stream_token"] = None
+        _session["stream_expires"] = 0.0
+        _session["stream_prev_token"] = None
+        _session["stream_prev_expires"] = 0.0
+
+
+def _live_stream_token() -> str | None:
+    """The session token if it is still inside its TTL, else None.
+
+    /status hands this to RomM so a reconnecting client can re-attach without
+    a relaunch. An expired token would only send it into the 403 loop the TTL
+    is there to end, so it is reported as absent.
+    """
+    with _session_lock:
+        if _session["stream_token"] and time.monotonic() < _session["stream_expires"]:
+            return _session["stream_token"]
+    return None
 
 
 def _extract_stream_token(query: str, cookie_header: str | None) -> str | None:
@@ -287,22 +351,28 @@ def _stream_cookie_value(token: str) -> str:
 
 def _verify_stream_decision(
     original_uri: str, cookie_header: str | None
-) -> tuple[int, str | None]:
+) -> tuple[int, str | None, str | None]:
     """Decide an nginx auth_request subrequest for the stream gate.
 
-    Returns (status, set_cookie). 200 admits the request, 403 rejects it.
+    Returns (status, set_cookie, reason). 200 admits the request, 403 rejects
+    it and carries the reason so the refusal is legible in the container log.
     When the token arrives in the query (the first iframe load), the caller
     gets a Set-Cookie so later requests carry stream_sid and the token drops
     out of the URL. A cookie-authed request that is already good gets no
     Set-Cookie back, so nginx does not rewrite it.
     """
     query = urlparse(original_uri).query
     token = _extract_stream_token(query, cookie_header)
-    if not _check_stream_token(token or ""):
-        return 403, None
+    reason = _check_stream_token(token or "")
+    if reason:
+        return 403, None, reason
     if "stream_token" in parse_qs(query):
-        return 200, _stream_cookie_value(token)
-    return 200, None
+        # Re-cookie on the query bootstrap, and also when the query token is
+        # the current one but the cookie still holds the superseded token:
+        # the browser must be moved onto the new value before the grace
+        # window closes, or the tab drops out the moment it does.
+        return 200, _stream_cookie_value(token), None
+    return 200, None, None
 
 
 def _validate_rom_path(raw: str) -> Path | None:
@@ -1760,14 +1830,14 @@ def _verify_stream(self) -> None:
         # real request URI (carrying the stream_token query on first load) via
         # X-Original-URI and the browser Cookie header; the broker returns 200
         # to admit or 403 to reject, and a Set-Cookie on the query bootstrap.
-        status, set_cookie = _verify_stream_decision(
+        status, set_cookie, reason = _verify_stream_decision(
             self.headers.get("X-Original-URI", ""),
             self.headers.get("Cookie"),
         )
         headers = {"Set-Cookie": set_cookie} if set_cookie else None
         body = {"ok": status == 200}
         if status != 200:
-            body["error"] = "stream token missing, expired, or already claimed"
+            body["error"] = reason or "stream request rejected"
         self._send_json(status, body, headers)
 
     def _log_error_response(self, code: int, body: dict) -> None:
@@ -2156,7 +2226,7 @@ def _handle_GET(self):
                 # and nothing will restart it without an explicit POST /launch.
                 # Distinguishes a dead container from an idle dashboard.
                 "relaunch_abandoned": abandoned,
-                "stream_token": snap.get("stream_token") if active else None,
+                "stream_token": _live_stream_token() if active else None,
             })
         else:
             self._send_json(404, {"error": "not found"})