Amazon SQS

Amazon SQS is a fully managed queue service from AWS. @node-ts/bus-sqs publishes each message to an SNS topic and subscribes your service queue to the topics of the messages it handles. It can create the topics, queues and subscriptions for you, or use ones you manage. This page covers installing and configuring it.

@node-ts/bus-sqs Source

Installation

npmpnpmyarn

npm i @node-ts/bus-sqs

pnpm add @node-ts/bus-sqs

yarn add @node-ts/bus-sqs

Configure an SqsTransport and pass it to the bus configuration:

const sqsConfiguration: SqsTransportConfiguration = {
  awsRegion: process.env.AWS_REGION,
  awsAccountId: process.env.AWS_ACCOUNT_ID,
  queueName: 'reservations-service',
  deadLetterQueueName: 'reservations-service-dead-letter'
}
const sqsTransport = new SqsTransport(sqsConfiguration)

const bus = Bus.configure()
  .withMessageTypes(messageTypes)
  .withTransport(sqsTransport)
  .withHandler(reserveRoomHandler)
  .build()

// Creates the queues and topics, and subscribes the queue to each handled message's topic
await bus.initialize()
await bus.start()

The transport uses the AWS SDK's default credentials. Pass your own SQSClient and SNSClient from @aws-sdk/client-sqs and @aws-sdk/client-sns as the second and third constructor arguments to configure them.

Configuration

Give either queueArn, or awsAccountId, awsRegion and queueName. awsAccountId and awsRegion are also needed by a send-only bus.

Option	Default	Description
`awsAccountId`		The account that queues and topics are created in.
`awsRegion`		The region that queues and topics are created in.
`queueName`		The queue that receives this service's messages.
`queueArn`		The ARN of the service queue, instead of `queueName`. The account, region and name are read from it.
`deadLetterQueueName`	`dlq`	The name of the dead letter queue.
`deadLetterQueueArn`		The ARN of an existing dead letter queue. Takes precedence over `deadLetterQueueName`.
`maxReceiveCount`	`10`	How many times a message is received before SQS moves it to the dead letter queue.
`visibilityTimeout`	`30`	The service queue's visibility timeout in seconds, which is how long a handler has before the message is redelivered.
`waitTimeSeconds`	`10`	The long polling wait when receiving. `0` turns on short polling. Longer waits make shutdown slower.
`messageRetentionPeriod`	`1209600` (14 days)	How long the dead letter queue keeps messages, in seconds. At least 60.
`queuePolicy`	allows SNS topics in the same account	A policy to attach to the service queue.
`resolveTopicName`	the `$name` with invalid characters as `-`	Maps a message's `$name` to its SNS topic name, for example to add an environment prefix.
`resolveTopicArn`	`arn:aws:sns:<region>:<account>:<topic>`	Maps a topic name to its ARN.
`autoProvision`	`true`	Whether the transport creates queues, topics, subscriptions and the queue policy, and keeps the queue's attributes in sync.

On startup, the transport compares the service queue's VisibilityTimeout and RedrivePolicy with the configuration and updates only the ones that differ.

Managing resources yourself

Set autoProvision: false when the queues and topics are created elsewhere, such as with CDK, CloudFormation or Terraform. The transport then creates nothing. At initialize() it checks that the service queue, the dead letter queue, each topic and each topic's subscription to the service queue exist, and throws if any are missing. visibilityTimeout, maxReceiveCount, messageRetentionPeriod and queuePolicy have no effect.

// Queues, topics and subscriptions are created elsewhere, e.g. with CDK or Terraform
new SqsTransport({
  queueArn: 'arn:aws:sqs:us-east-1:000000000000:reservations-service',
  deadLetterQueueArn:
    'arn:aws:sqs:us-east-1:000000000000:reservations-service-dead-letter',
  autoProvision: false
})

Message attributes

Attributes are sent as SNS message attributes named attributes.<key>, stickyAttributes.<key> and correlationId. Strings use the String type and numbers Number. SNS has no boolean type, so booleans are sent as String.boolean, with the value true or false, and read back as booleans. Keep this in mind when writing SNS subscription filter policies. Empty strings are left out, because SNS rejects them.

Running SQS locally

LocalStack emulates SQS and SNS:

docker run -d -e SERVICES=sqs,sns -p 4566:4566 localstack/localstack

Amazon SQS ​

Installation ​

Configuration ​

Managing resources yourself ​

Message attributes ​

Running SQS locally ​

See also ​