natsnet/docs/plans/2026-02-27-batch-24-leaf-nodes-design.md

Batch 24 Leaf Nodes Design

Date: 2026-02-27
Batch: 24 (Leaf Nodes)
Scope: Design only. No implementation in this document.

Problem

Batch 24 ports leaf-node connection handling from golang/nats-server/server/leafnode.go into the .NET server.

• Features: 67 (all currently deferred)
• Tests: 2 (both currently deferred)
• Dependencies: batches 19 and 23
• Go source: server/leafnode.go
• Batch status: pending

Leaf-node behavior touches client protocol parsing, solicited/accepted leaf lifecycle, account interest propagation, and cross-cluster subscription semantics.

Context Findings

Collected with:

• dotnet run --project tools/NatsNet.PortTracker -- batch show 24 --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

Additional repository findings:

• .NET already has leaf data models in dotnet/src/ZB.MOM.NatsNet.Server/LeafNode/LeafNodeTypes.cs (Leaf, LeafNodeCfg, LeafConnectInfo) but the Batch 24 behavior surface is largely unimplemented.
• ClientConnection currently has explicit leaf placeholders (IsHubLeafNode, RemoteCluster) and parser-level leaf argument helpers still marked as stubs/delegates.
• LeafNodeHandlerTests.Impltests.cs and RouteHandlerTests.Impltests.cs still contain placeholder-style tests and do not currently include the two Batch 24 mapped methods.
• Batch 24 mapped tests are:
  • 1966 (LeafNodeHandlerTests.LeafNodeRoutedSubKeyDifferentBetweenLeafSubAndRoutedSub_ShouldSucceed)
  • 2825 (RouteHandlerTests.ClusterQueueGroupWeightTrackingLeak_ShouldSucceed)

Constraints and Success Criteria

Constraints:

• Follow project standards in docs/standards/dotnet-standards.md.
• Keep behavior equivalent to Go intent, but idiomatic C# (.NET 10, nullable enabled).
• No placeholder implementations, no fake-pass tests, no status promotion without evidence.
• Feature work must be grouped into chunks of <= ~20 features.
• Batch 24 execution must wait for dependency readiness (batches 19 and 23).

Success criteria:

• All 67 features are either implemented and verified, or explicitly deferred with a concrete blocker reason.
• Both mapped tests are implemented as real behavioral tests and pass.
• Leaf-related parser/account regression tests pass before complete -> verified.
• Batch 24 can be completed through PortTracker without overrides for unverifiable work.

Approaches

Approach A: Single monolithic leaf file

Implement all 67 methods in one large NatsServer.LeafNodes.cs and keep most ClientConnection work in ClientConnection.cs.

Trade-offs:

• Pros: fewer files to navigate.
• Cons: very high review risk, difficult evidence tracking, poor checkpoint isolation.

Approach B (Recommended): Domain-segmented partials by leaf lifecycle stage

Split implementation by responsibility:

1. Leaf validation/config/bootstrap
2. Connect/handshake/lifecycle
3. Interest propagation/account/subscription maps
4. Message/sub/unsub processing and websocket solicit path

Trade-offs:

• Pros: aligns to leafnode.go sections, cleaner verification gates, easier status chunking and rollback.
• Cons: more file coordination.

Approach C: Test-first only on mapped tests, then fill remaining features

Start with the two mapped tests and then backfill features.

Trade-offs:

• Pros: immediate test signal.
• Cons: two tests under-cover 67 features, making false confidence likely unless strict feature-level verification is enforced.

Recommended Design

Use Approach B with four feature groups (18/18/14/17 IDs) mapped to Go line ranges and .NET class ownership.

Architecture

• ClientConnection partials handle leaf protocol parsing, leaf connect payload processing, sub/unsub deltas, permission violations, and websocket solicitation.
• NatsServer partials handle remote solicitation, outbound reconnect/connect loops, listener accept loop, leaf info dissemination, and connection registration lifecycle.
• LeafNode helper surface (LeafNodeHandler + LeafNodeCfg methods) centralizes validation and key generation utilities used by both server and client paths.
• Account updates cover UpdateLeafNodesEx semantics and gateway/leaf interest propagation coupling.

Proposed File Map

Primary production files:

• Create: dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.LeafNodes.cs
• Create: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.LeafNodes.ConfigAndConnect.cs
• Create: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.LeafNodes.Subscriptions.cs
• Create: dotnet/src/ZB.MOM.NatsNet.Server/LeafNode/LeafNodeHandler.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/LeafNode/LeafNodeTypes.cs (for LeafNodeCfg method surface)
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/Protocol/ProtocolParser.cs
• Modify (as needed): dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs

Mapped test files:

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

Related regression tests:

• dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Protocol/ProtocolParserTests.cs
• dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Accounts/ResolverDefaultsOpsTests.cs
• dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ClientTests.cs

Data and Control Flow

• Outbound flow: configured remote leaf nodes -> validate -> pick URL -> connect/proxy/ws path -> leaf CONNECT/INFO handshake -> register connection -> initialize subscription map.
• Inbound flow: accept loop -> create leaf client -> process INFO/CONNECT -> negotiate compression/perms -> account registration and interest sync.
• Interest propagation: account sub changes -> leaf smap deltas -> leaf SUB/UNSUB protocol emission -> inbound leaf message/sub updates -> permission enforcement.

Error Handling Strategy

• Preserve Go failure modes for malformed protocol args, invalid remote config, and loop/duplicate detection paths.
• Prefer explicit guard clauses with clear exceptions over silent default returns.
• On infrastructure blockers, defer with reason rather than introducing placeholders.

Verification Strategy

• Enforce per-feature verification loop (Go read, C# implementation, build, related test run).
• Enforce group-level stub scans and build gate before any stub -> complete.
• Enforce full leaf-related test gate before any complete -> verified.
• Enforce checkpoint protocol (full build + full tests + commit) between every task.

Risks and Mitigations

• Risk: race-prone account/smap updates regress existing account behavior.
  • Mitigation: isolate account update logic and require ResolverDefaultsOpsTests in every verification wave.
• Risk: parser and runtime leaf arg handling diverge.
  • Mitigation: keep parser and client leaf arg updates in the same feature group and verify via ProtocolParserTests.
• Risk: backlog tests remain placeholders and create false green.
  • Mitigation: mandatory anti-stub scans and method-level filters for mapped tests.

Design Approval Basis

This design is based on Batch 24 metadata from PortTracker, existing Batch 0 verification standards, and explicit requirements for feature+test anti-stub guardrails and grouped execution.