@shipfox/api-workflows 2.0.0

package/src/presentation/routes/cancel-run.test.ts

@@ -0,0 +1,156 @@
+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 {WorkflowRunNotFoundError} from '#core/errors.js';
+import {getJobsByWorkflowRunId, getWorkflowRunById, updateWorkflowRunStatus} from '#db/index.js';
+import {createWorkflowRun} from '#db/workflow-runs.js';
+import {workflowModel} from '#test/index.js';
+import {cancelRunRoute} from './cancel-run.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('POST /api/workflows/runs/:id/cancel', () => {
+  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.post('/api/workflows/runs/:id/cancel', cancelRunRoute);
+    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 200 and cancels a running run', async () => {
+    const run = await createRun();
+    await updateWorkflowRunStatus({workflowRunId: run.id, status: 'running', expectedVersion: 1});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/api/workflows/runs/${run.id}/cancel`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toMatchObject({id: run.id, status: 'cancelled'});
+    expect(await getWorkflowRunById(run.id)).toMatchObject({status: 'cancelled'});
+    const [job] = await getJobsByWorkflowRunId(run.id);
+    expect(job).toMatchObject({status: 'cancelled', statusReason: 'run_cancelled'});
+  });
+
+  test('returns 404 for an unknown run', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: `/api/workflows/runs/${crypto.randomUUID()}/cancel`,
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+
+  test('maps a run disappearing during cancellation to 404', () => {
+    let mapped: unknown;
+    const errorHandler = cancelRunRoute.errorHandler as (error: Error) => void;
+
+    try {
+      errorHandler(new WorkflowRunNotFoundError(crypto.randomUUID()));
+    } catch (error) {
+      mapped = error;
+    }
+
+    expect(mapped).toBeInstanceOf(ClientError);
+    expect(mapped).toMatchObject({status: 404, code: 'not-found'});
+  });
+
+  test('returns 404 when project access is denied', async () => {
+    const run = await createRun();
+    mockRequireProjectAccess.mockRejectedValueOnce(
+      new ClientError('Forbidden', 'forbidden', {status: 403}),
+    );
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/api/workflows/runs/${run.id}/cancel`,
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+    expect(await getWorkflowRunById(run.id)).toMatchObject({status: 'pending'});
+  });
+
+  test('returns 409 for a terminal run', async () => {
+    const run = await createRun();
+    await updateWorkflowRunStatus({workflowRunId: run.id, status: 'succeeded', expectedVersion: 1});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/api/workflows/runs/${run.id}/cancel`,
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('run-already-finished');
+    expect(await getWorkflowRunById(run.id)).toMatchObject({status: 'succeeded'});
+  });
+
+  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/cancel-run.ts

@@ -0,0 +1,37 @@
+import {workflowRunDtoSchema} from '@shipfox/api-workflows-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {WorkflowRunNotCancellableError, WorkflowRunNotFoundError} from '#core/errors.js';
+import {cancelWorkflowRun} from '#db/index.js';
+import {toRunDto} from '#presentation/dto/index.js';
+import {requireAccessibleRun} from './require-accessible-run.js';
+
+export const cancelRunRoute = defineRoute({
+  method: 'POST',
+  path: '/:id/cancel',
+  description: 'Cancel an in-progress workflow run',
+  schema: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+    response: {
+      200: workflowRunDtoSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof WorkflowRunNotCancellableError) {
+      throw new ClientError(error.message, 'run-already-finished', {status: 409});
+    }
+    if (error instanceof WorkflowRunNotFoundError) {
+      throw new ClientError('Run not found', 'not-found', {status: 404});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const {id} = request.params;
+    const run = await requireAccessibleRun({request, id});
+
+    const cancelled = await cancelWorkflowRun({workflowRunId: run.id});
+    return toRunDto(cancelled);
+  },
+});

package/src/presentation/routes/checkout-token.test.ts

@@ -0,0 +1,366 @@
+import {createLeaseTokenAuthMethod} from '@shipfox/api-auth';
+import {
+  type CheckoutSpec,
+  IntegrationCheckoutUnsupportedError,
+  IntegrationConnectionInactiveError,
+  IntegrationProviderError,
+  type IntegrationSourceControlService,
+} from '@shipfox/api-integration-core';
+import {getProjectById} from '@shipfox/api-projects';
+import {closeApp, createApp, type FastifyInstance} from '@shipfox/node-fastify';
+import {createCapturingLogger} from '@shipfox/node-log/test';
+import {clearSourceControl, setSourceControl} from '#core/source-control.js';
+import {jobFactory} from '#test/factories/job.js';
+import {projectFactory} from '#test/factories/project.js';
+import {mintActiveLeaseToken} from '#test/fixtures/active-lease-token.js';
+import {mintLeaseToken} from '#test/fixtures/lease-token.js';
+import {leaseTokenRouteGroup} from './index.js';
+
+vi.mock('@shipfox/api-projects', () => ({getProjectById: vi.fn()}));
+const mockGetProjectById = vi.mocked(getProjectById);
+
+const URL = '/runs/jobs/current/checkout-token';
+
+const githubSpec = (token: string): CheckoutSpec => ({
+  repositoryUrl: 'https://github.com/acme/repo.git',
+  ref: 'main',
+  credentials: {username: 'x-access-token', token, expiresAt: new Date('2026-06-10T12:00:00.000Z')},
+});
+
+describe('POST /runs/jobs/current/checkout-token', () => {
+  let app: FastifyInstance;
+  const createCheckoutSpec = vi.fn();
+  const {logger, lines: logLines, clear: clearLogLines} = createCapturingLogger();
+
+  beforeAll(async () => {
+    setSourceControl({createCheckoutSpec} as unknown as IntegrationSourceControlService);
+    app = await createApp({
+      auth: [createLeaseTokenAuthMethod()],
+      routes: [leaseTokenRouteGroup],
+      swagger: false,
+      fastifyOptions: {loggerInstance: logger},
+    });
+    await app.ready();
+  });
+
+  beforeEach(() => {
+    createCheckoutSpec.mockReset();
+    mockGetProjectById.mockReset();
+    clearLogLines();
+  });
+
+  afterAll(async () => {
+    await closeApp();
+    clearSourceControl();
+  });
+
+  describe('lease-token auth', () => {
+    test('rejects a request without an Authorization header', async () => {
+      const res = await app.inject({method: 'POST', url: URL});
+
+      expect(res.statusCode).toBe(401);
+      expect(res.json().code).toBe('unauthorized');
+    });
+
+    test('rejects an expired token', async () => {
+      const token = await mintLeaseToken({
+        jobId: crypto.randomUUID(),
+        jobExecutionId: crypto.randomUUID(),
+        expiresIn: '-1s',
+      });
+
+      const res = await app.inject({
+        method: 'POST',
+        url: URL,
+        headers: {authorization: `Bearer ${token}`},
+      });
+
+      expect(res.statusCode).toBe(401);
+    });
+
+    test('rejects a token with the wrong audience', async () => {
+      const token = await mintLeaseToken({
+        jobId: crypto.randomUUID(),
+        jobExecutionId: crypto.randomUUID(),
+        audience: 'user-session',
+      });
+
+      const res = await app.inject({
+        method: 'POST',
+        url: URL,
+        headers: {authorization: `Bearer ${token}`},
+      });
+
+      expect(res.statusCode).toBe(401);
+    });
+  });
+
+  test('returns basic auth for a GitHub-style spec with credentials', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    createCheckoutSpec.mockResolvedValue(githubSpec('ghs-secret-token'));
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['cache-control']).toBe('no-store');
+    expect(res.json()).toEqual({
+      repository_url: 'https://github.com/acme/repo.git',
+      ref: 'main',
+      auth: {
+        kind: 'basic',
+        username: 'x-access-token',
+        token: 'ghs-secret-token',
+        expires_at: '2026-06-10T12:00:00.000Z',
+        carry: 'header',
+        host: 'github.com',
+        persist: true,
+      },
+    });
+  });
+
+  test('omits auth for a credential-free (debug) spec', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://example.com/acme/repo.git',
+      ref: 'trunk',
+    } satisfies CheckoutSpec);
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({
+      repository_url: 'https://example.com/acme/repo.git',
+      ref: 'trunk',
+    });
+  });
+
+  test('returns 404 for a token without an active lease', async () => {
+    const token = await mintLeaseToken({
+      jobId: crypto.randomUUID(),
+      jobExecutionId: crypto.randomUUID(),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('lease-not-active');
+    expect(createCheckoutSpec).not.toHaveBeenCalled();
+  });
+
+  test.each([
+    'succeeded',
+    'failed',
+    'cancelled',
+    'skipped',
+  ] as const)('returns 404 and mints nothing without an active lease for %s job', async (status) => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id, status}});
+    const token = await mintLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('lease-not-active');
+    expect(createCheckoutSpec).not.toHaveBeenCalled();
+  });
+
+  test('returns checkout credentials while the parent job projection is still pending', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create(
+      {},
+      {transient: {projectId: project.id, status: 'pending'}},
+    );
+    createCheckoutSpec.mockResolvedValue(githubSpec('token'));
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(createCheckoutSpec).toHaveBeenCalledWith(
+      expect.objectContaining({connectionId: project.sourceConnectionId}),
+    );
+  });
+
+  test('ignores a hostile workflowRunAttemptId claim and resolves via the job row', async () => {
+    const projectA = projectFactory.build();
+    const projectB = projectFactory.build();
+    const projectsById = new Map([
+      [projectA.id, projectA],
+      [projectB.id, projectB],
+    ]);
+    mockGetProjectById.mockImplementation((id: string) => Promise.resolve(projectsById.get(id)));
+    const jobA = await jobFactory.create({}, {transient: {projectId: projectA.id}});
+    const jobB = await jobFactory.create({}, {transient: {projectId: projectB.id}});
+    createCheckoutSpec.mockResolvedValue(githubSpec('token'));
+    const token = await mintActiveLeaseToken({
+      jobId: jobA.id,
+      token: {workflowRunAttemptId: jobB.workflowRunAttemptId},
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(createCheckoutSpec).toHaveBeenCalledWith(
+      expect.objectContaining({connectionId: projectA.sourceConnectionId}),
+    );
+    expect(createCheckoutSpec).not.toHaveBeenCalledWith(
+      expect.objectContaining({connectionId: projectB.sourceConnectionId}),
+    );
+  });
+
+  test('passes the project workspace, never the lease workspace claim', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    createCheckoutSpec.mockResolvedValue(githubSpec('token'));
+    const token = await mintActiveLeaseToken({
+      jobId: job.id,
+      token: {workspaceId: crypto.randomUUID()},
+    });
+
+    await app.inject({method: 'POST', url: URL, headers: {authorization: `Bearer ${token}`}});
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith(
+      expect.objectContaining({workspaceId: project.workspaceId}),
+    );
+  });
+
+  test('returns 404 when the run has no project linkage', async () => {
+    mockGetProjectById.mockResolvedValue(undefined);
+    const project = {id: crypto.randomUUID(), workspaceId: crypto.randomUUID()};
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('checkout-unavailable');
+  });
+
+  test('maps a rate-limited provider error to 429 with retry_after_seconds', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    createCheckoutSpec.mockRejectedValue(
+      new IntegrationProviderError('rate-limited', 'slow down', 60),
+    );
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(429);
+    expect(res.json().code).toBe('rate-limited');
+    expect(res.json().details.retry_after_seconds).toBe(60);
+  });
+
+  test('maps an inactive connection error to 422', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    createCheckoutSpec.mockRejectedValue(
+      new IntegrationConnectionInactiveError(project.sourceConnectionId),
+    );
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(422);
+  });
+
+  test('maps an unsupported-checkout provider error to 422', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    createCheckoutSpec.mockRejectedValue(new IntegrationCheckoutUnsupportedError('github'));
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(422);
+    expect(res.json().code).toBe('integration-checkout-unsupported');
+  });
+
+  test('surfaces an unexpected provider error as a 500 server-error', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    createCheckoutSpec.mockRejectedValue(new Error('unexpected provider failure'));
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().code).toBe('server-error');
+  });
+
+  test('never writes the minted token to a log line', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    const secret = 'ghs-super-secret-token-value';
+    createCheckoutSpec.mockResolvedValue(githubSpec(secret));
+    const token = await mintActiveLeaseToken({jobId: job.id});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().auth.token).toBe(secret);
+    expect(logLines.join('\n')).not.toContain(secret);
+  });
+});

package/src/presentation/routes/checkout-token.ts

@@ -0,0 +1,61 @@
+import {requireLeasedJobContext} from '@shipfox/api-auth-context';
+import {integrationRouteErrorHandler} from '@shipfox/api-integration-core';
+import {isJobLeaseActive} from '@shipfox/api-runners';
+import {checkoutTokenResponseSchema} from '@shipfox/api-workflows-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {createJobCheckoutSpec} from '#core/checkout.js';
+import {
+  CheckoutIntentUnresolvedError,
+  JobNotFoundError,
+  WorkflowRunNotFoundError,
+} from '#core/errors.js';
+import {sourceControl} from '#core/source-control.js';
+import {toCheckoutTokenDto} from '#presentation/dto/checkout-token.js';
+
+export const checkoutTokenRoute = defineRoute({
+  method: 'POST',
+  path: '/checkout-token',
+  description:
+    "Exchanges the runner's job lease for short-lived, read-only checkout credentials for the job's repository. The job is identified by the access token, so no job ID is needed. The checkout target is resolved server-side from the job's run and project; no credential material is stored on the job or run. Returns the repository URL, ref, and (when the provider needs auth) a short-lived credential that expires soon.",
+  schema: {
+    response: {
+      200: checkoutTokenResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof JobNotFoundError) {
+      throw new ClientError(error.message, 'job-not-found', {status: 404});
+    }
+    if (error instanceof WorkflowRunNotFoundError) {
+      throw new ClientError(error.message, 'run-not-found', {status: 404});
+    }
+    if (error instanceof CheckoutIntentUnresolvedError) {
+      throw new ClientError(error.message, 'checkout-unavailable', {status: 404});
+    }
+    // Connection and provider errors (and the structural provider-error detection)
+    // map through the shared handler, which re-throws unknowns to the global handler.
+    return integrationRouteErrorHandler(error);
+  },
+  handler: async (request, reply) => {
+    const leasedJob = requireLeasedJobContext(request);
+
+    const leaseIsActive = await isJobLeaseActive({
+      jobId: leasedJob.jobId,
+      jobExecutionId: leasedJob.jobExecutionId,
+      runnerSessionId: leasedJob.runnerSessionId,
+    });
+    if (!leaseIsActive) {
+      throw new ClientError('Job lease is no longer active', 'lease-not-active', {status: 404});
+    }
+
+    const checkout = await createJobCheckoutSpec({
+      jobId: leasedJob.jobId,
+      sourceControl: sourceControl(),
+    });
+
+    // The body carries short-lived git credentials; forbid any intermediary or
+    // client cache from retaining them.
+    reply.header('cache-control', 'no-store');
+    return toCheckoutTokenDto(checkout.spec, {persist: checkout.persistCredentials});
+  },
+});