Fjall Docs — deploy AWS infrastructure into your own account

Overview

MessagingFactory creates event-driven AWS resources: SQS queues, SNS topics, and EventBridge event buses. These resources decouple application components for asynchronous work.

Queues and topics default to removalPolicy: "DESTROY". A stack deletion removes them along with any in-flight messages. Set removalPolicy: "RETAIN" on anything whose contents are irreplaceable. See Removal policies.

Basic Usage

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

const app = App.getApp("api");

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

Messaging Types

SQS Queue (Standard)

Standard queues for high-throughput messaging:

const queue = app.addMessaging(
  MessagingFactory.build("WorkerQueue", {
    type: "queue",
    queueType: "standard",
    visibilityTimeout: 30,
    messageRetentionPeriod: 1209600, // 14 days
  }),
);

Features:

Nearly unlimited throughput
At-least-once delivery
Best-effort ordering
Suited to background job processing

SQS Queue (FIFO)

FIFO queues for ordered, exactly-once processing:

const queue = app.addMessaging(
  MessagingFactory.build("OrderQueue", {
    type: "queue",
    queueType: "fifo",
    contentBasedDeduplication: true,
  }),
);

Features:

Exactly-once processing
First-in-first-out ordering
Message deduplication (on by default for FIFO queues)
Suited to ordered workflows

contentBasedDeduplication, fifoThroughputLimit and deduplicationScope apply to FIFO queues only. On a standard queue they are ignored and the synth logs a warning.

Dead Letter Queue

Capture failed messages for analysis:

const mainQueue = app.addMessaging(
  MessagingFactory.build("ProcessingQueue", {
    type: "queue",
    deadLetterQueue: {
      enabled: true,
      maxReceiveCount: 3, // Move to DLQ after 3 failures
    },
    alertsTopic: "import:SharedAlarmTopicArn",
  }),
);

Fjall creates the dead-letter queue with a 14-day retention period and the same removal policy as its parent queue. maxReceiveCount defaults to 3. Supply alertsTopic to arm a CloudWatch alarm that fires when the dead-letter queue holds any visible message. Without it, dead-lettered messages age out silently after 14 days. Publish-subscribe messaging for fan-out:

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

Features:

Fan-out to multiple subscribers
Push-based delivery
Multiple subscriber types (SQS, Lambda, HTTP, email)
Message filtering

Fjall attaches a TLS-only resource policy to every topic, and that policy replaces SNS’s implicit default policy. AWS service principals that publish to the topic (CloudWatch, S3, EventBridge) need an explicit allow merged in via topic.getTopic().addToResourcePolicy(...). Same-account IAM publishers are unaffected.

EventBridge Event Bus

Custom event bus for event-driven architectures:

const eventBus = app.addMessaging(
  MessagingFactory.build("AppEvents", {
    type: "eventBus",
  }),
);

Features:

Rule-based routing on event patterns
Targets across queues, Lambda, ECS, CodeBuild and log groups
Per-subscription dead-letter queues and retry policies
Cross-account and cross-region buses via ARN import

Every application also has a lazily created default bus. app.getEventBus() returns it and names it after the application.

Removal policies

Resource	Default removal policy
SQS queue (and its auto-created DLQ)	`"DESTROY"`
SNS topic	`"DESTROY"`
EventBridge event bus	`"RETAIN"` in production, `"DESTROY"` in every other stage

Queues and topics are treated as transient mediums, so they default to "DESTROY". Opt a durable queue or topic into "RETAIN" explicitly. The event bus default resolves from the deploy environment. Fjall passes the target account’s stage into synth, and an unrecognised value fails the synth rather than falling back to "DESTROY". Pass an explicit removalPolicy to sidestep the resolution entirely.

Configuration Parameters

Queue Parameters

