Domain Events

HMPPS uses an event-driven microservices architecture and has an AWS Simple Notification Service (SNS) topic called hmpps-domain-events for publishing events. This SNS topic should be used to notify other services about changes to your domain, and this is where you should listen for changes to other domains.

We’ve opted for a thin events strategy, which means we publish only the IDs for whatever has changed and the client is expected to call back to the relevant domain for details.

The Domain Event Schema defines the format of domain events.

We expect teams to document their published domain events using async-api. Look out for a button linking to event documentation in a project’s README.

Subscribing to domain events

To receive domain events you’ll need to create an SQS queue that subscribes to hmpps-domain-topic, filter for events you’re interested in and then listen for those events in your application.

An example best illustrates the various moving parts.

Authenticating with AWS

See the guide on AWS service accounts for how to create the IRSA module.

You’ll need to add policies to the service account as they are created below.

Accessing the domain topic

• expose the Domain Topic ARN from an SSM parameter to your namespace (as a Kubernetes secret)
• create a policy for the topic and store in local variables
• add the topic policy to the service account

Creating the queue

• define the queue and associated dead letter queue (DLQ)
• create Kubernetes secrets in your namespace so your application knows about the queues
• create a queue policy
• add the queue and DLQ policies to the service account

Subscribing to the topic

Create the topic subscription resource.

Note that the filter_policy determines which events on the domain topic end up on your queue. A common pattern is to use eventType to select those events.

Listening for events

We have an HMPPS SQS library that provides some tooling for integrating with AWS SQS and SNS. We use this in our Kotlin applications to help with configuration, listening / publishing and testing.

• add the HMPPS SQS library as a dependency to your application
• map the Kubernetes secrets created by Cloud Platform into environment variables that are picked up by the HMPPS SQS library
• create an SQS listener in your application code

As there is some “magic” happening in the HMPPS SQS library there are some important conventions at play here. Don’t change these things on a whim or your listener won’t work.

• the @SqsListener name (hmppsdomaineventsqueue) must match the environment variable (HMPPS_SQS_QUEUES_HMPPSDOMAINEVENTSQUEUE_QUEUE_NAME) from your values.yaml file
• the format of the env var is important and must follow the library’s conventions
• the factory hmppsQueueContainerFactoryProxy is a hook into the HMPPS SQS library

Your listener should now receive all events published to the hmpps-domain-topic that match your filter.

Localstack and testing event listeners

We use Localstack to mock our AWS services for integration testing, specifically for SQS and SNS.

In order to start Localstack automatically for integration tests when running locally:

• add the testcontainers dependency
• add the Testcontainers Localstack container to your integration tests
• make sure the Testcontainers container does not start if LocalStack is already running - this will be the case in CircleCI which does not support Testcontainers
• set Spring test configuration to tell the HMPPS SQS library to create a topic in Localstack
• set Spring test configuration to tell the HMPPS SQS library to create a queue that listens to the Localstack domain topic
• provide a way for your tests to publish test events to the Localstack domain

As mentioned above, we can’t use Testcontainers in our CircleCI tests and this is why the Testcontainers container does not start if it thinks Localstack is already running. To run the integration tests on Circle you’ll need to use one of our HMPPS executors that starts Localstack in an external Docker container.

Publishing domain events

When publishing domain events you only need access to the domain topic. If you have not already done so, you’ll need to follow the steps above for Authenticating with AWS and Accessing the domain topic.

Publishing events

We have an HMPPS SQS library that provides some tooling for integrating with AWS SQS and SNS. We use this in our Kotlin applications to help with configuration, listening / publishing and testing.

• add the HMPPS SQS library as a dependency to your application
• map the Kubernetes secrets created by Cloud Platform into an environment variable which is picked up by the HMPPS SQS library
• get the topic from the HMPPS SQS library and you can now publish to the topic

As there is some “magic” happening in the HMPPS SQS library there are some important conventions at play here. Don’t change these things on a whim or your publish won’t work.

• the topicId (hmppseventtopic) must match the environment variable (HMPPS_SQS_TOPICS_HMPPSEVENTTOPIC_ARN) from your values.yaml file
• the format of the env var is important and must follow the library’s conventions

Localstack and testing event publishing

This is very similar to testing event listeners and the same steps should be followed to configure Localstack etc.

In addition to this test configuration we often create a “test queue” to check that domain events are published as expected. The test queue is only created during tests in Localstack and uses the HMPPS SQS library to both create the queue and subscribe to the topic.

• tell the HMPPS SQS library to create a test queue, subscribe to the topic and listen for certain events (the events you’re testing)
• create a test that triggers the event publish, waits until the event hits the test queue, reads the event and asserts it is correct

Documenting published events

We use AsyncAPI to document the events we publish.

This should be as simple as creating your API specification and adding a badge to your README.

Running the application locally

To spin up LocalStack locally provide a docker compose file. You’d then need to start the application using a Spring profile named e.g. local.