Skip to main content

Topic

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 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.

Examples​

Using the minimal config​

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

new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: "src/function1.handler",
    subscriber2: "src/function2.handler"
  },
});

Configuring subscribers​

Lazily adding subscribers​

Add subscribers after the topic has been created.

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

topic.addSubscribers(this, {
  subscriber3: "src/subscriber3.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(stack, "Topic", {
  defaults: {
    function: {
      timeout: 20,
      environment: { tableName: table.tableName },
      permissions: [table],
    },
  },
  subscribers: {
    subscriber1: "src/subscriber1.main",
    subscriber2: "src/subscriber2.main",
  },
});

Configuring an individual subscriber​

Configure each Lambda function separately.

new Topic(stack, "Topic", {
  subscribers: {
    subscriber: {
      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(stack, "Topic", {
  defaults: {
    function: {
      timeout: 20,
      environment: { tableName: table.tableName },
      permissions: [table],
    },
  },
  subscribers: {
    subscriber1: {
      function: {
        handler: "subscriber1.main",
        timeout: 10,
        environment: { bucketName: bucket.bucketName },
        permissions: [bucket],
      },
    },
    subscriber2: "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(stack, "Topic", {
  subscribers: {
    subscriber1: "src/subscriber1.main",
    subscriber2: "src/subscriber2.main",
  },
});

topic.attachPermissions(["s3"]);

Giving a specific subscriber some permissions​

Allow the first subscriber function to access S3.

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

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

Configuring the subscription​

Configure the internally created CDK Subscription.

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

new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: {
      function: "src/subscriber1.main",
      cdk: {
        subscription: {
          filterPolicy: {
            color: SubscriptionFilter.stringFilter({
              allowlist: ["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(stack, "Topic", {
  subscribers: {
    subscriber: 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(stack, "Topic", {
  subscribers: {
    subscriber: {
      queue: myQueue,
      cdk: {
        subscription: {
          filterPolicy: {
            color: SubscriptionFilter.stringFilter({
              allowlist: ["red"],
            }),
          },
        },
      },
    },
  },
});

FIFO topic​

new Topic(stack, "Topic", {
  cdk: {
    topic: {
      fifo: true,
    },
  },
});

Note that as of June 2022, FIFO Topic does not support Lambda subscription.

Advanced examples​

Configuring the SNS Topic​

Configure the internally created CDK Topic instance.

new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: "src/subscriber1.main",
    subscriber2: "src/subscriber2.main",
  },
  cdk: {
    topic: {
      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(stack, "Topic", {
  subscribers: {
    subscriber1: "src/subscriber1.main",
    subscriber2: "src/subscriber2.main",
  },
  cdk: {
    topic: sns.Topic.fromTopicArn(this, "MySnsTopic", topicArn),
  },
});

Constructor​

new Topic(scope, id, props)

Parameters

TopicProps​

defaults.function?​

Type : FunctionProps

The default function props to be applied to all the consumers in the Topic. The environment, permissions and layers properties will be merged with per route definitions if they are defined.

new Topic(stack, "Topic", {
  defaults: {
    function: {
      timeout: 20,
    }
  },
});

subscribers?​

Type : Record<string, string | Function | Queue | TopicQueueSubscriberProps | TopicFunctionSubscriberProps>

Configure subscribers for this topic

new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: "src/function1.handler",
    subscriber2: "src/function2.handler"
  },
});

cdk.id?​

Type : string

Allows you to override default id for this construct.

cdk.topic?​

Type : ITopic | TopicProps

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

Properties​

An instance of Topic has the following properties.

id​

Type : string

subscriberFunctions​

Type : Array<Function>

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

subscriptions​

Type : Array<Subscription>

Get a list of subscriptions for this topic

topicArn​

Type : string

The ARN of the internally created SNS Topic.

topicName​

Type : string

The name of the internally created SNS Topic.

cdk.topic​

Type : ITopic

The internally created CDK Topic instance.

Methods​

An instance of Topic has the following methods.

addSubscribers​

addSubscribers(scope, subscribers)

Parameters

Add subscribers to the topic.

const topic = new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: "src/function1.handler",
    subscriber2: "src/function2.handler"
  },
});
topic.addSubscribers(stack, {
  subscriber3: "src/function3.handler"
});

attachPermissions​

attachPermissions(permissions)

Parameters

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

const topic = new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: "src/function1.handler",
    subscriber2: "src/function2.handler"
  },
});
topic.attachPermissions(["s3"]);

attachPermissionsToSubscriber​

attachPermissionsToSubscriber(subscriberName, permissions)

Parameters

Attaches the list of permissions to a specific subscriber.

const topic = new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: "src/function1.handler",
    subscriber2: "src/function2.handler"
  },
});

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

bind​

bind(constructs)

Parameters

  • constructs Array<SSTConstruct>

Binds the given list of resources to all the subscriber functions.

const topic = new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: "src/function1.handler",
    subscriber2: "src/function2.handler"
  },
});
topic.bind([STRIPE_KEY, bucket]);

bindToSubscriber​

bindToSubscriber(subscriberName, constructs)

Parameters

  • subscriberName string
  • constructs Array<SSTConstruct>

Binds the given list of resources to a specific subscriber.

const topic = new Topic(stack, "Topic", {
  subscribers: {
    subscriber1: "src/function1.handler",
    subscriber2: "src/function2.handler"
  },
});

topic.bindToSubscriber("subscriber1", [STRIPE_KEY, bucket]);

TopicQueueSubscriberProps​

Used to define a queue subscriber for a topic

new Topic(stack, "Topic", {
  subscribers: {
    subscriber: {
      type: "queue",
      queue: new Queue(stack, "Queue", {
        consumer: "src/function.handler"
      })
    }
  }
})

queue​

Type : Queue

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

type​

Type : "queue"

String literal to signify that the subscriber is a queue

cdk.subscription?​

Type : SqsSubscriptionProps

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

TopicFunctionSubscriberProps​

Used to define a function subscriber for a topic

new Topic(stack, "Topic", {
  subscribers: {
    subscriber: "src/function.handler"
  }
})

function​

Type : string | Function | FunctionProps

Used to create the subscriber function for the topic

type?​

Type : "function"

String literal to signify that the subscriber is a function

cdk.subscription?​

Type : LambdaSubscriptionProps

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