/** * Shared helpers for the `outbox` CLI subtree. * * Both `requeue --event-id` and `requeue --type --since` flow through * the runners defined here so the citty command stays a thin wrapper * with full unit-test coverage on the business logic. * * The terminology mirrors the Prisma OutboxStatus enum (PENDING, * PROCESSING, DONE, FAILED, CANCELLED). */ export type OutboxRequeueStatus = "PENDING" | "PROCESSING" | "DONE" | "FAILED" | "CANCELLED"; /** * Refusable statuses — we never reset an event that's currently being * worked on by the dispatcher (PROCESSING) or that's still waiting in * the queue (PENDING). Doing so would double-deliver the work. */ export const OUTBOX_REQUEUE_REFUSED_STATUSES: ReadonlySet = new Set(["PENDING", "PROCESSING", "DONE"]); /** * Acceptable statuses for re-queue. DONE only proves enqueue, not consumer * completion, so replaying it could overlap an active delivery. */ export const OUTBOX_REQUEUE_ALLOWED_STATUSES: ReadonlySet = new Set(["FAILED", "CANCELLED"]); export interface OutboxRequeueEventRow { id: string; eventType: string; status: OutboxRequeueStatus; tenantId: string | null; retries: number; deliveryGeneration: number; createdAt: Date; } /** * Narrow interface against `@hivegrid/db` — just the methods the * runner uses. Tests inject an in-memory fake. */ export interface OutboxRequeueClient { outboxEvent: { findFirst(args: { where: { id: string; tenantId: string } }): Promise; update(args: { where: { id: string }; data: { status: OutboxRequeueStatus; retries: number; deliveryGeneration: { increment: number }; lastError: string | null; scheduledAt: Date; lockedUntil: null; processedAt: null; }; }): Promise; findMany(args: { where: { eventType: string; tenantId: string; createdAt: { gte: Date }; status: { in: OutboxRequeueStatus[] }; }; select: { id: true; eventType: true; status: true; tenantId: true; retries: true; deliveryGeneration: true; createdAt: true }; orderBy: { createdAt: "asc" }; take: number; }): Promise; updateMany(args: { where: { id: { in: string[] }; tenantId: string; status?: { in: OutboxRequeueStatus[] }; deliveryGeneration?: number; }; data: { status: OutboxRequeueStatus; retries: number; deliveryGeneration: { increment: number }; lastError: string | null; scheduledAt: Date; lockedUntil: null; processedAt: null; }; }): Promise<{ count: number }>; }; } export interface OutboxRequeueOutput { log(message: string): void; warn(message: string): void; error(message: string): void; json(payload: unknown): void; } export interface OutboxRequeueByIdArgs { tenantId: string; eventId: string; json?: boolean; now?: Date; } export type OutboxRequeueByIdOutcome = | { exitCode: 0; status: "requeued"; eventId: string; previousStatus: OutboxRequeueStatus } | { exitCode: 1; status: "not_found" | "refused"; eventId: string; previousStatus?: OutboxRequeueStatus; message?: string }; function isStatus(value: unknown): value is OutboxRequeueStatus { return typeof value === "string" && ["PENDING", "PROCESSING", "DONE", "FAILED", "CANCELLED"].includes(value); } export function normalizeStatus(value: unknown): OutboxRequeueStatus { if (isStatus(value)) return value; throw new Error(`Unrecognised OutboxStatus value ${JSON.stringify(value)}`); } export function normalizeTenantId(value: unknown): string { const normalized = typeof value === "string" ? value.trim() : ""; if (normalized.length === 0 || normalized.length > 191 || normalized.includes("\u0000")) { throw new Error("--tenant must be a non-empty database identifier"); } return normalized; } /** * Re-queue a single event by id. Refuses to act on events that are * currently PENDING or PROCESSING — re-queueing them would double- * deliver the work because the dispatcher still has the original copy * in its pipeline. */ export async function runOutboxRequeueById( args: OutboxRequeueByIdArgs, deps: { client: OutboxRequeueClient; output: OutboxRequeueOutput } ): Promise { const tenantId = normalizeTenantId(args.tenantId); const now = args.now ?? new Date(); const existing = await deps.client.outboxEvent.findFirst({ where: { id: args.eventId, tenantId } }); if (!existing) { if (args.json) { deps.output.json({ ok: false, reason: "not_found", eventId: args.eventId }); } else { deps.output.error(`outbox event ${args.eventId} not found`); } return { exitCode: 1, status: "not_found", eventId: args.eventId }; } const status = normalizeStatus(existing.status); if (OUTBOX_REQUEUE_REFUSED_STATUSES.has(status)) { const message = `outbox event ${args.eventId} is currently ${status}; refuse to re-queue (would double-deliver)`; if (args.json) { deps.output.json({ ok: false, reason: "refused", eventId: args.eventId, status }); } else { deps.output.error(message); } return { exitCode: 1, status: "refused", eventId: args.eventId, previousStatus: status, message }; } if (!OUTBOX_REQUEUE_ALLOWED_STATUSES.has(status)) { const message = `outbox event ${args.eventId} has unsupported status ${status}`; if (args.json) { deps.output.json({ ok: false, reason: "refused", eventId: args.eventId, status }); } else { deps.output.error(message); } return { exitCode: 1, status: "refused", eventId: args.eventId, previousStatus: status, message }; } const requeued = await deps.client.outboxEvent.updateMany({ where: { id: { in: [args.eventId] }, tenantId, status: { in: [status] }, deliveryGeneration: existing.deliveryGeneration, }, data: { status: "PENDING", retries: 0, deliveryGeneration: { increment: 1 }, lastError: null, scheduledAt: now, lockedUntil: null, processedAt: null, }, }); if (requeued.count !== 1) { const message = `outbox event ${args.eventId} changed while it was being re-queued; retry from fresh state`; if (args.json) { deps.output.json({ ok: false, reason: "refused", eventId: args.eventId, status }); } else { deps.output.error(message); } return { exitCode: 1, status: "refused", eventId: args.eventId, previousStatus: status, message }; } if (args.json) { deps.output.json({ ok: true, eventId: args.eventId, previousStatus: status }); } else { deps.output.log(`outbox event ${args.eventId} re-queued (was ${status})`); } return { exitCode: 0, status: "requeued", eventId: args.eventId, previousStatus: status }; } export interface OutboxRequeueBulkArgs { tenantId: string; type: string; since: string; /** Optional cap to avoid runaway re-queues. Default 10_000. */ limit?: number; /** `true` ⇒ confirm, perform the writes; `false` ⇒ dry-run summary only. */ apply?: boolean; /** Legacy flag. DONE replay is refused until consumer completion receipts exist. */ includeDone?: boolean; json?: boolean; now?: Date; } export type OutboxRequeueBulkOutcome = { exitCode: 0 | 1; status: "previewed" | "requeued" | "invalid_args"; matched: number; applied: number; eventType: string; since: Date | null; message?: string; }; const OUTBOX_REQUEUE_BULK_DEFAULT_LIMIT = 10_000; const OUTBOX_EVENT_TYPE_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*){2,}$/u; export async function runOutboxRequeueBulk( args: OutboxRequeueBulkArgs, deps: { client: OutboxRequeueClient; output: OutboxRequeueOutput } ): Promise { const tenantId = normalizeTenantId(args.tenantId); const limit = Math.max(1, Math.min(args.limit ?? OUTBOX_REQUEUE_BULK_DEFAULT_LIMIT, 100_000)); if (!OUTBOX_EVENT_TYPE_PATTERN.test(args.type)) { const message = `--type must match .. (got ${JSON.stringify(args.type)})`; if (args.json) { deps.output.json({ ok: false, reason: "invalid_args", message }); } else { deps.output.error(message); } return { exitCode: 1, status: "invalid_args", matched: 0, applied: 0, eventType: args.type, since: null, message }; } if (args.includeDone) { const message = "--include-done is unsafe without a consumer completion receipt and is no longer supported"; if (args.json) deps.output.json({ ok: false, reason: "invalid_args", message }); else deps.output.error(message); return { exitCode: 1, status: "invalid_args", matched: 0, applied: 0, eventType: args.type, since: null, message }; } const since = new Date(args.since); if (Number.isNaN(since.getTime())) { const message = `--since must be a valid ISO-8601 timestamp (got ${JSON.stringify(args.since)})`; if (args.json) { deps.output.json({ ok: false, reason: "invalid_args", message }); } else { deps.output.error(message); } return { exitCode: 1, status: "invalid_args", matched: 0, applied: 0, eventType: args.type, since: null, message }; } const statusFilter: OutboxRequeueStatus[] = ["FAILED", "CANCELLED"]; const candidates = await deps.client.outboxEvent.findMany({ where: { eventType: args.type, tenantId, createdAt: { gte: since }, status: { in: statusFilter }, }, select: { id: true, eventType: true, status: true, tenantId: true, retries: true, deliveryGeneration: true, createdAt: true }, orderBy: { createdAt: "asc" }, take: limit, }); if (!args.apply) { if (args.json) { deps.output.json({ ok: true, applied: 0, matched: candidates.length, eventType: args.type, since: since.toISOString(), preview: candidates.slice(0, 10).map((c) => ({ id: c.id, status: c.status, tenantId: c.tenantId })), }); } else { deps.output.log( `outbox requeue (dry-run): ${candidates.length} event(s) matched type=${args.type} since=${since.toISOString()}; pass --apply to perform the re-queue` ); } return { exitCode: 0, status: "previewed", matched: candidates.length, applied: 0, eventType: args.type, since }; } if (candidates.length === 0) { if (args.json) { deps.output.json({ ok: true, applied: 0, matched: 0, eventType: args.type, since: since.toISOString() }); } else { deps.output.log(`outbox requeue: no events matched type=${args.type} since=${since.toISOString()}`); } return { exitCode: 0, status: "requeued", matched: 0, applied: 0, eventType: args.type, since }; } const now = args.now ?? new Date(); let applied = 0; for (const candidate of candidates) { const result = await deps.client.outboxEvent.updateMany({ where: { id: { in: [candidate.id] }, tenantId, status: { in: [candidate.status] }, deliveryGeneration: candidate.deliveryGeneration, }, data: { status: "PENDING", retries: 0, deliveryGeneration: { increment: 1 }, lastError: null, scheduledAt: now, lockedUntil: null, processedAt: null, }, }); applied += result.count; } if (args.json) { deps.output.json({ ok: true, applied, matched: candidates.length, eventType: args.type, since: since.toISOString() }); } else { deps.output.log(`outbox requeue: ${applied} event(s) re-queued (type=${args.type} since=${since.toISOString()})`); } return { exitCode: 0, status: "requeued", matched: candidates.length, applied, eventType: args.type, since }; }