diff --git a/docs/plans/2026-02-23-nats-post-strict-full-go-parity-design.md b/docs/plans/2026-02-23-nats-post-strict-full-go-parity-design.md new file mode 100644 index 0000000..83249b2 --- /dev/null +++ b/docs/plans/2026-02-23-nats-post-strict-full-go-parity-design.md @@ -0,0 +1,142 @@ +# NATS Post-Strict Full Go Parity Design + +**Date:** 2026-02-23 +**Status:** Approved +**Scope:** Identify and close all remaining NATS functionality/features versus local Go HEAD (`golang/nats-server/server`) using behavior-level parity with test evidence. + +## 1. Architecture and Scope Boundary + +### Parity model +Each capability is considered complete only when all of the following are true: + +1. Behavior +Observable .NET runtime behavior matches the Go contract. + +2. Tests +Positive and edge/failure tests exist and fail on regression. + +3. Docs +`differences.md` and parity artifacts reflect verified behavior state. + +### Scope rule +This cycle is not constrained by existing parity-table status values. Residual behavior differences inferred from code depth, runtime paths, and subsystem contracts are in scope even when rows are currently marked `Y`. + +### Execution waves +1. Protocol/inter-server/account delivery semantics +2. MQTT full protocol/runtime semantics +3. JetStream runtime/state-machine semantics +4. RAFT/cluster governance + storage durability semantics +5. Operational/config/runtime drift closure and docs synchronization + +### Completion gate +Done is defined as feature-by-feature .NET behavioral parity evidence (targeted + full suite), not mandatory direct Go suite equivalence. + +## 2. Component Plan and Remaining Capability Groups + +### A. Core protocol and inter-server semantics +Primary files: +- `src/NATS.Server/NatsServer.cs` +- `src/NATS.Server/Routes/*` +- `src/NATS.Server/Gateways/*` +- `src/NATS.Server/LeafNodes/*` +- `src/NATS.Server/Subscriptions/SubList.cs` + +Remaining group: +- deep account-aware forwarding semantics +- advanced interest/topology behavior beyond baseline frame propagation + +### B. MQTT full parity +Primary files: +- `src/NATS.Server/Mqtt/*` +- `src/NATS.Server/MqttOptions.cs` +- integration points in auth/config/server startup paths + +Remaining group: +- behavior depth still below Go MQTT subsystem semantics despite packet/QoS/session/auth baseline +- requires broader protocol/runtime contract coverage + +### C. JetStream runtime/service depth +Primary files: +- `src/NATS.Server/JetStream/JetStreamService.cs` +- `src/NATS.Server/JetStream/StreamManager.cs` +- `src/NATS.Server/JetStream/ConsumerManager.cs` +- `src/NATS.Server/JetStream/Consumers/*` +- `src/NATS.Server/JetStream/MirrorSource/*` + +Remaining group: +- simplified manager/service behavior relative to Go stream/consumer runtime depth +- needs stricter long-run invariants and edge-state handling + +### D. RAFT, JetStream governance, and storage +Primary files: +- `src/NATS.Server/Raft/*` +- `src/NATS.Server/JetStream/Cluster/*` +- `src/NATS.Server/JetStream/Storage/*` + +Remaining group: +- broader convergence/placement/membership semantics +- deeper durability and consistency guarantees under restart/failure scenarios + +### E. Operational/config/runtime parity +Primary files: +- `src/NATS.Server/NatsOptions.cs` +- `src/NATS.Server/Configuration/*` +- `src/NATS.Server/Monitoring/*` +- `src/NATS.Server/Events/*` + +Remaining group: +- config surface vs runtime behavior depth mismatches +- monitoring/operations parity consistency closure + +### F. Evidence/documentation +Primary files: +- `differences.md` +- `docs/plans/2026-02-23-nats-strict-full-go-parity-map.md` +- `docs/plans/2026-02-23-jetstream-remaining-parity-map.md` +- `docs/plans/2026-02-23-jetstream-remaining-parity-verification.md` + +Remaining group: +- synchronize claims with measurable behavior and test evidence + +## 3. Data Flow and Behavioral Contracts + +1. Inter-server routing contract +- account-scoped interest and delivery must remain correct under churn/reconnect/replay +- transport markers/remaps remain internal and reversible + +2. MQTT protocol/runtime contract +- packet framing/encoding correctness and session/QoS/ack state-machine consistency +- auth/tls/account mapping fail closed on invalid state + +3. JetStream stream/consumer contract +- retention mode semantics diverge at runtime behavior +- deterministic cursor/ack/redelivery/backoff/replay/flow transitions +- mirror/source behavior respects account/filter/transform contracts + +4. RAFT/governance/storage contract +- quorum-gated commit visibility, term safety, and convergence +- snapshot/membership/placement semantics reflect committed state +- storage invariants hold across prune/recovery/restart paths + +5. Documentation contract +- no closure claim without behavior+test evidence +- deferred items must be explicit and evidence-backed + +## 4. Error Handling, Testing Strategy, and Completion Gates + +### Error handling +1. Preserve protocol-specific error semantics (NATS, MQTT, JetStream). +2. Fail closed on account/auth/consensus violations. +3. Avoid partial state mutation on multi-step cross-subsystem operations. + +### Testing strategy +1. Test-first for every capability. +2. Require happy-path + edge/failure coverage per capability. +3. Use integration tests for inter-server, MQTT runtime, RAFT/cluster, and restart durability semantics. +4. Use focused unit tests for deterministic parser/state primitives. + +### Completion gates +1. Capability closes only when Behavior + Tests + Docs are complete. +2. Focused wave suites pass and full suite passes: +- `dotnet test -v minimal` +3. Documentation artifacts are synchronized to verified runtime behavior.