@shipfox/api-workflows 2.0.0

package/src/db/index.ts

@@ -0,0 +1,86 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export {closeDb, db, schema} from './db.js';
+export {
+  type DeliverEventToListenerParams,
+  type DeliverEventToListenerResult,
+  deliverEventToListener,
+} from './job-listener-events.js';
+export type {
+  ActivateJobListenerParams,
+  ActivateJobListenerResult,
+  DrainListenerEventsParams,
+  DrainListenerEventsResult,
+  ListenerBufferPeek,
+} from './job-listeners.js';
+export {
+  activateJobListener,
+  countActiveListeners,
+  drainListenerEventsIntoExecution,
+  peekListenerBuffer,
+  resolveJobListener,
+  settleListenerJobExecution,
+} from './job-listeners.js';
+export {workflowsOutbox} from './schema/outbox.js';
+export type {
+  BulkUpdateStepStatusesParams,
+  CancelWorkflowRunParams,
+  CreateRerunWorkflowRunParams,
+  CreateWorkflowRunParams,
+  EvaluateJobActivationsParams,
+  FailWorkflowRunAsTimedOutParams,
+  JobActivationDecision,
+  ListWorkflowRunsParams,
+  ListWorkflowRunsResult,
+  UpdateJobExecutionStatusParams,
+  UpdateJobStatusParams,
+  UpdateWorkflowRunStatusParams,
+  WorkflowJobExecutionDepth,
+  WorkflowJobExecutionDepthParams,
+  WorkflowRunAggregates,
+  WorkflowRunFilters,
+} from './workflow-runs.js';
+export {
+  bulkUpdateStepStatuses,
+  cancelWorkflowRun,
+  createRerunWorkflowRun,
+  createWorkflowRun,
+  evaluateJobActivations,
+  failJobExecutionAsTimedOut,
+  failWorkflowRunAsTimedOut,
+  getFirstJobExecutionByJobId,
+  getJobById,
+  getJobExecutionById,
+  getJobExecutionDetail,
+  getJobExecutionsByJobId,
+  getJobExecutionsByWorkflowRunAttemptId,
+  getJobScope,
+  getJobsByWorkflowRunAttemptId,
+  getJobsByWorkflowRunId,
+  getLatestAttempt,
+  getStepAttempts,
+  getStepAttemptsByJobIds,
+  getStepById,
+  getStepByIdForJobExecution,
+  getStepsByJobExecutionId,
+  getStepsByJobExecutionIdForUpdate,
+  getWorkflowJobExecutionDepth,
+  getWorkflowRunAggregates,
+  getWorkflowRunAttemptById,
+  getWorkflowRunByAttemptId,
+  getWorkflowRunById,
+  getWorkflowRunDetail,
+  listRunAttempts,
+  listWorkflowRuns,
+  listWorkflowRunsByProject,
+  recordJobExecutionQueuedAt,
+  recordJobExecutionStartedAt,
+  resolveJobExecutionAfterLeaseExpiry,
+  resolveJobStatusFromJobExecutions,
+  updateJobExecutionStatus,
+  updateJobStatus,
+  updateWorkflowRunStatus,
+} from './workflow-runs.js';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');

package/src/db/job-listener-events.test.ts

