@squiz/job-runner-lib 2.2.0 → 2.4.0

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

@@ -0,0 +1,29 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+/**
+ * Retry configuration with exponential backoff delays in seconds.
+ * Using SQS message timer limits (max 15 minutes = 900 seconds).
+ *
+ * Delays: 30s, 1min, 2min, 5min, 10min, 15min
+ */
+export const RETRY_DELAYS_SECONDS: ReadonlyArray<number> = [30, 60, 120, 300, 600, 900];
+
+/**
+ * Maximum number of retry attempts for container start failures.
+ */
+export const MAX_RETRY_ATTEMPTS = RETRY_DELAYS_SECONDS.length;
+
+/**
+ * Get the delay in seconds for a given retry attempt.
+ * @param retryAttempt - The current retry attempt (0-indexed)
+ * @returns The delay in seconds for this retry attempt
+ */
+export const getRetryDelaySeconds = (retryAttempt: number): number => {
+  if (retryAttempt >= RETRY_DELAYS_SECONDS.length) {
+    return RETRY_DELAYS_SECONDS[RETRY_DELAYS_SECONDS.length - 1];
+  }
+  return RETRY_DELAYS_SECONDS[retryAttempt];
+};

package/src/domains/job/core/pagination/services/PaginationService.spec.ts

@@ -5,7 +5,7 @@
 
 import { AttributeValue } from '@aws-sdk/client-dynamodb';
 import { faker } from '@faker-js/faker/locale/en';
