System messages

System messages are message that originate externally to your app. These can be things like an event from S3 indicating an object has been created, an email receipt on a support mailbox, or a disk space threshold has been reached on an important server.

Because system messages are created and sent by external systems, it's not possible to enforce @node-ts/bus conventions on the structure of the message. Instead messages are consumed as is, with custom mapping code used to identify a system message and route it to its handler.

Having an adapter handler that receives a system message and then maps it to a locally declared message that's then published helps ensure your app doesn't get corrupted with language and conventions of external systems.

Creating a System Message

System messages are class definitions. If the system publishing the message doesn't expose a class definition for the message they're publishing then it can be created.

/**
* A message that is published by S3 each time an action has occurred on an object
*/
export class S3Event {
  readonly Records: {
    eventSource: 'aws:s3',
    eventName: string,
    s3: {
      object: {
        key: string
      }
    }
  }[]
}

Handling System Messages

System messages must be subscribed to manually. This usually means configuring the system to send to a topic that the application is subscribed to. This will ensure that messages sent by the external system will be routed to and read from the service queue.

Handler registration is done using the .withCustomHandler() function on configuration. This accepts the handler, a custom resolveWith property that identifies incoming messages as being the type the handler should receive, and a topicIdentifier that @node-ts/bus will subscribe the application service queue to.

import { S3Event } from 'contracts'

await Bus.configure()
  .withCustomHandler(
    async (event: S3Event) => console.log('Received S3 event', { event }),
    {
      resolveWith: event => event.Records
        && event.Records.length
        && event.Records[0].eventSource === 'aws:s3',
      topicIdentifier: 'arn:aws:sns:us-east-1:000000000000:s3-object-created'
    }
  ).initialize()

Remember to .start() the bus to start handling messages

await bus.start()