@shipfox/api-runners 10.0.0 → 10.2.0

package/src/presentation/routes/admin-runner-instances.ts

@@ -0,0 +1,67 @@
+import {AUTH_USER, requireUserContext} from '@shipfox/api-auth-context';
+import {
+  type AuthInterModuleClient,
+  authInterModuleContract,
+} from '@shipfox/api-auth-dto/inter-module';
+import {
+  listRunnerAdministratorInstancesQuerySchema,
+  listRunnerAdministratorInstancesResponseSchema,
+} from '@shipfox/api-runners-dto';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
+import {decodeTimestampIdCursor, encodeTimestampIdCursor} from '@shipfox/node-drizzle';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {listRunnerAdministratorInstances} from '#core/admin-runner-instances.js';
+import {toRunnerAdministratorInstanceDto} from '#presentation/dto/admin-runner-instances.js';
+
+function translateAdminRunnerInstancesRouteError(error: unknown): never {
+  if (
+    isInterModuleKnownError(authInterModuleContract.methods.requireAdminRole, error) &&
+    error.code === 'admin-role-required'
+  ) {
+    throw new ClientError('Administrator observer role required', 'forbidden', {
+      status: 403,
+      details: {required_role: error.details.requiredRole},
+    });
+  }
+
+  throw error;
+}
+
+export function createAdminRunnerInstancesRoute(
+  auth: Pick<AuthInterModuleClient, 'requireAdminRole'>,
+) {
+  return defineRoute({
+    method: 'GET',
+    path: '/',
+    auth: AUTH_USER,
+    description: 'List bounded safe installation-managed runner instances for administrators.',
+    schema: {
+      querystring: listRunnerAdministratorInstancesQuerySchema,
+      response: {200: listRunnerAdministratorInstancesResponseSchema},
+    },
+    errorHandler: translateAdminRunnerInstancesRouteError,
+    handler: async (request) => {
+      const actor = requireUserContext(request);
+      await auth.requireAdminRole({userId: actor.userId, minimumRole: 'admin-observer'});
+
+      const {state, assignment, label, limit, cursor} = request.query;
+      const decodedCursor = decodeTimestampIdCursor(cursor);
+      if (cursor !== undefined && !decodedCursor) {
+        throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+      }
+
+      const result = await listRunnerAdministratorInstances({
+        state,
+        assignment,
+        label,
+        limit,
+        ...(decodedCursor ? {cursor: decodedCursor} : {}),
+      });
+
+      return {
+        runners: result.runners.map(toRunnerAdministratorInstanceDto),
+        next_cursor: result.nextCursor ? encodeTimestampIdCursor(result.nextCursor) : null,
+      };
+    },
+  });
+}

package/src/presentation/routes/index.ts

@@ -8,6 +8,8 @@ import {
 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 {createAdminProvisionerTokenRoutes} from './admin-provisioner-tokens.js';
+import {createAdminRunnerInstancesRoute} from './admin-runner-instances.js';
 import {assignRunnerInstancesRoute} from './assign-runner-instances.js';
 import {createManualRegistrationTokenRoute} from './create-manual-registration-token.js';
 import {createProvisionerTokenRoute} from './create-provisioner-token.js';
@@ -77,6 +79,12 @@ function createRunnerOnlyRoutes(auth: AuthInterModuleClient): RouteGroup[] {
         reconcileRunnerInstancesRoute,
       ],
     },
+    {
+      prefix: '/admin/runners/instances',
+      auth: AUTH_USER,
+      routes: [createAdminRunnerInstancesRoute(auth)],
+    },
+    createAdminProvisionerTokenRoutes(auth),
   ];
 }
 

package/src/presentation/routes/runner-enrollment.test.ts

@@ -23,7 +23,10 @@ import {
   runnersTestAuthClient,
 } from '#test/index.js';
 import {createRunnerRoutes} from './index.js';
-import {pollForRunnerActivationToken} from './runner-enrollment.js';
+import {
+  pollForRunnerActivationToken,
+  resolveRunnerAssignmentPollWaitSeconds,
+} from './runner-enrollment.js';
 
 const token = 'provisioner-test-token';
 const fakeUserAuth: AuthMethod = {name: AUTH_USER, authenticate: () => Promise.resolve()};
@@ -65,6 +68,14 @@ describe('runner enrollment control plane', () => {
     provisionerId = crypto.randomUUID();
   });
 
