Fjall Docs — deploy AWS infrastructure into your own account

Overview

The SNSTopic construct creates an Amazon SNS topic for pub/sub messaging. One publish call fans the message out to every subscriber (Lambda, SQS, HTTPS endpoints, email). Fjall applies two defaults on top of the CDK topic: TLS-only access (enforceSSL) and signature version 2 (SHA-256).

Prerequisites

A Fjall application with an infrastructure.ts file.
@fjall/components-infrastructure installed in that application.

fjall add messaging scaffolds an SQS queue, not a topic. Add SNS topics by editing infrastructure.ts directly.

Import

import { MessagingFactory, SNSTopic } from "@fjall/components-infrastructure";

Add a topic

Use the MessagingFactory and app.addMessaging(). The topic lands in the application’s messaging stack.

const alerts = app.addMessaging(
  MessagingFactory.build("Alerts", {
    type: "topic",
    displayName: "Alert Notifications",
  }),
);

To place the construct yourself, instantiate it directly against a stack scope:

const topic = new SNSTopic(
  app.getDefaultMessagingStack().getStack(),
  "Alerts",
  {
    displayName: "Alert Notifications",
  },
);

Properties

Property	Type	Default	Description
`topicName`	`string`	Auto-generated	Topic name. Fjall appends `.fifo` when `fifo` is `true`
`displayName`	`string`	None	Human-readable name, used as the sender label for SMS subscriptions
`fifo`	`boolean`	`false`	Create a FIFO topic (strict ordering)
`contentBasedDeduplication`	`boolean`	`true` on FIFO	Content-based deduplication. FIFO only, ignored with a warning on standard topics
`signatureVersion`	`"1" \| "2"`	`"2"`	Message signature version. `"2"` is SHA-256, `"1"` is the deprecated SHA-1
`masterKey`	`IKey`	None	KMS customer-managed key for encryption at rest. Absent means the backup tier and `encryption` decide, see Encryption at rest
`removalPolicy`	`"DESTROY" \| "RETAIN"`	`"DESTROY"`	What happens on stack deletion

removalPolicy defaults to DESTROY in every environment, including production. This is deliberate: a topic holds no durable state, and subscriptions are re-created by the next deploy. Retaining one orphans it when a parent construct’s logical ID changes. Pass removalPolicy: "RETAIN" only for a topic that must survive stack deletion.

Methods

Method	Returns	Description
`getTopicArn()`	`string`	Topic ARN
`getTopicName()`	`string`	Topic name
`getTopic()`	`ITopic`	Underlying CDK Topic construct
`grantPublish(grantee)`	`Grant`	Grant permission to publish messages
`grantSubscribe(grantee)`	`Grant`	Grant permission to subscribe to the topic

grantPublish and grantSubscribe accept any CDK IGrantable, such as a Fjall LambdaFunction or an IAM role.

Examples

Standard topic

const notifications = app.addMessaging(
  MessagingFactory.build("Notifications", {
    type: "topic",
    displayName: "Order Notifications",
  }),
);

notifications.grantPublish(apiFunction);

FIFO topic

FIFO topics deliver messages in order and support deduplication. Fjall appends the required .fifo suffix to topicName, so the topic below deploys as order-events.fifo.

const events = app.addMessaging(
  MessagingFactory.build("Events", {
    type: "topic",
    topicName: "order-events",
    fifo: true,
    contentBasedDeduplication: true,
  }),
);

Encryption at rest

The application’s backup tier decides: at enterprise a topic is encrypted with the stack’s shared customer-managed key; at standard and resilient it is unencrypted, and Fjall reports it as an SNS_TOPIC_NOT_ENCRYPTED posture finding rather than pre-paying for a key you may not want. encryption: "SSE_KMS" opts one topic into the shared key at any tier and encryption: "NONE" is the auditable opt-out at enterprise; the finding names whichever applies. masterKey brings your own key and wins over both.

const orders = app.addMessaging(
  MessagingFactory.build("Orders", {
    type: "topic",
    encryption: "SSE_KMS",
  }),
);

To encrypt with a key you manage yourself:

import { CustomerManagedKey } from "@fjall/components-infrastructure/lib/resources/aws/secrets/kms";

const topicKey = new CustomerManagedKey(
  app.getDefaultMessagingStack().getStack(),
  "OrdersTopicKey",
  {
    protects: "stack-scoped",
    description: "Encrypts the order events topic",
  },
);

const orders = app.addMessaging(
  MessagingFactory.build("Orders", {
    type: "topic",
    masterKey: topicKey.key,
  }),
);

Fan-out to multiple queues

Combine SNS with SQS to give each consumer its own buffered copy of the event.

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

