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.