CCM-13906 Urgent Letter Priority

Author: stevebux

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       = "queueSortOrder-SK"
     projection_type = "ALL"
   }
 
@@ -27,7 +27,7 @@ resource "aws_dynamodb_table" "letter_queue" {
   }
 
   attribute {
-    name = "queueTimestamp"
+    name = "queueSortOrder-SK"
     type = "S"
   }
 

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",

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,20 @@ 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 ?? 10);
+    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({