# 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.