Merge branch 'main' into request-many

nats-io · Sep 22, 2024 · d4deecd · d4deecd
2 parents 0aabefa + 2c9cc9d
commit d4deecd
Show file tree

Hide file tree

Showing 25 changed files with 2,081 additions and 256 deletions.
diff --git a/.github/ISSUE_TEMPLATE/client_enhancement.md b/.github/ISSUE_TEMPLATE/client_enhancement.md
@@ -2,7 +2,7 @@
 name: Client Enhancement
 about: Request a new feature to be added to NATS clients
 labels: enhancement, client
-assignees: ripienaar, wallyqs, scottf, aricart, derekcollison, Jarema, piotrpio, jnmoyne, bruth, caspervonb, marthacp, levb
+assignees: ripienaar, wallyqs, scottf, aricart, derekcollison, Jarema, piotrpio, jnmoyne, bruth, levb, mtmk
 ---
 
 ## Overview
@@ -22,9 +22,10 @@ The behavior is documented in ADR-X.
  - [ ] JavaScript @aricart
  - [ ] .Net @scottf
  - [ ] C @levb
- - [ ] Python @wallyqs
+ - [ ] Python @caspervonb
  - [ ] Ruby @wallyqs
- - [ ] Rust @Jarema @caspervonb
+ - [ ] Rust @Jarema
+ - [ ] .Net V2 @mtmk
 
 ## Other Tasks
 

diff --git a/.github/workflows/validate.yaml b/.github/workflows/validate.yaml
@@ -16,7 +16,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v1
         with:
-          go-version: 1.16
+          go-version: "1.22"
 
       - name: Valid metadata and readme updated
         shell: bash --noprofile --norc -x -eo pipefail {0}

diff --git a/.readme.templ b/.readme.templ
@@ -2,7 +2,7 @@
 
 # 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.
+This repository captures Architecture, Design Specifications and Feature Guidance for the NATS ecosystem.
 
 # Architecture Decision Records
 {{- range . }}
@@ -16,29 +16,16 @@ This repo is used to capture architectural and design decisions as a reference o
 {{ end }}
 ## 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.
+We use this repository in a few ways:
 
