second first commit

2026-09-22 08:57:00 -04:00
parent e88d7e2ff3
commit 0aef7fb2d8
4766 changed files with 1236986 additions and 0 deletions
@@ -0,0 +1,163 @@
+# SQS
+
+**Protocol:** Query (XML) and JSON 1.0 (both supported)
+**Endpoint:** `POST http://localhost:4566/`
+
+## Supported Actions
+
+<!-- floci:actions:start -->
+| Action | Description |
+| --- | --- |
+| `CreateQueue` | Create a standard or FIFO queue |
+| `DeleteQueue` | Delete a queue |
+| `ListQueues` | List all queues |
+| `GetQueueUrl` | Look up a queue URL by name |
+| `GetQueueAttributes` | Get queue configuration attributes |
+| `SendMessage` | Send a message to a queue |
+| `ReceiveMessage` | Poll for messages |
+| `DeleteMessage` | Acknowledge and delete a message |
+| `DeleteMessageBatch` | Delete multiple messages at once |
+| `SendMessageBatch` | Send up to 10 messages in one call |
+| `ChangeMessageVisibility` | Extend or reset a message's visibility timeout |
+| `ChangeMessageVisibilityBatch` | Change visibility for multiple messages |
+| `SetQueueAttributes` | Update queue configuration |
+| `TagQueue` | Add tags to a queue |
+| `UntagQueue` | Remove tags from a queue |
+| `ListQueueTags` | List tags on a queue |
+| `PurgeQueue` | Delete all messages in a queue |
+| `ListDeadLetterSourceQueues` | Find queues that use this queue as DLQ |
+| `StartMessageMoveTask` | Start a DLQ redrive task |
+| `ListMessageMoveTasks` | List DLQ redrive tasks |
+| `CancelMessageMoveTask` | - |
+| `AddPermission` | - |
+| `RemovePermission` | - |
+<!-- floci:actions:end -->
+
+## Local Inspection Endpoint
+
+For test assertions and debugging, Floci exposes a LocalStack-compatible endpoint that lets you peek at queue contents without consuming messages:
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/_aws/sqs/messages?QueueUrl=<url>` | List all messages in the queue (non-destructive) |
+| `DELETE` | `/_aws/sqs/messages?QueueUrl=<url>` | Purge all messages from the queue |
+
+`GET` returns every message currently in the queue — including in-flight messages — without changing visibility timeouts or advancing receive counts. It does not remove messages.
+
+`DELETE` is equivalent to `PurgeQueue` and removes all messages.
+
+### Response shape
+
+```json
+{
+  "messages": [
+    {
+      "MessageId": "abc123",
+      "MD5OfBody": "...",
+      "Body": "{\"event\":\"order.placed\"}",
+      "ReceiptHandle": null,
+      "Attributes": {
+        "SentTimestamp": "1714000000000",
+        "ApproximateReceiveCount": "0"
+      },
+      "MessageAttributes": {}
+    }
+  ]
+}
+```
+
+`ReceiptHandle` is `null` for messages that have not yet been received. FIFO messages include `MessageGroupId`, `MessageDeduplicationId`, and `SequenceNumber` in `Attributes` when set.
+
+### Example
+
+```bash
+QUEUE_URL="http://localhost:4566/000000000000/orders"
+
+# Peek at messages without consuming them
+curl "http://localhost:4566/_aws/sqs/messages?QueueUrl=$QUEUE_URL"
+
+# Purge the queue
+curl -X DELETE "http://localhost:4566/_aws/sqs/messages?QueueUrl=$QUEUE_URL"
+```
+
+## Long Polling
+
+`ReceiveMessage` waits up to `WaitTimeSeconds` (0 to 20) for a message to arrive and returns as soon as one is available. Values outside that range are rejected with `InvalidParameterValue`. When the request omits `WaitTimeSeconds`, the queue's `ReceiveMessageWaitTimeSeconds` attribute applies (default `0`, short polling), matching AWS.
+
+```bash
+# Enable long polling for every consumer of the queue
+aws sqs set-queue-attributes \
+  --queue-url $QUEUE_URL \
+  --attributes ReceiveMessageWaitTimeSeconds=20 \
+  --endpoint-url $AWS_ENDPOINT_URL
+```
+
+## Queue Attributes
+
+`GetQueueAttributes` with `--attribute-names All` returns the set AWS returns for a standard queue: `QueueArn`, `CreatedTimestamp`, `LastModifiedTimestamp`, `ApproximateNumberOfMessages`, `ApproximateNumberOfMessagesNotVisible`, `ApproximateNumberOfMessagesDelayed`, `VisibilityTimeout`, `MaximumMessageSize`, `MessageRetentionPeriod`, `DelaySeconds`, `ReceiveMessageWaitTimeSeconds` and `SqsManagedSseEnabled`. `Policy`, `RedrivePolicy` and `KmsMasterKeyId` appear only once set, and FIFO queues also report `FifoQueue` and `ContentBasedDeduplication`.
+
+`MaximumMessageSize` defaults to `1048576` bytes, the AWS default and maximum since August 2025, when AWS raised both from `262144`. `CreateQueue` and `SetQueueAttributes` reject values outside 1024 to 1048576 with `InvalidAttributeValue`; raising `FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE` above the AWS maximum raises that accepted ceiling with it. Lowering the variable below 1048576 only changes the default a new queue receives: the accepted ceiling stays at the AWS maximum, so a queue can still be set to `1048576` explicitly.
+
+`SqsManagedSseEnabled` is `true` for a queue with no `KmsMasterKeyId`, matching AWS, and `false` once a KMS key is set. It is derived on read rather than stored, so clearing `KmsMasterKeyId` returns the queue to `true`, unless you set `SqsManagedSseEnabled` yourself, in which case your value stands. AWS does not document the cleared-key case crisply, so that behaviour is Floci's choice rather than a copied one.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SQS_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT` | `30` | Default message visibility timeout (seconds) |
+| `FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE` | `1048576` | Maximum message size in bytes (1 MiB) |
+| `FLOCI_SERVICES_SQS_CLEAR_FIFO_DEDUPLICATION_CACHE_ON_PURGE` | `false` | When `true`, `PurgeQueue` also clears the FIFO deduplication cache for the queue and any SNS FIFO topics subscribed to it |
+
+## Examples
+
+```bash
+export AWS_ENDPOINT_URL=http://localhost:4566
+
+# Create a standard queue
+aws sqs create-queue --queue-name orders --endpoint-url $AWS_ENDPOINT_URL
+
+# Create a FIFO queue
+aws sqs create-queue \
+  --queue-name orders.fifo \
+  --attributes FifoQueue=true \
+  --endpoint-url $AWS_ENDPOINT_URL
+
+# Send a message
+QUEUE_URL="$AWS_ENDPOINT_URL/000000000000/orders"
+aws sqs send-message \
+  --queue-url $QUEUE_URL \
+  --message-body '{"event":"order.placed","id":"abc123"}' \
+  --endpoint-url $AWS_ENDPOINT_URL
+
+# Receive messages
+aws sqs receive-message \
+  --queue-url $QUEUE_URL \
+  --max-number-of-messages 10 \
+  --endpoint-url $AWS_ENDPOINT_URL
+
+# Delete a message (replace RECEIPT_HANDLE with the value from ReceiveMessage)
+aws sqs delete-message \
+  --queue-url $QUEUE_URL \
+  --receipt-handle "RECEIPT_HANDLE" \
+  --endpoint-url $AWS_ENDPOINT_URL
+
+# Set up a dead-letter queue
+DLQ_ARN=$(aws sqs get-queue-attributes \
+  --queue-url $AWS_ENDPOINT_URL/000000000000/orders-dlq \
+  --attribute-names QueueArn \
+  --query Attributes.QueueArn \
+  --output text \
+  --endpoint-url $AWS_ENDPOINT_URL)
+
+aws sqs set-queue-attributes \
+  --queue-url $QUEUE_URL \
+  --attributes "{\"RedrivePolicy\":\"{\\\"deadLetterTargetArn\\\":\\\"$DLQ_ARN\\\",\\\"maxReceiveCount\\\":3}\"}" \
+  --endpoint-url $AWS_ENDPOINT_URL
+```
+
+## Queue URL Format
+
+```
+http://localhost:4566/000000000000/<queue-name>
+```