13. NATS JetStream

NATS JetStream is a persistent, replicated streaming engine built on top of the NATS messaging system. ArmoniK uses it as a durable task queue with explicit message acknowledgment and per-partition consumers.

13.1. Deployment

just queue=nats build-deploy

The local deployment runs the official nats:alpine Docker image (Linux) or nats:nanoserver-ltsc2022 (Windows) with JetStream and HTTP management enabled.

13.2. Architecture in ArmoniK

ArmoniK creates a single JetStream stream named armonik-stream with WorkQueue retention (messages are deleted once acknowledged). Each partition gets its own consumer (durable name = partition ID). The adapter uses at-least-once delivery: if a message is not acknowledged within AckWait seconds, NATS redelivers it.

PollingAgent[0] ──pull── consumer:partition-0 ──┐
PollingAgent[1] ──pull── consumer:partition-1 ──┤── stream: armonik-stream ── NATS server
PollingAgent[2] ──pull── consumer:partition-0 ──┘  (WorkQueue retention)

13.3. Configuration

All configuration variables and their defaults are documented in the Environment Variables reference.

13.4. Supported features

Feature	Supported
Task priorities	No — single stream, no priority routing
Durable subscriptions	Yes — per-partition consumers survive restarts
Automatic redelivery	Yes — via `AckWait` timeout
Delivery semantics	At-least-once — messages are redelivered if not acknowledged within `AckWait`
TLS	Yes — configure via the NATS server; the client honors `nats://` vs `tls://` in the URL

13.5. Limitations

No priority queues. Unlike SQS, NATS does not split tasks across priority-based queues. All tasks compete equally in the stream.
Stream name is fixed to armonik-stream. If you share a NATS server across multiple ArmoniK deployments, use different subject prefixes.
WorkQueue retention — messages are removed from the stream as soon as they are acknowledged. Unacknowledged messages are redelivered after AckWait seconds.

13.6. Health check

The NATS container exposes an HTTP management endpoint. The Terraform module waits for:

curl -fsSL http://localhost:8222/healthz

13.7. Monitoring

Use the NATS management UI at http://localhost:8222 to inspect stream and consumer state, message counts, and pending messages per partition.