-For a background of the rationale driving ADRs see [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by
-Michael Nygard
+ 1. Design specifications where a single document captures everything about a feature, examples are ADR-8, ADR-32, ADR-37 and ADR-40
+ 1. Guidance on conventions and design such as ADR-6 which documents all the valid naming rules
+ 1. 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](adr-template.md). 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](https://github.com/nats-io/nats-server)
- * Reference implementation [nats.go](https://github.com/nats-io/nats.go)
- * Java Client [nats.java](https://github.com/nats-io/nats..java)
- * .NET / C# client [nats.net](https://github.com/nats-io/nats.net)
- * JavaScript [nats.ws](https://github.com/nats-io/nats.ws) [nats.deno](https://github.com/nats-io/nats.deno)
- * C Client [nats.c](https://github.com/nats-io/nats.c)
- * Python3 Client for Asyncio [nats.py](https://github.com/nats-io/nats.py)
-
-### Client Tracking
-
-There is a [Client Feature Parity](https://docs.google.com/spreadsheets/d/1VcYcKqwOp8h8zZwNSRXMS5wrdA1jZz6AumMTHZbXrmY/edit#gid=1032495336) spreadsheet that tracks the clients somewhat, but it is not guaranteed to be complete or up to date.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 # 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.
+This repository captures Architecture, Design Specifications and Feature Guidance for the NATS ecosystem.
 
 # Architecture Decision Records
 ## Client
@@ -15,26 +15,26 @@ This repo is used to capture architectural and design decisions as a reference o
 |[ADR-5](adr/ADR-5.md)|server, client|Lame Duck Notification|
 |[ADR-6](adr/ADR-6.md)|server, client|Naming Rules|
 |[ADR-7](adr/ADR-7.md)|server, client, jetstream|NATS Server Error Codes|
-|[ADR-8](adr/ADR-8.md)|jetstream, client, kv|JetStream based Key-Value Stores|
+|[ADR-8](adr/ADR-8.md)|jetstream, client, kv, spec|JetStream based Key-Value Stores|
 |[ADR-9](adr/ADR-9.md)|server, client, jetstream|JetStream Consumer Idle Heartbeats|
 |[ADR-10](adr/ADR-10.md)|server, client, jetstream|JetStream Extended Purge|
 |[ADR-11](adr/ADR-11.md)|client|Hostname resolution|
 |[ADR-13](adr/ADR-13.md)|jetstream, client|Pull Subscribe internals|
 |[ADR-14](adr/ADR-14.md)|client, security|JWT library free jwt user generation|
-|[ADR-15](adr/ADR-15.md)|jetstream, client|JetStream Subscribe Workflow|
 |[ADR-17](adr/ADR-17.md)|jetstream, client|Ordered Consumer|
 |[ADR-18](adr/ADR-18.md)|client|URL support for all client options|
-|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views:|
-|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore|JetStream based Object Stores|
+|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views|
+|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore, spec|JetStream based Object Stores|
 |[ADR-21](adr/ADR-21.md)|client|NATS Configuration Contexts|
 |[ADR-22](adr/ADR-22.md)|jetstream, client|JetStream Publish Retries on No Responders|
 |[ADR-31](adr/ADR-31.md)|jetstream, client, server|JetStream Direct Get|
-|[ADR-32](adr/ADR-32.md)|client|Service API|
+|[ADR-32](adr/ADR-32.md)|client, spec|Service API|
 |[ADR-33](adr/ADR-33.md)|jetstream, client, server|Metadata for Stream and Consumer|
 |[ADR-34](adr/ADR-34.md)|jetstream, client, server|JetStream Consumers Multiple Filters|
 |[ADR-36](adr/ADR-36.md)|jetstream, client, server|Subject Mapping Transforms in Streams|
-|[ADR-37](adr/ADR-37.md)|jetstream, client|JetStream Simplification|
-|[ADR-40](adr/ADR-40.md)|client|Request Many|
+|[ADR-37](adr/ADR-37.md)|jetstream, client, spec|JetStream Simplification|
+|[ADR-40](adr/ADR-40.md)|client, server, spec|NATS Connection|
+|[ADR-43](adr/ADR-43.md)|jetstream, client, server|JetStream Per-Message TTL|
 
 ## Jetstream
 
@@ -43,42 +43,45 @@ This repo is used to capture architectural and design decisions as a reference o
 |[ADR-1](adr/ADR-1.md)|jetstream, client, server|JetStream JSON API Design|
 |[ADR-2](adr/ADR-2.md)|jetstream, server, client|NATS Typed Messages|
 |[ADR-7](adr/ADR-7.md)|server, client, jetstream|NATS Server Error Codes|
-|[ADR-8](adr/ADR-8.md)|jetstream, client, kv|JetStream based Key-Value Stores|
+|[ADR-8](adr/ADR-8.md)|jetstream, client, kv, spec|JetStream based Key-Value Stores|
 |[ADR-9](adr/ADR-9.md)|server, client, jetstream|JetStream Consumer Idle Heartbeats|
 |[ADR-10](adr/ADR-10.md)|server, client, jetstream|JetStream Extended Purge|
 |[ADR-12](adr/ADR-12.md)|jetstream|JetStream Encryption At Rest|
 |[ADR-13](adr/ADR-13.md)|jetstream, client|Pull Subscribe internals|
-|[ADR-15](adr/ADR-15.md)|jetstream, client|JetStream Subscribe Workflow|
 |[ADR-17](adr/ADR-17.md)|jetstream, client|Ordered Consumer|
-|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views:|
-|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore|JetStream based Object Stores|
+|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views|
+|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore, spec|JetStream based Object Stores|
 |[ADR-22](adr/ADR-22.md)|jetstream, client|JetStream Publish Retries on No Responders|
 |[ADR-28](adr/ADR-28.md)|jetstream, server|JetStream RePublish|
 |[ADR-31](adr/ADR-31.md)|jetstream, client, server|JetStream Direct Get|
 |[ADR-33](adr/ADR-33.md)|jetstream, client, server|Metadata for Stream and Consumer|
 |[ADR-34](adr/ADR-34.md)|jetstream, client, server|JetStream Consumers Multiple Filters|
 |[ADR-36](adr/ADR-36.md)|jetstream, client, server|Subject Mapping Transforms in Streams|
-|[ADR-37](adr/ADR-37.md)|jetstream, client|JetStream Simplification|
+|[ADR-37](adr/ADR-37.md)|jetstream, client, spec|JetStream Simplification|
+|[ADR-42](adr/ADR-42.md)|jetstream, server|Pull Consumer Priority Groups|
+|[ADR-43](adr/ADR-43.md)|jetstream, client, server|JetStream Per-Message TTL|
+|[ADR-44](adr/ADR-44.md)|jetstream, server|Versioning for JetStream Assets|
 
 ## Kv
 
 |Index|Tags|Description|
 |-----|----|-----------|
-|[ADR-8](adr/ADR-8.md)|jetstream, client, kv|JetStream based Key-Value Stores|
-|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views:|
+|[ADR-8](adr/ADR-8.md)|jetstream, client, kv, spec|JetStream based Key-Value Stores|
+|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views|
 
 ## Objectstore
 
 |Index|Tags|Description|
 |-----|----|-----------|
-|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views:|
-|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore|JetStream based Object Stores|
+|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views|
+|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore, spec|JetStream based Object Stores|
 
 ## Observability
 
 |Index|Tags|Description|
 |-----|----|-----------|
 |[ADR-3](adr/ADR-3.md)|observability, server|NATS Service Latency Distributed Tracing Interoperability|
+|[ADR-41](adr/ADR-41.md)|observability, server|NATS Message Path Tracing|
 
 ## Security
 
@@ -110,32 +113,40 @@ This repo is used to capture architectural and design decisions as a reference o
 |[ADR-36](adr/ADR-36.md)|jetstream, client, server|Subject Mapping Transforms in Streams|
 |[ADR-38](adr/ADR-38.md)|server, security|OCSP Peer Verification|
 |[ADR-39](adr/ADR-39.md)|server, security|Certificate Store|
+|[ADR-40](adr/ADR-40.md)|client, server, spec|NATS Connection|
+|[ADR-41](adr/ADR-41.md)|observability, server|NATS Message Path Tracing|
+|[ADR-42](adr/ADR-42.md)|jetstream, server|Pull Consumer Priority Groups|
+|[ADR-43](adr/ADR-43.md)|jetstream, client, server|JetStream Per-Message TTL|
+|[ADR-44](adr/ADR-44.md)|jetstream, server|Versioning for JetStream Assets|
 
-## When to write an ADR
+## Spec
 
-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.
+|Index|Tags|Description|
+|-----|----|-----------|
+|[ADR-8](adr/ADR-8.md)|jetstream, client, kv, spec|JetStream based Key-Value Stores|
+|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore, spec|JetStream based Object Stores|
+|[ADR-32](adr/ADR-32.md)|client, spec|Service API|
+|[ADR-37](adr/ADR-37.md)|jetstream, client, spec|JetStream Simplification|
+|[ADR-40](adr/ADR-40.md)|client, server, spec|NATS Connection|
 
-For a background of the rationale driving ADRs see [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by
-Michael Nygard
+## Deprecated
 
-## Template
+|Index|Tags|Description|
+|-----|----|-----------|
+|[ADR-15](adr/ADR-15.md)|deprecated|JetStream Subscribe Workflow|
 
-Please see the [template](adr-template.md). 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.
+## When to write an ADR
 
-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.
+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
+ 1. Guidance on conventions and design such as ADR-6 which documents all the valid naming rules
+ 1. Capturing design that might impact many areas of the system such as ADR-2
 
-## Related Repositories
+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.
 
- * Server [nats-server](https://github.com/nats-io/nats-server)
- * Reference implementation [nats.go](https://github.com/nats-io/nats.go)
- * Java Client [nats.java](https://github.com/nats-io/nats..java)
- * .NET / C# client [nats.net](https://github.com/nats-io/nats.net)
- * JavaScript [nats.ws](https://github.com/nats-io/nats.ws) [nats.deno](https://github.com/nats-io/nats.deno)
- * C Client [nats.c](https://github.com/nats-io/nats.c)
- * Python3 Client for Asyncio [nats.py](https://github.com/nats-io/nats.py)
+## Template
 
-### Client Tracking
+Please see the [template](adr-template.md). 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.
 
-There is a [Client Feature Parity](https://docs.google.com/spreadsheets/d/1VcYcKqwOp8h8zZwNSRXMS5wrdA1jZz6AumMTHZbXrmY/edit#gid=1032495336) spreadsheet that tracks the clients somewhat, but it is not guaranteed to be complete or up to date.
+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.
diff --git a/adr-template.md b/adr-template.md
@@ -1,11 +1,15 @@
 # Title
 
-|Metadata|Value|
-|--------|-----|
-|Date    |YYYY-MM-DD|
-|Author  |@<github user>, @<github user>|
-|Status  |`Proposed`, `Approved` `Partially Implemented`, `Implemented`|
-|Tags    |jetstream, client, server|
+| Metadata | Value                                                           |
+|----------|-----------------------------------------------------------------|
+| Date     | YYYY-MM-DD                                                      |
+| Author   | @<github user>, @<github user>                                  |
+| Status   | `Approved` `Partially Implemented`, `Implemented`, `Deprecated` |
+| Tags     | jetstream, client, server                                       |
+
+| Revision | Date       | Author  | Info           |
+|----------|------------|---------|----------------|
+| 1        | YYYY-MM-DD | @author | Initial design |
 
 ## Context and Problem Statement
 

diff --git a/adr/ADR-15.md b/adr/ADR-15.md
@@ -1,11 +1,17 @@
 # JetStream Subscribe Workflow
 
-|Metadata|Value|
-|--------|-----|
-|Date    |2021-08-11|
-|Author  |@kozlovic|
-|Status  |Partially Implemented|
-|Tags    |jetstream, client|
+| Metadata | Value      |
+|----------|------------|
+| Date     | 2021-08-11 |
+| Author   | @kozlovic  |
+| Status   | Deprecated |
+| Tags     | deprecated |
+
+## Revision History
+
+| Revision | Date       | Description                  |
+|----------|------------|------------------------------|
+| final    | 2024/07/17 | Deprecate in favor of ADR-37 |
 
 ## Context