@squiz/job-runner-lib 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squiz/job-runner-lib",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "",
   "main": "lib/index.js",
   "private": false,
@@ -35,10 +35,10 @@
     "@aws-sdk/client-sqs": "3.1003.0",
     "@aws-sdk/s3-request-presigner": "3.1003.0",
     "@squiz/dx-common-lib": "^1.66.1",
-    "@squiz/dx-json-schema-lib": "1.78.1",
+    "@squiz/dx-json-schema-lib": "1.85.0",
     "@squiz/dx-logger-lib": "^1.64.0",
     "@squiz/optimization-logger": "^1.9.0",
-    "axios": "^1.13.6",
+    "axios": "^1.15.0",
     "cli-color": "^2.0.4",
     "fs-extra": "11.1.0",
     "immer": "^10.1.3",

package/src/domains/job/S3Repository/S3RepositoryBase.ts

@@ -31,6 +31,20 @@ export class S3RepositoryBase {
     this.bucketName = bucketName;
   }
 
+  /**
+   * Validates S3 key to prevent malicious input
+   * @param {string} key The S3 object key to validate
+   * @private
+   */
+  private validateS3Key(key: string): void {
+    if (!key || typeof key !== 'string') {
+      throw new Error('Invalid S3 key: must be a non-empty string');
+    }
+    if (key.includes('..') || key.startsWith('/')) {
+      throw new Error('Invalid S3 key: contains suspicious patterns');
+    }
+  }
+
   /**
    * Save object into S3.
    * @param {string} key The S3 object key.
@@ -39,6 +53,7 @@ export class S3RepositoryBase {
    * @memberof S3RepositoryBase
    */
   async put(key: string, body: PutObjectCommandInput['Body']): Promise<void> {
+    this.validateS3Key(key);
     await this.s3Client.send(
       new PutObjectCommand({
         Bucket: this.bucketName,
@@ -55,6 +70,7 @@ export class S3RepositoryBase {
    * @memberof S3RepositoryBase
    */
   public async delete(key: string): Promise<void> {
+    this.validateS3Key(key);
     await this.s3Client.send(
       new DeleteObjectCommand({
         Bucket: this.bucketName,
@@ -70,6 +86,7 @@ export class S3RepositoryBase {
    * @memberof S3RepositoryBase
    */
   async get(key: string): Promise<string | null> {
+    this.validateS3Key(key);
     const s3Object = await this.s3Client.send(
       new GetObjectCommand({
         Bucket: this.bucketName,
@@ -87,6 +104,7 @@ export class S3RepositoryBase {
    * @memberof S3RepositoryBase
    */
   async check(key: string): Promise<HeadObjectCommandOutput> {
+    this.validateS3Key(key);
     return this.s3Client.send(
       new HeadObjectCommand({
         Bucket: this.bucketName,
@@ -96,6 +114,7 @@ export class S3RepositoryBase {
   }
 
   async getS3SignedUrl(key: string): Promise<string> {
+    this.validateS3Key(key);
     const command = new GetObjectCommand({
       Bucket: this.bucketName,
       Key: key,

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

@@ -16,6 +16,11 @@ export const RETRY_DELAYS_SECONDS: ReadonlyArray<number> = [30, 60, 120, 300, 60
  */
 export const MAX_RETRY_ATTEMPTS = RETRY_DELAYS_SECONDS.length;
 
+/**
+ * After a job has attempted to be started this number of times alerts will start to be sent.
+ */
+export const ALERT_AFTER_ATTEMPTS = 2;
+
 /**
  * Get the delay in seconds for a given retry attempt.
  * @param retryAttempt - The current retry attempt (0-indexed)

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

@@ -0,0 +1,22 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+export const SUPPORTED_RUNTIME_IMAGES = ['node:20', 'node:24'] as const;
+
+// Default for jobs that pre-date runtime image support.
+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 getRuntimeImageOrDefault = (image: string | null | undefined): string =>
+  image && isSupportedRuntimeImage(image) ? image : LEGACY_RUNTIME_IMAGE;
+
+export const isSupportedRuntimeImage = (image: string): boolean =>
+  (SUPPORTED_RUNTIME_IMAGES as readonly string[]).includes(image);
+
+export const isDeprecatedRuntimeImage = (image: string): boolean => DEPRECATED_RUNTIME_IMAGES.includes(image);

package/src/domains/job/index.ts

@@ -5,6 +5,7 @@ export * from './constants/InjectTokens';
 export * from './constants/JobExecutionStatus.constants';
 export * from './constants/Repository.constants';
 export * from './constants/RetryConfig.constants';
+export * from './constants/RuntimeImage.constants';
 
 export * from './services';
 export * from './utils';

package/src/domains/job/manifest/JobManifestTypes.ts

@@ -57,6 +57,13 @@ export interface JobManifest {
    */
   concurrency: number;
 
+  /**
+   * The runtime image the job should execute against (e.g. `node:20`, `node:24`).
+   * @type {string}
+   * @memberof JobManifest
+   */
+  image: string;
+
   /**
    * The DynamoDB record type ('job').
    * @type {EntityType}
@@ -128,6 +135,13 @@ export interface JobManifestRecord {
    * @memberof JobManifestRecord
    */
   concurrency: number;
+
+  /**
+   * The runtime image the job should execute against (e.g. `node:20`, `node:24`).
+   * @type {string}
+   * @memberof JobManifestRecord
+   */
+  image: string;
 }
 
 export type JobManifestDto = Record<keyof JobManifestRecord, AttributeValue>;

package/src/domains/job/manifest/mocks/JobManifest.mock.ts

@@ -5,6 +5,7 @@
 
 import { faker } from '@faker-js/faker/locale/en';
 import { ENTITY_TYPES } from '../../constants/Repository.constants';
+import { LEGACY_RUNTIME_IMAGE } from '../../constants/RuntimeImage.constants';
 import { JobManifest } from '../JobManifestTypes';
 
 export const createMockJobManifest = (partialRecord: Partial<JobManifest> = {}): JobManifest => {
@@ -24,6 +25,7 @@ export const createMockJobManifest = (partialRecord: Partial<JobManifest> = {}):
     name: faker.lorem.word(),
     version,
     timeoutSeconds: faker.number.int({ max: 28800, min: 5 }),
+    image: LEGACY_RUNTIME_IMAGE,
     type: ENTITY_TYPES.manifest,
     ...partialRecord,
   };

package/src/domains/job/manifest/mocks/JobManifestDto.mock.ts

@@ -5,6 +5,7 @@
 
 import { faker } from '@faker-js/faker/locale/en';
 import { ENTITY_TYPES } from '../../constants/Repository.constants';
+import { LEGACY_RUNTIME_IMAGE } from '../../constants/RuntimeImage.constants';
 import { JobManifestDto, JobManifestRecord } from '../JobManifestTypes';
 
 export const createMockJobManifestDto = (partialRecord: Partial<JobManifestRecord> = {}): JobManifestDto => {
@@ -38,6 +39,9 @@ export const createMockJobManifestDto = (partialRecord: Partial<JobManifestRecor
     timeoutSeconds: {
       N: (partialRecord.timeoutSeconds ?? faker.number.int({ max: 28800, min: 5 })).toString(),
     },
+    image: {
+      S: partialRecord.image ?? LEGACY_RUNTIME_IMAGE,
+    },
   };
 };
 

package/src/domains/job/manifest/mocks/JobManifestRecord.mock.ts

@@ -5,6 +5,7 @@
 
 import { faker } from '@faker-js/faker/locale/en';
 import { ENTITY_TYPES } from '../../constants/Repository.constants';
+import { LEGACY_RUNTIME_IMAGE } from '../../constants/RuntimeImage.constants';
 import { JobManifestRecord } from '../JobManifestTypes';
 
 export const createMockJobManifestRecord = (partialRecord: Partial<JobManifestRecord> = {}): JobManifestRecord => {
@@ -28,6 +29,7 @@ export const createMockJobManifestRecord = (partialRecord: Partial<JobManifestRe
     name,
     version,
     timeoutSeconds: faker.number.int({ max: 28800, min: 5 }),
+    image: LEGACY_RUNTIME_IMAGE,
     ...partialRecord,
   };
 };

package/src/domains/job/manifest/mocks/JobManifestRequest.mock.ts

@@ -4,6 +4,7 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
+import { LEGACY_RUNTIME_IMAGE } from '../../constants/RuntimeImage.constants';
 import { CreateJobManifestRequest } from '../JobManifestTypes';
 
 export const createMockCreateJobManifestRequest = (
@@ -25,6 +26,7 @@ export const createMockCreateJobManifestRequest = (
     name: faker.lorem.word(),
     version,
     timeoutSeconds: faker.number.int({ max: 28800, min: 5 }),
+    image: LEGACY_RUNTIME_IMAGE,
     ...partialRecord,
   };
 };

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

@@ -26,6 +26,7 @@ import {
   createMockJobManifestRecord,
   createMockCreateJobManifestRequest,
 } from '../../manifest';
+import { LEGACY_RUNTIME_IMAGE } from '../../constants/RuntimeImage.constants';
 import { JobManifestRepository } from './JobManifestRepository';
 
 initIocContainer();
@@ -99,7 +100,7 @@ describe('JobManifestRepository', (): void => {
 
   describe('findOne', () => {
     it(`should return job manifest`, async (): Promise<void> => {
-      const mockJobManifestItem = createMockJobManifestDto();
+      const mockJobManifestItem = createMockJobManifestDto({ image: 'node:24' });
       mockSend.mockImplementationOnce(
         (): GetItemCommandOutput =>
           createMockClientGetResponse({
@@ -118,11 +119,34 @@ describe('JobManifestRepository', (): void => {
         version: mockJobManifestItem.version.S as string,
         entryFunction: JSON.parse(mockJobManifestItem.entryFunction.S as string),
         timeoutSeconds: parseInt(mockJobManifestItem.timeoutSeconds.N as string),
+        image: 'node:24',
         type: `manifest`,
       } as JobManifest);
       expect(mockSend).toBeCalledTimes(1);
     });
 
+    it(`should default missing image to legacy runtime`, async (): Promise<void> => {
+      const mockJobManifestItem = createMockJobManifestDto();
+      delete (mockJobManifestItem as Partial<typeof mockJobManifestItem>).image;
+
+      mockSend.mockImplementationOnce(
+        (): GetItemCommandOutput =>
+          createMockClientGetResponse({
+            Item: mockJobManifestItem,
+          }),
+      );
+
+      const response = await jobManifestRepository.findOne({
+        name: mockJobManifestItem.name.S as string,
+        version: mockJobManifestItem.version.S as string,
+      });
+      expect(response).toEqual(
+        expect.objectContaining({
+          image: LEGACY_RUNTIME_IMAGE,
+        }),
+      );
+    });
+
     it(`should return null if job manifest does not exist`, async (): Promise<void> => {
       mockSend.mockImplementationOnce(
         (): ScanCommandOutput =>
@@ -191,6 +215,14 @@ describe('JobManifestRepository', (): void => {
     });
   });
 
+  describe('convertToDynamoDbItem', () => {
+    it(`should persist image on the DynamoDB item`, () => {
+      const manifest = createMockJobManifest({ image: 'node:24' });
+      const dto = jobManifestRepository.convertToDynamoDbItem(manifest);
+      expect(dto.image).toEqual({ S: 'node:24' });
+    });
+  });
+
   describe('delete', () => {
     it(`should return undefined when calling the delete operation`, async (): Promise<void> => {
       mockSend.mockImplementationOnce((): DeleteItemCommandOutput => {

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

@@ -16,6 +16,7 @@ import {
   UpdateJobManifestRequest,
 } from '../../manifest';
 import { InjectTokens } from '../../constants/InjectTokens';
+import { getRuntimeImageOrDefault } from '../../constants/RuntimeImage.constants';
 import { parsePartitionKey } from '../../ParsePartitionKey';
 
 @provideTransient(JobManifestRepository)
@@ -68,6 +69,11 @@ export class JobManifestRepository extends Repository<JobManifest, JobManifestDt
       expressionAttributeValues[':timeoutSeconds'] = { N: input.timeoutSeconds.toString() };
     }
 
+    if (input.image) {
+      expressionAttributeNames['#image'] = 'image';
+      expressionAttributeValues[':image'] = { S: input.image };
+    }
+
     const updateExpressionPairs = Object.keys(input).map((key) => `#${key} = :${key}`);
     const updateExpression = `SET ${updateExpressionPairs.join(', ')}`;
 
@@ -91,11 +97,13 @@ export class JobManifestRepository extends Repository<JobManifest, JobManifestDt
       pk: { S: this.pk },
       sk: { S: `${item.name}~${item.version}` },
       timeoutSeconds: { N: item.timeoutSeconds.toString() },
+      image: { S: item.image },
     };
   }
 
   convertToItem(dbItem: JobManifestDto): JobManifest {
     const { pk, name, version, concurrency, entryFile, entryFunction, timeoutSeconds } = dbItem;
+    const image = (dbItem as Partial<JobManifestDto>).image?.S;
     return {
       concurrency: parseInt(concurrency.N as string),
       entryFile: entryFile.S as string,
@@ -103,6 +111,7 @@ export class JobManifestRepository extends Repository<JobManifest, JobManifestDt
       name: name.S as string,
       version: version.S as string,
       timeoutSeconds: parseInt(timeoutSeconds.N as string),
+      image: getRuntimeImageOrDefault(image),
       type: parsePartitionKey(pk.S as string).entityType,
     };
   }

package/src/domains/job/services/JobExecutionTaskService/JobExecutionTaskService.spec.ts

@@ -265,6 +265,59 @@ describe('JobExecutionTaskService', () => {
       expect(response).toBe(undefined);
     });
 
+    it('should handle when ECS returns no task ARNs or failures', async () => {
+      const jobContext = createMockJobContext();
+      const jobManifest = createMockJobManifest();
+      const jobExecution = createMockJobExecution({
+        id: `20250917T005949395Z-9602417782`,
+        jobName: 'jobName',
+        version: 'jobVersion',
+      });
+
+      mockJobContextService.findJobContext.mockResolvedValue(jobContext);
+      mockJobManifestService.findJobManifest.mockResolvedValue(jobManifest);
+      mockEcsClient.on(RunTaskCommand).resolves({ tasks: [], failures: [] });
+
+      const response = await jobExecutionTaskService.runJobExecutionTask({
+        ...defaultRunJobTaskParams,
+        jobExecution: jobExecution,
+      });
+
+      // Similar to a ConflictException being thrown. ECS appears to sometimes return an empty tasks and failures
+      // array when the idempotency key is used.
+      expect(response).toBe(undefined);
+    });
+
+    it('should throw when ECS returns no task ARNs and has failures', async () => {
+      const jobContext = createMockJobContext();
+      const jobManifest = createMockJobManifest();
+      const jobExecution = createMockJobExecution({
+        id: `20250917T005949395Z-9602417782`,
+        jobName: 'jobName',
+        version: 'jobVersion',
+      });
+      const failures = [
+        {
+          arn: faker.string.uuid(),
+          detail: 'Insufficient capacity to start job',
+          reason: faker.lorem.words(),
+        },
+      ];
+
+      mockJobContextService.findJobContext.mockResolvedValue(jobContext);
+      mockJobManifestService.findJobManifest.mockResolvedValue(jobManifest);
+      mockEcsClient.on(RunTaskCommand).resolves({ tasks: [], failures });
+
+      await expect(
+        jobExecutionTaskService.runJobExecutionTask({
+          ...defaultRunJobTaskParams,
+          jobExecution: jobExecution,
+        }),
+      ).rejects.toThrow(
+        `Execution start failed: ${JSON.stringify(failures)} (id: "20250917T005949395Z-9602417782", job: jobName, tenant: some_tenant)`,
+      );
+    });
+
     it('should re-throw unhandled errors when starting a task', async () => {
       const expectedError = new ResourceNotFoundException({ message: faker.lorem.words(), $metadata: {} });
       const jobContext = createMockJobContext();

package/src/domains/job/services/JobExecutionTaskService/JobExecutionTaskService.ts

@@ -121,6 +121,30 @@ export class JobExecutionTaskService {
         }),
       );
 
+      if (!result.tasks?.length) {
+        if (result.failures?.length) {
+          // Task has probably already started.
+          // ECS can sometimes return no tasks/failures if attempting to start
+          // the same task multiple times in quick succession:
+          //   * {"tasks":[],"failures":[],"$metadata":{"httpStatusCode":200,...}}
+          throw new Error(
+            `Execution start failed: ${JSON.stringify(result.failures)} ` +
+              `(id: "${params.jobExecution.id}", job: ${params.jobExecution.jobName}, tenant: ${params.tenantId})`,
+          );
+        } else {
+          // Task has probably already started.
+          // ECS can sometimes return no tasks/failures if attempting to start
+          // the same task multiple times in quick succession:
+          //   * {"tasks":[],"failures":[],"$metadata":{"httpStatusCode":200,...}}
+          console.warn(
+            `Execution start returned no ECS task ID` +
+              ` (id: "${params.jobExecution.id}", job: ${params.jobExecution.jobName}, tenant: ${params.tenantId})`,
+            JSON.stringify(result),
+          );
+          return undefined;
+        }
+      }
+
       // This task ARN can be used to terminate the job task.
       // If no error is returned, assume task has started.
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion

package/src/domains/job/services/JobManifestService/JobManifestService.spec.ts

@@ -87,6 +87,7 @@ describe('JobManifestService', (): void => {
         name: mockJobManifestItem.name.S as string,
         version: mockJobManifestItem.version.S as string,
         timeoutSeconds: parseInt(mockJobManifestItem.timeoutSeconds.N as string),
+        image: mockJobManifestItem.image.S as string,
         type: `manifest`,
       } as JobManifest);
       expect(mockSend).toBeCalledTimes(1);

package/src/domains/manifest/index.ts

@@ -3,6 +3,7 @@ export * from './services/JobFunctionService';
 
 export * from './utils/getAndAssertJobManifestVersion';
 export * from './utils/isValidManifestVersion';
+export * from './utils/validateRuntimeImage';
 
 export * from './ManifestModel';
 export * from '../job/manifest/JobManifestV1';

package/src/domains/manifest/services/ManifestServiceForDev.spec.ts

@@ -1,8 +1,8 @@
 import { ManifestServiceForDev } from './ManifestServiceForDev';
 
+import { ResourceNotFoundError } from '@squiz/dx-common-lib';
 import path from 'path';
 import { ManifestValidationError } from '../errors/ManifestValidationError';
-import { ResourceNotFoundError } from '@squiz/dx-common-lib';
 
 describe('ManifestServiceForDev', () => {
   const service = new ManifestServiceForDev();

package/src/domains/manifest/services/ManifestServiceForDev.ts

@@ -1,10 +1,10 @@
 import { ResourceNotFoundError } from '@squiz/dx-common-lib';
+import { JsonValidationService } from '@squiz/dx-json-schema-lib';
+import fsExtra from 'fs-extra';
+import { JobManifestV1 } from '../../job/manifest/JobManifestV1';
 import { ManifestValidationError } from '../errors/ManifestValidationError';
 import { JobManifestModel } from '../ManifestModel';
 import { getAndAssertJobManifestVersion } from '../utils/getAndAssertJobManifestVersion';
-import { JobManifestV1 } from '../../job/manifest/JobManifestV1';
-import { JsonValidationService } from '@squiz/dx-json-schema-lib';
-import fsExtra from 'fs-extra';
 
 export class ManifestServiceForDev {
   protected jobValidationService: JsonValidationService = new JsonValidationService();

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

@@ -0,0 +1,40 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+import * as runtimeImageConstants from '../../job/constants/RuntimeImage.constants';
+import { RECOMMENDED_RUNTIME_IMAGE, SUPPORTED_RUNTIME_IMAGES } from '../../job/constants/RuntimeImage.constants';
+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);
+  });
+
+  it('returns the recommended runtime image when image is null', () => {
+    expect(validateAndDefaultRuntimeImage(null)).toEqual(RECOMMENDED_RUNTIME_IMAGE);
+  });
+
+  it.each(SUPPORTED_RUNTIME_IMAGES)('returns "%s" when it is in the supported list', (supportedImage) => {
+    expect(validateAndDefaultRuntimeImage(supportedImage)).toEqual(supportedImage);
+  });
+
+  it('throws ManifestValidationError when the image is not supported', () => {
+    expect(() => validateAndDefaultRuntimeImage('node:18')).toThrow(ManifestValidationError);
+    expect(() => validateAndDefaultRuntimeImage('node:18')).toThrow(/Unsupported runtime image "node:18"/);
+  });
+
+  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/);
+  });
+});

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

@@ -0,0 +1,33 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+import {
+  RECOMMENDED_RUNTIME_IMAGE,
+  SUPPORTED_RUNTIME_IMAGES,
+  isDeprecatedRuntimeImage,
+  isSupportedRuntimeImage,
+} from '../../job/constants/RuntimeImage.constants';
+import { ManifestValidationError } from '../errors/ManifestValidationError';
+
+export const validateAndDefaultRuntimeImage = (image: string | null | undefined): string => {
+  if (image === null || image === undefined) {
+    return RECOMMENDED_RUNTIME_IMAGE;
+  }
+
+  if (!isSupportedRuntimeImage(image)) {
+    throw new ManifestValidationError(
+      `Unsupported runtime image "${image}". Supported images are: ${SUPPORTED_RUNTIME_IMAGES.join(', ')}`,
+    );
+  }
+
+  if (isDeprecatedRuntimeImage(image)) {
+    throw new ManifestValidationError(
+      `Runtime image "${image}" is deprecated and can no longer be used for new uploads. ` +
+        `Please use the recommended runtime image "${RECOMMENDED_RUNTIME_IMAGE}".`,
+    );
+  }
+
+  return image;
+};