Queue behavior and limits
A Queue delivers every message at least once, in any order, on every platform. This page lists its guarantees, limits, and how each cloud's backing service differs.
Guarantees
At-least-once delivery. Every message is delivered at least once, and can be delivered more than once. Make consumers idempotent.
No ordering. Messages can arrive in any order, on every cloud. If order matters, carry a sequence number in the message.
Leases. A received message is hidden from other consumers until it's acknowledged or its lease runs out. Then it's delivered again. nack ends the lease early; renewLease resets it.
Idempotent acks. Acknowledging the same message twice is safe.
Durability. SQS, Pub/Sub, and Service Bus store messages redundantly until they're acknowledged or their retention ends.
No exactly-once. Some backends offer exactly-once delivery in specific configurations, but not in a form that's portable. Alien doesn't enable it.
On Kubernetes, the guarantees are those of the service in the external binding.
Limits
Alien checks these on every platform:
| Limit | Value |
|---|---|
| Message size | 64 KiB (65,536 bytes), after JSON encoding |
Messages per receive | 1 to 10 |
Lease after receive | Pub/Sub and Local: 30 seconds. SQS: the queue's visibility timeout, 30 seconds unless a Worker trigger raises it. Service Bus: the queue's lock duration. |
renewLease duration | 1 to 600 seconds |
| Payload types | JSON or UTF-8 text |
| Queue triggers per Worker | 1 |
| Trigger batch | 1 to 100 messages, window 0 to 300 seconds. More than 10 messages needs a nonzero window. |
Semantics
Payloads. send stores the JSON text of the value and sendText stores the string. receive returns payloadType so you know which one you got. The payload is always a string: parse JSON yourself.
Delivery attempts. attempt starts at 1. SQS reports the real receive count and the local queue its own count. Pub/Sub and Service Bus report 1 through receive.
Batch sends. sendBatch uses each backend's batch API and returns one outcome per message. unknown means the request failed in a way that leaves acceptance unclear, so retrying can duplicate. Alien never retries for you.
Batch acks. ackBatch acknowledges each receipt independently. It isn't a transaction.
Lease renewal. On SQS, Pub/Sub, and Local, renewLease sets the remaining lease to the given duration, which can shorten it. Service Bus renews its configured lock duration instead. A lease that already expired can't be renewed.
Purge. Supported on SQS and Local. Pub/Sub and Service Bus return OPERATION_NOT_SUPPORTED.
Triggers
| Platform | Wiring |
|---|---|
| AWS | SQS event source mapping on the Lambda function |
| GCP | Pub/Sub push subscription to the Cloud Run service |
| Azure | Service Bus scaler (KEDA) on the Container App |
| Kubernetes | Not supported. Consume with receive. |
| Local | Alien's local trigger service |
A handler that returns acknowledges its message. A handler that throws leaves it for redelivery. With batch, the handler returns success or retry for each delivery.
Per-cloud details
The lease settings below are set to fit the Workers that a queue triggers, so a message isn't redelivered while a Worker is still working on it.
AWS (SQS)
- Standard queue, not FIFO.
- Visibility timeout:
max(30 seconds, min(12 hours, Worker timeout × 6 + batch window))for the longest Worker the queue triggers, or 30 seconds when no Worker triggers it. Alien never lowers a timeout that's already higher. - Queues created at initial setup keep messages for 4 days and use SQS-managed server-side encryption.
receivelong-polls for up to 20 seconds.- SQS accepts messages up to 256 KiB; Alien enforces 64 KiB.
GCP (Pub/Sub)
- A topic with one pull subscription. Ordering is off.
receivesets each received message's ack deadline to 30 seconds.- In subscriptions declared in the stack, the ack deadline is
Worker timeout × 2, clamped to 10–600 seconds, or 60 seconds when no Worker triggers the queue. Messages are kept for 7 days and the subscription never expires. - Pub/Sub accepts messages up to 10 MB; Alien enforces 64 KiB.
Azure (Service Bus)
- One Service Bus namespace per stack, Standard tier. Each Queue resource is a queue in it.
receivetakes messages one at a time with peek-lock, waiting up to 30 seconds for each.- In queues created at initial setup, the lock duration is
Worker timeout × 2, clamped to 5–300 seconds (30 seconds when no Worker triggers the queue). - Queues created at initial setup keep messages for 14 days. After 10 failed deliveries a message moves to the dead-letter queue. Expired messages are dead-lettered too.
- Queues that Alien creates at runtime use the Service Bus defaults for these settings.
nackabandons the message.renewLeaserenews the lock for the configured lock duration.- Service Bus Standard accepts messages up to 256 KB; Alien enforces 64 KiB.
Kubernetes
Alien creates nothing. Point each Queue resource at SQS, Pub/Sub, or Service Bus in the Helm values. Worker queue triggers aren't available.
Local
- An embedded database file,
localqueue.sqlite, owned by the local Alien process. Messages survive restarts. - Applications reach it through Alien's local process, not by opening the file.
- A message is delivered to exactly one receiver per lease. Expired leases are reclaimed on the next
receive. attemptcounts real deliveries.
Design decisions
64 KiB messages. SQS and Service Bus Standard allow 256 KB and Pub/Sub 10 MB. One portable limit means a message that works locally works everywhere. Put large payloads in Storage and send the key.
10 messages per receive. SQS returns at most 10 per call, so that's the portable batch size.
Leases sized from Workers. Each backend's visibility setting is derived from the Workers a queue triggers, instead of a separate option you'd have to keep in sync.
Outcomes per message. Batch sends and acks report each message separately, including the uncertain case, so callers decide what to retry instead of the SDK guessing.