@shipfox/api-workflows 2.0.0

package/src/temporal/workflows/test-env.ts

@@ -0,0 +1,409 @@
+import {resolve} from 'node:path';
+import {TestWorkflowEnvironment} from '@temporalio/testing';
+import {Worker} from '@temporalio/worker';
+import type {RuntimeCompletionStatus} from '#core/workflow-scheduling/runtime-dag.js';
+import type {JobActivationDecision} from '#db/index.js';
+import type {
+  ActivateJobListenerResult,
+  DrainListenerEventsResult,
+  ListenerBufferPeek,
+} from '#db/job-listeners.js';
+import type {RunDag} from '../activities/orchestration-activities.js';
+import {JOB_FINISHED_SIGNAL, JOB_LEASE_EXPIRED_SIGNAL} from '../constants.js';
+
+const TASK_QUEUE = 'test-orchestration';
+const WORKFLOWS_PATH = resolve(import.meta.dirname, '../../../dist/temporal/workflows/index.js');
+
+export {TASK_QUEUE};
+
+// ---------------------------------------------------------------------------
+// Shared mutable test config — each test sets this before starting a workflow.
+// Activities read from it via closure. Tests run serially within a describe.
+// ---------------------------------------------------------------------------
+
+export interface TestConfig {
+  dag: RunDag;
+  /** Map of jobId → status the mock runner should signal back */
+  jobResults: Map<string, RuntimeCompletionStatus>;
+  /** If set, enqueueJobExecutionForRunner will throw with this message instead of signaling */
+  enqueueError?: string;
+  /** If true, enqueueJobExecutionForRunner sends two job-finished signals (for dedup testing) */
+  duplicateSignal?: boolean;
+  /** If true, enqueueJobExecutionForRunner does nothing (no signal — for timeout testing) */
+  skipSignal?: boolean;
+  /** If true, signal job-lease-expired instead of job-finished */
+  signalLeaseExpired?: boolean;
+  /** If true, signal BOTH job-finished and job-lease-expired (precedence testing) */
+  signalBoth?: boolean;
+  /** Status resolveLeaseExpiredJobExecutionActivity returns (defaults to 'failed') */
+  leaseExpiredStatus?: RuntimeCompletionStatus;
+  /** If set, resolveJobStatusFromJobExecutionsActivity throws with this message */
+  resolveJobStatusError?: string;
+  /** If set, releaseLeaseActivity throws (non-retryable) to prove the workflow still returns */
+  releaseLeaseError?: string;
+  /** Scripted job activation decisions keyed by job id; defaults to start */
+  activationDecisions?: Map<string, JobActivationDecision>;
+  /** If set, failJobExecutionAsTimedOutActivity throws (for timeout error-path testing) */
+  failJobExecutionAsTimedOutError?: string;
+  /** Effective status returned by the initial running setRunAttemptStatus call */
+  initialRunStatus?: string;
+  /** Effective status returned by a running setJobStatus call */
+  runningJobStatus?: string;
+  /** Result returned by activateJobListenerActivity (defaults to a running listener) */
+  listenerActivated?: ActivateJobListenerResult;
+  /** Scripted drain results consumed in order; once exhausted, drain returns {kind: 'empty'} */
+  drainResults?: DrainListenerEventsResult[];
+  /** Scripted listener buffer peeks consumed in order; once exhausted, returns an empty buffer */
+  peekResults?: ListenerBufferPeek[];
+  /** Result returned by resolveJobListenerActivity (defaults to succeeded) */
+  listenerResolved?: {status: 'succeeded' | 'failed'; jobVersion: number};
+}
+
+export let cfg: TestConfig;
+
+export function setCfg(value: TestConfig): void {
+  cfg = value;
+}
+
+// Track every activity call for assertions
+export interface ActivityCall {
+  name: string;
+  params: unknown;
+}
+
+export let calls: ActivityCall[];
+let versionSeq: number;
+
+function nextVersion(): number {
+  return ++versionSeq;
+}
+
+export function resetCalls(): void {
+  calls = [];
+  versionSeq = 0;
+}
+
+export function callsNamed(name: string): ActivityCall[] {
+  return calls.filter((c) => c.name === name);
+}
+
+export function setRunAttemptStatusCalls() {
+  return callsNamed('setRunAttemptStatus') as Array<{
+    name: string;
+    params: {runAttemptId: string; status: string; version: number};
+  }>;
+}
+
+export function setJobStatusCalls() {
+  return callsNamed('setJobStatus') as Array<{
+    name: string;
+    params: {jobId: string; status: string; version: number; statusReason?: string | null};
+  }>;
+}
+
+export function setExecutionStatusCalls() {
+  return callsNamed('setJobExecutionStatus') as Array<{
+    name: string;
+    params: {jobExecutionId: string; status: string; version: number; statusReason?: string | null};
+  }>;
+}
+
+export function listenerFiringOutcomeCalls() {
+  return callsNamed('recordListenerFiringOutcomeActivity') as Array<{
+    name: string;
+    params: {outcome: 'succeeded' | 'failed' | 'cancelled'};
+  }>;
+}
+
+export function resolveJobListenerCalls() {
+  return callsNamed('resolveJobListenerActivity') as Array<{
+    name: string;
+    params: {jobId: string; reason: string};
+  }>;
+}
+
+export function settleListenerCalls() {
+  return callsNamed('settleListenerJobExecutionActivity') as Array<{
+    name: string;
+    params: {jobExecutionId: string; status: 'failed' | 'cancelled'};
+  }>;
+}
+
+// ---------------------------------------------------------------------------
+// DAG helpers
+// ---------------------------------------------------------------------------
+
+export function dagJob(
+  id: string,
+  key: string,
+  deps: string[] = [],
+  options: {
+    mode?: RunDag['jobs'][number]['mode'] | undefined;
+    status?: RunDag['jobs'][number]['status'] | undefined;
+    hasActivationCondition?: boolean | undefined;
+  } = {},
+): RunDag['jobs'][number] {
+  const mode = options.mode ?? 'one_shot';
+  return {
+    id,
+    key,
+    mode,
+    status: options.status ?? 'pending',
+    ...(mode === 'listening' ? {} : {jobExecutionId: id, executionVersion: 1}),
+    executionTimeoutMs: null,
+    listeningTimeoutMs: null,
+    maxExecutions: null,
+    onResolve: null,
+    hasActivationCondition: options.hasActivationCondition ?? false,
+    dependencies: deps,
+    runner: ['ubuntu22'],
+    version: 1,
+  };
+}
+
+export function makeDag(jobs: RunDag['jobs'], workflowRunId = 'run-1'): RunDag {
+  return {
+    workflowRunId,
+    runAttemptId: `${workflowRunId}-attempt-1`,
+    workspaceId: 'workspace-1',
+    projectId: 'project-1',
+    runVersion: 1,
+    runTimeoutMs: 30 * 24 * 60 * 60 * 1000,
+    jobs,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Environment lifecycle
+// ---------------------------------------------------------------------------
+
+export let testEnv: TestWorkflowEnvironment;
+export let worker: Worker;
+
+let workerRunPromise: Promise<void> | undefined;
+
+export async function setupEnv(): Promise<void> {
+  testEnv = await TestWorkflowEnvironment.createLocal();
+
+  worker = await Worker.create({
+    connection: testEnv.nativeConnection,
+    taskQueue: TASK_QUEUE,
+    workflowsPath: WORKFLOWS_PATH,
+    activities: createMockActivities(),
+  });
+
+  // Run worker in background — it processes tasks until shutdown is called
+  workerRunPromise = worker.run();
+  workerRunPromise.catch(() => {
+    // Suppress unhandled rejection on shutdown
+  });
+}
+
+export async function teardownEnv(): Promise<void> {
+  worker?.shutdown();
+  await workerRunPromise;
+  await testEnv?.teardown();
+}
+
+function createMockActivities() {
+  return {
+    loadRunAttemptDag: (runAttemptId: string): RunDag => {
+      calls.push({name: 'loadRunAttemptDag', params: runAttemptId});
+      return cfg.dag;
+    },
+
+    setRunAttemptStatus: (params: {runAttemptId: string; status: string; version: number}) => {
+      calls.push({name: 'setRunAttemptStatus', params});
+      const status =
+        params.status === 'running' && cfg.initialRunStatus ? cfg.initialRunStatus : params.status;
+      return {newVersion: nextVersion(), status};
+    },
+
+    setJobStatus: (params: {
+      jobId: string;
+      status: string;
+      version: number;
+      statusReason?: string | null;
+    }) => {
+      calls.push({name: 'setJobStatus', params});
+      const status =
+        params.status === 'running' && cfg.runningJobStatus ? cfg.runningJobStatus : params.status;
+      return {newVersion: nextVersion(), status};
+    },
+
+    evaluateJobActivationsActivity: (params: {
+      runAttemptId: string;
+      jobs: readonly {jobId: string; expectedVersion: number}[];
+    }): JobActivationDecision[] => {
+      calls.push({name: 'evaluateJobActivationsActivity', params});
+      return params.jobs.map((job) => {
+        const decision = cfg.activationDecisions?.get(job.jobId);
+        return decision ?? {kind: 'start-job', jobId: job.jobId};
+      });
+    },
+
+    setJobExecutionStatus: (params: {
+      jobExecutionId: string;
+      status: string;
+      version: number;
+      statusReason?: string | null;
+    }) => {
+      calls.push({name: 'setJobExecutionStatus', params});
+      const status =
+        params.status === 'running' && cfg.runningJobStatus ? cfg.runningJobStatus : params.status;
+      return {newVersion: nextVersion(), status};
+    },
+
+    bulkSetStepStatuses: (params: {jobExecutionId: string; status: string}) => {
+      calls.push({name: 'bulkSetStepStatuses', params});
+    },
+
+    cancelRunnerJobsActivity: (params: {jobIds: string[]}) => {
+      calls.push({name: 'cancelRunnerJobsActivity', params});
+    },
+
+    // Scheduling is step-less. The mock runner reports the job outcome by signalling
+    // the per-step terminal-completion signal (job-finished) and/or the lease-expiry
+    // signal, reproducing the outbox → subscriber → signal rail.
+    enqueueJobExecutionForRunner: async (params: {
+      workspaceId: string;
+      workflowRunId: string;
+      runAttemptId: string;
+      jobId: string;
+      jobExecutionId: string;
+      projectId: string;
+      requiredLabels: string[];
+    }) => {
+      calls.push({name: 'enqueueJobExecutionForRunner', params});
+
+      if (cfg.enqueueError) {
+        const {ApplicationFailure} = await import('@temporalio/common');
+        throw ApplicationFailure.nonRetryable(cfg.enqueueError);
+      }
+
+      if (cfg.skipSignal) return;
+
+      const status = cfg.jobResults.get(params.jobId) ?? 'succeeded';
+      const handle = testEnv.client.workflow.getHandle(`job:${params.jobId}`);
+
+      if (cfg.signalLeaseExpired) {
+        await handle.signal(JOB_LEASE_EXPIRED_SIGNAL, {jobExecutionId: params.jobExecutionId});
+        return;
+      }
+
+      if (cfg.signalBoth) {
+        await handle.signal(JOB_FINISHED_SIGNAL, {status, jobExecutionId: params.jobExecutionId});
+        await handle.signal(JOB_LEASE_EXPIRED_SIGNAL, {jobExecutionId: params.jobExecutionId});
+        return;
+      }
+
+      await handle.signal(JOB_FINISHED_SIGNAL, {status, jobExecutionId: params.jobExecutionId});
+
+      if (cfg.duplicateSignal) {
+        await handle.signal(JOB_FINISHED_SIGNAL, {
+          status: 'failed',
+          jobExecutionId: params.jobExecutionId,
+        });
+      }
+    },
+
+    resolveLeaseExpiredJobExecutionActivity: (params: {
+      jobExecutionId: string;
+      expectedVersion: number;
+    }) => {
+      calls.push({name: 'resolveLeaseExpiredJobExecutionActivity', params});
+      return {status: cfg.leaseExpiredStatus ?? 'failed', executionVersion: nextVersion()};
+    },
+
+    resolveJobStatusFromJobExecutionsActivity: async (params: {jobId: string}) => {
+      calls.push({name: 'resolveJobStatusFromJobExecutionsActivity', params});
+      if (cfg.resolveJobStatusError) {
+        const {ApplicationFailure} = await import('@temporalio/common');
+        throw ApplicationFailure.nonRetryable(cfg.resolveJobStatusError);
+      }
+      const terminalExecutionStatus = [...setExecutionStatusCalls()]
+        .reverse()
+        .find(
+          (call) => call.params.jobExecutionId === params.jobId && call.params.status !== 'running',
+        )?.params.status as RuntimeCompletionStatus | undefined;
+      return {
+        status: cfg.leaseExpiredStatus ?? terminalExecutionStatus ?? 'succeeded',
+        jobVersion: nextVersion(),
+      };
+    },
+
+    releaseLeaseActivity: async (params: {jobExecutionId: string}) => {
+      calls.push({name: 'releaseLeaseActivity', params});
+      if (cfg.releaseLeaseError) {
+        const {ApplicationFailure} = await import('@temporalio/common');
+        throw ApplicationFailure.nonRetryable(cfg.releaseLeaseError);
+      }
+    },
+
+    failJobExecutionAsTimedOutActivity: async (params: {
+      jobExecutionId: string;
+      runAttemptId: string;
+      expectedVersion: number;
+    }) => {
+      calls.push({name: 'failJobExecutionAsTimedOutActivity', params});
+      if (cfg.failJobExecutionAsTimedOutError) {
+        const {ApplicationFailure} = await import('@temporalio/common');
+        throw ApplicationFailure.nonRetryable(cfg.failJobExecutionAsTimedOutError);
+      }
+      return {newVersion: nextVersion()};
+    },
+
+    activateJobListenerActivity: (params: {jobId: string; expectedVersion: number}) => {
+      calls.push({name: 'activateJobListenerActivity', params});
+      return (
+        cfg.listenerActivated ?? {
+          status: 'running',
+          jobStatus: 'running',
+          jobVersion: nextVersion(),
+          executionCount: 0,
+        }
+      );
+    },
+
+    // Each call consumes the next scripted drain result. An exhausted script means
+    // "no events buffered", which parks the listener until a signal or its deadline.
+    drainListenerEventsActivity: (params: {
+      jobId: string;
+      expectedSequence: number;
+      maxSize?: number;
+    }) => {
+      calls.push({name: 'drainListenerEventsActivity', params});
+      return cfg.drainResults?.shift() ?? {kind: 'empty'};
+    },
+
+    peekListenerBufferActivity: (params: {jobId: string}) => {
+      calls.push({name: 'peekListenerBufferActivity', params});
+      return (
+        cfg.peekResults?.shift() ?? {
+          fireCount: 0,
+          resolvePending: false,
+          oldestAgeMs: 0,
+          newestAgeMs: 0,
+        }
+      );
+    },
+
+    resolveJobListenerActivity: (params: {jobId: string; reason: string}) => {
+      calls.push({name: 'resolveJobListenerActivity', params});
+      return cfg.listenerResolved ?? {status: 'succeeded', jobVersion: nextVersion()};
+    },
+
+    settleListenerJobExecutionActivity: (params: {
+      jobExecutionId: string;
+      status: 'failed' | 'cancelled';
+    }) => {
+      calls.push({name: 'settleListenerJobExecutionActivity', params});
+    },
+
+    recordListenerFiringOutcomeActivity: (params: {
+      outcome: 'succeeded' | 'failed' | 'cancelled';
+    }) => {
+      calls.push({name: 'recordListenerFiringOutcomeActivity', params});
+    },
+  };
+}

package/test/env.ts

@@ -0,0 +1,11 @@
+process.env.POSTGRES_HOST ??= 'localhost';
+process.env.POSTGRES_PORT ??= '5432';
+process.env.POSTGRES_USERNAME ??= 'shipfox';
+process.env.POSTGRES_PASSWORD ??= 'password';
+process.env.POSTGRES_DATABASE = 'api_test';
+process.env.POSTGRES_MAX_CONNECTIONS ??= '5';
+process.env.AUTH_JWT_SECRET = 'test-secret';
+process.env.AUTH_JOB_LEASE_TOKEN_SECRET = 'test-lease-secret';
+process.env.AUTH_RUNNER_SESSION_TOKEN_SECRET = 'test-runner-session-secret';
+process.env.SECRETS_ENCRYPTION_KEK = 'ZmVkY2JhOTg3NjU0MzIxMGZlZGNiYTk4NzY1NDMyMTA=';
+process.env.TZ = 'UTC';

package/test/factories/job.ts

@@ -0,0 +1,83 @@
+import {eq} from 'drizzle-orm';
+import {Factory} from 'fishery';
+import type {Job, JobCheckout, JobStatus} from '#core/entities/job.js';
+import {db} from '#db/db.js';
+import {jobs} from '#db/schema/jobs.js';
+import {getJobsByWorkflowRunId} from '#db/workflow-runs.js';
+import {workflowModel} from './workflow-model.js';
+import {workflowRunFactory} from './workflow-run.js';
+
+interface JobTransientParams {
+  projectId?: string;
+  status?: JobStatus;
+  checkout?: Partial<JobCheckout>;
+}
+
+// Provisions a workflow run for `projectId` and returns its first job moved to
+// `status` (default 'running'). A job cannot exist without its run (workflow_run_id is a
+// NOT NULL FK), so this factory creates the enclosing run too. 'running' is the
+// realistic precondition for the lease-authed checkout path: a runner only holds
+// a lease for a job it has claimed and is executing.
+export const jobFactory = Factory.define<Job, JobTransientParams>(({transientParams, onCreate}) => {
+  onCreate(async () => {
+    const {projectId = crypto.randomUUID(), status = 'running', checkout} = transientParams;
+    const run = await workflowRunFactory.create(
+      {projectId},
+      checkout === undefined
+        ? undefined
+        : {
+            transient: {
+              model: workflowModel({
+                jobs: {
+                  build: {
+                    checkout: {
+                      permissions: checkout.permissions ?? {contents: 'read'},
+                      persistCredentials: checkout.persistCredentials ?? true,
+                    },
+                    steps: [{run: 'echo hello'}],
+                  },
+                },
+              }),
+            },
+          },
+    );
+    const [job] = await getJobsByWorkflowRunId(run.id);
+    if (!job) throw new Error('jobFactory: run created no jobs');
+    await db().update(jobs).set({status}).where(eq(jobs.id, job.id));
+    return {...job, status, statusReason: null, carriedOver: false};
+  });
+
+  return {
+    id: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    key: 'build',
+    name: null,
+    mode: 'one_shot',
+    status: 'running',
+    statusReason: null,
+    carriedOver: false,
+    checkout: {
+      permissions: {contents: 'read'},
+      persistCredentials: true,
+    },
+    success: null,
+    executionTimeoutMs: null,
+    listeningTimeoutMs: null,
+    maxExecutions: null,
+    onResolve: null,
+    batchDebounceMs: null,
+    batchMaxSize: null,
+    batchMaxWaitMs: null,
+    listenerStatus: 'inactive',
+    resolutionReason: null,
+    listeningOn: null,
+    listeningUntil: null,
+    outputs: null,
+    dependencies: [],
+    runner: null,
+    position: 0,
+    version: 1,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+});

package/test/factories/project.ts

@@ -0,0 +1,16 @@
+import type {Project} from '@shipfox/api-projects';
+import {Factory} from 'fishery';
+
+// Build-only: the workflows routes resolve projects through a mocked
+// `getProjectById`, so these are never persisted (the projects table lives in
+// @shipfox/api-projects). Typed against the real `Project` so the mock cannot
+// drift from the contract under test.
+export const projectFactory = Factory.define<Project>(({sequence}) => ({
+  id: crypto.randomUUID(),
+  workspaceId: crypto.randomUUID(),
+  sourceConnectionId: crypto.randomUUID(),
+  sourceExternalRepositoryId: `acme/repo-${sequence}`,
+  name: `Project ${sequence}`,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+}));

package/test/factories/workflow-model.test.ts

@@ -0,0 +1,26 @@
+import {workflowModel} from './workflow-model.js';
+
+describe('workflowModel', () => {
+  it('defaults jobs to a non-empty canonical runner label set', () => {
+    const model = workflowModel();
+
+    expect(model.jobs[0]?.runner).toEqual(['ubuntu-latest']);
+  });
+
+  it('uses workflow and job runner overrides', () => {
+    const model = workflowModel({
+      runner: 'ubuntu-22',
+      jobs: {
+        build: {
+          steps: [{run: 'pnpm build'}],
+        },
+        test: {
+          runner: ['ubuntu-22', 'node-22'],
+          steps: [{run: 'pnpm test'}],
+        },
+      },
+    });
+
+    expect(model.jobs.map((job) => job.runner)).toEqual([['ubuntu-22'], ['ubuntu-22', 'node-22']]);
+  });
+});