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

6.3 KiB

Raw Blame History

Batch 10 (OCSP Cache + JS Events) Design

Date: 2026-02-27
Scope: Design-only plan for Batch 10 (20 features, 38 tests) covering Go files server/ocsp_responsecache.go and server/jetstream_events.go.

Context Snapshot

PortTracker snapshot from:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 10 --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

Observed facts:

Batch ID: 10
Name: OCSP Cache + JS Events
Dependency: Batch 9
Status: pending
Features: 20 (all currently deferred)
Tests: 38 (all currently deferred)
Overall progress: 1924/6942 (27.7%)

Feature mapping summary:

JetStream advisory publish path: 1959 (Server.publishAdvisory)
OCSP cache config/parser: 2472, 2501
Local cache behavior: 2484-2497
Server OCSP cache lifecycle wiring: 2498-2500

Readiness reality from dependency analysis (sqlite3 on porting.db):

All Batch 10 features have 0 unresolved dependencies.
Batch 10 tests are mixed:
- 8 tests become implementable once Batch 10 features are done.
- 30 tests still depend on external deferred features (not in Batch 10), so they cannot be honestly verified in this batch.

Problem Statement

Batch 10 is a foundational OCSP cache batch with one JetStream advisory method. The main risk is false progress: implementing local cache APIs superficially or marking cross-module tests verified while upstream features remain deferred.

Constraints and Success Criteria

Constraints:

Execute after Batch 9 dependency.
Follow .NET standards (.NET 10, nullable, xUnit 3 + Shouldly + NSubstitute).
No fake-pass tests and no production stubs promoted to verified.
Status updates must be evidence-backed and chunked (<= 15 IDs per batch-update).

Success criteria:

All 20 Batch 10 features implemented with Go-behavior parity and verification evidence.
Batch 10 mapped tests split correctly into:
- truly verified tests (only when unblocked and passing), and
- deferred tests with concrete dependency/runtime reasons.
Batch completion only attempted after gates pass.

Approaches

Approach A: Minimal API shims (fast status movement)

Implement signatures for local cache and parser methods with simplified behavior.

Pros: quick throughput.
Cons: high semantic drift from Go behavior (stats, revocation preservation, atomic save path, timer semantics).

Approach B: Full-fidelity OCSP cache parity in one pass (all tests now)

Implement complete OCSP cache and attempt to force all 38 tests to pass in Batch 10.

Pros: ambitious closure.
Cons: invalid for this dependency graph because 30 tests still depend on external deferred features.

Approach C (Recommended): Feature-complete cache + dependency-aware test closure

Port all Batch 10 features fully, then verify only tests that become unblocked; keep externally blocked tests deferred with explicit evidence.

Pros: truthful status accounting, lower regression risk, auditable progress.
Cons: leaves some Batch 10 tests deferred until upstream batches progress.

Recommended Design

1. Production Code Architecture

Primary code paths:

dotnet/src/ZB.MOM.NatsNet.Server/Auth/Ocsp/OcspTypes.cs
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs

Expected new code files:

dotnet/src/ZB.MOM.NatsNet.Server/Auth/Ocsp/OcspHandler.cs
- NewOCSPResponseCacheConfig
- ParseOCSPResponseCache
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.OcspResponseCache.cs
- InitOCSPResponseCache
- StartOCSPResponseCache
- StopOCSPResponseCache
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.JetStreamEvents.cs
- PublishAdvisory

Design intent:

Replace simple disk LocalDirCache behavior with true Go-equivalent local cache semantics:
- in-memory cache map
- atomic stats (hits/misses/goods/revokes/unknowns)
- compression/decompression
- PreserveRevoked delete behavior
- load/save with dirty flag + periodic save timer
Keep parser behavior strict and deterministic (invalid shape/type/cache kind => config error).
Keep server lifecycle integration explicit in start/stop/init flows.

2. Test Design

Primary test files:

dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspResponseCacheTests.cs
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.Impltests.cs (mapped batch tests)

Expected new test files:

dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspResponseCacheParserTests.cs
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/NatsServerOcspCacheTests.cs
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/NatsServerJetStreamEventsTests.cs

Test strategy:

TDD at feature-group granularity:
- write failing tests for cache stats/timer/save-load/parser/server wiring/advisory publish
- implement minimal parity
- pass focused tests before status promotion
For mapped Batch 10 tests:
- verify only those with no unresolved external dependencies after feature completion
- keep the rest deferred with explicit blocker IDs and reasons

3. Execution Slicing

Feature groups (<=20 each):

F1 (1): 1959
F2 (13): 2472,2484,2485,2486,2487,2488,2489,2490,2491,2492,2493,2494,2495
F3 (6): 2496,2497,2498,2499,2500,2501

Test groups:

T1 Candidate Verify (8): 1537,1538,1607,1625,1682,2442,2807,2894
T2 Keep Deferred Unless Upstream Unblocks (30): remaining Batch 10 test IDs

4. Risks and Mitigations

Timer/save behavior can introduce flaky tests. Mitigation: deterministic timer intervals in tests, explicit waits with bounded timeouts, and repeated focused test runs.
Parser mismatch vs Go error semantics. Mitigation: dedicated parser test matrix for accepted/rejected input shapes and type conversions.
Pressure to close all 38 tests inside this batch. Mitigation: strict dependency evidence; external blockers stay deferred, never replaced by placeholders.

Design Decision

Proceed with Approach C: full feature parity for Batch 10 plus dependency-aware test closure. This gives real progress on OCSP cache and JS advisory wiring while preventing incorrect verified statuses for externally blocked tests.

6.3 KiB Raw Blame History