Parameter	Type	Description	Default
`type`	`"queue"`	Resource type	Required
`queueType`	`"standard" \| "fifo"`	Queue ordering mode	`"standard"`
`visibilityTimeout`	`number`	Seconds a message stays hidden after receive (0 to 43200)	`30`
`messageRetentionPeriod`	`number`	Seconds to retain messages (60 to 1209600)	`345600` (4 days)
`maxMessageSize`	`number`	Maximum message size in bytes (1 to 262144)	`262144` (256 KB)
`receiveMessageWaitTime`	`number`	Long-poll wait in seconds (0 to 20)	`0`
`deliveryDelay`	`number`	Seconds before a message becomes visible (0 to 900)	`0`
`deadLetterQueue`	`{ enabled: boolean; maxReceiveCount?: number }`	Dead-letter queue configuration	Disabled
`contentBasedDeduplication`	`boolean`	FIFO only. Deduplicate on the message body	`true` on FIFO
`fifoThroughputLimit`	`"perQueue" \| "perMessageGroupId"`	FIFO only. High-throughput mode	AWS default
`deduplicationScope`	`"queue" \| "messageGroup"`	FIFO only. Pair with `fifoThroughputLimit` for high throughput	AWS default
`encryption`	`"SSE_SQS" \| "SSE_KMS" \| "NONE"`	Encryption at rest	`"SSE_SQS"`
`kmsKeyArn`	`string`	Accepted but not applied. `"SSE_KMS"` provisions a dedicated KMS key	-
`alertsTopic`	`ITopic \| string`	DLQ-depth alarm target. Takes a topic, an ARN, or `"import:ExportName"`	-
`alarms`	`SqsAlarmThresholds \| false`	Alarm thresholds, or `false` to disable	Defaults
`applicationId`	`string`	Application id used to tag alarms	Application name
`removalPolicy`	`"DESTROY" \| "RETAIN"`	What happens on stack delete	`"DESTROY"`

Queues are created with enforceSSL, so every request must use TLS. That TLS deny is a statement in the queue’s resource policy, and from fjall 38 the policy is checked at synthesis: Fjall refuses a queue policy over 20 statements, or one that may reach more than 8,192 bytes, naming the queue. See Queue-policy limits.

Topic Parameters

Parameter	Type	Description	Default
`type`	`"topic"`	Resource type	Required
`topicName`	`string`	Custom topic name. FIFO topics gain a `.fifo` suffix automatically	Auto-generated
`displayName`	`string`	Display name used for SMS deliveries	-
`fifo`	`boolean`	Create a FIFO topic	`false`
`contentBasedDeduplication`	`boolean`	FIFO only. Deduplicate on the message body	`true` on FIFO
`masterKey`	`IKey`	KMS key for encryption at rest. Omit it and the topic is unencrypted	-
`signatureVersion`	`"1" \| "2"`	SNS message signature version. `"2"` is SHA-256	`"2"`
`removalPolicy`	`"DESTROY" \| "RETAIN"`	What happens on stack delete	`"DESTROY"`

Topics are unencrypted at rest unless you pass masterKey. A customer-managed key costs roughly

1 to

3 per month per account and region, so Fjall leaves the choice to you. Every AWS service principal that publishes to an encrypted topic needs kms:Decrypt and kms:GenerateDataKey* on that key’s resource policy.

Event Bus Parameters

Parameter	Type	Description	Default
`type`	`"eventBus"`	Resource type	Required
`eventBusName`	`string`	Custom event bus name	Auto-generated
`description`	`string`	Bus description	Generated from the application name
`appName`	`string`	Application name used in default bus and subscription descriptions	Application name
`removalPolicy`	`"DESTROY" \| "RETAIN"`	What happens on stack delete	`"RETAIN"` in production, else `"DESTROY"`

Subscriptions

Call subscribe(id, props) on an event bus to route matching events to a target. Each subscription synthesises an EventBridge rule scoped to that bus.

Subscription Options

Option	Type	Description	Default
`pattern`	`EventPattern`	EventBridge event pattern	Required
`target`	Queue, Lambda compute, ECS task, CodeBuild project, or log group	What receives matching events	Required
`messageGroupId`	`string`	Required when the target is a FIFO queue. Rejected for other targets	-
`payload`	`Record<string, unknown>`	Replaces the delivered event detail. Rejected for ECS and log-group targets	Full matched event
`deadLetterQueue`	`{ enabled: true; queue?: SQSQueue } \| { enabled: false } \| SQSQueue`	Capture failed deliveries	Disabled
`retryPolicy`	`EventBridgeRetryPolicy`	Delivery retry budget	AWS defaults (24h, 185 tries)
`enabled`	`boolean`	Whether the underlying rule is active	`true`
`description`	`string`	Rule description	Generated from the application name
`alertsTopic`	`ITopic`	SNS topic for subscription alarms	-
`alarms`	`boolean`	Suppress alarms even when `alertsTopic` is set	`true` when `alertsTopic` set

