@shipfox/api-workflows 2.0.0

package/src/presentation/routes/list-run-attempts.test.ts

@@ -0,0 +1,163 @@
+import {buildUserContext, setUserContext} from '@shipfox/api-auth-context';
+import {requireProjectAccess} from '@shipfox/api-projects';
+import {ClientError} from '@shipfox/node-fastify';
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {
+  createRerunWorkflowRun,
+  createWorkflowRun,
+  updateWorkflowRunStatus,
+} from '#db/workflow-runs.js';
+import {workflowModel} from '#test/index.js';
+import {listRunAttemptsRoute} from './list-run-attempts.js';
+
+const projectAccessState = vi.hoisted(() => ({workspaceId: ''}));
+
+vi.mock('@shipfox/api-projects', () => ({
+  requireProjectAccess: vi.fn(({projectId}) =>
+    Promise.resolve({
+      project: {id: projectId, workspaceId: projectAccessState.workspaceId},
+      workspaceId: projectAccessState.workspaceId,
+    }),
+  ),
+}));
+
+const mockRequireProjectAccess = vi.mocked(requireProjectAccess);
+
+describe('GET /api/workflows/runs/:id/attempts', () => {
+  let app: FastifyInstance;
+  let workspaceId: string;
+  let projectId: string;
+  let definitionId: string;
+
+  beforeAll(async () => {
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    app.addHook('onRequest', (request, _reply, done) => {
+      setUserContext(
+        request,
+        buildUserContext({
+          userId: crypto.randomUUID(),
+          email: 'user@example.com',
+          memberships: [{workspaceId, role: 'admin'}],
+        }),
+      );
+      done();
+    });
+    app.get('/api/workflows/runs/:id/attempts', listRunAttemptsRoute);
+    await app.ready();
+  });
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    projectId = crypto.randomUUID();
+    definitionId = crypto.randomUUID();
+    projectAccessState.workspaceId = workspaceId;
+    mockRequireProjectAccess.mockImplementation(({projectId: requestedProjectId}) =>
+      Promise.resolve({
+        project: {
+          id: requestedProjectId,
+          workspaceId,
+          sourceConnectionId: crypto.randomUUID(),
+          sourceExternalRepositoryId: `repo:${crypto.randomUUID()}`,
+          name: 'Project',
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+        workspaceId,
+      }),
+    );
+  });
+
+  test('returns attempts for the run', async () => {
+    const {source, rerun} = await createLineage();
+
+    const rootRes = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs/${source.id}/attempts`,
+    });
+
+    expect(rootRes.statusCode).toBe(200);
+    expect(
+      rootRes.json().attempts.map((attempt: {workflow_run_id: string}) => attempt.workflow_run_id),
+    ).toEqual([source.id, source.id]);
+    expect(rootRes.json().attempts[0]).toMatchObject({
+      workflow_run_id: source.id,
+      attempt: 1,
+      status: 'failed',
+      rerun_mode: null,
+    });
+    expect(rootRes.json().attempts[1]).toMatchObject({
+      workflow_run_id: source.id,
+      attempt: 2,
+      status: 'pending',
+      rerun_mode: 'all',
+    });
+    expect(rerun.id).toBe(source.id);
+  });
+
+  test('returns one attempt for a run without lineage', async () => {
+    const run = await createRun();
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs/${run.id}/attempts`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().attempts).toHaveLength(1);
+    expect(res.json().attempts[0]).toMatchObject({
+      workflow_run_id: run.id,
+      attempt: 1,
+      rerun_mode: null,
+    });
+  });
+
+  test('returns 404 for a missing or inaccessible run', async () => {
+    const missing = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs/${crypto.randomUUID()}/attempts`,
+    });
+    const run = await createRun();
+    mockRequireProjectAccess.mockRejectedValueOnce(
+      new ClientError('Forbidden', 'forbidden', {status: 403}),
+    );
+
+    const inaccessible = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs/${run.id}/attempts`,
+    });
+
+    expect(missing.statusCode).toBe(404);
+    expect(inaccessible.statusCode).toBe(404);
+  });
+
+  async function createLineage() {
+    const source = await createRun();
+    await updateWorkflowRunStatus({workflowRunId: source.id, status: 'failed', expectedVersion: 1});
+    const rerun = await createRerunWorkflowRun({
+      workflowRunId: source.id,
+      mode: 'all',
+      actorUserId: crypto.randomUUID(),
+    });
+
+    return {source, rerun};
+  }
+
+  function createRun() {
+    return createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: workflowModel({name: 'Deploy'}),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+  }
+});

package/src/presentation/routes/list-run-attempts.ts

