CCM-13787: create supplier mock for testing

.env.template

@@ -1,4 +1,5 @@
 # Your github Personal Access Token (PAT)
+PR_NUMBER=prxx # remove if needs to run against main
 GITHUB_TOKEN=
 
 # Apigee proxy name to be used for test execution

.github/workflows/stage-3-build.yaml

@@ -189,7 +189,6 @@ jobs:
             --terraformAction "apply" \
             --overrideProjectName "nhs" \
             --overrideRoleName "nhs-main-acct-supplier-api-github-deploy"
-
   populate-config:
     name: "Populate Supplier Config"
     runs-on: ubuntu-latest

infrastructure/terraform/components/api/README.md

@@ -18,6 +18,7 @@ No requirements.
 | <a name="input_csoc_destination_account"></a> [csoc\_destination\_account](#input\_csoc\_destination\_account) | value of the CSOC destination account, if applicable. If null, CSOC destination account will not be added as a resource in the logging policy | `string` | `"000000000000"` | no |
 | <a name="input_csoc_log_forwarding"></a> [csoc\_log\_forwarding](#input\_csoc\_log\_forwarding) | Enable forwarding of API Gateway logs to CSOC | `bool` | `true` | no |
 | <a name="input_default_tags"></a> [default\_tags](#input\_default\_tags) | A map of default tags to apply to all taggable resources within the component | `map(string)` | `{}` | no |
+| <a name="input_deploy_supplier_mock_scheduler"></a> [deploy\_supplier\_mock\_scheduler](#input\_deploy\_supplier\_mock\_scheduler) | Deploy EventBridge Scheduler trigger for supplier mock lambda | `bool` | `true` | no |
 | <a name="input_disable_gateway_execute_endpoint"></a> [disable\_gateway\_execute\_endpoint](#input\_disable\_gateway\_execute\_endpoint) | Disable the execution endpoint for the API Gateway | `bool` | `true` | no |
 | <a name="input_download_url_ttl_seconds"></a> [download\_url\_ttl\_seconds](#input\_download\_url\_ttl\_seconds) | TTL in seconds for generated download URLs | `number` | `60` | no |
 | <a name="input_enable_alarms"></a> [enable\_alarms](#input\_enable\_alarms) | Enable CloudWatch alarms for this deployed environment | `bool` | `true` | no |
@@ -26,6 +27,7 @@ No requirements.
 | <a name="input_enable_event_anomaly_detection"></a> [enable\_event\_anomaly\_detection](#input\_enable\_event\_anomaly\_detection) | Enable CloudWatch anomaly detection alarm for SNS message  Detects abnormal drops or spikes in event publishing volume. | `bool` | `true` | no |
 | <a name="input_enable_event_cache"></a> [enable\_event\_cache](#input\_enable\_event\_cache) | Enable caching of events to an S3 bucket | `bool` | `true` | no |
 | <a name="input_enable_sns_delivery_logging"></a> [enable\_sns\_delivery\_logging](#input\_enable\_sns\_delivery\_logging) | Enable SNS Delivery Failure Notifications | `bool` | `true` | no |
+| <a name="input_enable_supplier_mock_scheduler"></a> [enable\_supplier\_mock\_scheduler](#input\_enable\_supplier\_mock\_scheduler) | Enable EventBridge Scheduler trigger for supplier mock lambda | `bool` | `false` | no |
 | <a name="input_environment"></a> [environment](#input\_environment) | The name of the tfscaffold environment | `string` | n/a | yes |
 | <a name="input_event_anomaly_band_width"></a> [event\_anomaly\_band\_width](#input\_event\_anomaly\_band\_width) | The width of the anomaly detection band. Higher values (e.g. 4-6) reduce sensitivity and noise, lower values (e.g. 2-3) increase sensitivity. Recommended: 2-4. | `number` | `4` | no |
 | <a name="input_event_anomaly_evaluation_periods"></a> [event\_anomaly\_evaluation\_periods](#input\_event\_anomaly\_evaluation\_periods) | Number of evaluation periods for the anomaly alarm. Each period is defined by event\_anomaly\_period. | `number` | `3` | no |
@@ -51,6 +53,7 @@ No requirements.
 | <a name="input_region"></a> [region](#input\_region) | The AWS Region | `string` | n/a | yes |
 | <a name="input_shared_infra_account_id"></a> [shared\_infra\_account\_id](#input\_shared\_infra\_account\_id) | The AWS Account ID of the shared infrastructure account | `string` | `"000000000000"` | no |
 | <a name="input_sns_success_logging_sample_percent"></a> [sns\_success\_logging\_sample\_percent](#input\_sns\_success\_logging\_sample\_percent) | Enable SNS Delivery Successful Sample Percentage | `number` | `0` | no |
+| <a name="input_supplier_mock_schedule_expression"></a> [supplier\_mock\_schedule\_expression](#input\_supplier\_mock\_schedule\_expression) | Schedule expression for supplier mock scheduler | `string` | `"rate(1 minute)"` | no |
 ## Modules
 
 | Name | Source | Version |
@@ -85,6 +88,7 @@ No requirements.
 | <a name="module_sqs_supplier_config"></a> [sqs\_supplier\_config](#module\_sqs\_supplier\_config) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.1.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/4.0.2/terraform-lambda.zip | n/a |
 | <a name="module_supplier_config_ingress"></a> [supplier\_config\_ingress](#module\_supplier\_config\_ingress) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
+| <a name="module_supplier_mock"></a> [supplier\_mock](#module\_supplier\_mock) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/4.0.5/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/4.0.2/terraform-lambda.zip | n/a |
 | <a name="module_upsert_letter"></a> [upsert\_letter](#module\_upsert\_letter) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/4.0.2/terraform-lambda.zip | n/a |

infrastructure/terraform/components/api/iam_policy_supplier_mock_scheduler_invoke_policy.tf

@@ -0,0 +1,5 @@
+resource "aws_iam_policy" "supplier_mock_scheduler_invoke_policy" {
+  count  = var.deploy_supplier_mock_scheduler ? 1 : 0
+  name   = "${local.csi}-supplier-mock-scheduler-invoke"
+  policy = data.aws_iam_policy_document.supplier_mock_scheduler_invoke_policy[0].json
+}

infrastructure/terraform/components/api/iam_role_policy_attachment_supplier_mock_scheduler_invoke_policy.tf

@@ -0,0 +1,5 @@
+resource "aws_iam_role_policy_attachment" "supplier_mock_scheduler_invoke_policy" {
+  count      = var.deploy_supplier_mock_scheduler ? 1 : 0
+  role       = aws_iam_role.supplier_mock_scheduler[0].name
+  policy_arn = aws_iam_policy.supplier_mock_scheduler_invoke_policy[0].arn
+}

infrastructure/terraform/components/api/iam_role_supplier_mock_scheduler.tf

@@ -0,0 +1,6 @@
+resource "aws_iam_role" "supplier_mock_scheduler" {
+  name               = "${local.csi}-supplier-mock-scheduler"
+  description        = "Allows EventBridge Scheduler to invoke supplier mock lambda"
+  assume_role_policy = data.aws_iam_policy_document.supplier_mock_scheduler_trust_policy.json
+  count              = var.deploy_supplier_mock_scheduler ? 1 : 0
+}

infrastructure/terraform/components/api/module_lambda_supplier_mock.tf

@@ -0,0 +1,87 @@
+module "supplier_mock" {
+  source = "https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/4.0.5/terraform-lambda.zip"
+  count  = var.deploy_supplier_mock_scheduler ? 1 : 0
+
+  function_name = "supplier_mock"
+  description   = "Mock the behaviour of a supplier"
+
+  aws_account_id = var.aws_account_id
+  component      = var.component
+  environment    = var.environment
+  project        = var.project
+  region         = var.region
+  group          = var.group
+
+  log_retention_in_days = var.log_retention_in_days
+  kms_key_arn           = module.kms.key_arn
+
+  iam_policy_document = {
+    body = data.aws_iam_policy_document.supplier_mock_lambda.json
+  }
+
+  function_s3_bucket      = local.acct.s3_buckets["lambda_function_artefacts"]["id"]
+  function_code_base_path = local.aws_lambda_functions_dir_path
+  function_code_dir       = "supplier-mock/dist"
+  function_include_common = true
+  handler_function_name   = "supplierMockHandler"
+  runtime                 = "nodejs22.x"
+  memory                  = 512
+  timeout                 = 29
+  log_level               = var.log_level
+
+  force_lambda_code_deploy = var.force_lambda_code_deploy
+  enable_lambda_insights   = false
+
+  log_destination_arn       = local.destination_arn
+  log_subscription_role_arn = local.acct.log_subscription_role_arn
+
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    ENVIRONMENT                     = var.environment
+    GET_LETTERS_FUNCTION_NAME       = module.get_letters.function_name
+    PATCH_LETTER_FUNCTION_NAME      = module.patch_letter.function_name
+    SUPPLIER_MOCK_CONFIG_PARAM_NAME = aws_ssm_parameter.supplier_mock_config[0].name
+  })
+}
+
+data "aws_iam_policy_document" "supplier_mock_lambda" {
+  statement {
+    sid    = "KMSPermissions"
+    effect = "Allow"
+
+    actions = [
+      "kms:Decrypt",
+      "kms:GenerateDataKey",
+    ]
+
+    resources = [
+      module.kms.key_arn, ## Requires shared kms module
+    ]
+  }
+
+  statement {
+    sid    = "AllowInvokeLambda"
+    effect = "Allow"
+
+    actions = [
+      "lambda:InvokeFunction",
+    ]
+
+    resources = [
+      module.get_letters.function_arn,
+      module.patch_letter.function_arn
+    ]
+  }
+
+  statement {
+    sid    = "AllowReadSupplierMockConfigParameter"
+    effect = "Allow"
+
+    actions = [
+      "ssm:GetParameter",
+    ]
+
+    resources = [
+      aws_ssm_parameter.supplier_mock_config[0].arn
+    ]
+  }
+}

infrastructure/terraform/components/api/scheduler_schedule_supplier_mock.tf

@@ -0,0 +1,20 @@
+resource "aws_scheduler_schedule" "supplier_mock" {
+  count       = var.deploy_supplier_mock_scheduler ? 1 : 0
+  name        = "${local.csi}-supplier-mock"
+  description = "Scheduled trigger for supplier mock lambda"
+  state       = var.enable_supplier_mock_scheduler ? "ENABLED" : "DISABLED"
+
+  flexible_time_window {
+    mode = "OFF"
+  }
+
+  schedule_expression = var.supplier_mock_schedule_expression
+
+  target {
+    arn      = module.supplier_mock[0].function_arn
+    role_arn = aws_iam_role.supplier_mock_scheduler[0].arn
+    input = jsonencode({
+      source = "eventbridge-scheduler"
+    })
+  }
+}

infrastructure/terraform/components/api/scheduler_supplier_mock.tf

@@ -0,0 +1,36 @@
+data "aws_iam_policy_document" "supplier_mock_scheduler_trust_policy" {
+  statement {
+    sid    = "AllowSchedulerAssumeRole"
+    effect = "Allow"
+
+    actions = [
+      "sts:AssumeRole",
+    ]
+
+    principals {
+      type = "Service"
+
+      identifiers = [
+        "scheduler.amazonaws.com",
+      ]
+    }
+  }
+}
+
+
+data "aws_iam_policy_document" "supplier_mock_scheduler_invoke_policy" {
+  count = var.deploy_supplier_mock_scheduler ? 1 : 0
+
+  statement {
+    sid    = "AllowInvokeSupplierMockLambda"
+    effect = "Allow"
+
+    actions = [
+      "lambda:InvokeFunction",
+    ]
+
+    resources = [
+      module.supplier_mock[0].function_arn,
+    ]
+  }
+}

infrastructure/terraform/components/api/ssm_parameter_supplier_mock_config.tf

@@ -0,0 +1,17 @@
+resource "aws_ssm_parameter" "supplier_mock_config" {
+  count       = var.deploy_supplier_mock_scheduler ? 1 : 0
+  name        = format("/nhs/supapi/%s/supplier-mock/config", var.environment)
+  description = "JSON object containing supplier mock config for supplierID, getLetters limit, specificationId mapping, etc."
+  type        = "String"
+  value = jsonencode({
+    limit       = "100"
+    supplier_id = "TestSupplier1"
+    specification_id_mapping = {
+      "test-specification-id-1" = "ACCEPTED"
+    }
+  })
+
+  lifecycle {
+    ignore_changes = [value]
+  }
+}

infrastructure/terraform/components/api/variables.tf

@@ -226,6 +226,24 @@ variable "enable_alarms" {
   description = "Enable CloudWatch alarms for this deployed environment"
   default     = true
 }
+# Set value back to false before merging to main.
+variable "deploy_supplier_mock_scheduler" {
+  type        = bool
+  description = "Deploy EventBridge Scheduler trigger for supplier mock lambda"
+  default     = true
+}
+
+variable "enable_supplier_mock_scheduler" {
+  type        = bool
+  description = "Enable EventBridge Scheduler trigger for supplier mock lambda"
+  default     = false
+}
+
+variable "supplier_mock_schedule_expression" {
+  type        = string
+  description = "Schedule expression for supplier mock scheduler"
+  default     = "rate(1 minute)"
+}
 
 variable "enable_event_anomaly_detection" {
   type        = bool

lambdas/supplier-mock/.gitignore

@@ -0,0 +1,5 @@
+coverage
+node_modules
+dist
+.reports
+.aws-sam

lambdas/supplier-mock/README.md

@@ -0,0 +1,31 @@
+<!-- vale off -->
+
+# Supplier Mock
+
+## What is does
+
+The supplier-mock lambda simulates the supplier's system behaviour so that downstream services can simulate supplier interaction without relying on a live supplier system.
+The mock simulates the journey of a letter with the Supplier. It utilises the api-handler and retrieves pending letters by calling the `getLetters` lambda directly and then provides status updates for each letter by calling the `patchLetter` lambda.
+Each time the mock is called it will call `getLetters` once with for the **supplierId** `TestSupplier1` and with a **limit** of `100` letters. These default values can be configured in the AWS Parameter Store as explained in [How to modify parameter store variables](#how-to-modify-default-variable-values-in-parameter-store) . It then loops through each retrieved letter and updates its status by calling `patchLetter` and using the **specification_id_mapping** map to determine its status. If the map doesn't return a value it will default to `ACCEPTED` status.
+
+## How to deploy the supapi-supplier-mock schedule
+
+The AWS EventBridge Schedule that calls the supplier-mock lambda is created by the terraform file **/infrastructure/terraform/components/api/scheduler_supplier_mock.tf**, however, by default it's not deployed as it's not needed by every dynamic environment.
+If you need to deploy the schedule in your environment you need to set the variable `deploy_supplier_mock_scheduler = true` in the file **/infrastructure/terraform/components/api/variables.tf**.
+
+## How to run the lambda
+
+The supplier-mock lambda can be activated by manually enabling the `{environment}-supapi-supplier-mock` AWS EventBridge schedule from the AWS console. The schedule is configured to call the lambda once per minute. You need to manually disable the schedule from the AWS console to stop calling the supplier-mock lambda.
+**NOTE: The schedule is not deployed by default**
+
+## How to modify default variable values in parameter store
+
+As mentioned above the `limit`, `supplierId` and `specification_id_mapping` default values are stored in the AWS Parameter Store and can be modified if needed by accessing the Parameter Store from the AWS Console. These store parameters are created in the **/infrastructure/terraform/components/api/ssm_parameter.tf** file, but only if the `deploy_supplier_mock_scheduler` variable is set to `true`. We deploy a JSON parameter in the location `/nhs/supapi/{environment}/supplier-mock/config` with the following key/value pairs:
+
+| key                      | type   | default value                           |
+| ------------------------ | ------ | --------------------------------------- |
+| limit                    | string | 100                                     |
+| supplier_id              | string | TestSupplier1                           |
+| specification_id_mapping | map    | {"test-specification-id-1 = "ACCEPTED"} |
+
+<!-- vale on -->

lambdas/supplier-mock/jest.config.ts

@@ -0,0 +1,69 @@
+export const baseJestConfig = {
+  preset: "ts-jest",
+  extensionsToTreatAsEsm: [".ts"],
+  transform: {
+    "^.+\\.ts$": [
+      "ts-jest",
+      {
+        useESM: true,
+      },
+    ],
+  },
+  transformIgnorePatterns: [
+    "node_modules/(?!(@nhsdigital/nhs-notify-event-schemas-supplier-config)/)",
+  ],
+
+  // Automatically clear mock calls, instances, contexts and results before every test
+  clearMocks: true,
+
+  // Indicates whether the coverage information should be collected while executing the test
+  collectCoverage: true,
+
+  // The directory where Jest should output its coverage files
+  coverageDirectory: "./.reports/unit/coverage",
+
+  // Indicates which provider should be used to instrument code for coverage
+  coverageProvider: "babel",
+
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: -10,
+    },
+  },
+
+  coveragePathIgnorePatterns: ["/__tests__/"],
+  testPathIgnorePatterns: [".build"],
+  testMatch: ["**/?(*.)+(spec|test).[jt]s?(x)"],
+
+  // Use this configuration option to add custom reporters to Jest
+  reporters: [
+    "default",
+    [
+      "jest-html-reporter",
+      {
+        pageTitle: "Test Report",
+        outputPath: "./.reports/unit/test-report.html",
+        includeFailureMsg: true,
+      },
+    ],
+  ],
+
+  // The test environment that will be used for testing
+  testEnvironment: "jsdom",
+};
+
+const utilsJestConfig = {
+  ...baseJestConfig,
+
+  testEnvironment: "node",
+
+  coveragePathIgnorePatterns: [
+    ...(baseJestConfig.coveragePathIgnorePatterns ?? []),
+    "zod-validators.ts",
+  ],
+};
+
+export default utilsJestConfig;

lambdas/supplier-mock/package.json

@@ -0,0 +1,22 @@
+{
+  "dependencies": {
+    "@aws-sdk/client-api-gateway": "^3.1030.0",
+    "@aws-sdk/client-lambda": "^3.1030.0",
+    "@aws-sdk/client-ssm": "^3.1054.0",
+    "@internal/helpers": "^0.1.0",
+    "aws-embedded-metrics": "^4.2.1",
+    "aws-lambda": "^1.0.7",
+    "pino": "^10.3.1",
+    "zod": "^4.3.6"
+  },
+  "name": "nhs-notify-supplier-api-supplier-mock",
+  "private": true,
+  "scripts": {
+    "lambda-build": "rm -rf dist && npx esbuild --bundle --minify --sourcemap --target=es2020 --platform=node --loader:.node=file --entry-names=[name] --outdir=dist src/index.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test:unit": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "version": "0.0.1"
+}