@shipfox/api-runners 12.1.0 → 12.3.0

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

@@ -87,6 +87,7 @@ describe('POST /provisioners/demand/poll', () => {
   it('returns demand stats and reservations when matching demand exists', async () => {
     await pendingJobFactory.create({workspaceId, requiredLabels: ['linux']});
 
+    const requestStartedAt = Date.now();
     const res = await app.inject({
       method: 'POST',
       url: '/provisioners/demand/poll',
@@ -102,6 +103,60 @@ describe('POST /provisioners/demand/poll', () => {
     });
     expect(res.json().reservations[0].reservation_id).toEqual(expect.any(String));
     expect(res.json().reservations[0].expires_at).toEqual(expect.any(String));
+    const expiresAt = Date.parse(res.json().reservations[0].expires_at);
+    expect(expiresAt).toBeGreaterThanOrEqual(requestStartedAt + 55_000);
+    expect(expiresAt).toBeLessThan(requestStartedAt + 65_000);
+  });
+
+  it('clamps a requested reservation TTL for workspace provisioners', async () => {
+    await pendingJobFactory.create({workspaceId, requiredLabels: ['linux']});
+
+    const requestStartedAt = Date.now();
+    const res = await app.inject({
+      method: 'POST',
+      url: '/provisioners/demand/poll',
+      headers: {authorization: `Bearer ${VALID_PROVISIONER_TOKEN}`},
+      payload: body({max_reservations: 1, reservation_ttl_seconds: 601}),
+    });
+
+    expect(res.statusCode).toBe(200);
+    const expiresAt = Date.parse(res.json().reservations[0].expires_at);
+    expect(expiresAt).toBeGreaterThanOrEqual(requestStartedAt + 595_000);
+    expect(expiresAt).toBeLessThan(requestStartedAt + 605_000);
+  });
+
+  it('accepts a slow-boot reservation TTL below the raised ceiling', async () => {
+    await pendingJobFactory.create({workspaceId, requiredLabels: ['linux']});
+
+    const requestStartedAt = Date.now();
+    const res = await app.inject({
+      method: 'POST',
+      url: '/provisioners/demand/poll',
+      headers: {authorization: `Bearer ${VALID_PROVISIONER_TOKEN}`},
+      payload: body({max_reservations: 1, reservation_ttl_seconds: 540}),
+    });
+
+    expect(res.statusCode).toBe(200);
+    const expiresAt = Date.parse(res.json().reservations[0].expires_at);
+    expect(expiresAt).toBeGreaterThanOrEqual(requestStartedAt + 535_000);
+    expect(expiresAt).toBeLessThan(requestStartedAt + 545_000);
+  });
+
+  it('applies a requested reservation TTL below the ceiling', async () => {
+    await pendingJobFactory.create({workspaceId, requiredLabels: ['linux']});
+
+    const requestStartedAt = Date.now();
+    const res = await app.inject({
+      method: 'POST',
+      url: '/provisioners/demand/poll',
+      headers: {authorization: `Bearer ${VALID_PROVISIONER_TOKEN}`},
+      payload: body({max_reservations: 1, reservation_ttl_seconds: 120}),
+    });
+
+    expect(res.statusCode).toBe(200);
+    const expiresAt = Date.parse(res.json().reservations[0].expires_at);
+    expect(expiresAt).toBeGreaterThanOrEqual(requestStartedAt + 115_000);
+    expect(expiresAt).toBeLessThan(requestStartedAt + 125_000);
   });
 
   it('rejects installation provisioner credentials from workspace demand polling', async () => {
@@ -173,6 +228,39 @@ describe('POST /provisioners/demand/poll', () => {
     expect(clearedSnapshots).toEqual([]);
   });
 
+  it('strips reserved labels from workspace template advertisements', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/provisioners/demand/poll',
+      headers: {authorization: `Bearer ${VALID_PROVISIONER_TOKEN}`},
+      payload: {
+        wait_seconds: 0,
+        max_reservations: 0,
+        templates: [
+          {
+            template_key: 'linux',
+            labels: ['linux', 'shipfox-managed'],
+            available_slots: 1,
+            starting: 0,
+            running: 0,
+          },
+        ],
+      },
+    });
+
+    const snapshots = await db()
+      .select()
+      .from(provisionerCapabilitySnapshots)
+      .where(eq(provisionerCapabilitySnapshots.provisionerId, provisionerTokenId));
+
+    expect(res.statusCode).toBe(200);
+    expect(snapshots).toEqual([
+      expect.objectContaining({
+        labels: ['linux'],
+      }),
+    ]);
+  });
+
   it('returns terminate intent ids for active provisioned runners with cancelled latest jobs', async () => {
     await providerRunnerFactory.create({
       workspaceId,
@@ -330,10 +418,13 @@ describe('POST /provisioners/demand/poll', () => {
     expect(res.statusCode).toBe(401);
   });
 
-  function body(params: {max_reservations: number}) {
+  function body(params: {max_reservations: number; reservation_ttl_seconds?: number}) {
     return {
       wait_seconds: 0,
       max_reservations: params.max_reservations,
+      ...(params.reservation_ttl_seconds === undefined
+        ? {}
+        : {reservation_ttl_seconds: params.reservation_ttl_seconds}),
       templates: [
         {
           template_key: 'linux',
@@ -377,6 +468,7 @@ describe('POST /provisioners/demand/poll with installation provisioning configur
   let app: FastifyInstance;
   let workspaceId: string;
   let provisionerTokenId: string;
+  const filterEligibleWorkspaceIds = vi.fn().mockResolvedValue(new Set<string>());
 
   const fakeProvisionerAuth: AuthMethod = {
     name: AUTH_PROVISIONER_TOKEN,
@@ -402,7 +494,7 @@ describe('POST /provisioners/demand/poll with installation provisioning configur
       ],
       routes: createRunnerRoutes(runnersTestAuthClient, {
         installationProvisioning: {
-          policy: {filterEligibleWorkspaceIds: vi.fn().mockResolvedValue(new Set())},
+          policy: {filterEligibleWorkspaceIds},
         },
       }),
       swagger: false,
@@ -444,10 +536,31 @@ describe('POST /provisioners/demand/poll with installation provisioning configur
     expect(res.statusCode).toBe(200);
   });
 
-  function body(params: {max_reservations: number}) {
+  it('clamps a requested reservation TTL for installation provisioners', async () => {
+    await pendingJobFactory.create({workspaceId, requiredLabels: ['linux']});
+    filterEligibleWorkspaceIds.mockResolvedValueOnce(new Set([workspaceId]));
+
+    const requestStartedAt = Date.now();
+    const res = await app.inject({
+      method: 'POST',
+      url: '/provisioners/demand/poll',
+      headers: {authorization: `Bearer ${INSTALLATION_PROVISIONER_TOKEN}`},
+      payload: body({max_reservations: 1, reservation_ttl_seconds: 601}),
+    });
+
+    expect(res.statusCode).toBe(200);
+    const expiresAt = Date.parse(res.json().reservations[0].expires_at);
+    expect(expiresAt).toBeGreaterThanOrEqual(requestStartedAt + 595_000);
+    expect(expiresAt).toBeLessThan(requestStartedAt + 605_000);
+  });
+
+  function body(params: {max_reservations: number; reservation_ttl_seconds?: number}) {
     return {
       wait_seconds: 0,
       max_reservations: params.max_reservations,
+      ...(params.reservation_ttl_seconds === undefined
+        ? {}
+        : {reservation_ttl_seconds: params.reservation_ttl_seconds}),
       templates: [
         {
           template_key: 'linux',

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

@@ -9,6 +9,7 @@ import {ClientError, defineRoute} from '@shipfox/node-fastify';
 import {logger} from '@shipfox/node-opentelemetry';
 import {config} from '#config.js';
 import {pollDemand, releaseReservationGrants} from '#core/demand.js';
+import {sanitizeRunnerLabels} from '#core/runner-labels.js';
 import {publishWorkspaceProvisionerCapabilitySnapshot} from '#db/provisioner-capability-snapshots.js';
 import {
   listQueuedDemandWorkspaceIds,
@@ -21,10 +22,17 @@ import {toPollDemandResponseDto} from '#presentation/dto/index.js';
 
 const TERMINATE_INTENT_LIMIT = 1000;
 
-function toReservationTemplates(templates: PollDemandTemplateDto[]): ReservationTemplate[] {
+function toReservationTemplates(
+  templates: PollDemandTemplateDto[],
+  scope: 'installation' | 'workspace',
+): ReservationTemplate[] {
   return templates.map((template) => ({
     templateKey: template.template_key,
-    labels: template.labels,
+    labels: sanitizeRunnerLabels(template.labels, {
+      scope,
+      logLevel: 'debug',
+      source: 'provisioner template advertisement',
+    }),
     availableSlots: template.available_slots,
     starting: template.starting,
     running: template.running,
@@ -66,6 +74,10 @@ export function createPollDemandRoute(options: CreateRunnersModuleOptions = {})
         }
       });
       const provisionerContext = requireProvisionerContext(request);
+      const ttlSeconds = Math.min(
+        request.body.reservation_ttl_seconds ?? config.RESERVATION_TTL_SECONDS,
+        config.RESERVATION_TTL_MAX_SECONDS,
+      );
       if (provisionerContext.scope === 'installation') {
         if (!options.installationProvisioning) {
           throw new ClientError(
@@ -81,11 +93,11 @@ export function createPollDemandRoute(options: CreateRunnersModuleOptions = {})
           await options.installationProvisioning.policy.filterEligibleWorkspaceIds(
             candidateWorkspaceIds,
           );
-        const templates = toReservationTemplates(request.body.templates);
+        const templates = toReservationTemplates(request.body.templates, 'installation');
         const result = await pollInstallationDemandAndReserve({
           provisionerId: provisionerContext.provisionerTokenId,
           maxReservations: request.body.max_reservations,
-          ttlSeconds: config.RESERVATION_TTL_SECONDS,
+          ttlSeconds,
           templates,
           capabilityWindowSeconds: config.PROVISIONER_ACTIVE_WINDOW_SECONDS,
           eligibleWorkspaceIds,
@@ -101,7 +113,7 @@ export function createPollDemandRoute(options: CreateRunnersModuleOptions = {})
       }
       const {provisionerTokenId, workspaceId} = requireWorkspaceProvisionerContext(request);
 
-      const templates = toReservationTemplates(request.body.templates);
+      const templates = toReservationTemplates(request.body.templates, 'workspace');
       await publishWorkspaceProvisionerCapabilitySnapshot({
         workspaceId,
         provisionerId: provisionerTokenId,
@@ -113,7 +125,7 @@ export function createPollDemandRoute(options: CreateRunnersModuleOptions = {})
         provisionerId: provisionerTokenId,
         maxReservations: request.body.max_reservations,
         waitSeconds: request.body.wait_seconds,
-        ttlSeconds: config.RESERVATION_TTL_SECONDS,
+        ttlSeconds,
         terminateIntentLimit: TERMINATE_INTENT_LIMIT,
         templates,
         signal: abortController.signal,

package/src/presentation/routes/register.test.ts

@@ -1,11 +1,12 @@
 import {AUTH_PROVISIONER_TOKEN, AUTH_USER} from '@shipfox/api-auth-context';
 import type {RunnerToolCapabilitiesDto} from '@shipfox/api-runners-dto';
 import type {AuthMethod} from '@shipfox/node-fastify';
-import {closeApp, createApp} from '@shipfox/node-fastify';
+import {ClientError, closeApp, createApp} from '@shipfox/node-fastify';
 import {generateOpaqueToken} from '@shipfox/node-tokens';
 import {eq, sql} from 'drizzle-orm';
-import type {FastifyInstance} from 'fastify';
+import type {FastifyInstance, FastifyReply, FastifyRequest} from 'fastify';
 import {config} from '#config.js';
+import {RunnerLabelsReservedError} from '#core/errors.js';
 import {hashRunnersRateLimitIdentifier} from '#core/rate-limit.js';
 import {db} from '#db/db.js';
 import {revokeManualRegistrationToken} from '#db/manual-registration-tokens.js';
@@ -19,9 +20,11 @@ import {
   fakeRunnerSessionAuthMethod,
   getRunnerSessionTokenClaims,
   manualRegistrationTokenFactory,
+  provisionerTokenFactory,
   runnersTestAuthClient,
 } from '#test/index.js';
 import {createRunnerRoutes} from './index.js';
+import {createRegisterRoute} from './register.js';
 
 const fakeUserAuth: AuthMethod = {
   name: AUTH_USER,
@@ -123,6 +126,38 @@ describe('POST /runners/register', () => {
     expect(session?.toolCapabilitiesReportedAt).toBeInstanceOf(Date);
   });
 
+  it('strips reserved labels from manual registration', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/runners/register',
+      headers: {authorization: `Bearer ${rawToken}`},
+      payload: {labels: ['linux', 'shipfox-managed', 'x64']},
+    });
+
+    const [session] = await db()
+      .select()
+      .from(runnerSessions)
+      .where(eq(runnerSessions.id, res.json().session_id));
+
+    expect(res.statusCode).toBe(200);
+    expect(session?.labels).toEqual(['linux', 'x64']);
+  });
+
+  it('returns a distinct error when all manual registration labels are reserved', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/runners/register',
+      headers: {authorization: `Bearer ${rawToken}`},
+      payload: {labels: ['shipfox-managed']},
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toMatchObject({
+      code: 'runner-labels-reserved',
+      details: {labels: ['shipfox-managed']},
+    });
+  });
+
   it('exchanges an ephemeral registration token for a one-claim runner session', async () => {
     const ephemeralRawToken = generateOpaqueToken('ephemeralRegistrationToken');
     const token = await ephemeralRegistrationTokenFactory.create(
@@ -165,6 +200,65 @@ describe('POST /runners/register', () => {
     expect(consumed?.consumedSessionId).toBe(body.session_id);
   });
 
+  it('strips reserved labels from ephemeral registration', async () => {
+    const ephemeralRawToken = generateOpaqueToken('ephemeralRegistrationToken');
+    const provisioner = await provisionerTokenFactory.create({
+      scope: 'workspace',
+      workspaceId,
+    });
+    const token = await ephemeralRegistrationTokenFactory.create(
+      {workspaceId, provisionerId: provisioner.id},
+      {transient: {rawToken: ephemeralRawToken}},
+    );
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/runners/register',
+      headers: {authorization: `Bearer ${ephemeralRawToken}`},
+      payload: {labels: ['linux', 'shipfox-managed']},
+    });
+
+    const [session] = await db()
+      .select()
+      .from(runnerSessions)
+      .where(eq(runnerSessions.id, res.json().session_id));
+
+    expect(res.statusCode).toBe(200);
+    expect(session).toMatchObject({
+      id: res.json().session_id,
+      provisionerId: token.provisionerId,
+      labels: ['linux'],
+    });
+  });
+
+  it('preserves reserved labels for installation-scope ephemeral registration', async () => {
+    const ephemeralRawToken = generateOpaqueToken('ephemeralRegistrationToken');
+    const provisioner = await provisionerTokenFactory.create({scope: 'installation'});
+    const token = await ephemeralRegistrationTokenFactory.create(
+      {workspaceId, provisionerId: provisioner.id},
+      {transient: {rawToken: ephemeralRawToken}},
+    );
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/runners/register',
+      headers: {authorization: `Bearer ${ephemeralRawToken}`},
+      payload: {labels: ['linux', 'shipfox-managed']},
+    });
+
+    const [session] = await db()
+      .select()
+      .from(runnerSessions)
+      .where(eq(runnerSessions.id, res.json().session_id));
+
+    expect(res.statusCode).toBe(200);
+    expect(session).toMatchObject({
+      id: res.json().session_id,
+      provisionerId: token.provisionerId,
+      labels: ['linux', 'shipfox-managed'],
+    });
+  });
+
   it('rejects malformed capability reports without creating a runner session', async () => {
     const res = await app.inject({
       method: 'POST',
@@ -418,6 +512,26 @@ describe('POST /runners/register', () => {
     expect(res.statusCode).toBe(200);
   });
 
+  it('maps reserved-label-only registration failures to a public error code', () => {
+    const route = createRegisterRoute(runnersTestAuthClient);
+
+    try {
+      route.errorHandler?.(
+        new RunnerLabelsReservedError(['shipfox-managed']),
+        {} as FastifyRequest,
+        {} as FastifyReply,
+      );
+      throw new Error('Expected register route error handler to throw');
+    } catch (error) {
+      expect(error).toBeInstanceOf(ClientError);
+      expect(error).toMatchObject({
+        code: 'runner-labels-reserved',
+        details: {labels: ['shipfox-managed']},
+        status: 400,
+      });
+    }
+  });
+
   async function seedEphemeralRegisterRateLimit(
     tokenId: string,
     seedCount: number,

package/src/presentation/routes/register.ts

@@ -5,6 +5,7 @@ import {
   EmptyRunnerLabelsError,
   RegistrationTokenConsumedError,
   RegistrationTokenExpiredError,
+  RunnerLabelsReservedError,
 } from '#core/errors.js';
 import {registerRunnerSession} from '#core/runner-sessions.js';
 import {getRunnerContext} from '#presentation/auth/index.js';
@@ -23,6 +24,12 @@ export function createRegisterRoute(auth: AuthInterModuleClient) {
     },
     preHandler: createEphemeralRegisterRateLimitPreHandler(),
     errorHandler: (error, request) => {
+      if (error instanceof RunnerLabelsReservedError) {
+        throw new ClientError(error.message, 'runner-labels-reserved', {
+          details: {labels: error.labels},
+          status: 400,
+        });
+      }
       if (error instanceof EmptyRunnerLabelsError) {
         throw new ClientError(error.message, 'empty-runner-labels', {status: 400});
       }

package/src/presentation/routes/report-runner-instances.test.ts

@@ -113,6 +113,39 @@ describe('POST /provisioners/runner-instances/report', () => {
     expect(rows[0]?.reportedAt.toISOString()).toBe(reportedAt);
   });
 
+  it('strips reserved labels from workspace runner reports', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/provisioners/runner-instances/report',
+      headers: {authorization: `Bearer ${VALID_PROVISIONER_TOKEN}`},
+      payload: {
+        events: [
+          {
+            provider_runner_id: 'provisioned-runner-reserved-label',
+            labels: ['linux', 'shipfox-managed'],
+            state: 'starting',
+            reported_at: new Date('2025-01-01T00:00:00.000Z').toISOString(),
+            provider_kind: 'docker',
+          },
+        ],
+      },
+    });
+
+    const [row] = await db()
+      .select()
+      .from(providerRunners)
+      .where(
+        and(
+          eq(providerRunners.workspaceId, workspaceId),
+          eq(providerRunners.provisionerId, provisionerTokenId),
+          eq(providerRunners.providerRunnerId, 'provisioned-runner-reserved-label'),
+        ),
+      );
+
+    expect(res.statusCode).toBe(200);
+    expect(row?.labels).toEqual(['linux']);
+  });
+
   it('returns 400 when the batch exceeds the DTO limit', async () => {
     const event = {
       provider_runner_id: 'provisioned-runner-1',

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

@@ -20,6 +20,7 @@ export const reportRunnerInstancesRoute = defineRoute({
   handler: async (request) => {
     const context = requireProvisionerContext(request);
     const result = await reportRunnerInstances({
+      scope: context.scope,
       workspaceId: context.scope === 'workspace' ? context.workspaceId : null,
       provisionerId: context.provisionerTokenId,
       events: request.body.events.map((event) => ({

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

@@ -20,6 +20,7 @@ import {
 import {
   fakeLeaseTokenAuthMethod,
   fakeRunnerSessionAuthMethod,
+  provisionerTokenFactory,
   runnersTestAuthClient,
 } from '#test/index.js';
 import {createRunnerRoutes} from './index.js';
@@ -29,15 +30,27 @@ import {
 } from './runner-enrollment.js';
 
 const token = 'provisioner-test-token';
+const workspaceToken = 'workspace-provisioner-test-token';
 const fakeUserAuth: AuthMethod = {name: AUTH_USER, authenticate: () => Promise.resolve()};
 
 describe('runner enrollment control plane', () => {
   let app: FastifyInstance;
   let provisionerId: string;
+  let workspaceProvisionerId: string;
+  let workspaceProvisionerWorkspaceId: string;
   const provisionerAuth: AuthMethod = {
     name: AUTH_PROVISIONER_TOKEN,
     authenticate: (request: FastifyRequest) => {
-      if (extractBearerToken(request.headers.authorization) !== token)
+      const rawToken = extractBearerToken(request.headers.authorization);
+      if (rawToken === workspaceToken) {
+        setProvisionerContext(request, {
+          scope: 'workspace',
+          workspaceId: workspaceProvisionerWorkspaceId,
+          provisionerTokenId: workspaceProvisionerId,
+        });
+        return Promise.resolve();
+      }
+      if (rawToken !== token)
         throw new ClientError('Invalid provisioner token', 'unauthorized', {status: 401});
       setProvisionerContext(request, {scope: 'installation', provisionerTokenId: provisionerId});
       return Promise.resolve();
@@ -64,8 +77,17 @@ describe('runner enrollment control plane', () => {
     await closeApp();
   });
 
-  beforeEach(() => {
-    provisionerId = crypto.randomUUID();
+  beforeEach(async () => {
+    const provisioner = await provisionerTokenFactory.create({scope: 'installation'});
+    const workspaceProvisioner = await provisionerTokenFactory.create({
+      scope: 'workspace',
+    });
+    if (workspaceProvisioner.scope !== 'workspace') {
+      throw new Error('Expected a workspace provisioner token');
+    }
+    provisionerId = provisioner.id;
+    workspaceProvisionerId = workspaceProvisioner.id;
+    workspaceProvisionerWorkspaceId = workspaceProvisioner.workspaceId;
   });
 
   it('uses the requested assignment wait below the server cap and caps larger requests', () => {
@@ -112,7 +134,11 @@ describe('runner enrollment control plane', () => {
       method: 'POST',
       url: '/runner-control/enrollment',
       headers: {authorization: `Bearer ${controlToken}`},
-      payload: {labels: ['Linux', 'linux'], provider_kind: 'docker', protocol_version: '1'},
+      payload: {
+        labels: ['Linux', 'linux', 'shipfox-managed'],
+        provider_kind: 'docker',
+        protocol_version: '1',
+      },
     });
     expect(enrolled.statusCode).toBe(200);
     expect(enrolled.json()).toEqual({activation_token: null});
@@ -131,7 +157,7 @@ describe('runner enrollment control plane', () => {
       .where(eq(providerRunners.id, runner.runner_instance_id));
     expect(instance).toMatchObject({
       provisionerId,
-      labels: ['linux'],
+      labels: ['linux', 'shipfox-managed'],
       providerRunnerId: 'container-1',
       state: 'running',
       protocolVersion: '1',
@@ -150,6 +176,40 @@ describe('runner enrollment control plane', () => {
     expect(jobs.statusCode).toBe(401);
   });
 
+  it('strips reserved labels when a workspace provisioner enrolls a runner', async () => {
+    const created = await app.inject({
+      method: 'POST',
+      url: '/provisioners/runner-instances/batch',
+      headers: {authorization: `Bearer ${workspaceToken}`},
+      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 enrolled = await app.inject({
+      method: 'POST',
+      url: '/runner-control/enrollment',
+      headers: {authorization: `Bearer ${exchanged.json().control_session_token}`},
+      payload: {
+        labels: ['linux', 'shipfox-managed'],
+        provider_kind: 'docker',
+        protocol_version: '1',
+      },
+    });
+
+    const [instance] = await db()
+      .select()
+      .from(providerRunners)
+      .where(eq(providerRunners.id, runner.runner_instance_id));
+
+    expect(enrolled.statusCode).toBe(200);
+    expect(instance?.labels).toEqual(['linux']);
+  });
+
   it('promotes an intended reservation during enrollment and returns its activation token', async () => {
     const workspaceId = crypto.randomUUID();
     const [reservation] = await db()