f0455a1e45
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.
165 lines
6.3 KiB
Markdown
165 lines
6.3 KiB
Markdown
# 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
|
|
|
|
1. Timer/save behavior can introduce flaky tests.
|
|
Mitigation: deterministic timer intervals in tests, explicit waits with bounded timeouts, and repeated focused test runs.
|
|
|
|
2. Parser mismatch vs Go error semantics.
|
|
Mitigation: dedicated parser test matrix for accepted/rejected input shapes and type conversions.
|
|
|
|
3. 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.
|