Skip to main content

Topic

caution

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

The Topic construct is a higher level CDK construct that makes it easy to create a serverless pub/sub service. You can create a topic that has a list of subscribers. And you can publish messages to it from any part of your serverless app.

You can have two types of subscribers; Function subscribers (subscribe with a Lambda function) or Queue subscribers (subscribe with a SQS queue).

This construct makes it easier to define a topic and its subscribers. It also internally connects the subscribers and topic together.

Initializer

new Topic(scope: Construct, id: string, props: TopicProps)

Parameters

Examples

Using the minimal config

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

new Topic(this, "Topic", {
subscribers: ["src/subscriber1.main", "src/subscriber2.main"],
});

Adding Function subscribers

Add subscribers after the topic has been created.

const topic = new Topic(this, "Topic", {
subscribers: ["src/subscriber1.main", "src/subscriber2.main"],
});

topic.addSubscribers(this, ["src/subscriber3.main"]);

Lazily adding Function subscribers

Create an empty topic and lazily add the subscribers.

const topic = new Topic(this, "Topic");

topic.addSubscribers(this, ["src/subscriber1.main", "src/subscriber2.main"]);

Configuring Function subscribers

Specifying function props for all the subscribers

You can extend the minimal config, to set some function props and have them apply to all the subscribers.

new Topic(this, "Topic", {
defaultFunctionProps: {
timeout: 20,
environment: { tableName: table.tableName },
permissions: [table],
},
subscribers: ["src/subscriber1.main", "src/subscriber2.main"],
});

Using the full config

If you wanted to configure each Lambda function separately, you can pass in the TopicFunctionSubscriberProps.

new Topic(this, "Topic", {
subscribers: [{
function: {
srcPath: "src/",
handler: "subscriber1.main",
environment: { tableName: table.tableName },
permissions: [table],
},
}],
});

Note that, you can set the defaultFunctionProps while using the function per subscriber. The function will just override the defaultFunctionProps. Except for the environment, the layers, and the permissions properties, that will be merged.

new Topic(this, "Topic", {
defaultFunctionProps: {
timeout: 20,
environment: { tableName: table.tableName },
permissions: [table],
},
subscribers: [
{
function: {
handler: "subscriber1.main",
timeout: 10,
environment: { bucketName: bucket.bucketName },
permissions: [bucket],
},
},
"subscriber2.main",
],
});

So in the above example, the subscriber1 function doesn't use the timeout that is set in the defaultFunctionProps. It'll instead use the one that is defined in the function definition (10 seconds). And the function will have both the tableName and the bucketName environment variables set; as well as permissions to both the table and the bucket.

Giving the subscribers some permissions

Allow the subscriber functions to access S3.

const topic = new Topic(this, "Topic", {
subscribers: ["src/subscriber1.main", "src/subscriber2.main"],
});

topic.attachPermissions(["s3"]);

Giving a specific subscriber some permissions

Allow the first subscriber function to access S3.

const topic = new Topic(this, "Topic", {
subscribers: ["src/subscriber1.main", "src/subscriber2.main"],
});

topic.attachPermissionsToSubscriber(0, ["s3"]);

Configuring the subscription

Configure the internally created CDK Subscription.

import { SubscriptionFilter } from "aws-cdk-lib/aws-sns";

new Topic(this, "Topic", {
subscribers: [
{
function: "src/subscriber1.main",
subscriberProps: {
filterPolicy: {
color: SubscriptionFilter.stringFilter({
whitelist: ["red"],
}),
},
},
},
],
});

Configuring Queue subscribers

Specifying the Queue directly

You can directly pass in an instance of the Queue construct.

const myQueue = new Queue(this, "MyQueue");

new Topic(this, "Topic", {
subscribers: [myQueue],
});

Configuring the subscription

Configure the internally created CDK Subscription.

import { SubscriptionFilter } from "aws-cdk-lib/aws-sns";

const myQueue = new Queue(this, "MyQueue");

new Topic(this, "Topic", {
subscribers: [
{
queue: myQueue,
subscriberProps: {
filterPolicy: {
color: SubscriptionFilter.stringFilter({
whitelist: ["red"],
}),
},
},
},
],
});

Creating a FIFO topic

