Fjall Docs — deploy AWS infrastructure into your own account

Overview

The SQSQueue construct creates an Amazon SQS queue with an optional dead-letter queue, FIFO ordering, encryption, and a DLQ-depth CloudWatch alarm. Use it to decouple producers and consumers in event-driven architectures. Every queue is created with enforceSSL: true, so the queue policy denies any request that does not arrive over TLS.

Import

import { SQSQueue } from "@fjall/components-infrastructure/lib/resources/aws/messaging/sqs";

Add a queue from the CLI

fjall add messaging writes the queue into your application’s infrastructure.ts:

fjall add messaging -a api --name OrdersQueue --queueType standard

The codemod always emits type: "queue", so the statement it writes is a valid MessagingFactory call. Modify an existing queue by name:

fjall modify messaging -a api --name OrdersQueue --retentionPeriod 1209600

The CLI property vocabulary is narrower than the construct’s, and one flag is spelled differently:

CLI flag	Construct prop
`--name`	Construct id
`--queueType`	`queueType`
`--visibilityTimeout`	`visibilityTimeout`
`--retentionPeriod`	`messageRetentionPeriod`
`--contentBasedDeduplication`	`contentBasedDeduplication`
`--removalPolicy`	`removalPolicy`

Every other property in the tables below is authored by hand in infrastructure.ts.

Using the Messaging Factory

Inside infrastructure.ts, add SQS through the MessagingFactory:

import { MessagingFactory } from "@fjall/components-infrastructure/lib/patterns/aws/messaging";

const notifications = app.addMessaging(
  MessagingFactory.build("Notifications", {
    type: "queue",
    queueType: "standard",
    deadLetterQueue: { enabled: true, maxReceiveCount: 3 },
  }),
);

Direct construct usage

const queue = new SQSQueue(scope, "Notifications", {});

Properties

Property	Type	Default	Description
`queueName`	`string`	Auto-generated	Queue name. FIFO queues get a `.fifo` suffix automatically
`queueType`	`"standard" \| "fifo"`	`"standard"`	Queue type
`visibilityTimeout`	`number`	`30`	Seconds a message is hidden after being read (0-43200)
`messageRetentionPeriod`	`number`	`345600` (4 days)	Seconds to retain messages (60-1209600)
`receiveMessageWaitTime`	`number`	`0`	Long polling wait time in seconds (0-20)
`maxMessageSize`	`number`	`262144`	Maximum message size in bytes (1-262144)
`deliveryDelay`	`number`	`0`	Delay before a message becomes visible in seconds (0-900)
`deadLetterQueue.enabled`	`boolean`	`false`	Attach a dead-letter queue
`deadLetterQueue.maxReceiveCount`	`number`	`3`	Failed deliveries before moving to the DLQ (1-1000)
`deadLetterQueue.queue`	`IQueue`	Auto-created	Bring your own DLQ instead of letting Fjall create one
`encryption`	`"SSE_SQS" \| "SSE_KMS" \| "NONE"`	`"SSE_SQS"`	Encryption type
`kmsKeyArn`	`string`	None	Accepted but not wired. See the encryption warning below
`contentBasedDeduplication`	`boolean`	`true` (FIFO)	Content-based deduplication. FIFO only, ignored on standard queues
`fifoThroughputLimit`	`"perQueue" \| "perMessageGroupId"`	`"perQueue"`	FIFO throughput limit
`deduplicationScope`	`"queue" \| "messageGroup"`	`"queue"`	FIFO deduplication scope
`removalPolicy`	`"DESTROY" \| "RETAIN"`	`"DESTROY"`	What happens on stack deletion
`alertsTopic`	`ITopic`	None	SNS topic for the DLQ-depth alarm
`alarms`	`SqsAlarmThresholds \| false`	Defaults	Alarm thresholds. `false` disables the alarm
`applicationId`	`string`	Application name (factory)	Application id used to tag the alarms

removalPolicy defaults to "DESTROY", not "RETAIN". Deleting the stack deletes the queue, its in-flight messages, and the auto-created dead-letter queue, which tracks the same policy. A queue is treated as a transient work medium whose contents regenerate from a source of truth held elsewhere. Pass removalPolicy: "RETAIN" for a queue whose contents are irreplaceable.

kmsKeyArn is present on the props type but the construct does not read it. Setting encryption: "SSE_KMS" maps to CDK’s QueueEncryption.KMS, which provisions a new CDK-managed KMS key rather than the key you name. Use the default "SSE_SQS" unless you have a specific reason to hold a separate key.

A value of 0 for visibilityTimeout, receiveMessageWaitTime or deliveryDelay is treated as unset, and the AWS default applies. To turn long polling off explicitly, leave receiveMessageWaitTime out.

Factory prop differences

