CCM-13116 Letter queue operations

infrastructure/terraform/components/api/README.md

@@ -45,7 +45,7 @@ No requirements.
 | Name | Source | Version |
 |------|--------|---------|
 | <a name="module_amendment_event_transformer"></a> [amendment\_event\_transformer](#module\_amendment\_event\_transformer) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
-| <a name="module_amendments_queue"></a> [amendments\_queue](#module\_amendments\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.24/terraform-sqs.zip | n/a |
+| <a name="module_amendments_queue"></a> [amendments\_queue](#module\_amendments\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.5/terraform-sqs.zip | n/a |
 | <a name="module_authorizer_lambda"></a> [authorizer\_lambda](#module\_authorizer\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_ddb_alarms_letter_queue"></a> [ddb\_alarms\_letter\_queue](#module\_ddb\_alarms\_letter\_queue) | ../../modules/alarms-ddb | n/a |
 | <a name="module_ddb_alarms_letters"></a> [ddb\_alarms\_letters](#module\_ddb\_alarms\_letters) | ../../modules/alarms-ddb | n/a |
@@ -60,16 +60,16 @@ No requirements.
 | <a name="module_get_status"></a> [get\_status](#module\_get\_status) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_kms"></a> [kms](#module\_kms) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-kms.zip | n/a |
 | <a name="module_lambda_alarms"></a> [lambda\_alarms](#module\_lambda\_alarms) | ../../modules/alarms-lambda | n/a |
-| <a name="module_letter_status_updates_queue"></a> [letter\_status\_updates\_queue](#module\_letter\_status\_updates\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.24/terraform-sqs.zip | n/a |
+| <a name="module_letter_status_updates_queue"></a> [letter\_status\_updates\_queue](#module\_letter\_status\_updates\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.5/terraform-sqs.zip | n/a |
 | <a name="module_letter_updates_transformer"></a> [letter\_updates\_transformer](#module\_letter\_updates\_transformer) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_mi_updates_transformer"></a> [mi\_updates\_transformer](#module\_mi\_updates\_transformer) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-lambda.zip | n/a |
 | <a name="module_patch_letter"></a> [patch\_letter](#module\_patch\_letter) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_post_letters"></a> [post\_letters](#module\_post\_letters) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_post_mi"></a> [post\_mi](#module\_post\_mi) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_s3bucket_test_letters"></a> [s3bucket\_test\_letters](#module\_s3bucket\_test\_letters) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-s3bucket.zip | n/a |
 | <a name="module_sqs_alarms"></a> [sqs\_alarms](#module\_sqs\_alarms) | ../../modules/alarms-sqs | n/a |
-| <a name="module_sqs_letter_updates"></a> [sqs\_letter\_updates](#module\_sqs\_letter\_updates) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-sqs.zip | n/a |
-| <a name="module_sqs_supplier_allocator"></a> [sqs\_supplier\_allocator](#module\_sqs\_supplier\_allocator) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-sqs.zip | n/a |
+| <a name="module_sqs_letter_updates"></a> [sqs\_letter\_updates](#module\_sqs\_letter\_updates) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.5/terraform-sqs.zip | n/a |
+| <a name="module_sqs_supplier_allocator"></a> [sqs\_supplier\_allocator](#module\_sqs\_supplier\_allocator) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.5/terraform-sqs.zip | n/a |
 | <a name="module_supplier_allocator"></a> [supplier\_allocator](#module\_supplier\_allocator) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_supplier_ssl"></a> [supplier\_ssl](#module\_supplier\_ssl) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-ssl.zip | n/a |
 | <a name="module_update_letter_queue"></a> [update\_letter\_queue](#module\_update\_letter\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |

infrastructure/terraform/components/api/ddb_table_letter_queue.tf

@@ -3,16 +3,16 @@ resource "aws_dynamodb_table" "letter_queue" {
   billing_mode = "PAY_PER_REQUEST"
 
   hash_key  = "supplierId"
-  range_key = "queueTimestamp"
+  range_key = "letterId"
 
   ttl {
     attribute_name = "ttl"
     enabled        = true
   }
 
   local_secondary_index {
-    name            = "letterId-index"
-    range_key       = "letterId"
+    name            = "queueSortOrder-index"
+    range_key       = "queueTimestamp"
     projection_type = "ALL"
   }
 

infrastructure/terraform/components/api/module_lambda_update_letter_queue.tf

@@ -47,6 +47,7 @@ data "aws_iam_policy_document" "update_letter_queue_lambda" {
 
     actions = [
       "dynamodb:PutItem",
+      "dynamodb:DeleteItem",
     ]
 
     resources = [

internal/datastore/src/__test__/db.ts

@@ -132,7 +132,7 @@ const createLetterQueueTableCommand = new CreateTableCommand({
       IndexName: "timestamp-index",
       KeySchema: [
         { AttributeName: "supplierId", KeyType: "HASH" }, // Partition key for LSI
-        { AttributeName: "queueTimestamp", KeyType: "RANGE" }, // Sort key for LSI
+        { AttributeName: "queueSortOrder-index", KeyType: "RANGE" }, // Sort key for LSI
       ],
       Projection: {
         ProjectionType: "ALL",

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

@@ -1,3 +1,4 @@
+import { GetCommand } from "@aws-sdk/lib-dynamodb";
 import { Logger } from "pino";
 import {
   DBContext,
@@ -7,8 +8,9 @@ import {
 } from "./db";
 import LetterQueueRepository from "../letter-queue-repository";
 import { InsertPendingLetter } from "../types";
-import { LetterAlreadyExistsError } from "../errors";
+import { LetterAlreadyExistsError } from "../letter-already-exists-error";
 import { createTestLogger } from "./logs";
+import { LetterDoesNotExistError } from "../letter-does-not-exist-error";
 
 function createLetter(letterId = "letter1"): InsertPendingLetter {
   return {
@@ -51,32 +53,17 @@ describe("LetterQueueRepository", () => {
     await db.container.stop();
   });
 
-  function assertTtl(ttl: number, before: number, after: number) {
-    const expectedLower = Math.floor(
-      before / 1000 + 60 * 60 * db.config.letterQueueTtlHours,
-    );
-    const expectedUpper = Math.floor(
-      after / 1000 + 60 * 60 * db.config.lettersTtlHours,
-    );
-    expect(ttl).toBeGreaterThanOrEqual(expectedLower);
-    expect(ttl).toBeLessThanOrEqual(expectedUpper);
-  }
-
   describe("putLetter", () => {
     it("adds a letter to the database", async () => {
-      const before = Date.now();
+      jest.useFakeTimers().setSystemTime(new Date("2026-03-04T13:15:45.000Z"));
 
       const pendingLetter =
         await letterQueueRepository.putLetter(createLetter());
 
-      const after = Date.now();
-
-      const timestampInMillis = new Date(
-        pendingLetter.queueTimestamp,
-      ).valueOf();
-      expect(timestampInMillis).toBeGreaterThanOrEqual(before);
-      expect(timestampInMillis).toBeLessThanOrEqual(after);
-      assertTtl(pendingLetter.ttl, before, after);
+      expect(pendingLetter.queueTimestamp).toBe("2026-03-04T13:15:45.000Z");
+      expect(pendingLetter.visibilityTimeout).toBe("2026-03-04T13:15:45.000Z");
+      expect(pendingLetter.ttl).toBe(1_772_633_745);
+      expect(await letterExists(db, "supplier1", "letter1")).toBe(true);
     });
 
     it("throws LetterAlreadyExistsError when creating a letter which already exists", async () => {
@@ -101,4 +88,48 @@ describe("LetterQueueRepository", () => {
       ).rejects.toThrow("Cannot do operations on a non-existent table");
     });
   });
+
+  describe("deleteLetter", () => {
+    it("deletes a letter from the database", async () => {
+      await letterQueueRepository.putLetter(createLetter());
+
+      await letterQueueRepository.deleteLetter("supplier1", "letter1");
+
+      expect(await letterExists(db, "supplier1", "letter1")).toBe(false);
+    });
+
+    it("throws an error when the letter does not exist", async () => {
+      await expect(
+        letterQueueRepository.deleteLetter("supplier1", "letter1"),
+      ).rejects.toThrow(LetterDoesNotExistError);
+    });
+
+    it("rethrows errors from DynamoDB when deleting a letter", async () => {
+      const misconfiguredRepository = new LetterQueueRepository(
+        db.docClient,
+        logger,
+        {
+          ...db.config,
+          letterQueueTableName: "nonexistent-table",
+        },
+      );
+      await expect(
+        misconfiguredRepository.deleteLetter("supplier1", "letter1"),
+      ).rejects.toThrow("Cannot do operations on a non-existent table");
+    });
+  });
 });
+
+async function letterExists(
+  db: DBContext,
+  supplierId: string,
+  letterId: string,
+): Promise<boolean> {
+  const result = await db.docClient.send(
+    new GetCommand({
+      TableName: db.config.letterQueueTableName,
+      Key: { supplierId, letterId },
+    }),
+  );
+  return result.Item !== undefined;
+}

internal/datastore/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./types";
-export * from "./errors";
+export * from "./letter-already-exists-error";
+export * from "./letter-does-not-exist-error";
 export * from "./mi-repository";
 export * from "./letter-repository";
 export * from "./supplier-repository";

internal/datastore/src/letter-does-not-exist-error.ts

@@ -0,0 +1,15 @@
+/**
+ * Error thrown when attempting to delete a letter that does not exist in the database.
+ */
+// eslint-disable-next-line import-x/prefer-default-export
+export class LetterDoesNotExistError extends Error {
+  constructor(
+    public readonly supplierId: string,
+    public readonly letterId: string,
+  ) {
+    super(
+      `Letter does not exist: supplierId=${supplierId}, letterId=${letterId}`,
+    );
+    this.name = "LetterDoesNotExistError";
+  }
+}

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

@@ -1,11 +1,16 @@
-import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
+import {
+  DeleteCommand,
+  DynamoDBDocumentClient,
+  PutCommand,
+} from "@aws-sdk/lib-dynamodb";
 import { Logger } from "pino";
 import {
   InsertPendingLetter,
   PendingLetter,
   PendingLetterSchema,
 } from "./types";
-import { LetterAlreadyExistsError } from "./errors";
+import { LetterAlreadyExistsError } from "./letter-already-exists-error";
+import { LetterDoesNotExistError } from "./letter-does-not-exist-error";
 
 type LetterQueueRepositoryConfig = {
   letterQueueTableName: string;
@@ -22,10 +27,13 @@ export default class LetterQueueRepository {
   async putLetter(
     insertPendingLetter: InsertPendingLetter,
   ): Promise<PendingLetter> {
+    // needs to be an ISO timestamp as Db sorts alphabetically
+    const now = new Date().toISOString();
+
     const pendingLetter: PendingLetter = {
       ...insertPendingLetter,
-      // needs to be an ISO timestamp as Db sorts alphabetically
-      queueTimestamp: new Date().toISOString(),
+      queueTimestamp: now,
+      visibilityTimeout: now,
       ttl: Math.floor(
         Date.now() / 1000 + 60 * 60 * this.config.letterQueueTtlHours,
       ),
@@ -52,4 +60,24 @@ export default class LetterQueueRepository {
     }
     return PendingLetterSchema.parse(pendingLetter);
   }
+
+  async deleteLetter(supplierId: string, letterId: string): Promise<void> {
+    try {
+      await this.ddbClient.send(
+        new DeleteCommand({
+          TableName: this.config.letterQueueTableName,
+          Key: { supplierId, letterId },
+          ConditionExpression: "attribute_exists(letterId)",
+        }),
+      );
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        error.name === "ConditionalCheckFailedException"
+      ) {
+        throw new LetterDoesNotExistError(supplierId, letterId);
+      }
+      throw error;
+    }
+  }
 }

internal/datastore/src/types.ts

@@ -80,14 +80,18 @@ export const PendingLetterSchema = z.object({
   supplierId: idRef(SupplierSchema, "id"),
   letterId: idRef(LetterSchema, "id"),
   queueTimestamp: z.string().describe("Secondary index SK"),
+  visibilityTimeout: z.string(),
   specificationId: z.string(),
   groupId: z.string(),
   ttl: z.int(),
 });
 
 export type PendingLetter = z.infer<typeof PendingLetterSchema>;
 
-export type InsertPendingLetter = Omit<PendingLetter, "ttl" | "queueTimestamp">;
+export type InsertPendingLetter = Omit<
+  PendingLetter,
+  "ttl" | "queueTimestamp" | "visibilityTimeout"
+>;
 
 export const MISchemaBase = z.object({
   id: z.string(),