@squiz/job-runner-lib 2.8.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squiz/job-runner-lib",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "",
   "main": "lib/index.js",
   "private": false,

package/src/domains/job/constants/QueueBacklog.constants.ts

@@ -0,0 +1,12 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+/**
+ * Backlog guard defaults. A job's `begin` is rejected with 422 once it has more than
+ * DEFAULT_MAX_QUEUED_EXECUTIONS queued AND its oldest queued execution is older than
+ * DEFAULT_MAX_QUEUED_AGE_HOURS. Both conditions are required (large AND stale).
+ */
+export const DEFAULT_MAX_QUEUED_EXECUTIONS = 500;
+export const DEFAULT_MAX_QUEUED_AGE_HOURS = 2;

package/src/domains/job/constants/RuntimeImage.constants.ts

@@ -11,7 +11,7 @@ export const LEGACY_RUNTIME_IMAGE = 'node:20';
 export const RECOMMENDED_RUNTIME_IMAGE = 'node:24';
 
 // Still runnable but rejected on new uploads.
-export const DEPRECATED_RUNTIME_IMAGES: readonly string[] = [];
+export const DEPRECATED_RUNTIME_IMAGES: readonly string[] = ['node:20'];
 
 export const getRuntimeImageOrDefault = (image: string | null | undefined): string =>
   image === null || image === undefined ? LEGACY_RUNTIME_IMAGE : image;

package/src/domains/job/index.ts

@@ -3,6 +3,7 @@ export * from './core/pagination';
 
 export * from './constants/InjectTokens';
 export * from './constants/JobExecutionStatus.constants';
+export * from './constants/QueueBacklog.constants';
 export * from './constants/Repository.constants';
 export * from './constants/RetryConfig.constants';
 export * from './constants/RuntimeImage.constants';

package/src/domains/job/repository/JobExecutionRepository/JobExecutionRepository.spec.ts

@@ -381,6 +381,71 @@ describe('JobExecutionRepository', (): void => {
     });
   });
 
