@shipfox/api-runners 12.1.0 → 12.3.0

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),
@@ -155,13 +163,37 @@ export async function enrollRunnerControlSession(params: {
         sql`select pg_advisory_xact_lock(hashtext(${`runners_assignment:${params.provisionerId}:${current.intendedReservationId}`}))`,
       );
 
-    const [updated] = await tx
+    // Provider reports may populate reservationId before the assignment commits. assignedAt is
+    // written by the assignment transaction, so keep the guard on that write boundary.
+    const [metadataUpdated] = 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,
+      })
+      .where(
+        and(
+          eq(providerRunners.id, params.runnerInstanceId),
+          eq(providerRunners.provisionerId, params.provisionerId),
+          isNull(providerRunners.assignedAt),
+          notInArray(providerRunners.state, [...terminalStates]),
+        ),
+      )
+      .returning({id: providerRunners.id});
+    if (!metadataUpdated)
+      logger().debug(
+        {runnerInstanceId: params.runnerInstanceId, provisionerId: params.provisionerId},
+        'Runner enrollment metadata update skipped for assigned or terminal runner',
+      );
+
+    const [updated] = await tx
+      .update(providerRunners)
+      .set({
         state: 'running',
         reportedAt: sql`now()`,
         updatedAt: sql`now()`,
@@ -198,29 +230,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);
+  });
+});

package/src/core/runner-labels.ts

@@ -0,0 +1,51 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import {canonicalizeLabels} from '@shipfox/runner-labels';
+import {runnerReservedLabels} from '#config.js';
+import {RunnerLabelsReservedError} from './errors.js';
+
+export type RunnerLabelScope = 'installation' | 'workspace' | 'manual';
+
+type SanitizeRunnerLabelsParams = {
+  scope: RunnerLabelScope;
+  source: string;
+  logLevel?: 'debug' | 'warn';
+  reservedLabels?: readonly string[];
+};
+
+function sanitizeCanonicalRunnerLabels(
+  canonicalLabels: readonly string[],
+  params: SanitizeRunnerLabelsParams,
+): string[] {
+  if (params.scope === 'installation') return [...canonicalLabels];
+
+  const reservedLabels = new Set(canonicalizeLabels(params.reservedLabels ?? runnerReservedLabels));
+  if (reservedLabels.size === 0) return [...canonicalLabels];
+
+  const removedLabels = canonicalLabels.filter((label) => reservedLabels.has(label));
+  if (removedLabels.length === 0) return [...canonicalLabels];
+
+  const details = {source: params.source, removedLabels};
+  if (params.logLevel === 'debug')
+    logger().debug(details, 'Removed reserved runner labels from a non-installation source');
+  else logger().warn(details, 'Removed reserved runner labels from a non-installation source');
+  return canonicalLabels.filter((label) => !reservedLabels.has(label));
+}
+
+export function sanitizeRunnerLabels(
+  labels: readonly string[],
+  params: SanitizeRunnerLabelsParams,
+): string[] {
+  return sanitizeCanonicalRunnerLabels([...canonicalizeLabels(labels)], params);
+}
+
+export function sanitizeRunnerLabelsOrThrow(
+  labels: readonly string[],
+  params: SanitizeRunnerLabelsParams,
+): string[] {
+  const canonicalLabels = [...canonicalizeLabels(labels)];
+  const sanitizedLabels = sanitizeCanonicalRunnerLabels(canonicalLabels, params);
+  if (sanitizedLabels.length === 0 && canonicalLabels.length > 0) {
+    throw new RunnerLabelsReservedError(canonicalLabels);
+  }
+  return sanitizedLabels;
+}

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

@@ -9,12 +9,14 @@ import {
   getRunnerSessionTokenClaims,
   manualRegistrationTokenFactory,
   providerRunnerFactory,
+  provisionerTokenFactory,
   runnersTestAuthClient,
 } from '#test/index.js';
 import {
   EmptyRunnerLabelsError,
   RegistrationTokenConsumedError,
   RegistrationTokenWorkspaceMismatchError,
+  RunnerLabelsReservedError,
 } from './errors.js';
 import {issueRunnerActivationToken} from './runner-activation.js';
 import {registerRunnerSession} from './runner-sessions.js';
@@ -66,6 +68,15 @@ describe('registerRunnerSession', () => {
     ).rejects.toBeInstanceOf(EmptyRunnerLabelsError);
   });
 
