Skip to main content

Queue

caution

This is the SST v1.x Constructs doc. SST v2 is now released. If you are using v2, see the v2 Constructs doc. If you are looking to upgrade to v2, check out the upgrade steps.

The Queue construct is a higher level CDK construct that makes it easy to create a SQS Queues. You can create a queue by specifying a consumer function. And then publish to the queue from any part of your serverless app.

This construct makes it easier to define a queue and a consumer. It also internally connects the consumer and queue together.

Examples

Using the minimal config

import { Queue } from "@serverless-stack/resources";

new Queue(stack, "Queue", {
consumer: "src/queueConsumer.main",
});

Configuring consumers

Lazily adding consumer

Create an empty queue and lazily add the consumer.

const queue = new Queue(stack, "Queue");

queue.addConsumer(stack, "src/queueConsumer.main");

Configuring the consumer function

new Queue(stack, "Queue", {
consumer: {
function: {
handler: "src/queueConsumer.main",
timeout: 10,
environment: { bucketName: bucket.bucketName },
permissions: [bucket],
},
},
});

Configuring the consumer event source

Configure the internally created CDK Event Source.

new Queue(stack, "Queue", {
consumer: {
function: "src/queueConsumer.main",
cdk: {
eventSource: {
batchSize: 5,
},
},
},
});

Giving the consumer some permissions

Allow the consumer function to access S3.

const queue = new Queue(stack, "Queue", {
consumer: "src/queueConsumer.main",
});

queue.attachPermissions(["s3"]);

FIFO queue

new Queue(stack, "Queue", {
consumer: "src/queueConsumer.main",
cdk: {
queue: {
fifo: true,
},
},
});

Advanced examples

Configuring the SQS queue

Configure the internally created CDK Queue instance.

import { Duration } from "aws-cdk-lib";

new Queue(stack, "Queue", {
consumer: "src/queueConsumer.main",
cdk: {
queue: {
queueName: "my-queue",
visibilityTimeout: Duration.seconds(5),
},
},
});

Importing an existing queue

Override the internally created CDK Queue instance.

import * as sqs from "aws-cdk-lib/aws-sqs";

new Queue(stack, "Queue", {
consumer: "src/queueConsumer.main",
cdk: {
queue: sqs.Queue.fromQueueArn(stack, "MySqsQueue", queueArn),
},
});

Using existing Lambda functions as consumer

import * as iam from "aws-cdk-lib/aws-iam";
import * as lambda from "aws-cdk-lib/aws-lambda";

new Queue(stack, "Queue", {
consumer: {
cdk: {
function: lambda.Function.fromFunctionAttributes(stack, "IFunction", {
functionArn: "arn:aws:lambda:us-east-1:123456789:function:my-function",
role: iam.Role.fromRoleArn(stack, "IRole", "arn:aws:iam::123456789:role/my-role"),
}),
},
},
});

Constructor

new Queue(scope, id, props)

Parameters

QueueProps

consumer?

Type : string | Function | QueueConsumerProps

Used to create the consumer for the queue.

new Queue(stack, "Queue", {
consumer: "src/function.handler",
})

cdk.id?

Type : string

Allows you to override default id for this construct.

cdk.queue?

Type : IQueue | QueueProps

Override the default settings this construct uses internally to create the queue.

new Queue(stack, "Queue", {
consumer: "src/function.handler",
cdk: {
queue: {
fifo: true,
},
}
});

Properties

An instance of Queue has the following properties.

consumerFunction?

Type : Function | IFunction

The internally created consumer Function instance.

id

Type : string

queueArn

Type : string

The ARN of the SQS Queue

queueName

Type : string

The name of the SQS Queue

queueUrl

Type : string

The URL of the SQS Queue

cdk.queue

Type : IQueue

The internally created CDK Queue instance.

Methods

An instance of Queue has the following methods.

addConsumer

addConsumer(scope, consumer)

Parameters

Adds a consumer after creating the queue. Note only one consumer can be added to a queue

const queue = new Queue(stack, "Queue");
queue.addConsumer(props.stack, "src/function.handler");

attachPermissions

attachPermissions(permissions)

Parameters

Attaches additional permissions to the consumer function

const queue = new Queue(stack, "Queue", {
consumer: "src/function.handler",
});
queue.attachPermissions(["s3"]);

bind

bind(constructs)

Parameters

  • constructs Array<SSTConstruct>

Binds the given list of resources to the consumer function

const queue = new Queue(stack, "Queue", {
consumer: "src/function.handler",
});
queue.bind([STRIPE_KEY, bucket]);

QueueConsumerProps

Used to define the consumer for the queue and invocation details

function?

Type : string | Function | FunctionProps

Used to create the consumer function for the queue.

new Queue(stack, "Queue", {
consumer: {
function: {
handler: "src/function.handler",
timeout: 10,
},
},
});

cdk.eventSource?

Type : SqsEventSourceProps

This allows you to override the default settings this construct uses internally to create the consumer.

new Queue(stack, "Queue", {
consumer: {
function: "test/lambda.handler",
cdk: {
eventSource: {
batchSize: 5,
},
},
},
});

cdk.function?

Type : IFunction

This allows you to use an existing or imported Lambda function.

new Queue(stack, "Queue", {
consumer: {
cdk: {
function: lambda.Function.fromFunctionAttributes(stack, "ImportedFn", {
functionArn: "arn:aws:lambda:us-east-1:123456789:function:my-function",
role: iam.Role.fromRoleArn(stack, "IRole", "arn:aws:iam::123456789:role/my-role"),
}),
},
},
});