# README
NATS Architecture And Design
This repository captures Architecture, Design Specifications and Feature Guidance for the NATS ecosystem.
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, spec | 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-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, spec | 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, spec | 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, spec | JetStream Simplification |
| ADR-40 | client, server, spec | NATS Connection |
| ADR-43 | jetstream, client, server | JetStream Per-Message TTL |
| ADR-47 | client, spec, orbit | Request Many |
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, spec | 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-17 | jetstream, client | Ordered Consumer |
| ADR-19 | jetstream, client, kv, objectstore | API prefixes for materialized JetStream views |
| ADR-20 | jetstream, client, objectstore, spec | 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, spec | JetStream Simplification |
| ADR-42 | jetstream, server | Pull Consumer Priority Groups |
| ADR-43 | jetstream, client, server | JetStream Per-Message TTL |
| ADR-44 | jetstream, server | Versioning for JetStream Assets |
Kv
| Index | Tags | Description |
|---|---|---|
| ADR-8 | jetstream, client, kv, spec | 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, spec | JetStream based Object Stores |
Observability
| Index | Tags | Description |
|---|---|---|
| ADR-3 | observability, server | NATS Service Latency Distributed Tracing Interoperability |
| ADR-41 | observability, server | NATS Message Path Tracing |
Orbit
| Index | Tags | Description |
|---|---|---|
| ADR-47 | client, spec, orbit | Request Many |
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 |
| ADR-40 | client, server, spec | NATS Connection |
| ADR-41 | observability, server | NATS Message Path Tracing |
| ADR-42 | jetstream, server | Pull Consumer Priority Groups |
| ADR-43 | jetstream, client, server | JetStream Per-Message TTL |
| ADR-44 | jetstream, server | Versioning for JetStream Assets |
Spec
| Index | Tags | Description |
|---|---|---|
| ADR-8 | jetstream, client, kv, spec | JetStream based Key-Value Stores |
| ADR-20 | jetstream, client, objectstore, spec | JetStream based Object Stores |
| ADR-32 | client, spec | Service API |
| ADR-37 | jetstream, client, spec | JetStream Simplification |
| ADR-40 | client, server, spec | NATS Connection |
| ADR-47 | client, spec, orbit | Request Many |
Deprecated
| Index | Tags | Description |
|---|---|---|
| ADR-15 | deprecated | JetStream Subscribe Workflow |
When to write an ADR
We use this repository in a few ways:
- Design specifications where a single document captures everything about a feature, examples are ADR-8, ADR-32, ADR-37 and ADR-40
- Guidance on conventions and design such as ADR-6 which documents all the valid naming rules
- Capturing design that might impact many areas of the system such as ADR-2
We want to move away from using these to document individual minor decisions, moving instead to spec like documents that are living documents and can change over time. Each capturing revisions and history.
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.