@shipfox/api-runners 12.1.0 → 12.2.0

package/drizzle/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1785235910167,
       "tag": "0003_flaky_sally_floyd",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1786017247182,
+      "tag": "0004_huge_skreet",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-runners",
   "license": "MIT",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -22,24 +22,24 @@
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
     "@shipfox/api-common-dto": "12.0.0",
-    "@shipfox/api-auth-context": "12.0.0",
+    "@shipfox/api-auth-context": "12.2.0",
     "@shipfox/api-auth-dto": "12.0.0",
-    "@shipfox/api-runners-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "12.1.0",
+    "@shipfox/api-runners-dto": "12.2.0",
+    "@shipfox/api-workflows-dto": "12.2.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
     "@shipfox/node-auth-root-key": "0.2.3",
-    "@shipfox/node-fastify": "0.4.1",
-    "@shipfox/node-module": "1.0.5",
-    "@shipfox/node-opentelemetry": "0.6.3",
+    "@shipfox/node-fastify": "0.4.2",
+    "@shipfox/node-opentelemetry": "0.6.4",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.5.0",
     "@shipfox/node-rate-limit": "0.4.0",
-    "@shipfox/node-temporal": "0.4.4",
+    "@shipfox/node-temporal": "0.4.5",
+    "@shipfox/node-module": "1.0.6",
     "@shipfox/node-tokens": "0.3.2",
-    "@shipfox/runner-labels": "0.1.3"
+    "@shipfox/runner-labels": "0.2.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/config.test.ts

@@ -1,6 +1,42 @@
 import {RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS} from '@shipfox/api-runners-dto';
 import {vi} from '@shipfox/vitest/vi';
 
