Subscription Management

/**
 * A new subscription to an SNS topic.
 * Prefer to use the ITopic.addSubscription() methods to create instances.
 * @param scope - The scope in which to define this construct
 * @param id - The scoped construct ID
 * @param props - Subscription configuration properties
 */
class Subscription extends Resource {
  constructor(scope: Construct, id: string, props: SubscriptionProps);
  
  /** The DLQ associated with this subscription if present */
  readonly deadLetterQueue?: IQueue;
}

import { Subscription, SubscriptionProtocol } from '@aws-cdk/aws-sns';
import { Queue } from '@aws-cdk/aws-sqs';

// Basic HTTP subscription
new Subscription(this, 'HttpSubscription', {
  topic: myTopic,
  protocol: SubscriptionProtocol.HTTPS,
  endpoint: 'https://api.example.com/webhook'
});

// SQS subscription with dead letter queue
const dlq = new Queue(this, 'DeadLetterQueue');
new Subscription(this, 'SqsSubscription', {
  topic: myTopic,
  protocol: SubscriptionProtocol.SQS,
  endpoint: 'arn:aws:sqs:us-east-1:123456789012:my-queue',
  deadLetterQueue: dlq,
  rawMessageDelivery: true
});

// Lambda subscription with filter policy
new Subscription(this, 'LambdaSubscription', {
  topic: myTopic,
  protocol: SubscriptionProtocol.LAMBDA,
  endpoint: 'arn:aws:lambda:us-east-1:123456789012:function:MyFunction',
  filterPolicy: {
    eventType: SubscriptionFilter.stringFilter({
      allowlist: ['order-created', 'order-updated']
    })
  }
});

/**
 * Properties for creating a new subscription
 */
interface SubscriptionProps extends SubscriptionOptions {
  /** The topic to subscribe to */
  topic: ITopic;
}

/**
 * Options for creating a new subscription
 */
interface SubscriptionOptions {
  /** What type of subscription to add */
  protocol: SubscriptionProtocol;
  
  /** 
   * The subscription endpoint. The meaning of this value depends on the 
   * value for 'protocol'. 
   */
  endpoint: string;
  
  /** 
   * True if raw message delivery is enabled for the subscription. Raw messages 
   * are free of JSON formatting and can be sent to HTTP/S and Amazon SQS endpoints.
   * @default false
   */
  rawMessageDelivery?: boolean;
  
  /** 
   * The filter policy for selective message delivery
   * @default - all messages are delivered
   */
  filterPolicy?: { [attribute: string]: SubscriptionFilter };
  
  /** 
   * The region where the topic resides, in the case of cross-region subscriptions
   * @default - the region where the CloudFormation stack is being deployed
   */
  region?: string;
  
  /** 
   * Queue to be used as dead letter queue. If not passed no dead letter queue is enabled.
   * @default - No dead letter queue enabled
   */
  deadLetterQueue?: IQueue;
  
  /** 
   * Arn of role allowing access to firehose delivery stream.
   * Required for a firehose subscription protocol.
   * @default - No subscription role is provided
   */
  subscriptionRoleArn?: string;
}

/**
 * The type of subscription, controlling the type of the endpoint parameter
 */
enum SubscriptionProtocol {
  /** JSON-encoded message is POSTED to an HTTP url */
  HTTP = 'http',
  
  /** JSON-encoded message is POSTed to an HTTPS url */
  HTTPS = 'https',
  
  /** Notifications are sent via email */
  EMAIL = 'email',
  
  /** Notifications are JSON-encoded and sent via mail */
  EMAIL_JSON = 'email-json',
  
  /** Notification is delivered by SMS */
  SMS = 'sms',
  
  /** Notifications are enqueued into an SQS queue */
  SQS = 'sqs',
  
  /** JSON-encoded notifications are sent to a mobile app endpoint */
  APPLICATION = 'application',
  
  /** Notifications trigger a Lambda function */
  LAMBDA = 'lambda',
  
  /** Notifications put records into a firehose delivery stream */
  FIREHOSE = 'firehose'
}

/**
 * Topic subscription interface
 */
