Topic Management

/**
 * Creates a new SNS topic
 * @param scope - The scope in which to define this construct
 * @param id - The scoped construct ID
 * @param props - Topic configuration properties
 */
class Topic extends TopicBase {
  constructor(scope: Construct, id: string, props?: TopicProps);
  
  readonly topicArn: string;
  readonly topicName: string;
  readonly fifo: boolean;
  protected readonly autoCreatePolicy: boolean;
}

import { Topic } from '@aws-cdk/aws-sns';
import { Key } from '@aws-cdk/aws-kms';
import { Stack } from '@aws-cdk/core';

// Basic topic
const basicTopic = new Topic(this, 'BasicTopic');

// Topic with display name
const namedTopic = new Topic(this, 'NamedTopic', {
  displayName: 'Customer Notifications'
});

// Encrypted topic
const encryptedTopic = new Topic(this, 'EncryptedTopic', {
  displayName: 'Secure Messages',
  masterKey: new Key(this, 'TopicKey')
});

// FIFO topic with content-based deduplication
const fifoTopic = new Topic(this, 'FifoTopic', {
  fifo: true,
  contentBasedDeduplication: true,
  topicName: 'my-ordered-messages',
  displayName: 'Ordered Message Processing'
});

/**
 * Properties for creating a new SNS topic
 */
interface TopicProps {
  /** A developer-defined string that can be used to identify this SNS topic */
  displayName?: string;
  
  /** 
   * A name for the topic. If you don't specify a name, AWS CloudFormation 
   * generates a unique physical ID and uses that ID for the topic name.
   * For FIFO topics, the .fifo suffix is automatically added if not present.
   */
  topicName?: string;
  
  /** A KMS Key for encrypting messages stored in the topic */
  masterKey?: IKey;
  
  /** 
   * Enables content-based deduplication for FIFO topics.
   * Can only be used with FIFO topics.
   */
  contentBasedDeduplication?: boolean;
  
  /** 
   * Set to true to create a FIFO topic.
   * FIFO topics require a topic name to be specified.
   */
  fifo?: boolean;
}

/**
 * Import an existing SNS topic provided an ARN
 * @param scope - The parent creating construct
 * @param id - The construct's name
 * @param topicArn - Topic ARN (e.g., arn:aws:sns:us-east-2:444455556666:MyTopic)
 * @returns ITopic interface for the imported topic
 */
static fromTopicArn(scope: Construct, id: string, topicArn: string): ITopic;

import { Topic } from '@aws-cdk/aws-sns';

// Import existing topic
const existingTopic = Topic.fromTopicArn(
  this, 
  'ImportedTopic', 
  'arn:aws:sns:us-east-1:123456789012:MyExistingTopic'
);

// Use imported topic (read-only operations)
existingTopic.grantPublish(myLambdaFunction);

/**
 * Represents an SNS topic
 */
interface ITopic extends IResource, notifications.INotificationRuleTarget {
  /** The ARN of the topic */
  readonly topicArn: string;
  
  /** The name of the topic */
  readonly topicName: string;
  
  /** Whether this topic is an Amazon SNS FIFO queue. If false, this is a standard topic */
  readonly fifo: boolean;
  
  /** Subscribe some endpoint to this topic */
  addSubscription(subscription: ITopicSubscription): void;
  
  /** 
   * Adds a statement to the IAM resource policy associated with this topic.
   * If this topic was created in this stack, a topic policy will be automatically 
   * created upon the first call to addToResourcePolicy. If the topic is imported, 
   * then this is a no-op.
   */
  addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
  
  /** Grant topic publishing permissions to the given identity */
  grantPublish(identity: iam.IGrantable): iam.Grant;
}

/**
 * Base class for SNS topics providing common functionality
 */
abstract class TopicBase extends Resource implements ITopic {
  abstract readonly topicArn: string;
  abstract readonly topicName: string;
  abstract readonly fifo: boolean;
  protected abstract readonly autoCreatePolicy: boolean;
  
  /** Subscribe some endpoint to this topic */
  addSubscription(subscription: ITopicSubscription): void;
  
  /** Adds a statement to the IAM resource policy associated with this topic */
  addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
  
  /** Grant topic publishing permissions to the given identity */
  grantPublish(grantee: iam.IGrantable): iam.Grant;
  
  /** 
   * Represents a notification target that allows SNS topic to associate 
   * with CloudWatch Events rule target 
   */
  bindAsNotificationRuleTarget(scope: constructs.Construct): notifications.NotificationRuleTargetConfig;
}

import { Key } from '@aws-cdk/aws-kms';

const key = new Key(this, 'TopicKey', {
  description: 'Key for SNS topic encryption'
});

const encryptedTopic = new Topic(this, 'EncryptedTopic', {
  masterKey: key,
  displayName: 'Encrypted Notifications'
});

import { Role, ServicePrincipal } from '@aws-cdk/aws-iam';

const role = new Role(this, 'PublisherRole', {
  assumedBy: new ServicePrincipal('lambda.amazonaws.com')
});

// Grant publish permissions
topic.grantPublish(role);

// Add custom policy statement
topic.addToResourcePolicy(new iam.PolicyStatement({
  actions: ['sns:Subscribe'],
  principals: [new iam.AccountRootPrincipal()],
  resources: [topic.topicArn]
}));

import * as events from '@aws-cdk/aws-events';
import * as targets from '@aws-cdk/aws-events-targets';

const rule = new events.Rule(this, 'MyRule', {
  eventPattern: {
    source: ['aws.ec2']
  }
});

rule.addTarget(new targets.SnsTopic(topic));

// FIFO topic configuration
const fifoTopic = new Topic(this, 'OrderedMessages', {
  fifo: true,
  topicName: 'order-processing', // Becomes 'order-processing.fifo'
  contentBasedDeduplication: true,
  displayName: 'Order Processing Queue'
});