natsnet/docs/plans/2026-02-27-batch-18-server-core-design.md

# Batch 18 (Server Core) Design

**Date:** 2026-02-27  
**Scope:** Design only for Batch 18 (`server/server.go`): 10 features and 8 tests.

## Context Snapshot

Batch metadata from PortTracker (`batch show 18`):

- Batch ID: `18`
- Name: `Server Core`
- Dependencies: batches `4`, `16`
- Go file focus: `golang/nats-server/server/server.go`
- Features: `10` (all currently `deferred`)
- Tests: `8` (all currently `deferred`)

Feature IDs in scope:

- `2982` `s2WriterOptions`
- `2987` `Server.logRejectedTLSConns`
- `3048` `Server.fetchAccount`
- `3066` `Server.getMonitoringTLSConfig`
- `3068` `Server.HTTPHandler`
- `3078` `tlsTimeout`
- `3088` `Server.numRemotes`
- `3112` `Server.readyForConnections`
- `3118` `Server.String`
- `3119` `setGoRoutineLabels`

Test IDs in scope:

- `2111` `TestMonitorHandler`
- `2167` `BenchmarkXMQTT`
- `2382` `TestNoRaceAccountAddServiceImportRace`
- `2467` `TestNoRaceRoutePerAccount`
- `2468` `TestNoRaceRoutePerAccountSubWithWildcard`
- `2481` `TestNoRaceWSNoCorruptionWithFrameSizeLimit`
- `2819` `TestRouteIPResolutionAndRouteToSelf`
- `2897` `TestInsecureSkipVerifyWarning`

Repository progress snapshot (`report summary`):

- Features: `1271 verified`, `2377 deferred`, `24 n_a`, `1 stub`
- Unit tests: `430 verified`, `2640 deferred`, `187 n_a`
- Overall: `1924/6942 (27.7%)`

## Problem Statement

Batch 18 is a narrow but high-leverage seam in `NatsServer`: readiness gates, monitoring handler exposure, TLS timeout/monitor TLS helper behavior, account fetch path naming/parity, and goroutine labeling parity with Go.

The highest risk is false progress from placeholder tests and name-mismatch implementations:

1. Several mapped methods are partially covered by equivalent but differently named C# methods, so Roslyn audit can still keep IDs `deferred`.
2. Existing `ImplBacklog` test files contain low-signal placeholders (string/constant assertions) that can pass without exercising server behavior.
3. Batch 18 tests include benchmark and norace wrappers that may need explicit `deferred` or `n_a` handling instead of fake ports.

## Approaches

### Approach A: Minimal audit-alignment wrappers only

Add exact method names/signatures expected by mappings and delegate to existing logic.

- Pros: fastest path to audit alignment for deferred features.
- Cons: can miss behavior gaps (for example monitor handler lifecycle and readiness semantics).

### Approach B (Recommended): Behavior-first parity by helper cluster

Implement exact mapped methods and close semantic gaps in two feature clusters, then port/triage the 8 tests with strict anti-stub evidence.

- Pros: balances audit alignment and real behavior parity; lower regression risk.
- Cons: slightly more effort than wrappers-only.

### Approach C: Test-first only, defer most features

Start with Batch 18 tests and defer remaining features when they do not immediately block tests.

- Pros: fast test activity.
- Cons: poor feature closure and likely repeated defer/audit churn.

## Recommended Design

### 1. Architecture and File Boundaries

Keep all Batch 18 work in existing `NatsServer` partials and mapped backlog test classes:

- Feature implementation files:
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Listeners.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.cs` (only if a shared type/field is required)
- Test files:
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttExternalTests.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs`

### 2. Feature Grouping Strategy (<=20 per group)

- **Group A (6 features):** `2982,2987,3066,3068,3078,3119`
  - Compression writer options helper, TLS rejection log loop parity, monitoring TLS callback, HTTP handler getter lifecycle, TLS handshake timeout helper, goroutine labels helper.
- **Group B (4 features):** `3048,3088,3112,3118`
  - Account fetch parity helper, `numRemotes` internal parity, readiness check parity, `String()` parity.

### 3. Test Porting/Triage Strategy

- **Test Group T1 (behavioral, target for verify):** `2111,2819,2897`
  - Must execute real server behavior (monitor handler lifecycle, route self-resolution logging path, insecure TLS warning path).
- **Test Group T2 (non-unit or race wrappers):** `2167,2382,2467,2468,2481`
  - Evaluate for direct xUnit viability.
  - If not viable without benchmark tooling/race harness/live infra, keep `deferred` (or set `n_a` when clearly benchmark-only) with explicit reason and zero stubs.

### 4. Verification Design (adapted from Batch 0 protocol)

Execution must use hard gates after each feature/test group:

1. Per-feature loop: read Go function -> implement C# -> build -> run related tests.
2. Stub scans over touched feature and test files.
3. Build/test gates before any status promotion.
4. Status updates in evidence-backed chunks (`<=15` IDs).
5. Task checkpoints with full build + full unit test + commit before next task.

### 5. Risks and Mitigations

1. **Mapped-name vs existing-name mismatch**  
   Mitigation: add exact mapped methods (or wrappers) and keep behavior in one canonical implementation.
2. **Shallow placeholder tests**  
   Mitigation: enforce anti-stub guardrails that reject literal-only assertions and no-act/no-behavior tests.
3. **Benchmark/race test portability limits**  
   Mitigation: explicitly classify as `deferred`/`n_a` with concrete blocker text instead of fake-pass tests.

## Success Criteria

1. All 10 Batch 18 features are `verified` or intentionally `deferred/n_a` with evidence and reasons.
2. All 8 Batch 18 tests are `verified` or intentionally `deferred/n_a` with evidence and reasons.
3. No forbidden stub patterns are introduced in touched feature/test files.
4. Batch updates are auditable and bounded (<=15 IDs per update command).

## Non-Goals

1. No implementation in this design document.
2. No broad refactoring outside Batch 18 server-core scope.
3. No fake benchmark/race replacements that produce green tests without behavioral coverage.