new Topic(this, "Topic", {
subscribers: ["src/subscriber1.main", "src/subscriber2.main"],
snsTopic: {
fifo: true,
},
});

Configuring the SNS topic

Configure the internally created CDK Topic instance.

new Topic(this, "Topic", {
subscribers: ["src/subscriber1.main", "src/subscriber2.main"],
snsTopic: {
topicName: "my-topic",
},
});

Importing an existing topic

Override the internally created CDK Topic instance.

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

new Topic(this, "Topic", {
subscribers: ["src/subscriber1.main", "src/subscriber2.main"],
snsTopic: sns.Topic.fromTopicArn(this, "MySnsTopic", topicArn),
});

Properties

An instance of Topic contains the following properties.

topicArn

Type: string

The ARN of the internally created CDK Topic instance.

topicName

Type: string

The name of the internally created CDK Topic instance.

snsTopic

Type : cdk.aws-sns.Topic

The internally created CDK Topic instance.

snsSubscriptions

Type : cdk.aws-sns.Subscription

A list of the internally created CDK Subscription instances.

subscriberFunctions

Type : Function[]

A list of the internally created Function instances for the subscribers.

Methods

An instance of Topic contains the following methods.

addSubscribers

addSubscribers(scope: cdk.Construct, subscribers: (FunctionDefinition | TopicFunctionSubscriberProps | Queue | TopicQueueSubscriberProps)[])

Parameters

  • scope cdk.Construct
  • subscribers (FunctionDefinition | TopicFunctionSubscriberProps | Queue | TopicQueueSubscriberProps)[]

A list of FunctionDefinition, TopicFunctionSubscriberProps, Queue, or TopicQueueSubscriberProps objects that'll be used to add the subscribers for the topic.

Use FunctionDefinition or TopicFunctionSubscriberProps to add a Lambda function subscriber.

Or, use Queue or TopicQueueSubscriberProps to add a Queue subscriber.

attachPermissions

attachPermissions(permissions: Permissions)

Parameters

Attaches the given list of permissions to all the subscriberFunctions. This allows the subscribers to access other AWS resources.

Internally calls Function.attachPermissions.

attachPermissionsToSubscriber

attachPermissions(index: number, permissions: Permissions)

Parameters

Attaches the given list of permissions to a specific function in the list of subscriberFunctions. Where index (starting at 0) is used to identify the subscriber. This allows that subscriber to access other AWS resources.

Internally calls Function.attachPermissions.

TopicProps

subscribers?

Type : (FunctionDefinition | TopicFunctionSubscriberProps | Queue | TopicQueueSubscriberProps)[], defaults to []

A list of FunctionDefinition, TopicFunctionSubscriberProps, Queue, or TopicQueueSubscriberProps objects that'll be used to add the subscribers for the topic.

Use FunctionDefinition or TopicFunctionSubscriberProps to add a Lambda function subscriber.

Or, use Queue or TopicQueueSubscriberProps to add a Queue subscriber.

snsTopic?

Type : cdk.aws-sns.Topic | cdk.aws-sns.TopicProps, defaults to undefined

Or optionally pass in a CDK cdk.aws-sns.TopicProps or a cdk.aws-sns.Topic instance. This allows you to override the default settings this construct uses internally to create the topic.

defaultFunctionProps?

Type : FunctionProps, defaults to {}

The default function props to be applied to all the Lambda functions in the Topic. If the function is specified for a subscriber, these default values are overridden. Except for the environment, the layers, and the permissions properties, that will be merged.

TopicFunctionSubscriberProps

function

Type : FunctionDefinition

A FunctionDefinition object that'll be used to create the subscriber function for the topic.

subscriberProps?

Type : cdk.aws-sns-subscriptions.LambdaSubscriptionProps, defaults to undefined

Or optionally pass in a CDK LambdaSubscriptionProps. This allows you to override the default settings this construct uses internally to create the subscriber.

TopicQueueSubscriberProps

queue

Type : Queue

The Queue construct that'll be added as a subscriber to the topic.

subscriberProps?

Type : cdk.aws-sns-subscriptions.SqsSubscriptionProps, defaults to undefined

Or optionally pass in the CDK SqsSubscriptionProps. This allows you to override the default settings this construct uses internally to create the subscriber.