natsnet/docs/plans/2026-02-27-batch-4-logging-design.md

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.