@@ -0,0 +1,27 @@
+import {workflowRunAttemptsResponseSchema} from '@shipfox/api-workflows-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {listRunAttempts} from '#db/index.js';
+import {toRunAttemptDto} from '#presentation/dto/index.js';
+import {requireAccessibleRun} from './require-accessible-run.js';
+
+export const listRunAttemptsRoute = defineRoute({
+  method: 'GET',
+  path: '/:id/attempts',
+  description: 'List attempts in a workflow run lineage',
+  schema: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+    response: {
+      200: workflowRunAttemptsResponseSchema,
+    },
+  },
+  handler: async (request) => {
+    const {id} = request.params;
+    const run = await requireAccessibleRun({request, id});
+    const attempts = await listRunAttempts({workflowRunId: run.id, projectId: run.projectId});
+
+    return {attempts: attempts.map(toRunAttemptDto)};
+  },
+});

package/src/presentation/routes/list-runs.test.ts

@@ -0,0 +1,244 @@
+import {buildUserContext, setUserContext} from '@shipfox/api-auth-context';
+import {encodeTimestampIdCursor} from '@shipfox/node-drizzle';
+import {eq} from 'drizzle-orm';
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {db} from '#db/db.js';
+import {workflowRuns} from '#db/schema/workflow-runs.js';
+import {createWorkflowRun, updateWorkflowRunStatus} from '#db/workflow-runs.js';
+import {workflowModel} from '#test/index.js';
+import {listRunsRoute} from './list-runs.js';
+
+const projectAccessState = vi.hoisted(() => ({workspaceId: ''}));
+
+vi.mock('@shipfox/api-projects', () => ({
+  ProjectNotFoundError: class ProjectNotFoundError extends Error {},
+  requireProjectAccess: vi.fn(({projectId}) =>
+    Promise.resolve({
+      project: {id: projectId, workspaceId: projectAccessState.workspaceId},
+      workspaceId: projectAccessState.workspaceId,
+    }),
+  ),
+}));
+
+describe('GET /api/workflows/runs', () => {
+  let app: FastifyInstance;
+  let workspaceId: string;
+  let projectId: string;
+
+  beforeAll(async () => {
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    app.addHook('onRequest', (request, _reply, done) => {
+      setUserContext(
+        request,
+        buildUserContext({
+          userId: crypto.randomUUID(),
+          email: 'user@example.com',
+          memberships: [{workspaceId, role: 'admin'}],
+        }),
+      );
+      done();
+    });
+    app.get('/api/workflows/runs', listRunsRoute);
+    await app.ready();
+  });
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    projectId = crypto.randomUUID();
+    projectAccessState.workspaceId = workspaceId;
+  });
+
+  test('returns runs for a project', async () => {
+    await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId: crypto.randomUUID(),
+      name: 'Test',
+      model: workflowModel({name: 'Test'}),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+    await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId: crypto.randomUUID(),
+      name: 'Test 2',
+      model: workflowModel({name: 'Test 2'}),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.runs).toHaveLength(2);
+    expect(body.runs[0].project_id).toBe(projectId);
+    expect(body.runs[0].name).toBeDefined();
+    expect(body.runs[0].trigger_source).toBe('manual');
+    // The runs list carries run-level timing (null until the run starts).
+    expect(body.runs[0]).toMatchObject({started_at: null, finished_at: null});
+    expect(body.next_cursor).toBeNull();
+    expect(body.filtered_total_count).toBe(2);
+  });
+
+  test('returns empty array for project with no runs', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().runs).toEqual([]);
+    expect(res.json().next_cursor).toBeNull();
+    expect(res.json().filtered_total_count).toBe(0);
+  });
+
+  test('filters runs and returns filtered total count', async () => {
+    const succeeded = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId: crypto.randomUUID(),
+      name: 'Deploy',
+      model: workflowModel({name: 'Deploy'}),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+    await updateWorkflowRunStatus({
+      workflowRunId: succeeded.id,
+      status: 'succeeded',
+      expectedVersion: succeeded.version,
+    });
+    await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId: crypto.randomUUID(),
+      name: 'Nightly',
+      model: workflowModel({name: 'Nightly'}),
+      triggerPayload: {source: 'cron', event: 'tick', scheduleId: 'nightly'},
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}&status=succeeded&trigger_source=manual`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.runs).toHaveLength(1);
+    expect(body.runs[0].id).toBe(succeeded.id);
+    expect(body.filtered_total_count).toBe(1);
+  });
+
+  test('paginates with created_at and id cursor', async () => {
+    const first = await createRunAt({
+      workspaceId,
+      projectId,
+      name: 'First',
+      createdAt: new Date('2026-05-07T00:00:00.000Z'),
+    });
+    const second = await createRunAt({
+      workspaceId,
+      projectId,
+      name: 'Second',
+      createdAt: new Date('2026-05-07T01:00:00.000Z'),
+    });
+    await createRunAt({
+      workspaceId,
+      projectId,
+      name: 'Other',
+      createdAt: new Date('2026-05-07T02:00:00.000Z'),
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}&limit=2`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.runs.map((run: {name: string}) => run.name)).toEqual(['Other', 'Second']);
+    expect(body.next_cursor).toBe(
+      encodeTimestampIdCursor({createdAt: second.createdAt, id: second.id}),
+    );
+
+    const next = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}&limit=2&cursor=${body.next_cursor}`,
+    });
+
+    expect(next.statusCode).toBe(200);
+    expect(next.json().runs.map((run: {id: string}) => run.id)).toEqual([first.id]);
+  });
+
+  test('invalid cursor returns stable client error', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}&cursor=not-a-cursor`,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('invalid-cursor');
+  });
+
+  test('invalid date window returns 400', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}&created_from=2026-05-08T00:00:00.000Z&created_to=2026-05-07T00:00:00.000Z`,
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+});
+
+async function createRunAt({
+  workspaceId,
+  projectId,
+  name,
+  createdAt,
+}: {
+  workspaceId: string;
+  projectId: string;
+  name: string;
+  createdAt: Date;
+}) {
+  const run = await createWorkflowRun({
+    workspaceId,
+    projectId,
+    definitionId: crypto.randomUUID(),
+    name,
+    model: workflowModel({name}),
+    triggerPayload: {
+      source: 'manual',
+      event: 'fire',
+      subscriptionId: crypto.randomUUID(),
+      userId: crypto.randomUUID(),
+    },
+  });
+
+  await db()
+    .update(workflowRuns)
+    .set({createdAt, updatedAt: createdAt})
+    .where(eq(workflowRuns.id, run.id));
+
+  return {...run, createdAt, updatedAt: createdAt};
+}

package/src/presentation/routes/list-runs.ts

@@ -0,0 +1,83 @@
+import {ProjectNotFoundError, requireProjectAccess} from '@shipfox/api-projects';
+import {
+  workflowRunListQuerySchema,
+  workflowRunListResponseSchema,
+} from '@shipfox/api-workflows-dto';
+import {decodeTimestampIdCursor, encodeTimestampIdCursor} from '@shipfox/node-drizzle';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {logger} from '@shipfox/node-opentelemetry';
+import {listWorkflowRuns} from '#db/index.js';
+import {toRunDto} from '#presentation/dto/index.js';
+
+export const listRunsRoute = defineRoute({
+  method: 'GET',
+  path: '/',
+  description: 'List workflow runs for a project',
+  schema: {
+    querystring: workflowRunListQuerySchema,
+    response: {
+      200: workflowRunListResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof ProjectNotFoundError) {
+      throw new ClientError(error.message, 'project-not-found', {status: 404});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const startedAt = performance.now();
+    const {
+      project_id: projectId,
+      limit,
+      cursor,
+      status,
+      definition_id: definitionId,
+      trigger_source: triggerSource,
+      created_from: createdFrom,
+      created_to: createdTo,
+    } = request.query;
+    const decodedCursor = decodeTimestampIdCursor(cursor);
+    if (cursor && !decodedCursor) {
+      throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+    }
+
+    const {project} = await requireProjectAccess({request, projectId});
+
+    const filters = {
+      status,
+      definitionId,
+      triggerSource,
+      createdFrom: createdFrom ? new Date(createdFrom) : undefined,
+      createdTo: createdTo ? new Date(createdTo) : undefined,
+    };
+    const result = await listWorkflowRuns({
+      projectId: project.id,
+      limit,
+      cursor: decodedCursor,
+      filters,
+      includeTotal: !decodedCursor,
+    });
+
+    logger().info(
+      {
+        projectId: project.id,
+        filterKeys: Object.entries(filters)
+          .filter(([, value]) => value !== undefined)
+          .map(([key]) => key),
+        limit,
+        cursorPresent: Boolean(cursor),
+        resultCount: result.runs.length,
+        nextCursorPresent: Boolean(result.nextCursor),
+        durationMs: Math.round(performance.now() - startedAt),
+      },
+      'Listed workflow runs',
+    );
+
+    return {
+      runs: result.runs.map((run) => toRunDto(run)),
+      next_cursor: result.nextCursor ? encodeTimestampIdCursor(result.nextCursor) : null,
+      filtered_total_count: result.filteredTotalCount,
+    };
+  },
+});