https://github.com/defra/forms-notify-listener
Git repository for service forms-notify-listener
https://github.com/defra/forms-notify-listener
backend cdp node service
Last synced: 2 months ago
JSON representation
Git repository for service forms-notify-listener
- Host: GitHub
- URL: https://github.com/defra/forms-notify-listener
- Owner: DEFRA
- License: other
- Created: 2025-08-15T09:31:14.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-04-08T15:23:03.000Z (3 months ago)
- Last Synced: 2026-04-08T16:18:49.561Z (3 months ago)
- Topics: backend, cdp, node, service
- Language: JavaScript
- Size: 799 KB
- Stars: 0
- Watchers: 0
- Forks: 1
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# forms-notify-listener
Core delivery platform Node.js Backend Template.
- [forms-notify-listener](#forms-notify-listener)
- [Requirements](#requirements)
- [Node.js](#nodejs)
- [Local development](#local-development)
- [Setup](#setup)
- [Development](#development)
- [Development](#development-1)
- [Testing](#testing)
- [Production](#production)
- [Notes on SQS queue configuration](#notes-on-sqs-queue-configuration)
- [Queue configuration in forms-audit-api](#queue-configuration-in-forms-audit-api)
- [Npm scripts](#npm-scripts)
- [Update dependencies](#update-dependencies)
- [Formatting](#formatting)
- [Windows prettier issue](#windows-prettier-issue)
- [API endpoints](#api-endpoints)
- [Development helpers](#development-helpers)
- [Proxy](#proxy)
- [Docker](#docker)
- [Development image](#development-image)
- [Production image](#production-image)
- [Docker Compose](#docker-compose)
- [Dependabot](#dependabot)
- [SonarCloud](#sonarcloud)
- [Licence](#licence)
- [About the licence](#about-the-licence)
## Requirements
### Node.js
Please install [Node.js](http://nodejs.org/) `>= v22` and [npm](https://nodejs.org/) `>= v11`. You will find it
easier to use the Node Version Manager [nvm](https://github.com/creationix/nvm)
To use the correct version of Node.js for this application, via nvm:
```bash
cd forms-notify-listener
nvm use
```
## Local development
### Setup
1. Install Docker
2. Bring up runtime dependencies
```bash
docker compose up
```
3. Create a `.env` file with the following mandatory environment variables populated at root level:
```text
FORMS_AUDIT_QUEUE='forms_notify_listener_events'
LOG_LEVEL=debug
SQS_ENDPOINT=http://localhost:4566
AWS_REGION=eu-west-2
EVENTS_SQS_QUEUE_URL=http://sqs.eu-west-2.127.0.0.1:4566/000000000000/forms_notify_listener_events
AWS_ACCESS_KEY_ID=dummy
AWS_SECRET_ACCESS_KEY=dummy
RECEIVE_MESSAGE_TIMEOUT_MS=5000
NOTIFY_TEMPLATE_ID=3d448938-8a8b-40c2-a3de-414597f976e1
NOTIFY_API_KEY=[your api key]
NOTIFY_REPLY_TO_ID=462e5ac0-28f1-4e51-9d8e-8d8c31f59f6a
RECEIVE_MESSAGE_TIMEOUT_MS=5000
MANAGER_URL=http://localhost:3001
DESIGNER_URL=http://localhost:3000
```
For proxy options, see https://www.npmjs.com/package/proxy-from-env which is used by https://github.com/TooTallNate/proxy-agents/tree/main/packages/proxy-agent. It's currently supports Hapi Wreck only, e.g. in the JWKS lookup.
### Development
Install application dependencies:
```bash
npm install
```
### Development
To run the application in `development` mode run:
```bash
npm run dev
```
### Testing
To test the application run:
```bash
npm run test
```
### Production
To mimic the application running in `production` mode locally run:
```bash
npm start
```
### Notes on SQS queue configuration
`ReceiveMessageWaitTime` - this is probably the most important queue setting and controls what amazon call long polling vs short polling. When `ReceiveMessageWaitTime` is greater than 0, long polling is in effect. The max `ReceiveMessageWaitTime` is 20s.
This is the code affect by this setting:
```js
export function receiveEventMessages() {
const command = new ReceiveMessageCommand(input)
return sqsClient.send(command)
}
```
With short-polling, line 3 fetches any messages from SQS and yields immediately.
It may sample only a subset of the queue’s partitions, so you might not see all currently available messages on that call.
With long-polling, if there aren’t any messages found, the HTTP connection is kept open for up to 20s until some arrive. The consumer of receiveEventMessages is left waiting while that happens.
It will fetch all currently available messages up to the message limit across the queue's partitions.
By default, CDP set `ReceiveMessageWaitTime` to 20s. The auditing queue also uses this default.
See [here](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html) for more information.
#### Queue configuration in forms-audit-api
`RECEIVE_MESSAGE_TIMEOUT_MS` - the amount of time to wait between calls to receive messages
`SQS_MAX_NUMBER_OF_MESSAGES` - the number of messages to receive at once (max 10)
`SQS_VISIBILITY_TIMEOUT` - when receiving a message from an Amazon SQS queue, it remains in the queue but becomes temporarily invisible to other consumers. This invisibility is controlled by the visibility timeout, which ensures that other consumers cannot process the same message while you are working on it.
### Npm scripts
All available Npm scripts can be seen in [package.json](./package.json).
To view them in your command line run:
```bash
npm run
```
### Update dependencies
To update dependencies use [npm-check-updates](https://github.com/raineorshine/npm-check-updates):
> The following script is a good start. Check out all the options on
> the [npm-check-updates](https://github.com/raineorshine/npm-check-updates)
```bash
ncu --interactive --format group
```
### Formatting
#### Windows prettier issue
If you are having issues with formatting of line breaks on Windows update your global git config by running:
```bash
git config --global core.autocrlf false
```
## API endpoints
| Endpoint | Description |
| :------------------- | :----------------------------- |
| `GET: /health` | Health |
| `GET: /example ` | Example API (remove as needed) |
| `GET: /example/` | Example API (remove as needed) |
## Development helpers
### Proxy
We are using forward-proxy which is set up by default. To make use of this: `import { fetch } from 'undici'` then
because of the `setGlobalDispatcher(new ProxyAgent(proxyUrl))` calls will use the ProxyAgent Dispatcher
If you are not using Wreck, Axios or Undici or a similar http that uses `Request`. Then you may have to provide the
proxy dispatcher:
To add the dispatcher to your own client:
```javascript
import { ProxyAgent } from 'undici'
return await fetch(url, {
dispatcher: new ProxyAgent({
uri: proxyUrl,
keepAliveTimeout: 10,
keepAliveMaxTimeout: 10
})
})
```
## Docker
### Development image
Build:
```bash
docker build --target development --no-cache --tag forms-notify-listener:development .
```
Run:
```bash
docker run -e PORT=3001 -p 3001:3001 forms-notify-listener:development
```
### Production image
Build:
```bash
docker build --no-cache --tag forms-notify-listener .
```
Run:
```bash
docker run -e PORT=3001 -p 3001:3001 forms-notify-listener
```
### Docker Compose
A local environment with:
- Localstack for AWS services (S3, SQS)
- Redis
- This service.
- A commented out frontend example.
```bash
docker compose up --build -d
```
### Dependabot
We have added an example dependabot configuration file to the repository. You can enable it by renaming
the [.github/example.dependabot.yml](.github/example.dependabot.yml) to `.github/dependabot.yml`
### SonarCloud
Instructions for setting up SonarCloud can be found in [sonar-project.properties](./sonar-project.properties)
## Licence
THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:
The following attribution statement MUST be cited in your products and applications when using this information.
> Contains public sector information licensed under the Open Government license v3
### About the licence
The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable
information providers in the public sector to license the use and re-use of their information under a common open
licence.
It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.