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.
139 lines
6.3 KiB
Markdown
139 lines
6.3 KiB
Markdown
# 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.
|