Queue

The Queue component lets you add a serverless queue to your app. It uses Amazon SQS.

Create a queue

sst.config.ts

const queue = new sst.aws.Queue("MyQueue");

Make it a FIFO queue

You can optionally make it a FIFO queue.

sst.config.ts

new sst.aws.Queue("MyQueue", {
  fifo: true
});

Add a subscriber

sst.config.ts

queue.subscribe("src/subscriber.handler");

Link the queue to a resource

You can link the queue to other resources, like a function or your Next.js app.

sst.config.ts

new sst.aws.Nextjs("MyWeb", {
  link: [queue]
});

Once linked, you can send messages to the queue from your function code.

app/page.tsx

import { Resource } from "sst";
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";

const sqs = new SQSClient({});

await sqs.send(new SendMessageCommand({
  QueueUrl: Resource.MyQueue.url,
  MessageBody: "Hello from Next.js!"
}));

---

Constructor

new Queue(name, args?, opts?)

Parameters

• name string

• args? QueueArgs

• opts? ComponentResourceOptions

QueueArgs

delay?

Type Input<“${number} minute” | “${number} minutes” | “${number} second” | “${number} seconds”>

Default “0 seconds”

The period of time which the delivery of all messages in the queue is delayed.

This can range from 0 seconds to 900 seconds (15 minutes).

{
  delay: "10 seconds"
}

dlq?

Type Input<string | Object>

• queue

• retry

Optionally add a dead-letter queue or DLQ for this queue.

A dead-letter queue is used to store messages that can’t be processed successfully by the subscriber function after the retry limit is reached.

This takes either the ARN of the dead-letter queue or an object to configure how the dead-letter queue is used.

For example, here’s how you can create a dead-letter queue and link it to the main queue.

sst.config.ts

const deadLetterQueue = new sst.aws.Queue("MyDLQ");

new sst.aws.Queue("MyQueue", {
  dlq: deadLetterQueue.arn,
});

By default, the main queue will retry processing the message 3 times before sending it to the dead-letter queue. You can customize this.

sst.config.ts

new sst.aws.Queue("MyQueue", {
  dlq: {
    retry: 5,
    queue: deadLetterQueue.arn,
  }
});

dlq.queue

Type Input<string>

The ARN of the dead-letter queue.

dlq.retry

Type Input<number>

Default 3

The number of times the main queue will retry the message before sending it to the dead-letter queue.

fifo?

Type Input<boolean | Object>

• contentBasedDeduplication?

Default false

FIFO or first-in-first-out queues are designed to guarantee that messages are processed exactly once and in the order that they are sent.

Caution

Changing a standard queue to a FIFO queue (or the other way around) will cause the queue to be destroyed and recreated.

{
  fifo: true
}

By default, content based deduplication is disabled. You can enable it by configuring the fifo property.

{
  fifo: {
    contentBasedDeduplication: true
  }
}

fifo.contentBasedDeduplication?

Type Input<boolean>

Default false

Content-based deduplication automatically generates a deduplication ID by hashing the message body to prevent duplicate message delivery.

transform?

Type Object

• queue?

Transform how this component creates its underlying resources.

transform.queue?

Type QueueArgs | (args: QueueArgs, opts: ComponentResourceOptions, name: string) => void

Transform the SQS Queue resource.

visibilityTimeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds”>

Default “30 seconds”

Visibility timeout is a period of time during which a message is temporarily invisible to other consumers after a consumer has retrieved it from the queue. This mechanism prevents other consumers from processing the same message concurrently, ensuring that each message is processed only once.

This timeout can range from 0 seconds to 12 hours.

{
  visibilityTimeout: "1 hour"
}

Properties

arn

Type Output<string>

The ARN of the SQS Queue.

nodes

Type Object

• queue

The underlying resources this component creates.

nodes.queue

Type Queue

The Amazon SQS Queue.

url

Type Output<string>

The SQS Queue URL.

SDK

Use the SDK in your runtime to interact with your infrastructure.

---

Links

This is accessible through the Resource object in the SDK.

• url string

  The SQS Queue URL.

Methods

subscribe

subscribe(subscriber, args?, opts?)

Parameters

• subscriber Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

  The function that’ll be notified.

• args? QueueSubscriberArgs

  Configure the subscription.

• opts? ComponentResourceOptions

Returns Output<QueueLambdaSubscriber>

Subscribe to this queue.

sst.config.ts

queue.subscribe("src/subscriber.handler");

Add a filter to the subscription.

sst.config.ts

queue.subscribe("src/subscriber.handler", {
  filters: [
    {
      body: {
        RequestCode: ["BBBB"]
      }
    }
  ]
});

Customize the subscriber function.

sst.config.ts

queue.subscribe({
  handler: "src/subscriber.handler",
  timeout: "60 seconds"
});

Or pass in the ARN of an existing Lambda function.

sst.config.ts

