steam-backlog-enforcer/DOCS-ctl-socket.md
Krzysztof kuhy Rudnicki 9ad424d777 Verify store unblock/re-block; file failures
Every store-window action now checks its result instead of trusting
the commands: unblock needs no live store hosts line, no iptables
chain and a reachable store (else "network down" when
steamcommunity.com is down too), with one repair pass. Re-block needs
every domain on a sinkhole and the store unreachable, and is not
retried. A failure fails the job, names the check, and files one todo
task (deduplicated by title) through the local todo MCP; re-block
reports reach the web server via the new store_reports op. Job log
times now show local time like the summary.

Todo: 85af719b

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:07:29 +01:00

111 lines
6.4 KiB
Markdown

# Control socket: implementation notes
How the root daemon's `ctl.sock` (contract: `DOCS-web-control-api.md`, "Control
socket") is built. Code: `steam_backlog_enforcer/_ctl_*.py`; client for the web
server: `_ctl_client.py` (results in `_ctl_types.py`, errors in `_ctl_protocol.py`).
## Trust
- Root (uid 0) is admitted besides the desktop user: root can already do all of
this directly, so refusing it protects nothing and it keeps recovery/tests on
one interface. Any other uid is closed unanswered (client: `DaemonUnreachableError`).
- A second `enforce` (manual run, `--demo`) never takes the socket from a live
daemon; `--demo` never serves.
- The daemon re-checks the CLI's locks with the same tables
(`_command_locks.py`): under a total block only `gaming_unblock` works; under
the manual-pick lock `store_unblock` and `block_gaming` are `locked`.
- Ops run on connection threads and take the enforce loop's `tick_lock`, so they
never interleave with a pass; the loop reloads state under that lock.
## Differences from the contract
- Daemon-only error codes: `op_failed` (the privileged action ran and failed, or
an unexpected exception) and `unsupported` (restart asked of a daemon systemd
does not supervise: the exit would be a stop). Not in `ApiErrorCode`; the web
server should map unknown daemon codes to a 502.
- The two-phase reply uses `pending_id` (the contract's `PendingAction.id`) and an
extra `lapse_after_seconds`; the server maps it.
- `block_gaming` is capped at 1..365 days and refused while a block is active.
- `gaming_reset_arm` while one is armed returns the existing pending action
(same `pending_id`, same `ready_at`): re-arming can neither shorten nor extend
the wait. Pending resets live in daemon memory, so a daemon restart drops them
(fail closed: arm again).
- Test-only: `SBE_CTL_TEST_COUNTDOWN_SECONDS` (1..299) in the unit's environment
shortens the countdown for VM runs. It cannot lengthen it; unset means 300 s.
## Gaming reset
`_gaming_reset.reset_today`, shared with the CLI: zeroes billed time and per-game
attribution, re-arms warnings, releases the mounts, keeps earned time
(`budget_seconds`; the old CLI path dropped it), and writes a `manual_adjustment`
record to `/var/log/steam-backlog-enforcer/budget.jsonl` (billed seconds and
per-game breakdown before). That record is the auditable trail; the per-day
history mirrors current billed time, so it shows the day as quiet.
## What a restart does and does not lose
`restart` sets a flag; the enforce loop finishes its pass, runs one more
accounting tick (billing the time since the last tick), leaves an exit-time
marker (`_ctl_gap.py`), and exits 0; `Restart=always` brings it back after
`RestartSec=5`. The new daemon spends the marker on its first tick, billing the
whole downtime. Everything else already lives on disk after every tick:
| State | Survives? | Why |
|---|---|---|
| Billed seconds, per-game attribution | yes | `playtime_state.json` saved every tick; the final tick bills up to the exit, the first tick of the new daemon bills the gap |
| Cutoff / kill-grace timing | yes | `blocked_at` is persisted; `_sustain_block` measures from it |
| Playtime mounts (the block itself) | yes | kernel mount table; `reconcile` is mountinfo-driven. `RuntimeDirectoryPreserve=yes` keeps the stub file |
| Fired warnings, budget high-water | yes | in `PlaytimeState` |
| Open store window | yes (blip) | deadline in `state.json`; startup re-blocks the store once, the first tick re-opens it |
| Total block | yes | lock file, guard-lib |
| Armed gaming reset | no | memory only: arm again (fails closed) |
| Audit-journal "last verdict", history throttle | no | cosmetic: one extra `verdict_change` line, one extra history write |
Why the gap is billed explicitly: the budget clamps each tick's delta to
`2 x ENFORCE_INTERVAL` = 6 s so a suspend cannot inflate it, which would forgive
the restart gap (`RestartSec` + interpreter start + startup pass, seconds to tens
of seconds) and make a restart repeatable free play. The marker is deleted
before use, expires after 300 s and only a requested restart writes one, so a
crash or a long outage still goes through the normal clamp. Downtime nothing
enforces: an unauthorised game started in the gap is killed on the first tick;
the budget cutoff and its mounts persist throughout.
Rate limit: 1 per 10 minutes, persisted in
`/var/lib/steam-backlog-enforcer/ctl_restart.json` (root, 0600) so restarting
the daemon does not reset it.
## Store checks
`store_unblock` checks its own result (`_store_verify.py`): no live store line
in `/etc/hosts` in either family (`0.0.0.0` and `::`), the iptables store chain
gone, and `https://store.steampowered.com/` answering. A failure gets one
repair pass (unblock again, which also flushes DNS), then the op fails as
`op_failed` with `data.report = {action, check, title, body}`; `check` is the
first failing check, or `network down` when steamcommunity.com is unreachable
too. The web server (or the CLI) files the report as a todo task.
The end-of-window re-block runs the reverse checks (every domain resolves only
to a sinkhole, the store does not answer) with no repair and no retry for that
deadline. A failure is queued in memory; `store_reports {}` hands the queue
back and clears it. The web server asks every 60 s and files each report.
## Research game
`research_game {"app_id": N}` and `research_game_revoke {}` (`_ctl_research_game.py`,
rules in `_research_game.py`). game-research (PlayStudy) writes its approval
file `~/.config/game-research/research_game.json` (`{app_id, added_at, flags}`)
and then calls `research_game`; the op refuses (`invalid_params`) unless the
file names the same app id, writes the root record
`/var/lib/steam-backlog-enforcer/research_game.json` and appends
`RESEARCH_GAME_ADDED app_id=N` to `exception_audit.log`. No phrase, no delay,
no time lock: it can only confirm what the file says, one game at a time.
The game is the research game while the file and the record agree. It is
never uninstalled (`uninstall_game` refuses it for every caller), never hidden,
exempt from the tampering check, and a total-block purge keeps
`~/.local/share/Steam`. The unauthorized-game kill spares it only while one of
the file's `flags` (game-research's `recording.pid` or `research_launch.pid`,
under the user's home, launch flag at most 20 min old) names a live
`game_research_desktop` process. Deleting the file revokes it at once;
`research_game_revoke` also drops the record and logs `RESEARCH_GAME_REVOKED`.