MessagingFactory.build accepts IQueueProps, which is a subset of the construct props with one widened field:

Difference	Detail
`queueName`	Not accepted. The factory names the queue from the construct id
`deadLetterQueue.queue`	Not accepted. The factory always creates its own DLQ when `enabled` is `true`
`alertsTopic`	Accepts `ITopic`, a raw topic ARN, or `"import:<ExportName>"` to resolve a cross-stack CloudFormation export

The factory also validates ranges eagerly and throws on an out-of-range visibilityTimeout, messageRetentionPeriod, deliveryDelay, receiveMessageWaitTime or maxMessageSize, and warns when FIFO-only options are set on a standard queue.

Dead-letter queue behaviour

When deadLetterQueue.enabled is true and you do not supply your own queue, Fjall creates a companion DLQ alongside the main queue:

Attribute	Value
Name	`<queueName>-dlq`, or `<queueName>-dlq.fifo` for FIFO queues
Retention	Fixed at 14 days, independent of `messageRetentionPeriod`
Encryption	Same as the main queue
Removal policy	Same as the main queue
TLS	`enforceSSL: true`

Pair the DLQ with alertsTopic to get a CloudWatch alarm on DLQ depth. The alarm fires on the maximum of ApproximateNumberOfMessagesVisible over one evaluation period, with a default threshold of 0, so any dead-lettered message pages. Override it with alarms: { dlqDepthThreshold: 5 }, or disable it with alarms: false. A bring-your-own DLQ passed as deadLetterQueue.queue is never alarmed here. Its owner wires the alarms, which keeps a shared DLQ from collecting one duplicate alarm per referencing queue.

Queue-policy limits

The queue’s single resource policy holds the TLS-only statement Fjall adds plus every grant to a service that pushes to the queue: each EventBridge rule, each SNS subscription, each S3 notification. None of those reaches a queue through an IAM role, so the resource policy is their only grant. A grant to a role, such as tasks.grantSendMessages(apiService) or the execution role addSqsEventSource grants a polling Lambda, lands on that role’s own policy and costs nothing here. SQS caps the queue policy at 20 statements and 8,192 bytes, and refuses the whole policy past either. From fjall 38 SQSQueue checks the policy when the application synthesises, so an over-budget queue is refused before the deploy instead of rolling the stack back mid-deploy. The check covers the queue and the dead-letter queue Fjall creates. A dead-letter queue you pass as deadLetterQueue.queue is not checked here. It is checked only when it is itself a Fjall SQSQueue, by that construct.

Limit	Refusal begins
20 statements	`The resource policy on queue <path> has <count> statements; SQS allows at most 20.`
8,192 bytes	`The resource policy on queue <path> may reach <bytes> bytes; SQS refuses a policy over 8192.`

Each refusal names the queue’s construct path and tells you to split the grants across queues. An EventBridge rule costs its ARN inside a shared statement rather than a statement of its own, so rules exhaust the byte budget long before the statement count. That byte count is an upper bound. An ARN CloudFormation has not created yet is sized at the longest its partition, region, account and name can be, so the refusal can arrive a few grants before SQS’s own would.

Rules targeting one queue	Refused at
Default event bus	61 rules, where SQS accepts about 70
Application’s own bus, 31-character bus name	49 rules
Application’s own bus, 64-character bus name	40 rules

The thresholds above do not apply to a queue created with encryption: "SSE_KMS". Its delivery grant names the account rather than each rule, so one statement covers however many rules deliver to it. As a rule’s dead-letter queue it still shares the dead-letter statement like any other queue. A reference the check cannot size counts at CDK’s own ARN estimate of 150 bytes, and the refusal says how many references that applied to. Lower the estimate when those ARNs are shorter, by adding this one key to the context block already in the application’s cdk.json. Leave the rest of that block in place, including @aws-cdk/aws-iam:minimizePolicies:

cdk.json

{
  "context": {
    "@aws-cdk/aws-iam.arnSizeEstimate": 90
  }
}

The first deploy on fjall 38 rewrites each affected AWS::SQS::QueuePolicy in place, including a queue with a single rule. No queue or rule is replaced, and the same rules are granted before and after. Regenerate any snapshot that reads a queue policy, and see the changelog for the migration.

Methods

Both the construct and the factory wrapper expose these:

Method	Returns	Description
`getQueueUrl()`	`string`	Queue URL
`getQueueArn()`	`string`	Queue ARN
`getQueueName()`	`string`	Queue name
`getQueue()`	`IQueue`	Underlying CDK Queue construct
`getDeadLetterQueue()`	`IQueue \| undefined`	DLQ construct, when Fjall created one
`grantSend(grantee)`	`Grant`	Grant permission to send messages
`grantConsume(grantee)`	`Grant`	Grant permission to receive and delete messages
`grantPurge(grantee)`	`Grant`	Grant permission to purge the queue
`grantSendAndConsume(grantee)`	`Grant`	Grant send and consume permissions

