326 lines
12 KiB
TypeScript
326 lines
12 KiB
TypeScript
/**
|
|
* 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<OutboxRequeueStatus> = 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<OutboxRequeueStatus> = 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<OutboxRequeueEventRow | null>;
|
|
update(args: {
|
|
where: { id: string };
|
|
data: {
|
|
status: OutboxRequeueStatus;
|
|
retries: number;
|
|
deliveryGeneration: { increment: number };
|
|
lastError: string | null;
|
|
scheduledAt: Date;
|
|
lockedUntil: null;
|
|
processedAt: null;
|
|
};
|
|
}): Promise<OutboxRequeueEventRow>;
|
|
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<OutboxRequeueEventRow[]>;
|
|
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<OutboxRequeueByIdOutcome> {
|
|
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<OutboxRequeueBulkOutcome> {
|
|
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 <domain>.<entity>.<verb> (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 };
|
|
}
|