From cdcc89183311b32ab904923b84e9a953a262b47b Mon Sep 17 00:00:00 2001 From: HugoXK Date: Tue, 17 Nov 2026 01:27:47 +0000 Subject: [PATCH 1/3] feat(schedule): read a run's delivery from the outbox (#544) The console answered `unknown` for every repository because the page said the schedule slice had no delivery outbox. The outbox exists (#544 slice 7) and a decided instant names the job it dispatched, so the delivery fact is readable. - `notification_outbox.job_id` (nullable, indexed) is written by the job-scoped webhook queue, so a scheduled run's send is named by the job that produced it instead of being guessed from the idempotency key. A row written before the column keeps NULL and is never retro-attached to a run. - `scheduleConsole` reads the notifications for the newest decided instant's job: `none` when that job queued nothing, the worst of the queued states when it queued one or more, and `unknown` only when the caller did not read the outbox at all. - The outbox's own `unknown` (a send that may have crossed the boundary and is never resent) prints as `unconfirmed`, so it cannot be read as "nobody looked". The page prints a bilingual label for every state. Red first: `test/scheduleDelivery.test.ts` failed 6/6 at `d3e16b33` (the column and the reader did not exist, the console still answered `unknown`, and the page still printed "no delivery outbox in this slice"); it passes 6/6 with the fix. `npm run check` passed at the tip: 2608/2608 tests, lint, typecheck, build. Written-by: Fledge Platform Dev-1 Docs: docs/architecture.md --- changelog.d/544-schedule-delivery.changed.md | 1 + docs/architecture.md | 19 ++- src/app.ts | 4 + src/db.ts | 38 ++++- src/jobs/service.ts | 13 +- src/schedules/console.ts | 54 +++++- src/views/pages.ts | 19 ++- test/db.test.ts | 2 +- test/notificationOutbox.test.ts | 4 +- test/releaseAnalysis.test.ts | 2 +- test/scheduleDelivery.test.ts | 166 +++++++++++++++++++ test/scheduleLeases.test.ts | 4 +- test/scheduleOccurrences.test.ts | 4 +- test/scheduleSchema.test.ts | 4 +- 14 files changed, 304 insertions(+), 30 deletions(-) create mode 100644 changelog.d/544-schedule-delivery.changed.md create mode 100644 test/scheduleDelivery.test.ts diff --git a/changelog.d/544-schedule-delivery.changed.md b/changelog.d/544-schedule-delivery.changed.md new file mode 100644 index 00000000..14858832 --- /dev/null +++ b/changelog.d/544-schedule-delivery.changed.md @@ -0,0 +1 @@ +The schedule console now reports what actually happened to a run's notifications instead of the fixed `unknown`. A notification a job queued carries that job's id, so the console reads the outbox for the newest decided instant and names the state: sent, queued, sending, retry scheduled, failed or blocked. A run that queued no external notification reads `none`, a send that may have crossed the boundary reads `unconfirmed` and is never resent automatically, and `unknown` now means only that nothing was read or nothing has run. diff --git a/docs/architecture.md b/docs/architecture.md index 5462b3a5..1ebbc1d3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -624,8 +624,13 @@ recorded". `scripts/restore-drill.mjs --status-file` is the writer. schedule, the next run from `nextTime`, the newest decided instant with its state, reason, `missed` and `attempts`, whether a live lease holds it, and the last instant whose job succeeded. A value nobody recorded prints `unknown`: a - schedule with no occurrence row has not run, and this slice has no delivery - outbox, so neither is a zero. The eight facts render through `.schedule-facts`, + schedule with no occurrence row has not run, so it is not a zero. The delivery + fact is read from the outbox (`notification_outbox.job_id`, below) for the job + the newest decided instant dispatched: a job that queued a send reports that + send's state, and a job that queued none prints `none` — a run with nothing to + deliver — rather than the `unknown` of a page that did not look. The outbox's own + `unknown` (a send that may have crossed the external boundary) is printed as + `unconfirmed`, so it is never confused with "nobody read the outbox". The eight facts render through `.schedule-facts`, a two-column grid with muted labels that stacks to one column below 640px, so the console does not fall back to the browser's default definition-list text. `src/schedules/console.ts` is that view model. The @@ -658,9 +663,13 @@ recorded". `scripts/restore-drill.mjs --status-file` is the writer. (`#387`) must move the count inside that claim, or two workers could each spend the last slot. - **The notification outbox** (#544, slice 7): the notifications it covers are - durable rows (`notification_outbox`) instead of a call whose failure lived only - in a log line — the digests, question mails, ops alerts and per-job/PR webhooks - are queued with an idempotency key, so a replayed callback or a second tick + durable rows (`notification_outbox`), and a send that reports on a job carries + its `job_id` (nullable, indexed) so the schedule console can name a run's + delivery without parsing the idempotency key; a row written before the column + existed keeps NULL and is never retro-attached to a run. A notification is a + row instead of a call whose failure lived only in a log line — the digests, + question mails, ops alerts and per-job/PR webhooks are queued with an + idempotency key, so a replayed callback or a second tick keeps one row rather than sending twice. Per-job success/failure mail and the transactional approval, quota, trial and feedback mail still send inline in this slice; they are not queued rows yet. A tick pass sweeps lapsed `sending` diff --git a/src/app.ts b/src/app.ts index be13d527..f4c5d8bf 100644 --- a/src/app.ts +++ b/src/app.ts @@ -1770,6 +1770,10 @@ export async function buildApp(options: BuildOptions): Promise { occurrences: store.listScheduleOccurrences(repo.id, 20), now, jobStatus: (jobId) => store.getJob(jobId)?.status ?? null, + // #544: the delivery fact is the state of the notification the newest run's + // job queued, read from the outbox rather than assumed unknown. A job that + // queued nothing answers empty, which the console prints as `none`. + jobDeliveries: (jobId) => store.notificationsForJob(jobId), // #544 slice 6: the same count function the worker charges with, read over // today's UTC day — the worker charges the *instant's* day, so a catch-up // run can spend a past day while this fact answers "how much of today is diff --git a/src/db.ts b/src/db.ts index 68a02190..f98146cc 100644 --- a/src/db.ts +++ b/src/db.ts @@ -63,7 +63,7 @@ const { DatabaseSync } = require('node:sqlite') as { DatabaseSync: new (path: st // restore check (#652) has to prove a fixture written by an older build still // migrates to exactly this number, and a literal in two places would let the // check and the migration disagree. -export const SCHEMA_VERSION = 47 +export const SCHEMA_VERSION = 48 export type UserStatus = 'onboarding' | 'pending' | 'approved' | 'rejected' export type UserRole = 'user' | 'admin' | 'superadmin' @@ -343,6 +343,10 @@ export interface NotificationOutboxRow { /** The account the email belongs to; null for a webhook. Delivery re-checks * that account and its current notification address before sending. */ user_id: string | null + /** #544: the job whose outcome this notification reports, when it reports one. + * A scheduled run's delivery is read through it, so the console never has to + * parse the idempotency key to guess which send belongs to which run. */ + job_id: string | null payload_json: string /** Reused by a human resend: the same logical notification, not a second one. */ idempotency_key: string @@ -2189,6 +2193,9 @@ CREATE TABLE IF NOT EXISTS notification_outbox ( transport TEXT NOT NULL, destination TEXT NOT NULL, user_id TEXT REFERENCES users(id) ON DELETE CASCADE, + -- #544: the job this send reports, when it reports one. Null for a send that + -- is not about a job (a digest, an ops alert without a job). + job_id TEXT, payload_json TEXT NOT NULL, idempotency_key TEXT NOT NULL, state TEXT NOT NULL, @@ -2521,6 +2528,7 @@ export class Store { this.migrateScheduleMisfireColumns() this.migrateScheduleBudgetColumns() this.migrateSchedulePauseColumns() + this.migrateNotificationJobColumns() this.migrateReleaseColumns() this.migrateIndexes() this.backfillTokenRepoIds() @@ -2566,6 +2574,17 @@ export class Store { if (!columns.includes('paused_at')) this.db.exec('ALTER TABLE schedules ADD COLUMN paused_at INTEGER') } + // #544: the console answers a scheduled run's delivery through the job the + // occurrence dispatched, so an outbox row has to name that job. The column is + // added in place with no backfill: a row written before it cannot be attached + // to a run afterwards, and guessing from the idempotency key would attach the + // wrong one. Such rows answer `none` for an old run, never a fabricated state. + private migrateNotificationJobColumns(): void { + const columns = this.all<{ name: string }>('PRAGMA table_info(notification_outbox)').map((column) => column.name) + if (!columns.includes('job_id')) this.db.exec('ALTER TABLE notification_outbox ADD COLUMN job_id TEXT') + this.run('CREATE INDEX IF NOT EXISTS notification_outbox_job_idx ON notification_outbox(job_id, created_at DESC)') + } + private migrateScheduleOccurrenceColumns(): void { const columns = new Set(this.all<{ name: string }>('PRAGMA table_info(schedule_occurrences)').map((row) => row.name)) const additions: Array<[string, string]> = [ @@ -5876,6 +5895,8 @@ export class Store { transport: NotificationTransport destination: string userId?: string | null + /** #544: the job this send reports, so a scheduled run's delivery is readable. */ + jobId?: string | null payload: unknown idempotencyKey: string now?: number @@ -5883,14 +5904,15 @@ export class Store { const now = input.now ?? Date.now() const result = this.db.prepare( `INSERT INTO notification_outbox - (id, transport, destination, user_id, payload_json, idempotency_key, state, attempts, next_attempt_at, created_at, updated_at) - VALUES (?, ?, ?, ?, ?, ?, 'pending', 0, ?, ?, ?) + (id, transport, destination, user_id, job_id, payload_json, idempotency_key, state, attempts, next_attempt_at, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?, ?, ?) ON CONFLICT(transport, idempotency_key) DO NOTHING`, ).run(...clean([ `ntf_${randomBytes(8).toString('hex')}`, input.transport, input.destination.slice(0, 500), input.userId ?? null, + input.jobId ?? null, JSON.stringify(input.payload), input.idempotencyKey.slice(0, 300), now, @@ -5909,6 +5931,16 @@ export class Store { return this.get('SELECT * FROM notification_outbox WHERE id = ?', id) } + // #544: every send a job produced, newest first. The console asks this for the + // job an occurrence dispatched; an empty answer is a run that queued nothing, + // which is `none` on the page rather than an unread `unknown`. + notificationsForJob(jobId: string): NotificationOutboxRow[] { + return this.all( + 'SELECT * FROM notification_outbox WHERE job_id = ? ORDER BY created_at DESC, rowid DESC', + jobId, + ) + } + // Claiming is one transaction, like the occurrence lease: the due rows are // read and taken under the same lock, so two workers cannot both hold one row. // Only `pending` and a due `retry` are claimable. `unknown` is deliberately diff --git a/src/jobs/service.ts b/src/jobs/service.ts index 9e587573..b16c7f9d 100644 --- a/src/jobs/service.ts +++ b/src/jobs/service.ts @@ -1752,7 +1752,7 @@ export class Jobs { issueUrl: issueUrl, summary: redact(result.summary ?? job.summary ?? ''), error: redact(result.error ?? job.error ?? ''), - }, `job.${job.id}:${result.status}:webhook`) + }, `job.${job.id}:${result.status}:webhook`, job.id) } const repo = this.store.getRepo(job.repo_id) if (repo !== undefined && repo.job_budget_cny > 0) { @@ -1864,7 +1864,7 @@ export class Jobs { jobId, recurrenceKey: record.recurrence.recurrence_key, count: record.recurrence.count, - }, `postmortem.recurring:${record.postmortem.repo_id}:${record.recurrence.recurrence_key}:${record.recurrence.count}`) + }, `postmortem.recurring:${record.postmortem.repo_id}:${record.recurrence.recurrence_key}:${record.recurrence.count}`, jobId) } catch (error) { log.warn('postmortem write failed', { trace: jobId, error: String(error) }) // #666: a postmortem that was not written is a repair job, not a no-op, so @@ -1991,7 +1991,7 @@ export class Jobs { this.store.setSetting(key, nowIso()) this.store.notify(job.user_id, 'job', `${label} 连续 3 个任务失败,自动迭代已暂停;请检查 bridge、GitHub 凭据和模型额度后手动重新开启。`) this.store.audit(job.user_id, 'ops.repeated_failures', `${label}: 3 consecutive failures`) - this.queueWebhook('repo.repeated_failures', { text: `${label}: 3 consecutive job failures; auto-iterate paused`, repoId: job.repo_id, jobId: job.id }, `repo.repeated_failures:${job.repo_id}:${job.id}`) + this.queueWebhook('repo.repeated_failures', { text: `${label}: 3 consecutive job failures; auto-iterate paused`, repoId: job.repo_id, jobId: job.id }, `repo.repeated_failures:${job.repo_id}:${job.id}`, job.id) } private async refreshRepoAccess(repo: RepoRow): Promise { @@ -2826,7 +2826,7 @@ export class Jobs { // webhook call; the settings keys above are what make the pass idempotent. private notifyPlan(job: JobRow, message: string, code: string): void { this.store.notify(job.user_id, 'job', message, code) - this.queueWebhook(code, { text: message, repoId: job.repo_id, jobId: job.id }, `${code}:${job.id}`) + this.queueWebhook(code, { text: message, repoId: job.repo_id, jobId: job.id }, `${code}:${job.id}`, job.id) } private async releaseAllPendingFollowups(): Promise { @@ -3321,12 +3321,15 @@ export class Jobs { // logical event, so a replayed callback or a second tick keeps one row instead // of sending twice. With no webhook configured there is no destination to // record, which is the same no-op the old fire-and-forget call had. - private queueWebhook(event: string, payload: Record, key: string): void { + private queueWebhook(event: string, payload: Record, key: string, jobId?: string | null): void { if (this.config.notifyWebhookUrl === '') return try { this.store.enqueueNotification({ transport: 'webhook', destination: 'webhook', + // #544: a send about a job names it, so a scheduled run's delivery is + // readable without parsing the key. + ...(jobId === undefined ? {} : { jobId }), payload: { event, ...payload }, idempotencyKey: key, }) diff --git a/src/schedules/console.ts b/src/schedules/console.ts index 258ab54d..7b0f34cd 100644 --- a/src/schedules/console.ts +++ b/src/schedules/console.ts @@ -8,13 +8,46 @@ // formula. // // Every value it cannot know is `null`, and the page prints `unknown`. A schedule -// with no occurrence row has not run yet, which is not "zero runs"; a delivery has -// no outbox in this slice, so its result is `unknown` rather than a happy zero. +// with no occurrence row has not run yet, which is not "zero runs"; a run whose +// job queued no notification is `none`, which is also not a happy zero. -import type { ScheduleOccurrenceRow, ScheduleRow } from '../db.js' +import type { NotificationOutboxState, ScheduleOccurrenceRow, ScheduleRow } from '../db.js' import { nextTime, type Schedule } from './next.js' import { scheduleFromRow } from './tick.js' +/** + * What the console can say about the newest run's delivery. `none` is a run that + * queued nothing; `unknown` is a caller that read nothing (or a schedule that + * never ran); `unconfirmed` is an outbox row whose send may have crossed the + * boundary and is never resent automatically. + */ +export type ScheduleDelivery = 'unknown' | 'none' | 'unconfirmed' | 'dead' | 'blocked' | 'retry' | 'sending' | 'pending' | 'sent' + +// One row per state, worst first: a state that needs a person outranks one that +// needs time, which outranks one that is in flight, which outranks one that is +// already done. Several sends for one job (a webhook that is retrying beside one +// that was accepted) must not read as the accepted one. +const DELIVERY_RANK: Record = { + unknown: 0, dead: 1, blocked: 2, retry: 3, sending: 4, pending: 5, sent: 6, +} + +function worstDelivery(states: NotificationOutboxState[]): ScheduleDelivery { + let worst = states[0] ?? 'sent' + for (const state of states) if (DELIVERY_RANK[state] < DELIVERY_RANK[worst]) worst = state + return worst === 'unknown' ? 'unconfirmed' : worst +} + +function deliveryOf( + newest: ScheduleOccurrenceRow | undefined, + read: ((jobId: string) => Array<{ state: NotificationOutboxState }>) | undefined, +): ScheduleDelivery { + if (newest === undefined) return 'unknown' + if (newest.job_id === null) return 'none' + if (read === undefined) return 'unknown' + const rows = read(newest.job_id) + return rows.length === 0 ? 'none' : worstDelivery(rows.map((row) => row.state)) +} + export interface OccurrenceView { id: string logicalTime: number @@ -52,8 +85,14 @@ export interface ScheduleConsoleState { last: OccurrenceView | null /** The newest dispatched instant whose job has succeeded. */ lastSuccess: OccurrenceView | null - /** There is no delivery outbox in this slice, so the result is never known. */ - delivery: 'unknown' + /** + * #544: the delivery of the newest decided instant, read through the job it + * dispatched. `unknown` means nobody read the outbox (or nothing has run); + * `none` means that job queued no notification. The outbox's own `unknown` — + * the send may have crossed the external boundary — is reported as + * `unconfirmed` so it is never mistaken for "nobody looked". + */ + delivery: ScheduleDelivery /** * #544 slice 6: the schedule layer of the run budget. `dailyRuns` null is * unbounded; `runsToday` null is unknown, which the page prints as unknown and @@ -85,6 +124,8 @@ function viewOf(row: ScheduleOccurrenceRow, now: number): OccurrenceView { * a success; an unknown job answers null and is not counted as either. * `runsToday` is `Store.countScheduleDispatchesBetween` over the current UTC day; * a caller that did not read it leaves it out, and the page says unknown. + * `jobDeliveries` resolves the notifications a job queued; a caller that did not + * read the outbox leaves it out, and the page says unknown rather than `none`. */ export function scheduleConsole(input: { repoId: string @@ -93,6 +134,7 @@ export function scheduleConsole(input: { now: number jobStatus: (jobId: string) => string | null runsToday?: number + jobDeliveries?: (jobId: string) => Array<{ state: NotificationOutboxState }> }): ScheduleConsoleState { const { row, now } = input const schedule = row === undefined ? null : scheduleFromRow(row) @@ -116,7 +158,7 @@ export function scheduleConsole(input: { nextAt: schedule === null ? null : nextTime(schedule, now), last: occurrences[0] ?? null, lastSuccess, - delivery: 'unknown', + delivery: deliveryOf(input.occurrences[0], input.jobDeliveries), budget: { dailyRuns, runsToday, diff --git a/src/views/pages.ts b/src/views/pages.ts index f61540a2..d4f1f2e8 100644 --- a/src/views/pages.ts +++ b/src/views/pages.ts @@ -4865,6 +4865,23 @@ export function scheduleConsolePage(input: { : last.leaseHeld ? t(`持有中,至 ${shown(last.leaseExpiresAt)}`, `held until ${shown(last.leaseExpiresAt)}`) : t(`未被持有(尝试 ${last.attempts} 次)`, `not held (${last.attempts} attempt${last.attempts === 1 ? '' : 's'})`) + // #544: the delivery is the state of the notification the newest run's job + // queued. `unknown` means nothing was read or nothing has run; the outbox's own + // unknown is `unconfirmed`, because a send that may have crossed the boundary is + // a different fact from a page that did not look. + const deliveryLine = ((): string => { + switch (state.delivery) { + case 'none': return t('未排队(这次运行没有外部通知)', 'not queued (this run queued no external notification)') + case 'sent': return t('已发送', 'sent') + case 'pending': return t('排队中', 'queued') + case 'sending': return t('发送中', 'sending') + case 'retry': return t('等待重试', 'retry scheduled') + case 'dead': return t('发送失败', 'failed') + case 'blocked': return t('被阻止(需要人处理)', 'blocked (a person must fix it)') + case 'unconfirmed': return t('未确认(不会自动重发)', 'unconfirmed (never resent automatically)') + default: return t('未知(没有读取投递箱,或还没有运行)', 'unknown (nothing read, or nothing has run yet)') + } + })() const occurrenceRows = state.occurrences.length === 0 ? `${escapeHtml(t('还没有决定过任何时刻。', 'No instant has been decided yet.'))}` : state.occurrences.map((occurrence) => ` @@ -4911,7 +4928,7 @@ export function scheduleConsolePage(input: {
${escapeHtml(t('上次成功', 'Last success'))}
${escapeHtml(shown(state.lastSuccess?.logicalTime ?? null))}
${escapeHtml(t('最后决定', 'Last decision'))}
${lastLine}
${escapeHtml(t('租约', 'Lease'))}
${leaseLine}
-
${escapeHtml(t('投递结果', 'Delivery'))}
${escapeHtml(t('unknown(这一片还没有投递箱)', 'unknown (no delivery outbox in this slice)'))}
+
${escapeHtml(t('投递结果', 'Delivery'))}
${escapeHtml(deliveryLine)}
${escapeHtml(t('有效期', 'Window'))}
${window}
${escapeHtml(t('时序版本', 'Timing revision'))}
${escapeHtml(state.timingRevision === null ? t('unknown', 'unknown') : String(state.timingRevision))} · ${escapeHtml(state.misfire === null ? t('unknown', 'unknown') : state.misfire)}
${escapeHtml(t('宽限', 'Grace'))}
${escapeHtml(state.graceMs === null ? t('不限(默认)', 'unbounded (default)') : t(`${Math.round(state.graceMs / 60_000)} 分钟`, `${Math.round(state.graceMs / 60_000)} minutes`))}
diff --git a/test/db.test.ts b/test/db.test.ts index 83d9a78a..ca8bd3c2 100644 --- a/test/db.test.ts +++ b/test/db.test.ts @@ -153,7 +153,7 @@ test('the role backfill runs once and future schema versions are refused', () => assert.notEqual(reopened.getRepo(repo.id)?.role_checked_at, null) // The job-attempts table moved the build's schema to 46 and the release run // analysis to 47, so the first refused version is 48. - reopened.db.exec('PRAGMA user_version = 48;') + reopened.db.exec('PRAGMA user_version = 49;') reopened.close() assert.throws(() => new Store(path), /newer than this build/) diff --git a/test/notificationOutbox.test.ts b/test/notificationOutbox.test.ts index 4a631951..f8192ec5 100644 --- a/test/notificationOutbox.test.ts +++ b/test/notificationOutbox.test.ts @@ -42,11 +42,11 @@ function row(id: string): NotificationOutboxRow { return { id, payload_json: JSON.stringify({ event: 'ops.alert', text: 'disk almost full' }) } as NotificationOutboxRow } -test('the outbox table and its state machine exist at user_version 47', () => { +test('the outbox table and its state machine exist at user_version 48', () => { const store = new Store(':memory:') try { const version = store.get<{ user_version: number }>('PRAGMA user_version') - assert.equal(Number(version?.user_version), 47, 'job attempts move the refusal boundary to 46 and the release run analysis to 47') + assert.equal(Number(version?.user_version), 48, 'job attempts move the refusal boundary to 46, the release run analysis to 47, and the notification job link to 48') const columns = store.all<{ name: string }>('PRAGMA table_info(notification_outbox)').map((column) => column.name) for (const column of ['transport', 'destination', 'payload_json', 'idempotency_key', 'state', 'attempts', 'next_attempt_at', 'lease_token', 'lease_expires_at', 'last_error', 'sent_at']) { assert.equal(columns.includes(column), true, `notification_outbox must have ${column}`) diff --git a/test/releaseAnalysis.test.ts b/test/releaseAnalysis.test.ts index bbddb5bc..1e503b2a 100644 --- a/test/releaseAnalysis.test.ts +++ b/test/releaseAnalysis.test.ts @@ -431,7 +431,7 @@ test('a database written at schema 46 gains the analysis column and keeps its re const upgraded = new Store(path) const version = upgraded.get<{ user_version: number }>('PRAGMA user_version')?.user_version - assert.equal(version, 47) + assert.equal(version, 48, 'the 46 shape migrates through the release column and the notification job link to the current version') const columns = upgraded.all<{ name: string }>('PRAGMA table_info(repo_releases)').map((row) => row.name) assert.ok(columns.includes('analysis_json'), 'the upgrade adds the column') const kept = upgraded.releaseById(release.id) diff --git a/test/scheduleDelivery.test.ts b/test/scheduleDelivery.test.ts new file mode 100644 index 00000000..a4d1f66d --- /dev/null +++ b/test/scheduleDelivery.test.ts @@ -0,0 +1,166 @@ +import test from 'node:test' +import assert from 'node:assert/strict' +import { buildApp, type BuiltApp } from '../src/app.js' +import { Store, type NotificationOutboxState } from '../src/db.js' +import { MockRunner } from '../src/jobs/mock.js' +import { scheduleConsole } from '../src/schedules/console.js' +import { scheduleConsolePage } from '../src/views/pages.js' +import { makeUser, MemoryMailer, sessionFor, testConfig } from './helpers.js' + +// #544, the delivery fact: the console used to answer `unknown` for every +// repository because the page said no outbox existed. The outbox exists (#544 +// slice 7) and a dispatched occurrence names its job, so the honest answer is +// the state of the notification that job queued — `none` when it queued +// nothing, and `unknown` only when nobody read the outbox at all. + +const HOUR = 3_600_000 +const NOW = Date.parse('2026-11-16T00:00:00Z') + +function harness(name: string): { store: Store; userId: string; repoId: string } { + const store = new Store(':memory:') + const user = makeUser(store, { login: `${name}-owner`, status: 'approved' }) + const repo = store.createRepo({ + id: `repo_${name}`, userId: user.id, owner: 'o', name, + defaultBranch: 'main', tokenEnc: 'x', permission: 'admin', + repoRole: 'maintainer', goal: 'fix bugs', autoIterate: true, intervalMinutes: 1440, + }) + return { store, userId: user.id, repoId: repo.id } +} + +function dispatched(store: Store, repoId: string, jobId: string): ReturnType { + const row = store.saveSchedule({ id: `sch_${repoId}`, repoId, kind: 'interval', everyMs: HOUR }) + const logicalTime = Math.floor(NOW / HOUR) * HOUR + store.claimScheduleOccurrence({ id: `occ_${repoId}`, scheduleId: row.id, repoId, logicalTime, timingRevision: row.timing_revision, leaseToken: 'tok', leaseMs: HOUR, now: NOW }) + store.settleScheduleOccurrence({ scheduleId: row.id, logicalTime, timingRevision: row.timing_revision, leaseToken: 'tok', state: 'dispatched', jobId, dispatchedAt: NOW, lagMs: 0, now: NOW }) + return row +} + +const noJobs = (): string | null => null +const fake = (states: NotificationOutboxState[]) => (): Array<{ state: NotificationOutboxState }> => states.map((state) => ({ state })) + +// -- the link between a job and the notification it queued ------------------ + +test('an outbox row remembers the job it belongs to, and a job with no row answers empty', () => { + const { store, userId, repoId } = harness('delivery-link') + try { + const job = store.createJob({ id: 'job_linked', repoId, userId, trigger: 'schedule', goal: 'g', callbackHash: 'cb_linked', platformTokenHash: '' }) + const queued = store.enqueueNotification({ + transport: 'webhook', destination: 'webhook', payload: { event: 'job.succeeded', jobId: job.id }, + idempotencyKey: `job.${job.id}:succeeded:webhook`, jobId: job.id, now: NOW, + }) + assert.equal(queued.row.job_id, job.id, 'the row names the job, so the console never guesses from a key string') + assert.deepEqual(store.notificationsForJob(job.id).map((row) => row.state), ['pending']) + assert.deepEqual(store.notificationsForJob('job_nobody'), [], 'a job that queued nothing answers empty, not every row') + } finally { store.close() } +}) + +// -- the console's answer --------------------------------------------------- + +test('the console reports the delivery state of the newest dispatched run', () => { + const { store, repoId, userId } = harness('delivery-sent') + try { + const job = store.createJob({ id: 'job_sent', repoId, userId, trigger: 'schedule', goal: 'g', callbackHash: 'cb_sent', platformTokenHash: '' }) + const row = dispatched(store, repoId, job.id) + const state = scheduleConsole({ + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: noJobs, + jobDeliveries: fake(['sent']), + }) + assert.equal(state.delivery, 'sent', 'a notification the transport accepted reads sent, not unknown') + } finally { store.close() } +}) + +test('a run that queued no notification reads none, and no run at all stays unknown', () => { + const { store, repoId, userId } = harness('delivery-none') + try { + const job = store.createJob({ id: 'job_none', repoId, userId, trigger: 'schedule', goal: 'g', callbackHash: 'cb_none', platformTokenHash: '' }) + const row = dispatched(store, repoId, job.id) + const ran = scheduleConsole({ + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: noJobs, + jobDeliveries: fake([]), + }) + assert.equal(ran.delivery, 'none', 'a job that queued nothing is none, not unknown') + + const empty = scheduleConsole({ repoId, row, occurrences: [], now: NOW, jobStatus: noJobs, jobDeliveries: fake([]) }) + assert.equal(empty.delivery, 'unknown', 'nothing has run, so nothing is known') + + const skipped = scheduleConsole({ repoId, row, occurrences: [{ ...store.listScheduleOccurrences(repoId, 10)[0]!, state: 'skipped', job_id: null }], now: NOW, jobStatus: noJobs, jobDeliveries: fake([]) }) + assert.equal(skipped.delivery, 'none', 'a skipped instant dispatched no job, so it queued nothing rather than unknown') + } finally { store.close() } +}) + +test('several notifications read as the worst of them, because one needs attention', () => { + const { store, repoId, userId } = harness('delivery-worst') + try { + const job = store.createJob({ id: 'job_worst', repoId, userId, trigger: 'schedule', goal: 'g', callbackHash: 'cb_worst', platformTokenHash: '' }) + const row = dispatched(store, repoId, job.id) + const state = (states: NotificationOutboxState[]) => scheduleConsole({ + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: noJobs, + jobDeliveries: fake(states), + }).delivery + assert.equal(state(['sent', 'retry']), 'retry', 'a retry behind a sent row is still visible') + assert.equal(state(['dead', 'unknown']), 'unconfirmed', 'an unconfirmed send outranks a definite refusal') + assert.equal(state(['retry', 'sending']), 'retry') + assert.equal(state(['sent', 'sent']), 'sent') + } finally { store.close() } +}) + +// -- the page --------------------------------------------------------------- + +test('the page prints the delivery it knows instead of "no delivery outbox in this slice"', () => { + const { store, repoId, userId } = harness('delivery-page') + try { + const job = store.createJob({ id: 'job_page', repoId, userId, trigger: 'schedule', goal: 'g', callbackHash: 'cb_page', platformTokenHash: '' }) + const row = dispatched(store, repoId, job.id) + const user = store.userById(userId)! + const viewer = { user, csrfToken: 'csrf_test' } + const page = (deliveries: Array<{ state: NotificationOutboxState }>) => scheduleConsolePage({ + config: testConfig(), locale: 'en', viewer, repo: store.getRepo(repoId)!, state: scheduleConsole({ + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: noJobs, + jobDeliveries: () => deliveries, + }), + form: { cron: '', every: '', timezone: '', startAt: '', endAt: '', misfire: 'skip', grace: '', dailyRuns: '' }, + runNowKey: 'cmd_page', + } as never) + + const sent = page([{ state: 'sent' }]) + assert.match(sent, /data-delivery="sent"/, 'the state is machine-readable') + assert.match(sent, />sent { + const store = new Store(':memory:') + const built: BuiltApp = await buildApp({ config: testConfig(), store, mailer: new MemoryMailer(), runner: new MockRunner(), startScheduler: false }) + try { + const user = makeUser(store, { login: 'delivery-route-owner', status: 'approved' }) + const repo = store.createRepo({ + id: 'repo_delivery_route', userId: user.id, owner: 'o', name: 'delivery-route', + defaultBranch: 'main', tokenEnc: 'x', permission: 'admin', + repoRole: 'maintainer', goal: 'fix bugs', autoIterate: true, intervalMinutes: 1440, + }) + const job = store.createJob({ id: 'job_route', repoId: repo.id, userId: user.id, trigger: 'schedule', goal: 'g', callbackHash: 'cb_route', platformTokenHash: '' }) + dispatched(store, repo.id, job.id) + store.enqueueNotification({ + transport: 'webhook', destination: 'webhook', payload: { event: 'job.succeeded', jobId: job.id }, + idempotencyKey: `job.${job.id}:succeeded:webhook`, jobId: job.id, now: NOW, + }) + const session = sessionFor(built, user) + const response = await built.app.inject({ method: 'GET', url: `/repos/${repo.id}/schedule`, headers: { cookie: session.cookie } }) + assert.equal(response.statusCode, 200) + assert.match(response.body, /data-delivery="pending"/, 'the queued notification is visible on the console') + } finally { await built.close() } +}) diff --git a/test/scheduleLeases.test.ts b/test/scheduleLeases.test.ts index 7e2a5019..2209f6ee 100644 --- a/test/scheduleLeases.test.ts +++ b/test/scheduleLeases.test.ts @@ -45,11 +45,11 @@ function claim(h: { store: Store; repoId: string; scheduleId: string }, token: s }) } -test('the occurrence row carries attempts and a lease, at user_version 47', () => { +test('the occurrence row carries attempts and a lease, at user_version 48', () => { const store = new Store(':memory:') try { const version = store.get<{ user_version: number }>('PRAGMA user_version') - assert.equal(Number(version?.user_version), 47, 'job attempts move the refusal boundary to 46 and the release run analysis to 47') + assert.equal(Number(version?.user_version), 48, 'job attempts move the refusal boundary to 46, the release run analysis to 47, and the notification job link to 48') const columns = store.all<{ name: string }>('PRAGMA table_info(schedule_occurrences)').map((column) => column.name) for (const column of ['attempts', 'lease_token', 'lease_expires_at']) { diff --git a/test/scheduleOccurrences.test.ts b/test/scheduleOccurrences.test.ts index 8b98e274..90862b56 100644 --- a/test/scheduleOccurrences.test.ts +++ b/test/scheduleOccurrences.test.ts @@ -56,11 +56,11 @@ function audits(store: Store, action: string): string[] { // -- the table ------------------------------------------------------------- -test('the occurrence table is part of the schema at user_version 47', () => { +test('the occurrence table is part of the schema at user_version 48', () => { const store = new Store(':memory:') try { const version = store.get<{ user_version: number }>('PRAGMA user_version') - assert.equal(Number(version?.user_version), 47, 'job attempts move the refusal boundary to 46 and the release run analysis to 47') + assert.equal(Number(version?.user_version), 48, 'job attempts move the refusal boundary to 46, the release run analysis to 47, and the notification job link to 48') const table = store.get<{ name: string }>("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'schedule_occurrences'") assert.equal(table?.name, 'schedule_occurrences') diff --git a/test/scheduleSchema.test.ts b/test/scheduleSchema.test.ts index fd82ad81..806e5ea7 100644 --- a/test/scheduleSchema.test.ts +++ b/test/scheduleSchema.test.ts @@ -7,11 +7,11 @@ import { makeUser } from './helpers.js' // the version boundary, the columns the planner reads, and the one-row-per- // repository rule the tick relies on. -test('the schedule table is part of the schema at user_version 47', () => { +test('the schedule table is part of the schema at user_version 48', () => { const store = new Store(':memory:') try { const version = store.get<{ user_version: number }>('PRAGMA user_version') - assert.equal(Number(version?.user_version), 47, 'each schema change moves the refusal boundary: 43 Lead delivery, 44 notification outbox, 45 retired provider model, 46 job attempts, 47 release run analysis') + assert.equal(Number(version?.user_version), 48, 'each schema change moves the refusal boundary: 43 Lead delivery, 44 notification outbox, 45 retired provider model, 46 job attempts, 47 release run analysis, 48 notification job link') const table = store.get<{ name: string }>("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'schedules'") assert.equal(table?.name, 'schedules') From ca2614d6f89645d8adeafc423e0b6930a3a386ec Mon Sep 17 00:00:00 2001 From: Day Dreamer <87640074+HugoXK@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:46:32 +0000 Subject: [PATCH 2/3] fix(schedule): answer unknown while the run's job has not finished (#959 review) A job queues its notifications only when it ends (succeeded/failed), so a queued or running job has no outbox rows yet. The console read that empty set as a definite none and printed 'not queued (this run queued no external notification)' until the run finished, which #544's Expected forbids: a missing value is 'unknown', never zero. deliveryOf now takes the jobStatus scheduleConsole already receives and answers unknown while the job is queued/running or its row is missing; none only for a terminal job whose outbox read is empty. The page's unknown label says the run may not have finished, and the dead-before-blocked rank order states its reason. --- changelog.d/544-schedule-delivery.changed.md | 2 +- docs/architecture.md | 8 +++- src/schedules/console.ts | 39 +++++++++++----- src/views/pages.ts | 9 ++-- test/scheduleDelivery.test.ts | 47 ++++++++++++++++---- 5 files changed, 79 insertions(+), 26 deletions(-) diff --git a/changelog.d/544-schedule-delivery.changed.md b/changelog.d/544-schedule-delivery.changed.md index 14858832..a5d85f5f 100644 --- a/changelog.d/544-schedule-delivery.changed.md +++ b/changelog.d/544-schedule-delivery.changed.md @@ -1 +1 @@ -The schedule console now reports what actually happened to a run's notifications instead of the fixed `unknown`. A notification a job queued carries that job's id, so the console reads the outbox for the newest decided instant and names the state: sent, queued, sending, retry scheduled, failed or blocked. A run that queued no external notification reads `none`, a send that may have crossed the boundary reads `unconfirmed` and is never resent automatically, and `unknown` now means only that nothing was read or nothing has run. +The schedule console now reports what actually happened to a run's notifications instead of the fixed `unknown`. A notification a job queued carries that job's id, so the console reads the outbox for the newest decided instant and names the state: sent, queued, sending, retry scheduled, failed or blocked. A finished run that queued no external notification reads `none`, a send that may have crossed the boundary reads `unconfirmed` and is never resent automatically, and a run whose job is still running reads `unknown` — a job queues its notifications only when it ends, so a missing value is never printed as a definite none. diff --git a/docs/architecture.md b/docs/architecture.md index 1ebbc1d3..055b5b31 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -627,8 +627,12 @@ recorded". `scripts/restore-drill.mjs --status-file` is the writer. schedule with no occurrence row has not run, so it is not a zero. The delivery fact is read from the outbox (`notification_outbox.job_id`, below) for the job the newest decided instant dispatched: a job that queued a send reports that - send's state, and a job that queued none prints `none` — a run with nothing to - deliver — rather than the `unknown` of a page that did not look. The outbox's own + send's state, and a finished job that queued none prints `none` — a run with + nothing to deliver — rather than the `unknown` of a page that did not look. A + job queues its notifications only when it ends (`succeeded`/`failed`), so a + run whose job is still queued or running prints `unknown` too: the empty read + is a value nobody knows yet, and a missing value is never printed as a + definite none. The outbox's own `unknown` (a send that may have crossed the external boundary) is printed as `unconfirmed`, so it is never confused with "nobody read the outbox". The eight facts render through `.schedule-facts`, a two-column grid with muted labels that stacks to one column below 640px, so diff --git a/src/schedules/console.ts b/src/schedules/console.ts index 7b0f34cd..341e0b50 100644 --- a/src/schedules/console.ts +++ b/src/schedules/console.ts @@ -9,24 +9,31 @@ // // Every value it cannot know is `null`, and the page prints `unknown`. A schedule // with no occurrence row has not run yet, which is not "zero runs"; a run whose -// job queued no notification is `none`, which is also not a happy zero. +// job has finished and queued no notification is `none`, which is also not a +// happy zero; a run whose job is still queued or running is `unknown`, because +// a job queues its notifications only when it ends. import type { NotificationOutboxState, ScheduleOccurrenceRow, ScheduleRow } from '../db.js' import { nextTime, type Schedule } from './next.js' import { scheduleFromRow } from './tick.js' /** - * What the console can say about the newest run's delivery. `none` is a run that - * queued nothing; `unknown` is a caller that read nothing (or a schedule that - * never ran); `unconfirmed` is an outbox row whose send may have crossed the - * boundary and is never resent automatically. + * What the console can say about the newest run's delivery. `none` is a finished + * run that queued nothing; `unknown` is a caller that read nothing, a schedule + * that never ran, or a run whose job has not finished; `unconfirmed` is an + * outbox row whose send may have crossed the boundary and is never resent + * automatically. */ export type ScheduleDelivery = 'unknown' | 'none' | 'unconfirmed' | 'dead' | 'blocked' | 'retry' | 'sending' | 'pending' | 'sent' // One row per state, worst first: a state that needs a person outranks one that // needs time, which outranks one that is in flight, which outranks one that is // already done. Several sends for one job (a webhook that is retrying beside one -// that was accepted) must not read as the accepted one. +// that was accepted) must not read as the accepted one. `dead` outranks +// `blocked` even though both need a person: a dead send spent its retries +// against a destination that exists and is lost without one, while a blocked +// send never left — its destination was never reachable — and the row is still +// intact for a person to fix and resend. const DELIVERY_RANK: Record = { unknown: 0, dead: 1, blocked: 2, retry: 3, sending: 4, pending: 5, sent: 6, } @@ -39,11 +46,19 @@ function worstDelivery(states: NotificationOutboxState[]): ScheduleDelivery { function deliveryOf( newest: ScheduleOccurrenceRow | undefined, + jobStatus: (jobId: string) => string | null, read: ((jobId: string) => Array<{ state: NotificationOutboxState }>) | undefined, ): ScheduleDelivery { if (newest === undefined) return 'unknown' if (newest.job_id === null) return 'none' if (read === undefined) return 'unknown' + // A job queues its notifications only when it ends (`succeeded`/`failed`), + // so while it is queued or running the empty outbox read is a value nobody + // knows yet — printing `none` there would deny a notification the run may + // still queue. A job the store cannot find is unknown for the same reason: + // the console cannot prove it will never queue one. + const status = jobStatus(newest.job_id) + if (status === null || status === 'queued' || status === 'running') return 'unknown' const rows = read(newest.job_id) return rows.length === 0 ? 'none' : worstDelivery(rows.map((row) => row.state)) } @@ -87,9 +102,10 @@ export interface ScheduleConsoleState { lastSuccess: OccurrenceView | null /** * #544: the delivery of the newest decided instant, read through the job it - * dispatched. `unknown` means nobody read the outbox (or nothing has run); - * `none` means that job queued no notification. The outbox's own `unknown` — - * the send may have crossed the external boundary — is reported as + * dispatched. `unknown` means nobody read the outbox, nothing has run, or the + * run's job has not finished — a job queues its notifications only when it + * ends; `none` means a finished job queued no notification. The outbox's own + * `unknown` — the send may have crossed the external boundary — is reported as * `unconfirmed` so it is never mistaken for "nobody looked". */ delivery: ScheduleDelivery @@ -126,6 +142,9 @@ function viewOf(row: ScheduleOccurrenceRow, now: number): OccurrenceView { * a caller that did not read it leaves it out, and the page says unknown. * `jobDeliveries` resolves the notifications a job queued; a caller that did not * read the outbox leaves it out, and the page says unknown rather than `none`. + * `jobStatus` decides the same line: a job still queued or running has not + * queued anything yet, so its empty read is unknown, and only a terminal job + * whose read is empty answers `none`. */ export function scheduleConsole(input: { repoId: string @@ -158,7 +177,7 @@ export function scheduleConsole(input: { nextAt: schedule === null ? null : nextTime(schedule, now), last: occurrences[0] ?? null, lastSuccess, - delivery: deliveryOf(input.occurrences[0], input.jobDeliveries), + delivery: deliveryOf(input.occurrences[0], input.jobStatus, input.jobDeliveries), budget: { dailyRuns, runsToday, diff --git a/src/views/pages.ts b/src/views/pages.ts index d4f1f2e8..b09fc59b 100644 --- a/src/views/pages.ts +++ b/src/views/pages.ts @@ -4866,9 +4866,10 @@ export function scheduleConsolePage(input: { ? t(`持有中,至 ${shown(last.leaseExpiresAt)}`, `held until ${shown(last.leaseExpiresAt)}`) : t(`未被持有(尝试 ${last.attempts} 次)`, `not held (${last.attempts} attempt${last.attempts === 1 ? '' : 's'})`) // #544: the delivery is the state of the notification the newest run's job - // queued. `unknown` means nothing was read or nothing has run; the outbox's own - // unknown is `unconfirmed`, because a send that may have crossed the boundary is - // a different fact from a page that did not look. + // queued. `unknown` means nothing was read, nothing has run, or the run's job + // has not finished (a job queues its notifications only when it ends); the + // outbox's own unknown is `unconfirmed`, because a send that may have crossed + // the boundary is a different fact from a page that did not look. const deliveryLine = ((): string => { switch (state.delivery) { case 'none': return t('未排队(这次运行没有外部通知)', 'not queued (this run queued no external notification)') @@ -4879,7 +4880,7 @@ export function scheduleConsolePage(input: { case 'dead': return t('发送失败', 'failed') case 'blocked': return t('被阻止(需要人处理)', 'blocked (a person must fix it)') case 'unconfirmed': return t('未确认(不会自动重发)', 'unconfirmed (never resent automatically)') - default: return t('未知(没有读取投递箱,或还没有运行)', 'unknown (nothing read, or nothing has run yet)') + default: return t('未知(没有读取、还没有运行,或运行未结束)', 'unknown (nothing read, nothing has run, or the run has not finished)') } })() const occurrenceRows = state.occurrences.length === 0 diff --git a/test/scheduleDelivery.test.ts b/test/scheduleDelivery.test.ts index a4d1f66d..0c662a96 100644 --- a/test/scheduleDelivery.test.ts +++ b/test/scheduleDelivery.test.ts @@ -10,8 +10,11 @@ import { makeUser, MemoryMailer, sessionFor, testConfig } from './helpers.js' // #544, the delivery fact: the console used to answer `unknown` for every // repository because the page said no outbox existed. The outbox exists (#544 // slice 7) and a dispatched occurrence names its job, so the honest answer is -// the state of the notification that job queued — `none` when it queued -// nothing, and `unknown` only when nobody read the outbox at all. +// the state of the notification that job queued — `none` when a finished job +// queued nothing, and `unknown` while nobody read the outbox, nothing has run, +// or the run's job has not finished: a job queues its notifications only when +// it ends (`succeeded`/`failed`), so a queued or running job has no rows yet +// and a missing value must never print as a definite none. const HOUR = 3_600_000 const NOW = Date.parse('2026-11-16T00:00:00Z') @@ -36,6 +39,8 @@ function dispatched(store: Store, repoId: string, jobId: string): ReturnType null +const doneJobs = (): string | null => 'succeeded' +const jobAt = (status: string): (() => string | null) => () => status const fake = (states: NotificationOutboxState[]) => (): Array<{ state: NotificationOutboxState }> => states.map((state) => ({ state })) // -- the link between a job and the notification it queued ------------------ @@ -62,23 +67,39 @@ test('the console reports the delivery state of the newest dispatched run', () = const job = store.createJob({ id: 'job_sent', repoId, userId, trigger: 'schedule', goal: 'g', callbackHash: 'cb_sent', platformTokenHash: '' }) const row = dispatched(store, repoId, job.id) const state = scheduleConsole({ - repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: noJobs, + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: doneJobs, jobDeliveries: fake(['sent']), }) assert.equal(state.delivery, 'sent', 'a notification the transport accepted reads sent, not unknown') } finally { store.close() } }) -test('a run that queued no notification reads none, and no run at all stays unknown', () => { +test('a run whose job has not finished reads unknown; a finished job that queued nothing reads none', () => { const { store, repoId, userId } = harness('delivery-none') try { const job = store.createJob({ id: 'job_none', repoId, userId, trigger: 'schedule', goal: 'g', callbackHash: 'cb_none', platformTokenHash: '' }) const row = dispatched(store, repoId, job.id) + // A job queues its notifications only when it ends, so while it is queued + // or running the empty outbox read is a value nobody knows yet — printing + // `none` there would deny a notification the run may still queue. + const at = (status: string) => scheduleConsole({ + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: jobAt(status), + jobDeliveries: fake([]), + }).delivery + assert.equal(at('queued'), 'unknown', 'a queued job has not queued its notifications yet') + assert.equal(at('running'), 'unknown', 'a running job may still queue a notification, so none would be a lie') + const ran = scheduleConsole({ + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: doneJobs, + jobDeliveries: fake([]), + }) + assert.equal(ran.delivery, 'none', 'a finished job that queued nothing is none, not unknown') + + const lost = scheduleConsole({ repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: noJobs, jobDeliveries: fake([]), }) - assert.equal(ran.delivery, 'none', 'a job that queued nothing is none, not unknown') + assert.equal(lost.delivery, 'unknown', 'a job the store cannot find is unknown, not none') const empty = scheduleConsole({ repoId, row, occurrences: [], now: NOW, jobStatus: noJobs, jobDeliveries: fake([]) }) assert.equal(empty.delivery, 'unknown', 'nothing has run, so nothing is known') @@ -94,7 +115,7 @@ test('several notifications read as the worst of them, because one needs attenti const job = store.createJob({ id: 'job_worst', repoId, userId, trigger: 'schedule', goal: 'g', callbackHash: 'cb_worst', platformTokenHash: '' }) const row = dispatched(store, repoId, job.id) const state = (states: NotificationOutboxState[]) => scheduleConsole({ - repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: noJobs, + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: doneJobs, jobDeliveries: fake(states), }).delivery assert.equal(state(['sent', 'retry']), 'retry', 'a retry behind a sent row is still visible') @@ -113,9 +134,9 @@ test('the page prints the delivery it knows instead of "no delivery outbox in th const row = dispatched(store, repoId, job.id) const user = store.userById(userId)! const viewer = { user, csrfToken: 'csrf_test' } - const page = (deliveries: Array<{ state: NotificationOutboxState }>) => scheduleConsolePage({ + const page = (deliveries: Array<{ state: NotificationOutboxState }>, jobStatus: () => string | null = doneJobs) => scheduleConsolePage({ config: testConfig(), locale: 'en', viewer, repo: store.getRepo(repoId)!, state: scheduleConsole({ - repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus: noJobs, + repoId, row, occurrences: store.listScheduleOccurrences(repoId, 10), now: NOW, jobStatus, jobDeliveries: () => deliveries, }), form: { cron: '', every: '', timezone: '', startAt: '', endAt: '', misfire: 'skip', grace: '', dailyRuns: '' }, @@ -131,6 +152,10 @@ test('the page prints the delivery it knows instead of "no delivery outbox in th assert.match(none, /data-delivery="none"/) assert.match(none, /not queued/, 'a run that queued nothing says so') + const running = page([], jobAt('running')) + assert.match(running, /data-delivery="unknown"/, 'a run whose job has not finished reads unknown') + assert.doesNotMatch(running, /not queued/, 'the page must not deny a notification the run may still queue') + const retry = page([{ state: 'sent' }, { state: 'retry' }]) assert.match(retry, /data-delivery="retry"/) @@ -154,6 +179,10 @@ test('the schedule console route reads the outbox for the run it shows', async ( }) const job = store.createJob({ id: 'job_route', repoId: repo.id, userId: user.id, trigger: 'schedule', goal: 'g', callbackHash: 'cb_route', platformTokenHash: '' }) dispatched(store, repo.id, job.id) + // The route reads the store, and a job queues its notifications only when + // it ends, so the fixture finishes the job before seeding the webhook row — + // the real order at the finish path this page observes. + store.updateJob(job.id, { status: 'succeeded' }) store.enqueueNotification({ transport: 'webhook', destination: 'webhook', payload: { event: 'job.succeeded', jobId: job.id }, idempotencyKey: `job.${job.id}:succeeded:webhook`, jobId: job.id, now: NOW, @@ -161,6 +190,6 @@ test('the schedule console route reads the outbox for the run it shows', async ( const session = sessionFor(built, user) const response = await built.app.inject({ method: 'GET', url: `/repos/${repo.id}/schedule`, headers: { cookie: session.cookie } }) assert.equal(response.statusCode, 200) - assert.match(response.body, /data-delivery="pending"/, 'the queued notification is visible on the console') + assert.match(response.body, /data-delivery="pending"/, 'the finished run queued a webhook and the console reads it') } finally { await built.close() } }) From adee1a782e178c1a33f14776dfd5f21d48997a26 Mon Sep 17 00:00:00 2001 From: HugoXK Date: Wed, 18 Nov 2026 00:49:37 +0000 Subject: [PATCH 3/3] fix(schedule): answer unknown for an instant that has not decided (#959 review) --- docs/architecture.md | 5 ++++- src/schedules/console.ts | 9 ++++++++- test/scheduleDelivery.test.ts | 33 +++++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 2 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 055b5b31..d02e9e02 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -632,7 +632,10 @@ recorded". `scripts/restore-drill.mjs --status-file` is the writer. job queues its notifications only when it ends (`succeeded`/`failed`), so a run whose job is still queued or running prints `unknown` too: the empty read is a value nobody knows yet, and a missing value is never printed as a - definite none. The outbox's own + definite none. Only a decided instant answers: `skipped` queued nothing by + definition, while `claimed` (a worker holds it, `job_id` still NULL until the + job starts) and `expired` (a lease that lapsed before anyone settled it) have + not decided yet and print `unknown`. The outbox's own `unknown` (a send that may have crossed the external boundary) is printed as `unconfirmed`, so it is never confused with "nobody read the outbox". The eight facts render through `.schedule-facts`, a two-column grid with muted labels that stacks to one column below 640px, so diff --git a/src/schedules/console.ts b/src/schedules/console.ts index 341e0b50..b9c401ee 100644 --- a/src/schedules/console.ts +++ b/src/schedules/console.ts @@ -50,7 +50,14 @@ function deliveryOf( read: ((jobId: string) => Array<{ state: NotificationOutboxState }>) | undefined, ): ScheduleDelivery { if (newest === undefined) return 'unknown' - if (newest.job_id === null) return 'none' + // Only a decided instant can answer. `dispatched` names the job whose + // notifications are the delivery fact, and `skipped` provably queued none. + // A `claimed` row keeps its `job_id` NULL until the worker starts the job, + // and an `expired` row is a lease that lapsed before anyone settled it, so + // neither has decided yet and `none` would be a lie the page prints as + // "not queued". + if (newest.state !== 'dispatched' && newest.state !== 'skipped') return 'unknown' + if (newest.job_id === null) return newest.state === 'skipped' ? 'none' : 'unknown' if (read === undefined) return 'unknown' // A job queues its notifications only when it ends (`succeeded`/`failed`), // so while it is queued or running the empty outbox read is a value nobody diff --git a/test/scheduleDelivery.test.ts b/test/scheduleDelivery.test.ts index 0c662a96..1b33d356 100644 --- a/test/scheduleDelivery.test.ts +++ b/test/scheduleDelivery.test.ts @@ -109,6 +109,39 @@ test('a run whose job has not finished reads unknown; a finished job that queued } finally { store.close() } }) +// #959 review: only a decided instant can answer. A `claimed` row keeps its +// `job_id` NULL until the worker starts the job, and an `expired` row is a +// lease that lapsed before anyone settled it — reading either as `none` prints +// "not queued" for a run that has not decided yet. +test('a run that has not decided yet reads unknown, never none', () => { + const { store, repoId } = harness('delivery-undecided') + try { + const row = store.saveSchedule({ id: `sch_${repoId}`, repoId, kind: 'interval', everyMs: HOUR }) + const logicalTime = Math.floor(NOW / HOUR) * HOUR + store.claimScheduleOccurrence({ + id: `occ_${repoId}`, scheduleId: row.id, repoId, logicalTime, timingRevision: row.timing_revision, + leaseToken: 'tok', leaseMs: HOUR, now: NOW, + }) + const claimed = store.listScheduleOccurrences(repoId, 10) + assert.equal(claimed[0]?.state, 'claimed', 'the fixture holds the instant') + assert.equal(claimed[0]?.job_id, null, 'a claimed row names no job until it dispatches') + + const at = (occurrences: typeof claimed, status: string) => scheduleConsole({ + repoId, row, occurrences, now: NOW, jobStatus: jobAt(status), jobDeliveries: fake([]), + }).delivery + + assert.equal(at(claimed, 'running'), 'unknown', 'a claimed run has not decided whether it will queue a notification') + assert.equal(at(claimed, 'queued'), 'unknown') + assert.equal(at(claimed, 'succeeded'), 'unknown', 'no job is linked, so no job status can make the answer definite') + + const expired = [{ ...claimed[0]!, state: 'expired' }] + assert.equal(at(expired, 'failed'), 'unknown', 'an expired lease left the instant unreconciled, so its delivery is unknown') + + const skipped = [{ ...claimed[0]!, state: 'skipped', reason: 'misfire' }] + assert.equal(at(skipped, 'failed'), 'none', 'a decided skip dispatched no job, so it queued nothing') + } finally { store.close() } +}) + test('several notifications read as the worst of them, because one needs attention', () => { const { store, repoId, userId } = harness('delivery-worst') try {