or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmessage-filtering.mdpolicy-management.mdsubscription-management.mdtopic-management.md
tile.json

tessl/npm-aws-cdk--aws-sns

AWS CDK constructs for Amazon Simple Notification Service enabling Infrastructure as Code creation of scalable pub/sub messaging.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-cdk/aws-sns@1.204.x

To install, run

npx @tessl/cli install tessl/npm-aws-cdk--aws-sns@1.204.0

index.mddocs/

AWS CDK SNS

⚠️ DEPRECATION NOTICE: AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated, and users should migrate to AWS CDK v2. For migration information, see https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html

AWS CDK SNS provides TypeScript constructs for Amazon Simple Notification Service (SNS) that enable Infrastructure as Code creation of scalable pub/sub messaging systems. The library offers comprehensive SNS topic management with support for both standard and FIFO topics, extensive subscription management with multiple protocols, advanced filter policies for selective message delivery, and seamless integration with other AWS services.

Package Information

  • Package Name: @aws-cdk/aws-sns
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-cdk/aws-sns (⚠️ Deprecated - use AWS CDK v2)
  • CDK Version: v1 (End-of-Support as of 2023-06-01)
  • License: Apache-2.0
  • Maturity: End-of-Support

Core Imports

import * as sns from '@aws-cdk/aws-sns';
import { Topic, TopicProps, ITopic } from '@aws-cdk/aws-sns';

For specific constructs:

import { 
  Topic, 
  TopicBase,
  ITopic,
  Subscription, 
  TopicPolicy, 
  SubscriptionFilter,
  SubscriptionProtocol,
  SubscriptionOptions,
  ITopicSubscription,
  TopicSubscriptionConfig
} from '@aws-cdk/aws-sns';

Basic Usage

import * as sns from '@aws-cdk/aws-sns';
import * as cdk from '@aws-cdk/core';

export class MyStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Create a standard SNS topic
    const topic = new sns.Topic(this, 'MyTopic', {
      displayName: 'My Notification Topic'
    });

    // Create a FIFO topic with content-based deduplication
    const fifoTopic = new sns.Topic(this, 'MyFifoTopic', {
      fifo: true,
      contentBasedDeduplication: true,
      topicName: 'my-fifo-topic'
    });

    // Add a subscription with filter policy
    new sns.Subscription(this, 'MySubscription', {
      topic: topic,
      protocol: sns.SubscriptionProtocol.SQS,
      endpoint: 'arn:aws:sqs:us-east-1:123456789012:my-queue',
      filterPolicy: {
        eventType: sns.SubscriptionFilter.stringFilter({
          allowlist: ['order-placed', 'order-cancelled']
        })
      }
    });
  }
}

Architecture

AWS CDK SNS is built around several key architectural patterns:

  • Resource Constructs: CDK constructs that map to CloudFormation resources (Topic, Subscription, TopicPolicy)
  • Interface Abstractions: ITopic interface enables polymorphism between new and imported topics
  • Base Classes: TopicBase provides common functionality while allowing specialization
  • Configuration Objects: Props interfaces define construct configuration with sensible defaults
  • Integration Points: Built-in integration with IAM, KMS, SQS, and other AWS services
  • Subscription System: Pluggable subscription interface allowing custom subscription types
  • Filter Policies: Rich filtering system for selective message delivery

Capabilities

Topic Management

Core SNS topic creation and management functionality supporting both standard and FIFO topics with encryption, naming, and policy configuration.

class Topic extends TopicBase {
  constructor(scope: Construct, id: string, props?: TopicProps);
  static fromTopicArn(scope: Construct, id: string, topicArn: string): ITopic;
  readonly topicArn: string;
  readonly topicName: string;
  readonly fifo: boolean;
}

interface TopicProps {
  displayName?: string;
  topicName?: string;
  masterKey?: IKey;
  contentBasedDeduplication?: boolean;
  fifo?: boolean;
}

Topic Management

Subscription Management

Comprehensive subscription system supporting multiple protocols (HTTP/S, SQS, Lambda, Email, SMS, etc.) with dead letter queues, filter policies, and cross-region configuration.

class Subscription extends Resource {
  constructor(scope: Construct, id: string, props: SubscriptionProps);
  readonly deadLetterQueue?: IQueue;
}

