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"),
      }),
    },
  },
});