EventPattern and the EventField / RuleTargetInput helpers are re-exported from @fjall/components-infrastructure. An ECS target takes the shape { ecs: ecsCompute, serviceName: "worker", taskCount?: 1 } rather than the compute wrapper on its own.

Subscribing to AWS Service Events

AWS service events (aws.ecr, aws.ec2, aws.ecs) fire only on the account and region default bus. Subscribing an aws.* source on a custom application bus deploys cleanly and never invokes the target, so subscribe() rejects it with an error. Import the default bus instead:

import { EventBusMessaging } from "@fjall/components-infrastructure";

const defaultBus = EventBusMessaging.fromAwsServiceBus(
  scope,
  "AwsServiceBus",
  "eu-west-1",
  "123456789012",
);

defaultBus.subscribe("EcrPushes", {
  pattern: {
    source: ["aws.ecr"],
    detailType: ["ECR Image Action"],
  },
  target: buildQueue,
});

Importing an Existing Bus

Wrap a bus owned by another account or region by ARN. The importing stack owns the rules, and no new AWS::Events::EventBus is synthesised:

const sharedBus = EventBusMessaging.fromEventBusArn(
  scope,
  "SharedBus",
  "arn:aws:events:eu-west-1:123456789012:event-bus/platform",
);

sharedBus.subscribe("PlatformAudit", {
  pattern: { source: ["platform.audit"] },
  target: auditQueue,
});

Common Patterns

Background Job Processing

connections grants IAM permissions. It does not create the Lambda trigger, so add the SQS event source explicitly:

import {
  ComputeFactory,
  MessagingFactory,
} from "@fjall/components-infrastructure";
import { Code } from "aws-cdk-lib/aws-lambda";

const jobQueue = app.addMessaging(
  MessagingFactory.build("JobQueue", {
    type: "queue",
    visibilityTimeout: 300, // 5 min for long jobs
    deadLetterQueue: { enabled: true, maxReceiveCount: 3 },
  }),
);

const worker = app.addCompute(
  ComputeFactory.build("Worker", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("lambda/worker"),
    handler: "worker.handler",
    timeout: 300,
    connections: [jobQueue],
  }),
);

worker.getLambdaFunction().addSqsEventSource(jobQueue.getQueue(), {
  batchSize: 10,
  reportBatchItemFailures: true,
});

A Lambda with connections needs a VPC. ComputeFactory injects app.getVpc() automatically when the props carry connections, so no extra wiring is required.

Event Fan-Out

Route matching events to multiple targets with an EventBridge event bus:

// Central event bus
const orderBus = app.addMessaging(
  MessagingFactory.build("OrderEvents", {
    type: "eventBus",
  }),
);

// Subscriber queues
const inventoryQueue = app.addMessaging(
  MessagingFactory.build("InventoryQueue", { type: "queue" }),
);

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

// Subscribe each queue to the bus with an event pattern
orderBus.subscribe("InventorySub", {
  pattern: { source: ["app.orders"], detailType: ["OrderPlaced"] },
  target: inventoryQueue,
});

orderBus.subscribe("NotificationSub", {
  pattern: { source: ["app.orders"], detailType: ["OrderPlaced"] },
  target: notificationQueue,
});

SNS topics support fan-out through publish/subscribe, but MessagingFactory topics expose no wrapper subscription method. Use an EventBridge event bus for declarative fan-out, or attach SNS subscriptions to the underlying CDK construct via topic.getTopic().

ISR Revalidation Queue (OpenNext)

const revalidationQueue = app.addMessaging(
  MessagingFactory.build("RevalidationQueue", {
    type: "queue",
    queueType: "fifo",
    contentBasedDeduplication: true,
    visibilityTimeout: 30,
  }),
);

Connecting to Compute

Access Levels

connections accepts a queue directly, or a { resource, access } pair:

Access	Grants
`"send"`	`sqs:SendMessage`
`"consume"`	Receive and delete
`"full"`	Send, receive and delete

A bare queue in connections defaults to "full".

ECS with Queue Access

