CCM-22692: Send letters to DLQ if supplier allocation fails

[stevebux]

Description

• Introduces new error handling for supplier config issues, placing the message directly on the DLQ, instead of writing a REJECTED record to the database
• Terraform IAM changes to give access to DLQ from lambda
• Adds a SQS test helper class and fixes component tests to assert new behaviour

Context

When letters fail to be delivered due to missing or incorrect config, we have no way to replay them once the config is updated, meaning that we have to go back to the client and ask them to resend them. If the messages are on a DLQ, we can replay them ourselves without needing assistance from the client.

Type of changes

• Refactoring (non-breaking change)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would change existing functionality)
• Bug fix (non-breaking change which fixes an issue)

Checklist

• I am familiar with the contributing guidelines
• I have followed the code style of the project
• I have added tests to cover my changes
• I have updated the documentation accordingly
• This PR is a result of pair or mob programming

DT3-Specific Checklist

• If I have added a new resource (SQS, Lambda, Gateway, DDB table, etc), I have created the appropriate alarms

---

Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others privacy, we kindly ask you to NOT including PII (Personal Identifiable Information) / PID (Personal Identifiable Data) or any other sensitive data in this PR (Pull Request) and the codebase changes. We will remove any PR that do contain any sensitive information. We really appreciate your cooperation in this matter.

• I confirm that neither PII/PID nor sensitive data are included in this PR and the codebase changes.

[Copilot]

Pull request overview

Routes terminal supplier-configuration allocation failures directly to the allocator DLQ instead of creating rejected letters.

Changes:

• Adds typed configuration errors and DLQ handling.
• Updates IAM, environment configuration, tests, and documentation.
• Adds component-test SQS polling support.

Validation: AI-assisted static review; tests were not executed.

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/package.json	Adds SQS and allocator test dependencies.
tests/helpers/aws-queue-helper.ts	Adds DLQ polling helper.
tests/component-tests/allocation-tests/supplier-allocation.spec.ts	Verifies unknown variants reach the DLQ.
tests/component-tests/allocation-tests/letter-allocation-rejected.spec.ts	Updates rejected-allocation scenarios for DLQ behavior.
tests/component-tests/allocation-tests/allocation-target-percentage.spec.ts	Verifies unavailable suppliers reach the DLQ.
package-lock.json	Locks new test dependencies.
lambdas/supplier-allocator/src/services/supplier-config.ts	Classifies terminal configuration validation failures.
lambdas/supplier-allocator/src/services/__tests__/supplier-config.test.ts	Tests typed validation errors.
lambdas/supplier-allocator/src/handler/allocation-config.ts	Uses typed errors for allocation failures.
lambdas/supplier-allocator/src/handler/allocate-handler.ts	Sends terminal failures directly to the DLQ.
lambdas/supplier-allocator/src/handler/__tests__/allocation-config.test.ts	Tests allocation error types.
lambdas/supplier-allocator/src/handler/__tests__/allocate-handler.test.ts	Tests DLQ and retry behavior.
lambdas/supplier-allocator/src/errors/supplier-config-validation-error.ts	Defines validation error type.
lambdas/supplier-allocator/README.md	Documents revised failure handling.
lambdas/supplier-allocator/jest.config.ts	Enables transformation of supplier-config schemas.
internal/datastore/src/supplier-config-repository.ts	Classifies missing configuration records.
internal/datastore/src/index.ts	Exports the missing-config error.
internal/datastore/src/errors/missing-supplier-config-error.ts	Defines missing-config error type.
infrastructure/terraform/components/api/module_lambda_supplier_allocator.tf	Configures DLQ URL and send permissions.

Suppressed comments (3)

lambdas/supplier-allocator/README.md:22

• This integration-point description omits MissingSupplierConfigError, although the handler directly publishes that error type to the DLQ too. Include both terminal configuration errors.

- **SQS**: Input from EventSub, output to the upsert-letter queue (`UPSERT_LETTERS_QUEUE`), and direct publish to the allocator DLQ (`SUPPLIER_ALLOCATOR_DLQ_URL`) for `SupplierConfigValidationError`.

lambdas/supplier-allocator/README.md:31

• These retry semantics exclude only SupplierConfigValidationError, but the implementation also acknowledges MissingSupplierConfigError after a direct DLQ send. Update this summary so operators do not expect missing-config records to follow normal retries.

- **`SupplierConfigValidationError` is treated as terminal for retries.** The handler sends the original message directly to the allocator DLQ and acknowledges the source record.
- **All other failures retain normal retry semantics.** Non-`SupplierConfigValidationError` records are returned in `batchItemFailures` and retried according to queue configuration.

tests/helpers/aws-queue-helper.ts:32

• With VisibilityTimeout: 0, every unmatched message is immediately eligible to be returned again. Because allocation tests run fully parallel with up to ten workers (tests/config/playwright.base.config.ts:12,21), pollers can repeatedly receive the same unrelated DLQ record and time out without progressing through the queue. Temporarily hide a batch of unmatched messages so polling advances.

        VisibilityTimeout: 0,
        WaitTimeSeconds: 5,

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud