> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fjall.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SQS Queue

> Decouple services on AWS with a Fjall SQS queue: dead-letter handling, FIFO ordering, and encryption.

## Overview

The `SQSQueue` construct creates an Amazon SQS queue with optional dead-letter queue, FIFO ordering, and encryption. Use it to decouple producers and consumers in event-driven architectures.

## Import

```typescript theme={null}
import { SQSQueue } from "@fjall/components-infrastructure/lib/resources/aws/messaging/sqs";
```

## Basic Usage

```typescript theme={null}
const queue = new SQSQueue(scope, "Notifications", {});
```

## Using the Messaging Factory

The recommended way to add SQS to a Fjall application is through the `MessagingFactory`:

```typescript theme={null}
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 },
  }),
);
```

## Properties

| Property                          | Type                                | Default           | Description                                                                                    |
| --------------------------------- | ----------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------- |
| `queueName`                       | `string`                            | Auto-generated    | Queue name                                                                                     |
| `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 message becomes visible in seconds (0-900)                                        |
| `deadLetterQueue.enabled`         | `boolean`                           | `false`           | Create a dead-letter queue                                                                     |
| `deadLetterQueue.maxReceiveCount` | `number`                            | `3`               | Failed deliveries before moving to DLQ (1-1000)                                                |
| `encryption`                      | `"SSE_SQS" \| "SSE_KMS" \| "NONE"`  | `"SSE_SQS"`       | Encryption type                                                                                |
| `kmsKeyArn`                       | `string`                            | --                | KMS key ARN (when using SSE\_KMS)                                                              |
| `contentBasedDeduplication`       | `boolean`                           | `true` (FIFO)     | Enable content-based deduplication. FIFO only, defaults to `true`. Ignored for standard queues |
| `fifoThroughputLimit`             | `"perQueue" \| "perMessageGroupId"` | `"perQueue"`      | FIFO throughput limit                                                                          |
| `deduplicationScope`              | `"queue" \| "messageGroup"`         | `"queue"`         | FIFO deduplication scope                                                                       |
| `removalPolicy`                   | `"DESTROY" \| "RETAIN"`             | `"RETAIN"`        | What happens on stack deletion                                                                 |

## Methods

| Method                         | Returns               | Description                                     |
| ------------------------------ | --------------------- | ----------------------------------------------- |
| `getQueueUrl()`                | `string`              | Queue URL                                       |
| `getQueueArn()`                | `string`              | Queue ARN                                       |
| `getQueueName()`               | `string`              | Queue name                                      |
| `getQueue()`                   | `IQueue`              | CDK Queue construct                             |
| `getDeadLetterQueue()`         | `IQueue \| undefined` | DLQ construct (if enabled)                      |
| `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              |

## Examples

### Standard Queue with DLQ

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

tasks.grantSend(apiService);
tasks.grantConsume(workerLambda);
```

### FIFO Queue

FIFO queues guarantee exactly-once processing and preserve message order:

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

### Long Polling

Reduce empty responses and API costs with long polling:

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

### KMS Encryption

```typescript theme={null}
const sensitive = app.addMessaging(
  MessagingFactory.build("Sensitive", {
    type: "queue",
    encryption: "SSE_KMS",
    kmsKeyArn: encryptionKey.getKeyArn(),
  }),
);
```

## Connecting to Lambda

Use the Lambda event source integration to process queue messages:

```typescript theme={null}
// Lambda automatically polls the queue
processor.addSqsEventSource(tasks);
```

## CloudFormation Outputs

| Output                   | Description          |
| ------------------------ | -------------------- |
| `{id}QueueUrl`           | Queue URL            |
| `{id}QueueArn`           | Queue ARN            |
| `{id}QueueName`          | Queue name           |
| `{id}DeadLetterQueueUrl` | DLQ URL (if enabled) |
| `{id}DeadLetterQueueArn` | DLQ ARN (if enabled) |

## Next Steps

<CardGroup cols={2}>
  <Card title="Messaging Factory" icon="industry" href="/patterns/messaging-factory">
    Create messaging resources via the factory pattern
  </Card>

  <Card title="Lambda Function" icon="bolt" href="/resources/compute/lambda-function">
    Process queue messages with Lambda
  </Card>
</CardGroup>