natsnet/docs/plans/2026-02-27-batch-3-sendq-service-client-proxyproto-design.md

Batch 3 (SendQ, Service, Client ProxyProto) Design

Date: 2026-02-27
Scope: Design only for Batch 3 implementation planning (18 features, 1 test).

Context Snapshot

Batch metadata (from porting.db):

• Batch ID: 3
• Name: SendQ, Service, Client ProxyProto
• Features: 18
• Tests: 1
• Dependency: Batch 1
• Go files: server/client_proxyproto.go, server/sendq.go, server/service.go, server/service_windows.go

Batch 3 feature sets:

• Proxy protocol (8): 574-581
• Send queue (3): 2971-2973
• Service (7): 3148-3154
• Tracked test (1): 2832 (TestRoutePoolRouteStoredSameIndexBothSides)

Current Code Findings

1. Proxy protocol behavior is mostly present in .NET:
   • dotnet/src/ZB.MOM.NatsNet.Server/Protocol/ProxyProtocol.cs
   • dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Protocol/ProxyProtocolTests.cs
2. ClientConnection.RemoteAddress() exists, but Batch 3 maps proxyConn.RemoteAddr and parser methods to ClientConnection-named methods.
3. Send queue is not implemented as a concrete type yet:
   • Account.SendQueue is currently object? with TODO note.
4. Service wrappers are partly represented by Internal/SignalHandler.cs (Run, IsWindowsService), but Batch 3 maps to ServiceManager and Windows-specific service functions.
5. The tracked test #2832 maps to RouteHandlerTests, but current route backlog tests are mostly placeholder-style and do not yet include this scenario.

Constraints and Success Criteria

• Follow .NET 10 + xUnit 3 + Shouldly + NSubstitute standards.
• No fake/stub implementations to satisfy status updates.
• Every feature/test status change must be evidence-backed (build + related tests + source parity).
• Batch 3 completion should leave all 19 items in verified, complete, or n_a only when justified.

Approach Options

Approach A: Strict file-by-file Go shape port

Create direct C# equivalents for all four Go files with minimal reuse of existing .NET code.

• Pros: Strong visual parity with Go source.
• Cons: Duplicates already-ported proxy logic; higher regression risk; unnecessary churn.

Approach B: Tracker-only remap/status promotion

Avoid code movement; rely on current behavior and update statuses aggressively.

• Pros: Fastest short-term status movement.
• Cons: High audit risk, likely mapping mismatches, and weak behavioral evidence.

Approach C (Recommended): Compatibility-layer parity with evidence-first verification

Reuse existing .NET behavior where already correct (proxy parser and signal handling), add compatibility wrappers/classes to satisfy mapped Batch 3 entry points (ClientConnection, SendQueue, ServiceManager), and add focused tests for each group before status promotion.

• Pros: Lowest risk path to real parity and audit compliance.
• Cons: Requires disciplined verification and selective wrapper design.

Recommended Design

1. Proxy protocol group (574-581)

• Keep Protocol/ProxyProtocol.cs as the behavioral core.
• Add a ClientConnection partial shim exposing mapped method names (RemoteAddr, DetectProxyProtoVersion, ReadProxyProtoV1Header, ReadProxyProtoHeader, ReadProxyProtoV2Header, ParseProxyProtoV2Header, ParseIPv4Addr, ParseIPv6Addr) that delegate to the parser core.
• Extend ProxyProtocolTests only where mapping-specific behavior lacks direct assertion.

2. Send queue group (2971-2973)

• Introduce concrete SendQueue implementation (newSendQ, InternalLoop, Send) using existing IpQueue<T> and internal client plumbing (CreateInternalSystemClient).
• Replace Account.SendQueue placeholder type from object? to concrete queue type.
• Add focused unit tests for queue push/pop, no-op on null queue, and internal loop dispatch semantics.

3. Service group (3148-3154)

• Create ServiceManager abstraction as mapped Batch 3 surface.
• Non-Windows path: Run delegates to start action; IsWindowsService returns false.
• Windows-specific entries (SetServiceName, Init, Execute, Windows Run, Windows IsWindowsService) use one of two evidence-backed outcomes:
  • implemented wrapper behavior where runtime-checkable, or
  • explicit n_a classification when host-level Windows service integration is intentionally owned by Microsoft.Extensions.Hosting.WindowsServices and not by server library.
• Add/extend tests to verify non-Windows and wrapper semantics.

4. Tracked test group (2832)

• Implement real RoutePoolRouteStoredSameIndexBothSides_ShouldSucceed only if route-pool prerequisites are available in current server runtime.
• If infrastructure is still missing, keep test deferred with explicit reason and no fake assertions.

Risk Register and Mitigations

1. Mapping mismatch despite correct behavior
   • Mitigation: compatibility shim methods with mapped names on mapped classes.
2. Stub creep while filling gaps quickly
   • Mitigation: mandatory stub scans on touched files after each feature group.
3. Windows-service ambiguity
   • Mitigation: explicit decision tree (verified wrapper vs n_a with evidence) captured per feature ID.
4. Route test false positives
   • Mitigation: require non-trivial assertions and actual route index comparison; otherwise defer with reason.

Design Outcome

Proceed with Approach C in three feature groups plus one test group, each with strict evidence gates, explicit anti-stub checks, and controlled status updates.