b928be4f2f
Generated design docs and implementation plans via Codex for: - Batch 1: Proto, Const, CipherSuites, NKey, JWT - Batch 2: Parser, Sublist, MemStore remainders - Batch 3: SendQ, Service, Client ProxyProto - Batch 4: Logging - Batch 5: JetStream Errors - Batch 8: Store Interfaces All plans include mandatory verification protocol and anti-stub guardrails. Updated batches.md with file paths and planned status.
107 lines
5.4 KiB
Markdown
107 lines
5.4 KiB
Markdown
# 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.
|