RunicGateway/website
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity

feat(events): the runner (Phase 2)
All checks were successful
PR Checks / bot-tests (pull_request) Successful in 32s
Details
PR Checks / client-build (pull_request) Successful in 33s
Details
PR Checks / server-tests (pull_request) Successful in 5m29s
Details

Browse Source 
`utils/eventRunner.js`, the eighth poller, wired into server.js beside
engagementWorker. Its tick reclaims stale leases, sweeps occurrences past their
grace window into `missed`, advances each due run through its phases, and drains
that phase's steps in `seq` order. The three core actions from Phase 1 get real
bodies, so a published event started from the existing run route now announces,
waits and completes on its own.

No routes are added: a runner has no surface, and the live controls stay Phase
3's.

Four things the org lead settled (2026-09-02): a parked step is `running` with a
NULL lease; `await: 'human'` and `holdFor` are ordinary success-envelope members
rather than special cases keyed on an action id; a run whose concurrency key is
held stays `scheduled` and lets its grace window decide; and `n` in §L's
`retry(n)` is a runner constant.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
claude
2026-09-02 06:32:24 -05:00
parent d88906e43c
commit 2e964cfeee
10 changed files with 2527 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

508
server/test/eventRunnerSql.test.js Normal file
View File

@@ -0,0 +1,508 @@
// ── The runner's raw SQL, against a real MariaDB ───────────────────────────
//
// EVENTS_PLAN.md Phase 2. `eventRunner.test.js` stubs the three tables and
// exercises everything the runner DECIDES. It cannot prove the statements whose
// whole correctness is a server contract, and on this codebase that gap has
// already cost something once: engagement's cooldown claim was green against its
// stub and always allowed the send against a real server, because the connector
// defaults `foundRows: true` and a no-op UPDATE reports 1 rather than 0.
//
// So the five statements that decide who owns what run here, for real:
//
// • **`claimStart`** — the CAS `scheduled -> starting`. "Exactly one winner" is
// `affectedRows = 1` for one caller and 0 for every other, and that is a
// property of the SERVER's answer, not of the SQL's shape.
// • **`claimTick`** — the same, for a run already in flight, and with no
// owner-matches escape clause. A live lease must refuse its own holder, or
// one `setInterval` that overran advances one run twice.
// • **`transition`** — a guarded status move. The guard is the whole thing: a
// run cancelled between the read and the write must not be transitioned.
// • **`reclaimStale`** on steps — two statements in a fixed ORDER, give-up
// before hand-back. Reversing them makes `MAX_ATTEMPTS` unreachable and the
// row cycles forever (Engagement Phase 14's defect), and **neither statement
// may touch `attempts`**.
// • **`holdNext`** — `UPDATE ... ORDER BY seq LIMIT 1` with a guard, which is
// both a MariaDB-specific syntax and a correctness claim: it must move the
// next PENDING step and only ever push a due date later.
//
// Plus the two unique indexes that are load-bearing rather than tidy:
// `uq_evrun_occurrence` (which, not the claim, is what stops two runs of one
// occurrence existing) and `uq_evstep_slot` (which is what makes re-materialising
// a phase a no-op).
//
// **It SKIPS when there is no database**, deliberately: CI runs the suite with
// the pool pointed at a dead port, and a file that failed there would make every
// PR red for a reason unrelated to itself. Run it against this machine's
// container with:
//
// DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=... DB_PASSWORD=... \
// node --test test/eventRunnerSql.test.js
//
// It creates its tables in a throwaway database named after the process and
// drops it again, so it can never touch a real schema.
const { test, before, after, beforeEach } = require('node:test')
const assert = require('node:assert/strict')
const mariadb = require('mariadb')
// Trimmed to the columns these statements read or write. The ENUMs are verbatim,
// because "is `missed` a legal value" is one of the things being proved.
const SCHEMA = `
CREATE TABLE event_definitions (
id INT AUTO_INCREMENT PRIMARY KEY,
grace_seconds INT NOT NULL DEFAULT 900
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE event_runs (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
definition_id INT NOT NULL,
version_id INT NOT NULL,
scope VARCHAR(190) NOT NULL DEFAULT '',
status ENUM('scheduled','starting','running','paused','ending',
'completed','cancelled','failed','missed')
NOT NULL DEFAULT 'scheduled',
health ENUM('ok','degraded','stalled') NOT NULL DEFAULT 'ok',
current_phase VARCHAR(64) NULL,
scheduled_for DATETIME NOT NULL,
concurrency_key VARCHAR(190) NULL,
started_at DATETIME NULL,
ended_at DATETIME NULL,
claimed_by VARCHAR(64) NULL,
claim_expires_at DATETIME NULL,
last_error VARCHAR(500) NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uq_evrun_occurrence (definition_id, scope, scheduled_for),
INDEX idx_evrun_due (status, scheduled_for),
INDEX idx_evrun_concurrency (concurrency_key, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE event_run_steps (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
run_id BIGINT NOT NULL,
phase VARCHAR(64) NOT NULL,
seq INT NOT NULL,
action_id VARCHAR(96) NOT NULL,
params JSON NULL,
action_version INT NOT NULL DEFAULT 1,
status ENUM('pending','running','done','failed','skipped','refused','cancelled')
NOT NULL DEFAULT 'pending',
due_at DATETIME NULL,
attempts INT NOT NULL DEFAULT 0,
on_failure VARCHAR(32) NOT NULL DEFAULT 'skip',
idempotency_key CHAR(40) NOT NULL,
claimed_by VARCHAR(64) NULL,
claim_expires_at DATETIME NULL,
last_error VARCHAR(500) NULL,
started_at DATETIME NULL,
finished_at DATETIME NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uq_evstep_slot (run_id, phase, seq),
INDEX idx_evstep_due (status, due_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
`
// The statements under test, verbatim from `eventRuns.db.js` and
// `eventRunSteps.db.js`. Duplicated rather than required, because requiring the
// modules would drag in `utils/db`'s pool, which the harness has already pointed
// at a dead port. The pool below leaves `foundRows` at the connector's default,
// exactly as `utils/db.js` does — pinning it here would make this file agree with
// the code by construction and prove nothing about the pool the server runs.
const CLAIM_START = `
UPDATE event_runs
SET status = 'starting', claimed_by = ?, claim_expires_at = ?,
started_at = COALESCE(started_at, NOW())
WHERE id = ? AND status = 'scheduled'`
const CLAIM_TICK = `
UPDATE event_runs
SET claimed_by = ?, claim_expires_at = ?
WHERE id = ?
AND status IN ('starting','running','ending')
AND (claim_expires_at IS NULL OR claim_expires_at < ?)`
const TRANSITION = `
UPDATE event_runs SET status = ?, current_phase = ?
WHERE id = ? AND status IN (?)`
const CLAIM_STEP = `
UPDATE event_run_steps
SET status = 'running', attempts = attempts + 1, claimed_by = ?, claim_expires_at = ?,
started_at = COALESCE(started_at, NOW())
WHERE id = ? AND status = 'pending' AND (due_at IS NULL OR due_at <= ?)`
const STEP_GIVE_UP = `
UPDATE event_run_steps
SET status = 'failed', last_error = 'gave up after repeated interruptions',
finished_at = NOW(), claimed_by = NULL, claim_expires_at = NULL
WHERE status = 'running'
AND claim_expires_at IS NOT NULL AND claim_expires_at < ?
AND attempts >= ?`
const STEP_RECLAIM = `
UPDATE event_run_steps
SET status = 'pending', claimed_by = NULL, claim_expires_at = NULL
WHERE status = 'running' AND claim_expires_at IS NOT NULL AND claim_expires_at < ?`
const HOLD_NEXT = `
UPDATE event_run_steps
SET due_at = ?
WHERE run_id = ? AND phase = ? AND seq > ? AND status = 'pending'
AND (due_at IS NULL OR due_at < ?)
ORDER BY seq LIMIT 1`
const MATERIALISE_RUN = `
INSERT IGNORE INTO event_runs (definition_id, version_id, scope, scheduled_for, concurrency_key)
VALUES (?, ?, ?, ?, ?)`
const MATERIALISE_STEP = `
INSERT IGNORE INTO event_run_steps (run_id, phase, seq, action_id, idempotency_key)
VALUES (?, ?, ?, ?, ?)`
const FIND_MISSED = `
SELECT r.id FROM event_runs r
JOIN event_definitions d ON d.id = r.definition_id
WHERE r.status = 'scheduled'
AND r.scheduled_for + INTERVAL d.grace_seconds SECOND < ?`
const DB = `rg_events_test_${process.pid}`
let pool = null
let available = false
const poolOpts = () => ({
host: process.env.DB_HOST || '127.0.0.1',
port: Number(process.env.DB_PORT) || 3306,
user: process.env.DB_USER || 'root',
password: process.env.DB_PASSWORD || '',
})
before(async () => {
const admin = mariadb.createPool({
...poolOpts(),
connectionLimit: 1,
connectTimeout: 2000,
initializationTimeout: 2000,
multipleStatements: true,
})
try {
await admin.query(`CREATE DATABASE ${DB}`)
available = true
} catch {
available = false
} finally {
await admin.end().catch(() => {})
}
if (!available) return
pool = mariadb.createPool({
...poolOpts(),
database: DB,
connectionLimit: 3,
multipleStatements: true,
bigIntAsNumber: true,
insertIdAsNumber: true,
})
await pool.query(SCHEMA)
})
after(async () => {
if (pool) {
await pool.query(`DROP DATABASE IF EXISTS ${DB}`).catch(() => {})
await pool.end().catch(() => {})
}
})
// Checked INSIDE each test, never as a `{ skip }` option: the option is evaluated
// when the file is read, which is before `before()` has had a chance to find out
// whether there is a database. Every test skipped unconditionally is what that
// mistake looks like, and it looks exactly like a passing suite.
const SKIP = 'no database reachable - set DB_HOST/DB_PORT/DB_USER/DB_PASSWORD to run'
const needDb = (t) => {
if (available) return false
t.skip(SKIP)
return true
}
const T0 = new Date('2026-09-02T12:00:00Z')
const later = (ms) => new Date(T0.getTime() + ms)
const rows = (r) => Number(r.affectedRows)
beforeEach(async () => {
if (!available) return
await pool.query('DELETE FROM event_run_steps')
await pool.query('DELETE FROM event_runs')
await pool.query('DELETE FROM event_definitions')
})
async function seedRun(over = {}) {
const def = await pool.query('INSERT INTO event_definitions (grace_seconds) VALUES (?)', [
over.graceSeconds ?? 900,
])
const r = await pool.query(
`INSERT INTO event_runs (definition_id, version_id, scope, status, scheduled_for, concurrency_key,
claimed_by, claim_expires_at)
VALUES (?, 1, ?, ?, ?, ?, ?, ?)`,
[
def.insertId,
over.scope ?? '',
over.status ?? 'scheduled',
over.scheduledFor ?? T0,
over.concurrencyKey ?? null,
over.claimedBy ?? null,
over.claimExpiresAt ?? null,
],
)
return { runId: r.insertId, definitionId: def.insertId }
}
const seedStep = async (runId, over = {}) =>
(
await pool.query(
`INSERT INTO event_run_steps (run_id, phase, seq, action_id, status, due_at, attempts,
claimed_by, claim_expires_at, idempotency_key)
VALUES (?, ?, ?, 'test.noop', ?, ?, ?, ?, ?, ?)`,
[
runId,
over.phase ?? 'main',
over.seq ?? 0,
over.status ?? 'pending',
over.dueAt ?? null,
over.attempts ?? 0,
over.claimedBy ?? null,
over.claimExpiresAt ?? null,
over.key ?? 'k'.repeat(40),
],
)
).insertId
const stepById = async (id) => (await pool.query('SELECT * FROM event_run_steps WHERE id = ?', [id]))[0]
const runById = async (id) => (await pool.query('SELECT * FROM event_runs WHERE id = ?', [id]))[0]
// ── claimStart: exactly one winner ─────────────────────────────────────────
test('claimStart: the first caller wins and every other gets zero', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun()
const first = await pool.query(CLAIM_START, ['host:1', later(60_000), runId])
const second = await pool.query(CLAIM_START, ['host:2', later(60_000), runId])
assert.equal(rows(first), 1, 'the winner is told 1')
assert.equal(rows(second), 0, 'the loser is told 0, not 1 with foundRows')
assert.equal((await runById(runId)).claimed_by, 'host:1')
assert.equal((await runById(runId)).status, 'starting')
})
test('claimStart: started_at is stamped once and never moved', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun()
await pool.query(CLAIM_START, ['host:1', later(60_000), runId])
const first = (await runById(runId)).started_at
await pool.query("UPDATE event_runs SET status = 'scheduled' WHERE id = ?", [runId])
await pool.query(CLAIM_START, ['host:2', later(60_000), runId])
assert.deepEqual((await runById(runId)).started_at, first, 'COALESCE keeps the original instant')
})
// ── claimTick: a live lease refuses even its own holder ────────────────────
test('claimTick: a live lease is not re-enterable by the process that took it', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running', claimedBy: 'host:1', claimExpiresAt: later(60_000) })
const again = await pool.query(CLAIM_TICK, ['host:1', later(120_000), runId, T0])
assert.equal(rows(again), 0, 'a tick that overran must not advance its own run twice')
})
test('claimTick: an expired lease is takeable, by anyone', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running', claimedBy: 'host:1', claimExpiresAt: later(-60_000) })
const taken = await pool.query(CLAIM_TICK, ['host:2', later(60_000), runId, T0])
assert.equal(rows(taken), 1)
assert.equal((await runById(runId)).claimed_by, 'host:2')
})
test('claimTick: a paused run is never claimable', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'paused' })
assert.equal(rows(await pool.query(CLAIM_TICK, ['host:1', later(60_000), runId, T0])), 0)
})
// ── transition: the guard is the whole point ───────────────────────────────
test('transition: a run cancelled underneath the tick is not transitioned', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
await pool.query("UPDATE event_runs SET status = 'cancelled' WHERE id = ?", [runId])
const moved = await pool.query(TRANSITION, ['completed', 'main', runId, 'running'])
assert.equal(rows(moved), 0)
assert.equal((await runById(runId)).status, 'cancelled')
})
test('transition: running -> running is a guarded write, not a no-op', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
// This is how the runner advances `current_phase`, and `foundRows` is exactly
// what makes it report 1 despite `status` not changing — which is the answer
// the caller needs, because what it is checking is that the run is STILL
// running, not that the status moved.
const moved = await pool.query(TRANSITION, ['running', 'closing', runId, 'running'])
assert.equal(rows(moved), 1)
assert.equal((await runById(runId)).current_phase, 'closing')
})
// ── The step claim ─────────────────────────────────────────────────────────
test('the step claim: one winner, and attempts is incremented by the claim alone', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
const stepId = await seedStep(runId)
assert.equal(rows(await pool.query(CLAIM_STEP, ['host:1', later(60_000), stepId, T0])), 1)
assert.equal(rows(await pool.query(CLAIM_STEP, ['host:2', later(60_000), stepId, T0])), 0)
assert.equal((await stepById(stepId)).attempts, 1, 'one claim, one attempt')
})
test('the step claim: a step held behind a core.wait is not due', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
const stepId = await seedStep(runId, { dueAt: later(300_000) })
assert.equal(rows(await pool.query(CLAIM_STEP, ['host:1', later(60_000), stepId, T0])), 0)
assert.equal(rows(await pool.query(CLAIM_STEP, ['host:1', later(360_000), stepId, later(301_000)])), 1)
})
// ── The reclaim: order, and what it must not touch ─────────────────────────
test('the reclaim hands a stale step back WITHOUT resetting attempts', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
const stepId = await seedStep(runId, { status: 'running', attempts: 2, claimExpiresAt: later(-1000) })
await pool.query(STEP_GIVE_UP, [T0, 3])
await pool.query(STEP_RECLAIM, [T0])
const step = await stepById(stepId)
assert.equal(step.status, 'pending')
assert.equal(step.attempts, 2, 'Engagement Phase 14: a reclaim that reset this made MAX_ATTEMPTS unreachable')
})
test('the reclaim gives up FIRST, so a spent step leaves running as failed', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
const stepId = await seedStep(runId, { status: 'running', attempts: 3, claimExpiresAt: later(-1000) })
const gaveUp = await pool.query(STEP_GIVE_UP, [T0, 3])
const reclaimed = await pool.query(STEP_RECLAIM, [T0])
assert.equal(rows(gaveUp), 1)
assert.equal(rows(reclaimed), 0, 'reversing these two makes the row retry forever')
assert.equal((await stepById(stepId)).status, 'failed')
assert.equal((await stepById(stepId)).attempts, 3)
})
test('the reclaim leaves a PARKED step alone, however long it waits', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
const stepId = await seedStep(runId, { status: 'running', attempts: 1, claimExpiresAt: null })
await pool.query(STEP_GIVE_UP, [later(365 * 24 * 3600 * 1000), 3])
await pool.query(STEP_RECLAIM, [later(365 * 24 * 3600 * 1000)])
const step = await stepById(stepId)
assert.equal(step.status, 'running', 'a NULL lease is a parked cue, not staleness')
assert.equal(step.attempts, 1)
})
// ── holdNext ───────────────────────────────────────────────────────────────
test('holdNext moves the next PENDING step of the phase, and only one', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
await seedStep(runId, { seq: 0, status: 'done' })
const second = await seedStep(runId, { seq: 1 })
const third = await seedStep(runId, { seq: 2 })
const moved = await pool.query(HOLD_NEXT, [later(300_000), runId, 'main', 0, later(300_000)])
assert.equal(rows(moved), 1)
assert.deepEqual((await stepById(second)).due_at, later(300_000))
assert.equal((await stepById(third)).due_at, null, 'a wait holds the next step, not the rest of the phase')
})
test('holdNext never pulls a due date earlier, so a re-dispatch cannot double the wait', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
await seedStep(runId, { seq: 0, status: 'done' })
const second = await seedStep(runId, { seq: 1, dueAt: later(600_000) })
const moved = await pool.query(HOLD_NEXT, [later(300_000), runId, 'main', 0, later(300_000)])
assert.equal(rows(moved), 0)
assert.deepEqual((await stepById(second)).due_at, later(600_000))
})
test('holdNext skips a step that is already running', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
await seedStep(runId, { seq: 0, status: 'done' })
await seedStep(runId, { seq: 1, status: 'running' })
const third = await seedStep(runId, { seq: 2 })
await pool.query(HOLD_NEXT, [later(300_000), runId, 'main', 0, later(300_000)])
assert.deepEqual((await stepById(third)).due_at, later(300_000))
})
// ── The two unique indexes that carry the weight ───────────────────────────
test('uq_evrun_occurrence, not the claim, is what stops two runs of one occurrence', async (t) => {
if (needDb(t)) return
const def = await pool.query('INSERT INTO event_definitions (grace_seconds) VALUES (900)')
const a = await pool.query(MATERIALISE_RUN, [def.insertId, 1, '', T0, null])
const b = await pool.query(MATERIALISE_RUN, [def.insertId, 1, '', T0, null])
assert.equal(rows(a), 1)
assert.equal(rows(b), 0, 'INSERT IGNORE answers honestly rather than raising a 1062')
const all = await pool.query('SELECT COUNT(*) AS n FROM event_runs')
assert.equal(Number(all[0].n), 1)
})
test("scope '' rather than NULL is what makes that index work at all", async (t) => {
if (needDb(t)) return
const def = await pool.query('INSERT INTO event_definitions (grace_seconds) VALUES (900)')
// The empty-string case collides, as it must. A NULL scope would NOT: multiple
// NULLs do not collide in MariaDB, which would silently permit two runs of one
// occurrence — the reason the column is NOT NULL DEFAULT ''.
await pool.query(MATERIALISE_RUN, [def.insertId, 1, '', T0, null])
assert.equal(rows(await pool.query(MATERIALISE_RUN, [def.insertId, 1, '', T0, null])), 0)
// Two different scopes are two different occurrences, which is what lets a
// worldwide event fan out across servers without colliding with itself.
assert.equal(rows(await pool.query(MATERIALISE_RUN, [def.insertId, 1, 'atlantic', T0, null])), 1)
})
test('uq_evstep_slot makes re-materialising a phase a no-op', async (t) => {
if (needDb(t)) return
const { runId } = await seedRun({ status: 'running' })
assert.equal(rows(await pool.query(MATERIALISE_STEP, [runId, 'main', 0, 'test.noop', 'a'.repeat(40)])), 1)
assert.equal(rows(await pool.query(MATERIALISE_STEP, [runId, 'main', 0, 'test.noop', 'b'.repeat(40)])), 0)
const [step] = await pool.query('SELECT idempotency_key FROM event_run_steps WHERE run_id = ?', [runId])
assert.equal(step.idempotency_key, 'a'.repeat(40), 'a re-materialise cannot overwrite a key a dispatch already sent')
})
// ── The grace window is per definition ─────────────────────────────────────
test('findMissed compares against each definition’s own grace window', async (t) => {
if (needDb(t)) return
const tight = await seedRun({ graceSeconds: 600 })
const generous = await seedRun({ graceSeconds: 3600, scope: 'b' })
const missed = (await pool.query(FIND_MISSED, [later(30 * 60 * 1000)])).map((r) => Number(r.id))
assert.deepEqual(missed, [tight.runId])
assert.ok(!missed.includes(generous.runId), 'inside its own window a run starts late rather than being missed')
})