c05d93618e
Generated design docs and implementation plans via Codex for: - Batch 23: Routes - Batch 24: Leaf Nodes - Batch 25: Gateways - Batch 26: WebSocket - Batch 27: JetStream Core - Batch 28: JetStream API - Batch 29: JetStream Batching - Batch 30: Raft Part 1 All plans include mandatory verification protocol and anti-stub guardrails. Updated batches.md with file paths and planned status.
127 lines
5.5 KiB
Markdown
127 lines
5.5 KiB
Markdown
# Batch 27 JetStream Core Design
|
|
|
|
## Context
|
|
|
|
- Batch: `27` (`JetStream Core`)
|
|
- Scope: `82` features, `77` tests
|
|
- Dependencies: batches `5`, `8`, `19`
|
|
- Primary Go source: `golang/nats-server/server/jetstream.go`
|
|
- PortTracker status snapshot (2026-02-27): batch `27` is `pending`
|
|
|
|
Batch 27 is the first full behavior layer for JetStream server lifecycle and per-account resource management. It spans server bootstrap/shutdown wiring, account-level JetStream enable/disable and usage tracking, limits enforcement, and config validation helpers consumed by later JetStream API and clustering batches.
|
|
|
|
## Constraints and Success Criteria
|
|
|
|
### Constraints
|
|
|
|
- No placeholder implementations or fake-pass tests.
|
|
- Dependency order is mandatory: batch 27 cannot start until batches `5`, `8`, and `19` are complete.
|
|
- Keep feature execution chunked to `~20` features per task group.
|
|
- Keep status updates evidence-based and chunked to max `15` IDs per `batch-update` call.
|
|
- Follow .NET standards: .NET 10, nullable, xUnit 3 + Shouldly + NSubstitute.
|
|
|
|
### Success Criteria
|
|
|
|
- All 82 feature IDs are moved to `verified` or kept `deferred` with explicit blocker notes.
|
|
- All 77 test IDs are moved to `verified` or kept `deferred` with explicit blocker notes.
|
|
- No forbidden stub patterns in touched production or test files.
|
|
- Build and test gates pass at every checkpoint.
|
|
|
|
## Approaches Considered
|
|
|
|
### Approach A (Recommended): Incremental in-place behavior port with grouped feature waves
|
|
|
|
- Implement missing methods in existing core files (`NatsServer` partials, `Account`, `JetStream`/`JsAccount` core files).
|
|
- Execute five feature groups (max ~20 each), then port mapped tests in staged class waves.
|
|
- Promote statuses only after per-feature/per-test verification evidence.
|
|
|
|
Pros:
|
|
- Lowest structural risk.
|
|
- Best audit trace from Go line ranges to C# methods.
|
|
- Works well with strict status-evidence protocol.
|
|
|
|
Cons:
|
|
- Large diffs in a few high-churn files.
|
|
|
|
### Approach B: Structural refactor first (convert types to partial files), then port behavior
|
|
|
|
- First split large classes into new partial files, then implement features.
|
|
|
|
Pros:
|
|
- Cleaner long-term organization.
|
|
|
|
Cons:
|
|
- Extra upfront churn before behavior parity.
|
|
- Harder to isolate regressions during a large dependency-heavy batch.
|
|
|
|
### Approach C: Signature-first skeleton pass, fill behavior later
|
|
|
|
- Add methods quickly to satisfy compile, then return later to complete behavior.
|
|
|
|
Pros:
|
|
- Fast apparent progress.
|
|
|
|
Cons:
|
|
- Violates anti-stub requirements and creates false status inflation.
|
|
|
|
Decision: **Approach A**.
|
|
|
|
## Proposed Design
|
|
|
|
### 1. Source Partitioning by Runtime Responsibility
|
|
|
|
Implement Batch 27 behavior in four logical zones:
|
|
|
|
- `NatsServer` JetStream lifecycle/config orchestration methods.
|
|
- `Account` JetStream account enrollment, limits assignment, account usage projections.
|
|
- `JetStream` engine-level limits/resource checks and global usage stats.
|
|
- `JsAccount` per-account synchronized usage, cluster usage sync, tier selection.
|
|
|
|
This mirrors the Go file layout while staying idiomatic in C#.
|
|
|
|
### 2. Feature Grouping Strategy (Max ~20/group)
|
|
|
|
Use five feature groups with contiguous IDs and behavior cohesion:
|
|
|
|
1. Group 1 (`20`): `1368-1387` — server enable/disable bootstrap, encryption setup, exports, account wiring
|
|
2. Group 2 (`19`): `1388,1389,1390,1391,1392,1394,1396,1397,1398,1399,1400,1401,1402,1403,1404,1405,1406,1407,1408` — runtime state flags/getters and account enable/update core
|
|
3. Group 3 (`18`): `1409-1426` — account usage snapshots and foundational limits helpers
|
|
4. Group 4 (`17`): `1427-1443` — jsAccount limits enforcement and stream resource reservation/release
|
|
5. Group 5 (`8`): `1444-1451` — dynamic config/validation/error helper tail
|
|
|
|
### 3. Test Porting Strategy
|
|
|
|
Port tests by class waves after core feature groups are green:
|
|
|
|
- Wave A (smaller cross-module classes, 19 tests): `AccountTests`, `EventsHandlerTests`, `MonitoringHandlerTests`, `JetStreamVersioningTests`, `MqttHandlerTests`, `MessageTracerTests`, `ConcurrencyTests2`, `NatsServerTests`
|
|
- Wave B (mid-size JetStream/storage classes, 17 tests): `JetStreamFileStoreTests`, `NatsConsumerTests`, `ConcurrencyTests1`
|
|
- Wave C (heavy class, 41 tests): `JetStreamEngineTests` in sub-batches; keep perf/benchmark-style tests deferred if they require unsupported harness/runtime shape.
|
|
|
|
### 4. Verification Model
|
|
|
|
The implementation plan defines a mandatory protocol with:
|
|
|
|
- Per-feature verification loop (read Go lines -> implement -> build/test evidence)
|
|
- Per-test verification loop (single-test pass evidence)
|
|
- Stub scan required after each group/class
|
|
- Build gate and test gate before status promotion
|
|
- Status updates in max-15 ID chunks
|
|
- Required checkpoints between tasks
|
|
|
|
### 5. Defer-Not-Stub Policy
|
|
|
|
If blocked by infrastructure/runtime gaps (cluster setup, benchmark harness, missing dependent behavior), keep item `deferred` with explicit reason in PortTracker; do not write placeholder code/tests.
|
|
|
|
## Risks and Mitigations
|
|
|
|
- Risk: dependency batches still pending.
|
|
- Mitigation: hard preflight gate before `batch start 27`.
|
|
- Risk: large JetStreamEngine test class can hide shallow ports.
|
|
- Mitigation: single-test evidence + assertion density checks + periodic class gates.
|
|
- Risk: status inflation without proof.
|
|
- Mitigation: max-15 update chunks and evidence checklist per update.
|
|
|
|
## Design Approval Note
|
|
|
|
This design is based on the explicit constraints in your request and current repository state. The implementation plan materializes this design into executable, checkpointed tasks without running any batch work.
|