queue.subscribe("arn:aws:lambda:us-east-1:123456789012:function:my-function");

static get

Queue.get(name, queueUrl, opts?)

Parameters

• name string

  The name of the component.

• queueUrl Input<string>

  The URL of the existing SQS Queue.

• opts? ComponentResourceOptions

Returns Queue

Reference an existing SQS Queue with its queue URL. This is useful when you create a queue in one stage and want to share it in another stage. It avoids having to create a new queue in the other stage.

Tip

You can use the static get method to share SQS queues across stages.

Imagine you create a queue in the dev stage. And in your personal stage frank, instead of creating a new queue, you want to share the queue from dev.

sst.config.ts

const queue = $app.stage === "frank"
  ? sst.aws.Queue.get("MyQueue", "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue")
  : new sst.aws.Queue("MyQueue");

Here https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue is the URL of the queue created in the dev stage. You can find this by outputting the queue URL in the dev stage.

sst.config.ts

return queue.url;

static subscribe

Queue.subscribe(queueArn, subscriber, args?, opts?)

Parameters

• queueArn Input<string>

  The ARN of the SQS Queue to subscribe to.

• subscriber Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

  The function that’ll be notified.

• args? QueueSubscriberArgs

  Configure the subscription.

• opts? ComponentResourceOptions

Returns Output<QueueLambdaSubscriber>

Subscribe to an SQS Queue that was not created in your app.

For example, let’s say you have an existing SQS Queue with the following ARN.

sst.config.ts

const queueArn = "arn:aws:sqs:us-east-1:123456789012:MyQueue";

You can subscribe to it by passing in the ARN.

sst.config.ts

sst.aws.Queue.subscribe(queueArn, "src/subscriber.handler");

Add a filter to the subscription.

sst.config.ts

sst.aws.Queue.subscribe(queueArn, "src/subscriber.handler", {
  filters: [
    {
      body: {
        RequestCode: ["BBBB"]
      }
    }
  ]
});

Customize the subscriber function.

sst.config.ts

sst.aws.Queue.subscribe(queueArn, {
  handler: "src/subscriber.handler",
  timeout: "60 seconds"
});

QueueSubscriberArgs

batch?

Type Input<Object>

• partialResponses?

• size?

• window?

Default {size: 10, window: “20 seconds”, partialResponses: false}

Configure batch processing options for the consumer function.

batch.partialResponses?

Type Input<boolean>

Default false

Whether to return partial successful responses for a batch.

Enables reporting of individual message failures in a batch. When enabled, only failed messages become visible in the queue again, preventing unnecessary reprocessing of successful messages.

The handler function must return a response with failed message IDs.

Note

Ensure your Lambda function is updated to handle batchItemFailures responses when enabling this option.

Read more about partial batch responses.

Enable partial responses.

{
  batch: {
    partialResponses: true
  }
}

For a batch of messages (id1, id2, id3, id4, id5), if id2 and id4 fail:

{
  "batchItemFailures": [
        {
            "itemIdentifier": "id2"
        },
        {
            "itemIdentifier": "id4"
        }
    ]
}

This makes only id2 and id4 visible again in the queue.

batch.size?

Type Input<number>

Default 10

The maximum number of events that will be processed together in a single invocation of the consumer function.

Value must be between 1 and 10000.

Note

When size is set to a value greater than 10, window must be set to at least 1 second.

Set batch size to 1. This will process events individually.

{
  batch: {
    size: 1
  }
}

batch.window?

Type Input<“${number} minute” | “${number} minutes” | “${number} second” | “${number} seconds”>

Default “0 seconds”

The maximum amount of time to wait for collecting events before sending the batch to the consumer function, even if the batch size hasn’t been reached.

Value must be between 0 seconds and 5 minutes (300 seconds).

{
  batch: {
    window: "20 seconds"
  }
}

filters?

Type Input<Input<Record<string, any>>[]>

Filter the records that’ll be processed by the subscriber function.

Tip

You can pass in up to 5 different filters.

You can pass in up to 5 different filter policies. These will logically ORed together. Meaning that if any single policy matches, the record will be processed. Learn more about the filter rule syntax.

For example, if you Queue contains records in this JSON format.

{
  RecordNumber: 0000,
  RequestCode: "AAAA",
  TimeStamp: "yyyy-mm-ddThh:mm:ss"
}

To process only those records where the RequestCode is BBBB.

{
  filters: [
    {
      body: {
        RequestCode: ["BBBB"]
      }
    }
  ]
}

And to process only those records where RecordNumber greater than 9999.

{
  filters: [
    {
      body: {
        RecordNumber: [{ numeric: [ ">", 9999 ] }]
      }
    }
  ]
}

transform?

Type Object

• eventSourceMapping?

Transform how this component creates its underlying resources.

transform.eventSourceMapping?

Type EventSourceMappingArgs | (args: EventSourceMappingArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Lambda Event Source Mapping resource.