143 lines
5.2 KiB
Markdown
143 lines
5.2 KiB
Markdown
# 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.
|