support bot light: dry run with migration checks and rollback (#8147)

* support bot light: check config and database with --dry-run

* ci: test the light support bot

---------

Co-authored-by: sh-agents <350651734+sh-agents@users.noreply.github.com>
This commit is contained in:
sh-agentsandsh-agents authored and GitHub committed 2026-11-12 14:16:33 +00:00
1 parent a77bfdcec3
commit 158338e5d0
9 files changed
+466 -2

No files matched your search

+1
View File
@@ -43,6 +43,7 @@ on:
- "website/package.json"
- "packages/simplex-chat-mcp/**"
- "apps/simplex-support-bot/**"
- "apps/simplex-support-bot-light/**"
types: [opened, synchronize, reopened, ready_for_review]
workflow_dispatch:
inputs:
+36
View File
@@ -122,6 +122,42 @@ Startup reconciles what downtime missed: acceptances that arrived while the bot
was stopped, members who left the roster group, and business chats left without
their roster members.
## Dry run
`--dry-run` opens the database, reports the migrations and what the next start
would find, and exits. It does not start chat, so nothing is sent to the network.
```bash
uv run support-bot-light --config config.toml --dry-run
docker compose run --rm support-bot-light --dry-run
```
```
ok database opened, schema up to date
ok active user: 1:Support
ok roster group 10: Invite roster
```
With chat stopped, the core lists groups only as chat previews, so the roster
group is looked up by `roster.group_name`. A group renamed in a client is
reported with `?`: the bot finds it by its marker at startup.
Pending migrations and a database migrated by a newer build stop the checks:
```
FAIL database: pending 1 migration(s): 20261111_feeds; a real start would apply them, --allow-migrations applies them now
```
`--allow-migrations` applies pending migrations, and `--allow-down-migrations`
rolls back migrations that this build does not have, using the down migrations
the newer build stored in the database; the checks run after them. Both need
`--dry-run`. The core rolls back only when this build's migrations are a prefix
of the database's, and otherwise reports a migration state error and changes
nothing. Stop the bot first and copy the `./state` directory: rolling back
deletes the data of the removed migrations.
The exit code is 0 when no line is `FAIL`, 1 otherwise.
## Development
```bash
@@ -17,6 +17,7 @@ from simplex_chat.types import CEvt
from . import business, commands, handlers, health, setup
from .config import Config, ConfigError, load_config
from .context import BotContext
from .dry_run import dry_run
log = logging.getLogger("support_bot_light")
@@ -176,7 +177,24 @@ async def _serve(config: Config, bot: Bot) -> None:
def main() -> int:
parser = argparse.ArgumentParser(prog="support-bot-light")
parser.add_argument("--config", type=Path, default=Path("config.toml"))
parser.add_argument(
"--dry-run",
action="store_true",
help="check config, database and roster group, then exit without starting chat",
)
parser.add_argument(
"--allow-migrations",
action="store_true",
help="with --dry-run: apply pending migrations instead of reporting them",
)
parser.add_argument(
"--allow-down-migrations",
action="store_true",
help="with --dry-run: roll back migrations that this build does not have",
)
args = parser.parse_args()
if (args.allow_migrations or args.allow_down_migrations) and not args.dry_run:
parser.error("--allow-migrations and --allow-down-migrations require --dry-run")
if not logging.getLogger().handlers:
logging.basicConfig(
@@ -193,6 +211,10 @@ def main() -> int:
log.error("%s", e)
return 2
try:
if args.dry_run:
report = asyncio.run(dry_run(config, args.allow_migrations, args.allow_down_migrations))
print("\n".join(report.lines))
return 1 if report.failed else 0
asyncio.run(_run(config))
except ConfigError as e:
# Raised past load_config only by the health endpoint, which cannot know
@@ -0,0 +1,145 @@
"""Check the database, migrations and roster group that the next start would use, then exit."""
from __future__ import annotations
import json
from dataclasses import dataclass, field
from typing import Literal
from simplex_chat import ChatApi, MigrationConfirmation, SqliteDb
from simplex_chat.core import ChatInitError
from simplex_chat.types import T
from . import setup
from .config import Config
ProbeKind = Literal["current", "upgrade", "downgrade", "failed"]
# Chat previews are the group list the core serves with chat stopped.
SEARCH_LIMIT = 100
@dataclass(frozen=True, slots=True)
class Probe:
kind: ProbeKind
names: tuple[str, ...] = ()
text: str = ""
@dataclass(frozen=True, slots=True)
class Plan:
confirm: MigrationConfirmation | None
message: str
@dataclass(slots=True)
class Report:
lines: list[str] = field(default_factory=list)
failed: bool = False
def ok(self, text: str) -> None:
self.lines.append(f"ok {text}")
def fail(self, text: str) -> None:
self.failed = True
self.lines.append(f"FAIL {text}")
def unverified(self, text: str) -> None:
self.lines.append(f"? {text}")
def migration_error_text(e: ChatInitError) -> str:
err = e.db_migration_error
if err.get("type") == "errorMigration":
me = err.get("migrationError", {})
if me.get("type") == "upgrade":
names = [m["upName"] for m in me.get("upMigrations", [])]
return f"{len(names)} migration(s) pending: {', '.join(names)}"
if me.get("type") == "downgrade":
names = me.get("downMigrations", [])
return f"database is newer than this build, to roll back: {', '.join(names)}"
return f"migration state error: {json.dumps(me)}"
return str(e)
def probe_of(e: ChatInitError) -> Probe:
err = e.db_migration_error
me = err.get("migrationError", {}) if err.get("type") == "errorMigration" else {}
if me.get("type") == "upgrade":
return Probe("upgrade", tuple(m["upName"] for m in me.get("upMigrations", [])))
if me.get("type") == "downgrade":
return Probe("downgrade", tuple(me.get("downMigrations", [])))
return Probe("failed", text=migration_error_text(e))
def migration_plan(probe: Probe, allow_up: bool, allow_down: bool) -> Plan:
listed = f"{len(probe.names)} migration(s): {', '.join(probe.names)}"
if probe.kind == "current":
return Plan(MigrationConfirmation.ERROR, "schema up to date")
if probe.kind == "upgrade":
if allow_up:
return Plan(MigrationConfirmation.YES_UP, f"applied {listed}")
return Plan(
None,
f"pending {listed}; a real start would apply them, --allow-migrations applies them now",
)
if probe.kind == "downgrade":
if allow_down:
return Plan(MigrationConfirmation.YES_UP_DOWN, f"rolled back {listed}")
return Plan(
None,
f"database is newer than this build, to roll back {listed}; "
"a real start would refuse, --allow-down-migrations rolls them back",
)
return Plan(None, probe.text)
async def probe_database(db: SqliteDb) -> Probe:
try:
api = await ChatApi.init(db, MigrationConfirmation.ERROR)
except ChatInitError as e:
return probe_of(e)
await api.close()
return Probe("current")
async def check_state(api: ChatApi, config: Config, report: Report) -> None:
user = await api.api_get_active_user()
if user is None:
report.fail("no active user in database, a real start would create one")
return
user_id = user["userId"]
report.ok(f"active user: {user_id}:{user['profile']['displayName']}")
search: T.ChatListQuery = {"type": "search", "search": config.group_name}
chats = await api.api_get_chats(user_id, {"type": "last", "count": SEARCH_LIMIT}, search)
groups = [c["chatInfo"]["groupInfo"] for c in chats if c["chatInfo"]["type"] == "group"]
marked = [g for g in groups if setup.is_roster_group(g)]
if marked:
group = marked[0]
report.ok(f"roster group {group['groupId']}: {group['groupProfile']['displayName']}")
else:
report.unverified(
f'no roster group named "{config.group_name}" in chat previews; '
"the bot finds a renamed one by its marker at startup, or creates it"
)
async def dry_run(config: Config, allow_up: bool, allow_down: bool) -> Report:
report = Report()
db = SqliteDb(file_prefix=config.db_prefix)
plan = migration_plan(await probe_database(db), allow_up, allow_down)
if plan.confirm is None:
report.fail(f"database: {plan.message}")
return report
try:
api = await ChatApi.init(db, plan.confirm)
except ChatInitError as e:
report.fail(f"database: {migration_error_text(e)}")
return report
report.ok(f"database opened, {plan.message}")
try:
await check_state(api, config, report)
finally:
await api.close()
return report
@@ -0,0 +1,235 @@
import sys
import pytest
from simplex_chat import MigrationConfirmation
from simplex_chat.core import ChatAPIError, ChatInitError
from support_bot_light import dry_run as dr
from support_bot_light import roster, setup
from support_bot_light.__main__ import main
from support_bot_light.config import Config
from tests.conftest import FakeChatApi, make_group
from tests.test_config import VALID
CONFIG = Config("Support", "./x", "hi", "Invite roster", "owner")
UPGRADE = ChatInitError(
"migration error",
{
"type": "errorMigration",
"dbFile": "x",
"migrationError": {
"type": "upgrade",
"upMigrations": [{"upName": "20261019_chat_layout", "withDown": True}],
},
},
)
DOWNGRADE = ChatInitError(
"migration error",
{
"type": "errorMigration",
"dbFile": "x",
"migrationError": {"type": "downgrade", "downMigrations": ["20261111_feeds"]},
},
)
DIFFERENT = ChatInitError(
"migration error",
{
"type": "errorMigration",
"dbFile": "x",
"migrationError": {
"type": "migrationError",
"mtrError": {"type": "different", "appMigration": "a", "dbMigration": "b"},
},
},
)
NOT_A_DATABASE = ChatInitError("not a database", {"type": "errorNotADatabase", "dbFile": "x"})
CHAT_NOT_STARTED = {"type": "error", "errorType": {"type": "chatNotStarted"}}
class DryRunApi(FakeChatApi):
"""The core with chat stopped: only chat previews list groups."""
def __init__(self, user: dict | None = None):
super().__init__()
self.user = user
self.closed = False
async def api_get_active_user(self):
return self.user
async def api_list_groups(self, user_id: int, contact_id=None, search=None) -> list[dict]:
raise ChatAPIError("chat command error", CHAT_NOT_STARTED)
async def api_list_contacts(self, user_id: int) -> list[dict]:
raise ChatAPIError("chat command error", CHAT_NOT_STARTED)
async def api_get_chats(self, user_id: int, pagination: dict, query: dict) -> list[dict]:
return [
{"chatInfo": {"type": "group", "groupInfo": g}}
for g in self.groups
if g["groupProfile"]["displayName"] == query["search"]
]
async def close(self) -> None:
self.closed = True
USER = {"userId": 1, "profile": {"displayName": "Support"}}
def roster_group(group_id: int = 10, name: str = "Invite roster") -> dict:
return make_group(
group_id,
{"displayName": name},
{roster.NAMESPACE: {"group": setup.GROUP_MARKER}},
)
def test_probe_reports_pending_and_newer_migrations_by_name():
assert dr.probe_of(UPGRADE) == dr.Probe("upgrade", ("20261019_chat_layout",))
assert dr.probe_of(DOWNGRADE) == dr.Probe("downgrade", ("20261111_feeds",))
def test_probe_reports_other_errors_as_failed_with_their_text():
different = dr.probe_of(DIFFERENT)
assert different.kind == "failed"
assert different.text.startswith("migration state error: ")
assert dr.probe_of(NOT_A_DATABASE) == dr.Probe("failed", text="not a database")
def test_plan_for_a_current_schema_opens_without_migrating():
plan = dr.migration_plan(dr.Probe("current"), False, False)
assert plan == dr.Plan(MigrationConfirmation.ERROR, "schema up to date")
def test_plan_applies_pending_migrations_only_when_allowed():
probe = dr.Probe("upgrade", ("a", "b"))
assert dr.migration_plan(probe, False, True).confirm is None
assert "--allow-migrations applies them now" in dr.migration_plan(probe, False, True).message
assert dr.migration_plan(probe, True, False) == dr.Plan(
MigrationConfirmation.YES_UP, "applied 2 migration(s): a, b"
)
def test_plan_rolls_back_only_when_allowed():
probe = dr.Probe("downgrade", ("20261111_feeds",))
refused = dr.migration_plan(probe, True, False)
assert refused.confirm is None
assert "--allow-down-migrations rolls them back" in refused.message
assert dr.migration_plan(probe, False, True) == dr.Plan(
MigrationConfirmation.YES_UP_DOWN, "rolled back 1 migration(s): 20261111_feeds"
)
def test_plan_for_a_failed_probe_stops_whatever_is_allowed():
assert dr.migration_plan(dr.Probe("failed", text="boom"), True, True) == dr.Plan(None, "boom")
async def test_state_without_an_active_user_fails():
report = dr.Report()
await dr.check_state(DryRunApi(), CONFIG, report)
assert report.failed
assert report.lines == ["FAIL no active user in database, a real start would create one"]
async def test_state_finds_the_marked_roster_group_by_name_with_chat_stopped():
api = DryRunApi(USER)
api.groups = [make_group(9, {"displayName": "Invite roster"}), roster_group()]
report = dr.Report()
await dr.check_state(api, CONFIG, report)
assert not report.failed
assert report.lines == [
"ok active user: 1:Support",
"ok roster group 10: Invite roster",
]
@pytest.mark.parametrize(
"groups",
[[], [roster_group(name="Renamed roster")], [make_group(9, {"displayName": "Invite roster"})]],
)
async def test_state_without_a_marked_group_of_that_name_is_unverified(groups):
api = DryRunApi(USER)
api.groups = groups
report = dr.Report()
await dr.check_state(api, CONFIG, report)
assert not report.failed
assert report.lines[1] == (
'? no roster group named "Invite roster" in chat previews; '
"the bot finds a renamed one by its marker at startup, or creates it"
)
def fake_init(monkeypatch, probe_error: ChatInitError | None, api: DryRunApi):
calls: list[MigrationConfirmation] = []
async def init(_db, confirm):
calls.append(confirm)
if confirm == MigrationConfirmation.ERROR and probe_error is not None:
raise probe_error
return api
monkeypatch.setattr(dr.ChatApi, "init", init)
return calls
async def test_dry_run_rolls_back_with_yes_up_down_and_checks_after(monkeypatch):
api = DryRunApi(USER)
api.groups = [roster_group()]
calls = fake_init(monkeypatch, DOWNGRADE, api)
report = await dr.dry_run(CONFIG, False, True)
assert calls == [MigrationConfirmation.ERROR, MigrationConfirmation.YES_UP_DOWN]
assert report.lines[0] == "ok database opened, rolled back 1 migration(s): 20261111_feeds"
assert not report.failed
assert api.closed
async def test_dry_run_reports_pending_migrations_without_opening_again(monkeypatch):
calls = fake_init(monkeypatch, UPGRADE, DryRunApi(USER))
report = await dr.dry_run(CONFIG, False, False)
assert calls == [MigrationConfirmation.ERROR]
assert report.failed
assert report.lines[0].startswith(
"FAIL database: pending 1 migration(s): 20261019_chat_layout"
)
async def test_dry_run_on_a_current_schema_closes_both_opens(monkeypatch):
api = DryRunApi(USER)
api.groups = [roster_group()]
calls = fake_init(monkeypatch, None, api)
report = await dr.dry_run(CONFIG, False, False)
assert calls == [MigrationConfirmation.ERROR, MigrationConfirmation.ERROR]
assert report.lines[0] == "ok database opened, schema up to date"
assert api.closed
@pytest.mark.parametrize("flag", ["--allow-migrations", "--allow-down-migrations"])
def test_migration_flags_require_dry_run(monkeypatch, flag):
monkeypatch.setattr(sys, "argv", ["support-bot-light", flag])
with pytest.raises(SystemExit) as exc:
main()
assert exc.value.code == 2
@pytest.mark.parametrize("failed,code", [(False, 0), (True, 1)])
def test_main_prints_the_report_and_exits_by_its_result(
tmp_path, monkeypatch, capsys, failed, code
):
(tmp_path / "config.toml").write_text(VALID, encoding="utf-8")
seen: list[tuple[bool, bool]] = []
async def fake_dry_run(_config, allow_up, allow_down):
seen.append((allow_up, allow_down))
return dr.Report(["ok database opened, schema up to date"], failed)
monkeypatch.setattr("support_bot_light.__main__.dry_run", fake_dry_run)
monkeypatch.setattr("support_bot_light.__main__.os.umask", lambda _mask: 0)
argv = ["support-bot-light", "--config", str(tmp_path / "config.toml"), "--dry-run"]
monkeypatch.setattr(sys, "argv", [*argv, "--allow-down-migrations"])
assert main() == code
assert seen == [(False, True)]
assert capsys.readouterr().out == "ok database opened, schema up to date\n"
+8 -1
View File
@@ -153,6 +153,14 @@ The reduced build runs one Linux job, build-linux (ubuntu-22.04 x86_64), for eve
- The Docker image (scripts/support-bot/Dockerfile) is not built in CI.
- Local: `scripts/ci/scope-tests.sh support-bot`.
#### support-bot-light
- Globs:
- apps/simplex-support-bot-light/**
- packages/simplex-chat-python/**
- CI, in build-linux: `scope-tests.sh support-bot-light` (step "Test changed scopes"): the Python library of the branch and the bot installed in a virtual environment, then ruff, pyright and pytest. The tests use a fake API, without libsimplex.
- Local: `scripts/ci/scope-tests.sh support-bot-light`.
#### Scopes lacking CI tests
| Scope | Paths | CI |
@@ -162,7 +170,6 @@ The reduced build runs one Linux job, build-linux (ubuntu-22.04 x86_64), for eve
| ts-client | packages/simplex-chat-client/typescript/** | - |
| webrtc | packages/simplex-chat-webrtc/** | - |
| calculator-bot | apps/simplex-calculator-bot/** | - |
| support-bot-light | apps/simplex-support-bot-light/** | - |
| prices | scripts/prices/** | - |
| nft | eth/nft/** | - |
+1
View File
@@ -91,6 +91,7 @@ SCOPE_CHANGES = {
"packages/simplex-chat-client/types/typescript/**",
],
"support-bot": ["apps/simplex-support-bot/**"],
"support-bot-light": ["apps/simplex-support-bot-light/**", "packages/simplex-chat-python/**"],
}
CABAL_FILE = "simplex-chat.cabal"
CABAL_VERSION = re.compile(r"^(version:\s*)(\S+)", re.M)
+10 -1
View File
@@ -28,8 +28,17 @@ case "${1:-}" in
support-bot)
(cd apps/simplex-support-bot && npm ci --no-audit --no-fund && npm run build && npm test)
;;
support-bot-light)
cd apps/simplex-support-bot-light
python3 -m venv .venv
.venv/bin/pip install -e ../../packages/simplex-chat-python -e '.[dev]'
.venv/bin/ruff check
.venv/bin/ruff format --check src tests
.venv/bin/pyright
.venv/bin/pytest tests
;;
*)
echo "usage: $0 badge-web | ci-scripts | website | mcp | support-bot" >&2
echo "usage: $0 badge-web | ci-scripts | website | mcp | support-bot | support-bot-light" >&2
exit 1
;;
esac
+8
View File
@@ -531,6 +531,14 @@ class ChangesTest(GitRepoTest):
self.assertEqual(self.builds("apps/simplex-support-bot/src/bot.ts"), set())
self.assertEqual(self.values["scopes"], "support-bot")
def test_support_bot_light_change_tests_its_scope(self):
self.assertEqual(self.builds("apps/simplex-support-bot-light/src/support_bot_light/handlers.py"), set())
self.assertEqual(self.values["scopes"], "support-bot-light")
def test_python_library_change_builds_packages_and_tests_the_support_bot_light_scope(self):
self.assertEqual(self.builds("packages/simplex-chat-python/src/simplex_chat/client.py"), {"packages"})
self.assertEqual(self.values["scopes"], "support-bot-light")
class PackageStateTest(GitRepoTest):
def setUp(self):