Skip to navigation
Specification

NATS JetStream binding

Build an AMP broker on NATS JetStream
View as Markdown

This page shows how to build an AMP broker on NATS JetStream. It is informative: a broker may use any backend that meets the specification.

Mapping

AMPNATS JetStream
Participant inboxSubject amp.<ns>.inbox.<name>, one durable consumer per participant
Job queueStream AMP_TASKS_<ns> with work-queue retention on subjects amp.<ns>.job.<job>
Offer and claimA pull consumer per job; the session gateway fetches one message per free slot
LeaseConsumer AckWait = lease_s. The session gateway sends an in-progress ack (+WPI) on claim and on each heartbeat. Each one restarts the full AckWait
Re-offer after expiryRedelivery after AckWait. Leave MaxDeliver unlimited: a declined offer (Nak) also counts as a delivery, so MaxDeliver cannot stand for max_attempts
Exhausted attemptsThe task store counts attempt. At max_attempts, the session gateway terminates the message (AckTerm) and moves the task to failed. The max-deliveries advisory fires only on the next pull and leaves the message in the stream
TopicStream AMP_TOPICS_<ns> with limits retention, one consumer per subscriber; replay with a start time or sequence
RegistryKV bucket AMP_REGISTRY_<ns> with LimitMarkerTTL, one key per participant with a per-key TTL. A heartbeat republishes the key with a Nats-TTL header; a plain put removes the TTL. Watchers see a purge when a key expires
Task storeKV bucket AMP_TASK_STATE, one key per task, with history. Each update sets the last revision, so two claims cannot both succeed
AuthenticationAuth callout: validate the participant’s credential and issue a scoped user JWT
Address permissionPublish and subscribe permissions in that JWT
FederationSuperclusters (gateways) between regions, or leaf nodes

What NATS does not provide

RequirementWhere it lives
Lease ownershipJetStream accepts an ack from an earlier lease holder and removes the task. The session gateway checks the lease in the task store before it acks, and returns lease_lost otherwise
Broker-set fromThe session gateway stamps it from the authenticated identity before publishing
Job eligibility and least-loaded choiceThe session gateway, using the registry
Rate limits and budgetsA policy service on the publish path
Envelope validationThe session gateway, against the JSON Schema

Shape of a broker

participant ── WebSocket or gRPC ──► session gateway ──► NATS JetStream
                                         │
                                  auth callout · policy service

The session gateway terminates AMP sessions, translates frames to NATS operations, and enforces the parts of the specification NATS does not.

Next steps