natsnet/docs/plans/2026-02-27-batch-23-routes-design.md

Batch 23 Routes Design

Date: 2026-02-27
Batch: 23 (Routes)
Scope: Design only. No implementation in this document.

Problem

Batch 23 ports NATS route/cluster behavior from golang/nats-server/server/route.go into .NET.

• Features: 52 (currently deferred)
• Tests: 5 (currently deferred)
• Dependencies: batches 16, 18
• Go source: server/route.go
• Batch status: pending

This batch is the route control plane: route connect negotiation, route INFO gossip, per-account route subscriptions, route pooling, route lifecycle, and compression negotiation.

Context Findings

Collected with:

• dotnet run --project tools/NatsNet.PortTracker -- batch show 23 --db porting.db
• dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db
• dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db

Key findings:

• Most Batch 23 methods do not yet exist in .NET runtime code.
• Existing route surface in .NET is mostly type definitions (Routes/RouteTypes.cs) and some route-adjacent stubs in NatsServer.Lifecycle.cs.
• The 5 mapped tests are all in RouteHandlerTests and currently deferred.
• Existing ProtocolParserTests and ServerTests already cover route-adjacent parser/compression helpers and should be part of the feature verification gate.

Constraints and Success Criteria

Constraints:

• Follow .NET 10 and project standards (xUnit 3, Shouldly, NSubstitute, no FluentAssertions/Moq).
• Keep implementation idiomatic C# while preserving Go behavior semantics.
• No placeholder implementations or fake-pass tests.
• Feature groups must be <= ~20 features.
• Batch status changes require evidence and guarded update cadence.

Success criteria:

• All 52 Batch 23 features are implemented and promoted with evidence (deferred -> stub -> complete -> verified) or explicitly deferred with blocker reason.
• All 5 mapped Batch 23 tests are real behavioral tests and passing.
• Route-related regression gates pass (ProtocolParserTests, ServerTests, lifecycle route tests, and mapped route ImplBacklog tests).

Approaches

Approach A: Single large route partial

Implement all route behavior in one large NatsServer.Routes.cs + one ClientConnection.Routes.cs file.

Trade-offs:

• Pros: fewer files.
• Cons: very large diff, difficult review, high regression risk, weak checkpointing.

Approach B (Recommended): Domain-segmented route partials

Split route implementation into bounded domains aligned with route.go sections and Batch 23 grouping.

Trade-offs:

• Pros: clear ownership boundaries, strong per-group build/test gates, easier status evidence, lower merge risk.
• Cons: more files and more coordination.

Approach C: Tests-first for all 5 mapped tests before feature work

Rewrite all five mapped tests first, then implement features until tests pass.

Trade-offs:

• Pros: immediate test signal.
• Cons: only 5 mapped tests under-cover 52 features, so this risks false confidence without strict per-feature verification.

Recommended Design

Use Approach B.

Architecture

Organize Batch 23 into three feature domains:

1. Route protocol parsing and permission handling (inbound route msgs, account sub/unsub, permission checks, route info processing)
2. Route subscription propagation and route creation pipeline (remote sub/unsub map operations, protocol emission, route object creation)
3. Route lifecycle and cluster connectivity (start routing, reconnect/validate routes, duplicate handling, gossip/implicit route handling, route iteration helpers)

Mapped tests are executed after feature groups, with additional regression gates from parser/server test classes before complete -> verified promotion.

Proposed File Map

Primary production files:

• Create: dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.Routes.cs
• Create: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Routes.InfoAndPerms.cs
• Create: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Routes.Subscriptions.cs
• Create: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Routes.Connections.cs
• Create: dotnet/src/ZB.MOM.NatsNet.Server/Routes/RouteHandler.cs
• Modify (as needed): dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs
• Modify (as needed): dotnet/src/ZB.MOM.NatsNet.Server/Protocol/IProtocolHandler.cs
• Modify (as needed): dotnet/src/ZB.MOM.NatsNet.Server/Protocol/ProtocolParser.cs
• Modify (as needed): dotnet/src/ZB.MOM.NatsNet.Server/Routes/RouteTypes.cs

Primary mapped test files:

• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs

Related regression test files:

• dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Protocol/ProtocolParserTests.cs
• dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ServerTests.cs
• dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/ServerLifecycleStubFeaturesTests.cs

Data and Control Flow

• Route connection establishment: connect -> route CONNECT/INFO exchange -> route registration -> sub interest sync.
• Route message path: parse routed protocol args -> permission checks -> route/local interest updates -> inbound delivery handling.
• Route topology updates: implicit route processing + forwarding new route info to known remotes + duplicate-route handling.

Error Handling Strategy

• Mirror Go error semantics for parse and negotiation failures (return error / close connection path).
• Use explicit guard clauses for malformed protocols and invalid route state transitions.
• Keep blocked infrastructure behavior deferred with explicit reason instead of stubs.

Verification Strategy

• Per-feature loop: read Go implementation, implement minimum C# behavior, build, run smallest related tests, record evidence.
• Per-group gates: mandatory stub scan, build gate, targeted test gate.
• Pre-verify gate: all related route test classes and mapped tests must pass before promoting any Batch 23 feature to verified.

Risks and Mitigations

• Risk: Route lifecycle races/regressions due lock-sensitive logic.
  • Mitigation: keep route iteration/removal code in focused partials; include lifecycle regression tests in every gate.
• Risk: Placeholder test ports in ImplBacklog produce false green.
  • Mitigation: explicit anti-stub scans and assertion quality checks before status updates.
• Risk: Large route.go surface causes drift in status updates.
  • Mitigation: strict ID chunking (<=15 per update) and evidence ledger per update.

Design Approval Basis

This design is derived from the explicit request for Batch 23 planning, mandatory verification protocol parity with Batch 0, anti-stub guardrails, and grouped execution without implementation.