steam-backlog-enforcer/steam_backlog_enforcer/jobs/_specs.py
Krzysztof kuhy Rudnicki 9ed4725d45 Add cancel window to hiding jobs
done, check, pick, pick-manual and hide can be cancelled only while they
hide games in the Steam library: cancel_window events, a SIGTERM handler
during that phase that skips the hide, and the web UI shows the cancel
button while the window is open. Docs fixed (check is mutating).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWYNS1qAMRdgAtbr5Rq
2026-11-16 09:44:37 +01:00

81 lines
2.9 KiB
Python

"""How each job command behaves: lock, cancel and privilege flags.
Pure data, deliberately free of command imports. The web server imports
this (through the job store and the catalog) from inside
``steam_backlog_enforcer.main`` → ``misc`` → ``_web_server``; importing the
command modules from here would close that loop into a circular import.
The handlers live in :mod:`._registry`, which only the job subprocess loads.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import TYPE_CHECKING, Final
if TYPE_CHECKING:
from collections.abc import Mapping
@dataclass(frozen=True)
class JobFlags:
"""How one command runs as a job.
Attributes:
mutating: Takes the one-mutating-job lock.
cancellable: SIGTERM cancels it (only where stopping midway is safe).
privileged: Runs in the root daemon; never spawned as a job.
cancel_window: Cancellable only while the job reports an open
``cancel_window`` (hiding games in the Steam library); the work
before it cannot be stopped midway.
"""
mutating: bool = True
cancellable: bool = False
privileged: bool = False
cancel_window: bool = False
_PRIVILEGED = JobFlags(privileged=True)
JOB_FLAGS: Final[dict[str, JobFlags]] = {
# check is mutating: a new achievement releases the game and assigns
# the next one, exactly like done. Every command that hides games in the
# Steam library (try_hide_other_games, which may wait on a Steam launch)
# can be stopped only during that step. do_check never hides today, so
# check's window is inert until it gains one.
"check": JobFlags(cancel_window=True),
"scan": JobFlags(cancellable=True),
"done": JobFlags(cancel_window=True),
"pick": JobFlags(cancel_window=True),
"pick-manual": JobFlags(cancel_window=True),
"abandon-pick": JobFlags(),
"install": JobFlags(),
"uninstall": JobFlags(),
"hide": JobFlags(cancel_window=True),
"unhide": JobFlags(),
"add-exception": JobFlags(),
"reset": JobFlags(),
"restore-backup": JobFlags(),
"stats": JobFlags(mutating=False, cancellable=True),
"list": JobFlags(mutating=False, cancellable=True),
# Only the demo runs as a job (see is_privileged).
"enforce": JobFlags(cancellable=True),
"gaming-reset": _PRIVILEGED,
"gaming-unblock": _PRIVILEGED,
"block-gaming": _PRIVILEGED,
"unblock": _PRIVILEGED,
"buy-dlc": _PRIVILEGED,
}
def is_privileged(command: str, params: Mapping[str, object]) -> bool:
"""Whether *command* with *params* must go to the root daemon.
``enforce`` is both: its 60-second demo runs as a job, anything else is
the real enforcer, which only the daemon may (re)start.
"""
if command == "enforce":
return not params.get("demo")
flags = JOB_FLAGS.get(command)
return flags is not None and flags.privileged