New: [AEA-0000] - Add logic to handle the channel status callback updates (#2074)

## Summary

- ✨ New Feature

### Details

The Notifications callback lambda needs to be able to handle data from
both of these schemas:


https://digital.nhs.uk/developer/api-catalogue/nhs-notify#post-/%3Cclient-provided-message-status-URI%3E

https://digital.nhs.uk/developer/api-catalogue/nhs-notify#post-/%3Cclient-provided-channel-status-URI%3E

The message status is already implemented - this PR adds the channel
status update logic

Author: wildjames

packages/nhsNotifyUpdateCallback/src/helpers.ts

@@ -9,7 +9,7 @@ import {createHmac, timingSafeEqual} from "crypto"
 
 import {LastNotificationStateType} from "@PrescriptionStatusUpdate_common/commonTypes"
 
-import {MessageStatusResponse} from "./types"
+import {CallbackResponse, CallbackType} from "./types"
 
 const APP_NAME_SECRET = process.env.APP_NAME_SECRET
 const API_KEY_SECRET = process.env.API_KEY_SECRET
@@ -105,14 +105,15 @@ export async function checkSignature(logger: Logger, event: APIGatewayProxyEvent
 
   // Must be same length for timingSafeEqual
   if (givenSigBuf.length !== expectedSigBuf.length ||
-      !timingSafeEqual(expectedSigBuf, givenSigBuf)) {
+    !timingSafeEqual(expectedSigBuf, givenSigBuf)) {
     logger.error("Incorrect signature given", {
       expectedSignature: expectedSigBuf.toString("hex"),
       givenSignature: signature
     })
     return response(403, {message: "Incorrect signature"})
   }
 
+  logger.info("Signature OK!")
   return undefined
 }
 
@@ -124,11 +125,29 @@ export async function checkSignature(logger: Logger, event: APIGatewayProxyEvent
  */
 export async function updateNotificationsTable(
   logger: Logger,
-  bodyData: MessageStatusResponse
+  bodyData: CallbackResponse
 ): Promise<void> {
   // For each callback resource, return a promise
   const callbackPromises = bodyData.data.map(async (resource) => {
-    const {messageId, messageStatus, timestamp} = resource.attributes
+    let messageId: string
+    let messageStatus: string
+    let timestamp: string
+
+    if (resource.type === CallbackType.message) {
+      messageId = resource.attributes.messageId
+      messageStatus = resource.attributes.messageStatus
+      timestamp = resource.attributes.timestamp
+    } else if (resource.type === CallbackType.channel) {
+      messageId = resource.attributes.messageId
+      messageStatus = resource.attributes.channelStatus
+      timestamp = resource.attributes.timestamp
+    } else {
+      logger.error("Unknown data structure - cannot store to notifications table.", {resource})
+      // Set to junk data, so that when we try and update the table we will fail. This is fine, and handled later.
+      messageId = "unknown"
+      messageStatus = "unknown"
+      timestamp = "unknown"
+    }
 
     // Query matching records
     let queryResult

packages/nhsNotifyUpdateCallback/src/lambdaHandler.ts

@@ -9,7 +9,7 @@ import httpHeaderNormalizer from "@middy/http-header-normalizer"
 
 import errorHandler from "@nhs/fhir-middy-error-handler"
 
-import {MessageStatusResponse} from "./types"
+import {CallbackType, CallbackResponse} from "./types"
 import {checkSignature, response, updateNotificationsTable} from "./helpers"
 
 export const logger = new Logger({serviceName: "nhsNotifyUpdateCallback"})
@@ -20,36 +20,53 @@ const lambdaHandler = async (event: APIGatewayProxyEvent): Promise<APIGatewayPro
     "apigw-request-id": event.headers["apigw-request-id"],
     "x-request-id": event.headers["x-request-id"]
   })
-  logger.info("Lambda called with this event", {event})
 
   // Require a request ID
   if (!event.headers["x-request-id"]) return response(400, {message: "No x-request-id given"})
 
   // Check the request signature
   const isErr = await checkSignature(logger, event)
   if (isErr) return isErr
-  logger.info("Signature OK!")
 
   // Parse out the request body
   if (!event.body) return response(400, {message: "No request body given"})
-  let payload: MessageStatusResponse
+  let payload: CallbackResponse
   try {
     payload = JSON.parse(event.body)
   } catch (error) {
     logger.error("Failed to parse payload", {error, payload: event.body})
     return response(400, {message: "Request body failed to parse"})
   }
 
+  let receivedUnknownCallbackType = false
   payload.data.forEach(m => {
-    logger.info(
-      "Message state updated",
-      {
+    let logPayload = {}
+    if (m.type === CallbackType.message) {
+      logPayload = {
+        callbackType: m.type,
         messageStatus: m.attributes.messageStatus,
         messageReference: m.attributes.messageReference,
         messageId: m.attributes.messageId,
         receivedTimestamp: m.attributes.timestamp
       }
-    )
+
+    } else if (m.type === CallbackType.channel) {
+      logPayload = {
+        callbackType: m.type,
+        messageStatus: m.attributes.channelStatus,
+        supplierStatus: m.attributes.supplierStatus ?? "not given",
+        retryCount: m.attributes.retryCount,
+        messageReference: m.attributes.messageReference,
+        messageId: m.attributes.messageId,
+        receivedTimestamp: m.attributes.timestamp
+      }
+    } else {
+      logger.warn("Unknown callback data structure.", {data: m})
+      receivedUnknownCallbackType = true
+    }
+
+    // If we have populated the logPayload object, then log it.
+    if (Object.keys(logPayload).length > 0) logger.info("Message state updated", logPayload)
   })
 
   try {
@@ -59,11 +76,23 @@ const lambdaHandler = async (event: APIGatewayProxyEvent): Promise<APIGatewayPro
     return response(500, {message: "Failed to update the notification state table"})
   }
 
-  // All's well that ends well
-  return {
-    statusCode: 202,
-    body: "OK"
+  if (receivedUnknownCallbackType) {
+    logger.info(
+      "Detected some unknown callback types. Returning 400 despite possible partial success."
+    )
+    return response(
+      400,
+      {
+        message: (
+          "Received an unknown callback data type. expected data[].type"
+          + " to always be either ChannelStatus or MessageStatus"
+        )
+      }
+    )
   }
+
+  // All's well that ends well
+  return response(202)
 }
 
 export const handler = middy(lambdaHandler)

packages/nhsNotifyUpdateCallback/src/types.ts

@@ -1,79 +1,133 @@
-// Enums
-export type MessageStatus =
-  | "created"
-  | "pending_enrichment"
-  | "enriched"
-  | "sending"
-  | "delivered"
-  | "failed";
-
-export type ChannelType =
-  | "nhsapp"
-  | "email"
-  | "sms"
-  | "letter";
-
-export type ChannelStatus =
-  | "created"
-  | "sending"
-  | "delivered"
-  | "failed"
-  | "skipped";
-
-// Callback return schema
+// --- Literal sets ------------------------------------------------------------
+
+export enum CallbackType {
+  message = "MessageStatus",
+  channel = "ChannelStatus"
+}
+
+export const MessageStatuses = [
+  "created",
+  "pending_enrichment",
+  "enriched",
+  "sending",
+  "delivered",
+  "failed"
+] as const
+export type MessageStatus = typeof MessageStatuses[number];
+
+export const ChannelTypes = ["nhsapp", "email", "sms", "letter"] as const
+export type ChannelType = typeof ChannelTypes[number];
+
+export const ChannelStatuses = [
+  "created",
+  "sending",
+  "delivered",
+  "failed",
+  "skipped"
+] as const
+export type ChannelStatus = typeof ChannelStatuses[number];
+
+export const CascadeTypes = ["primary", "secondary"] as const
+export type CascadeType = typeof CascadeTypes[number];
+
+export const SupplierStatuses = [
+  "accepted",
+  "cancelled",
+  "delivered",
+  "notification_attempted",
+  "notified",
+  "pending_virus_check",
+  "permanent_failure",
+  "read",
+  "received",
+  "rejected",
+  "technical_failure",
+  "temporary_failure",
+  "unnotified",
+  "unknown",
+  "validation_failed"
+] as const
+export type SupplierStatus = typeof SupplierStatuses[number];
+
+// --- Core models -------------------------------------------------------------
+
 export interface Channel {
-  /** The communication type of this channel */
-  type: ChannelType;
-  /** Current status of this channel */
-  channelStatus: ChannelStatus;
+  readonly type: ChannelType;
+  readonly channelStatus: ChannelStatus;
 }
 
 export interface RoutingPlan {
-  /** Identifier for the routing plan */
-  id: string;
-  /** Name of the routing plan */
-  name: string;
-  /** Specific version of the routing plan */
-  version: string;
-  /** Creation date of the routing plan */
-  createdDate: string;
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly createdDate: string;
 }
 
-export interface MessageStatusAttributes {
-  /** Unique identifier for the message */
-  messageId: string;
-  /** Original reference supplied for the message */
-  messageReference: string;
+// Shared attributes across callbacks
+interface BaseAttributes {
+  /** Notify ID for the message (KSUID; 27-char alphanumeric) */
+  readonly messageId: string;
+  /** Original reference supplied by us for the message */
+  readonly messageReference: string;
+  /** Timestamp of the callback event */
+  readonly timestamp: string;
+}
+
+export interface MessageStatusAttributes extends BaseAttributes {
   /** Aggregate status across all channels */
-  messageStatus: MessageStatus;
-  /** Extra information about the message status, if any */
-  messageStatusDescription?: string;
+  readonly messageStatus: MessageStatus;
+  readonly messageStatusDescription?: string;
   /** List of channels attempted for delivery */
-  channels: Array<Channel>;
-  /** Timestamp of the callback event */
-  timestamp: string;
-  /** Routing plan details */
-  routingPlan: RoutingPlan;
+  readonly channels: ReadonlyArray<Channel>;
+  readonly routingPlan: RoutingPlan;
 }
 
-export interface MessageStatusResource {
-  /** Always "MessageStatus" */
-  type: "MessageStatus";
-  attributes: MessageStatusAttributes;
-  links: {
-    /** URL to retrieve the overarching message status */
-    message: string;
-  };
-  meta: {
-    /** Key to deduplicate retried requests */
-    idempotencyKey: string;
-  };
+export interface ChannelStatusAttributes extends BaseAttributes {
+  readonly cascadeType?: CascadeType;
+  readonly cascadeOrder?: number;
+  readonly channel: ChannelType;
+  readonly channelStatus: ChannelStatus;
+  /** Extra information associated with the status of this channel */
+  readonly channelStatusDescription?: string;
+  readonly supplierStatus?: SupplierStatus;
+  readonly retryCount: number;
 }
 
+// --- Generic JSON-ish resource -----------------------------------------------
+
+interface Links {
+  /** URL to retrieve the overarching message status */
+  readonly message: string;
+}
+
+interface Meta {
+  /** Key to deduplicate retried requests */
+  readonly idempotencyKey: string;
+}
+
+interface Resource<CallbackType, TAttributes> {
+  readonly type: CallbackType;
+  readonly attributes: TAttributes;
+  readonly links: Links;
+  readonly meta: Meta;
+}
+
+// Concrete resources
+export type MessageStatusResource = Resource<"MessageStatus", MessageStatusAttributes>;
+export type ChannelStatusResource = Resource<"ChannelStatus", ChannelStatusAttributes>;
+
+// --- Responses ---------------------------------------------------------------
+
 export interface MessageStatusResponse {
-  /**
-   * Array of MessageStatus resources.
-   * Must contain at least one element.
-   */
-  data: Array<MessageStatusResource>;
+  readonly data: Array<MessageStatusResource>;
+}
+
+export interface ChannelStatusResponse {
+  readonly data: Array<ChannelStatusResource>;
+}
+
+export type CallbackResource = MessageStatusResource | ChannelStatusResource;
+
+export interface CallbackResponse {
+  readonly data: Array<CallbackResource>;
 }