interface ITopicSubscription {
  /**
   * Returns a configuration used to subscribe to an SNS topic
   * @param topic - Topic for which subscription will be configured
   */
  bind(topic: ITopic): TopicSubscriptionConfig;
}

/**
 * Subscription configuration returned by bind()
 */
interface TopicSubscriptionConfig extends SubscriptionOptions {
  /** 
   * The scope in which to create the SNS subscription resource. Normally you'd
   * want the subscription to be created on the consuming stack because the
   * topic is usually referenced by the consumer's resource policy.
   * @default - use the topic as the scope of the subscription
   */
  subscriberScope?: Construct;
  
  /** 
   * The id of the SNS subscription resource created under scope. In most
   * cases, it is recommended to use the uniqueId of the topic you are
   * subscribing to.
   */
  subscriberId: string;
}

import { Subscription, SubscriptionProtocol } from '@aws-cdk/aws-sns';

// HTTP endpoint
new Subscription(this, 'HttpEndpoint', {
  topic: topic,
  protocol: SubscriptionProtocol.HTTP,
  endpoint: 'http://api.internal.com/webhook'
});

// HTTPS endpoint with raw message delivery
new Subscription(this, 'HttpsEndpoint', {
  topic: topic,
  protocol: SubscriptionProtocol.HTTPS,
  endpoint: 'https://api.example.com/sns-webhook',
  rawMessageDelivery: true
});

import { Queue } from '@aws-cdk/aws-sqs';

const queue = new Queue(this, 'TargetQueue');
const dlq = new Queue(this, 'DeadLetterQueue', {
  retentionPeriod: Duration.days(14)
});

new Subscription(this, 'SqsSubscription', {
  topic: topic,
  protocol: SubscriptionProtocol.SQS,
  endpoint: queue.queueArn,
  rawMessageDelivery: true,
  deadLetterQueue: dlq
});

import { Function } from '@aws-cdk/aws-lambda';

const handler = new Function(this, 'Handler', {
  // ... lambda configuration
});

new Subscription(this, 'LambdaSubscription', {
  topic: topic,
  protocol: SubscriptionProtocol.LAMBDA,
  endpoint: handler.functionArn
});

// Plain text email
new Subscription(this, 'EmailSubscription', {
  topic: topic,
  protocol: SubscriptionProtocol.EMAIL,
  endpoint: 'notifications@example.com'
});

// JSON-formatted email
new Subscription(this, 'JsonEmailSubscription', {
  topic: topic,
  protocol: SubscriptionProtocol.EMAIL_JSON,
  endpoint: 'admin@example.com'
});

new Subscription(this, 'SmsSubscription', {
  topic: topic,
  protocol: SubscriptionProtocol.SMS,
  endpoint: '+1234567890'
});

new Subscription(this, 'FirehoseSubscription', {
  topic: topic,
  protocol: SubscriptionProtocol.FIREHOSE,
  endpoint: 'arn:aws:firehose:us-east-1:123456789012:deliverystream/my-stream',
  subscriptionRoleArn: 'arn:aws:iam::123456789012:role/firehose-delivery-role'
});

import { Queue } from '@aws-cdk/aws-sqs';
import { Duration } from '@aws-cdk/core';

const dlq = new Queue(this, 'SubscriptionDLQ', {
  queueName: 'MySubscription_DLQ',
  retentionPeriod: Duration.days(14)
});

new Subscription(this, 'SubscriptionWithDLQ', {
  topic: topic,
  protocol: SubscriptionProtocol.LAMBDA,
  endpoint: myFunction.functionArn,
  deadLetterQueue: dlq
});

new Subscription(this, 'CrossRegionSubscription', {
  topic: topic,
  protocol: SubscriptionProtocol.SQS,
  endpoint: 'arn:aws:sqs:eu-west-1:123456789012:my-queue',
  region: 'eu-west-1'
});

// This is the recommended approach
topic.addSubscription(new subscriptions.SqsSubscription(queue, {
  rawMessageDelivery: true,
  filterPolicy: {
    eventType: sns.SubscriptionFilter.stringFilter({
      allowlist: ['important']
    })
  }
}));