+describe('RUNNER_RESERVED_LABELS', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('defaults to no reserved labels', async () => {
+    vi.stubEnv('RUNNER_RESERVED_LABELS', undefined);
+    vi.resetModules();
+
+    const {config, runnerReservedLabels} = await import('#config.js');
+
+    expect(config.RUNNER_RESERVED_LABELS).toBe('');
+    expect(runnerReservedLabels).toEqual([]);
+  });
+
+  it('parses comma-separated labels for case-insensitive matching', async () => {
+    vi.stubEnv('RUNNER_RESERVED_LABELS', ' ShipFox-Managed, Linux,shipfox-managed ');
+    vi.resetModules();
+
+    const {config, runnerReservedLabels} = await import('#config.js');
+
+    expect(config.RUNNER_RESERVED_LABELS).toBe(' ShipFox-Managed, Linux,shipfox-managed ');
+    expect(runnerReservedLabels).toEqual(['linux', 'shipfox-managed']);
+  });
+
+  it('rejects invalid runner labels', async () => {
+    vi.stubEnv('RUNNER_RESERVED_LABELS', 'linux,has space');
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow(
+      'RUNNER_RESERVED_LABELS contains invalid runner label(s): has space',
+    );
+  });
+});
+
 describe('EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS validation', () => {
   afterEach(() => {
     vi.unstubAllEnvs();
@@ -49,6 +85,51 @@ describe('runner assignment polling defaults', () => {
     await expect(import('#config.js')).rejects.toThrow('RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS');
   });
 });
+
+describe('reservation TTL ceiling validation', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it.each([
+    '0',
+    '-5',
+    '1.5',
+    '3601',
+  ])('fails startup when RESERVATION_TTL_MAX_SECONDS is %s', async (value) => {
+    vi.stubEnv('RESERVATION_TTL_MAX_SECONDS', value);
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('RESERVATION_TTL_MAX_SECONDS');
+  });
+
+  it('defaults high enough for the EC2 registration deadline', async () => {
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.RESERVATION_TTL_MAX_SECONDS).toBe(300);
+  });
+
+  it('accepts a whole-second ceiling inside the hard maximum', async () => {
+    vi.stubEnv('RESERVATION_TTL_MAX_SECONDS', '600');
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.RESERVATION_TTL_MAX_SECONDS).toBe(600);
+  });
+
+  it('fails startup when the default reservation TTL is above the ceiling', async () => {
+    vi.stubEnv('RESERVATION_TTL_SECONDS', '600');
+    vi.stubEnv('RESERVATION_TTL_MAX_SECONDS', '300');
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('RESERVATION_TTL_SECONDS');
+  });
+});
+
 describe('REGISTRATION_TOKEN_BATCH_MAX validation', () => {
   afterEach(() => {
     vi.unstubAllEnvs();

package/src/config.ts

@@ -1,10 +1,12 @@
 import {RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS} from '@shipfox/api-runners-dto';
-import {bool, createConfig, num} from '@shipfox/config';
+import {bool, createConfig, num, str} from '@shipfox/config';
+import {findInvalidLabels, parseLabelList} from '@shipfox/runner-labels';
 import {STUCK_JOB_THRESHOLD_SECONDS} from '#core/maintenance-policy.js';
 
 const EPHEMERAL_REGISTRATION_TOKEN_TTL_HARD_MAX_SECONDS = 3600;
 const REGISTRATION_TOKEN_BATCH_HARD_MAX = 1000;
 const RUNNER_CONTROL_PLANE_TOKEN_TTL_HARD_MAX_SECONDS = 3600;
+const RESERVATION_TTL_HARD_MAX_SECONDS = 3600;
 
 export const config = createConfig({
   RUNNER_BOOTSTRAP_TOKEN_TTL_SECONDS: num({
@@ -27,6 +29,10 @@ export const config = createConfig({
     desc: 'Delay between durable assignment reads while a runner-control session waits for an assignment, in milliseconds.',
     default: 250,
   }),
+  RUNNER_RESERVED_LABELS: str({
+    desc: 'Comma-separated labels that only installation-scope provisioners may advertise. Any other provisioner or runner has them removed.',
+    default: '',
+  }),
   EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS: num({
     desc: `Lifetime of a provisioner-minted runner registration token, in seconds. The token can be exchanged once by a runner before this time passes. Set this between 1 and ${EPHEMERAL_REGISTRATION_TOKEN_TTL_HARD_MAX_SECONDS}.`,
     default: 300,
@@ -56,9 +62,13 @@ export const config = createConfig({
     default: 250,
   }),
   RESERVATION_TTL_SECONDS: num({
-    desc: 'Lifetime of a count-based runner reservation, in seconds. Expired reservations stop counting against queued demand.',
+    desc: 'Default lifetime of a count-based runner reservation, in seconds. Used when a provisioner does not request a provider-specific value. Expired reservations stop counting against queued demand.',
     default: 60,
   }),
+  RESERVATION_TTL_MAX_SECONDS: num({
+    desc: `Server-side ceiling for a count-based runner reservation lifetime, in seconds. Set it at least as high as every provider registration deadline so provider-specific values can cover boot and enrollment. Set this between 1 and ${RESERVATION_TTL_HARD_MAX_SECONDS}.`,
+    default: 300,
+  }),
   RESERVATION_LONG_POLL_MAX_WAIT_SECONDS: num({
     desc: 'Maximum time the provisioner demand poll endpoint waits for reservable demand before returning, in seconds.',
     default: 30,
@@ -133,6 +143,17 @@ export const config = createConfig({
   }),
 });
 
+const parsedRunnerReservedLabels = parseLabelList(config.RUNNER_RESERVED_LABELS);
+const invalidRunnerReservedLabels = findInvalidLabels(parsedRunnerReservedLabels);
+
+if (invalidRunnerReservedLabels.length > 0) {
+  throw new Error(
+    `RUNNER_RESERVED_LABELS contains invalid runner label(s): ${invalidRunnerReservedLabels.join(', ')}`,
+  );
+}
+
+export const runnerReservedLabels = parsedRunnerReservedLabels;
+
 if (
   !Number.isInteger(config.EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS) ||
   config.EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS < 1 ||
@@ -209,6 +230,22 @@ if (!Number.isInteger(config.RESERVATION_TTL_SECONDS) || config.RESERVATION_TTL_
   );
 }
 
+if (
+  !Number.isInteger(config.RESERVATION_TTL_MAX_SECONDS) ||
+  config.RESERVATION_TTL_MAX_SECONDS < 1 ||
+  config.RESERVATION_TTL_MAX_SECONDS > RESERVATION_TTL_HARD_MAX_SECONDS
+) {
+  throw new Error(
+    `RESERVATION_TTL_MAX_SECONDS (${config.RESERVATION_TTL_MAX_SECONDS}) must be a whole number of seconds between 1 and ${RESERVATION_TTL_HARD_MAX_SECONDS}.`,
+  );
+}
+
+if (config.RESERVATION_TTL_SECONDS > config.RESERVATION_TTL_MAX_SECONDS) {
+  throw new Error(
+    `RESERVATION_TTL_SECONDS (${config.RESERVATION_TTL_SECONDS}) must not be greater than RESERVATION_TTL_MAX_SECONDS (${config.RESERVATION_TTL_MAX_SECONDS}).`,
+  );
+}
+
 if (
   !Number.isInteger(config.RESERVATION_LONG_POLL_MAX_WAIT_SECONDS) ||
   config.RESERVATION_LONG_POLL_MAX_WAIT_SECONDS < 0

package/src/core/errors.ts

@@ -40,6 +40,15 @@ export class EmptyRunnerLabelsError extends Error {
   }
 }
 
+export class RunnerLabelsReservedError extends Error {
+  constructor(public readonly labels: string[]) {
+    super(
+      `All supplied runner labels are reserved for installation-scope provisioners: ${labels.join(', ')}`,
+    );
+    this.name = 'RunnerLabelsReservedError';
+  }
+}
+
 export class EmptyRequiredLabelsError extends Error {
   constructor() {
     super('Required labels cannot be empty');

package/src/core/index.ts

@@ -25,6 +25,7 @@ export {
   ProvisionerTokenNotFoundError,
   RegistrationTokenConsumedError,
   RegistrationTokenExpiredError,
+  RunnerLabelsReservedError,
   RunnerSessionExhaustedError,
   RunningJobExecutionNotFoundError,
 } from './errors.js';

package/src/core/runner-control-sessions.test.ts

@@ -0,0 +1,239 @@
+import {afterEach, vi} from '@shipfox/vitest/vi';
+import {inArray} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {reservations} from '#db/schema/reservations.js';
+import {runnerActivationTokens} from '#db/schema/runner-activation-tokens.js';
+import {runnerControlSessions} from '#db/schema/runner-control-sessions.js';
+import {providerRunners} from '#db/schema/runner-instances.js';
+import {
+  type RunnerReservationPromotionFailureReason,
+  runnerReservationPromotionFailureCount,
+} from '#metrics/instance.js';
+import {enrollRunnerControlSession} from './runner-control-sessions.js';
+
+const createdReservationIds = new Set<string>();
+const createdRunnerInstanceIds = new Set<string>();
+
+afterEach(async () => {
+  const runnerInstanceIds = [...createdRunnerInstanceIds];
+  const reservationIds = [...createdReservationIds];
+
+  if (runnerInstanceIds.length > 0) {
+    await db()
+      .delete(runnerActivationTokens)
+      .where(inArray(runnerActivationTokens.runnerInstanceId, runnerInstanceIds));
+    await db()
+      .delete(runnerControlSessions)
+      .where(inArray(runnerControlSessions.runnerInstanceId, runnerInstanceIds));
+    await db().delete(providerRunners).where(inArray(providerRunners.id, runnerInstanceIds));
+  }
+  if (reservationIds.length > 0)
+    await db().delete(reservations).where(inArray(reservations.id, reservationIds));
+
+  createdRunnerInstanceIds.clear();
+  createdReservationIds.clear();
+});
+
+describe('enrollRunnerControlSession', () => {
+  it('counts expired reservation promotion failures', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({
+      provisionerId,
+      expiresAt: new Date(Date.now() - 1_000),
+    });
+
+    await expectPromotionFailure({
+      provisionerId,
+      intendedReservationId: reservation.id,
+      reason: 'reservation-expired',
+    });
+  });
+
+  it('counts missing reservation promotion failures', async () => {
+    await expectPromotionFailure({
+      provisionerId: crypto.randomUUID(),
+      intendedReservationId: crypto.randomUUID(),
+      reason: 'reservation-not-found',
+    });
+  });
+
+  it('counts already-assigned reservation promotion failures', async () => {
+    const provisionerId = crypto.randomUUID();
+    const intendedReservation = await createReservation({provisionerId});
+    const assignedReservation = await createReservation({provisionerId});
+
+    await expectPromotionFailure({
+      provisionerId,
+      intendedReservationId: intendedReservation.id,
+      reservationId: assignedReservation.id,
+      reason: 'already-assigned',
+    });
+  });
+
+  it('counts not-assignable reservation promotion failures', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({
+      provisionerId,
+      requiredLabels: ['gpu'],
+    });
+
+    await expectPromotionFailure({
+      provisionerId,
+      intendedReservationId: reservation.id,
+      labels: ['linux'],
+      reason: 'not-assignable',
+    });
+  });
+
+  it('does not count successful reservation promotion', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({provisionerId});
+    const runnerInstanceId = await createRunner({
+      provisionerId,
+      intendedReservationId: reservation.id,
+    });
+    const addSpy = vi.spyOn(runnerReservationPromotionFailureCount, 'add');
+
+    try {
+      const activationToken = await enrollRunnerControlSession({
+        runnerInstanceId,
+        provisionerId,
+        labels: ['linux'],
+        providerKind: 'docker',
+        protocolVersion: '1',
+      });
+
+      expect(activationToken).toEqual(expect.any(String));
+      expect(addSpy).not.toHaveBeenCalled();
+    } finally {
+      addSpy.mockRestore();
+    }
+  });
+
+  it('keeps unexpected promotion failures on the error-log path', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({provisionerId});
+    const runnerInstanceId = await createRunner({
+      provisionerId,
+      intendedReservationId: reservation.id,
+    });
+    const unexpectedError = new Error('database unavailable');
+    const debugLog = vi.fn();
+    const errorLog = vi.fn();
+
+    vi.resetModules();
+    vi.doMock('@shipfox/node-opentelemetry', async (importOriginal) => ({
+      ...(await importOriginal<typeof import('@shipfox/node-opentelemetry')>()),
+      logger: () => ({debug: debugLog, error: errorLog}),
+    }));
+    vi.doMock('#db/runner-assignments.js', async (importOriginal) => ({
+      ...(await importOriginal<typeof import('#db/runner-assignments.js')>()),
+      assignRunnerInstancesTx: vi.fn().mockRejectedValue(unexpectedError),
+    }));
+
+    const {closePostgresClient, createPostgresClient} = await import('@shipfox/node-postgres');
+    createPostgresClient();
+
+    try {
+      const {enrollRunnerControlSession: enroll} = await import('./runner-control-sessions.js');
+      const result = await enroll({
+        runnerInstanceId,
+        provisionerId,
+        labels: ['linux'],
+        providerKind: 'docker',
+        protocolVersion: '1',
+      });
+
+      expect(result).toBeNull();
+      expect(debugLog).not.toHaveBeenCalled();
+      expect(errorLog).toHaveBeenCalledWith(
+        expect.objectContaining({err: unexpectedError}),
+        'Unexpected failure promoting runner reservation during enrollment',
+      );
+    } finally {
+      await closePostgresClient();
+      vi.doUnmock('@shipfox/node-opentelemetry');
+      vi.doUnmock('#db/runner-assignments.js');
+      vi.resetModules();
+    }
+  });
+});
+
+async function expectPromotionFailure(params: {
+  provisionerId: string;
+  intendedReservationId: string;
+  reservationId?: string;
+  labels?: string[];
+  reason: RunnerReservationPromotionFailureReason;
+}): Promise<void> {
+  const runnerInstanceId = await createRunner(params);
+  const addSpy = vi.spyOn(runnerReservationPromotionFailureCount, 'add');
+
+  try {
+    const result = await enrollRunnerControlSession({
+      runnerInstanceId,
+      provisionerId: params.provisionerId,
+      labels: params.labels ?? ['linux'],
+      providerKind: 'docker',
+      protocolVersion: '1',
+    });
+
+    expect(result).toBeNull();
+    expect(addSpy).toHaveBeenCalledWith(1, {reason: params.reason});
+  } finally {
+    addSpy.mockRestore();
+  }
+}
+
+async function createReservation(params: {
+  provisionerId: string;
+  requiredLabels?: string[];
+  expiresAt?: Date;
+}) {
+  const [reservation] = await db()
+    .insert(reservations)
+    .values({
+      workspaceId: crypto.randomUUID(),
+      provisionerId: params.provisionerId,
+      requiredLabels: params.requiredLabels ?? ['linux'],
+      count: 1,
+      expiresAt: params.expiresAt ?? new Date(Date.now() + 60_000),
+    })
+    .returning();
+  if (!reservation) throw new Error('Expected reservation');
+  createdReservationIds.add(reservation.id);
+  return reservation;
+}
+
+async function createRunner(params: {
+  provisionerId: string;
+  intendedReservationId: string;
+  reservationId?: string;
+  labels?: string[];
+}): Promise<string> {
+  const [runner] = await db()
+    .insert(providerRunners)
+    .values({
+      provisionerId: params.provisionerId,
+      intendedReservationId: params.intendedReservationId,
+      reservationId: params.reservationId ?? null,
+      providerRunnerId: crypto.randomUUID(),
+      labels: params.labels ?? [],
+      state: 'starting',
+      reportedAt: new Date(),
+    })
+    .returning({id: providerRunners.id});
+  if (!runner) throw new Error('Expected runner instance');
+  createdRunnerInstanceIds.add(runner.id);
+
+  await db()
+    .insert(runnerControlSessions)
+    .values({
+      runnerInstanceId: runner.id,
+      provisionerId: params.provisionerId,
+      hashedToken: crypto.randomUUID(),
+      prefix: 'test',
+      expiresAt: new Date(Date.now() + 60_000),
+    });
+  return runner.id;
+}

package/src/core/runner-control-sessions.ts

@@ -2,7 +2,6 @@ import type {RunnerToolCapabilitiesDto} from '@shipfox/api-runners-dto';
 import type {NodePgDatabase} from '@shipfox/node-drizzle';
 import {logger} from '@shipfox/node-opentelemetry';
 import {extractDisplayPrefix, generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
-import {canonicalizeLabels} from '@shipfox/runner-labels';
 import {and, eq, gt, isNull, notInArray, or, sql} from 'drizzle-orm';
 import {config} from '#config.js';
 import {
@@ -11,12 +10,17 @@ import {
   RunnerInstanceAlreadyAssignedError,
   RunnerInstanceNotAssignableError,
 } from '#core/errors.js';
+import {sanitizeRunnerLabels} from '#core/runner-labels.js';
 import {db, type schema, type Tx} from '#db/db.js';
 import {assignRunnerInstancesTx} from '#db/runner-assignments.js';
 import {terminalStates} from '#db/runner-instances.js';
 import {provisionerTokens} from '#db/schema/provisioner-tokens.js';
 import {runnerBootstrapTokens, runnerControlSessions} from '#db/schema/runner-control-sessions.js';
 import {providerRunners} from '#db/schema/runner-instances.js';
+import {
+  type RunnerReservationPromotionFailureReason,
+  recordRunnerReservationPromotionFailure,
+} from '#metrics/index.js';
 import {issueRunnerActivationTokenTx} from './runner-activation.js';
 
 export class RunnerBootstrapTokenInvalidError extends Error {
@@ -141,8 +145,12 @@ export async function enrollRunnerControlSession(params: {
 }): Promise<string | null> {
   return await db().transaction(async (tx) => {
     const [current] = await tx
-      .select({intendedReservationId: providerRunners.intendedReservationId})
+      .select({
+        intendedReservationId: providerRunners.intendedReservationId,
+        provisionerScope: provisionerTokens.scope,
+      })
       .from(providerRunners)
+      .innerJoin(provisionerTokens, eq(provisionerTokens.id, providerRunners.provisionerId))
       .where(
         and(
           eq(providerRunners.id, params.runnerInstanceId),
@@ -158,7 +166,10 @@ export async function enrollRunnerControlSession(params: {
     const [updated] = await tx
       .update(providerRunners)
       .set({
-        labels: [...canonicalizeLabels(params.labels)],
+        labels: sanitizeRunnerLabels(params.labels, {
+          scope: current.provisionerScope,
+          source: 'runner control enrollment',
+        }),
         providerKind: params.providerKind,
         protocolVersion: params.protocolVersion,
         capabilities: params.capabilities ?? null,
@@ -198,29 +209,37 @@ export async function enrollRunnerControlSession(params: {
         });
       });
     } catch (error) {
-      const expectedFailure =
-        error instanceof ReservationExpiredError ||
-        error instanceof ReservationNotFoundError ||
-        error instanceof RunnerInstanceAlreadyAssignedError ||
-        error instanceof RunnerInstanceNotAssignableError;
+      const expectedFailureReason = getRunnerReservationPromotionFailureReason(error);
       const details = {
         err: error,
         runnerInstanceId: params.runnerInstanceId,
         provisionerId: params.provisionerId,
         reservationId: intendedReservationId,
       };
-      if (expectedFailure)
+      if (expectedFailureReason) {
+        recordRunnerReservationPromotionFailure(expectedFailureReason);
         logger().debug(details, 'Runner reservation could not be promoted during enrollment');
-      else
+      } else {
         logger().error(
           details,
           'Unexpected failure promoting runner reservation during enrollment',
         );
+      }
       return null;
     }
   });
 }
 
+function getRunnerReservationPromotionFailureReason(
+  error: unknown,
+): RunnerReservationPromotionFailureReason | null {
+  if (error instanceof ReservationExpiredError) return 'reservation-expired';
+  if (error instanceof ReservationNotFoundError) return 'reservation-not-found';
+  if (error instanceof RunnerInstanceAlreadyAssignedError) return 'already-assigned';
+  if (error instanceof RunnerInstanceNotAssignableError) return 'not-assignable';
+  return null;
+}
+
 export async function attachRunnerControlProviderId(params: {
   runnerInstanceId: string;
   provisionerId: string;

package/src/core/runner-instances.ts

@@ -23,6 +23,7 @@ import {
 import {config} from '../config.js';
 
 export interface ReportRunnerInstancesParams {
+  scope: 'installation' | 'workspace';
   workspaceId: string | null;
   provisionerId: string;
   events: RunnerInstanceReportEvent[];

package/src/core/runner-labels.test.ts

@@ -0,0 +1,53 @@
+import {RunnerLabelsReservedError} from './errors.js';
+import {sanitizeRunnerLabels, sanitizeRunnerLabelsOrThrow} from './runner-labels.js';
+
+describe('sanitizeRunnerLabels', () => {
+  it('strips reserved labels from non-installation sources', () => {
+    const labels = sanitizeRunnerLabels([' Linux ', 'shipfox-managed', 'linux'], {
+      scope: 'workspace',
+      source: 'test',
+      reservedLabels: ['Shipfox-Managed'],
+    });
+
+    expect(labels).toEqual(['linux']);
+  });
+
+  it('preserves reserved labels for installation sources', () => {
+    const labels = sanitizeRunnerLabels([' Linux ', 'shipfox-managed'], {
+      scope: 'installation',
+      source: 'test',
+      reservedLabels: ['shipfox-managed'],
+    });
+
+    expect(labels).toEqual(['linux', 'shipfox-managed']);
+  });
+
+  it('does not change labels when no reserved labels are configured', () => {
+    const labels = sanitizeRunnerLabels([' Linux ', 'linux'], {
+      scope: 'manual',
+      source: 'test',
+      reservedLabels: [],
+    });
+
+    expect(labels).toEqual(['linux']);
+  });
+
+  it('uses the configured reserved labels when none are provided explicitly', () => {
+    const labels = sanitizeRunnerLabels(['linux', 'shipfox-managed'], {
+      scope: 'workspace',
+      source: 'test',
+    });
+
+    expect(labels).toEqual(['linux']);
+  });
+
+  it('throws when sanitization removes every canonical label', () => {
+    expect(() =>
+      sanitizeRunnerLabelsOrThrow([' Shipfox-Managed '], {
+        scope: 'workspace',
+        source: 'test',
+        reservedLabels: ['shipfox-managed'],
+      }),
+    ).toThrow(RunnerLabelsReservedError);
+  });
+});