+  it('names labels removed by the reserved-label policy', () => {
+    const error = new RunnerLabelsReservedError(['shipfox-managed']);
+
+    expect(error.message).toBe(
+      'All supplied runner labels are reserved for installation-scope provisioners: shipfox-managed',
+    );
+    expect(error.labels).toEqual(['shipfox-managed']);
+  });
+
   it('consumes an ephemeral token and creates a one-claim session', async () => {
     const token = await ephemeralRegistrationTokenFactory.create({workspaceId});
 
@@ -223,7 +234,8 @@ describe('activation runner sessions', () => {
 
   beforeEach(async () => {
     workspaceId = crypto.randomUUID();
-    provisionerId = crypto.randomUUID();
+    const provisioner = await provisionerTokenFactory.create({workspaceId});
+    provisionerId = provisioner.id;
     const runner = await providerRunnerFactory.create({workspaceId, provisionerId});
     runnerInstanceId = runner.id;
   });
@@ -296,4 +308,25 @@ describe('activation runner sessions', () => {
     expect(storedToken?.consumedAt).toBeInstanceOf(Date);
     expect(sessions).toHaveLength(1);
   });
+
+  it('strips reserved labels from workspace activation registration', async () => {
+    const rawToken = await issueRunnerActivationToken({
+      runnerInstanceId,
+      provisionerId,
+      ttlSeconds: 60,
+    });
+    const [activationToken] = await db()
+      .select()
+      .from(runnerActivationTokens)
+      .where(eq(runnerActivationTokens.runnerInstanceId, runnerInstanceId));
+    if (!rawToken || !activationToken) throw new Error('Activation token was not created');
+
+    const result = await registerRunnerSession({
+      auth: runnersTestAuthClient,
+      credential: {kind: 'activation', activationTokenId: activationToken.id, workspaceId},
+      labels: ['linux', 'shipfox-managed'],
+    });
+
+    expect(result.session.labels).toEqual(['linux']);
+  });
 });

package/src/core/runner-sessions.ts

@@ -8,6 +8,7 @@ import {
 } from '#db/runner-sessions.js';
 import type {RunnerSession} from './entities/runner-session.js';
 import {EmptyRunnerLabelsError} from './errors.js';
+import {sanitizeRunnerLabelsOrThrow} from './runner-labels.js';
 
 export interface RegisterRunnerSessionResult {
   session: RunnerSession;
@@ -38,7 +39,13 @@ export async function registerRunnerSession(params: {
   labels: string[];
   toolCapabilities?: RunnerToolCapabilitiesDto | null;
 }): Promise<RegisterRunnerSessionResult> {
-  const labels = [...canonicalizeLabels(params.labels)];
+  const labels =
+    params.credential.kind === 'manual'
+      ? sanitizeRunnerLabelsOrThrow(params.labels, {
+          scope: 'manual',
+          source: 'manual runner registration',
+        })
+      : [...canonicalizeLabels(params.labels)];
   if (labels.length === 0) throw new EmptyRunnerLabelsError();
 
   const mode = params.credential.kind;

package/src/db/ephemeral-registration-tokens.ts

@@ -4,6 +4,7 @@ import type {EphemeralRegistrationToken} from '#core/entities/ephemeral-registra
 import {
   ActiveEphemeralRegistrationTokenExistsError,
   ActiveEphemeralRegistrationTokensExistError,
+  EmptyRunnerLabelsError,
   RegistrationTokenBatchExceedsReservationError,
   RegistrationTokenConsumedError,
   RegistrationTokenExpiredError,
@@ -11,11 +12,13 @@ import {
   ReservationExpiredError,
   ReservationNotFoundError,
 } from '#core/errors.js';
+import {sanitizeRunnerLabelsOrThrow} from '#core/runner-labels.js';
 import {db} from './db.js';
 import {
   ephemeralRegistrationTokens,
   toEphemeralRegistrationToken,
 } from './schema/ephemeral-registration-tokens.js';
+import {provisionerTokens} from './schema/provisioner-tokens.js';
 import {reservations} from './schema/reservations.js';
 import {providerRunners} from './schema/runner-instances.js';
 import {runnerSessions, toRunnerSession} from './schema/runner-sessions.js';
@@ -307,6 +310,17 @@ export async function createRunnerSessionConsumingEphemeralToken(params: {
       );
     }
 
+    const [provisioner] = await tx
+      .select({scope: provisionerTokens.scope})
+      .from(provisionerTokens)
+      .where(eq(provisionerTokens.id, consumed[0].provisionerId))
+      .limit(1);
+    const labels = sanitizeRunnerLabelsOrThrow(params.labels, {
+      scope: provisioner?.scope ?? 'workspace',
+      source: 'ephemeral runner registration',
+    });
+    if (labels.length === 0) throw new EmptyRunnerLabelsError();
+
     const [session] = await tx
       .insert(runnerSessions)
       .values({
@@ -316,7 +330,7 @@ export async function createRunnerSessionConsumingEphemeralToken(params: {
         registrationTokenKind: 'ephemeral',
         provisionerId: consumed[0].provisionerId,
         providerRunnerId: consumed[0].providerRunnerId,
-        labels: params.labels,
+        labels,
         toolCapabilities: params.toolCapabilities ?? null,
         toolCapabilitiesReportedAt: params.toolCapabilities ? sql`now()` : null,
         maxClaims: params.maxClaims,

package/src/db/index.ts

@@ -90,6 +90,7 @@ export type {
 } from './runner-instances.js';
 export {
   attachRunnerInstanceProviderId,
+  countStaleEnrolledRunnerInstances,
   isTerminalState,
   listActiveRunnerInstanceCountsByTemplateTx,
   listActiveRunnerInstances,