+  it('uses the requested assignment wait below the server cap and caps larger requests', () => {
+    expect(resolveRunnerAssignmentPollWaitSeconds(5)).toBe(5);
+    expect(resolveRunnerAssignmentPollWaitSeconds(0)).toBe(1);
+    expect(resolveRunnerAssignmentPollWaitSeconds(30)).toBe(30);
+    expect(resolveRunnerAssignmentPollWaitSeconds(31)).toBe(30);
+    expect(resolveRunnerAssignmentPollWaitSeconds(undefined)).toBe(30);
+  });
+
   it('creates a hashed one-use bootstrap token and restricts its control session to its instance', async () => {
     const created = await app.inject({
       method: 'POST',
@@ -370,7 +381,7 @@ describe('runner enrollment control plane', () => {
 
     const assignment = await app.inject({
       method: 'GET',
-      url: '/runner-control/assignment',
+      url: '/runner-control/assignment?wait_seconds=5',
       headers: {authorization: `Bearer ${controlToken}`},
     });
     expect(assignment.statusCode).toBe(200);
@@ -394,6 +405,29 @@ describe('runner enrollment control plane', () => {
     expect(closed.statusCode).toBe(401);
   });
 
+  it('rejects a negative assignment wait before entering the control-plane poll', async () => {
+    const created = await app.inject({
+      method: 'POST',
+      url: '/provisioners/runner-instances/batch',
+      headers: {authorization: `Bearer ${token}`},
+      payload: {runner_instances: [{}]},
+    });
+    const runner = created.json().runner_instances[0];
+    const exchanged = await app.inject({
+      method: 'POST',
+      url: '/runner-enrollment/exchange',
+      payload: {bootstrap_token: runner.bootstrap_token},
+    });
+
+    const assignment = await app.inject({
+      method: 'GET',
+      url: '/runner-control/assignment?wait_seconds=-1',
+      headers: {authorization: `Bearer ${exchanged.json().control_session_token}`},
+    });
+
+    expect(assignment.statusCode).toBe(400);
+  });
+
   it('keeps polling when an assignment cannot yet mint an activation token', async () => {
     vi.useFakeTimers();
     const abortController = new AbortController();
@@ -419,6 +453,30 @@ describe('runner enrollment control plane', () => {
       vi.useRealTimers();
     }
   });
+
+  it('does not read or sleep past the assignment poll deadline', async () => {
+    vi.useFakeTimers();
+    const abortController = new AbortController();
+    const getAssignment = vi.fn().mockResolvedValue(null);
+    const issueActivationToken = vi.fn();
+    try {
+      const activationToken = pollForRunnerActivationToken({
+        deadline: Date.now() + 10,
+        intervalMs: 100,
+        signal: abortController.signal,
+        getAssignment,
+        issueActivationToken,
+      });
+
+      await vi.advanceTimersByTimeAsync(10);
+
+      await expect(activationToken).resolves.toBeNull();
+      expect(getAssignment).toHaveBeenCalledTimes(1);
+      expect(issueActivationToken).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
   it('rejects registration with an expired activation token', async () => {
     const created = await app.inject({
       method: 'POST',

package/src/presentation/routes/runner-enrollment.ts

@@ -6,6 +6,7 @@ import {
   attachRunnerControlProviderIdBodySchema,
   createRunnerInstancesBodySchema,
   createRunnerInstancesResponseSchema,
+  runnerAssignmentPollQuerySchema,
   runnerAssignmentPollResponseSchema,
   runnerBootstrapExchangeBodySchema,
   runnerBootstrapExchangeResponseSchema,
@@ -175,17 +176,32 @@ type RunnerAssignmentPollParams = {
   getAssignment: () => Promise<unknown | null>;
   issueActivationToken: () => Promise<string | null>;
 };
+
+export function resolveRunnerAssignmentPollWaitSeconds(
+  requestedWaitSeconds: number | undefined,
+): number {
+  return Math.max(
+    1,
+    Math.min(
+      requestedWaitSeconds ?? config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS,
+      config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS,
+    ),
+  );
+}
+
 export async function pollForRunnerActivationToken(
   params: RunnerAssignmentPollParams,
 ): Promise<string | null> {
-  while (Date.now() <= params.deadline) {
+  while (Date.now() < params.deadline) {
     if (params.signal.aborted) return null;
     const assignment = await params.getAssignment();
     if (assignment) {
       const activationToken = await params.issueActivationToken();
       if (activationToken) return activationToken;
     }
-    await new Promise((resolve) => setTimeout(resolve, params.intervalMs));
+    const remainingMs = params.deadline - Date.now();
+    if (remainingMs <= 0 || params.signal.aborted) return null;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(params.intervalMs, remainingMs)));
   }
   return null;
 }
@@ -193,11 +209,15 @@ export const runnerAssignmentPollRoute = defineRoute({
   method: 'GET',
   path: '/assignment',
   description: 'Wait for only the authenticated runner instance assignment',
-  schema: {response: {200: runnerAssignmentPollResponseSchema}},
+  schema: {
+    querystring: runnerAssignmentPollQuerySchema,
+    response: {200: runnerAssignmentPollResponseSchema},
+  },
   preHandler: authenticateRunnerControlSession,
   handler: async (request, reply) => {
     const session = requireRunnerControlSessionContext(request);
-    const deadline = Date.now() + config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS * 1000;
+    const waitSeconds = resolveRunnerAssignmentPollWaitSeconds(request.query.wait_seconds);
+    const deadline = Date.now() + waitSeconds * 1000;
     const abortController = new AbortController();
     reply.raw.on('close', () => abortController.abort());
     const activationToken = await pollForRunnerActivationToken({

package/test/globalSetup.ts

@@ -20,6 +20,7 @@ export async function setup() {
   await db().execute(sql`TRUNCATE runners_pending_jobs CASCADE`);
   await db().execute(sql`TRUNCATE runners_running_jobs CASCADE`);
   await db().execute(sql`TRUNCATE runners_outbox CASCADE`);
+  await db().execute(sql`TRUNCATE runners_admin_command_results CASCADE`);
 
   closeDb();
   await closePostgresClient();