@shipfox/api-runners 5.0.0 → 7.0.1

package/src/presentation/routes/heartbeat.ts

@@ -1,79 +1,82 @@
-import {issueJobLeaseToken, jobLeaseParamsFrom} from '@shipfox/api-auth';
 import {requireLeasedJobContext} from '@shipfox/api-auth-context';
+import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
 import {heartbeatBodySchema, heartbeatResponseSchema} from '@shipfox/api-runners-dto';
 import {ClientError, defineRoute} from '@shipfox/node-fastify';
 import {z} from 'zod';
 import {RunningJobExecutionNotFoundError} from '#core/errors.js';
 import {recordHeartbeat} from '#db/job-executions.js';
 
-export const heartbeatRoute = defineRoute({
-  method: 'POST',
-  path: '/:jobId/heartbeat',
-  description:
-    'Keeps a running job execution alive while the runner is still working on it. Returns whether the server has asked the runner to cancel.',
-  schema: {
-    params: z.object({jobId: z.string().uuid()}),
-    body: heartbeatBodySchema.nullish(),
-    response: {
-      200: heartbeatResponseSchema,
+export function createHeartbeatRoute(auth: AuthInterModuleClient) {
+  return defineRoute({
+    method: 'POST',
+    path: '/:jobId/heartbeat',
+    description:
+      'Keeps a running job execution alive while the runner is still working on it. Returns whether the server has asked the runner to cancel.',
+    schema: {
+      params: z.object({jobId: z.string().uuid()}),
+      body: heartbeatBodySchema.nullish(),
+      response: {
+        200: heartbeatResponseSchema,
+      },
     },
-  },
-  errorHandler: (error) => {
-    if (error instanceof RunningJobExecutionNotFoundError) {
-      throw new ClientError(error.message, 'running-job-execution-not-found', {status: 404});
-    }
-    throw error;
-  },
-  handler: async (request) => {
-    const {jobId} = request.params;
-    const lease = requireLeasedJobContext(request);
-    if (lease.jobId !== jobId) {
-      throw new ClientError('Lease token does not match job', 'lease-job-mismatch', {
-        status: 404,
-      });
-    }
+    errorHandler: (error) => {
+      if (error instanceof RunningJobExecutionNotFoundError) {
+        throw new ClientError(error.message, 'running-job-execution-not-found', {status: 404});
+      }
+      throw error;
+    },
+    handler: async (request) => {
+      const {jobId} = request.params;
+      const lease = requireLeasedJobContext(request);
+      if (lease.jobId !== jobId) {
+        throw new ClientError('Lease token does not match job', 'lease-job-mismatch', {
+          status: 404,
+        });
+      }
 
-    const heartbeatResult = await recordHeartbeat({
-      jobExecutionId: lease.jobExecutionId,
-      runnerSessionId: lease.runnerSessionId,
-      toolCapabilities: request.body?.capabilities ?? null,
-    });
+      const heartbeatResult = await recordHeartbeat({
+        jobExecutionId: lease.jobExecutionId,
+        runnerSessionId: lease.runnerSessionId,
+        toolCapabilities: request.body?.capabilities ?? null,
+      });
 
-    if (
-      heartbeatResult.previousToolCapabilities &&
-      !sameToolCapabilities(
-        heartbeatResult.previousToolCapabilities,
-        heartbeatResult.currentToolCapabilities,
-      )
-    ) {
-      request.log.info(
-        {
-          runnerSessionId: lease.runnerSessionId,
-          jobExecutionId: lease.jobExecutionId,
-          previousHarnesses: Object.keys(heartbeatResult.previousToolCapabilities.harnesses),
-          currentHarnesses: heartbeatResult.currentToolCapabilities
-            ? Object.keys(heartbeatResult.currentToolCapabilities.harnesses)
-            : [],
-        },
-        'Runner heartbeat changed advertised tool capabilities',
-      );
-    }
+      if (
+        heartbeatResult.previousToolCapabilities &&
+        !sameToolCapabilities(
+          heartbeatResult.previousToolCapabilities,
+          heartbeatResult.currentToolCapabilities,
+        )
+      ) {
+        request.log.info(
+          {
+            runnerSessionId: lease.runnerSessionId,
+            jobExecutionId: lease.jobExecutionId,
+            previousHarnesses: Object.keys(heartbeatResult.previousToolCapabilities.harnesses),
+            currentHarnesses: heartbeatResult.currentToolCapabilities
+              ? Object.keys(heartbeatResult.currentToolCapabilities.harnesses)
+              : [],
+          },
+          'Runner heartbeat changed advertised tool capabilities',
+        );
+      }
 
-    const leaseToken = await issueJobLeaseToken(
-      jobLeaseParamsFrom(
-        heartbeatResult.runningJobExecution,
-        lease.currentStepId && lease.currentStepAttempt !== undefined
-          ? {
-              currentStepId: lease.currentStepId,
-              currentStepAttempt: lease.currentStepAttempt,
-            }
-          : undefined,
-      ),
-    );
+      const {token: leaseToken} = await auth.mintJobLeaseToken({
+        workflowRunId: heartbeatResult.runningJobExecution.workflowRunId,
+        workflowRunAttemptId: heartbeatResult.runningJobExecution.workflowRunAttemptId,
+        jobId: heartbeatResult.runningJobExecution.jobId,
+        jobExecutionId: heartbeatResult.runningJobExecution.jobExecutionId,
+        projectId: heartbeatResult.runningJobExecution.projectId,
+        workspaceId: heartbeatResult.runningJobExecution.workspaceId,
+        runnerSessionId: heartbeatResult.runningJobExecution.runnerSessionId,
+        ...(lease.currentStepId && lease.currentStepAttempt !== undefined
+          ? {currentStepId: lease.currentStepId, currentStepAttempt: lease.currentStepAttempt}
+          : {}),
+      });
 
-    return {cancel: heartbeatResult.cancellationRequested, lease_token: leaseToken};
-  },
-});
+      return {cancel: heartbeatResult.cancellationRequested, lease_token: leaseToken};
+    },
+  });
+}
 
 function sameToolCapabilities(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);

package/src/presentation/routes/index.ts

@@ -5,62 +5,90 @@ import {
   AUTH_RUNNER_SESSION,
   AUTH_USER,
 } from '@shipfox/api-auth-context';
+import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
 import type {RouteGroup} from '@shipfox/node-fastify';
+import type {CreateRunnersModuleOptions} from '#installation-provisioning.js';
+import {assignRunnerInstancesRoute} from './assign-runner-instances.js';
 import {createManualRegistrationTokenRoute} from './create-manual-registration-token.js';
 import {createProvisionerTokenRoute} from './create-provisioner-token.js';
 import {getProvisionerMeRoute} from './get-provisioner-me.js';
-import {heartbeatRoute} from './heartbeat.js';
+import {createHeartbeatRoute} from './heartbeat.js';
 import {listActiveProvisionersRoute} from './list-active-provisioners.js';
 import {listActiveRunnersRoute} from './list-active-runners.js';
 import {listManualRegistrationTokensRoute} from './list-manual-registration-tokens.js';
 import {listProvisionerTokensRoute} from './list-provisioner-tokens.js';
-import {mintRegistrationTokensRoute} from './mint-registration-tokens.js';
-import {pollDemandRoute} from './poll-demand.js';
-import {reconcileProvisionedRunnersRoute} from './reconcile-provisioned-runners.js';
-import {registerRoute} from './register.js';
-import {reportProvisionedRunnersRoute} from './report-provisioned-runners.js';
-import {requestJobRoute} from './request-job.js';
+import {createPollDemandRoute, pollDemandRoute} from './poll-demand.js';
+import {reconcileRunnerInstancesRoute} from './reconcile-runner-instances.js';
+import {createRegisterRoute} from './register.js';
+import {reportRunnerInstancesRoute} from './report-runner-instances.js';
+import {createRequestJobRoute} from './request-job.js';
 import {revokeManualRegistrationTokenRoute} from './revoke-manual-registration-token.js';
 import {revokeProvisionerTokenRoute} from './revoke-provisioner-token.js';
+import {
+  attachRunnerControlProviderIdRoute,
+  attachRunnerInstanceProviderIdRoute,
+  createRunnerInstancesRoute,
+  enrollRunnerRoute,
+  exchangeRunnerBootstrapRoute,
+  runnerAssignmentPollRoute,
+  runnerControlHeartbeatRoute,
+} from './runner-enrollment.js';
 
-const runnerOnlyRoutes: RouteGroup[] = [
-  {
-    prefix: '/workspaces/:workspaceId/runners/manual-registration-tokens',
-    auth: AUTH_USER,
-    routes: [
-      listManualRegistrationTokensRoute,
-      createManualRegistrationTokenRoute,
-      revokeManualRegistrationTokenRoute,
-    ],
-  },
-  {
-    prefix: '/workspaces/:workspaceId/runners/active',
-    auth: AUTH_USER,
-    routes: [listActiveRunnersRoute],
-  },
-  {
-    prefix: '/runners',
-    auth: AUTH_RUNNER_REGISTRATION_TOKEN,
-    routes: [registerRoute],
-  },
-  {
-    prefix: '/runners/jobs',
-    auth: AUTH_RUNNER_SESSION,
-    routes: [requestJobRoute],
-  },
-  {
-    prefix: '/runners/jobs',
-    auth: AUTH_LEASED_JOB,
-    routes: [heartbeatRoute],
-  },
+function createRunnerOnlyRoutes(auth: AuthInterModuleClient): RouteGroup[] {
+  return [
+    {
+      prefix: '/workspaces/:workspaceId/runners/manual-registration-tokens',
+      auth: AUTH_USER,
+      routes: [
+        listManualRegistrationTokensRoute,
+        createManualRegistrationTokenRoute,
+        revokeManualRegistrationTokenRoute,
+      ],
+    },
+    {
+      prefix: '/workspaces/:workspaceId/runners/active',
+      auth: AUTH_USER,
+      routes: [listActiveRunnersRoute],
+    },
+    {
+      prefix: '/runners',
+      auth: AUTH_RUNNER_REGISTRATION_TOKEN,
+      routes: [createRegisterRoute(auth)],
+    },
+    {
+      prefix: '/runners/jobs',
+      auth: AUTH_RUNNER_SESSION,
+      routes: [createRequestJobRoute(auth)],
+    },
+    {
+      prefix: '/runners/jobs',
+      auth: AUTH_LEASED_JOB,
+      routes: [createHeartbeatRoute(auth)],
+    },
+    {
+      prefix: '/provisioners',
+      auth: AUTH_PROVISIONER_TOKEN,
+      routes: [
+        pollDemandRoute,
+        createRunnerInstancesRoute,
+        attachRunnerInstanceProviderIdRoute,
+        assignRunnerInstancesRoute,
+        reportRunnerInstancesRoute,
+        reconcileRunnerInstancesRoute,
+      ],
+    },
+  ];
+}
+
+const runnerControlRoutes: RouteGroup[] = [
+  {prefix: '/runner-enrollment', routes: [exchangeRunnerBootstrapRoute]},
   {
-    prefix: '/provisioners',
-    auth: AUTH_PROVISIONER_TOKEN,
+    prefix: '/runner-control',
     routes: [
-      pollDemandRoute,
-      mintRegistrationTokensRoute,
-      reportProvisionedRunnersRoute,
-      reconcileProvisionedRunnersRoute,
+      enrollRunnerRoute,
+      attachRunnerControlProviderIdRoute,
+      runnerControlHeartbeatRoute,
+      runnerAssignmentPollRoute,
     ],
   },
 ];
@@ -83,4 +111,23 @@ export const provisionerRoutes: RouteGroup[] = [
   },
 ];
 
-export const runnerRoutes: RouteGroup[] = [...runnerOnlyRoutes, ...provisionerRoutes];
+export function createRunnerRoutes(
+  auth: AuthInterModuleClient,
+  options: CreateRunnersModuleOptions = {},
+): RouteGroup[] {
+  const runnerOnlyRoutes = createRunnerOnlyRoutes(auth);
+  return [
+    ...runnerOnlyRoutes.map((route) =>
+      route.routes.includes(pollDemandRoute)
+        ? {
+            ...route,
+            routes: route.routes.map((r) =>
+              r === pollDemandRoute ? createPollDemandRoute(options) : r,
+            ),
+          }
+        : route,
+    ),
+    ...runnerControlRoutes,
+    ...provisionerRoutes,
+  ];
+}

package/src/presentation/routes/list-active-runners.test.ts

@@ -12,10 +12,10 @@ import type {AuthMethod} from '@shipfox/node-fastify';
 import {ClientError, closeApp, createApp} from '@shipfox/node-fastify';
 import type {FastifyInstance, FastifyRequest} from 'fastify';
 import {db} from '#db/db.js';
-import {provisionedRunners} from '#db/schema/provisioned-runners.js';
+import {providerRunners} from '#db/schema/runner-instances.js';
 import {runningJobExecutions} from '#db/schema/running-job-executions.js';
-import {runnerSessionFactory} from '#test/index.js';
-import {runnerRoutes} from './index.js';
+import {runnerSessionFactory, runnersTestAuthClient} from '#test/index.js';
+import {createRunnerRoutes} from './index.js';
 
 let authenticatedMemberships: ReadonlyArray<UserContextMembership> = [];
 
@@ -59,7 +59,7 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
         passthroughAuth(AUTH_LEASED_JOB),
         passthroughAuth(AUTH_PROVISIONER_TOKEN),
       ],