const orderTopic = app.addMessaging(
  MessagingFactory.build("OrderEvents", {
    type: "topic",
  }),
);

const billingQueue = app.addMessaging(
  MessagingFactory.build("Billing", {
    type: "queue",
  }),
);

const shippingQueue = app.addMessaging(
  MessagingFactory.build("Shipping", {
    type: "queue",
  }),
);

orderTopic
  .getTopic()
  .addSubscription(new SqsSubscription(billingQueue.getQueue()));
orderTopic
  .getTopic()
  .addSubscription(new SqsSubscription(shippingQueue.getQueue()));

Each SqsSubscription adds one statement to the queue’s resource policy, not the topic’s. SQS caps that policy at 20 statements and 8,192 bytes, and a Fjall queue’s TLS-only deny counts towards both. The byte cap binds first on a queue whose name CloudFormation generates, so a queue with no other grants carries 18 subscriptions. From fjall 38 a Fjall SQSQueue, which is what type: "queue" builds above, checks its own policy when the application synthesises and refuses an over-budget one before the deploy. A queue you build straight from aws-cdk-lib carries no such check, so its over-budget policy fails mid-deploy and rolls the stack back. Split the subscriptions across queues when one queue subscribes to many topics. See Queue-policy limits.

Gotchas

AWS service publishers need an explicit Allow

The TLS-only default synthesises an AWS::SNS::TopicPolicy, and that resource replaces the topic’s implicit default policy. Any AWS service principal that published under the default Allow, CloudWatch alarms being the common case, stops publishing until you merge an explicit Allow back in. Same-account IAM publishers are unaffected, because their identity policies suffice.

import { PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
import { Stack } from "aws-cdk-lib";

const stack = Stack.of(alerts);

alerts.getTopic().addToResourcePolicy(
  new PolicyStatement({
    principals: [new ServicePrincipal("cloudwatch.amazonaws.com")],
    actions: ["sns:Publish"],
    resources: [alerts.getTopicArn()],
    conditions: {
      StringEquals: { "aws:SourceAccount": stack.account },
      ArnLike: {
        "aws:SourceArn": `arn:${stack.partition}:cloudwatch:${stack.region}:${stack.account}:alarm:*`,
      },
    },
  }),
);

An encrypted topic needs key-policy grants too

A service principal publishing to an encrypted topic also needs kms:Decrypt and kms:GenerateDataKey* on the key’s resource policy, or its publishes fail silently. The AWS-managed aws/sns key cannot serve service publishers, because its policy is immutable. Use a CustomerManagedKey and call key.addToResourcePolicy(...).

Signature version

Fjall sets signatureVersion: "2" (SHA-256). The AWS account-level default is "1" (SHA-1), which signature-verifying HTTPS subscribers reject, leaving their subscriptions stuck in PendingConfirmation. Pass signatureVersion: "1" only for a legacy consumer that cannot verify SHA-256.

FIFO-only options

contentBasedDeduplication applies to FIFO topics only. Setting it on a standard topic logs a warning at synth time and has no effect.

CloudFormation Outputs

Output	Description
`{id}TopicArn`	Topic ARN
`{id}TopicName`	Topic name

Next Steps

Messaging Factory

Create queues, topics, and event buses via the factory

SQS Queue

Buffer each fan-out consumer with its own queue

EventBridge Bus

Route events by pattern instead of by subscription

KMS Key

Provision the customer-managed key that encrypts a topic

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

SNS Topic

Overview

Prerequisites

Import

Add a topic

Properties

Methods

Examples

Standard topic

FIFO topic

Encryption at rest

Fan-out to multiple queues

Gotchas

AWS service publishers need an explicit Allow

An encrypted topic needs key-policy grants too

Signature version

FIFO-only options

CloudFormation Outputs

Next Steps

Messaging Factory

SQS Queue

EventBridge Bus

KMS Key

​Overview

​Prerequisites

​Import

​Add a topic

​Properties

​Methods

​Examples

​Standard topic

​FIFO topic

​Encryption at rest

​Fan-out to multiple queues

​Gotchas

​AWS service publishers need an explicit Allow

​An encrypted topic needs key-policy grants too

​Signature version

​FIFO-only options

​CloudFormation Outputs

​Next Steps

Messaging Factory

SQS Queue

EventBridge Bus

KMS Key

Overview

Prerequisites

Import

Add a topic

Properties

Methods

Examples

Standard topic

FIFO topic

Encryption at rest

Fan-out to multiple queues

Gotchas

AWS service publishers need an explicit Allow

An encrypted topic needs key-policy grants too

Signature version

FIFO-only options

CloudFormation Outputs

Next Steps