connections lives on each service entry, not on the compute root:

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

app.addCompute(
  ComputeFactory.build("Worker", {
    type: "ecs",
    cluster: { loadBalancer: false },
    services: [
      {
        name: "worker",
        serviceType: "worker",
        capacityProvider: "FARGATE",
        containers: [
          {
            environment: {
              QUEUE_URL: queue.getQueueUrl(),
            },
          },
        ],
        connections: [{ resource: queue, access: "consume" }],
      },
    ],
  }),
);

Scoping connections to the service keeps the grant least-privilege. Other services in the same cluster get no queue access.

Access Grants

Queue Permissions

// Send only
queue.grantSendMessages(producer);

// Receive and delete
queue.grantConsumeMessages(consumer);

// Purge the queue
queue.grantPurge(admin);

// Send and consume in one call
queue.grantFull(worker);

// Arbitrary SQS actions
queue.grant(auditor, "sqs:GetQueueAttributes");

Topic Permissions

// Publish
topic.grantPublish(publisher);

// Subscribe (for service principals)
topic.grantSubscribe(subscriber);

Event Bus Permissions

// Put events onto the bus
eventBus.grantPutEventsTo(orderService);

Best Practices

Set removalPolicy: "RETAIN" on any queue or topic whose contents cannot be regenerated
Configure a DLQ on every production queue and point alertsTopic at your alarm topic
Use FIFO queues when order matters, and pass messageGroupId on FIFO subscriptions
Set visibilityTimeout to at least the consumer’s processing time
Use EventBridge for pattern-based routing and SNS for simple broadcast
Import the default bus with fromAwsServiceBus for any aws.* event source
Make consumers idempotent. EventBridge and standard SQS both deliver at least once

Next Steps

Compute Factory

Process messages with Lambda or ECS.

SQS Queue Resource

Configure queues at the resource level.

EventBridge Resource

Build rules, schedules, and subscriptions.

Payload Pattern

See messaging in a full OpenNext application.

Factory Patterns

Application Patterns

Architecture Patterns

Messaging Factory

Overview

Basic Usage

Messaging Types

SQS Queue (Standard)

SQS Queue (FIFO)

Dead Letter Queue

EventBridge Event Bus

Removal policies

Configuration Parameters

Queue Parameters

Topic Parameters

Event Bus Parameters

Subscriptions

Subscription Options

Subscribing to AWS Service Events

Importing an Existing Bus

Common Patterns

Background Job Processing

Event Fan-Out

ISR Revalidation Queue (OpenNext)

Connecting to Compute

Access Levels

ECS with Queue Access

Access Grants

Queue Permissions

Topic Permissions

Event Bus Permissions

Best Practices

Next Steps

Compute Factory

SQS Queue Resource

EventBridge Resource

Payload Pattern

​Overview

​Basic Usage

​Messaging Types

​SQS Queue (Standard)

​SQS Queue (FIFO)

​Dead Letter Queue

​SNS Topic

​EventBridge Event Bus

​Removal policies

​Configuration Parameters

​Queue Parameters

​Topic Parameters

​Event Bus Parameters

​Subscriptions

​Subscription Options

​Subscribing to AWS Service Events

​Importing an Existing Bus

​Common Patterns

​Background Job Processing

​Event Fan-Out

​ISR Revalidation Queue (OpenNext)

​Connecting to Compute

​Access Levels

​ECS with Queue Access

​Access Grants

​Queue Permissions

​Topic Permissions

​Event Bus Permissions

​Best Practices

​Next Steps

Compute Factory

SQS Queue Resource

EventBridge Resource

Payload Pattern

Overview

Basic Usage

Messaging Types

SQS Queue (Standard)

SQS Queue (FIFO)

Dead Letter Queue

SNS Topic

EventBridge Event Bus

Removal policies

Configuration Parameters

Queue Parameters

Topic Parameters

Event Bus Parameters

Subscriptions

Subscription Options

Subscribing to AWS Service Events

Importing an Existing Bus

Common Patterns

Background Job Processing

Event Fan-Out

ISR Revalidation Queue (OpenNext)

Connecting to Compute

Access Levels

ECS with Queue Access

Access Grants

Queue Permissions

Topic Permissions

Event Bus Permissions

Best Practices

Next Steps