-      routes: runnerRoutes,
+      routes: createRunnerRoutes(runnersTestAuthClient),
       swagger: false,
     });
     await app.ready();
@@ -73,11 +73,11 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
     const runnerSession = await runnerSessionFactory.create({workspaceId});
     const runnerSessionId = runnerSession.id;
     await db()
-      .insert(provisionedRunners)
+      .insert(providerRunners)
       .values({
         workspaceId,
         provisionerId: crypto.randomUUID(),
-        provisionedRunnerId: 'provisioned-runner-1',
+        providerRunnerId: 'provisioned-runner-1',
         labels: ['linux'],
         state: 'running',
         runnerSessionId,
@@ -108,7 +108,7 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
     expect(res.json().runners).toEqual([
       expect.objectContaining({
         runner_session_id: runnerSessionId,
-        provisioned_runner_id: 'provisioned-runner-1',
+        provider_runner_id: 'provisioned-runner-1',
         state: 'busy',
         labels: ['linux'],
       }),
@@ -121,11 +121,11 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
     const firstJobId = crypto.randomUUID();
     const secondJobId = crypto.randomUUID();
     await db()
-      .insert(provisionedRunners)
+      .insert(providerRunners)
       .values({
         workspaceId,
         provisionerId: crypto.randomUUID(),
-        provisionedRunnerId: 'provisioned-runner-1',
+        providerRunnerId: 'provisioned-runner-1',
         labels: ['linux'],
         state: 'running',
         runnerSessionId,
@@ -172,13 +172,13 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
       expect.arrayContaining([
         expect.objectContaining({
           runner_session_id: runnerSessionId,
-          provisioned_runner_id: 'provisioned-runner-1',
+          provider_runner_id: 'provisioned-runner-1',
           state: 'busy',
           job_id: firstJobId,
         }),
         expect.objectContaining({
           runner_session_id: runnerSessionId,
-          provisioned_runner_id: 'provisioned-runner-1',
+          provider_runner_id: 'provisioned-runner-1',
           state: 'busy',
           job_id: secondJobId,
         }),
@@ -192,11 +192,11 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
     const runnerSessionId = runnerSession.id;
     const jobId = crypto.randomUUID();
     await db()
-      .insert(provisionedRunners)
+      .insert(providerRunners)
       .values({
         workspaceId,
         provisionerId,
-        provisionedRunnerId: 'provisioned-runner-1',
+        providerRunnerId: 'provisioned-runner-1',
         labels: ['linux'],
         state: 'running',
         runnerSessionId: null,
@@ -214,7 +214,7 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
         projectId: crypto.randomUUID(),
         runnerSessionId,
         provisionerId,
-        provisionedRunnerId: 'provisioned-runner-1',
+        providerRunnerId: 'provisioned-runner-1',
         requiredLabels: ['linux'],
         runnerLabels: ['linux'],
       });
@@ -229,7 +229,7 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
     expect(res.json().runners).toEqual([
       expect.objectContaining({
         runner_session_id: runnerSessionId,
-        provisioned_runner_id: 'provisioned-runner-1',
+        provider_runner_id: 'provisioned-runner-1',
         provisioner_id: provisionerId,
         state: 'busy',
         job_id: jobId,
@@ -253,7 +253,7 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
         projectId: crypto.randomUUID(),
         runnerSessionId,
         provisionerId,
-        provisionedRunnerId: 'provisioned-runner-1',
+        providerRunnerId: 'provisioned-runner-1',
         requiredLabels: ['linux'],
         runnerLabels: ['linux'],
       });
@@ -268,7 +268,7 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
     expect(res.json().runners).toEqual([
       expect.objectContaining({
         runner_session_id: runnerSessionId,
-        provisioned_runner_id: 'provisioned-runner-1',
+        provider_runner_id: 'provisioned-runner-1',
         provisioner_id: provisionerId,
         state: 'busy',
         job_id: jobId,
@@ -284,12 +284,12 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
     const older = new Date(Date.now() - 1000);
     const newer = new Date();
     await db()
-      .insert(provisionedRunners)
+      .insert(providerRunners)
       .values([
         {
           workspaceId,
           provisionerId,
-          provisionedRunnerId: 'provisioned-runner-b',
+          providerRunnerId: 'provisioned-runner-b',
           labels: ['linux'],
           state: 'running',
           runnerSessionId,
@@ -300,7 +300,7 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
         {
           workspaceId,
           provisionerId,
-          provisionedRunnerId: 'provisioned-runner-a',
+          providerRunnerId: 'provisioned-runner-a',
           labels: ['linux'],
           state: 'running',
           runnerSessionId: null,
@@ -320,7 +320,7 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
         projectId: crypto.randomUUID(),
         runnerSessionId,
         provisionerId,
-        provisionedRunnerId: 'provisioned-runner-a',
+        providerRunnerId: 'provisioned-runner-a',
         requiredLabels: ['linux'],
         runnerLabels: ['linux'],
       });
@@ -338,13 +338,13 @@ describe('GET /workspaces/:workspaceId/runners/active', () => {
       expect.arrayContaining([
         expect.objectContaining({
           runner_session_id: runnerSessionId,
-          provisioned_runner_id: 'provisioned-runner-a',
+          provider_runner_id: 'provisioned-runner-a',
           state: 'busy',
           job_id: jobId,
         }),
         expect.objectContaining({
           runner_session_id: runnerSessionId,
-          provisioned_runner_id: 'provisioned-runner-b',
+          provider_runner_id: 'provisioned-runner-b',
           state: 'running',
           job_id: null,
         }),

package/src/presentation/routes/manual-registration-tokens.test.ts

@@ -18,8 +18,8 @@ import {db} from '#db/db.js';
 import {revokeManualRegistrationToken} from '#db/manual-registration-tokens.js';
 import {manualRegistrationTokens} from '#db/schema/manual-registration-tokens.js';
 import {createRunnerRegistrationTokenAuthMethod} from '#presentation/auth/index.js';
-import {manualRegistrationTokenFactory} from '#test/index.js';
-import {runnerRoutes} from './index.js';
+import {manualRegistrationTokenFactory, runnersTestAuthClient} from '#test/index.js';
+import {createRunnerRoutes} from './index.js';
 
 let authenticatedMemberships: ReadonlyArray<UserContextMembership> = [];
 
@@ -63,7 +63,7 @@ describe('manual registration token routes', () => {
         createLeaseTokenAuthMethod(),
         fakeProvisionerAuth,
       ],
-      routes: runnerRoutes,
+      routes: createRunnerRoutes(runnersTestAuthClient),
       swagger: false,
     });
     await app.ready();
@@ -74,6 +74,7 @@ describe('manual registration token routes', () => {
   });
 
   test('uses the expected auth method for each runner route group', () => {
+    const runnerRoutes = createRunnerRoutes(runnersTestAuthClient);
     expect(runnerRoutes[0]?.auth).toBe(AUTH_USER);
     expect(runnerRoutes[1]?.auth).toBe(AUTH_USER);
     expect(runnerRoutes[2]?.auth).toBe(AUTH_RUNNER_REGISTRATION_TOKEN);

package/src/presentation/routes/poll-demand-release.test.ts

@@ -15,8 +15,8 @@ describe('POST /provisioners/demand/poll reservation cleanup', () => {
     const listProvisionerTerminateIntentRowsTx = vi
       .fn()
       .mockRejectedValueOnce(new Error('db unavailable'));
-    vi.doMock('#db/provisioned-runners.js', async (importOriginal) => ({
-      ...(await importOriginal<typeof import('#db/provisioned-runners.js')>()),
+    vi.doMock('#db/runner-instances.js', async (importOriginal) => ({
+      ...(await importOriginal<typeof import('#db/runner-instances.js')>()),
       listProvisionerTerminateIntentRowsTx,
     }));
     const {pollDemandRoute} = await import('./poll-demand.js');
@@ -28,7 +28,7 @@ describe('POST /provisioners/demand/poll reservation cleanup', () => {
         if (extractBearerToken(request.headers.authorization) !== VALID_PROVISIONER_TOKEN) {
           throw new Error('unauthorized');
         }
-        setProvisionerContext(request, {workspaceId, provisionerTokenId});
+        setProvisionerContext(request, {scope: 'workspace', workspaceId, provisionerTokenId});
         return Promise.resolve();
       },
     };
@@ -72,7 +72,7 @@ describe('POST /provisioners/demand/poll reservation cleanup', () => {
       expect(res.statusCode).toBe(500);
       expect(reservationRows).toHaveLength(0);
     } finally {
-      vi.doUnmock('#db/provisioned-runners.js');
+      vi.doUnmock('#db/runner-instances.js');
       vi.resetModules();
       await closeApp();
     }