natsnet/docs/plans/2026-02-27-batch-7-opts-class-methods-reload-design.md

# 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

1. Reload behavior touches many server subsystems and may expose unported internals.  
Mitigation: two bounded feature groups, explicit deferment protocol, and checkpoint gates.

2. Existing ImplBacklog placeholders can mask missing behavior.  
Mitigation: mandatory anti-stub scans and class-level gates before status updates.

3. 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.