The factory wrapper adds the IQueueMessaging interface names:

Method	Returns	Description
`grantSendMessages(grantee)`	`Grant`	Grant permission to send messages
`grantConsumeMessages(grantee)`	`Grant`	Grant permission to receive and delete messages
`grant(grantee, ...actions)`	`Grant`	Grant specific SQS actions
`grantFull(grantee)`	`Grant`	Grant send and consume permissions

Examples

Standard queue with a DLQ

const tasks = app.addMessaging(
  MessagingFactory.build("Tasks", {
    type: "queue",
    queueType: "standard",
    visibilityTimeout: 300,
    deadLetterQueue: {
      enabled: true,
      maxReceiveCount: 5,
    },
  }),
);

tasks.grantSendMessages(apiService);
tasks.grantConsumeMessages(workerLambda);

DLQ alarm on a shared topic

const tasks = app.addMessaging(
  MessagingFactory.build("Tasks", {
    type: "queue",
    deadLetterQueue: { enabled: true, maxReceiveCount: 5 },
    alertsTopic: "import:SharedAlarmTopicArn",
    alarms: { dlqDepthThreshold: 0 },
  }),
);

FIFO queue

FIFO queues preserve message order and deduplicate within a five-minute window:

const orders = app.addMessaging(
  MessagingFactory.build("Orders", {
    type: "queue",
    queueType: "fifo",
    contentBasedDeduplication: true,
    fifoThroughputLimit: "perMessageGroupId",
    deduplicationScope: "messageGroup",
  }),
);

Long polling

Long polling cuts empty receive responses and the API calls they cost:

const events = app.addMessaging(
  MessagingFactory.build("Events", {
    type: "queue",
    receiveMessageWaitTime: 20,
    messageRetentionPeriod: 1209600, // 14 days
  }),
);

Retained queue

const ledger = app.addMessaging(
  MessagingFactory.build("Ledger", {
    type: "queue",
    removalPolicy: "RETAIN",
    deadLetterQueue: { enabled: true },
  }),
);

Connecting to Lambda

addSqsEventSource takes a CDK IQueue, so pass the underlying queue rather than the Fjall wrapper:

processor.addSqsEventSource(tasks.getQueue(), {
  batchSize: 10,
  reportBatchItemFailures: true,
});

The Lambda polls the queue and deletes messages it processes. Set visibilityTimeout on the queue to at least the function’s timeout, otherwise a slow invocation lets the same message be redelivered while it is still in flight.

CloudFormation Outputs

Output keys are built from the construct id converted to PascalCase, so new SQSQueue(scope, "order-events", {}) produces OrderEventsQueueUrl.

Output	Description
`<PascalCaseId>QueueUrl`	Queue URL
`<PascalCaseId>QueueArn`	Queue ARN
`<PascalCaseId>QueueName`	Queue name
`<PascalCaseId>DeadLetterQueueUrl`	DLQ URL, when Fjall created the DLQ
`<PascalCaseId>DeadLetterQueueArn`	DLQ ARN, when Fjall created the DLQ

A bring-your-own DLQ emits no DLQ outputs, since the queue is owned by another stack.

Next Steps

Messaging Factory

Create queues, topics, and event buses through one factory

Lambda Function

Process queue messages with Lambda

SNS Topic

Fan out one publish to many subscribers

EventBridge

Route events with rules and schedules

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

SQS Queue

Overview

Import

Add a queue from the CLI

Using the Messaging Factory

Direct construct usage

Properties

Factory prop differences

Dead-letter queue behaviour

Queue-policy limits

Methods

Examples

Standard queue with a DLQ

DLQ alarm on a shared topic

FIFO queue

Long polling

Retained queue

Connecting to Lambda

CloudFormation Outputs

Next Steps

Messaging Factory

Lambda Function

SNS Topic

EventBridge

​Overview

​Import

​Add a queue from the CLI

​Using the Messaging Factory

​Direct construct usage

​Properties

​Factory prop differences

​Dead-letter queue behaviour

​Queue-policy limits

​Methods

​Examples

​Standard queue with a DLQ

​DLQ alarm on a shared topic

​FIFO queue

​Long polling

​Retained queue

​Connecting to Lambda

​CloudFormation Outputs

​Next Steps

Messaging Factory

Lambda Function

SNS Topic

EventBridge

Overview

Import

Add a queue from the CLI

Using the Messaging Factory

Direct construct usage

Properties

Factory prop differences

Dead-letter queue behaviour

Queue-policy limits

Methods

Examples

Standard queue with a DLQ

DLQ alarm on a shared topic

FIFO queue

Long polling

Retained queue

Connecting to Lambda

CloudFormation Outputs

Next Steps