Files

Joseph Doherty f0455a1e45 Add batch plans for batches 6-7, 9-12, 16-17 (rounds 4-7)

Generated design docs and implementation plans via Codex for:
- Batch 6: Opts package-level functions
- Batch 7: Opts class methods + Reload
- Batch 9: Auth, DirStore, OCSP foundations
- Batch 10: OCSP Cache + JS Events
- Batch 11: FileStore Init
- Batch 12: FileStore Recovery
- Batch 16: Client Core (first half)
- Batch 17: Client Core (second half)

All plans include mandatory verification protocol and anti-stub guardrails.
Updated batches.md with file paths and planned status.

2026-02-27 14:56:19 -05:00

7.6 KiB

Raw Blame History

Batch 7 (Opts Class Methods + Reload) Design

Date: 2026-02-27
Scope: Design for Batch 7 planning only (25 features, 63 tests). No implementation in this document.

Context Snapshot

From:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 7 --db porting.db
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db

Current state:

Batch ID: 7
Name: Opts class methods + Reload
Status: pending
Dependency: Batch 6
Go files: server/opts.go, server/reload.go
Features: 25 (all currently deferred)
Tests: 63 (all currently deferred)
Environment note: use /usr/local/share/dotnet/dotnet (dotnet is not on PATH in this workspace)

Relevant .NET baseline:

dotnet/src/ZB.MOM.NatsNet.Server/Config/ReloadOptions.cs contains many reload option types and a ConfigReloader stub, but the core reload pipeline methods mapped in Batch 7 are mostly missing.
dotnet/src/ZB.MOM.NatsNet.Server/Config/ServerOptionsConfiguration.cs contains static config-string/file processing, while Batch 7 maps receiver-style ServerOptions methods from opts.go.
Batch 7 mapped tests are concentrated in ImplBacklog classes and many are placeholder-style and not verification-grade.
LeafNodeProxyTests mapped by Batch 7 does not currently exist in ImplBacklog and must be created.

Problem Statement

Batch 7 is where config parsing receiver methods and live reload orchestration converge. The highest risk is not compilation failure; it is false progress from stubs, shallow tests, or status promotion without evidence. Design must enforce strict feature+test verification and allow explicit deferment for runtime-blocked behaviors instead of fake implementations.

Constraints and Success Criteria

Constraints:

Follow docs/standards/dotnet-standards.md (.NET 10, nullable, xUnit 3 + Shouldly + NSubstitute).
Respect dependency ordering: Batch 7 starts only after Batch 6 is complete.
Feature implementation groups must stay <= ~20 features each.
No placeholder source or placeholder tests can be promoted.

Success criteria:

Batch 7 features are implemented with Go parity (or explicitly deferred with concrete reasons).
Batch 7 tests are real behavioral tests or explicitly deferred with blocker notes.
porting.db status changes are evidence-backed and chunked (<=15 IDs per update call).

Candidate Approaches

Approach A: Keep all work in existing monolith files

Implementation primarily in ReloadOptions.cs and ServerOptions.Methods.cs without introducing new partial files.
Pros: minimal file churn.
Cons: very high review complexity and high risk of accidental stub retention in a large file.

Approach B: Split by responsibility with focused partials (Recommended)

Keep option-type classes in ReloadOptions.cs, but move core reload orchestration to NatsServer.Reload.cs and helper diff/order logic to dedicated config helper partial(s).
Keep ServerOptions receiver-style config entry methods in ServerOptions.Methods.cs (or a dedicated ServerOptions.ConfigProcessing.cs partial).
Pros: direct mapping to Go responsibilities, easier per-feature verification and smaller commits.
Cons: introduces new files and requires careful type visibility.

Approach C: Implement only thin wrappers and defer most reload internals

Adds minimal API surface and marks most runtime methods deferred.
Pros: fastest short-term movement.
Cons: fails batch intent, leaves large reload behavior gap, and pushes risk forward.

Recommended Design

Use Approach B.

1. Feature Decomposition (<=20 each)

F1 Config receiver + reload helper primitives (14): 2510,2511,2513,2514,2815,2816,2839,2873,2875,2877,2878,2886,2887,2888
F2 Reload orchestration and server application path (11): 2869,2872,2874,2876,2879,2880,2881,2882,2883,2884,2885

2. Test Decomposition

T1 Options parsing surface (40): ServerOptionsTests IDs from 2514..2597 subset in Batch 7
T2 Route/leaf/proxy reload behavior (18): RouteHandlerTests, LeafNodeHandlerTests, LeafNodeProxyTests
T3 Cross-cutting regression (5): ConfigReloaderTests, JwtProcessorTests, MqttHandlerTests, ConcurrencyTests1, NatsServerTests

3. File Strategy

Primary feature files:

Modify: dotnet/src/ZB.MOM.NatsNet.Server/ServerOptions.Methods.cs
Modify: dotnet/src/ZB.MOM.NatsNet.Server/Config/ServerOptionsConfiguration.cs
Modify: dotnet/src/ZB.MOM.NatsNet.Server/Config/ReloadOptions.cs
Create (recommended): dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Reload.cs
Create (optional helper split if needed): dotnet/src/ZB.MOM.NatsNet.Server/Config/ReloadDiffHelpers.cs

Primary test files:

Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ServerOptionsTests.Impltests.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs
Create: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeProxyTests.Impltests.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JwtProcessorTests.Impltests.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttHandlerTests.Impltests.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs

4. Data and Control Flow

Config reload entry: NatsServer.ReloadOptions() normalizes config, merges flag snapshot/boolean overrides, applies baseline defaults, computes diff, applies ordered reload options, then performs post-apply actions (recheckPinnedCerts, timestamps, statsz/config metadata updates).
Diff pipeline: DiffOptions() + helper functions (ImposeOrder, route/proxy diffs, copy-without-TLS helpers) produce an ordered option list for deterministic ApplyOptions() behavior.
Authorization/cluster paths: ReloadAuthorization(), ReloadClusterPermissions(), ReloadClusterPoolAndAccounts() run after apply, with side effects explicitly validated by mapped tests or deferred with reason.

5. Error Handling and Deferment Model

Unsupported runtime changes return explicit errors (mirroring Go behavior), not silent no-op.
If a feature requires unported server internals, keep feature deferred with concrete reason.
If a test requires live runtime topology or unsupported infra, keep test deferred with concrete reason.
Stubbing is not an allowed fallback.

6. Verification Philosophy

Feature verification is gated by build + related test evidence.
Test verification requires real Arrange/Act/Assert on production behavior.
Status promotion is evidence-driven and chunked.

Key Risks and Mitigations

Reload behavior touches many server subsystems and may expose unported internals.
Mitigation: two bounded feature groups, explicit deferment protocol, and checkpoint gates.
Existing ImplBacklog placeholders can mask missing behavior.
Mitigation: mandatory anti-stub scans and class-level gates before status updates.
Batch dependency on Batch 6 may block execution sequencing.
Mitigation: preflight dependency gate in implementation plan before any Batch 7 status changes.

Design Output

This design selects Approach B and is ready for execution planning with strict, mandatory verification guardrails for both features and tests.

7.6 KiB Raw Blame History