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.