+  describe('getOldestQueuedExecution', () => {
+    const jobName = 'backed-up-job';
+
+    it('queries lsi1 for the oldest queued execution (ascending, limit 1)', async () => {
+      const mockJobExecution = createMockJobExecution({ jobName, status: JOB_EXECUTION_STATUS.queued });
+      dynamoClient.on(QueryCommand).resolvesOnce({ Items: [createMockJobExecutionDto(mockJobExecution)] });
+
+      const result = await jobExecutionRepository.getOldestQueuedExecution(jobName);
+
+      expect(result).toEqual(mockJobExecution);
+      expect(dynamoClient).toHaveReceivedCommandWith(QueryCommand, {
+        TableName: tableName,
+        IndexName: 'lsi1',
+        KeyConditionExpression: '#pk = :pk and #lsi1sk = :lsi1sk',
+        ExpressionAttributeNames: { '#pk': 'pk', '#lsi1sk': 'lsi1sk' },
+        ExpressionAttributeValues: {
+          ':pk': { S: `${ENTITY_TYPES.jobExecution}~${tenant}` },
+          ':lsi1sk': { S: `${JOB_EXECUTION_STATUS.queued}~${jobName}` },
+        },
+        ScanIndexForward: true,
+        Limit: 1,
+      });
+    });
+
+    it('returns null when there are no queued executions', async () => {
+      dynamoClient.on(QueryCommand).resolvesOnce({ Items: [] });
+
+      const result = await jobExecutionRepository.getOldestQueuedExecution(jobName);
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('countQueuedExecutions', () => {
+    const jobName = 'backed-up-job';
+
+    it('counts queued executions on lsi1 bounded by limit', async () => {
+      dynamoClient.on(QueryCommand).resolvesOnce({ Count: 501 });
+
+      const result = await jobExecutionRepository.countQueuedExecutions(jobName, 501);
+
+      expect(result).toBe(501);
+      expect(dynamoClient).toHaveReceivedCommandWith(QueryCommand, {
+        TableName: tableName,
+        IndexName: 'lsi1',
+        Select: 'COUNT',
+        KeyConditionExpression: '#pk = :pk and #lsi1sk = :lsi1sk',
+        ExpressionAttributeNames: { '#pk': 'pk', '#lsi1sk': 'lsi1sk' },
+        ExpressionAttributeValues: {
+          ':pk': { S: `${ENTITY_TYPES.jobExecution}~${tenant}` },
+          ':lsi1sk': { S: `${JOB_EXECUTION_STATUS.queued}~${jobName}` },
+        },
+        Limit: 501,
+      });
+    });
+
+    it('returns 0 when DynamoDB returns no count', async () => {
+      dynamoClient.on(QueryCommand).resolvesOnce({});
+
+      const result = await jobExecutionRepository.countQueuedExecutions(jobName, 501);
+
+      expect(result).toBe(0);
+    });
+  });
+
   describe('update', () => {
     it('Updates the record properties', async () => {
       const jobExecution = createMockJobExecution({ status: JOB_EXECUTION_STATUS.queued });

package/src/domains/job/repository/JobExecutionRepository/JobExecutionRepository.ts

@@ -9,6 +9,7 @@ import {
   QueryCommand,
   QueryCommandInput,
   QueryCommandOutput,
+  Select,
   UpdateItemCommand,
   UpdateItemCommandInput,
 } from '@aws-sdk/client-dynamodb';
@@ -136,6 +137,58 @@ export class JobExecutionRepository extends Repository<JobExecution, JobExecutio
     return results.map((item) => this.convertToItem(item as JobExecutionDto));
   }
 
+  /**
+   * Returns the single oldest queued execution for a job, or null if there are none.
+   *
+   * Queries the `lsi1` index (`lsi1sk = "<status>~<jobName>"`). All queued executions of one
+   * job share the same `lsi1sk`, so DynamoDB breaks ties by the base-table `sk`
+   * (`"<jobName>~<id>"`); `id` is prefixed with the ISO `timeQueued`, which sorts
+   * lexicographically, so ascending order is chronological and the first item is the oldest.
+   */
+  async getOldestQueuedExecution(jobName: string): Promise<JobExecution | null> {
+    const res = await this.dynamoDbClient.send(
+      new QueryCommand({
+        TableName: this.tableName,
+        IndexName: 'lsi1',
+        KeyConditionExpression: '#pk = :pk and #lsi1sk = :lsi1sk',
+        ExpressionAttributeNames: { '#pk': 'pk', '#lsi1sk': 'lsi1sk' },
+        ExpressionAttributeValues: {
+          ':pk': { S: this.pk },
+          ':lsi1sk': { S: `${JOB_EXECUTION_STATUS.queued}~${jobName}` },
+        },
+        ScanIndexForward: true,
+        Limit: 1,
+      }),
+    );
+
+    const item = res.Items?.[0];
+    return item ? this.convertToItem(item as JobExecutionDto) : null;
+  }
+
+  /**
+   * Counts queued executions for a job, evaluating at most `limit` items (`Select: COUNT` so no
+   * item data is returned). Pass a `limit` just above the threshold you care about — queued
+   * items are small, so a single page covers the bounded count.
+   */
+  async countQueuedExecutions(jobName: string, limit?: number): Promise<number> {
+    const res = await this.dynamoDbClient.send(
+      new QueryCommand({
+        TableName: this.tableName,
+        IndexName: 'lsi1',
+        Select: Select.COUNT,
+        KeyConditionExpression: '#pk = :pk and #lsi1sk = :lsi1sk',
+        ExpressionAttributeNames: { '#pk': 'pk', '#lsi1sk': 'lsi1sk' },
+        ExpressionAttributeValues: {
+          ':pk': { S: this.pk },
+          ':lsi1sk': { S: `${JOB_EXECUTION_STATUS.queued}~${jobName}` },
+        },
+        Limit: limit,
+      }),
+    );
+
+    return res.Count ?? 0;
+  }
+
   /**
    * Get list of records from database.
    * @abstract

package/src/domains/manifest/utils/validateRuntimeImage.spec.ts

@@ -3,7 +3,6 @@
  * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
  */
 
-import * as runtimeImageConstants from '../../job/constants/RuntimeImage.constants';
 import {
   DEPRECATED_RUNTIME_IMAGES,
   RECOMMENDED_RUNTIME_IMAGE,
@@ -13,10 +12,6 @@ import { ManifestValidationError } from '../errors/ManifestValidationError';
 import { validateAndDefaultRuntimeImage } from './validateRuntimeImage';
 
 describe('validateAndDefaultRuntimeImage', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
   it('returns the recommended runtime image when image is undefined', () => {
     expect(validateAndDefaultRuntimeImage(undefined)).toEqual(RECOMMENDED_RUNTIME_IMAGE);
   });
@@ -38,9 +33,6 @@ describe('validateAndDefaultRuntimeImage', () => {
   });
 
   it('throws ManifestValidationError when the image is deprecated', () => {
-    jest.spyOn(runtimeImageConstants, 'isSupportedRuntimeImage').mockReturnValue(true);
-    jest.spyOn(runtimeImageConstants, 'isDeprecatedRuntimeImage').mockReturnValue(true);
-
     expect(() => validateAndDefaultRuntimeImage('node:20')).toThrow(ManifestValidationError);
     expect(() => validateAndDefaultRuntimeImage('node:20')).toThrow(/deprecated/);
   });