From 158338e5d08e4dbcd3da21741e3dd18823e0edc5 Mon Sep 17 00:00:00 2001 From: sh-agents Date: Thu, 12 Nov 2026 14:16:33 +0000 Subject: [PATCH] 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> --- .github/workflows/build.yml | 1 + apps/simplex-support-bot-light/README.md | 36 +++ .../src/support_bot_light/__main__.py | 22 ++ .../src/support_bot_light/dry_run.py | 145 +++++++++++ .../tests/test_dry_run.py | 235 ++++++++++++++++++ scripts/ci/README.md | 9 +- scripts/ci/packages_release.py | 1 + scripts/ci/scope-tests.sh | 11 +- scripts/ci/test_packages_release.py | 8 + 9 files changed, 466 insertions(+), 2 deletions(-) create mode 100644 apps/simplex-support-bot-light/src/support_bot_light/dry_run.py create mode 100644 apps/simplex-support-bot-light/tests/test_dry_run.py diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c90accfbf2..28d7aa7747 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -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: diff --git a/apps/simplex-support-bot-light/README.md b/apps/simplex-support-bot-light/README.md index 058f539d3f..e065134f89 100644 --- a/apps/simplex-support-bot-light/README.md +++ b/apps/simplex-support-bot-light/README.md @@ -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 diff --git a/apps/simplex-support-bot-light/src/support_bot_light/__main__.py b/apps/simplex-support-bot-light/src/support_bot_light/__main__.py index a7476643a2..8d930080f9 100644 --- a/apps/simplex-support-bot-light/src/support_bot_light/__main__.py +++ b/apps/simplex-support-bot-light/src/support_bot_light/__main__.py @@ -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 diff --git a/apps/simplex-support-bot-light/src/support_bot_light/dry_run.py b/apps/simplex-support-bot-light/src/support_bot_light/dry_run.py new file mode 100644 index 0000000000..8da57e70f2 --- /dev/null +++ b/apps/simplex-support-bot-light/src/support_bot_light/dry_run.py @@ -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 diff --git a/apps/simplex-support-bot-light/tests/test_dry_run.py b/apps/simplex-support-bot-light/tests/test_dry_run.py new file mode 100644 index 0000000000..11968e6fe8 --- /dev/null +++ b/apps/simplex-support-bot-light/tests/test_dry_run.py @@ -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" diff --git a/scripts/ci/README.md b/scripts/ci/README.md index 0693d4e90d..d4814235bb 100644 --- a/scripts/ci/README.md +++ b/scripts/ci/README.md @@ -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/** | - | diff --git a/scripts/ci/packages_release.py b/scripts/ci/packages_release.py index 15c00501f7..dae1b14a4b 100644 --- a/scripts/ci/packages_release.py +++ b/scripts/ci/packages_release.py @@ -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) diff --git a/scripts/ci/scope-tests.sh b/scripts/ci/scope-tests.sh index 74c04c2842..eca861c925 100755 --- a/scripts/ci/scope-tests.sh +++ b/scripts/ci/scope-tests.sh @@ -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 diff --git a/scripts/ci/test_packages_release.py b/scripts/ci/test_packages_release.py index e5bfac4823..b1bea26fdf 100644 --- a/scripts/ci/test_packages_release.py +++ b/scripts/ci/test_packages_release.py @@ -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):