diff --git a/apps/simplex-support-bot/README.md b/apps/simplex-support-bot/README.md index f67e6bb739..031d9f0cd5 100644 --- a/apps/simplex-support-bot/README.md +++ b/apps/simplex-support-bot/README.md @@ -59,11 +59,12 @@ Run `npm start -- --help` for the auto-generated reference. Summary: | `--context-file` | both | required with `GROK_API_KEY` | | text file with Grok system context | | `--dry-run` | both | no | | check config, database and state, then exit | | `--allow-migrations` | both | no | | with `--dry-run`: apply pending migrations instead of reporting them | +| `--allow-down-migrations` | both | no | | with `--dry-run`: roll back migrations that this build does not have | | `-h` / `--help` | both | no | | show usage and exit | ## Config file -`--config config.toml` reads option values and message texts from a TOML file, as [config.toml.example](../../scripts/support-bot/config/config.toml.example) shows. Keys are the command-line options in snake_case (`team_group` for `--team-group`); a list is joined with commas. An option given on the command line takes precedence over the file. `--dry-run` and `--allow-migrations` are command-line only. +`--config config.toml` reads option values and message texts from a TOML file, as [config.toml.example](../../scripts/support-bot/config/config.toml.example) shows. Keys are the command-line options in snake_case (`team_group` for `--team-group`); a list is joined with commas. An option given on the command line takes precedence over the file. `--dry-run`, `--allow-migrations` and `--allow-down-migrations` are command-line only. The file holds the `pg_conn` password, so keep it readable only by the user that runs the bot. A message left out of `[messages]` keeps its built-in text. `{hours}` is replaced with 24 on weekdays and 48 at weekends in `timezone`. The welcome message is updated in the bot address on the next start. @@ -105,11 +106,11 @@ A message left out of `[messages]` keeps its built-in text. `{hours}` is replace ```bash cd scripts/support-bot cp config/config.toml.example config/config.toml -PG_CONN='postgres://simplex@127.0.0.1/simplex_support_bot' docker compose up --build +docker compose up --build LIBS=source docker compose build ``` -`scripts/support-bot/config` is mounted at `/etc/support-bot` and holds `config.toml` and the Grok context file. `GROK_API_KEY` is read from the environment. +`scripts/support-bot/config` is mounted at `/etc/support-bot` and holds `config.toml`, with `pg_conn`, and the Grok context file; the bot runs as uid 1000, which must be able to read them. `GROK_API_KEY` is read from the environment. Other arguments are passed after the service name, for example `docker compose run --rm support-bot --config /etc/support-bot/config.toml --dry-run`. ## Dry run @@ -130,11 +131,19 @@ FAIL team member 3:alice has display name "bob", the bot would exit A pending migration stops the checks: ``` -FAIL database: 2 migration(s) pending, a real start would apply them: 20261019_chat_layout, 20261021_badge_subscriptions +FAIL database: pending 2 migration(s): 20261019_chat_layout, 20261021_badge_subscriptions; a real start would apply them, --allow-migrations applies them now ``` With `--allow-migrations`, the migrations are applied first and the checks run after them. Run it against a restored copy of the database unless the migration is intended, and with the bot stopped. +A database migrated by a newer build also stops the checks, since the bot refuses to start on it: + +``` +FAIL database: database is newer than this build, to roll back 1 migration(s): 20260905_feeds; a real start would refuse, --allow-down-migrations rolls them back +``` + +With `--allow-down-migrations`, those migrations are rolled back with the down SQL that the newer build stored in the database, and the checks run after it. The core rolls back only when this build's migrations are a prefix of the database's; a database whose migrations diverge from this build's is reported as a migration state error and is not changed. Rolling back deletes the data of the removed migrations, so take a backup first. + A line is `ok`, `FAIL` or `?`. `?` marks an id absent from the chat previews: with chat stopped, only chats that were used are listed, so the bot verifies such ids at startup. The exit code is 0 when no line is `FAIL`, 1 otherwise. The checks cover the database connection and migrations, the persisted team group, Grok user and Grok contact, the `--auto-add-team-members` ids and names, and the `--context-file`. diff --git a/apps/simplex-support-bot/bot.test.ts b/apps/simplex-support-bot/bot.test.ts index 25a91fce90..640b10069f 100644 --- a/apps/simplex-support-bot/bot.test.ts +++ b/apps/simplex-support-bot/bot.test.ts @@ -8,7 +8,7 @@ import {CardManager} from "./src/cards.js" import {parseConfig} from "./src/config.js" import {GrokApiClient} from "./src/grok.js" import {loadGrokContext} from "./src/context.js" -import {dryRun} from "./src/dryRun.js" +import {dryRun, migrationPlan} from "./src/dryRun.js" import {defaultMessages, queueMessage, teamAddedMessage, noTeamMembersMessage} from "./src/messages.js" // Silence console output during tests @@ -2484,6 +2484,13 @@ describe("parseConfig Validation", () => { .toThrow(/--allow-migrations requires --dry-run/) }) + test("--allow-down-migrations defaults to false, parses with --dry-run, throws without it", () => { + expect(parseConfig(baseArgs).allowDownMigrations).toBe(false) + expect(parseConfig([...baseArgs, "--dry-run", "--allow-down-migrations"]).allowDownMigrations).toBe(true) + expect(() => parseConfig([...baseArgs, "--allow-down-migrations"])) + .toThrow(/--allow-down-migrations requires --dry-run/) + }) + describe("--config TOML file", () => { const configFile = (toml: string): string => { const path = join(mkdtempSync(join(tmpdir(), "support-bot-config-")), "bot.toml") @@ -2871,6 +2878,43 @@ describe("Dry Run", () => { expect(await dryRun(chat, config({contextFile: path}), {teamGroupId: 1})).toBe(false) }) + describe("migrationPlan", () => { + const allow = (allowMigrations: boolean, allowDownMigrations: boolean) => ({allowMigrations, allowDownMigrations}) + const upgrade = {type: "upgrade" as const, names: ["20261019_chat_layout", "20261021_badge_subscriptions"]} + const downgrade = {type: "downgrade" as const, names: ["20260905_feeds"]} + + test("current schema → opens without migrating", () => { + expect(migrationPlan({type: "current"}, allow(false, false))) + .toEqual({ok: true, confirm: "error", result: "schema up to date"}) + }) + + test("pending up migrations → fail without --allow-migrations, YesUp with it", () => { + expect(migrationPlan(upgrade, allow(false, true))).toEqual({ + ok: false, + reason: "pending 2 migration(s): 20261019_chat_layout, 20261021_badge_subscriptions; a real start would apply them, --allow-migrations applies them now", + }) + expect(migrationPlan(upgrade, allow(true, false))).toEqual({ + ok: true, + confirm: "yesUp", + result: "applied 2 migration(s): 20261019_chat_layout, 20261021_badge_subscriptions", + }) + }) + + test("down migrations → fail without --allow-down-migrations, YesUpDown with it", () => { + expect(migrationPlan(downgrade, allow(true, false))).toEqual({ + ok: false, + reason: "database is newer than this build, to roll back 1 migration(s): 20260905_feeds; a real start would refuse, --allow-down-migrations rolls them back", + }) + expect(migrationPlan(downgrade, allow(false, true))) + .toEqual({ok: true, confirm: "yesUpDown", result: "rolled back 1 migration(s): 20260905_feeds"}) + }) + + test("probe failure → fails with its text whatever is allowed", () => { + expect(migrationPlan({type: "failed", text: "connection refused"}, allow(true, true))) + .toEqual({ok: false, reason: "connection refused"}) + }) + }) + test("missing context file → reported, passes", async () => { const chat = mkChat([groupChat(1, "Support Team")]) const cfg = config({contextFile: join(tmpdir(), "no-such-context.txt")}) diff --git a/apps/simplex-support-bot/src/config.ts b/apps/simplex-support-bot/src/config.ts index 1823875e06..e9da119290 100644 --- a/apps/simplex-support-bot/src/config.ts +++ b/apps/simplex-support-bot/src/config.ts @@ -21,6 +21,7 @@ export interface Config { contextFile: string | null dryRun: boolean allowMigrations: boolean + allowDownMigrations: boolean grokApiKey: string | null messages: Messages } @@ -62,6 +63,7 @@ function buildCommand(): Command { .option("--context-file ", "text file with Grok system context (required if GROK_API_KEY set)") .option("--dry-run", "check config, database and state, then exit without starting chat") .option("--allow-migrations", "with --dry-run: apply pending migrations instead of reporting them") + .option("--allow-down-migrations", "with --dry-run: roll back migrations that this build does not have") .addHelpText("after", "\nEnvironment:\n GROK_API_KEY xAI API key — enables Grok replies\n SIMPLEX_LIBS_DIR local libsimplex build for the --db backend\n SIMPLEX_ADDON_PATH locally built Node.js add-on\n") } @@ -80,6 +82,7 @@ interface RawOpts { contextFile?: string dryRun?: boolean allowMigrations?: boolean + allowDownMigrations?: boolean } interface ConfigFile { @@ -159,6 +162,7 @@ export function parseConfig(args: string[]): Config { } if (opts.allowMigrations && !opts.dryRun) throw new Error("--allow-migrations requires --dry-run") + if (opts.allowDownMigrations && !opts.dryRun) throw new Error("--allow-down-migrations requires --dry-run") const teamGroup: IdName = {id: 0, name: opts.teamGroup} @@ -190,6 +194,7 @@ export function parseConfig(args: string[]): Config { contextFile, dryRun: opts.dryRun ?? false, allowMigrations: opts.allowMigrations ?? false, + allowDownMigrations: opts.allowDownMigrations ?? false, grokApiKey, messages: file.messages, } diff --git a/apps/simplex-support-bot/src/dryRun.ts b/apps/simplex-support-bot/src/dryRun.ts index a04128cbc5..b0fe4b0a87 100644 --- a/apps/simplex-support-bot/src/dryRun.ts +++ b/apps/simplex-support-bot/src/dryRun.ts @@ -1,4 +1,4 @@ -import {api} from "simplex-chat" +import {api, core} from "simplex-chat" import {T} from "@simplex-chat/types" import {Config, IdName} from "./config.js" import {loadGrokContext} from "./context.js" @@ -9,6 +9,37 @@ export interface DryRunState { grokUserId?: number } +export type DbProbe = + | {type: "current"} + | {type: "upgrade"; names: string[]} + | {type: "downgrade"; names: string[]} + | {type: "failed"; text: string} + +export type MigrationPlan = + | {ok: true; confirm: core.MigrationConfirmation; result: string} + | {ok: false; reason: string} + +export function migrationPlan(probe: DbProbe, config: Pick): MigrationPlan { + switch (probe.type) { + case "current": + return {ok: true, confirm: core.MigrationConfirmation.Error, result: "schema up to date"} + case "upgrade": { + const list = `${probe.names.length} migration(s): ${probe.names.join(", ")}` + return config.allowMigrations + ? {ok: true, confirm: core.MigrationConfirmation.YesUp, result: `applied ${list}`} + : {ok: false, reason: `pending ${list}; a real start would apply them, --allow-migrations applies them now`} + } + case "downgrade": { + const list = `${probe.names.length} migration(s): ${probe.names.join(", ")}` + return config.allowDownMigrations + ? {ok: true, confirm: core.MigrationConfirmation.YesUpDown, result: `rolled back ${list}`} + : {ok: false, reason: `database is newer than this build, to roll back ${list}; a real start would refuse, --allow-down-migrations rolls them back`} + } + case "failed": + return {ok: false, reason: probe.text} + } +} + const SEARCH_LIMIT = 100 const LISTING_LIMIT = 1000 const GROK_PROFILE_NAME = "Grok" diff --git a/apps/simplex-support-bot/src/index.ts b/apps/simplex-support-bot/src/index.ts index 373f819115..ef289ecc65 100644 --- a/apps/simplex-support-bot/src/index.ts +++ b/apps/simplex-support-bot/src/index.ts @@ -3,7 +3,7 @@ import {api, bot, core, util} from "simplex-chat" import {T} from "@simplex-chat/types" import {Config, parseConfig} from "./config.js" import {SupportBot} from "./bot.js" -import {dryRun} from "./dryRun.js" +import {DbProbe, dryRun, migrationPlan} from "./dryRun.js" import {GrokApiClient, GrokMessage} from "./grok.js" import {loadGrokContext} from "./context.js" import {profileMutex, log, logError, getGroupInfo, getContact} from "./util.js" @@ -375,29 +375,19 @@ async function main(): Promise { } async function runDryRun(config: Config, state: BotState): Promise { - const probe = await probeDatabase(config.db) - if (probe.type === "failed") { - console.log(`FAIL database: ${probe.text}`) + const plan = migrationPlan(await probeDatabase(config.db), config) + if (!plan.ok) { + console.log(`FAIL database: ${plan.reason}`) return false } - const pending = probe.type === "pending" ? probe.names : [] - if (pending.length > 0 && !config.allowMigrations) { - console.log(`FAIL database: ${pending.length} migration(s) pending, a real start would apply them: ${pending.join(", ")}`) - return false - } - const migrating = pending.length > 0 let chat: api.ChatApi try { - chat = await api.ChatApi.init( - config.db, - migrating ? core.MigrationConfirmation.YesUp : core.MigrationConfirmation.Error - ) + chat = await api.ChatApi.init(config.db, plan.confirm) } catch (err) { console.log(`FAIL database: ${migrationErrorText(err)}`) return false } - const schemaState = migrating ? `applied ${pending.length} migration(s): ${pending.join(", ")}` : "schema up to date" - console.log(`ok database ${config.db.type} opened, ${schemaState}`) + console.log(`ok database ${config.db.type} opened, ${plan.result}`) try { return await dryRun(chat, config, state) } finally { @@ -405,8 +395,6 @@ async function runDryRun(config: Config, state: BotState): Promise { } } -type DbProbe = {type: "current"} | {type: "pending"; names: string[]} | {type: "failed"; text: string} - async function probeDatabase(db: api.DbConfig): Promise { try { const chat = await api.ChatApi.init(db, core.MigrationConfirmation.Error) @@ -414,8 +402,10 @@ async function probeDatabase(db: api.DbConfig): Promise { return {type: "current"} } catch (err) { const dbErr = (err as core.ChatInitError).dbMigrationError - if (dbErr?.type === "errorMigration" && dbErr.migrationError.type === "upgrade") { - return {type: "pending", names: dbErr.migrationError.upMigrations.map(m => m.upName)} + if (dbErr?.type === "errorMigration") { + const me = dbErr.migrationError + if (me.type === "upgrade") return {type: "upgrade", names: me.upMigrations.map(m => m.upName)} + if (me.type === "downgrade") return {type: "downgrade", names: me.downMigrations} } return {type: "failed", text: migrationErrorText(err)} } diff --git a/apps/simplex-support-bot/test/__mocks__/simplex-chat.js b/apps/simplex-support-bot/test/__mocks__/simplex-chat.js index 92e05a4178..974f0deb38 100644 --- a/apps/simplex-support-bot/test/__mocks__/simplex-chat.js +++ b/apps/simplex-support-bot/test/__mocks__/simplex-chat.js @@ -31,6 +31,6 @@ class ChatAPIError extends Error { module.exports = { api: {ChatApi: {}}, bot: {}, - core: {ChatAPIError}, + core: {ChatAPIError, MigrationConfirmation: {YesUp: "yesUp", YesUpDown: "yesUpDown", Console: "console", Error: "error"}}, util: {ciContentText, ciBotCommand, contactAddressStr}, } diff --git a/scripts/support-bot/compose.yml b/scripts/support-bot/compose.yml index 8a8238c3c9..70f8114aaa 100644 --- a/scripts/support-bot/compose.yml +++ b/scripts/support-bot/compose.yml @@ -1,7 +1,7 @@ # network_mode: host makes 127.0.0.1 reach PostgreSQL on the host. # # cp config/config.toml.example config/config.toml -# PG_CONN='postgres://simplex@127.0.0.1/simplex_support_bot' docker compose up --build +# docker compose up --build # LIBS=source docker compose build services: @@ -19,11 +19,6 @@ services: volumes: - support-bot-data:/data - ./config:/etc/support-bot:ro - command: - - "--config" - - "/etc/support-bot/config.toml" - - "--pg-conn" - - "${PG_CONN:?set PG_CONN, e.g. postgres://simplex@127.0.0.1/simplex_support_bot}" stop_grace_period: 30s volumes: diff --git a/scripts/support-bot/config/config.toml.example b/scripts/support-bot/config/config.toml.example index 4d08b0dd44..89f3c2d01f 100644 --- a/scripts/support-bot/config/config.toml.example +++ b/scripts/support-bot/config/config.toml.example @@ -5,6 +5,7 @@ auto_add_team_members = ["1:Alice"] context_file = "/etc/support-bot/grok-context.yaml" state_file = "/data/state.json" db = "postgres" +pg_conn = "postgres://simplex@127.0.0.1/simplex_support_bot" timezone = "UTC" # A message left out keeps its built-in text.