signal-bot/DOCS-reload.md
Krzysztof kuhy Rudnicki d13ae42590
Some checks are pending
CI / check (push) Waiting to run
CI / web (push) Waiting to run
A switchboard: any command off, off until, or on its own cooldown
One row per live command on a new Commands tab of the management page,
each with an on/off switch, an optional "off until" moment and a cooldown
that overrides the bot's default for that command alone. Every switch is
live: the bot keeps them in its own SQLite (command_settings, a permanent
table) and reads the row on every attempt, so nothing goes through
/_reload and nothing restarts.

A command that is off answers "BEEP BOOP !kot WYŁĄCZONE." (with "DO HH:MM"
for a timed switch) rather than going quiet, so nobody reports it broken;
the refusal is filed as refused_off, which the analytics count with the
other refusals, and it neither starts the cooldown nor counts as a use.

The bot grows GET /_commands and PUT /_commands/{name}; the management app
proxies them under /api/commands and passes the bot's 404/503 through
unwrapped. !cisza and !odcisz carry no cooldown and the page says so
instead of accepting a number the bot would ignore (test_wiring_ungated
keeps that set honest against the real table).

Proven end to end: scripts/e2e.sh now brackets a PUT with switch_off.yaml
and switch_on.yaml, the same actor refused and then served, with no reload
between them. Also bumps vitest and @vitest/coverage-v8 to 5.0.0 and
@types/react-dom to 19.2.7, which the freshness gate asked for.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-04 15:55:56 +02:00

3.3 KiB

Picking up a change without a restart

Two kinds of change reach the running bot, and they are handled differently.

Data: POST /_reload

Aliases, an album's people.json/tags.json, and the .env and album settings the management UI writes are data. The command table is built from that data by one function (signal_bot/wiring.py), and RegistryHolder can run it again: the new table is built whole, then swapped in with a single assignment. Nothing restarts, the websocket stays up, and no frame is lost or replayed.

scripts/reload.sh                 # rebuild the table, report how many commands are live
scripts/reload.sh '!nowaosoba'    # ...and then type that at the bot in testbot

The answer is what the bot is serving now:

status code meaning
reloaded 200 the new table is live; commands is its size
kept 409 the data no longer builds; the previous table is still answering, and reason says what was wrong
connecting 503 the bot has not reached Signal yet; there is no table to rebuild

A rejected reload is deliberate: the builder reads files people edit by hand and pages write mid-session, and the only safe answer to a file that does not load is the table that was already answering. Only bad data is survived (ConfigError, DuplicateTriggerError); a programming error still surfaces as a 500 and a traceback in the journal, because a bug is not a file.

Startup is the one time a bad table is fatal: there is nothing to fall back on, and Restart=always looping on a ConfigError is a clearer signal than a bot that answers nothing.

One thing the management UI writes needs neither: the per-command switches on its Commands tab (/_commands) live in the bot's own database and are read on every attempt, so they are live on the next message without a rebuild. They are also what a reload does not reset -- command_settings is a permanent table.

Code: scripts/reload.sh --code

A Python change needs the process replaced. The restart is about a second and lossless (signal-cli replays what arrived meanwhile), but it is a deploy step, so it is the flag rather than the default:

scripts/reload.sh --code '!pomoc'

restarts the unit, waits for /healthz to report ok again, prints the version it came back as, and -- with a command given -- types it in the test group so "restarted" means "answered". There is no hot-reload of Python on purpose: importlib.reload leaves every object the old module already created bound to the old classes, which is a bug that looks like a feature until the first isinstance check.

Proven where

scripts/e2e.sh brackets a scripts/reload.sh with the two scenarios in fake_signal/proofs/: !delta is unknown, a fifth person is tagged into the synthetic pack, the script runs, and the same process posts delta's photo. The route itself is covered in tests/test_app.py, the holder in tests/test_registry_holder.py, and the album case in tests/test_bot.py. The switches get the same bracket: switch_off.yaml and switch_on.yaml around a PUT /_commands/cat, with no reload in between.