NATS Architecture And Design
This repo is used to capture architectural and design decisions as a reference of the server implementation and expected client behavior.
Architecture Decision Records
Client
| Index | Tags | Description |
|---|---|---|
| ADR-1 | jetstream, client, server | JetStream JSON API Design |
| ADR-2 | jetstream, server, client | NATS Typed Messages |
| ADR-4 | server, client | NATS Message Headers |
| ADR-5 | server, client | Lame Duck Notification |
| ADR-6 | server, client | Naming Rules |
| ADR-7 | server, client, jetstream | NATS Server Error Codes |
| ADR-8 | jetstream, client, kv | JetStream based Key-Value Stores |
| ADR-9 | server, client, jetstream | JetStream Consumer Idle Heartbeats |
| ADR-10 | server, client, jetstream | JetStream Extended Purge |
| ADR-11 | client | Hostname resolution |
| ADR-13 | jetstream, client | Pull Subscribe internals |
| ADR-14 | client, security | JWT library free jwt user generation |
| ADR-15 | jetstream, client | JetStream Subscribe Workflow |
| ADR-17 | jetstream, client | Ordered Consumer |
| ADR-18 | client | URL support for all client options |
| ADR-19 | jetstream, client, kv, objectstore | API prefixes for materialized JetStream views: |
| ADR-20 | jetstream, client, objectstore | JetStream based Object Stores |
| ADR-21 | client | NATS Configuration Contexts |
| ADR-22 | jetstream, client | JetStream Publish Retries on No Responders |
| ADR-31 | jetstream, client, server | JetStream Direct Get |
| ADR-32 | client | Service API |
| ADR-33 | jetstream, client, server | Metadata for Stream and Consumer |
| ADR-34 | jetstream, client, server | JetStream Consumers Multiple Filters |
| ADR-36 | jetstream, client, server | Subject Mapping Transforms in Streams |
| ADR-37 | jetstream, client | JetStream Simplification |
Jetstream
| Index | Tags | Description |
|---|---|---|
| ADR-1 | jetstream, client, server | JetStream JSON API Design |
| ADR-2 | jetstream, server, client | NATS Typed Messages |
| ADR-7 | server, client, jetstream | NATS Server Error Codes |
| ADR-8 | jetstream, client, kv | JetStream based Key-Value Stores |
| ADR-9 | server, client, jetstream | JetStream Consumer Idle Heartbeats |
| ADR-10 | server, client, jetstream | JetStream Extended Purge |
| ADR-12 | jetstream | JetStream Encryption At Rest |
| ADR-13 | jetstream, client | Pull Subscribe internals |
| ADR-15 | jetstream, client | JetStream Subscribe Workflow |
| ADR-17 | jetstream, client | Ordered Consumer |
| ADR-19 | jetstream, client, kv, objectstore | API prefixes for materialized JetStream views: |
| ADR-20 | jetstream, client, objectstore | JetStream based Object Stores |
| ADR-22 | jetstream, client | JetStream Publish Retries on No Responders |
| ADR-28 | jetstream, server | JetStream RePublish |
| ADR-31 | jetstream, client, server | JetStream Direct Get |
| ADR-33 | jetstream, client, server | Metadata for Stream and Consumer |
| ADR-34 | jetstream, client, server | JetStream Consumers Multiple Filters |
| ADR-36 | jetstream, client, server | Subject Mapping Transforms in Streams |
| ADR-37 | jetstream, client | JetStream Simplification |
Kv
| Index | Tags | Description |
|---|---|---|
| ADR-8 | jetstream, client, kv | JetStream based Key-Value Stores |
| ADR-19 | jetstream, client, kv, objectstore | API prefixes for materialized JetStream views: |
Objectstore
| Index | Tags | Description |
|---|---|---|
| ADR-19 | jetstream, client, kv, objectstore | API prefixes for materialized JetStream views: |
| ADR-20 | jetstream, client, objectstore | JetStream based Object Stores |
Observability
| Index | Tags | Description |
|---|---|---|
| ADR-3 | observability, server | NATS Service Latency Distributed Tracing Interoperability |
Security
| Index | Tags | Description |
|---|---|---|
| ADR-14 | client, security | JWT library free jwt user generation |
| ADR-38 | server, security | OCSP Peer Verification |
| ADR-39 | server, security | Certificate Store |
Server
| Index | Tags | Description |
|---|---|---|
| ADR-1 | jetstream, client, server | JetStream JSON API Design |
| ADR-2 | jetstream, server, client | NATS Typed Messages |
| ADR-3 | observability, server | NATS Service Latency Distributed Tracing Interoperability |
| ADR-4 | server, client | NATS Message Headers |
| ADR-5 | server, client | Lame Duck Notification |
| ADR-6 | server, client | Naming Rules |
| ADR-7 | server, client, jetstream | NATS Server Error Codes |
| ADR-9 | server, client, jetstream | JetStream Consumer Idle Heartbeats |
| ADR-10 | server, client, jetstream | JetStream Extended Purge |
| ADR-26 | server | NATS Authorization Callouts |
| ADR-28 | jetstream, server | JetStream RePublish |
| ADR-30 | server | Subject Transform |
| ADR-31 | jetstream, client, server | JetStream Direct Get |
| ADR-33 | jetstream, client, server | Metadata for Stream and Consumer |
| ADR-34 | jetstream, client, server | JetStream Consumers Multiple Filters |
| ADR-36 | jetstream, client, server | Subject Mapping Transforms in Streams |
| ADR-38 | server, security | OCSP Peer Verification |
| ADR-39 | server, security | Certificate Store |
When to write an ADR
Not every little decision needs an ADR, and we are not overly prescriptive about the format apart from the initial header format. The kind of change that should have an ADR are ones likely to impact many client libraries, server configuration, security, deployment and those where we specifically wish to solicit wider community input.
For a background of the rationale driving ADRs see Documenting Architecture Decisions by Michael Nygard
Template
Please see the template. The template body is a guideline. Feel free to add sections as you feel appropriate. Look at the other ADRs for examples. However the initial Table of metadata and header format is required to match.
After editing / adding a ADR please run go run main.go > README.md to update the embedded index. This will also validate the header part of your ADR.
Related Repositories
- Server nats-server
- Reference implementation nats.go
- Java Client nats.java
- .NET / C# client nats.net
- JavaScript nats.ws nats.deno
- C Client nats.c
- Python3 Client for Asyncio nats.py
Client Tracking
There is a Client Feature Parity spreadsheet that tracks the clients somewhat, but it is not guaranteed to be complete or up to date.