-import { PartitionKey, PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { EntityType, ENTITY_TYPES } from '../../../constants/Repository.constants';
 import { PaginationInfo } from '../model/PaginationInfo';
 import { PAGINATION_DIRECTION_TYPE_AFTER, PAGINATION_DIRECTION_TYPE_BEFORE } from '../model/PaginationTypes';
 import { encodeTokenString } from '../utils/PaginationUtils';
@@ -20,16 +20,14 @@ describe('PaginationService', (): void => {
   });
 
   describe('addPaginationLinksToResponse', (): void => {
-    let mockType: PartitionKey;
+    let mockType: EntityType;
     let mockData;
     let mockPaginationInfo: PaginationInfo;
     let mockExclusiveStartKey: Record<string, AttributeValue>;
     const mockLastEvaluatedKey: string | null = null;
 
     beforeEach(() => {
-      jest.resetAllMocks();
-
-      mockType = PARTITION_KEYS.job;
+      mockType = ENTITY_TYPES.job;
 
       mockPaginationInfo = {
         direction: PAGINATION_DIRECTION_TYPE_AFTER,

package/src/domains/job/index.ts

@@ -1,23 +1,25 @@
-export * from './core/pagination';
 export * from './core/dynamoClient.mock';
+export * from './core/pagination';
 
+export * from './constants/InjectTokens';
 export * from './constants/JobExecutionStatus.constants';
 export * from './constants/Repository.constants';
+export * from './constants/RetryConfig.constants';
 
 export * from './services';
 export * from './utils';
 
+export * from './model/Base';
 export * from './model/Job';
 export * from './model/JobContext';
 export * from './model/JobExecution';
-export * from './model/Base';
 export * from './model/LogPayload';
 
 export * from './errors';
 export * from './manifest';
 export * from './ParsePartitionKey';
 
-export * from './transientProvider';
-export * from './singletonProvider';
 export * from './repository';
 export * from './S3Repository';
+export * from './singletonProvider';
+export * from './transientProvider';

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

@@ -5,7 +5,7 @@
 
 import { AttributeValue } from '@aws-sdk/client-dynamodb';
 import { MANIFEST_MODELS } from '@squiz/dx-json-schema-lib';
-import { PartitionKey } from '../constants/Repository.constants';
+import { EntityType } from '../constants/Repository.constants';
 
 /**
  * Job manifest interface.
@@ -59,10 +59,10 @@ export interface JobManifest {
 
   /**
    * The DynamoDB record type ('job').
-   * @type {PartitionKey}
+   * @type {EntityType}
    * @memberof JobManifest
    */
-  type: PartitionKey;
+  type: EntityType;
 }
 
 /**
@@ -73,10 +73,10 @@ export interface JobManifest {
 export interface JobManifestRecord {
   /**
    * The partition key ('manifest').
-   * @type {PartitionKey}
+   * @type {EntityType}
    * @memberof JobManifestRecord
    */
-  pk: PartitionKey;
+  pk: EntityType;
 
   /**
    * The sort key ('name-version').
@@ -142,4 +142,6 @@ export type CreateJobManifestRequest = Omit<JobManifest, 'type'>;
  * The request body for updating a job (PUT /job-manifest).
  * @export
  */
-export type UpdateJobManifestRequest = Partial<Omit<JobManifest, 'name' | 'type'>>;
+export type UpdateJobManifestRequest = Partial<Omit<JobManifest, 'name' | 'version' | 'type'>>;
+
+export type JobManifestSk = Pick<JobManifest, 'name' | 'version'>;

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

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

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

@@ -4,10 +4,11 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
-import { PARTITION_KEYS } from '../../constants/Repository.constants';
+import { ENTITY_TYPES } from '../../constants/Repository.constants';
 import { JobManifestDto, JobManifestRecord } from '../JobManifestTypes';
 
 export const createMockJobManifestDto = (partialRecord: Partial<JobManifestRecord> = {}): JobManifestDto => {
+  const tenant = faker.string.uuid();
   const name = faker.lorem.word();
   const version = Array.from({ length: 3 })
     .map(() => faker.number.int())
@@ -23,7 +24,7 @@ export const createMockJobManifestDto = (partialRecord: Partial<JobManifestRecor
       S: JSON.stringify(partialRecord.entryFunction) ?? JSON.stringify(input),
     },
     pk: {
-      S: partialRecord.pk ?? PARTITION_KEYS.manifest,
+      S: partialRecord.pk ?? `${ENTITY_TYPES.manifest}~${tenant}`,
     },
     sk: {
       S: partialRecord.sk ?? `${name}-${version}`,

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

@@ -4,10 +4,11 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
-import { PARTITION_KEYS } from '../../constants/Repository.constants';
+import { ENTITY_TYPES } from '../../constants/Repository.constants';
 import { JobManifestRecord } from '../JobManifestTypes';
 
 export const createMockJobManifestRecord = (partialRecord: Partial<JobManifestRecord> = {}): JobManifestRecord => {
+  const tenant = faker.string.uuid();
   const name = faker.lorem.word();
   const version = Array.from({ length: 3 })
     .map(() => faker.number.int())
@@ -22,8 +23,8 @@ export const createMockJobManifestRecord = (partialRecord: Partial<JobManifestRe
       entry: faker.system.filePath(),
       input,
     },
-    pk: PARTITION_KEYS.job,
-    sk: `${name}-${version}`,
+    pk: `${ENTITY_TYPES.manifest}~${tenant}`,
+    sk: `${name}~${version}`,
     name,
     version,
     timeoutSeconds: faker.number.int({ max: 28800, min: 5 }),

package/src/domains/job/model/Base/Base.ts

@@ -1,5 +1,5 @@
 import { AttributeValue } from '@aws-sdk/client-dynamodb';
-import { PartitionKey } from '../../constants/Repository.constants';
+import { EntityType } from '../../constants/Repository.constants';
 
 /**
  * The base interface for job runner entities.
@@ -9,10 +9,10 @@ import { PartitionKey } from '../../constants/Repository.constants';
 export interface BaseItem {
   /**
    * The property representing the corresponding record's partition key.
-   * @type {PartitionKey}
+   * @type {EntityType}
    * @memberof BaseItem
    */
-  type: PartitionKey;
+  type: EntityType;
 }
 
 /**
@@ -23,10 +23,10 @@ export interface BaseItem {
 export interface BaseRecord {
   /**
    * The partition key.
-   * @type {PartitionKey}
+   * @type {EntityType}
    * @memberof BaseRecord
    */
-  pk: PartitionKey;
+  pk: EntityType;
 
   /**
    * The sort key.
@@ -42,3 +42,9 @@ export interface BaseRecord {
  * @interface BaseDto
  */
 export type BaseDto = Record<keyof BaseRecord, AttributeValue>;
+
+export type ListParameters<TFilters> = {
+  filters?: TFilters;
+  consistentRead?: boolean;
+  limit?: number;
+};

package/src/domains/job/model/Job/Job.ts

@@ -4,7 +4,8 @@
  */
 
 import { AttributeValue } from '@aws-sdk/client-dynamodb';
-import { PartitionKey } from '../../constants/Repository.constants';
+import { EntityType } from '../../constants/Repository.constants';
+import { ListParameters } from '../Base';
 
 /**
  * Job interface.
@@ -35,10 +36,10 @@ export interface Job {
 
   /**
    * The DynamoDB record type ('job').
-   * @type {PartitionKey}
+   * @type {EntityType}
    * @memberof Job
    */
-  type: PartitionKey;
+  type: EntityType;
 }
 
 /**
@@ -49,10 +50,10 @@ export interface Job {
 export interface JobRecord {
   /**
    * The partition key ('job').
-   * @type {PartitionKey}
+   * @type {EntityType}
    * @memberof JobRecord
    */
-  pk: PartitionKey;
+  pk: EntityType;
 
   /**
    * The sort key ('name-version').
@@ -89,10 +90,14 @@ export type JobDto = Record<keyof JobRecord, AttributeValue>;
  * The parameters for listing jobs.
  * @export
  */
-export type ListJobParameters = Partial<Pick<Job, 'name' | 'version'>>;
+export type ListJobParameters = ListParameters<Partial<Pick<Job, 'name' | 'version'>>>;
 
 /**
  * The request body for creating a job (POST /job).
  * @export
  */
 export type CreateJobRequest = Omit<Job, 'type'>;
+
+export type UpdateJobRequest = Partial<Omit<Job, 'name' | 'version' | 'type'>>;
+
+export type JobSk = Pick<Job, 'name' | 'version'>;

package/src/domains/job/model/Job/mocks/Job.mock.ts

@@ -4,7 +4,7 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
-import { PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { ENTITY_TYPES } from '../../../constants/Repository.constants';
 import { Job } from '../Job';
 
 export const createMockJob = (partialRecord: Partial<Job> = {}): Job => {
@@ -14,7 +14,7 @@ export const createMockJob = (partialRecord: Partial<Job> = {}): Job => {
   return {
     name: faker.lorem.word(),
     description: faker.lorem.sentence(),
-    type: PARTITION_KEYS.job,
+    type: ENTITY_TYPES.job,
     version: version,
     ...partialRecord,
   };

package/src/domains/job/model/Job/mocks/JobDto.mock.ts

@@ -4,17 +4,18 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
-import { PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { ENTITY_TYPES } from '../../../constants/Repository.constants';
 import { JobDto, JobRecord } from '../Job';
 
 export const createMockJobDto = (partialRecord: Partial<JobRecord> = {}): JobDto => {
+  const tenant = faker.string.uuid();
   const version = Array.from({ length: 3 })
     .map(() => faker.number.int())
     .join('.');
 
   return {
     pk: {
-      S: partialRecord.pk ?? PARTITION_KEYS.job,
+      S: partialRecord.pk ?? `${ENTITY_TYPES.job}~${tenant}`,
     },
     sk: {
       S: partialRecord.sk ?? `${faker.lorem.word()}-${faker.lorem.word()}`,

package/src/domains/job/model/Job/mocks/JobRecord.mock.ts

@@ -4,16 +4,17 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
-import { PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { ENTITY_TYPES } from '../../../constants/Repository.constants';
 import { JobRecord } from '../Job';
 
 export const createMockJobRecord = (partialRecord: Partial<JobRecord> = {}): JobRecord => {
+  const tenant = faker.string.uuid();
   const version = Array.from({ length: 3 })
     .map(() => faker.number.int())
     .join('.');
 
   return {
-    pk: PARTITION_KEYS.job,
+    pk: `${ENTITY_TYPES.job}~${tenant}`,
     sk: `${faker.lorem.word()}-${faker.lorem.word()}`,
     name: faker.lorem.word(),
     description: faker.lorem.sentence(),

package/src/domains/job/model/JobContext/JobContext.ts

@@ -4,7 +4,7 @@
  */
 
 import { AttributeValue } from '@aws-sdk/client-dynamodb';
-import { PartitionKey } from '../../constants/Repository.constants';
+import { EntityType } from '../../constants/Repository.constants';
 
 /**
  * Environment interface.
@@ -45,10 +45,10 @@ export interface JobContext {
 
   /**
    * The DynamoDB record type ('context').
-   * @type {PartitionKey}
+   * @type {EntityType}
    * @memberof JobContext
    */
-  type: PartitionKey;
+  type: EntityType;
 }
 
 /**
@@ -59,10 +59,10 @@ export interface JobContext {
 export interface JobContextRecord {
   /**
    * The partition key ('context').
-   * @type {PartitionKey}
+   * @type {EntityType}
    * @memberof JobContextRecord
    */
-  pk: PartitionKey;
+  pk: EntityType;
 
   /**
    * The description of the job context.
@@ -99,3 +99,5 @@ export type CreateJobContextRequest = Omit<JobContext, 'type'>;
  * @export
  */
 export type UpdateJobContextRequest = Partial<Omit<JobContext, 'contextName' | 'type'>>;
+
+export type JobContextSk = Pick<JobContext, 'contextName'>;

package/src/domains/job/model/JobContext/mocks/JobContext.mock.ts

@@ -4,7 +4,7 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
-import { PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { ENTITY_TYPES } from '../../../constants/Repository.constants';
 import { JobContext } from '../JobContext';
 
 export const createMockJobContext = (partialRecord: Partial<JobContext> = {}): JobContext => {
@@ -23,7 +23,7 @@ export const createMockJobContext = (partialRecord: Partial<JobContext> = {}): J
     contextName: faker.lorem.word(),
     description: faker.lorem.words(),
     environment,
-    type: PARTITION_KEYS.context,
+    type: ENTITY_TYPES.context,
     ...partialRecord,
   };
 };

package/src/domains/job/model/JobContext/mocks/JobContextDto.mock.ts

@@ -4,10 +4,11 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
-import { PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { ENTITY_TYPES } from '../../../constants/Repository.constants';
 import { JobContextDto, JobContextRecord } from '../JobContext';
 
 export const createMockJobContextDto = (partialRecord: Partial<JobContextRecord> = {}): JobContextDto => {
+  const tenant = faker.string.uuid();
   const environment: Record<string, string> = partialRecord.environment ?? {};
 
   if (!partialRecord.environment) {
@@ -32,7 +33,7 @@ export const createMockJobContextDto = (partialRecord: Partial<JobContextRecord>
       S: partialRecord.description ?? faker.lorem.words(),
     },
     pk: {
-      S: partialRecord.pk ?? PARTITION_KEYS.context,
+      S: partialRecord.pk ?? `${ENTITY_TYPES.context}~${tenant}`,
     },
     sk: {
       S: partialRecord.sk ?? faker.lorem.word(),

package/src/domains/job/model/JobContext/mocks/JobContextRecord.mock.ts

@@ -4,10 +4,11 @@
  */
 
 import { faker } from '@faker-js/faker/locale/en';
-import { PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { ENTITY_TYPES } from '../../../constants/Repository.constants';
 import { JobContextRecord } from '../JobContext';
 
 export const createMockJobContextRecord = (partialRecord: Partial<JobContextRecord> = {}): JobContextRecord => {
+  const tenant = faker.string.uuid();
   const contextName = faker.lorem.word();
   const numOfEnvVars = faker.number.int({ max: 5, min: 1 });
   const environment: Record<string, string> = {};
@@ -20,7 +21,7 @@ export const createMockJobContextRecord = (partialRecord: Partial<JobContextReco
   return {
     environment,
     description,
-    pk: PARTITION_KEYS.context,
+    pk: `${ENTITY_TYPES.context}~${tenant}`,
     sk: contextName,
     ...partialRecord,
   };

package/src/domains/job/model/JobExecution/JobExecution.ts

@@ -3,9 +3,9 @@
  * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
  */
 
-import { JobExecutionStatus } from '../../constants/JobExecutionStatus.constants';
-import { JobExecutionPk } from '../../constants/Repository.constants';
 import { AttributeValue } from '@aws-sdk/client-dynamodb';
+import { JobExecutionStatus } from '../../constants/JobExecutionStatus.constants';
+import { ListParameters } from '../Base';
 
 /**
  * JobExecution interface.
@@ -85,10 +85,32 @@ export interface JobExecution {
 
   /**
    * The DynamoDB record type (dynamic, 'jobExecution-<jobName>').
-   * @type {JobExecutionPk}
+   * @type {string}
+   * @memberof JobExecution
+   */
+  type: string;
+
+  /**
+   * The number of times the container start has been retried.
+   * @type {number}
+   * @memberof JobExecution
+   */
+  retryCount: number;
+
+  /**
+   * The reason for the last container start failure (if any).
+   * @type {(string | null)}
    * @memberof JobExecution
    */
-  type: JobExecutionPk;
+  lastFailureReason: string | null;
+
+  /**
+   * ISO timestamp indicating when the execution can be retried.
+   * Used to implement exponential backoff - executions with retryAfter > now should be skipped.
+   * @type {(string | null)}
+   * @memberof JobExecution
+   */
+  retryAfter: string | null;
 }
 
 /**
@@ -98,19 +120,33 @@ export interface JobExecution {
  */
 export interface JobExecutionRecord {
   /**
-   * The partition key (dynamic, 'jobExecution-<jobName>').
-   * @type {JobExecutionPk}
+   * The partition key ('jobExecution~<tenant>').
+   * @type {string}
    * @memberof JobExecutionRecord
    */
-  pk: JobExecutionPk;
+  pk: string;
 
   /**
-   * The sort key ('timeQueued-id').
+   * The sort key ('<jobName>~<id>').
    * @type {string}
    * @memberof JobExecutionRecord
    */
   sk: string;
 
+  /**
+   * Secondary sort key ('<status>~<jobName>').
+   * @type {string}
+   * @memberof JobExecutionRecord
+   */
+  lsi1sk: string;
+
+  /**
+   * Global secondary partition key ('jobExecution~<status>').
+   * @type {string}
+   * @memberof JobExecutionRecord
+   */
+  gsi1pk: string;
+
   /**
    * The name of the job to execute.
    * @type {string}
@@ -180,6 +216,28 @@ export interface JobExecutionRecord {
    * @memberof JobExecutionRecord
    */
   input: any;
+
+  /**
+   * The number of times the container start has been retried.
+   * @type {number}
+   * @memberof JobExecutionRecord
+   */
+  retryCount: number;
+
+  /**
+   * The reason for the last container start failure (if any).
+   * @type {(string | null)}
+   * @memberof JobExecutionRecord
+   */
+  lastFailureReason: string | null;
+
+  /**
+   * ISO timestamp indicating when the execution can be retried.
+   * Used to implement exponential backoff - executions with retryAfter > now should be skipped.
+   * @type {(string | null)}
+   * @memberof JobExecutionRecord
+   */
+  retryAfter: string | null;
 }
 
 export type JobExecutionDto = Record<keyof JobExecutionRecord, AttributeValue>;
@@ -211,10 +269,17 @@ export interface TerminateJobExecutionRequest {
  * The parameters for listing job executions.
  * @export
  */
-export type ListJobExecutionParameters = Partial<Pick<JobExecution, 'jobName' | 'status'>>;
+export type ListJobExecutionParameters = ListParameters<Partial<Pick<JobExecution, 'jobName' | 'status'>>>;
 
 /**
  * The parameters for updating job executions.
  * @export
  */
 export type UpdateJobExecutionParameters = Partial<Omit<JobExecution, 'id' | 'jobName' | 'timeQueued' | 'type'>>;
+
+export type JobExecutionSk = Pick<JobExecution, 'jobName' | 'id'>;
+
+/**
+ * Array of job executions keys by tenant.
+ */
+export type JobExecutionsByTenant = Record<string, Array<JobExecution>>;

package/src/domains/job/model/JobExecution/mocks/JobExecution.mock.ts

@@ -3,9 +3,9 @@
  * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
  */
 
-import { JOB_EXECUTION_STATUS } from '../../../constants/JobExecutionStatus.constants';
-import { PARTITION_KEYS } from '../../../constants/Repository.constants';
 import { faker } from '@faker-js/faker/locale/en';
+import { JOB_EXECUTION_STATUS } from '../../../constants/JobExecutionStatus.constants';
+import { ENTITY_TYPES } from '../../../constants/Repository.constants';
 import { JobExecution } from '../JobExecution';
 
 export const createMockJobExecution = (partialRecord: Partial<JobExecution> = {}): JobExecution => {
@@ -19,7 +19,7 @@ export const createMockJobExecution = (partialRecord: Partial<JobExecution> = {}
     { [faker.lorem.word()]: faker.lorem.words() },
     null,
   ]);
-  const jobName = faker.lorem.word();
+  const jobName = partialRecord.jobName || faker.lorem.word();
   const timeQueued = new Date().toISOString();
   return {
     context: faker.string.uuid(),
@@ -30,9 +30,12 @@ export const createMockJobExecution = (partialRecord: Partial<JobExecution> = {}
     timeFinished: null,
     timeQueued,
     timeStarted: null,
-    type: `${PARTITION_KEYS.jobExecution}-${jobName}`,
+    type: `${ENTITY_TYPES.jobExecution}-${jobName}`,
     version,
     input,
+    retryCount: 0,
+    lastFailureReason: null,
+    retryAfter: null,
     ...partialRecord,
   };
 };