# Batch 4 (Logging) Design

**Date:** 2026-02-27  
**Scope:** Design for Batch 4 implementation planning only (11 features, 31 tests).

## Context Snapshot

Batch metadata (from `porting.db`):

- Batch ID: `4`
- Name: `Logging`
- Features: `11` (all currently `deferred`)
- Tests: `31` (all currently `deferred`)
- Dependency: `Batch 1`
- Go source: `server/log.go`

PortTracker command snapshot:

- `batch show 4` confirms feature IDs: `2050,2052,2053,2054,2057,2058,2059,2061,2062,2063,2067`
- `batch show 4` confirms test IDs: `622,623,643,678,1906,1911,1916,1917,1922,1940,1947,1954,1971,1973,1977,1991,2000,2188,2270,2469,2506,2820,2826,2827,2828,2834,2847,2848,3104,3110,3130`
- `report summary` shows the repository is mixed-state (`verified`, `deferred`, `n_a`) with Batch 4 still pending.

## Current Code Findings

1. `dotnet/src/ZB.MOM.NatsNet.Server/Internal/NatsLogger.cs` already implements most `log.go` behavior in `ServerLogging` (set logger flags, execute log call, error convenience methods, rate-limited warn/debug).
2. `NatsServer` still lacks the mapped Batch 4 `NatsServer` method surface (`ConfigureLogger`, `SetLogger`, `SetLoggerV2`, `ReOpenLogFile`, `Errors`, `Errorc`, `Errorsc`, `RateLimit*`, `ExecuteLogCall`).
3. `NatsServer` currently uses `ILogger` fields directly (`_logger`, `_debugEnabled`, `_traceEnabled`, `_traceSysAcc`), so the Batch 4 implementation must preserve compatibility with existing callers.
4. Batch 4 mapped tests point to `ImplBacklog` classes in:
   - `GatewayHandlerTests.Impltests.cs`
   - `LeafNodeHandlerTests.Impltests.cs`
   - `MqttHandlerTests.Impltests.cs`
   - `ConcurrencyTests1.Impltests.cs`
   - `ConcurrencyTests2.Impltests.cs`
   - `RouteHandlerTests.Impltests.cs`
   - `WebSocketHandlerTests.Impltests.cs`
5. Existing backlog tests in those files are mostly shallow placeholders and need real behavior assertions for Batch 4 IDs instead of synthetic constant checks.

## Constraints and Success Criteria

Constraints:

- Follow .NET standards and toolchain already used by this repo.
- Plan must enforce mandatory verification protocol and anti-stub controls for both features and tests.
- Feature/test status changes must be evidence-based with max 15 IDs per batch update.
- No implementation in this design step; planning only.

Success criteria:

- All 11 Batch 4 features implemented on `NatsServer` with `log.go` parity.
- Batch 4 test methods are real tests (or explicitly deferred with concrete blockers).
- No feature marked `verified` without passing related test gates.
- No placeholder/stub code promoted as complete.

## Approach Options

### Approach A: Keep `NatsServer` logging as-is and update statuses only

- Pros: fastest paperwork.
- Cons: fails parity goals and verification gates; high audit risk.

### Approach B: Replace `NatsServer` logging internals entirely with `ServerLogging`

- Pros: direct reuse of existing `Internal/NatsLogger.cs`.
- Cons: larger refactor risk for existing `ILogger` call sites and `INatsServer.Logger` consumers.

### Approach C (Recommended): Add `NatsServer` logging partial with adapter bridge

- Keep existing `ILogger`-based behavior compatible.
- Implement mapped Batch 4 methods in a dedicated `NatsServer.Logging.cs` partial.
- Bridge `INatsLogger <-> ILogger` using `MicrosoftLoggerAdapter`.
- Port Batch 4 tests in mapped backlog classes with real Arrange/Act/Assert semantics.

Why this is recommended: it achieves Go parity for mapped methods with minimal disruption to already-ported code paths.

## Recommended Design

### 1. Production Surface

- Add `NatsServer` partial for Batch 4 APIs:
  - `ConfigureLogger`
  - `SetLogger`
  - `SetLoggerV2`
  - `ReOpenLogFile`
  - `Errors`
  - `Errorc`
  - `Errorsc`
  - `RateLimitFormatWarnf`
  - `RateLimitWarnf`
  - `RateLimitDebugf`
  - `ExecuteLogCall`
- Preserve current `ILogger Logger` property and existing call sites.
- Use lock + atomic patterns consistent with current server style.

### 2. Logger Configuration Strategy

- `ConfigureLogger` reads `ServerOptions` and selects logger backend behavior by precedence:
  1. `NoLog` => no-op/null logging
  2. `LogFile` => file-backed logger path (or explicit deferred reason if host constraint blocks parity)
  3. `RemoteSyslog`/`Syslog` => explicit behavior branch with documented platform policy
  4. default => standard logger path
- `SetLoggerV2` and `SetLogger` update debug/trace/system-trace flags and replace prior logger safely.
- `ReOpenLogFile` only reopens when file logging is active; otherwise logs ignore notice.

### 3. Test Strategy for 31 Batch 4 Tests

- Port only mapped IDs in their mapped classes with real behavior:
  - Gateway/Route reconnection and duplicate-name scenarios validate expected log warnings/errors.
  - Leaf/MQTT scenarios validate logger interactions tied to option/auth/reconnect paths.
  - Concurrency/WebSocket scenarios validate log emission and suppression under failure/loop paths.
- If runtime topology requirements are unavailable in current harness, keep test `deferred` with explicit reason and evidence.

### 4. Grouping Strategy

Feature groups (both <=20):

- **F1 Core Logger Wiring (5):** `2050,2052,2053,2054,2067`
- **F2 Error + Rate-Limit Helpers (6):** `2057,2058,2059,2061,2062,2063`

Test groups:

- **T1 Gateway + Route (11):** `622,623,643,678,2820,2826,2827,2828,2834,2847,2848`
- **T2 Leaf + MQTT (15):** `1906,1911,1916,1917,1922,1940,1947,1954,1971,1973,1977,1991,2000,2188,2270`
- **T3 Concurrency + WebSocket (5):** `2469,2506,3104,3110,3130`

### 5. Risk Register

1. Existing `ILogger` call paths regress if adapter bridge is intrusive.
   - Mitigation: keep `ILogger` as source of truth and isolate new mapped methods in partial file.
2. Backlog test quality regresses into synthetic assertions.
   - Mitigation: mandatory anti-stub scans and per-test verification loop.
3. Infra-heavy tests cannot run in local harness.
   - Mitigation: explicit defer protocol with blocker evidence; no fake passes.
4. Status drift between code and `porting.db`.
   - Mitigation: capped chunked updates with evidence before each update command.

## Design Outcome

Proceed with **Approach C** and execute in two feature groups plus three test groups under strict verification gates. The implementation plan will enforce mandatory verification protocol and anti-stub guardrails for both production features and mapped tests.