Feature/ccm 13906 urgent letter priority

infrastructure/terraform/components/api/README.md

@@ -30,7 +30,7 @@ No requirements.
 | <a name="input_group"></a> [group](#input\_group) | The group variables are being inherited from (often synonmous with account short-name) | `string` | n/a | yes |
 | <a name="input_kms_deletion_window"></a> [kms\_deletion\_window](#input\_kms\_deletion\_window) | When a kms key is deleted, how long should it wait in the pending deletion state? | `string` | `"30"` | no |
 | <a name="input_letter_table_ttl_hours"></a> [letter\_table\_ttl\_hours](#input\_letter\_table\_ttl\_hours) | Number of hours to set as TTL on letters table | `number` | `24` | no |
-| <a name="input_letter_variant_map"></a> [letter\_variant\_map](#input\_letter\_variant\_map) | n/a | `map(object({ supplierId = string, specId = string }))` | <pre>{<br/>  "lv1": {<br/>    "specId": "spec1",<br/>    "supplierId": "supplier1"<br/>  },<br/>  "lv2": {<br/>    "specId": "spec2",<br/>    "supplierId": "supplier1"<br/>  },<br/>  "lv3": {<br/>    "specId": "spec3",<br/>    "supplierId": "supplier2"<br/>  }<br/>}</pre> | no |
+| <a name="input_letter_variant_map"></a> [letter\_variant\_map](#input\_letter\_variant\_map) | n/a | `map(object({ supplierId = string, specId = string, priority = number }))` | <pre>{<br/>  "lv1": {<br/>    "priority": 10,<br/>    "specId": "spec1",<br/>    "supplierId": "supplier1"<br/>  },<br/>  "lv2": {<br/>    "priority": 10,<br/>    "specId": "spec2",<br/>    "supplierId": "supplier1"<br/>  },<br/>  "lv3": {<br/>    "priority": 10,<br/>    "specId": "spec3",<br/>    "supplierId": "supplier2"<br/>  }<br/>}</pre> | no |
 | <a name="input_log_level"></a> [log\_level](#input\_log\_level) | The log level to be used in lambda functions within the component. Any log with a lower severity than the configured value will not be logged: https://docs.python.org/3/library/logging.html#levels | `string` | `"INFO"` | no |
 | <a name="input_log_retention_in_days"></a> [log\_retention\_in\_days](#input\_log\_retention\_in\_days) | The retention period in days for the Cloudwatch Logs events to be retained, default of 0 is indefinite | `number` | `0` | no |
 | <a name="input_manually_configure_mtls_truststore"></a> [manually\_configure\_mtls\_truststore](#input\_manually\_configure\_mtls\_truststore) | Manually manage the truststore used for API Gateway mTLS (e.g. for prod environment) | `bool` | `false` | no |

infrastructure/terraform/components/api/ddb_table_letter_queue.tf

@@ -12,7 +12,7 @@ resource "aws_dynamodb_table" "letter_queue" {
 
   local_secondary_index {
     name            = "queueSortOrder-index"
-    range_key       = "queueTimestamp"
+    range_key       = "queueSortOrderSk"
     projection_type = "ALL"
   }
 
@@ -27,7 +27,7 @@ resource "aws_dynamodb_table" "letter_queue" {
   }
 
   attribute {
-    name = "queueTimestamp"
+    name = "queueSortOrderSk"
     type = "S"
   }
 

infrastructure/terraform/components/api/variables.tf

@@ -136,11 +136,11 @@ variable "eventpub_control_plane_bus_arn" {
 }
 
 variable "letter_variant_map" {
-  type = map(object({ supplierId = string, specId = string }))
+  type = map(object({ supplierId = string, specId = string, priority = number }))
   default = {
-    "lv1" = { supplierId = "supplier1", specId = "spec1" },
-    "lv2" = { supplierId = "supplier1", specId = "spec2" },
-    "lv3" = { supplierId = "supplier2", specId = "spec3" }
+    "lv1" = { supplierId = "supplier1", specId = "spec1", priority = 10 },
+    "lv2" = { supplierId = "supplier1", specId = "spec2", priority = 10 },
+    "lv3" = { supplierId = "supplier2", specId = "spec3", priority = 10 }
   }
 }
 

internal/datastore/src/__test__/db.ts

@@ -22,6 +22,7 @@ export async function setupDynamoDBContainer() {
       accessKeyId: "fakeMyKeyId",
       secretAccessKey: "fakeSecretAccessKey",
     },
+    maxAttempts: 1,
   });
 
   const docClient = DynamoDBDocumentClient.from(ddbClient);
@@ -132,7 +133,7 @@ const createLetterQueueTableCommand = new CreateTableCommand({
       IndexName: "queueSortOrder-index",
       KeySchema: [
         { AttributeName: "supplierId", KeyType: "HASH" }, // Partition key for LSI
-        { AttributeName: "queueTimestamp", KeyType: "RANGE" }, // Sort key for LSI
+        { AttributeName: "queueSortOrderSk", KeyType: "RANGE" }, // Sort key for LSI
       ],
       Projection: {
         ProjectionType: "ALL",
@@ -142,7 +143,7 @@ const createLetterQueueTableCommand = new CreateTableCommand({
   AttributeDefinitions: [
     { AttributeName: "supplierId", AttributeType: "S" },
     { AttributeName: "letterId", AttributeType: "S" },
-    { AttributeName: "queueTimestamp", AttributeType: "S" },
+    { AttributeName: "queueSortOrderSk", AttributeType: "S" },
   ],
 });
 

internal/datastore/src/__test__/letter-queue-repository.test.ts

@@ -12,12 +12,16 @@ import { LetterAlreadyExistsError } from "../letter-already-exists-error";
 import { createTestLogger } from "./logs";
 import { LetterDoesNotExistError } from "../letter-does-not-exist-error";
 
-function createLetter(letterId = "letter1"): InsertPendingLetter {
+function createLetter(
+  overrides: Partial<InsertPendingLetter> = {},
+): InsertPendingLetter {
   return {
-    letterId,
+    letterId: "letter1",
     supplierId: "supplier1",
     specificationId: "specification1",
     groupId: "group1",
+    priority: 10,
+    ...overrides,
   };
 }
 
@@ -54,9 +58,11 @@ describe("LetterQueueRepository", () => {
   });
 
   describe("putLetter", () => {
-    it("adds a letter to the database", async () => {
+    beforeEach(() => {
       jest.useFakeTimers().setSystemTime(new Date("2026-03-04T13:15:45.000Z"));
+    });
 
+    it("adds a letter to the database", async () => {
       const pendingLetter =
         await letterQueueRepository.putLetter(createLetter());
 
@@ -65,9 +71,32 @@ describe("LetterQueueRepository", () => {
         "2026-03-04T13:15:45.000Z",
       );
       expect(pendingLetter.ttl).toBe(1_772_633_745);
+      expect(pendingLetter.queueSortOrderSk).toBe(
+        "10-2026-03-04T13:15:45.000Z",
+      );
       expect(await letterExists(db, "supplier1", "letter1")).toBe(true);
     });
 
+    it("left-pads the priority with zeros in the sort key", async () => {
+      const pendingLetter = await letterQueueRepository.putLetter(
+        createLetter({ priority: 5 }),
+      );
+
+      expect(pendingLetter.queueSortOrderSk).toBe(
+        "05-2026-03-04T13:15:45.000Z",
+      );
+    });
+
+    it("defaults a missing priority to 10 in the sort key", async () => {
+      const pendingLetter = await letterQueueRepository.putLetter(
+        createLetter({ priority: undefined }),
+      );
+
+      expect(pendingLetter.queueSortOrderSk).toBe(
+        "10-2026-03-04T13:15:45.000Z",
+      );
+    });
+
     it("throws LetterAlreadyExistsError when creating a letter which already exists", async () => {
       await letterQueueRepository.putLetter(createLetter());
 
@@ -122,16 +151,21 @@ describe("LetterQueueRepository", () => {
   });
 });
 
-async function letterExists(
-  db: DBContext,
-  supplierId: string,
-  letterId: string,
-): Promise<boolean> {
+async function getLetter(db: DBContext, supplierId: string, letterId: string) {
   const result = await db.docClient.send(
     new GetCommand({
       TableName: db.config.letterQueueTableName,
       Key: { supplierId, letterId },
     }),
   );
-  return result.Item !== undefined;
+  return result.Item;
+}
+
+async function letterExists(
+  db: DBContext,
+  supplierId: string,
+  letterId: string,
+): Promise<boolean> {
+  const letter = await getLetter(db, supplierId, letterId);
+  return letter !== undefined;
 }

internal/datastore/src/letter-queue-repository.ts

@@ -24,16 +24,22 @@ export default class LetterQueueRepository {
     readonly config: LetterQueueRepositoryConfig,
   ) {}
 
+  private readonly defaultPriority = 10;
+
   async putLetter(
     insertPendingLetter: InsertPendingLetter,
   ): Promise<PendingLetter> {
     // needs to be an ISO timestamp as Db sorts alphabetically
     const now = new Date().toISOString();
-
+    const priority = String(
+      insertPendingLetter.priority ?? this.defaultPriority,
+    );
+    const queueSortOrderSk = `${priority.padStart(2, "0")}-${now}`;
     const pendingLetter: PendingLetter = {
       ...insertPendingLetter,
       queueTimestamp: now,
       visibilityTimestamp: now,
+      queueSortOrderSk,
       ttl: Math.floor(
         Date.now() / 1000 + 60 * 60 * this.config.letterQueueTtlHours,
       ),

internal/datastore/src/types.ts

@@ -43,6 +43,7 @@ export const LetterSchemaBase = z.object({
 export const LetterSchema = LetterSchemaBase.extend({
   supplierId: idRef(SupplierSchema, "id"),
   eventId: z.string().optional(),
+  priority: z.int().min(0).max(99).optional(), // A lower number represents a higher priority
   url: z.url(),
   createdAt: z.string(),
   updatedAt: z.string(),
@@ -79,18 +80,20 @@ export type UpdateLetter = {
 export const PendingLetterSchema = z.object({
   supplierId: idRef(SupplierSchema, "id"),
   letterId: idRef(LetterSchema, "id"),
-  queueTimestamp: z.string().describe("Secondary index SK"),
+  queueTimestamp: z.string(),
   visibilityTimestamp: z.string(),
+  queueSortOrderSk: z.string().describe("Secondary index SK"),
   specificationId: z.string(),
   groupId: z.string(),
+  priority: z.int().min(0).max(99).optional(),
   ttl: z.int(),
 });
 
 export type PendingLetter = z.infer<typeof PendingLetterSchema>;
 
 export type InsertPendingLetter = Omit<
   PendingLetter,
-  "ttl" | "queueTimestamp" | "visibilityTimestamp"
+  "ttl" | "queueTimestamp" | "visibilityTimestamp" | "queueSortOrderSk"
 >;
 
 export const MISchemaBase = z.object({

lambdas/supplier-allocator/package.json

@@ -9,6 +9,7 @@
     "@nhsdigital/nhs-notify-event-schemas-letter-rendering-v1": "npm:@nhsdigital/nhs-notify-event-schemas-letter-rendering@^1.1.5",
     "@nhsdigital/nhs-notify-event-schemas-supplier-api": "^1.0.8",
     "@types/aws-lambda": "^8.10.148",
+    "aws-embedded-metrics": "^4.2.1",
     "aws-lambda": "^1.0.7",
     "esbuild": "^0.27.2",
     "pino": "^9.7.0",

lambdas/supplier-allocator/src/config/__tests__/env.test.ts

@@ -18,7 +18,8 @@ describe("lambdaEnv", () => {
     process.env.VARIANT_MAP = `{
       "lv1": {
         "supplierId": "supplier1",
-        "specId": "spec1"
+        "specId": "spec1",
+        "priority": 10
       }
     }`;
 
@@ -29,6 +30,7 @@ describe("lambdaEnv", () => {
         lv1: {
           supplierId: "supplier1",
           specId: "spec1",
+          priority: 10,
         },
       },
     });

lambdas/supplier-allocator/src/config/env.ts

@@ -5,6 +5,7 @@ const LetterVariantSchema = z.record(
   z.object({
     supplierId: z.string(),
     specId: z.string(),
+    priority: z.int().min(0).max(99), // Lower number represents a higher priority
   }),
 );
 export type LetterVariant = z.infer<typeof LetterVariantSchema>;