@@ -0,0 +1,113 @@
+import {WORKFLOWS_JOB_EVENT_DELIVERED} from '@shipfox/api-workflows-dto';
+import {eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {jobListenerEvents} from '#db/schema/job-listener-events.js';
+import {jobs} from '#db/schema/jobs.js';
+import {workflowsOutbox} from '#db/schema/outbox.js';
+
+const {deliverEventToListener} = await import('./job-listener-events.js');
+const {jobFactory} = await import('#test/index.js');
+
+interface DeliverOverrides {
+  jobId?: string;
+  disposition?: 'fire' | 'resolve';
+  eventRef?: string;
+  provider?: string;
+}
+
+function deliver(overrides: DeliverOverrides = {}) {
+  return deliverEventToListener({
+    jobId: overrides.jobId ?? crypto.randomUUID(),
+    disposition: overrides.disposition ?? 'fire',
+    eventRef: overrides.eventRef ?? crypto.randomUUID(),
+    deliveryId: crypto.randomUUID(),
+    source: 'github',
+    event: 'pull_request_review',
+    provider: overrides.provider ?? 'github',
+    payload: {action: 'submitted'},
+    receivedAt: new Date('2026-01-01T00:00:00.000Z'),
+  });
+}
+
+function listEvents(jobId: string) {
+  return db().select().from(jobListenerEvents).where(eq(jobListenerEvents.jobId, jobId));
+}
+
+describe('deliverEventToListener', () => {
+  it('buffers a matching event once per job and event ref', async () => {
+    const job = await jobFactory.create({}, {transient: {status: 'pending'}});
+    const eventRef = crypto.randomUUID();
+
+    const first = await deliver({jobId: job.id, eventRef});
+    const second = await deliver({jobId: job.id, eventRef});
+
+    const rows = await listEvents(job.id);
+    expect(first).toEqual({buffered: true, skipped: false});
+    expect(second).toEqual({buffered: false, skipped: false});
+    expect(rows).toHaveLength(1);
+  });
+
+  it.each(['fire', 'resolve'] as const)('persists disposition %s', async (disposition) => {
+    const job = await jobFactory.create({}, {transient: {status: 'pending'}});
+
+    await deliver({jobId: job.id, disposition});
+
+    const rows = await listEvents(job.id);
+    expect(rows[0]?.disposition).toBe(disposition);
+  });
+
+  it('skips terminal jobs without throwing or buffering', async () => {
+    const job = await jobFactory.create({}, {transient: {status: 'succeeded'}});
+
+    const result = await deliver({jobId: job.id});
+
+    const rows = await listEvents(job.id);
+    expect(result).toEqual({buffered: false, skipped: true});
+    expect(rows).toHaveLength(0);
+  });
+
+  it('skips a missing job without throwing or buffering', async () => {
+    const jobId = crypto.randomUUID();
+
+    const result = await deliver({jobId});
+
+    const rows = await db().select().from(jobListenerEvents);
+    expect(result).toEqual({buffered: false, skipped: true});
+    expect(rows.some((row) => row.jobId === jobId)).toBe(false);
+  });
+
+  it('allows buffering for a job that has not started yet', async () => {
+    const job = await jobFactory.create({}, {transient: {status: 'pending'}});
+
+    const result = await deliver({jobId: job.id});
+
+    const [row] = await db().select().from(jobs).where(eq(jobs.id, job.id));
+    expect(row?.status).toBe('pending');
+    expect(result).toEqual({buffered: true, skipped: false});
+  });
+
+  it('writes a delivered outbox event when an event is buffered', async () => {
+    const job = await jobFactory.create({}, {transient: {status: 'pending'}});
+    const eventRef = crypto.randomUUID();
+
+    const result = await deliver({jobId: job.id, eventRef, disposition: 'resolve'});
+
+    const rows = await db()
+      .select()
+      .from(workflowsOutbox)
+      .where(eq(workflowsOutbox.eventType, WORKFLOWS_JOB_EVENT_DELIVERED));
+    const matching = rows.find(
+      (row) =>
+        (row.payload as Record<string, unknown>).jobId === job.id &&
+        (row.payload as Record<string, unknown>).eventRef === eventRef,
+    );
+    expect(result).toEqual({buffered: true, skipped: false});
+    expect(matching?.payload).toMatchObject({
+      jobId: job.id,
+      disposition: 'resolve',
+      eventRef,
+      eventName: 'pull_request_review',
+    });
+    expect(matching?.orderingKey).toBeNull();
+  });
+});

package/src/db/job-listener-events.ts

@@ -0,0 +1,73 @@
+import {WORKFLOWS_JOB_EVENT_DELIVERED} from '@shipfox/api-workflows-dto';
+import {eq} from 'drizzle-orm';
+import {isJobTerminal} from '#core/entities/job.js';
+import type {JobListenerEventDisposition} from '#core/entities/job-listener-event.js';
+import {recordListenerEventReceived} from '#metrics/instance.js';
+import {db} from './db.js';
+import {writeWorkflowsOutboxEvent} from './outbox-writes.js';
+import {jobListenerEvents} from './schema/job-listener-events.js';
+import {jobs} from './schema/jobs.js';
+
+export interface DeliverEventToListenerParams {
+  jobId: string;
+  disposition: JobListenerEventDisposition;
+  eventRef: string;
+  deliveryId: string;
+  source: string;
+  event: string;
+  provider: string;
+  payload: unknown;
+  receivedAt: Date;
+}
+
+export interface DeliverEventToListenerResult {
+  buffered: boolean;
+  skipped: boolean;
+}
+
+export async function deliverEventToListener(
+  params: DeliverEventToListenerParams,
+): Promise<DeliverEventToListenerResult> {
+  const result = await db().transaction(async (tx) => {
+    const [job] = await tx
+      .select({id: jobs.id, status: jobs.status})
+      .from(jobs)
+      .where(eq(jobs.id, params.jobId))
+      .for('update')
+      .limit(1);
+
+    if (!job || isJobTerminal(job.status)) return {buffered: false, skipped: true};
+
+    const rows = await tx
+      .insert(jobListenerEvents)
+      .values({
+        jobId: params.jobId,
+        disposition: params.disposition,
+        eventRef: params.eventRef,
+        deliveryId: params.deliveryId,
+        source: params.source,
+        event: params.event,
+        payload: params.payload,
+        receivedAt: params.receivedAt,
+      })
+      .onConflictDoNothing({target: [jobListenerEvents.jobId, jobListenerEvents.eventRef]})
+      .returning({id: jobListenerEvents.id});
+
+    if (!rows[0]) return {buffered: false, skipped: false};
+    await writeWorkflowsOutboxEvent(tx, {
+      type: WORKFLOWS_JOB_EVENT_DELIVERED,
+      payload: {
+        jobId: params.jobId,
+        disposition: params.disposition,
+        eventRef: params.eventRef,
+        eventName: params.event,
+      },
+    });
+    return {buffered: true, skipped: false};
+  });
+
+  if (!result.buffered) return result;
+
+  recordListenerEventReceived(params.provider);
+  return result;
+}