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-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, 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

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-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, 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

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

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

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

When to write an ADR

We use this repository in a few ways:

1. Design specifications where a single document captures everything about a feature, examples are ADR-8, ADR-32, ADR-37 and ADR-40
2. Guidance on conventions and design such as ADR-6 which documents all the valid naming rules
3. 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.