interface SubscriptionProps extends SubscriptionOptions {
  topic: ITopic;
}

enum SubscriptionProtocol {
  HTTP = 'http',
  HTTPS = 'https',
  EMAIL = 'email',
  EMAIL_JSON = 'email-json',
  SMS = 'sms',
  SQS = 'sqs',
  APPLICATION = 'application',
  LAMBDA = 'lambda',
  FIREHOSE = 'firehose'
}

Subscription Management

Message Filtering

Advanced filter policy system for selective message delivery based on message attributes, supporting string conditions, numeric conditions, and existence checks.

class SubscriptionFilter {
  constructor(conditions: any[]);
  static stringFilter(conditions: StringConditions): SubscriptionFilter;
  static numericFilter(conditions: NumericConditions): SubscriptionFilter;
  static existsFilter(): SubscriptionFilter;
  readonly conditions: any[];
}

Message Filtering

Policy Management

IAM policy management for SNS topics with automatic policy creation, statement addition, and integration with CDK's permission grant system.

class TopicPolicy extends Resource {
  constructor(scope: Construct, id: string, props: TopicPolicyProps);
  readonly document: PolicyDocument;
}

interface TopicPolicyProps {
  topics: ITopic[];
  policyDocument?: PolicyDocument;
}

Policy Management

Common Types

interface ITopic extends IResource, notifications.INotificationRuleTarget {
  readonly topicArn: string;
  readonly topicName: string;
  readonly fifo: boolean;
  addSubscription(subscription: ITopicSubscription): void;
  addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
  grantPublish(identity: iam.IGrantable): iam.Grant;
}

interface ITopicSubscription {
  bind(topic: ITopic): TopicSubscriptionConfig;
}

interface SubscriptionOptions {
  protocol: SubscriptionProtocol;
  endpoint: string;
  rawMessageDelivery?: boolean;
  filterPolicy?: { [attribute: string]: SubscriptionFilter };
  region?: string;
  deadLetterQueue?: IQueue;
  subscriptionRoleArn?: string;
}

interface TopicSubscriptionConfig extends SubscriptionOptions {
  subscriberScope?: Construct;
  subscriberId: string;
}

interface StringConditions {
  allowlist?: string[];
  denylist?: string[];
  matchPrefixes?: string[];
  /** @deprecated use allowlist */
  whitelist?: string[];
  /** @deprecated use denylist */
  blacklist?: string[];
}

interface NumericConditions {
  allowlist?: number[];
  greaterThan?: number;
  greaterThanOrEqualTo?: number;
  lessThan?: number;
  lessThanOrEqualTo?: number;
  between?: BetweenCondition;
  betweenStrict?: BetweenCondition;
  /** @deprecated use allowlist */
  whitelist?: number[];
}

interface BetweenCondition {
  start: number;
  stop: number;
}

Generated CloudFormation Resources

The library includes generated CloudFormation resource constructs that provide direct access to CloudFormation properties:

class CfnTopic extends CfnResource {
  /** 
   * Direct CloudFormation AWS::SNS::Topic resource
   * Properties include displayName, topicName, kmsMasterKeyId, 
   * contentBasedDeduplication, fifoTopic, etc.
   */
  constructor(scope: Construct, id: string, props?: CfnTopic.Props);
  readonly ref: string;
  readonly attrTopicName: string;
}

class CfnSubscription extends CfnResource {
  /**
   * Direct CloudFormation AWS::SNS::Subscription resource
   * Properties include endpoint, protocol, topicArn, filterPolicy,
   * rawMessageDelivery, redrivePolicy, etc.
   */
  constructor(scope: Construct, id: string, props: CfnSubscription.Props);
  readonly ref: string;
}

class CfnTopicPolicy extends CfnResource {
  /**
   * Direct CloudFormation AWS::SNS::TopicPolicy resource
   * Properties include policyDocument and topics array
   */
  constructor(scope: Construct, id: string, props: CfnTopicPolicy.Props);
  readonly ref: string;
}

These generated resources are used internally by the higher-level constructs and are typically not used directly in application code unless you need direct access to CloudFormation properties not exposed by the higher-level constructs.