Add batch plans for batches 13-15, 18-22 (rounds 8-11)
Generated design docs and implementation plans via Codex for: - Batch 13: FileStore Read/Query - Batch 14: FileStore Write/Lifecycle - Batch 15: MsgBlock + ConsumerFileStore - Batch 18: Server Core - Batch 19: Accounts Core - Batch 20: Accounts Resolvers - Batch 21: Events + MsgTrace - Batch 22: Monitoring All plans include mandatory verification protocol and anti-stub guardrails. Updated batches.md with file paths and planned status.
This commit is contained in:
Joseph Doherty
@@ -27,16 +27,16 @@
|
||||
| 10 | OCSP Cache + JS Events | [design](plans/2026-02-27-batch-10-ocsp-cache-js-events-design.md) | [plan](plans/2026-02-27-batch-10-ocsp-cache-js-events-plan.md) | planned |
|
||||
| 11 | FileStore Init | [design](plans/2026-02-27-batch-11-filestore-init-design.md) | [plan](plans/2026-02-27-batch-11-filestore-init-implementation-plan.md) | planned |
|
||||
| 12 | FileStore Recovery | [design](plans/2026-02-27-batch-12-filestore-recovery-design.md) | [plan](plans/2026-02-27-batch-12-filestore-recovery-plan.md) | planned |
|
||||
| 13 | FileStore Read/Query | | | not_planned |
|
||||
| 14 | FileStore Write/Lifecycle | | | not_planned |
|
||||
| 15 | MsgBlock + ConsumerFileStore | | | not_planned |
|
||||
| 13 | FileStore Read/Query | [design](plans/2026-02-27-batch-13-filestore-read-query-design.md) | [plan](plans/2026-02-27-batch-13-filestore-read-query-plan.md) | planned |
|
||||
| 14 | FileStore Write/Lifecycle | [design](plans/2026-02-27-batch-14-filestore-write-lifecycle-design.md) | [plan](plans/2026-02-27-batch-14-filestore-write-lifecycle-plan.md) | planned |
|
||||
| 15 | MsgBlock + ConsumerFileStore | [design](plans/2026-02-27-batch-15-msgblock-consumerfilestore-design.md) | [plan](plans/2026-02-27-batch-15-msgblock-consumerfilestore-implementation-plan.md) | planned |
|
||||
| 16 | Client Core (first half) | [design](plans/2026-02-27-batch-16-client-core-first-half-design.md) | [plan](plans/2026-02-27-batch-16-client-core-first-half-plan.md) | planned |
|
||||
| 17 | Client Core (second half) | [design](plans/2026-02-27-batch-17-client-core-second-half-design.md) | [plan](plans/2026-02-27-batch-17-client-core-second-half-plan.md) | planned |
|
||||
| 18 | Server Core | | | not_planned |
|
||||
| 19 | Accounts Core | | | not_planned |
|
||||
| 20 | Accounts Resolvers | | | not_planned |
|
||||
| 21 | Events + MsgTrace | | | not_planned |
|
||||
| 22 | Monitoring | | | not_planned |
|
||||
| 18 | Server Core | [design](plans/2026-02-27-batch-18-server-core-design.md) | [plan](plans/2026-02-27-batch-18-server-core-implementation-plan.md) | planned |
|
||||
| 19 | Accounts Core | [design](plans/2026-02-27-batch-19-accounts-core-design.md) | [plan](plans/2026-02-27-batch-19-accounts-core-implementation-plan.md) | planned |
|
||||
| 20 | Accounts Resolvers | [design](plans/2026-02-27-batch-20-accounts-resolvers-design.md) | [plan](plans/2026-02-27-batch-20-accounts-resolvers-implementation-plan.md) | planned |
|
||||
| 21 | Events + MsgTrace | [design](plans/2026-02-27-batch-21-events-msgtrace-design.md) | [plan](plans/2026-02-27-batch-21-events-msgtrace-implementation-plan.md) | planned |
|
||||
| 22 | Monitoring | [design](plans/2026-02-27-batch-22-monitoring-design.md) | [plan](plans/2026-02-27-batch-22-monitoring-implementation-plan.md) | planned |
|
||||
| 23 | Routes | | | not_planned |
|
||||
| 24 | Leaf Nodes | | | not_planned |
|
||||
| 25 | Gateways | | | not_planned |
|
||||
|
||||
127
docs/plans/2026-02-27-batch-13-filestore-read-query-design.md
Normal file
127
docs/plans/2026-02-27-batch-13-filestore-read-query-design.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Batch 13 FileStore Read/Query Design
|
||||
|
||||
## Context
|
||||
|
||||
- Batch: `13` (`FileStore Read/Query`)
|
||||
- Dependency: Batch `12` (`FileStore Recovery`)
|
||||
- Scope: 8 feature IDs, 0 mapped tests
|
||||
- Go reference: `golang/nats-server/server/filestore.go` (primarily lines `3241-3571`)
|
||||
- .NET target: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
|
||||
Features in scope:
|
||||
|
||||
- `1006` `fileStore.checkSkipFirstBlock`
|
||||
- `1007` `fileStore.checkSkipFirstBlockMulti`
|
||||
- `1008` `fileStore.selectSkipFirstBlock`
|
||||
- `1009` `fileStore.numFilteredPending`
|
||||
- `1010` `fileStore.numFilteredPendingNoLast`
|
||||
- `1011` `fileStore.numFilteredPendingWithLast`
|
||||
- `1014` `fileStore.allLastSeqsLocked`
|
||||
- `1015` `fileStore.filterIsAll`
|
||||
|
||||
## Problem Statement
|
||||
|
||||
`JetStreamFileStore` currently delegates nearly all query behavior to `JetStreamMemStore`. Batch 13 requires file-store-native read/query helpers that depend on file-store indexes (`_psim`, `_bim`, `_blks`) and file-store locking patterns. Without these helpers, later file-store read/write batches cannot safely switch from delegation to true file-backed query paths.
|
||||
|
||||
## Approaches Considered
|
||||
|
||||
### Approach 1 (Recommended): Implement file-store-native helpers now, keep public delegation stable
|
||||
|
||||
Implement the 8 methods in `JetStreamFileStore` as internal/private helpers that operate on `_psim`, `_bim`, `_blks`, and `MessageBlock` metadata. Keep the current public `IStreamStore` delegation unchanged for now, but add focused tests for helper correctness and edge cases.
|
||||
|
||||
Pros:
|
||||
|
||||
- Preserves current behavior while enabling later batches.
|
||||
- Aligns tightly with Go logic and lock semantics.
|
||||
- Reduces risk when moving public query paths to file-store-native execution.
|
||||
|
||||
Cons:
|
||||
|
||||
- Adds methods that are not yet fully wired into every public API path.
|
||||
- Requires test harness/setup for internal state.
|
||||
|
||||
### Approach 2: Keep delegation and defer helper implementation to Batch 14+
|
||||
|
||||
Do nothing in Batch 13 besides documentation/notes, then implement all helpers when public read paths are ported.
|
||||
|
||||
Pros:
|
||||
|
||||
- Lower immediate implementation effort.
|
||||
|
||||
Cons:
|
||||
|
||||
- Violates the intent of Batch 13 feature scope.
|
||||
- Pushes complexity/risk into later larger batches.
|
||||
- Prevents granular verification of these helpers.
|
||||
|
||||
### Approach 3: Replace delegation immediately and port full read/query path end-to-end
|
||||
|
||||
Implement helpers plus rewire all relevant public methods (`NumPending`, `MultiLastSeqs`, etc.) to native file-store logic in this batch.
|
||||
|
||||
Pros:
|
||||
|
||||
- End-state behavior reached sooner.
|
||||
|
||||
Cons:
|
||||
|
||||
- Scope explosion beyond 8 Batch 13 features.
|
||||
- High regression risk and poor fit for dependency sequencing.
|
||||
|
||||
## Recommended Design
|
||||
|
||||
### 1) FileStore helper surface for Batch 13
|
||||
|
||||
Add/port the following methods in `JetStreamFileStore` with Go-equivalent behavior:
|
||||
|
||||
- `CheckSkipFirstBlock(string filter, bool wc, int bi)`
|
||||
- `CheckSkipFirstBlockMulti(SimpleSublist sl, int bi)`
|
||||
- `SelectSkipFirstBlock(int bi, uint start, uint stop)`
|
||||
- `NumFilteredPending(string filter, ref SimpleState ss)`
|
||||
- `NumFilteredPendingNoLast(string filter, ref SimpleState ss)`
|
||||
- `NumFilteredPendingWithLast(string filter, bool includeLast, ref SimpleState ss)`
|
||||
- `AllLastSeqsLocked()`
|
||||
- `FilterIsAll(string[] filters)`
|
||||
|
||||
### 2) State and indexing model
|
||||
|
||||
- Use `_psim` (`SubjectTree<Psi>`) for per-subject totals and first/last block index hints.
|
||||
- Use `_bim` to dereference block index (`uint`) to `MessageBlock`.
|
||||
- Use `_blks` ordering for forward/backward block scans.
|
||||
- Preserve lazy correction behavior for stale `Psi.Fblk` when first-sequence lookup misses.
|
||||
|
||||
### 3) Locking and concurrency model
|
||||
|
||||
- Methods ending with `Locked` assume `_mu` read lock is held by caller.
|
||||
- Avoid lock upgrade from read to write in-place.
|
||||
- For stale `Fblk` correction, schedule deferred write-lock update (Go uses goroutine). In C#, use a background `Task.Run` that reacquires `_mu` write lock and revalidates before update.
|
||||
- Avoid nested read-lock recursion patterns that can deadlock with pending writes.
|
||||
|
||||
### 4) Error and boundary behavior
|
||||
|
||||
- Return `StoreErrors.ErrStoreEOF` when skip/jump helpers find no matching future blocks.
|
||||
- Return empty results (not exceptions) when there are no matching subjects for filtered pending.
|
||||
- Keep null checks defensive for `_psim`, `_bim`, missing blocks, and empty `_blks`.
|
||||
|
||||
### 5) Testing strategy
|
||||
|
||||
- Add focused tests for helper behavior in `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs`.
|
||||
- Derive cases from Go tests around:
|
||||
- `TestFileStoreFilteredPendingPSIMFirstBlockUpdate`
|
||||
- `TestFileStoreWildcardFilteredPendingPSIMFirstBlockUpdate`
|
||||
- `TestFileStoreFilteredPendingPSIMFirstBlockUpdateNextBlock`
|
||||
- `TestJetStreamStoreFilterIsAll`
|
||||
- Run existing related tests (`JetStreamFileStoreTests`, `StorageEngineTests` subset, `JetStreamMemoryStoreTests` subset) as regression gates.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Full migration of public file-store query APIs away from `_memStore` delegation.
|
||||
- Implementing unrelated file-store write/lifecycle features from Batch 14.
|
||||
- Porting new PortTracker-mapped test IDs (Batch 13 has 0 mapped tests).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- All 8 feature methods are implemented with behavior aligned to Go intent.
|
||||
- No placeholder/stub patterns in touched source/tests.
|
||||
- `dotnet build dotnet/` passes after each feature group.
|
||||
- Related test gates pass before features are marked `verified`.
|
||||
- Feature status updates are evidence-backed and chunked (max 15 IDs).
|
||||
529
docs/plans/2026-02-27-batch-13-filestore-read-query-plan.md
Normal file
529
docs/plans/2026-02-27-batch-13-filestore-read-query-plan.md
Normal file
@@ -0,0 +1,529 @@
|
||||
# Batch 13 FileStore Read/Query Implementation Plan
|
||||
|
||||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Implement and verify Batch 13 FileStore read/query helpers (`1006,1007,1008,1009,1010,1011,1014,1015`) from `filestore.go` without introducing placeholder logic.
|
||||
|
||||
**Architecture:** Port the helper methods into `JetStreamFileStore` with Go-equivalent lock and index behavior (`_psim`, `_bim`, `_blks`), add focused unit tests for helper-level correctness, and keep current public delegation stable until later batches wire these helpers into public query paths.
|
||||
|
||||
**Tech Stack:** .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (`porting.db`)
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-batch-13-filestore-read-query-design.md`
|
||||
|
||||
---
|
||||
|
||||
## Batch Facts
|
||||
|
||||
- Batch ID: `13`
|
||||
- Name: `FileStore Read/Query`
|
||||
- Dependencies: Batch `12`
|
||||
- Features: `8`
|
||||
- Tests mapped in batch: `0`
|
||||
- Go source: `golang/nats-server/server/filestore.go`
|
||||
|
||||
Feature IDs:
|
||||
|
||||
- Group A: `1006,1007,1008`
|
||||
- Group B: `1009,1010,1011`
|
||||
- Group C: `1014,1015`
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY VERIFICATION PROTOCOL
|
||||
|
||||
> **NON-NEGOTIABLE. Every feature task must follow this protocol.**
|
||||
|
||||
### Per-Feature Verification Loop (REQUIRED for every feature ID)
|
||||
|
||||
For each feature (`1006` through `1015` in this batch):
|
||||
|
||||
1. Read the exact Go method body and nearby comments from `golang/nats-server/server/filestore.go`.
|
||||
2. Add/adjust failing unit tests that assert the method behavior (or behavior exercised through a helper entry point).
|
||||
3. Run the targeted test filter and verify it fails for the expected reason.
|
||||
4. Implement minimal C# code to pass the failing test.
|
||||
5. Run targeted tests again and confirm pass.
|
||||
6. Run `dotnet build dotnet/` and confirm build success.
|
||||
7. Add feature ID to the evidence table only if steps 1-6 are complete.
|
||||
|
||||
### Stub Detection Check (REQUIRED after each feature group)
|
||||
|
||||
Run stub scans on all files touched in the group before any status update:
|
||||
|
||||
```bash
|
||||
grep -n -E "(NotImplementedException|TODO|PLACEHOLDER)" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs
|
||||
|
||||
grep -n -E "^\s*(public|private|internal|protected).*\{\s*\}$" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs
|
||||
```
|
||||
|
||||
If any matches are found, fix code or defer the impacted feature. Do not mark complete/verified.
|
||||
|
||||
### Build Gate (REQUIRED after each feature group)
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
|
||||
Must pass with `0` errors before feature status changes in that group.
|
||||
|
||||
### Test Gate (REQUIRED before `verified`)
|
||||
|
||||
Run related tests after each group and before any `verified` update:
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~JetStreamFileStoreReadQueryTests|FullyQualifiedName~JetStreamFileStoreTests|FullyQualifiedName~StorageEngineTests.FileStoreMultiLastSeqsAndLoadLastMsgWithLazySubjectState_ShouldSucceed|FullyQualifiedName~JetStreamMemoryStoreTests.MemStoreAllLastSeqs_ShouldSucceed|FullyQualifiedName~JetStreamMemoryStoreTests.MemStoreMultiLastSeqs_ShouldSucceed"
|
||||
```
|
||||
|
||||
All selected tests must pass. Any failure blocks `verified`.
|
||||
|
||||
### Status Update Protocol (REQUIRED)
|
||||
|
||||
- Maximum `15` IDs per `feature batch-update` call.
|
||||
- Evidence required per ID: Go lines reviewed, targeted test names, pass output, build pass.
|
||||
- Transition order: `deferred/not_started -> stub -> complete -> verified`.
|
||||
- Never mark `verified` before both Build Gate and Test Gate pass.
|
||||
- If audit disagrees, use `--override "<specific evidence>"` only with concrete reason.
|
||||
|
||||
Status update commands for this batch:
|
||||
|
||||
```bash
|
||||
# Claim work
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1006-1011,1014-1015" --set-status stub --db porting.db --execute
|
||||
|
||||
# Group completion (run per group with only that group's IDs)
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "<group ids>" --set-status complete --db porting.db --execute
|
||||
|
||||
# Group verification (after test gate)
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "<group ids>" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
### Checkpoint Protocol (REQUIRED between tasks)
|
||||
|
||||
Between Task 2, Task 3, and Task 4:
|
||||
|
||||
1. Run full build:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
2. Run full unit test project:
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
3. Confirm pass/fail/skip summary and capture it in notes.
|
||||
4. Commit checkpoint before moving to next task.
|
||||
|
||||
---
|
||||
|
||||
## ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)
|
||||
|
||||
These rules apply to both production features and tests in this plan.
|
||||
|
||||
### Forbidden Patterns
|
||||
|
||||
Do not leave any of these in touched code:
|
||||
|
||||
- `throw new NotImplementedException(...)`
|
||||
- `// TODO` or `// PLACEHOLDER` in implemented method bodies
|
||||
- Empty method bodies (including one-line `{ }` placeholders)
|
||||
- Test methods with no assertions
|
||||
- Tests that only assert non-null for complex query behavior
|
||||
|
||||
### Hard Limits
|
||||
|
||||
- Max `15` feature IDs per status batch update.
|
||||
- Max `1` feature group per status-update cycle.
|
||||
- Mandatory build + related test gate before `verified`.
|
||||
- Mandatory checkpoint commit between feature groups.
|
||||
|
||||
### If You Get Stuck
|
||||
|
||||
If a feature cannot be completed without missing infrastructure:
|
||||
|
||||
1. Leave or move that feature to `deferred` (never ship a stub).
|
||||
2. Record the blocker using `--override` with specific reason.
|
||||
3. Continue with remaining features in the same group.
|
||||
4. Do not force `complete/verified` to unblock the batch.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature update <id> --status deferred --db porting.db \
|
||||
--override "blocked: requires <missing dependency> for non-stub implementation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Batch Setup and Baseline
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Read: `golang/nats-server/server/filestore.go`
|
||||
- Read: `docs/plans/2026-02-27-batch-13-filestore-read-query-design.md`
|
||||
|
||||
**Step 1: Confirm batch readiness**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 13 --db porting.db
|
||||
```
|
||||
|
||||
Expected: Batch 13 displayed with dependency on Batch 12.
|
||||
|
||||
**Step 2: Start batch**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch start 13 --db porting.db
|
||||
```
|
||||
|
||||
Expected: Batch status changes to in-progress (or equivalent accepted state).
|
||||
|
||||
**Step 3: Claim all 8 features as `stub`**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1006-1011,1014-1015" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
Expected: All 8 features updated to `stub`.
|
||||
|
||||
**Step 4: Run baseline build and unit tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
|
||||
Expected: Baseline captured before feature changes.
|
||||
|
||||
**Step 5: Commit baseline checkpoint**
|
||||
|
||||
```bash
|
||||
git add porting.db docs/plans/2026-02-27-batch-13-filestore-read-query-design.md docs/plans/2026-02-27-batch-13-filestore-read-query-plan.md
|
||||
git commit -m "plan(batch13): establish filestore read/query baseline and protocol"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Group A Features (1006, 1007, 1008) Skip-First-Block Helpers
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- Create: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs`
|
||||
- Optional Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs` (only if helper accessors are required)
|
||||
|
||||
**Step 1: Read Go source slice for Group A**
|
||||
|
||||
Read:
|
||||
|
||||
```bash
|
||||
sed -n '3241,3307p' golang/nats-server/server/filestore.go
|
||||
```
|
||||
|
||||
Expected: Exact behavior for `checkSkipFirstBlock`, `checkSkipFirstBlockMulti`, `selectSkipFirstBlock`.
|
||||
|
||||
**Step 2: Write failing tests for block-selection behavior**
|
||||
|
||||
Add tests covering:
|
||||
|
||||
- `filter=""` and `filter=">"` returns `bi + 1`.
|
||||
- Literal filter with no `psim` match returns `ErrStoreEOF`.
|
||||
- `stop <= currentBlockIndex` returns `ErrStoreEOF`.
|
||||
- `start > currentBlockIndex` jumps to selected block index.
|
||||
- Multi-filter path uses `SimpleSublist` intersection semantics.
|
||||
|
||||
**Step 3: Run targeted tests to verify failure**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~JetStreamFileStoreReadQueryTests.CheckSkipFirstBlock|FullyQualifiedName~JetStreamFileStoreReadQueryTests.SelectSkipFirstBlock"
|
||||
```
|
||||
|
||||
Expected: Failing tests indicating missing or incorrect behavior.
|
||||
|
||||
**Step 4: Implement Group A methods in `FileStore.cs`**
|
||||
|
||||
Implement logic equivalent to Go:
|
||||
|
||||
```csharp
|
||||
private (int Next, Exception? Error) SelectSkipFirstBlock(int bi, uint start, uint stop)
|
||||
{
|
||||
var mbi = _blks[bi].Index;
|
||||
if (stop <= mbi)
|
||||
return (-1, StoreErrors.ErrStoreEOF);
|
||||
if (start > mbi && _bim.TryGetValue(start, out var mb) && mb != null)
|
||||
{
|
||||
var (ni, _) = SelectMsgBlockWithIndex(mb.Last.Seq);
|
||||
return (ni, null);
|
||||
}
|
||||
return (bi + 1, null);
|
||||
}
|
||||
```
|
||||
|
||||
Use the same boundary rules for `CheckSkipFirstBlock` and multi-filter variant.
|
||||
|
||||
**Step 5: Run targeted tests to green**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~JetStreamFileStoreReadQueryTests.CheckSkipFirstBlock|FullyQualifiedName~JetStreamFileStoreReadQueryTests.SelectSkipFirstBlock"
|
||||
```
|
||||
|
||||
Expected: Pass.
|
||||
|
||||
**Step 6: Run Stub Detection Check, Build Gate, Test Gate**
|
||||
|
||||
Run all commands from `MANDATORY VERIFICATION PROTOCOL`.
|
||||
|
||||
**Step 7: Update statuses for Group A**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1006-1008" --set-status complete --db porting.db --execute
|
||||
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1006-1008" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
Expected: IDs `1006-1008` set to verified with recorded evidence.
|
||||
|
||||
**Step 8: Run Checkpoint Protocol and commit**
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs \
|
||||
porting.db
|
||||
git commit -m "feat(batch13): port filestore skip-first-block query helpers"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Group B Features (1009, 1010, 1011) Filtered Pending Helpers
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs`
|
||||
|
||||
**Step 1: Read Go source slice for Group B**
|
||||
|
||||
```bash
|
||||
sed -n '3308,3503p' golang/nats-server/server/filestore.go
|
||||
```
|
||||
|
||||
Expected: Behavior for `numFilteredPending*`, stale `fblk` correction, optional last-seq logic.
|
||||
|
||||
**Step 2: Write failing tests for filtered pending**
|
||||
|
||||
Add tests for:
|
||||
|
||||
- All-subject short-circuit (`filter=""` and `filter=">"`).
|
||||
- No-match returns zeroed `SimpleState`.
|
||||
- Literal and wildcard totals from `psim`.
|
||||
- `NumFilteredPendingNoLast` leaves `Last == 0`.
|
||||
- Stale `Psi.Fblk` is corrected after first miss path.
|
||||
|
||||
**Step 3: Run targeted tests to verify failure**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~JetStreamFileStoreReadQueryTests.NumFilteredPending"
|
||||
```
|
||||
|
||||
Expected: Fail until implementation is in place.
|
||||
|
||||
**Step 4: Implement Group B methods**
|
||||
|
||||
Port Go behavior:
|
||||
|
||||
- `NumFilteredPending` delegates to with-last variant (`includeLast=true`).
|
||||
- `NumFilteredPendingNoLast` delegates with `includeLast=false`.
|
||||
- `NumFilteredPendingWithLast`:
|
||||
- Calculates totals from `_psim`.
|
||||
- Resolves first via start block then forward scan.
|
||||
- Schedules `Psi.Fblk` correction under write lock if stale.
|
||||
- Computes last only when requested.
|
||||
|
||||
**Step 5: Run targeted + related tests**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~JetStreamFileStoreReadQueryTests.NumFilteredPending|FullyQualifiedName~JetStreamFileStoreTests"
|
||||
```
|
||||
|
||||
Expected: Pass.
|
||||
|
||||
**Step 6: Run Stub Detection Check, Build Gate, Test Gate**
|
||||
|
||||
Run all commands from `MANDATORY VERIFICATION PROTOCOL`.
|
||||
|
||||
**Step 7: Update statuses for Group B**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1009-1011" --set-status complete --db porting.db --execute
|
||||
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1009-1011" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 8: Run Checkpoint Protocol and commit**
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs \
|
||||
porting.db
|
||||
git commit -m "feat(batch13): port filestore filtered-pending query helpers"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Group C Features (1014, 1015) Last-Sequence and Filter-All Helpers
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs`
|
||||
|
||||
**Step 1: Read Go source slice for Group C**
|
||||
|
||||
```bash
|
||||
sed -n '3504,3571p' golang/nats-server/server/filestore.go
|
||||
```
|
||||
|
||||
Expected: `allLastSeqsLocked` and `filterIsAll` behavior details.
|
||||
|
||||
**Step 2: Write failing tests for Group C**
|
||||
|
||||
Add tests for:
|
||||
|
||||
- `AllLastSeqsLocked` returns sorted last sequence list.
|
||||
- No messages or no subject tracking returns empty/nil equivalent.
|
||||
- Lazy `lastNeedsUpdate` path recalculates before collecting sequence.
|
||||
- `FilterIsAll` true for reordered equivalent subject set.
|
||||
- `FilterIsAll` false for count mismatch or non-subset match.
|
||||
|
||||
**Step 3: Run targeted tests to verify failure**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~JetStreamFileStoreReadQueryTests.AllLastSeqsLocked|FullyQualifiedName~JetStreamFileStoreReadQueryTests.FilterIsAll"
|
||||
```
|
||||
|
||||
Expected: Fail until implementation is complete.
|
||||
|
||||
**Step 4: Implement Group C methods**
|
||||
|
||||
Port behavior:
|
||||
|
||||
- Reverse block walk collecting per-subject last sequence once.
|
||||
- Keep `subs` set to avoid duplicates.
|
||||
- Sort final sequence array before return.
|
||||
- `FilterIsAll` compares sorted `filters` to sorted configured subjects using subset-match check.
|
||||
|
||||
**Step 5: Run targeted + regression tests**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~JetStreamFileStoreReadQueryTests.AllLastSeqsLocked|FullyQualifiedName~JetStreamFileStoreReadQueryTests.FilterIsAll|FullyQualifiedName~StorageEngineTests.FileStoreMultiLastSeqsAndLoadLastMsgWithLazySubjectState_ShouldSucceed|FullyQualifiedName~JetStreamMemoryStoreTests.MemStoreAllLastSeqs_ShouldSucceed|FullyQualifiedName~JetStreamMemoryStoreTests.MemStoreMultiLastSeqs_ShouldSucceed"
|
||||
```
|
||||
|
||||
Expected: Pass.
|
||||
|
||||
**Step 6: Run Stub Detection Check, Build Gate, Test Gate**
|
||||
|
||||
Run all commands from `MANDATORY VERIFICATION PROTOCOL`.
|
||||
|
||||
**Step 7: Update statuses for Group C**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1014-1015" --set-status complete --db porting.db --execute
|
||||
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1014-1015" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 8: Run Checkpoint Protocol and commit**
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamFileStoreReadQueryTests.cs \
|
||||
porting.db
|
||||
git commit -m "feat(batch13): port filestore all-last-seqs and filter-is-all helpers"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Batch Completion and Handoff
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Optional Modify: `reports/current.md` (if report script updates it)
|
||||
|
||||
**Step 1: Full verification sweep**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/
|
||||
```
|
||||
|
||||
Expected: Green build and tests (or clearly documented pre-existing failures).
|
||||
|
||||
**Step 2: Audit features**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- audit --type features --db porting.db
|
||||
```
|
||||
|
||||
Expected: Batch 13 IDs classified consistently with implementation.
|
||||
|
||||
**Step 3: Complete batch**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch complete 13 --db porting.db
|
||||
```
|
||||
|
||||
Expected: Batch 13 completes if all required statuses are valid.
|
||||
|
||||
**Step 4: Refresh report and inspect newly unblocked work**
|
||||
|
||||
```bash
|
||||
./reports/generate-report.sh
|
||||
dotnet run --project tools/NatsNet.PortTracker -- dependency ready --db porting.db
|
||||
```
|
||||
|
||||
Expected: Updated report and visibility into next available batches.
|
||||
|
||||
---
|
||||
|
||||
## Evidence Log Template (Use During Execution)
|
||||
|
||||
For each feature ID, capture:
|
||||
|
||||
- Go reference: file + line range reviewed.
|
||||
- Test cases added/updated.
|
||||
- Targeted test command + pass summary.
|
||||
- Build command + pass summary.
|
||||
- Stub scan output status.
|
||||
- PortTracker status command(s) executed.
|
||||
|
||||
This evidence is required before any `verified` transition.
|
||||
@@ -0,0 +1,133 @@
|
||||
# Batch 14 FileStore Write/Lifecycle Design
|
||||
|
||||
## Context
|
||||
|
||||
- Batch: `14` (`FileStore Write/Lifecycle`)
|
||||
- Dependency: Batch `13` (`FileStore Read/Query`)
|
||||
- Scope: `76` features + `64` tests
|
||||
- Go reference: `golang/nats-server/server/filestore.go` (primarily lines `4394-12549`)
|
||||
- .NET target surface:
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
|
||||
Current implementation state:
|
||||
|
||||
- `JetStreamFileStore` is still a delegation shell to `JetStreamMemStore` for most `IStreamStore` behavior.
|
||||
- Batch 14 methods are mostly not present yet in .NET.
|
||||
- Most mapped Batch 14 tests are not implemented in backlog files and need real behavioral coverage.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Batch 14 is the first large FileStore execution batch where write path, retention/compaction, purge/reset, state flush, snapshot, and shutdown lifecycle all need file-backed behavior instead of memory-store delegation. If this batch is implemented without strict lock discipline and anti-stub verification, downstream batches (`15`, `36`, `37`) will inherit brittle storage behavior and unreliable test evidence.
|
||||
|
||||
## Clarified Constraints
|
||||
|
||||
- Keep Batch 14 scoped to mapped methods/tests only; do not pull Batch 15 `MessageBlock + ConsumerFileStore` work forward.
|
||||
- Use evidence-backed status updates in PortTracker (`max 15 IDs` per update).
|
||||
- Keep tests real: no placeholders, no always-pass assertions, no non-behavioral smoke tests.
|
||||
- If a test requires unavailable runtime infrastructure, keep it `deferred` with a concrete reason instead of stubbing.
|
||||
|
||||
## Approaches Considered
|
||||
|
||||
### Approach 1 (Recommended): Vertical implementation by four feature groups with dependency-resolved test waves
|
||||
|
||||
Implement Batch 14 in four functional feature groups (`18 + 18 + 20 + 20`), each followed by targeted test waves that only promote tests whose feature dependencies are already implemented and verified.
|
||||
|
||||
Pros:
|
||||
|
||||
- Keeps each cycle below the complexity threshold for file-store concurrency code.
|
||||
- Makes failures local and debuggable.
|
||||
- Aligns naturally with mandatory build/test/status checkpoints.
|
||||
|
||||
Cons:
|
||||
|
||||
- Requires careful bookkeeping of cross-group tests.
|
||||
- More commits and checkpoint overhead.
|
||||
|
||||
### Approach 2: Implement all 76 features first, then all 64 tests
|
||||
|
||||
Complete production surface in one pass, then backfill all tests at the end.
|
||||
|
||||
Pros:
|
||||
|
||||
- Fewer context switches.
|
||||
|
||||
Cons:
|
||||
|
||||
- High risk of broad regressions discovered late.
|
||||
- Weak traceability between feature status and test evidence.
|
||||
- Encourages accidental stub completion pressure near the end.
|
||||
|
||||
### Approach 3: Test-first only with synthetic wrappers over memstore delegation
|
||||
|
||||
Attempt to satisfy mapped tests through wrapper behavior while delaying real file-backed implementation.
|
||||
|
||||
Pros:
|
||||
|
||||
- Fast initial green tests.
|
||||
|
||||
Cons:
|
||||
|
||||
- Violates batch intent (real FileStore write/lifecycle parity).
|
||||
- Produces fragile tests that validate wrappers, not storage behavior.
|
||||
- Increases later rework and hidden defects.
|
||||
|
||||
## Recommended Design
|
||||
|
||||
### 1) Implementation topology
|
||||
|
||||
Use four feature groups with bounded scope:
|
||||
|
||||
- Group 1 (`18`): write-path foundation, per-subject totals, limits/removal entrypoints.
|
||||
- Group 2 (`18`): age/scheduling loops, record/tombstone writes, block sync/select helpers.
|
||||
- Group 3 (`20`): seq/read helpers, cache/state counters, purge/compact/reset and block-list mutation.
|
||||
- Group 4 (`20`): purge-block/global subject info, stream-state write loop, stop/snapshot/delete-map lifecycle.
|
||||
|
||||
### 2) Locking and lifecycle model
|
||||
|
||||
- Preserve `ReaderWriterLockSlim` ownership boundaries in `JetStreamFileStore`.
|
||||
- Keep timer/background loop ownership explicit (`_ageChk`, `_syncTmr`, `_qch`, `_fsld`).
|
||||
- Ensure stop/flush/snapshot/delete paths are idempotent and race-safe under repeated calls.
|
||||
- Treat file writes and state writes as durability boundaries; enforce explicit optional-sync behavior parity.
|
||||
|
||||
### 3) Test model
|
||||
|
||||
Implement backlog tests as real behavioral tests in:
|
||||
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
|
||||
|
||||
Create missing backlog classes for mapped tests:
|
||||
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeProxyTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamClusterLongTests.Impltests.cs`
|
||||
|
||||
### 4) Status strategy
|
||||
|
||||
- Features: `deferred -> stub -> complete -> verified`.
|
||||
- Tests: `deferred -> stub -> verified` or `deferred` with explicit blocker reason.
|
||||
- Promote only IDs that have direct Go-read + build + targeted test evidence.
|
||||
|
||||
### 5) Risk controls
|
||||
|
||||
- Mandatory stub scans after each feature/test wave.
|
||||
- Build gate after each feature group.
|
||||
- Related test gate before any `verified` promotion.
|
||||
- Full checkpoint (`build + full unit tests + commit`) between groups.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Port Batch 15 (`MessageBlock + ConsumerFileStore`) behaviors beyond what Batch 14 methods directly require.
|
||||
- Converting integration-only tests into unit tests by weakening assertions.
|
||||
- Marking blocked runtime-heavy tests `verified` without executable evidence.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- All 76 Batch 14 features implemented with non-stub behavior and verified evidence.
|
||||
- All implementable mapped tests in Batch 14 converted to real behavioral tests and verified.
|
||||
- Runtime-blocked tests remain `deferred` with concrete blocker notes.
|
||||
- Batch 14 can be completed with `batch complete 14` after status/audit validation.
|
||||
481
docs/plans/2026-02-27-batch-14-filestore-write-lifecycle-plan.md
Normal file
481
docs/plans/2026-02-27-batch-14-filestore-write-lifecycle-plan.md
Normal file
@@ -0,0 +1,481 @@
|
||||
# Batch 14 FileStore Write/Lifecycle Implementation Plan
|
||||
|
||||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Implement and verify all Batch 14 FileStore write/lifecycle features and mapped tests from `server/filestore.go` with non-stub behavior and evidence-backed status transitions.
|
||||
|
||||
**Architecture:** Execute Batch 14 in four vertical feature groups (`18 + 18 + 20 + 20`) aligned to `filestore.go` locality and lifecycle boundaries. After each feature group, run strict stub/build/test gates, then port and verify the dependency-resolved test wave before any `verified` status changes. Keep implementation centered in `JetStream/FileStore.cs`, with targeted support updates in `MessageBlock.cs` and `FileStoreTypes.cs` only when required by Go parity.
|
||||
|
||||
**Tech Stack:** .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (`porting.db`)
|
||||
|
||||
---
|
||||
|
||||
I'm using `writeplan` to create the implementation plan.
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-batch-14-filestore-write-lifecycle-design.md`
|
||||
|
||||
## Batch Inputs
|
||||
|
||||
- Batch: `14` (`FileStore Write/Lifecycle`)
|
||||
- Depends on: Batch `13`
|
||||
- Features: `76`
|
||||
- Tests: `64`
|
||||
- Go source: `golang/nats-server/server/filestore.go`
|
||||
|
||||
Feature groups (max ~20 each):
|
||||
|
||||
- Group 1 (`18`): `1020,1024,1027,1028,1029,1036,1037,1038,1039,1040,1041,1042,1045,1046,1047,1048,1054,1066`
|
||||
- Group 2 (`18`): `1076,1077,1078,1079,1080,1081,1082,1083,1084,1085,1099,1100,1101,1102,1108,1109,1110,1111`
|
||||
- Group 3 (`20`): `1131,1132,1133,1139,1140,1147,1148,1160,1161,1162,1168,1169,1171,1172,1178,1179,1180,1181,1182,1183`
|
||||
- Group 4 (`20`): `1184,1189,1193,1195,1197,1198,1199,1201,1202,1203,1204,1205,1207,1208,1210,1211,1212,1214,1215,1260`
|
||||
|
||||
Test waves (dependency-resolved):
|
||||
|
||||
- Wave 1 (`8`): `549,551,561,572,586,587,1219,2441`
|
||||
- Wave 2 (`6`): `354,365,372,435,593,2476`
|
||||
- Wave 3 (`27`): `363,378,418,437,438,442,452,455,457,461,462,464,470,475,476,485,490,491,492,494,495,496,498,501,503,523,2480`
|
||||
- Wave 4 (`23`): `384,412,413,477,483,518,519,530,531,566,567,588,589,590,594,1899,1900,1901,1984,2001,2431,2494,2854`
|
||||
|
||||
Primary test files:
|
||||
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
|
||||
- Create if missing:
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeProxyTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamClusterLongTests.Impltests.cs`
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY VERIFICATION PROTOCOL
|
||||
|
||||
> **NON-NEGOTIABLE:** Every feature/test task and every status update must pass this protocol.
|
||||
|
||||
### Per-Feature Verification Loop (REQUIRED for every feature ID)
|
||||
|
||||
For each active feature ID:
|
||||
|
||||
1. Read feature mapping and Go intent:
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- feature show <FEATURE_ID> --db porting.db
|
||||
```
|
||||
2. Read exact Go method body and nearby helpers in `golang/nats-server/server/filestore.go`.
|
||||
3. Write minimal real C# behavior in FileStore/MessageBlock/FileStoreTypes.
|
||||
4. Build immediately:
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet build dotnet/
|
||||
```
|
||||
5. Run targeted related tests for that behavior (single method or tight class filter).
|
||||
6. Only then add the feature ID to status-update candidates.
|
||||
|
||||
### Stub Detection Check (REQUIRED after each feature group and test wave)
|
||||
|
||||
Any match below is a blocker:
|
||||
|
||||
```bash
|
||||
# Production stubs/placeholders
|
||||
rg -n "NotImplementedException|TODO|PLACEHOLDER|throw new NotSupportedException" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream -g '*.cs'
|
||||
|
||||
# Empty production bodies on FileStore surface
|
||||
rg -n "^\s*(public|private|internal|protected).*(\)\s*\{\s*\}|=>\s*default;|=>\s*null;)" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs
|
||||
|
||||
# Test placeholders and always-pass patterns
|
||||
rg -n "NotImplementedException|Assert\.True\(true\)|Assert\.Pass|// TODO|// PLACEHOLDER|ShouldBe\(true\);" \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.cs
|
||||
|
||||
# Existing placeholder-template smell (must be removed from ported tests)
|
||||
rg -n "goFile\.ShouldStartWith\(\"server/\"\)|ServerConstants\.DefaultPort\.ShouldBe\(4222\)" \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.cs
|
||||
```
|
||||
|
||||
### Build Gate (REQUIRED after each feature group)
|
||||
|
||||
Before any status update for that group:
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet build dotnet/
|
||||
```
|
||||
|
||||
Build must pass with zero errors.
|
||||
|
||||
### Test Gate (REQUIRED before marking features verified)
|
||||
|
||||
All related tests for the active scope must pass before any feature in that scope can be marked `verified`.
|
||||
|
||||
Minimum gate commands:
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.JetStreamFileStoreTests" \
|
||||
--verbosity normal
|
||||
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.ConcurrencyTests1|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.ConcurrencyTests2|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.LeafNodeHandlerTests|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.LeafNodeProxyTests|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.RouteHandlerTests|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.JetStreamClusterLongTests" \
|
||||
--verbosity normal
|
||||
```
|
||||
|
||||
### Status Update Protocol (REQUIRED)
|
||||
|
||||
- Max `15` IDs per `feature batch-update` or `test batch-update` command.
|
||||
- Required progression:
|
||||
- Features: `deferred -> stub -> complete -> verified`
|
||||
- Tests: `deferred -> stub -> verified` (or stay `deferred` with reason)
|
||||
- Evidence is mandatory before each update:
|
||||
- Go method reviewed
|
||||
- build passed
|
||||
- related tests passed
|
||||
- stub scan clean
|
||||
- Keep evidence logs under `/tmp/batch14-evidence/`.
|
||||
|
||||
Example update command:
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "1020,1024,1027" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
### Checkpoint Protocol Between Tasks (REQUIRED)
|
||||
|
||||
Between each feature/test group transition:
|
||||
|
||||
1. Full build:
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet build dotnet/
|
||||
```
|
||||
2. Full unit suite:
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
|
||||
```
|
||||
3. Commit checkpoint:
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog \
|
||||
porting.db
|
||||
git commit -m "feat(batch14): complete group <N> filestore write lifecycle"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ANTI-STUB GUARDRAILS
|
||||
|
||||
### Forbidden Patterns
|
||||
|
||||
Do not introduce or keep any of these in Batch 14 feature/test scope:
|
||||
|
||||
- `throw new NotImplementedException(...)`
|
||||
- Empty mapped method bodies (`{ }`) in `FileStore.cs`/`MessageBlock.cs`
|
||||
- `TODO`/`PLACEHOLDER` markers in implemented methods/tests
|
||||
- Always-pass tests (`Assert.True(true)`, `Assert.Pass`, trivial constants-only assertions)
|
||||
- Placeholder-template tests that only validate static constants or method names
|
||||
- Tests with no production behavior act step against FileStore APIs
|
||||
|
||||
### Hard Limits
|
||||
|
||||
- Max ~20 features per implementation group (fixed at `18/18/20/20`)
|
||||
- Max `15` IDs per status update command
|
||||
- Max one feature group per status-update cycle
|
||||
- Zero stub-scan hits before `complete` or `verified`
|
||||
- No `verified` transition without Build Gate + Test Gate evidence
|
||||
|
||||
### If You Get Stuck (MANDATORY)
|
||||
|
||||
1. Do not write stubs, no-ops, or fake pass tests.
|
||||
2. Mark only blocked IDs as `deferred` with concrete reason.
|
||||
3. Continue with unblocked IDs in the same group.
|
||||
4. Record blocker evidence and use override reason text.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature update <ID> --status deferred --db porting.db \
|
||||
--override "blocked: requires <specific infra/dependency> for non-stub implementation"
|
||||
```
|
||||
|
||||
Use same pattern for tests.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Batch Start, Baseline, and Staging
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Create: `/tmp/batch14-evidence/`
|
||||
|
||||
**Step 1: Confirm batch state**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 14 --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
|
||||
```
|
||||
|
||||
Expected: Batch 14 pending with dependency on 13.
|
||||
|
||||
**Step 2: Start batch**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch start 14 --db porting.db
|
||||
```
|
||||
|
||||
**Step 3: Stage Group 1 IDs to stub**
|
||||
|
||||
Run chunked updates (`<=15 IDs` each) for Group 1 features and Wave 1 tests.
|
||||
|
||||
**Step 4: Baseline build/test**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet build dotnet/
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
|
||||
```
|
||||
|
||||
**Step 5: Commit baseline checkpoint**
|
||||
|
||||
```bash
|
||||
git add porting.db docs/plans/2026-02-27-batch-14-filestore-write-lifecycle-design.md docs/plans/2026-02-27-batch-14-filestore-write-lifecycle-plan.md
|
||||
git commit -m "plan(batch14): establish filestore write lifecycle execution baseline"
|
||||
```
|
||||
|
||||
### Task 2: Implement Group 1 Features (18 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
|
||||
**Step 1: Port write-path foundations**
|
||||
|
||||
Feature IDs: `1020,1024,1027,1028,1029`
|
||||
|
||||
**Step 2: Port sequence and limit/removal paths**
|
||||
|
||||
Feature IDs: `1036,1037,1038,1039,1040,1041,1042,1045,1046,1047,1048,1054,1066`
|
||||
|
||||
**Step 3: Apply mandatory verification protocol**
|
||||
|
||||
Run per-feature loop, stub scans, and build gate for all 18 IDs.
|
||||
|
||||
**Step 4: Update Group 1 feature status**
|
||||
|
||||
- Move to `complete` in chunks <=15.
|
||||
- Move to `verified` only after Wave 1 test gate passes.
|
||||
|
||||
### Task 3: Port and Verify Wave 1 Tests (8 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- Create: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamClusterLongTests.Impltests.cs`
|
||||
|
||||
**Wave 1 IDs:** `549,551,561,572,586,587,1219,2441`
|
||||
|
||||
**Step 1: Read Go tests via `test show <ID>` and implement real behavior tests**
|
||||
|
||||
**Step 2: Run each test method individually, verify discovery and pass**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~<TestMethodName>" --verbosity normal
|
||||
```
|
||||
|
||||
**Step 3: Run class-level test gates for modified classes**
|
||||
|
||||
**Step 4: Run stub scans and build gate**
|
||||
|
||||
**Step 5: Update Wave 1 test statuses to verified (<=15 IDs per command)**
|
||||
|
||||
### Task 4: Group 1 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1: Run checkpoint protocol**
|
||||
|
||||
**Step 2: Commit Group 1 checkpoint**
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "feat(batch14): complete group1 write path and wave1 tests"
|
||||
```
|
||||
|
||||
### Task 5: Implement Group 2 Features (18 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
|
||||
**Feature IDs:** `1076,1077,1078,1079,1080,1081,1082,1083,1084,1085,1099,1100,1101,1102,1108,1109,1110,1111`
|
||||
|
||||
**Step 1: Port age-check, scheduling, and check/flush loops**
|
||||
|
||||
**Step 2: Port message record/tombstone and block sync/select helpers**
|
||||
|
||||
**Step 3: Apply mandatory verification protocol**
|
||||
|
||||
**Step 4: Update Group 2 feature statuses (chunked <=15)**
|
||||
|
||||
### Task 6: Port and Verify Wave 2 Tests (6 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
|
||||
**Wave 2 IDs:** `354,365,372,435,593,2476`
|
||||
|
||||
**Step 1: Implement tests from Go source intent**
|
||||
|
||||
**Step 2: Execute per-test loop + class-level gate**
|
||||
|
||||
**Step 3: Run stub scans/build gate and verify no placeholder-template remnants**
|
||||
|
||||
**Step 4: Mark Wave 2 tests verified (<=15 IDs per call)**
|
||||
|
||||
### Task 7: Group 2 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1: Run checkpoint protocol**
|
||||
|
||||
**Step 2: Commit Group 2 checkpoint**
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "feat(batch14): complete group2 lifecycle checks and wave2 tests"
|
||||
```
|
||||
|
||||
### Task 8: Implement Group 3 Features (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
|
||||
**Feature IDs:** `1131,1132,1133,1139,1140,1147,1148,1160,1161,1162,1168,1169,1171,1172,1178,1179,1180,1181,1182,1183`
|
||||
|
||||
**Step 1: Port seq/message/load helpers and cache/state accessors**
|
||||
|
||||
**Step 2: Port purge/compact/reset and block list management methods**
|
||||
|
||||
**Step 3: Apply mandatory verification protocol**
|
||||
|
||||
**Step 4: Update Group 3 feature statuses (<=15 IDs per command)**
|
||||
|
||||
### Task 9: Port and Verify Wave 3 Tests (27 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
|
||||
**Wave 3 IDs:** `363,378,418,437,438,442,452,455,457,461,462,464,470,475,476,485,490,491,492,494,495,496,498,501,503,523,2480`
|
||||
|
||||
**Step 1: Implement tests in sub-batches of 10-12 methods**
|
||||
|
||||
**Step 2: For each sub-batch, run per-test loop and class gate**
|
||||
|
||||
**Step 3: Run mandatory stub/build/test gates**
|
||||
|
||||
**Step 4: Mark Wave 3 tests verified in max-15 ID chunks**
|
||||
|
||||
### Task 10: Group 3 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1: Run checkpoint protocol**
|
||||
|
||||
**Step 2: Commit Group 3 checkpoint**
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "feat(batch14): complete group3 purge compact state and wave3 tests"
|
||||
```
|
||||
|
||||
### Task 11: Implement Group 4 Features (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
|
||||
**Feature IDs:** `1184,1189,1193,1195,1197,1198,1199,1201,1202,1203,1204,1205,1207,1208,1210,1211,1212,1214,1215,1260`
|
||||
|
||||
**Step 1: Port purge-block/global subject info and stream-state write loops**
|
||||
|
||||
**Step 2: Port stop/snapshot/read-lock-all/delete-map/delete-blocks/write-file-with-optional-sync lifecycle methods**
|
||||
|
||||
**Step 3: Apply mandatory verification protocol**
|
||||
|
||||
**Step 4: Update Group 4 feature statuses (<=15 IDs per command)**
|
||||
|
||||
### Task 12: Port and Verify Wave 4 Tests (23 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
|
||||
- Create: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeProxyTests.Impltests.cs`
|
||||
|
||||
**Wave 4 IDs:** `384,412,413,477,483,518,519,530,531,566,567,588,589,590,594,1899,1900,1901,1984,2001,2431,2494,2854`
|
||||
|
||||
**Step 1: Implement file-store lifecycle tests in `JetStreamFileStoreTests.Impltests.cs`**
|
||||
|
||||
**Step 2: Implement cross-module backlog tests (leaf/proxy/route/concurrency) only with real behavior assertions**
|
||||
|
||||
**Step 3: If any test requires unavailable infra, mark that test `deferred` with explicit reason (no stubs)**
|
||||
|
||||
**Step 4: Run per-test loop, class gates, stub scans, and build gate**
|
||||
|
||||
**Step 5: Mark verified/deferred statuses in <=15 ID chunks with evidence**
|
||||
|
||||
### Task 13: Final Verification, Audit, and Batch Closure
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Generate: `reports/current.md`
|
||||
|
||||
**Step 1: Full regression gates**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet build dotnet/
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
|
||||
```
|
||||
|
||||
**Step 2: Global stub audit (features + tests)**
|
||||
|
||||
```bash
|
||||
rg -n "NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)|Assert\.Pass|goFile\.ShouldStartWith\(\"server/\"\)" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog
|
||||
```
|
||||
|
||||
**Step 3: Run PortTracker audits**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- audit --type features --db porting.db
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- audit --type tests --db porting.db
|
||||
```
|
||||
|
||||
**Step 4: Verify batch visibility and complete**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 14 --db porting.db
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch complete 14 --db porting.db
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
|
||||
```
|
||||
|
||||
**Step 5: Generate report and final commit**
|
||||
|
||||
```bash
|
||||
./reports/generate-report.sh
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db reports/
|
||||
git commit -m "feat(batch14): complete filestore write lifecycle features and tests"
|
||||
```
|
||||
@@ -0,0 +1,156 @@
|
||||
# Batch 15 MsgBlock + ConsumerFileStore Design
|
||||
|
||||
I'm using `brainstorm` to produce this design before implementation planning.
|
||||
|
||||
## Context
|
||||
|
||||
- Batch: `15` (`MsgBlock + ConsumerFileStore`)
|
||||
- Dependency: Batch `14` (`FileStore Write/Lifecycle`)
|
||||
- Scope: `121` features + `89` tests
|
||||
- Go source: `golang/nats-server/server/filestore.go`
|
||||
- Current batch status: `pending` (all mapped features/tests currently `deferred`)
|
||||
|
||||
Observed with PortTracker:
|
||||
|
||||
- `batch show 15`: full feature/test inventory loaded from `server/filestore.go` and related tests.
|
||||
- `batch list`: Batch 15 depends on Batch 14.
|
||||
- `batch ready`: Batch 15 is not startable yet (dependency gate not satisfied).
|
||||
- `report summary`: overall porting progress is `1924/6942 (27.7%)`.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Batch 15 is the deepest part of FileStore internals: message block recovery/scanning, cache lifecycle, compaction/tombstones, disk rewrite/compression/encryption paths, and `ConsumerFileStore` state flushing. If this batch is implemented without strict verification discipline, downstream stream/consumer lifecycle batches will inherit correctness and durability bugs that are expensive to debug.
|
||||
|
||||
## Constraints and Success Criteria
|
||||
|
||||
- Do not start Batch 15 execution until Batch 14 is complete.
|
||||
- Keep implementation scoped to Batch 15 mapped IDs.
|
||||
- Enforce non-stub behavior for both production code and tests.
|
||||
- Promote statuses only with evidence-backed build/test proof.
|
||||
- If blocked, keep IDs deferred with explicit reasons; do not fake-pass.
|
||||
|
||||
Success for this batch means:
|
||||
|
||||
1. All implementable Batch 15 features are real C# ports with parity-oriented behavior.
|
||||
2. All implementable mapped tests are real behavioral tests and passing.
|
||||
3. Blocked items remain deferred with concrete, auditable reasons.
|
||||
4. Batch can pass final `batch complete 15` validation once dependencies are met and evidence is complete.
|
||||
|
||||
## Approaches Considered
|
||||
|
||||
### Approach 1 (Recommended): Vertical slices by feature groups and test waves
|
||||
|
||||
Split 121 features into seven groups (`20/20/20/20/20/20/1`) and execute each group with immediate build/test/status gates before moving on.
|
||||
|
||||
Pros:
|
||||
|
||||
- Contains risk in file-store concurrency code.
|
||||
- Makes regressions local and debuggable.
|
||||
- Supports strict anti-stub and evidence requirements.
|
||||
|
||||
Cons:
|
||||
|
||||
- More checkpoints and bookkeeping overhead.
|
||||
|
||||
### Approach 2: Feature-complete first, tests second
|
||||
|
||||
Implement all production features first, then port all tests.
|
||||
|
||||
Pros:
|
||||
|
||||
- Fewer context switches while coding.
|
||||
|
||||
Cons:
|
||||
|
||||
- Late detection of regressions.
|
||||
- Weak traceability for status updates.
|
||||
- Higher risk of last-minute stub behavior.
|
||||
|
||||
### Approach 3: Test-first broad wave with temporary placeholders
|
||||
|
||||
Attempt to satisfy test volume rapidly with minimal implementation placeholders.
|
||||
|
||||
Pros:
|
||||
|
||||
- Fast apparent progress.
|
||||
|
||||
Cons:
|
||||
|
||||
- Violates anti-stub requirement.
|
||||
- Creates false confidence and rework.
|
||||
- Unacceptable for durability-critical file store logic.
|
||||
|
||||
## Recommended Design
|
||||
|
||||
### 1) Implementation Topology
|
||||
|
||||
Primary code targets:
|
||||
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/StoreTypes.cs`
|
||||
|
||||
Scope focus:
|
||||
|
||||
- `MessageBlock` internals (95 mapped features)
|
||||
- `ConsumerFileStore` internals (18 mapped features)
|
||||
- Store enum/codec helpers and error wrappers
|
||||
|
||||
### 2) Verification-First Control Plane
|
||||
|
||||
Every feature group and test wave must pass:
|
||||
|
||||
- Per-feature read/port/build/test loop
|
||||
- Stub scan gates (production + tests)
|
||||
- Build gate after each feature group
|
||||
- Related test gate before feature `verified`
|
||||
- Chunked status updates (`<=15` IDs/update)
|
||||
- Full checkpoint (`build + full test + commit`) between tasks
|
||||
|
||||
### 3) Test Strategy
|
||||
|
||||
Mapped tests are concentrated in:
|
||||
|
||||
- `JetStreamFileStoreTests.Impltests.cs` (58)
|
||||
- `JwtProcessorTests.Impltests.cs` (24)
|
||||
- `GatewayHandlerTests.Impltests.cs` (2)
|
||||
- `ConcurrencyTests1.Impltests.cs` (1)
|
||||
- `ConcurrencyTests2.Impltests.cs` (2)
|
||||
- `EventsHandlerTests.Impltests.cs` (1)
|
||||
- `ConfigReloaderTests.Impltests.cs` (1)
|
||||
|
||||
Design decision:
|
||||
|
||||
- Treat filestore/concurrency tests as primary verification for Batch 15 behavior.
|
||||
- Treat cross-module JWT/gateway/events/reload tests as dependency-sensitive; keep deferred with reasons if blocked by non-Batch-15 surfaces.
|
||||
|
||||
### 4) Data and Concurrency Parity Priorities
|
||||
|
||||
Highest-risk behavior areas to preserve from Go:
|
||||
|
||||
- Block rebuild and index/tombstone accounting integrity.
|
||||
- Cache ownership transitions and forced expiration races.
|
||||
- Flush loops and fsync boundaries for pending writes.
|
||||
- Compression/encryption conversion and checksum correctness.
|
||||
- Consumer state encode/encrypt/flush sequencing.
|
||||
|
||||
### 5) Status Governance
|
||||
|
||||
- Feature lifecycle: `deferred -> stub -> complete -> verified`
|
||||
- Test lifecycle: `deferred -> stub -> verified` (or `deferred` with blocker note)
|
||||
- Status updates require direct evidence references (Go line reviewed, build output, targeted test output, stub scan clean).
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Pulling in work from future stream/consumer lifecycle batches beyond mapped Batch 15 IDs.
|
||||
- Marking cross-module tests verified without executable evidence.
|
||||
- Using placeholder methods/tests to satisfy status transitions.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Batch 15 feature groups fully implemented with non-stub logic.
|
||||
- Mandatory verification protocol passed for each group/wave.
|
||||
- Evidence-backed status transitions applied in chunks of max 15 IDs.
|
||||
- Deferred items carry explicit blocker reasons.
|
||||
- Batch closure commands are expected to pass once dependency Batch 14 is complete.
|
||||
@@ -0,0 +1,479 @@
|
||||
# Batch 15 MsgBlock + ConsumerFileStore Implementation Plan
|
||||
|
||||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Implement and verify Batch 15 (`MsgBlock + ConsumerFileStore`) with real `MessageBlock`/`ConsumerFileStore` behavior parity from `server/filestore.go`, then close feature/test statuses with evidence-backed updates.
|
||||
|
||||
**Architecture:** Execute seven feature groups (max 20 IDs each) and five test waves in a strict vertical loop: read Go intent, implement minimal real C#, build, run related tests, and only then update statuses. Apply mandatory anti-stub checks and checkpoint gates between tasks to prevent false-positive progress.
|
||||
|
||||
**Tech Stack:** .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (`porting.db`)
|
||||
|
||||
---
|
||||
|
||||
I'm using `writeplan` to create the implementation plan.
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-batch-15-msgblock-consumerfilestore-design.md`
|
||||
|
||||
## Batch Inputs
|
||||
|
||||
- Batch: `15` (`MsgBlock + ConsumerFileStore`)
|
||||
- Dependency: Batch `14`
|
||||
- Features: `121` (all currently `deferred`)
|
||||
- Tests: `89` (all currently `deferred`)
|
||||
- Go source: `golang/nats-server/server/filestore.go`
|
||||
|
||||
Feature groups (max ~20 each):
|
||||
|
||||
- Group 1 (`20`): `951,952,953,954,971,973,977,981,982,983,984,985,986,994,1000,1001,1002,1003,1004,1025`
|
||||
- Group 2 (`20`): `1026,1032,1049,1050,1051,1052,1053,1055,1056,1058,1059,1060,1061,1062,1063,1064,1065,1067,1068,1069`
|
||||
- Group 3 (`20`): `1070,1071,1072,1073,1074,1075,1086,1087,1088,1089,1090,1091,1092,1093,1094,1095,1096,1097,1098,1103`
|
||||
- Group 4 (`20`): `1104,1105,1106,1107,1112,1113,1114,1115,1116,1117,1118,1119,1120,1121,1122,1123,1124,1125,1126,1127`
|
||||
- Group 5 (`20`): `1128,1129,1130,1134,1135,1136,1156,1157,1159,1173,1174,1175,1176,1185,1186,1187,1188,1190,1191,1192`
|
||||
- Group 6 (`20`): `1194,1218,1219,1220,1221,1222,1223,1231,1234,1236,1237,1238,1240,1241,1245,1246,1247,1250,1253,1258`
|
||||
- Group 7 (`1`): `1259`
|
||||
|
||||
Test waves:
|
||||
|
||||
- Wave 1 (`20`, filestore core): `368,373,382,394,399,403,404,405,407,411,416,428,445,448,449,451,458,459,460,472`
|
||||
- Wave 2 (`20`, filestore compaction/recovery): `473,474,478,479,482,486,497,499,500,502,527,533,534,535,544,546,547,550,555,557`
|
||||
- Wave 3 (`18`, filestore tombstone/index edges): `559,562,570,571,573,574,577,578,579,580,581,582,583,584,591,595,596,597`
|
||||
- Wave 4 (`7`, concurrency + cross-module smoke dependencies): `2422,2505,2510,333,603,604,2762`
|
||||
- Wave 5 (`24`, JWT-linked tests likely dependency-sensitive): `1809,1810,1811,1812,1813,1814,1815,1816,1817,1818,1820,1824,1826,1827,1828,1829,1842,1843,1844,1845,1848,1850,1851,1852`
|
||||
|
||||
Primary files in scope:
|
||||
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/StoreTypes.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/GatewayHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JwtProcessorTests.Impltests.cs`
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY VERIFICATION PROTOCOL
|
||||
|
||||
> **NON-NEGOTIABLE:** Every feature/test transition and status update in this plan must satisfy all gates below.
|
||||
|
||||
### Per-Feature Verification Loop (required for every feature ID)
|
||||
|
||||
1. Read feature mapping:
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- feature show <FEATURE_ID> --db porting.db
|
||||
```
|
||||
2. Read Go source at mapped location in `golang/nats-server/server/filestore.go` (include nearby helpers and lock assumptions).
|
||||
3. Implement the C# port in the mapped .NET file with real behavior (no placeholder logic).
|
||||
4. Build immediately:
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet build dotnet/
|
||||
```
|
||||
5. Run related tests (single method or narrow class filter).
|
||||
6. Only after green build + related tests, add ID to `complete`/`verified` candidate list.
|
||||
|
||||
### Stub Detection Check (required after each feature group and each test wave)
|
||||
|
||||
Run all scans before any status update:
|
||||
|
||||
```bash
|
||||
# Production placeholder markers
|
||||
grep -R -n -E "NotImplementedException|TODO|PLACEHOLDER" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream
|
||||
|
||||
# Empty/suspicious method bodies on core files
|
||||
grep -R -n -E "^[[:space:]]*(public|private|internal|protected).*[)]\s*\{\s*\}$|=>\s*default;|=>\s*null;" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/JetStream/StoreTypes.cs
|
||||
|
||||
# Test placeholders/always-pass patterns
|
||||
grep -R -n -E "NotImplementedException|Assert\\.True\\(true\\)|Assert\\.Pass|// TODO|// PLACEHOLDER|ShouldBe\\(true\\);" \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog
|
||||
```
|
||||
|
||||
Any hit must be fixed or intentionally deferred with explicit reason before continuing.
|
||||
|
||||
### Build Gate (required after each feature group)
|
||||
|
||||
After each feature group, before status updates:
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet build dotnet/
|
||||
```
|
||||
|
||||
Build must complete with zero errors.
|
||||
|
||||
### Test Gate (required before marking features verified)
|
||||
|
||||
Before moving any feature IDs to `verified`, all related tests in the active wave/class set must pass.
|
||||
|
||||
Minimum required commands:
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.JetStreamFileStoreTests" \
|
||||
--verbosity normal
|
||||
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.ConcurrencyTests1|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.ConcurrencyTests2|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.EventsHandlerTests|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.GatewayHandlerTests|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.ConfigReloaderTests|FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.JwtProcessorTests" \
|
||||
--verbosity normal
|
||||
```
|
||||
|
||||
### Status Update Protocol (required)
|
||||
|
||||
- Max `15` IDs per `feature batch-update` or `test batch-update` command.
|
||||
- Required evidence per update batch:
|
||||
- Go source reviewed for each ID.
|
||||
- Build gate passed.
|
||||
- Related test gate passed.
|
||||
- Stub detection check clean.
|
||||
- Keep evidence logs in `/tmp/batch15-evidence/`.
|
||||
- Never mark IDs `verified` without recorded evidence.
|
||||
|
||||
Example command pattern:
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "951,952,953,954,971" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
### Checkpoint Protocol Between Tasks (required)
|
||||
|
||||
After every feature group + test wave pair:
|
||||
|
||||
1. Full build:
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet build dotnet/
|
||||
```
|
||||
2. Full unit test run:
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
|
||||
```
|
||||
3. Commit checkpoint:
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog \
|
||||
porting.db
|
||||
git commit -m "feat(batch15): complete group <N> msgblock/consumerfilestore"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ANTI-STUB GUARDRAILS
|
||||
|
||||
### Forbidden Patterns
|
||||
|
||||
The following are forbidden in Batch 15 scope (production or tests):
|
||||
|
||||
- `throw new NotImplementedException(...)`
|
||||
- Empty mapped method bodies (`{ }`) for mapped APIs
|
||||
- `TODO`/`PLACEHOLDER` markers in implemented methods/tests
|
||||
- `Assert.True(true)` or equivalent always-pass assertions
|
||||
- Test methods with no production act step
|
||||
- “Name-only” or constant-only assertions that do not verify behavior
|
||||
|
||||
### Hard Limits
|
||||
|
||||
- Max ~20 features per implementation group (fixed at `20/20/20/20/20/20/1`)
|
||||
- Max `15` IDs per status update command
|
||||
- Max one feature group per status-update cycle
|
||||
- Zero stub-scan hits before `complete` or `verified`
|
||||
- No feature may move to `verified` before related tests pass
|
||||
- Mandatory checkpoint commit between tasks
|
||||
|
||||
### If You Get Stuck (mandatory behavior)
|
||||
|
||||
1. Do not stub and do not fake-pass tests.
|
||||
2. Keep blocked IDs `deferred`.
|
||||
3. Record precise blocker reason (`infra missing`, `dependency batch not complete`, `non-batch surface required`, etc.).
|
||||
4. Continue with unblocked IDs in the same group.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature update <ID> --status deferred --db porting.db \
|
||||
--override "blocked: requires <specific dependency/infra> for non-stub implementation"
|
||||
```
|
||||
|
||||
Use same pattern for tests.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Preflight Dependency Gate and Evidence Setup
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Create: `/tmp/batch15-evidence/`
|
||||
|
||||
**Step 1: Confirm Batch 14 dependency and batch state**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 15 --db porting.db
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch ready --db porting.db
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
|
||||
```
|
||||
|
||||
Expected: Batch 15 not startable until Batch 14 is complete.
|
||||
|
||||
**Step 2: Create evidence folder**
|
||||
|
||||
```bash
|
||||
mkdir -p /tmp/batch15-evidence
|
||||
```
|
||||
|
||||
**Step 3: Start Batch 15 only after dependency is satisfied**
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch start 15 --db porting.db
|
||||
```
|
||||
|
||||
### Task 2: Implement Feature Group 1 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/StoreTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
|
||||
**Step 1:** Port IDs `951,952,953,954,971,973,977,981,982,983`
|
||||
|
||||
**Step 2:** Port IDs `984,985,986,994,1000,1001,1002,1003,1004,1025`
|
||||
|
||||
**Step 3:** Apply mandatory verification protocol (per-feature loop + stub detection + build gate).
|
||||
|
||||
**Step 4:** Update Group 1 feature statuses in chunks <=15 (`stub -> complete`).
|
||||
|
||||
### Task 3: Port and Verify Test Wave 1 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
|
||||
**Step 1:** Port first 10 tests from Wave 1; run individual-method verification.
|
||||
|
||||
**Step 2:** Port second 10 tests; run individual-method verification.
|
||||
|
||||
**Step 3:** Run class-level `JetStreamFileStoreTests` gate + stub detection.
|
||||
|
||||
**Step 4:** Mark passing Wave 1 tests `verified` in chunks <=15.
|
||||
|
||||
### Task 4: Group 1 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1:** Run Checkpoint Protocol (`build + full unit tests + commit`).
|
||||
|
||||
**Step 2:** Promote Group 1 features to `verified` only if Wave 1 gate is green.
|
||||
|
||||
### Task 5: Implement Feature Group 2 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
|
||||
**Step 1:** Port IDs `1026,1032,1049,1050,1051,1052,1053,1055,1056,1058`.
|
||||
|
||||
**Step 2:** Port IDs `1059,1060,1061,1062,1063,1064,1065,1067,1068,1069`.
|
||||
|
||||
**Step 3:** Run per-feature verification loop and group build gate.
|
||||
|
||||
**Step 4:** Update statuses in chunks <=15.
|
||||
|
||||
### Task 6: Port and Verify Test Wave 2 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
|
||||
**Step 1:** Port first 10 tests in Wave 2.
|
||||
|
||||
**Step 2:** Port second 10 tests in Wave 2.
|
||||
|
||||
**Step 3:** Run class gate + stub detection + assertion depth review.
|
||||
|
||||
**Step 4:** Mark verified tests (<=15 IDs per command).
|
||||
|
||||
### Task 7: Group 2 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1:** Run Checkpoint Protocol.
|
||||
|
||||
**Step 2:** Promote Group 2 features to `verified` if Wave 2 tests are green.
|
||||
|
||||
### Task 8: Implement Feature Group 3 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
|
||||
**Step 1:** Port IDs `1070,1071,1072,1073,1074,1075,1086,1087,1088,1089`.
|
||||
|
||||
**Step 2:** Port IDs `1090,1091,1092,1093,1094,1095,1096,1097,1098,1103`.
|
||||
|
||||
**Step 3:** Apply mandatory verification protocol.
|
||||
|
||||
**Step 4:** Update statuses (<=15 IDs per update).
|
||||
|
||||
### Task 9: Port and Verify Test Wave 3 (18 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
|
||||
**Step 1:** Port first 9 tests in Wave 3.
|
||||
|
||||
**Step 2:** Port last 9 tests in Wave 3.
|
||||
|
||||
**Step 3:** Run class gate + stub detection.
|
||||
|
||||
**Step 4:** Update test statuses for passing IDs.
|
||||
|
||||
### Task 10: Group 3 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1:** Run Checkpoint Protocol.
|
||||
|
||||
**Step 2:** Promote Group 3 features to `verified` after Wave 3 gate.
|
||||
|
||||
### Task 11: Implement Feature Group 4 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStoreTypes.cs`
|
||||
|
||||
**Step 1:** Port IDs `1104,1105,1106,1107,1112,1113,1114,1115,1116,1117`.
|
||||
|
||||
**Step 2:** Port IDs `1118,1119,1120,1121,1122,1123,1124,1125,1126,1127`.
|
||||
|
||||
**Step 3:** Run per-feature loop and group build/test gates.
|
||||
|
||||
**Step 4:** Update feature statuses in <=15 chunks.
|
||||
|
||||
### Task 12: Port and Verify Test Wave 4 (7 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/GatewayHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs`
|
||||
|
||||
**Step 1:** Port concurrency-focused tests (`2422,2505,2510`) and run each 3 times for flake check.
|
||||
|
||||
**Step 2:** Attempt `333,603,604,2762`; if blocked by non-Batch-15 dependencies, keep deferred with reasons.
|
||||
|
||||
**Step 3:** Run cross-class test gate and status updates with evidence.
|
||||
|
||||
### Task 13: Group 4 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1:** Run Checkpoint Protocol.
|
||||
|
||||
**Step 2:** Promote Group 4 features to `verified` where gates passed.
|
||||
|
||||
### Task 14: Implement Feature Group 5 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
|
||||
**Step 1:** Port IDs `1128,1129,1130,1134,1135,1136,1156,1157,1159,1173`.
|
||||
|
||||
**Step 2:** Port IDs `1174,1175,1176,1185,1186,1187,1188,1190,1191,1192`.
|
||||
|
||||
**Step 3:** Run mandatory verification protocol and update status in <=15 chunks.
|
||||
|
||||
### Task 15: Port and Evaluate Test Wave 5 (24 JWT-linked IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JwtProcessorTests.Impltests.cs`
|
||||
|
||||
**Step 1:** For each test ID, verify whether dependency feature(s) are in Batch 15 scope.
|
||||
|
||||
**Step 2:** Port only tests backed by implemented dependencies.
|
||||
|
||||
**Step 3:** For blocked tests, keep `deferred` with explicit reason (dependency outside Batch 15).
|
||||
|
||||
**Step 4:** Run class gate and update only evidenced IDs.
|
||||
|
||||
### Task 16: Group 5 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1:** Run Checkpoint Protocol.
|
||||
|
||||
**Step 2:** Promote Group 5 features to `verified` only with passing related test coverage.
|
||||
|
||||
### Task 17: Implement Feature Group 6 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MessageBlock.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/FileStore.cs`
|
||||
|
||||
**Step 1:** Port IDs `1194,1218,1219,1220,1221,1222,1223,1231,1234,1236`.
|
||||
|
||||
**Step 2:** Port IDs `1237,1238,1240,1241,1245,1246,1247,1250,1253,1258`.
|
||||
|
||||
**Step 3:** Run per-feature loop, group build gate, and related test gate.
|
||||
|
||||
**Step 4:** Update statuses in <=15 chunks.
|
||||
|
||||
### Task 18: ConsumerFileStore Regression Sweep
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
|
||||
**Step 1:** Add/adjust tests that specifically exercise consumer state flush, encryption, and delete/flush coordination.
|
||||
|
||||
**Step 2:** Run narrow filters for consumer-focused tests and then class-level gates.
|
||||
|
||||
**Step 3:** Update remaining Group 6 feature/test statuses with evidence.
|
||||
|
||||
### Task 19: Group 6 Checkpoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1:** Run Checkpoint Protocol.
|
||||
|
||||
**Step 2:** Commit Group 6 completion.
|
||||
|
||||
### Task 20: Implement Group 7 + Final Batch Closure
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/StoreTypes.cs`
|
||||
- Modify: `porting.db`
|
||||
- Modify: `reports/current.md`
|
||||
|
||||
**Step 1:** Implement feature `1259` (`StoreCompression.Decompress`) with full per-feature verification loop.
|
||||
|
||||
**Step 2:** Run mandatory stub detection checks across full batch scope.
|
||||
|
||||
**Step 3:** Run final full build and full unit test suite.
|
||||
|
||||
**Step 4:** Perform status cleanup (`complete -> verified`) in <=15-ID chunks with evidence.
|
||||
|
||||
**Step 5:** Attempt batch closure and generate report.
|
||||
|
||||
```bash
|
||||
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch complete 15 --db porting.db
|
||||
./reports/generate-report.sh
|
||||
```
|
||||
|
||||
**Step 6:** Final commit.
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog \
|
||||
porting.db reports/current.md
|
||||
|
||||
git commit -m "feat(batch15): complete msgblock and consumer file store port"
|
||||
```
|
||||
145
docs/plans/2026-02-27-batch-18-server-core-design.md
Normal file
145
docs/plans/2026-02-27-batch-18-server-core-design.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Batch 18 (Server Core) Design
|
||||
|
||||
**Date:** 2026-02-27
|
||||
**Scope:** Design only for Batch 18 (`server/server.go`): 10 features and 8 tests.
|
||||
|
||||
## Context Snapshot
|
||||
|
||||
Batch metadata from PortTracker (`batch show 18`):
|
||||
|
||||
- Batch ID: `18`
|
||||
- Name: `Server Core`
|
||||
- Dependencies: batches `4`, `16`
|
||||
- Go file focus: `golang/nats-server/server/server.go`
|
||||
- Features: `10` (all currently `deferred`)
|
||||
- Tests: `8` (all currently `deferred`)
|
||||
|
||||
Feature IDs in scope:
|
||||
|
||||
- `2982` `s2WriterOptions`
|
||||
- `2987` `Server.logRejectedTLSConns`
|
||||
- `3048` `Server.fetchAccount`
|
||||
- `3066` `Server.getMonitoringTLSConfig`
|
||||
- `3068` `Server.HTTPHandler`
|
||||
- `3078` `tlsTimeout`
|
||||
- `3088` `Server.numRemotes`
|
||||
- `3112` `Server.readyForConnections`
|
||||
- `3118` `Server.String`
|
||||
- `3119` `setGoRoutineLabels`
|
||||
|
||||
Test IDs in scope:
|
||||
|
||||
- `2111` `TestMonitorHandler`
|
||||
- `2167` `BenchmarkXMQTT`
|
||||
- `2382` `TestNoRaceAccountAddServiceImportRace`
|
||||
- `2467` `TestNoRaceRoutePerAccount`
|
||||
- `2468` `TestNoRaceRoutePerAccountSubWithWildcard`
|
||||
- `2481` `TestNoRaceWSNoCorruptionWithFrameSizeLimit`
|
||||
- `2819` `TestRouteIPResolutionAndRouteToSelf`
|
||||
- `2897` `TestInsecureSkipVerifyWarning`
|
||||
|
||||
Repository progress snapshot (`report summary`):
|
||||
|
||||
- Features: `1271 verified`, `2377 deferred`, `24 n_a`, `1 stub`
|
||||
- Unit tests: `430 verified`, `2640 deferred`, `187 n_a`
|
||||
- Overall: `1924/6942 (27.7%)`
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Batch 18 is a narrow but high-leverage seam in `NatsServer`: readiness gates, monitoring handler exposure, TLS timeout/monitor TLS helper behavior, account fetch path naming/parity, and goroutine labeling parity with Go.
|
||||
|
||||
The highest risk is false progress from placeholder tests and name-mismatch implementations:
|
||||
|
||||
1. Several mapped methods are partially covered by equivalent but differently named C# methods, so Roslyn audit can still keep IDs `deferred`.
|
||||
2. Existing `ImplBacklog` test files contain low-signal placeholders (string/constant assertions) that can pass without exercising server behavior.
|
||||
3. Batch 18 tests include benchmark and norace wrappers that may need explicit `deferred` or `n_a` handling instead of fake ports.
|
||||
|
||||
## Approaches
|
||||
|
||||
### Approach A: Minimal audit-alignment wrappers only
|
||||
|
||||
Add exact method names/signatures expected by mappings and delegate to existing logic.
|
||||
|
||||
- Pros: fastest path to audit alignment for deferred features.
|
||||
- Cons: can miss behavior gaps (for example monitor handler lifecycle and readiness semantics).
|
||||
|
||||
### Approach B (Recommended): Behavior-first parity by helper cluster
|
||||
|
||||
Implement exact mapped methods and close semantic gaps in two feature clusters, then port/triage the 8 tests with strict anti-stub evidence.
|
||||
|
||||
- Pros: balances audit alignment and real behavior parity; lower regression risk.
|
||||
- Cons: slightly more effort than wrappers-only.
|
||||
|
||||
### Approach C: Test-first only, defer most features
|
||||
|
||||
Start with Batch 18 tests and defer remaining features when they do not immediately block tests.
|
||||
|
||||
- Pros: fast test activity.
|
||||
- Cons: poor feature closure and likely repeated defer/audit churn.
|
||||
|
||||
## Recommended Design
|
||||
|
||||
### 1. Architecture and File Boundaries
|
||||
|
||||
Keep all Batch 18 work in existing `NatsServer` partials and mapped backlog test classes:
|
||||
|
||||
- Feature implementation files:
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Listeners.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.cs` (only if a shared type/field is required)
|
||||
- Test files:
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttExternalTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs`
|
||||
|
||||
### 2. Feature Grouping Strategy (<=20 per group)
|
||||
|
||||
- **Group A (6 features):** `2982,2987,3066,3068,3078,3119`
|
||||
- Compression writer options helper, TLS rejection log loop parity, monitoring TLS callback, HTTP handler getter lifecycle, TLS handshake timeout helper, goroutine labels helper.
|
||||
- **Group B (4 features):** `3048,3088,3112,3118`
|
||||
- Account fetch parity helper, `numRemotes` internal parity, readiness check parity, `String()` parity.
|
||||
|
||||
### 3. Test Porting/Triage Strategy
|
||||
|
||||
- **Test Group T1 (behavioral, target for verify):** `2111,2819,2897`
|
||||
- Must execute real server behavior (monitor handler lifecycle, route self-resolution logging path, insecure TLS warning path).
|
||||
- **Test Group T2 (non-unit or race wrappers):** `2167,2382,2467,2468,2481`
|
||||
- Evaluate for direct xUnit viability.
|
||||
- If not viable without benchmark tooling/race harness/live infra, keep `deferred` (or set `n_a` when clearly benchmark-only) with explicit reason and zero stubs.
|
||||
|
||||
### 4. Verification Design (adapted from Batch 0 protocol)
|
||||
|
||||
Execution must use hard gates after each feature/test group:
|
||||
|
||||
1. Per-feature loop: read Go function -> implement C# -> build -> run related tests.
|
||||
2. Stub scans over touched feature and test files.
|
||||
3. Build/test gates before any status promotion.
|
||||
4. Status updates in evidence-backed chunks (`<=15` IDs).
|
||||
5. Task checkpoints with full build + full unit test + commit before next task.
|
||||
|
||||
### 5. Risks and Mitigations
|
||||
|
||||
1. **Mapped-name vs existing-name mismatch**
|
||||
Mitigation: add exact mapped methods (or wrappers) and keep behavior in one canonical implementation.
|
||||
2. **Shallow placeholder tests**
|
||||
Mitigation: enforce anti-stub guardrails that reject literal-only assertions and no-act/no-behavior tests.
|
||||
3. **Benchmark/race test portability limits**
|
||||
Mitigation: explicitly classify as `deferred`/`n_a` with concrete blocker text instead of fake-pass tests.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. All 10 Batch 18 features are `verified` or intentionally `deferred/n_a` with evidence and reasons.
|
||||
2. All 8 Batch 18 tests are `verified` or intentionally `deferred/n_a` with evidence and reasons.
|
||||
3. No forbidden stub patterns are introduced in touched feature/test files.
|
||||
4. Batch updates are auditable and bounded (<=15 IDs per update command).
|
||||
|
||||
## Non-Goals
|
||||
|
||||
1. No implementation in this design document.
|
||||
2. No broad refactoring outside Batch 18 server-core scope.
|
||||
3. No fake benchmark/race replacements that produce green tests without behavioral coverage.
|
||||
@@ -0,0 +1,456 @@
|
||||
# Batch 18 (Server Core) Implementation Plan
|
||||
|
||||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Implement and verify Batch 18 server-core behavior from `server/server.go` across 10 features and 8 tests without placeholder logic or fake-pass tests.
|
||||
|
||||
**Architecture:** Execute in two feature groups (6 + 4 IDs) mapped to `NatsServer` partial files, then run two test waves: real behavioral tests first, benchmark/race viability triage second. Promote tracker statuses only with build/test/stub-scan evidence.
|
||||
|
||||
**Tech Stack:** .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (`porting.db`)
|
||||
|
||||
---
|
||||
|
||||
I'm using `writeplan` to create the implementation plan.
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-batch-18-server-core-design.md`
|
||||
|
||||
## Batch Inputs
|
||||
|
||||
- Batch: `18` (`Server Core`)
|
||||
- Depends on: `4`, `16`
|
||||
- Features: `10`
|
||||
- Tests: `8`
|
||||
- Go source focus: `golang/nats-server/server/server.go`
|
||||
|
||||
Feature groups (max ~20 each):
|
||||
|
||||
- **Group A (6):** `2982,2987,3066,3068,3078,3119`
|
||||
- **Group B (4):** `3048,3088,3112,3118`
|
||||
|
||||
Test groups:
|
||||
|
||||
- **T1 (behavioral ports):** `2111,2819,2897`
|
||||
- **T2 (benchmark/race triage):** `2167,2382,2467,2468,2481`
|
||||
|
||||
> If `dotnet` is not on `PATH`, use `/usr/local/share/dotnet/dotnet` in all commands below.
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY VERIFICATION PROTOCOL
|
||||
|
||||
> **NON-NEGOTIABLE:** Every feature/test status change in Batch 18 must satisfy this protocol.
|
||||
|
||||
### Per-Feature Verification Loop (REQUIRED for every feature ID)
|
||||
|
||||
1. Read tracker mapping and Go location:
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature show <FEATURE_ID> --db porting.db
|
||||
```
|
||||
2. Read the exact Go implementation in `golang/nats-server/server/server.go` at mapped lines.
|
||||
3. Write behavior-faithful C# code in the mapped `NatsServer` partial file.
|
||||
4. Build immediately:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
5. Run related tests (targeted filter):
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~<RelatedClassOrMethod>" --verbosity normal
|
||||
```
|
||||
6. Confirm tests were discovered (`Passed` > 0 when expected) and `Failed: 0`.
|
||||
7. Only then add that feature ID to the verified-candidate list.
|
||||
|
||||
### Stub Detection Check (REQUIRED after every feature/test group)
|
||||
|
||||
Run all scans before any `complete` or `verified` promotion:
|
||||
|
||||
```bash
|
||||
# Feature-code stubs
|
||||
grep -R -n -E "NotImplementedException|TODO|PLACEHOLDER" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs
|
||||
|
||||
# Empty method-body detector in feature files touched by Batch 18
|
||||
grep -R -n -E "^[[:space:]]*(public|internal|private|protected)[^{;]*\)[[:space:]]*\{[[:space:]]*\}$" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs
|
||||
|
||||
# Test stubs + fake-pass patterns
|
||||
grep -R -n -E "NotImplementedException|Assert\.True\(true\)|Assert\.Pass|// TODO|// PLACEHOLDER|ShouldContain\(\"Should\"\)|ShouldStartWith\(\"server/\"\)" \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog
|
||||
```
|
||||
|
||||
Any new hit in touched files blocks promotion until fixed or explicitly deferred.
|
||||
|
||||
### Build Gate (REQUIRED after each feature group)
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
|
||||
Required: `0` errors.
|
||||
|
||||
### Test Gate (REQUIRED before marking features `verified`)
|
||||
|
||||
All related tests for the feature group must pass before `complete -> verified`:
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ServerTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ServerLifecycleStubFeaturesTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.RouteHandlerTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsServerTests" --verbosity normal
|
||||
```
|
||||
|
||||
Required: `Failed: 0` and non-trivial execution for changed scenarios.
|
||||
|
||||
### Status Update Protocol (REQUIRED)
|
||||
|
||||
1. Maximum **15 IDs per `feature batch-update` or `test batch-update` call**.
|
||||
2. Evidence required per update chunk:
|
||||
- Go source reviewed for each ID.
|
||||
- Build gate passed.
|
||||
- Related tests passed.
|
||||
- Stub scan clean.
|
||||
3. No blind promotion:
|
||||
- Features: `deferred -> stub -> complete -> verified`.
|
||||
- Tests: `deferred -> stub -> verified` (or `deferred/n_a` with explicit reason).
|
||||
4. If Roslyn audit disagrees, require explicit override reason.
|
||||
|
||||
### Checkpoint Protocol Between Tasks (REQUIRED)
|
||||
|
||||
After each task (and before the next):
|
||||
|
||||
1. Full build:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
2. Full unit-test pass:
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
|
||||
```
|
||||
3. Verify no new regressions.
|
||||
4. Commit checkpoint:
|
||||
```bash
|
||||
git add <touched-files> porting.db
|
||||
git commit -m "<checkpoint message>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)
|
||||
|
||||
### Forbidden Patterns
|
||||
|
||||
Do not introduce or keep any of these in Batch 18 scope:
|
||||
|
||||
- `throw new NotImplementedException(...)`
|
||||
- `// TODO` or `// PLACEHOLDER` in executable Batch 18 paths
|
||||
- Empty method bodies (`{ }`) for mapped Batch 18 features
|
||||
- Tests that only assert constants/labels (for example `"...ShouldSucceed".ShouldContain("Should")`)
|
||||
- Tests that never execute target server behavior (no real Arrange/Act against `NatsServer`)
|
||||
- Fake wrappers that ignore inputs and always return success values
|
||||
|
||||
### Hard Limits
|
||||
|
||||
- Max ~20 feature IDs per implementation task group (Batch 18 uses `6` and `4`)
|
||||
- Max 15 IDs per status-update command
|
||||
- No status promotion without clean stub scan + build gate + test gate
|
||||
- No cross-group status updates until current group is fully verified/deferred
|
||||
- Mandatory commit at each checkpoint
|
||||
|
||||
### If You Get Stuck
|
||||
|
||||
1. Stop on the blocked item; do not add a stub workaround.
|
||||
2. Do **not** write fake-pass tests or no-op implementations.
|
||||
3. Mark the exact ID as `deferred` (or `n_a` for benchmark-only items) with specific reason:
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature update <ID> --status deferred --db porting.db \
|
||||
--override "blocked: <specific infra/dependency reason>"
|
||||
```
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
test update <ID> --status deferred --db porting.db \
|
||||
--override "blocked: <specific infra/dependency reason>"
|
||||
```
|
||||
4. Continue with the next unblocked ID.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Preflight and Batch Activation
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1: Confirm dependency readiness and batch contents**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 18 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch ready --db porting.db
|
||||
```
|
||||
|
||||
**Step 2: Start batch**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch start 18 --db porting.db
|
||||
```
|
||||
|
||||
**Step 3: Move Group A features to `stub` (<=15 IDs)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "2982,2987,3066,3068,3078,3119" \
|
||||
--set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 4: Commit checkpoint**
|
||||
|
||||
```bash
|
||||
git add porting.db
|
||||
git commit -m "chore(batch18): start batch and stage group-a features"
|
||||
```
|
||||
|
||||
### Task 2: Group A Features (6) - Compression/TLS/Monitoring/Goroutine Labels
|
||||
|
||||
**Feature IDs:** `2982,2987,3066,3068,3078,3119`
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Listeners.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ServerTests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
|
||||
**Step 1: Add/extend failing tests for Group A behavior**
|
||||
|
||||
Target behaviors:
|
||||
- S2 writer-option mapping behavior (`s2WriterOptions`).
|
||||
- TLS rejection log loop cadence and warning behavior.
|
||||
- Monitoring TLS config clone + `ClientAuth` override.
|
||||
- `HTTPHandler` returns non-null while monitor is active and null after shutdown.
|
||||
- TLS handshake timeout closure path.
|
||||
- Goroutine label helper invoked by task start path (or explicit helper test if direct validation is feasible).
|
||||
|
||||
**Step 2: Run focused tests and confirm failures first**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ServerTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests" --verbosity normal
|
||||
```
|
||||
|
||||
**Step 3: Implement Group A methods with per-feature loop**
|
||||
|
||||
For each of the 6 feature IDs: read Go -> implement -> build -> run related tests.
|
||||
|
||||
**Step 4: Run mandatory stub detection + build gate + test gate**
|
||||
|
||||
Use protocol commands above.
|
||||
|
||||
**Step 5: Promote Group A feature statuses (`complete`, then `verified`)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "2982,2987,3066,3068,3078,3119" \
|
||||
--set-status complete --db porting.db --execute
|
||||
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "2982,2987,3066,3068,3078,3119" \
|
||||
--set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint protocol + commit**
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Listeners.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ServerTests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs \
|
||||
porting.db
|
||||
git commit -m "feat(batch18): implement group-a server core helpers"
|
||||
```
|
||||
|
||||
### Task 3: Group B Features (4) - Accounts/Readiness/Introspection
|
||||
|
||||
**Feature IDs:** `3048,3088,3112,3118`
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/ServerLifecycleStubFeaturesTests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs`
|
||||
|
||||
**Step 1: Write/extend failing tests for Group B behavior**
|
||||
|
||||
Target behaviors:
|
||||
- Account fetch path parity (`fetchAccount` wrapper/behavior alignment).
|
||||
- Internal `numRemotes` path parity under lock.
|
||||
- `readyForConnections` path parity for listener checks and timeout errors.
|
||||
- `String()` / `ToString()` parity on server identity.
|
||||
|
||||
**Step 2: Run focused tests and confirm failures first**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ServerLifecycleStubFeaturesTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.RouteHandlerTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsServerTests" --verbosity normal
|
||||
```
|
||||
|
||||
**Step 3: Implement Group B methods with per-feature loop**
|
||||
|
||||
For each of the 4 feature IDs: read Go -> implement -> build -> run related tests.
|
||||
|
||||
**Step 4: Run mandatory stub detection + build gate + test gate**
|
||||
|
||||
Use protocol commands above.
|
||||
|
||||
**Step 5: Promote Group B feature statuses (`complete`, then `verified`)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "3048,3088,3112,3118" \
|
||||
--set-status complete --db porting.db --execute
|
||||
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "3048,3088,3112,3118" \
|
||||
--set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint protocol + commit**
|
||||
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/ServerLifecycleStubFeaturesTests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs \
|
||||
porting.db
|
||||
git commit -m "feat(batch18): implement group-b server core helpers"
|
||||
```
|
||||
|
||||
### Task 4: Test Group T1 (Behavioral Tests) - Verify 3 Tests
|
||||
|
||||
**Test IDs:** `2111,2819,2897`
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs`
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1: For each test ID, read mapping + Go source and port behavior intent**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test show <TEST_ID> --db porting.db
|
||||
```
|
||||
|
||||
**Step 2: Run each test method individually (must execute and pass)**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~<MappedClass>.<MappedMethod>" --verbosity normal
|
||||
```
|
||||
|
||||
**Step 3: Run class-level validation for touched classes**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.RouteHandlerTests" --verbosity normal
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsServerTests" --verbosity normal
|
||||
```
|
||||
|
||||
**Step 4: Update T1 tests in one chunk (<=15 IDs)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
test batch-update --ids "2111,2819,2897" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Checkpoint protocol + commit**
|
||||
|
||||
```bash
|
||||
git add dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs \
|
||||
porting.db
|
||||
git commit -m "test(batch18): port behavioral batch-18 tests"
|
||||
```
|
||||
|
||||
### Task 5: Test Group T2 (Benchmark/Race Triage) - Resolve 5 Tests Without Stubs
|
||||
|
||||
**Test IDs:** `2167,2382,2467,2468,2481`
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttExternalTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1: Evaluate each Go test for xUnit viability**
|
||||
|
||||
- `2167` is a Go benchmark (`BenchmarkXMQTT`): classify as `n_a` unless a benchmark harness is explicitly introduced.
|
||||
- Norace wrapper tests (`2382,2467,2468,2481`): verify whether meaningful deterministic unit assertions can be ported.
|
||||
|
||||
**Step 2: For viable tests, implement and verify with single-test execution**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~ImplBacklog.ConcurrencyTests" --verbosity normal
|
||||
```
|
||||
|
||||
**Step 3: For non-viable tests, set `deferred` or `n_a` with concrete reasons**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
test update 2167 --status n_a --db porting.db \
|
||||
--override "BenchmarkXMQTT is benchmark-only and not an xUnit unit-test target"
|
||||
```
|
||||
|
||||
(Repeat for remaining blocked IDs with specific blocker text.)
|
||||
|
||||
**Step 4: Run stub scan and checkpoint protocol, then commit**
|
||||
|
||||
```bash
|
||||
git add dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttExternalTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs \
|
||||
porting.db
|
||||
git commit -m "test(batch18): triage benchmark and norace mapped tests"
|
||||
```
|
||||
|
||||
### Task 6: Final Batch 18 Verification and Closure
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Generate: `reports/current.md`
|
||||
|
||||
**Step 1: Final full verification**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
|
||||
```
|
||||
|
||||
**Step 2: Batch-wide stub audit**
|
||||
|
||||
```bash
|
||||
grep -R -n -E "NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)|Assert\.Pass|ShouldContain\(\"Should\"\)" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog
|
||||
```
|
||||
|
||||
**Step 3: Validate batch status and close**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 18 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch complete 18 --db porting.db
|
||||
```
|
||||
|
||||
**Step 4: Refresh reports and final commit**
|
||||
|
||||
```bash
|
||||
./reports/generate-report.sh
|
||||
git add porting.db reports/
|
||||
git commit -m "chore(batch18): complete server-core batch with verified evidence"
|
||||
```
|
||||
|
||||
123
docs/plans/2026-02-27-batch-19-accounts-core-design.md
Normal file
123
docs/plans/2026-02-27-batch-19-accounts-core-design.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# Batch 19 Accounts Core Design
|
||||
|
||||
## Context
|
||||
|
||||
- Batch: `19` (`Accounts Core`)
|
||||
- Scope: `92` features, `9` tests
|
||||
- Dependencies: Batches `16`, `18`
|
||||
- Primary Go reference: `golang/nats-server/server/accounts.go`
|
||||
- Primary .NET target: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
|
||||
Batch 19 is the largest non-JetStream account behavior surface: service import/export wiring, reverse reply tracking, activation and issuer checks, leaf-node cluster bookkeeping, and account-level message tracing hooks.
|
||||
|
||||
## Constraints
|
||||
|
||||
- No stubs for feature or test completion.
|
||||
- Port behavior from Go intent, not line-for-line syntax.
|
||||
- Keep batch execution chunked (max ~20 features per task group).
|
||||
- Keep PortTracker status updates evidence-based and chunked (max 15 IDs per update call).
|
||||
- Dependencies `16` and `18` must be complete before execution starts.
|
||||
|
||||
## Approaches Considered
|
||||
|
||||
### Approach A (Recommended): Incremental Port in Existing `Account.cs` + Backlog Test Hardening
|
||||
|
||||
- Keep `Account` in its current file and add missing methods in ordered regions.
|
||||
- Use feature groups aligned to Go line ranges and behavior domains.
|
||||
- Promote features `stub -> complete` during implementation; only promote to `verified` after related tests are green.
|
||||
- Port only Batch 19 test IDs in existing backlog classes first, then run broader account-related suite gates.
|
||||
|
||||
Pros:
|
||||
- Lowest structural risk and least file churn.
|
||||
- Preserves current locking/state conventions already used in `Account.cs`.
|
||||
- Easier diff review against Go line ranges and PortTracker IDs.
|
||||
|
||||
Cons:
|
||||
- `Account.cs` grows further until later refactor batch.
|
||||
|
||||
### Approach B: Convert `Account` to Partial Class and Split by Domain During Port
|
||||
|
||||
- First convert `Account` to `partial`, then create files like `Account.ServiceImports.cs`, `Account.StreamImports.cs`, etc.
|
||||
- Port methods into these new files while adding tests.
|
||||
|
||||
Pros:
|
||||
- Cleaner file organization.
|
||||
- Better long-term readability.
|
||||
|
||||
Cons:
|
||||
- Larger structural change while behavior is still moving.
|
||||
- Higher merge risk and harder one-to-one audit against existing method maps.
|
||||
|
||||
### Approach C: Minimal Compile-First Skeletons, Fill Later
|
||||
|
||||
- Add signatures and placeholders quickly to satisfy compile, then fill behavior in later passes.
|
||||
|
||||
Pros:
|
||||
- Fast initial progress indicators.
|
||||
|
||||
Cons:
|
||||
- Violates anti-stub requirements.
|
||||
- High risk of false progress and broken verification integrity.
|
||||
|
||||
Decision: **Approach A**.
|
||||
|
||||
## Proposed Architecture
|
||||
|
||||
### 1. Keep Account Behavior Localized to `Account.cs`
|
||||
|
||||
- Implement missing Batch 19 methods directly in `Account.cs`.
|
||||
- Only modify `AccountTypes.cs` when a missing helper type/field is required by real behavior.
|
||||
- Avoid cross-module refactors while porting this batch.
|
||||
|
||||
### 2. Feature Grouping Strategy
|
||||
|
||||
Use five implementation groups with contiguous, behavior-aligned IDs:
|
||||
|
||||
1. Group 1 (17 features): identity, trace destination, connection/interest, leaf cluster registration, base service export registration
|
||||
2. Group 2 (20 features): latency tracking send paths + service import cycle checks + pending response counters
|
||||
3. Group 3 (20 features): service import map mutation, reverse response tracking, internal subscription lifecycle, response wildcard processing
|
||||
4. Group 4 (20 features): service reply generation, thresholds, response import wiring, stream import/export add and authorization checks
|
||||
5. Group 5 (15 features): activation expiration paths, issuer trust checks, bearer/expiration handling, external auth helpers
|
||||
|
||||
Each group is independently buildable and testable.
|
||||
|
||||
### 3. Test Porting Strategy for the 9 Batch Tests
|
||||
|
||||
Port only these IDs in backlog classes:
|
||||
|
||||
- `81`, `82`, `95` -> `ImplBacklog/AccountTests.Impltests.cs`
|
||||
- `658`, `666` -> `ImplBacklog/GatewayHandlerTests.Impltests.cs`
|
||||
- `1935`, `1952`, `1955` -> `ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
|
||||
- `2359` -> `ImplBacklog/MessageTracerTests.Impltests.cs`
|
||||
|
||||
Replace placeholder tests with behavioral assertions derived from Go test intent.
|
||||
|
||||
### 4. Verification-First Status Flow
|
||||
|
||||
- During coding: move feature IDs to `stub`.
|
||||
- After implementation + build + related tests: move to `complete`.
|
||||
- After full related test gate and evidence capture: move to `verified`.
|
||||
- If blocked: keep `deferred` with explicit reason (no placeholder code).
|
||||
|
||||
## Error Handling and Concurrency Design Notes
|
||||
|
||||
- Preserve lock discipline already used in `Account.cs` (`_mu`, `_lmu`, `_sqmu`, `_eventIdsMu`).
|
||||
- Do not widen lock scopes unless required for correctness parity with Go behavior.
|
||||
- Preserve existing exception-return pattern used by account APIs (`Exception?` return for validation paths).
|
||||
- Preserve current JWT placeholder boundaries; if JWT-infra dependency is missing, defer with reason instead of stubbing.
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
- Risk: long `Account.cs` diffs become hard to review.
|
||||
- Mitigation: strict feature grouping + per-group checkpoints + frequent commits.
|
||||
- Risk: false-positive "passing" backlog tests.
|
||||
- Mitigation: anti-stub scans and required per-test behavioral assertions.
|
||||
- Risk: status inflation without evidence.
|
||||
- Mitigation: max-15 ID update chunks + required command output evidence per chunk.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- All 92 Batch 19 feature IDs are `verified` or explicitly `deferred` with reason.
|
||||
- All 9 Batch 19 test IDs are `verified` or explicitly `deferred` with reason.
|
||||
- No forbidden stub patterns in touched source/tests.
|
||||
- Full build and required test gates pass at each checkpoint.
|
||||
@@ -0,0 +1,564 @@
|
||||
# Batch 19 Accounts Core Implementation Plan
|
||||
|
||||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Port and verify Batch 19 (`Accounts Core`) by implementing 92 `Account` features from `server/accounts.go` and porting 9 mapped tests without introducing stubs.
|
||||
|
||||
**Architecture:** Implement missing Batch 19 behavior directly in `Account.cs` in five feature groups (max 20 each), preserve existing lock/state patterns, and harden the 9 mapped backlog tests into real behavioral tests. Promote IDs through `stub -> complete -> verified` only with captured build/test evidence.
|
||||
|
||||
**Tech Stack:** .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (`porting.db`)
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-batch-19-accounts-core-design.md`
|
||||
|
||||
---
|
||||
|
||||
## Batch 19 Scope
|
||||
|
||||
- Batch ID: `19`
|
||||
- Name: `Accounts Core`
|
||||
- Dependencies: batches `16`, `18`
|
||||
- Go source: `golang/nats-server/server/accounts.go`
|
||||
- Feature count: `92`
|
||||
- Test count: `9`
|
||||
|
||||
Primary .NET files expected:
|
||||
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs` (only if needed by real behavior)
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/GatewayHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MessageTracerTests.Impltests.cs`
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY VERIFICATION PROTOCOL
|
||||
|
||||
> **NON-NEGOTIABLE:** Every feature and test in this batch must follow this protocol.
|
||||
|
||||
### Per-Feature Verification Loop (REQUIRED for each feature ID)
|
||||
|
||||
1. Read feature metadata and Go source range:
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature show <feature_id> --db porting.db
|
||||
sed -n '<start_line>,<end_line>p' golang/nats-server/server/accounts.go
|
||||
```
|
||||
2. Implement the mapped C# method in `Account.cs` (or supporting type in `AccountTypes.cs` if strictly required).
|
||||
3. Build immediately:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
4. Run related tests immediately (smallest relevant filter first):
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~AccountTests"
|
||||
```
|
||||
5. If green, record feature ID in the current "complete-candidate" list.
|
||||
6. If red, fix before touching next feature ID.
|
||||
|
||||
### Stub Detection Check (REQUIRED after each feature group and test class)
|
||||
|
||||
Run scan before status updates:
|
||||
|
||||
```bash
|
||||
rg -n "(NotImplementedException|TODO|PLACEHOLDER|throw new Exception\\(\"TODO\"\\))" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/GatewayHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MessageTracerTests.Impltests.cs
|
||||
|
||||
rg -n "^\\s*(public|internal|private)\\s+.*\\)\\s*\\{\\s*\\}$" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs
|
||||
```
|
||||
|
||||
Any new match in touched code must be fixed or explicitly deferred in PortTracker. No status promotion with unresolved stub hits.
|
||||
|
||||
### Build Gate (REQUIRED after each feature group)
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
|
||||
`Build succeeded` is required before moving any group IDs to `complete` or `verified`.
|
||||
|
||||
### Test Gate (REQUIRED before any feature ID is set to `verified`)
|
||||
|
||||
All related tests must pass:
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.GatewayHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.LeafNodeHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.MessageTracerTests"
|
||||
```
|
||||
|
||||
Do not mark features `verified` until the 9 mapped Batch 19 tests are real and passing.
|
||||
|
||||
### Status Update Protocol (REQUIRED)
|
||||
|
||||
- Max `15` IDs per `feature batch-update` or `test batch-update` call.
|
||||
- Required sequence:
|
||||
- `not_started/deferred -> stub` when you begin active work.
|
||||
- `stub -> complete` only after per-feature loop + group build/test pass.
|
||||
- `complete -> verified` only after full test gate and evidence capture.
|
||||
- Evidence required for each update chunk:
|
||||
- last successful build output summary
|
||||
- last related test output summary
|
||||
- stub scan output (`0` unresolved matches for touched code)
|
||||
|
||||
### Checkpoint Protocol Between Tasks (REQUIRED)
|
||||
|
||||
At end of each task group (before starting next):
|
||||
|
||||
1. Run full build:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
2. Run unit tests:
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
3. Commit checkpoint:
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "<task-specific message>"
|
||||
```
|
||||
4. Continue only if build green and no new failing tests.
|
||||
|
||||
---
|
||||
|
||||
## ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)
|
||||
|
||||
### Forbidden Patterns
|
||||
|
||||
These patterns are forbidden in completed Batch 19 features/tests:
|
||||
|
||||
- `throw new NotImplementedException()`
|
||||
- Empty method bodies (`{ }`) for mapped feature methods
|
||||
- Placeholder tests that only assert constants unrelated to Account behavior
|
||||
- `Assert.True(true)` or equivalent always-pass assertion
|
||||
- `// TODO` or `// PLACEHOLDER` in newly ported feature/test bodies
|
||||
- Returning hardcoded defaults (`false`, `null`, `0`, `string.Empty`) where Go behavior is non-trivial
|
||||
|
||||
### Hard Limits
|
||||
|
||||
- Maximum `20` features per implementation task group.
|
||||
- Maximum `15` IDs per status update call.
|
||||
- One feature group at a time; no parallel status promotion.
|
||||
- No `verified` status updates while any mapped Batch 19 test ID remains deferred/stub without explicit blocker reason.
|
||||
|
||||
### If You Get Stuck
|
||||
|
||||
1. Stop the current feature/test ID immediately.
|
||||
2. Revert any partial placeholder code for that ID.
|
||||
3. Keep or set status to `deferred` with explicit reason:
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status deferred --override "blocked: <specific reason>" --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test update <id> --status deferred --override "blocked: <specific reason>" --db porting.db
|
||||
```
|
||||
4. Move to the next unblocked ID.
|
||||
5. Never introduce stubs just to keep momentum.
|
||||
|
||||
---
|
||||
|
||||
## Feature Group Map (Max 20 per Task)
|
||||
|
||||
### Group 1 (17 IDs): Trace, Counters, Interest, Leaf Cluster, Base Service Exports
|
||||
|
||||
`152,153,154,170,176,189,190,192,193,194,198,199,200,201,202,203,204`
|
||||
|
||||
### Group 2 (20 IDs): Latency Send Paths, Service Import Cycle Checks, Pending Counters
|
||||
|
||||
`210,211,212,213,214,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230`
|
||||
|
||||
### Group 3 (20 IDs): Service Import Mutation, Reverse Reply Map, Internal Subs, Response Processing
|
||||
|
||||
`231,232,233,234,235,236,237,238,239,240,241,243,244,245,246,247,248,249,254,255`
|
||||
|
||||
### Group 4 (20 IDs): Reply Generation, Thresholds, Resp Imports, Stream Import/Export Wiring
|
||||
|
||||
`257,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,280,281,282,283`
|
||||
|
||||
### Group 5 (15 IDs): Activation/Issuer/Auth Tail
|
||||
|
||||
`284,286,287,294,295,301,302,303,304,305,311,312,313,314,315`
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Preflight and Batch Start
|
||||
|
||||
**Files:**
|
||||
- Read: `docs/standards/dotnet-standards.md`
|
||||
- Read: `golang/nats-server/server/accounts.go`
|
||||
- Read: `docs/plans/2026-02-27-batch-19-accounts-core-design.md`
|
||||
|
||||
**Step 1: Validate dependencies and batch status**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 19 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db
|
||||
```
|
||||
|
||||
Expected: Batch 19 shown with dependencies `16,18`.
|
||||
|
||||
**Step 2: Start the batch**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch start 19 --db porting.db
|
||||
```
|
||||
|
||||
Expected: batch moves to `in_progress` (or clear dependency failure if blocked).
|
||||
|
||||
**Step 3: Baseline build and tests**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
|
||||
Expected: capture baseline pass/fail before edits.
|
||||
|
||||
**Step 4: Commit checkpoint**
|
||||
|
||||
```bash
|
||||
git add porting.db
|
||||
git commit -m "chore(batch19): start accounts core batch"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Implement Group 1 Features (17 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- Optional modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
||||
- Related tests: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Accounts/AccountTests.cs`
|
||||
|
||||
**Step 1: Mark Group 1 as `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "152,153,154,170,176,189,190,192,193,194,198,199,200,201,202" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "203,204" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Run per-feature loop for all 17 IDs**
|
||||
|
||||
For each ID: `feature show` -> read Go lines -> implement C# -> `dotnet build` -> run related tests.
|
||||
|
||||
**Step 3: Group gate**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.AccountTests"
|
||||
```
|
||||
|
||||
**Step 4: Stub detection scan**
|
||||
|
||||
Run the required scan commands from the mandatory protocol.
|
||||
|
||||
**Step 5: Mark Group 1 as `complete` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "152,153,154,170,176,189,190,192,193,194,198,199,200,201,202" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "203,204" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts porting.db
|
||||
git commit -m "feat(batch19): implement account trace/counter/export core methods"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Implement Group 2 Features (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- Optional modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
||||
- Related tests: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Accounts/AccountTests.cs`
|
||||
|
||||
**Step 1: Mark Group 2 as `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "210,211,212,213,214,216,217,218,219,220,221,222,223,224,225" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "226,227,228,229,230" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Run per-feature loop for all 20 IDs**
|
||||
|
||||
Implement and verify each ID individually.
|
||||
|
||||
**Step 3: Group gate**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.AccountTests"
|
||||
```
|
||||
|
||||
**Step 4: Stub detection scan**
|
||||
|
||||
Run required scan commands.
|
||||
|
||||
**Step 5: Mark Group 2 as `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "210,211,212,213,214,216,217,218,219,220,221,222,223,224,225" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "226,227,228,229,230" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts porting.db
|
||||
git commit -m "feat(batch19): implement account latency and import-cycle methods"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Implement Group 3 Features (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- Optional modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
||||
- Related tests: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs`
|
||||
|
||||
**Step 1: Mark Group 3 as `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "231,232,233,234,235,236,237,238,239,240,241,243,244,245,246" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "247,248,249,254,255" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Run per-feature loop for all 20 IDs**
|
||||
|
||||
Implement and verify each ID individually.
|
||||
|
||||
**Step 3: Group gate**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.AccountTests"
|
||||
```
|
||||
|
||||
**Step 4: Stub detection scan**
|
||||
|
||||
Run required scan commands.
|
||||
|
||||
**Step 5: Mark Group 3 as `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "231,232,233,234,235,236,237,238,239,240,241,243,244,245,246" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "247,248,249,254,255" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts porting.db
|
||||
git commit -m "feat(batch19): implement service import maps and response subscription methods"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Implement Group 4 Features (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- Optional modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
||||
- Related tests: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs`
|
||||
- Related tests: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/GatewayHandlerTests.Impltests.cs`
|
||||
- Related tests: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
|
||||
|
||||
**Step 1: Mark Group 4 as `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "257,262,263,264,265,266,267,268,269,270,271,272,273,274,275" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "276,280,281,282,283" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Run per-feature loop for all 20 IDs**
|
||||
|
||||
Implement and verify each ID individually.
|
||||
|
||||
**Step 3: Group gate**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.GatewayHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.LeafNodeHandlerTests"
|
||||
```
|
||||
|
||||
**Step 4: Stub detection scan**
|
||||
|
||||
Run required scan commands.
|
||||
|
||||
**Step 5: Mark Group 4 as `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "257,262,263,264,265,266,267,268,269,270,271,272,273,274,275" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "276,280,281,282,283" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts porting.db
|
||||
git commit -m "feat(batch19): implement service reply and stream import/export methods"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Implement Group 5 Features (15 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- Optional modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
||||
- Related tests: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MessageTracerTests.Impltests.cs`
|
||||
|
||||
**Step 1: Mark Group 5 as `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "284,286,287,294,295,301,302,303,304,305,311,312,313,314,315" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Run per-feature loop for all 15 IDs**
|
||||
|
||||
Implement and verify each ID individually.
|
||||
|
||||
**Step 3: Group gate**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MessageTracerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.AccountTests"
|
||||
```
|
||||
|
||||
**Step 4: Stub detection scan**
|
||||
|
||||
Run required scan commands.
|
||||
|
||||
**Step 5: Mark Group 5 as `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "284,286,287,294,295,301,302,303,304,305,311,312,313,314,315" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts porting.db
|
||||
git commit -m "feat(batch19): implement activation, issuer, and external auth account methods"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Port and Verify Batch 19 Tests (9 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs` (IDs `81,82,95`)
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/GatewayHandlerTests.Impltests.cs` (IDs `658,666`)
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs` (IDs `1935,1952,1955`)
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MessageTracerTests.Impltests.cs` (ID `2359`)
|
||||
|
||||
**Step 1: Mark test IDs as `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "81,82,95,658,666,1935,1952,1955,2359" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Per-test loop for all 9 IDs**
|
||||
|
||||
For each test ID: `test show` -> read Go test -> port C# method -> run single-test filter -> capture pass.
|
||||
|
||||
**Step 3: Run class-level test gates**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.GatewayHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.LeafNodeHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MessageTracerTests"
|
||||
```
|
||||
|
||||
**Step 4: Run stub detection scan on touched test files**
|
||||
|
||||
Run required scan commands.
|
||||
|
||||
**Step 5: Mark tests as `verified`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "81,82,95,658,666,1935,1952,1955,2359" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "test(batch19): port accounts core mapped tests"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 8: Promote Features to Verified and Complete Batch 19
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1: Re-run full build and all related test gates**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
|
||||
**Step 2: Promote Group 1 and Group 2 features to `verified` (max-15 chunks)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "152,153,154,170,176,189,190,192,193,194,198,199,200,201,202" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "203,204,210,211,212,213,214,216,217,218,219,220,221,222,223" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "224,225,226,227,228,229,230" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 3: Promote Group 3 and Group 4 features to `verified` (max-15 chunks)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "231,232,233,234,235,236,237,238,239,240,241,243,244,245,246" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "247,248,249,254,255,257,262,263,264,265,266,267,268,269,270" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "271,272,273,274,275,276,280,281,282,283" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 4: Promote Group 5 features to `verified`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "284,286,287,294,295,301,302,303,304,305,311,312,313,314,315" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Final batch complete validation**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch complete 19 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
|
||||
```
|
||||
|
||||
**Step 6: Final checkpoint commit**
|
||||
|
||||
```bash
|
||||
git add porting.db dotnet/src/ZB.MOM.NatsNet.Server/Accounts dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog
|
||||
git commit -m "feat(batch19): complete and verify accounts core"
|
||||
```
|
||||
124
docs/plans/2026-02-27-batch-20-accounts-resolvers-design.md
Normal file
124
docs/plans/2026-02-27-batch-20-accounts-resolvers-design.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# Batch 20 Accounts Resolvers Design
|
||||
|
||||
## Context
|
||||
|
||||
- Batch: `20` (`Accounts Resolvers`)
|
||||
- Scope: `38` features, `98` tests
|
||||
- Dependency: Batch `19` (`Accounts Core`)
|
||||
- Primary Go reference: `golang/nats-server/server/accounts.go`
|
||||
- Primary .NET targets:
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountResolver.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
|
||||
Batch 20 closes resolver-focused account behavior that Batch 19 intentionally deferred: resolver wiring, directory/cache resolver behavior, account-claim refresh paths, service-latency sampling helpers, operator-key validation helpers, and update/list/delete request handling.
|
||||
|
||||
## Goals
|
||||
|
||||
1. Port all 38 mapped features from `server/accounts.go` with behavior parity and no placeholders.
|
||||
2. Port or verify all 98 mapped tests as real behavioral tests (or keep deferred with explicit blocker reason).
|
||||
3. Enforce evidence-based status movement (`deferred/not_started -> stub -> complete -> verified`) with strict guardrails.
|
||||
4. Preserve existing .NET architecture (partial `NatsServer`, resolver types, existing account models) and avoid speculative refactors.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No broad refactor of account architecture into new modules.
|
||||
- No cross-batch JetStream/cluster rearchitecture beyond what Batch 20 features require.
|
||||
- No status inflation via stubs or placeholder tests.
|
||||
|
||||
## Approaches Considered
|
||||
|
||||
### Approach A (Recommended): Incremental in-place port with feature-first then test verification
|
||||
|
||||
Implement features in existing files grouped by behavior and Go line proximity (2 groups, 19 IDs each), run verification gates after each group, then complete mapped test classes in focused waves.
|
||||
|
||||
Pros:
|
||||
- Lowest merge risk and minimal structural churn.
|
||||
- Keeps audit traceability from feature ID -> Go range -> .NET method.
|
||||
- Works with existing partial implementations and comments in `AccountResolver.cs` and `NatsServer.Accounts.cs`.
|
||||
|
||||
Cons:
|
||||
- Resolver behavior spans multiple files, so discipline is required to avoid mixed concerns in a single commit.
|
||||
|
||||
### Approach B: Split resolver code into additional partial classes before feature work
|
||||
|
||||
Create new files such as `NatsServer.AccountResolver.cs` and `AccountResolver.Sync.cs`, then implement features.
|
||||
|
||||
Pros:
|
||||
- Cleaner long-term separation.
|
||||
|
||||
Cons:
|
||||
- Adds structural churn while behavior is still moving.
|
||||
- Harder to compare with existing tracker mappings and current code layout.
|
||||
|
||||
### Approach C: Signature-first scaffolding, behavior later
|
||||
|
||||
Add all signatures and minimal bodies quickly, then fill behavior later.
|
||||
|
||||
Pros:
|
||||
- Fast initial check-ins.
|
||||
|
||||
Cons:
|
||||
- Violates anti-stub constraints and verification integrity.
|
||||
- Creates false progress.
|
||||
|
||||
Decision: **Approach A**.
|
||||
|
||||
## Proposed Design
|
||||
|
||||
### 1. Feature Implementation Shape
|
||||
|
||||
Implement Batch 20 features in current target files:
|
||||
|
||||
- `AccountTypes.cs`: enum/string/latency helpers (`ServiceRespType.String`, `ServiceLatency.merge`, `NewMapDest`, sanitization helpers).
|
||||
- `Account.cs`: account-local helpers (`setExportAuth`, sampling/header helpers, service import/export response tracking helpers, `authAccounts`, operator/claim helpers).
|
||||
- `NatsServer.Accounts.cs`: resolver integration methods (`SetAccountResolver`, `UpdateAccountClaims`, `updateAccountClaimsWithRefresh`, server fetch/update flows).
|
||||
- `AccountResolver.cs`: default resolver store behavior, memory/url/dir/cache resolver fetch/store/reload/start wiring and option handling.
|
||||
|
||||
### 2. Feature Grouping (Max ~20 IDs Each)
|
||||
|
||||
- Group 1 (19 IDs): `150,183,197,208,209,215,250,251,252,253,258,259,260,261,306,307,310,316,318`
|
||||
- Group 2 (19 IDs): `319,320,326,327,328,330,331,334,335,336,337,338,339,341,343,345,346,347,349`
|
||||
|
||||
This keeps each implementation wave auditable and within the requested size limit.
|
||||
|
||||
### 3. Test Strategy (98 IDs)
|
||||
|
||||
Port tests in existing backlog classes, then gate feature verification on passing related tests:
|
||||
|
||||
- High-volume classes: `ConfigReloaderTests` (40), `NatsConsumerTests` (16), `JetStreamEngineTests` (12), `JwtProcessorTests` (9).
|
||||
- Medium/small classes: `AccountTests` (4), `EventsHandlerTests` (3), `MonitoringHandlerTests` (2), `MqttHandlerTests` (2), and single-test classes (`ConcurrencyTests2`, `GatewayHandlerTests`, `JetStreamBatchingTests`, `JetStreamFileStoreTests`, `MqttExternalTests`, `NatsServerTests`).
|
||||
|
||||
Tests remain in `ImplBacklog/*.Impltests.cs` unless a mapped test already belongs in an existing non-backlog class.
|
||||
|
||||
### 4. Status and Evidence Model
|
||||
|
||||
- Mark active IDs as `stub` only when implementation starts.
|
||||
- Promote to `complete` only after per-feature loop + group build gate + related targeted tests.
|
||||
- Promote to `verified` only after mapped test gate passes and stub scans are clean.
|
||||
- If blocked, keep `deferred` with explicit reason; do not add placeholders.
|
||||
|
||||
## Error Handling and Concurrency Notes
|
||||
|
||||
- Preserve lock and lifecycle discipline already present in `NatsServer`/`Account` code.
|
||||
- Use existing exception-return conventions for account validation/fetch paths.
|
||||
- Keep async resolver API contracts with `CancellationToken`.
|
||||
- Avoid introducing blocking waits in newly async paths beyond established project conventions.
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
- Risk: hidden dependency on not-yet-ported event/system wiring.
|
||||
- Mitigation: explicit deferred status with reason and no stubs.
|
||||
- Risk: broad regression surface (98 mapped tests across many classes).
|
||||
- Mitigation: class-by-class test waves plus mandatory full checkpoint runs.
|
||||
- Risk: false positives from legacy TODO comments in untouched files.
|
||||
- Mitigation: baseline stub-scan snapshot and fail only on new violations in touched code.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. All 38 Batch 20 feature IDs are `verified` or `deferred` with explicit blocker notes.
|
||||
2. All 98 Batch 20 test IDs are `verified` or `deferred` with explicit blocker notes.
|
||||
3. No newly introduced stub patterns in touched source or test files.
|
||||
4. Build/test evidence exists for each status-update chunk.
|
||||
5. Batch 20 can be completed through PortTracker validation without override except justified blockers.
|
||||
@@ -0,0 +1,567 @@
|
||||
# Batch 20 Accounts Resolvers Implementation Plan
|
||||
|
||||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Port and verify Batch 20 (`Accounts Resolvers`) by implementing 38 resolver/account features from `server/accounts.go` and validating 98 mapped tests without introducing stubs.
|
||||
|
||||
**Architecture:** Implement in existing account/resolver files (`AccountResolver.cs`, `NatsServer.Accounts.cs`, `Account.cs`, `AccountTypes.cs`) in two feature groups (19 IDs each), then verify/port mapped tests in class-based waves. Status changes are evidence-driven and chunked to max 15 IDs per update.
|
||||
|
||||
**Tech Stack:** .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (`porting.db`)
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-batch-20-accounts-resolvers-design.md`
|
||||
|
||||
---
|
||||
|
||||
## Batch 20 Scope
|
||||
|
||||
- Batch ID: `20`
|
||||
- Name: `Accounts Resolvers`
|
||||
- Dependency: batch `19`
|
||||
- Go source: `golang/nats-server/server/accounts.go`
|
||||
- Features: `38`
|
||||
- Tests: `98`
|
||||
|
||||
Primary source files:
|
||||
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountResolver.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
||||
|
||||
Primary mapped test files:
|
||||
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsConsumerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamEngineTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JwtProcessorTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttExternalTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/GatewayHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamBatchingTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs`
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY VERIFICATION PROTOCOL
|
||||
|
||||
> **NON-NEGOTIABLE:** Every feature and test in Batch 20 must follow this protocol.
|
||||
|
||||
### Per-Feature Verification Loop (REQUIRED for every feature ID)
|
||||
|
||||
1. Read feature metadata and Go source before editing:
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature show <feature_id> --db porting.db
|
||||
sed -n '<start_line>,<end_line>p' golang/nats-server/server/accounts.go
|
||||
```
|
||||
2. Implement C# behavior in mapped file/class/method (no placeholders).
|
||||
3. Build immediately:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
4. Run smallest related test filter immediately (class-level minimum):
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~<RelatedClassName>"
|
||||
```
|
||||
5. Only after green build + related tests: add feature ID to group `complete` candidate list.
|
||||
6. If failing, fix before starting the next feature ID.
|
||||
|
||||
### Stub Detection Check (REQUIRED after every feature group and test class)
|
||||
|
||||
Run on **touched files** and fail the task if new stub hits are introduced:
|
||||
|
||||
```bash
|
||||
# Forbidden tokens and TODO markers
|
||||
rg -n "(NotImplementedException|TODO|PLACEHOLDER|throw new Exception\(\"TODO\"\))" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountResolver.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.Impltests.cs
|
||||
|
||||
# Empty method-body detector
|
||||
rg -n "^\s*(public|internal|private|protected)\s+[^=;]+\)\s*\{\s*\}$" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountResolver.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs
|
||||
```
|
||||
|
||||
If any new violations appear, remove/fix them or defer the blocked ID with reason. Do not continue.
|
||||
|
||||
### Build Gate (REQUIRED after each feature group)
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
|
||||
`Build succeeded` is required before any group IDs move to `complete` or `verified`.
|
||||
|
||||
### Test Gate (REQUIRED before setting any feature to `verified`)
|
||||
|
||||
All related mapped tests for that feature group must pass:
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JwtProcessorTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.ConfigReloaderTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.EventsHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsConsumerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JetStreamEngineTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.ConcurrencyTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.Mqtt"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.GatewayHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JetStreamBatchingTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JetStreamFileStoreTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsServerTests"
|
||||
```
|
||||
|
||||
No feature ID may be set to `verified` until mapped tests are passing or explicitly deferred with reason.
|
||||
|
||||
### Status Update Protocol (REQUIRED)
|
||||
|
||||
- Maximum `15` IDs per `feature batch-update` or `test batch-update` command.
|
||||
- Allowed status flow only: `deferred/not_started -> stub -> complete -> verified`.
|
||||
- Each status update chunk requires evidence captured in notes/log:
|
||||
- successful build summary
|
||||
- successful related test summary
|
||||
- clean stub-scan outcome for touched files
|
||||
- Never bulk-update across unrelated groups/classes in one command.
|
||||
|
||||
### Checkpoint Protocol Between Tasks (REQUIRED)
|
||||
|
||||
After every implementation/testing task before starting next task:
|
||||
|
||||
1. Full build:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
2. Full unit test run:
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
3. Commit checkpoint:
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog \
|
||||
porting.db
|
||||
git commit -m "<task-specific message>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)
|
||||
|
||||
### Forbidden Patterns
|
||||
|
||||
The following patterns are forbidden in any completed Batch 20 feature or test:
|
||||
|
||||
- `throw new NotImplementedException()`
|
||||
- Empty method bodies for mapped feature methods (`{ }`)
|
||||
- `// TODO` or `// PLACEHOLDER` inside newly implemented feature/test bodies
|
||||
- Placeholder pass assertions (`Assert.True(true)`, equivalent always-pass checks)
|
||||
- Fake behavior returns (`return null;`, `return string.Empty;`, `return 0;`, `return false;`) where Go behavior is non-trivial
|
||||
- Tests with no real Arrange/Act/Assert against production code
|
||||
|
||||
### Hard Limits
|
||||
|
||||
- Max `~20` features per implementation group (this plan uses 19 + 19).
|
||||
- Max `15` IDs per any status-update command.
|
||||
- Max one feature group in active status transition at a time.
|
||||
- No feature may reach `verified` while its mapped tests are still stubbed/unverified without explicit deferred reason.
|
||||
- Mandatory checkpoint commit after every task.
|
||||
|
||||
### If You Get Stuck (REQUIRED BEHAVIOR)
|
||||
|
||||
1. Stop work on the blocked ID immediately.
|
||||
2. Remove any partial placeholder code for that ID.
|
||||
3. Keep or set status to `deferred` with explicit reason:
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status deferred --override "blocked: <specific reason>" --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test update <id> --status deferred --override "blocked: <specific reason>" --db porting.db
|
||||
```
|
||||
4. Continue with the next unblocked ID.
|
||||
5. Do not create stubs to preserve momentum.
|
||||
|
||||
---
|
||||
|
||||
## Feature Groups (Max ~20)
|
||||
|
||||
### Group 1 (19 Features)
|
||||
|
||||
`150,183,197,208,209,215,250,251,252,253,258,259,260,261,306,307,310,316,318`
|
||||
|
||||
### Group 2 (19 Features)
|
||||
|
||||
`319,320,326,327,328,330,331,334,335,336,337,338,339,341,343,345,346,347,349`
|
||||
|
||||
---
|
||||
|
||||
## Test Waves (98 Total)
|
||||
|
||||
### Wave 1 (18 tests)
|
||||
|
||||
- Account: `86,87,105,108`
|
||||
- JWT: `1819,1821,1823,1825,1830,1831,1841,1849,1894`
|
||||
- Events: `307,346,347`
|
||||
- Monitoring: `2125,2141`
|
||||
|
||||
### Wave 2 (40 tests)
|
||||
|
||||
- Config reload: `2721,2722,2724,2725,2726,2727,2728,2729,2730,2731,2732,2733,2734,2735,2736,2737,2738,2739,2741,2742,2743,2744,2745,2746,2750,2752,2753,2754,2761,2767,2768,2769,2770,2771,2773,2775,2776,2779,2781,2793`
|
||||
|
||||
### Wave 3 (40 tests)
|
||||
|
||||
- NatsConsumer: `1238,1254,1296,1300,1305,1307,1322,1324,1329,1331,1351,1354,1360,1375,1377,1378`
|
||||
- JetStreamEngine: `1566,1578,1579,1679,1680,1698,1705,1706,1712,1729,1730,1738`
|
||||
- Concurrency: `2379,2386,2444,2445,2500`
|
||||
- MQTT/Gateway/Other: `2169,2184,2262,683,723,493,2893`
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Preflight and Batch Start
|
||||
|
||||
**Files:**
|
||||
- Read: `docs/standards/dotnet-standards.md`
|
||||
- Read: `golang/nats-server/server/accounts.go`
|
||||
- Read: `docs/plans/2026-02-27-batch-20-accounts-resolvers-design.md`
|
||||
|
||||
**Step 1: Confirm dependency and scope**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 20 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
|
||||
```
|
||||
|
||||
Expected: Batch 20 depends on Batch 19 and remains pending or ready.
|
||||
|
||||
**Step 2: Start the batch**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch start 20 --db porting.db
|
||||
```
|
||||
|
||||
Expected: batch status becomes `in_progress`.
|
||||
|
||||
**Step 3: Baseline verification**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
|
||||
Expected: baseline output captured before edits.
|
||||
|
||||
**Step 4: Commit checkpoint**
|
||||
|
||||
```bash
|
||||
git add porting.db
|
||||
git commit -m "chore(batch20): start accounts resolvers batch"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Implement Feature Group 1 (19 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs`
|
||||
|
||||
**Step 1: Move Group 1 to `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "150,183,197,208,209,215,250,251,252,253,258,259,260,261,306" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "307,310,316,318" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute per-feature verification loop for all 19 IDs**
|
||||
|
||||
For each ID: `feature show` -> read Go range -> implement -> build -> run related tests.
|
||||
|
||||
**Step 3: Group build + focused tests**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JwtProcessorTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.EventsHandlerTests"
|
||||
```
|
||||
|
||||
**Step 4: Run stub detection check**
|
||||
|
||||
Use the mandatory stub-scan commands.
|
||||
|
||||
**Step 5: Move Group 1 to `complete` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "150,183,197,208,209,215,250,251,252,253,258,259,260,261,306" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "307,310,316,318" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint protocol + commit**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs \
|
||||
porting.db
|
||||
git commit -m "feat(batch20): implement resolver/latency/account refresh group"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Implement Feature Group 2 (19 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountResolver.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
|
||||
**Step 1: Move Group 2 to `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "319,320,326,327,328,330,331,334,335,336,337,338,339,341,343" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "345,346,347,349" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute per-feature verification loop for all 19 IDs**
|
||||
|
||||
For each ID: `feature show` -> Go source -> implement -> build -> targeted tests.
|
||||
|
||||
**Step 3: Group build + focused tests**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.ConfigReloaderTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests"
|
||||
```
|
||||
|
||||
**Step 4: Run stub detection check**
|
||||
|
||||
Use the mandatory stub-scan commands.
|
||||
|
||||
**Step 5: Move Group 2 to `complete` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "319,320,326,327,328,330,331,334,335,336,337,338,339,341,343" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "345,346,347,349" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 6: Checkpoint protocol + commit**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountResolver.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs \
|
||||
porting.db
|
||||
git commit -m "feat(batch20): implement resolver backends and operator helper paths"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Port and Verify Test Wave 1 (18 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JwtProcessorTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
|
||||
**Step 1: Move Wave 1 IDs to `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "86,87,105,108,1819,1821,1823,1825,1830,1831,1841,1849,1894,307,346" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "347,2125,2141" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Per-test loop for each ID**
|
||||
|
||||
For each test ID: `test show` -> read Go test range -> port behavior -> run single test -> verify `Passed: 1`.
|
||||
|
||||
**Step 3: Class-level gates**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JwtProcessorTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.EventsHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests"
|
||||
```
|
||||
|
||||
**Step 4: Stub scan + move Wave 1 to `verified`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "86,87,105,108,1819,1821,1823,1825,1830,1831,1841,1849,1894,307,346" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "347,2125,2141" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Checkpoint protocol + commit**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "test(batch20): verify account jwt events monitoring mapped tests"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Port and Verify Test Wave 2 (Config Reload, 40 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs`
|
||||
|
||||
**Step 1: Move Wave 2 IDs to `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "2721,2722,2724,2725,2726,2727,2728,2729,2730,2731,2732,2733,2734,2735,2736" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "2737,2738,2739,2741,2742,2743,2744,2745,2746,2750,2752,2753,2754,2761,2767" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "2768,2769,2770,2771,2773,2775,2776,2779,2781,2793" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Port in sub-batches of ~10 tests**
|
||||
|
||||
For each sub-batch: port tests -> run single-test checks -> run full class filter.
|
||||
|
||||
**Step 3: Class gate**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.ConfigReloaderTests"
|
||||
```
|
||||
|
||||
Expected: all 40 mapped IDs passing.
|
||||
|
||||
**Step 4: Stub scan + move Wave 2 IDs to `verified` in same 3 chunks**
|
||||
|
||||
Run the same ID chunks with `--set-status verified`.
|
||||
|
||||
**Step 5: Checkpoint protocol + commit**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs porting.db
|
||||
git commit -m "test(batch20): verify config reload mapped tests"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Port and Verify Test Wave 3 (40 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsConsumerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamEngineTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttExternalTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/GatewayHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamBatchingTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs`
|
||||
|
||||
**Step 1: Move Wave 3 IDs to `stub` in max-15 chunks**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "1238,1254,1296,1300,1305,1307,1322,1324,1329,1331,1351,1354,1360,1375,1377" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "1378,1566,1578,1579,1679,1680,1698,1705,1706,1712,1729,1730,1738,2379,2386" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "2444,2445,2500,2169,2184,2262,683,723,493,2893" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Port and verify per class**
|
||||
|
||||
Run single-test loops and then class filters for each touched class.
|
||||
|
||||
**Step 3: Class gates**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsConsumerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JetStreamEngineTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.ConcurrencyTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.Mqtt"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.GatewayHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JetStreamBatchingTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.JetStreamFileStoreTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsServerTests"
|
||||
```
|
||||
|
||||
**Step 4: Stub scan + move Wave 3 IDs to `verified` in same 3 chunks**
|
||||
|
||||
Run the same ID chunks with `--set-status verified`.
|
||||
|
||||
**Step 5: Checkpoint protocol + commit**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "test(batch20): verify jetstream mqtt concurrency and misc mapped tests"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Final Feature Verification, Batch Completion, and Report
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Generate: `reports/current.md` (via report script)
|
||||
|
||||
**Step 1: Promote feature groups from `complete` to `verified` in max-15 chunks**
|
||||
|
||||
Group 1:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "150,183,197,208,209,215,250,251,252,253,258,259,260,261,306" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "307,310,316,318" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
Group 2:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "319,320,326,327,328,330,331,334,335,336,337,338,339,341,343" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "345,346,347,349" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Final full gates**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 20 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch complete 20 --db porting.db
|
||||
```
|
||||
|
||||
Expected: batch completion succeeds (or explicit list of blocked IDs).
|
||||
|
||||
**Step 3: Dependency/report update and commit**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- dependency ready --db porting.db
|
||||
./reports/generate-report.sh
|
||||
git add porting.db reports/
|
||||
git commit -m "chore(batch20): complete accounts resolvers batch"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Evidence Checklist (Use Before Every Status Update)
|
||||
|
||||
1. Feature/test IDs updated are listed explicitly (<=15 per command).
|
||||
2. Build output captured and green.
|
||||
3. Related test output captured and green.
|
||||
4. Stub scan re-run and no new violations in touched files.
|
||||
5. Any blocked IDs are deferred with explicit reason (no placeholders).
|
||||
114
docs/plans/2026-02-27-batch-21-events-msgtrace-design.md
Normal file
114
docs/plans/2026-02-27-batch-21-events-msgtrace-design.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Batch 21 Events + MsgTrace Design
|
||||
|
||||
**Date:** 2026-02-27
|
||||
**Batch:** 21 (`Events + MsgTrace`)
|
||||
**Scope:** Design only. No implementation in this document.
|
||||
|
||||
## Problem
|
||||
|
||||
Batch 21 contains high-fanout eventing and tracing behavior used by system account messaging, server stats, admin requests, and distributed message tracing.
|
||||
|
||||
Current tracker scope from `batch show 21`:
|
||||
- Features: `118` (all `deferred`)
|
||||
- Tests: `9` (all `deferred`)
|
||||
- Dependencies: batches `18`, `19`
|
||||
- Go sources: `server/events.go`, `server/msgtrace.go`
|
||||
|
||||
## Context Findings
|
||||
|
||||
- Existing .NET code already has many event and trace DTO/types in:
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Events/EventTypes.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/MessageTrace/MsgTraceTypes.cs`
|
||||
- Runtime behavior methods mapped in Batch 21 are largely missing from `NatsServer` and `ClientConnection`.
|
||||
- Existing backlog tests for Events/MsgTrace include placeholder-style assertions and must be replaced with behavior-valid tests for mapped Batch 21 IDs.
|
||||
- `test show` mapping confirms target class/methods for all 9 tests:
|
||||
- Events: 6 methods in `EventsHandlerTests`
|
||||
- MsgTrace: 2 methods in `MessageTracerTests`
|
||||
- Concurrency: 1 method in `ConcurrencyTests1`
|
||||
|
||||
## Assumptions
|
||||
|
||||
- Batch 21 work begins only after dependencies (batches 18 and 19) are complete enough to compile and run related tests.
|
||||
- We preserve existing project structure and naming patterns (`NatsServer.*.cs`, `ClientConnection.*.cs`, `ImplBacklog/*.Impltests.cs`).
|
||||
- No new integration infrastructure is introduced in this batch; infra-blocked items remain deferred with explicit reasons.
|
||||
|
||||
## Approaches
|
||||
|
||||
### Approach A: Monolithic implementation in existing large files
|
||||
|
||||
Implement all methods directly in `NatsServer.cs`, `ClientConnection.cs`, `ClientTypes.cs`, and `NatsServerTypes.cs`.
|
||||
|
||||
Trade-offs:
|
||||
- Pros: Minimal file creation.
|
||||
- Cons: Very high merge conflict risk, poor reviewability, difficult verification per feature group.
|
||||
|
||||
### Approach B (Recommended): Partial-file segmentation by runtime domain
|
||||
|
||||
Add focused partial/runtime files for events and msgtrace behavior while leaving DTO/type files intact.
|
||||
|
||||
Trade-offs:
|
||||
- Pros: Enables clear feature-group boundaries, easier per-group build/test loops, lower risk of accidental regressions.
|
||||
- Cons: Requires a few new files and up-front structure decisions.
|
||||
|
||||
### Approach C: Test-only first, then backfill features
|
||||
|
||||
Start by rewriting the 9 tests to force implementation behavior.
|
||||
|
||||
Trade-offs:
|
||||
- Pros: Fast feedback for mapped tests.
|
||||
- Cons: Batch has 118 features and only 9 mapped tests; test-first alone leaves large behavior surface unvalidated.
|
||||
|
||||
## Recommended Design
|
||||
|
||||
Use **Approach B**.
|
||||
|
||||
### Code organization
|
||||
|
||||
Implement runtime behavior in small, targeted files:
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.cs` (core eventing/send loops)
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.System.cs` (system subscriptions/requests)
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.Admin.cs` (reload/kick/ldm/debug/OCSP event paths)
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.MsgTrace.cs` (client-side trace enable/init helpers)
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/MessageTrace/MsgTraceRuntime.cs` (runtime trace mutation/send behavior)
|
||||
- plus targeted edits in:
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServerTypes.cs` (ServerInfo capability helpers)
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs` (ClientInfo helper projections)
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs` (`Account.statz`)
|
||||
|
||||
### Behavior domains
|
||||
|
||||
- Domain 1: Capability and metadata helpers (`ServerInfo`, `ClientInfo`, hashing helpers).
|
||||
- Domain 2: Internal system message send/receive loops and event state lifecycle.
|
||||
- Domain 3: Remote server/account tracking and statsz/advisory publication.
|
||||
- Domain 4: System subscription wiring and request handlers (connsz/statsz/idz/nsubs/reload/kick/ldm).
|
||||
- Domain 5: OCSP advisory events and misc utility wrappers.
|
||||
- Domain 6: Message trace runtime (trace enablement, header extraction, event aggregation, publish path).
|
||||
|
||||
### Test design
|
||||
|
||||
Replace mapped placeholder tests with behavior checks that assert:
|
||||
- System subscription registration and unsubscribe behavior.
|
||||
- Connection update timer/sweep behavior under local/remote account changes.
|
||||
- Remote latency update validation and bad payload handling.
|
||||
- MsgTrace connection-name normalization and trace-header parsing correctness.
|
||||
- No-race JetStream compact scenario behavior for mapped test ID 2412.
|
||||
|
||||
### Execution model
|
||||
|
||||
Port features in 6 groups (<=20 IDs each), then tests in 2 waves, with strict per-feature verification and anti-stub gates.
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
- Risk: Placeholder tests can pass while behavior is wrong.
|
||||
- Mitigation: Mandatory anti-stub checks and per-test evidence before status updates.
|
||||
- Risk: Large eventing surface can regress unrelated server behavior.
|
||||
- Mitigation: Build gate after each feature group + full unit-test checkpoint between tasks.
|
||||
- Risk: Some tests require runtime topology not available in unit test harness.
|
||||
- Mitigation: keep deferred with explicit blocker reason; do not stub.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- All 118 Batch 21 feature IDs moved through `stub -> complete -> verified` only with build + test evidence.
|
||||
- All 9 Batch 21 test IDs either `verified` with real assertions or `deferred` with explicit blocker reason.
|
||||
- No new stubs (`NotImplementedException`, empty bodies, TODO placeholders) in touched feature/test files.
|
||||
- Batch 21 can be completed with `batch complete 21` once all IDs satisfy status requirements.
|
||||
@@ -0,0 +1,573 @@
|
||||
# Batch 21 Events + MsgTrace Implementation Plan
|
||||
|
||||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Implement and verify Batch 21 (`Events + MsgTrace`) by porting 118 deferred features from `server/events.go` and `server/msgtrace.go`, and by replacing 9 mapped deferred tests with real behavior-valid tests.
|
||||
|
||||
**Architecture:** Implement runtime behavior in focused partial/runtime files (`NatsServer.Events*.cs`, `ClientConnection.MsgTrace.cs`, `MsgTraceRuntime.cs`) while reusing existing DTO/type models in `EventTypes.cs` and `MsgTraceTypes.cs`. Execute in six feature groups (max 20 IDs each), keep IDs in `stub -> complete` during implementation, then move to `verified` only after full related test gate passes. Treat infra-blocked tests/features as explicitly deferred rather than stubbing.
|
||||
|
||||
**Tech Stack:** .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (`porting.db`)
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-batch-21-events-msgtrace-design.md`
|
||||
|
||||
---
|
||||
|
||||
## Batch 21 Scope
|
||||
|
||||
- Batch ID: `21`
|
||||
- Name: `Events + MsgTrace`
|
||||
- Dependencies: batches `18`, `19`
|
||||
- Go source files:
|
||||
- `golang/nats-server/server/events.go`
|
||||
- `golang/nats-server/server/msgtrace.go`
|
||||
- Features: `118`
|
||||
- Tests: `9`
|
||||
|
||||
Primary source files to modify/create:
|
||||
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServerTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.System.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.Admin.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.MsgTrace.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/MessageTrace/MsgTraceRuntime.cs`
|
||||
|
||||
Primary mapped test files:
|
||||
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MessageTracerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY VERIFICATION PROTOCOL
|
||||
|
||||
> **NON-NEGOTIABLE:** Every Batch 21 feature and mapped test must follow this protocol.
|
||||
|
||||
### Per-Feature Verification Loop (REQUIRED for every feature ID)
|
||||
|
||||
1. Read feature metadata and Go behavior before coding:
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature show <feature_id> --db porting.db
|
||||
```
|
||||
2. Read the corresponding Go method body in `events.go` or `msgtrace.go`.
|
||||
3. Implement only the mapped behavior in the target C# file (no placeholder code).
|
||||
4. Build immediately:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
5. Run the smallest related tests immediately:
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~EventsHandlerTests|FullyQualifiedName~MessageTracerTests|FullyQualifiedName~ConcurrencyTests1|FullyQualifiedName~ServerTests|FullyQualifiedName~AccountTests|FullyQualifiedName~ClientConnectionStubFeaturesTests"
|
||||
```
|
||||
6. Only after green build + related tests: keep the feature ID in the current `complete-candidate` set.
|
||||
7. If red: fix before moving to the next feature ID.
|
||||
|
||||
### Stub Detection Check (REQUIRED after every feature group and test wave)
|
||||
|
||||
Run on touched files before any status promotion:
|
||||
|
||||
```bash
|
||||
# Forbidden placeholder/stub markers
|
||||
grep -R -n -E "(NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)|throw new Exception\(\"TODO\"\))" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events*.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.MsgTrace.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/MessageTrace/MsgTraceRuntime.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServerTypes.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MessageTracerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs
|
||||
|
||||
# Empty body detector in touched source files
|
||||
grep -R -n -E "^[[:space:]]*(public|internal|private|protected)[^{;=]*\)[[:space:]]*\{[[:space:]]*\}$" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events*.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.MsgTrace.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/MessageTrace/MsgTraceRuntime.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServerTypes.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs
|
||||
```
|
||||
|
||||
Any new hit must be fixed or explicitly deferred. No exceptions.
|
||||
|
||||
### Build Gate (REQUIRED after each feature group)
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
|
||||
`Build succeeded` is required before any feature group IDs move to `complete`.
|
||||
|
||||
### Test Gate (REQUIRED before setting any Batch 21 feature to `verified`)
|
||||
|
||||
All related tests must pass first:
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.EventsHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.MessageTracerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.ConcurrencyTests1"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ServerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Accounts.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ClientConnectionStubFeaturesTests"
|
||||
```
|
||||
|
||||
No Batch 21 feature ID can be `verified` while mapped tests are failing, undiscovered, or still placeholder-based.
|
||||
|
||||
### Status Update Protocol (REQUIRED)
|
||||
|
||||
- Maximum `15` IDs per `feature batch-update` or `test batch-update` command.
|
||||
- Required state progression:
|
||||
- `deferred/not_started -> stub` when active work starts.
|
||||
- `stub -> complete` only after feature-group build gate + stub scan.
|
||||
- `complete -> verified` only after full test gate.
|
||||
- Evidence required before each status-update chunk:
|
||||
- latest successful `dotnet build` summary,
|
||||
- latest successful related test summary,
|
||||
- clean stub scan for touched files,
|
||||
- explicit list of IDs in that chunk.
|
||||
|
||||
### Checkpoint Protocol Between Tasks (REQUIRED)
|
||||
|
||||
Between every major task (feature group or test wave):
|
||||
|
||||
1. Full build:
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
2. Full unit tests:
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
3. Commit checkpoint:
|
||||
```bash
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "<task-specific message>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)
|
||||
|
||||
### Forbidden Patterns
|
||||
|
||||
- `throw new NotImplementedException()` in Batch 21 mapped methods.
|
||||
- Empty method bodies for mapped features.
|
||||
- `// TODO`, `// PLACEHOLDER`, or fake temporary logic in mapped behavior.
|
||||
- Placeholder pass tests (`Assert.True(true)`, string/self assertions not tied to behavior).
|
||||
- Default-return stubs (`return null`, `return 0`, `return false`, `return string.Empty`) where Go behavior is non-trivial.
|
||||
- Tests that do not call production Batch 21 code paths.
|
||||
|
||||
### Hard Limits
|
||||
|
||||
- Maximum `~20` features per group task.
|
||||
- Maximum `15` IDs per status-update command.
|
||||
- Only one feature group in active status transition at a time.
|
||||
- No feature promoted to `verified` before the mapped test gate is green.
|
||||
- Mandatory checkpoint (full build + full tests + commit) between tasks.
|
||||
|
||||
### If You Get Stuck (REQUIRED)
|
||||
|
||||
1. Stop working on the blocked ID immediately.
|
||||
2. Remove partial placeholder logic for that ID.
|
||||
3. Keep or set the blocked item to `deferred` with explicit reason:
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status deferred --override "blocked: <specific reason>" --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test update <id> --status deferred --override "blocked: <specific reason>" --db porting.db
|
||||
```
|
||||
4. Continue with next unblocked ID.
|
||||
5. Never introduce stubs to maintain pace.
|
||||
|
||||
---
|
||||
|
||||
## Feature Groups (Max ~20 IDs)
|
||||
|
||||
### Group 1 (20 IDs): Capability helpers + internal message loop foundations
|
||||
|
||||
`854,855,856,857,858,859,860,861,862,863,864,865,866,868,869,870,871,872,873,874`
|
||||
|
||||
### Group 2 (20 IDs): Event-state lifecycle + statsz/timer/hash/node initialization
|
||||
|
||||
`875,876,877,878,879,880,881,882,883,884,885,886,887,888,889,890,891,892,893,894`
|
||||
|
||||
### Group 3 (20 IDs): System import wiring + remote server/account update paths
|
||||
|
||||
`895,897,898,899,900,901,902,903,904,905,907,908,909,910,911,912,913,914,917,918`
|
||||
|
||||
### Group 4 (20 IDs): Account connection advisories + sys-subscribe and latency/reply flows
|
||||
|
||||
`919,920,921,923,925,926,927,928,929,930,931,932,933,934,935,936,937,938,939,940`
|
||||
|
||||
### Group 5 (20 IDs): Admin/debug/OCSP event paths + MsgTrace type/converter bridge
|
||||
|
||||
`941,942,943,944,945,946,947,948,949,950,2406,2407,2408,2409,2410,2411,2412,2413,2420,2421`
|
||||
|
||||
### Group 6 (18 IDs): MsgTrace runtime behaviors (conn names, headers, sampling, event emission)
|
||||
|
||||
`2422,2423,2424,2425,2426,2427,2428,2429,2430,2431,2432,2433,2434,2435,2436,2437,2438,2439`
|
||||
|
||||
---
|
||||
|
||||
## Test Waves (9 IDs)
|
||||
|
||||
### Wave 1 (6 IDs): events_test.go mapped behaviors in `EventsHandlerTests`
|
||||
|
||||
`303,304,305,319,334,343`
|
||||
|
||||
Target methods to add/replace:
|
||||
- `SysSubscribeRace_ShouldSucceed`
|
||||
- `SystemAccountInternalSubscriptions_ShouldSucceed`
|
||||
- `SystemAccountConnectionUpdatesStopAfterNoLocal_ShouldSucceed`
|
||||
- `SystemAccountWithBadRemoteLatencyUpdate_ShouldSucceed`
|
||||
- `ConnectionUpdatesTimerProperlySet_ShouldSucceed`
|
||||
- `ClusterSetupMsgs_ShouldSucceed`
|
||||
|
||||
### Wave 2 (3 IDs): msgtrace/norace mapped behaviors
|
||||
|
||||
`2329,2330,2412`
|
||||
|
||||
Target methods to add/replace:
|
||||
- `MsgTraceConnName_ShouldSucceed`
|
||||
- `MsgTraceGenHeaderMap_ShouldSucceed`
|
||||
- `NoRaceJetStreamLastSubjSeqAndFilestoreCompact_ShouldSucceed`
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Preflight, Dependency Validation, Batch Start
|
||||
|
||||
**Files:**
|
||||
- Read: `docs/standards/dotnet-standards.md`
|
||||
- Read: `docs/plans/2026-02-27-batch-21-events-msgtrace-design.md`
|
||||
- Read: `golang/nats-server/server/events.go`
|
||||
- Read: `golang/nats-server/server/msgtrace.go`
|
||||
|
||||
**Step 1: Validate batch status and dependency readiness**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 21 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
|
||||
```
|
||||
|
||||
**Step 2: Start batch when dependencies are satisfied**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch start 21 --db porting.db
|
||||
```
|
||||
|
||||
**Step 3: Capture baseline build/tests**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
|
||||
**Step 4: Commit checkpoint**
|
||||
|
||||
```bash
|
||||
git add porting.db
|
||||
git commit -m "chore(batch21): start events-msgtrace batch"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Implement Feature Group 1 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServerTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub` (max 15 per command)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "854,855,856,857,858,859,860,861,862,863,864,865,866,868,869" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "870,871,872,873,874" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 20 IDs**
|
||||
|
||||
**Step 3: Run required stub scan + build gate**
|
||||
|
||||
**Step 4: Move IDs to `complete` (max 15 per command)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "854,855,856,857,858,859,860,861,862,863,864,865,866,868,869" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "870,871,872,873,874" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Implement Feature Group 2 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.System.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "875,876,877,878,879,880,881,882,883,884,885,886,887,888,889" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "890,891,892,893,894" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 20 IDs**
|
||||
|
||||
**Step 3: Run required stub scan + build gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "875,876,877,878,879,880,881,882,883,884,885,886,887,888,889" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "890,891,892,893,894" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Implement Feature Group 3 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.System.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "895,897,898,899,900,901,902,903,904,905,907,908,909,910,911" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "912,913,914,917,918" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 20 IDs**
|
||||
|
||||
**Step 3: Run required stub scan + build gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "895,897,898,899,900,901,902,903,904,905,907,908,909,910,911" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "912,913,914,917,918" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Implement Feature Group 4 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.System.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "919,920,921,923,925,926,927,928,929,930,931,932,933,934,935" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "936,937,938,939,940" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 20 IDs**
|
||||
|
||||
**Step 3: Run required stub scan + build gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "919,920,921,923,925,926,927,928,929,930,931,932,933,934,935" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "936,937,938,939,940" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Implement Feature Group 5 (20 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Events.Admin.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/MessageTrace/MsgTraceTypes.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/MessageTrace/MsgTraceRuntime.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "941,942,943,944,945,946,947,948,949,950,2406,2407,2408,2409,2410" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2411,2412,2413,2420,2421" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 20 IDs**
|
||||
|
||||
**Step 3: Run required stub scan + build gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "941,942,943,944,945,946,947,948,949,950,2406,2407,2408,2409,2410" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2411,2412,2413,2420,2421" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Implement Feature Group 6 (18 IDs)
|
||||
|
||||
**Files:**
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.MsgTrace.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/MessageTrace/MsgTraceRuntime.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2422,2423,2424,2425,2426,2427,2428,2429,2430,2431,2432,2433,2434,2435,2436" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2437,2438,2439" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 18 IDs**
|
||||
|
||||
**Step 3: Run required stub scan + build gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2422,2423,2424,2425,2426,2427,2428,2429,2430,2431,2432,2433,2434,2435,2436" --set-status complete --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2437,2438,2439" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 8: Port/Verify Test Wave 1 (Events, 6 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs`
|
||||
|
||||
**Step 1: Move Wave 1 tests to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "303,304,305,319,334,343" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Per-test loop for each ID**
|
||||
|
||||
For each test ID:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test show <test_id> --db porting.db
|
||||
# Read corresponding Go test block in golang/nats-server/server/events_test.go
|
||||
```
|
||||
|
||||
Implement real Arrange/Act/Assert logic against Batch 21 production paths.
|
||||
|
||||
**Step 3: Run class-level test gate**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.EventsHandlerTests"
|
||||
```
|
||||
|
||||
**Step 4: Run stub scan on touched tests + set `verified` for passing IDs**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "303,304,305,319,334,343" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
If any test is blocked, keep deferred with explicit reason and only verify proven IDs.
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 9: Port/Verify Test Wave 2 (MsgTrace + NoRace, 3 IDs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MessageTracerTests.Impltests.cs`
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
|
||||
|
||||
**Step 1: Move Wave 2 tests to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "2329,2330,2412" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Per-test loop for each ID**
|
||||
|
||||
Use `test show <id>` and corresponding Go tests:
|
||||
- `golang/nats-server/server/msgtrace_test.go`
|
||||
- `golang/nats-server/server/norace_1_test.go`
|
||||
|
||||
**Step 3: Run class-level test gates**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.MessageTracerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.ConcurrencyTests1"
|
||||
```
|
||||
|
||||
**Step 4: Promote passing tests to `verified`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "2329,2330,2412" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
If blocked, defer with explicit reason.
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 10: Final Feature Verification, Batch Closure, and Reporting
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Optional update: `reports/current.md` (via report generation script)
|
||||
|
||||
**Step 1: Execute full Batch 21 test gate**
|
||||
|
||||
Run all commands from the mandatory Test Gate section.
|
||||
|
||||
**Step 2: Promote complete feature IDs to `verified` in max-15 chunks**
|
||||
|
||||
Use the same per-group chunking used for `stub`/`complete` transitions, but with `--set-status verified`.
|
||||
|
||||
Example (Group 1):
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "854,855,856,857,858,859,860,861,862,863,864,865,866,868,869" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "870,871,872,873,874" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
Repeat for Groups 2-6.
|
||||
|
||||
**Step 3: Confirm all Batch 21 items are in terminal statuses**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 21 --db porting.db
|
||||
```
|
||||
|
||||
**Step 4: Complete the batch**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch complete 21 --db porting.db
|
||||
```
|
||||
|
||||
**Step 5: Generate updated report and final checkpoint commit**
|
||||
|
||||
```bash
|
||||
./reports/generate-report.sh
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db reports/current.md
|
||||
git commit -m "feat(batch21): implement and verify events and msgtrace"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- If `dotnet` is not on PATH, use `/usr/local/share/dotnet/dotnet` for all commands.
|
||||
- Do not edit unrelated backlog tests while executing this plan.
|
||||
- Do not mark `verified` without captured evidence for build, tests, and stub scan.
|
||||
147
docs/plans/2026-02-27-batch-22-monitoring-design.md
Normal file
147
docs/plans/2026-02-27-batch-22-monitoring-design.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Batch 22 Monitoring Design
|
||||
|
||||
**Date:** 2026-02-27
|
||||
**Batch:** 22 (`Monitoring`)
|
||||
**Scope:** Design only. No implementation in this document.
|
||||
|
||||
## Problem
|
||||
|
||||
Batch 22 ports NATS server monitoring behavior from `server/monitor.go` into .NET. The batch is large and mixed:
|
||||
|
||||
- Features: `70` (all currently `deferred`)
|
||||
- Tests: `29` (all currently `deferred`)
|
||||
- Dependencies: batches `18`, `19`
|
||||
- Go source: `golang/nats-server/server/monitor.go`
|
||||
|
||||
This batch includes both core data endpoints (`/connz`, `/routez`, `/subsz`, `/varz`) and broader operational surfaces (`/gatewayz`, `/leafz`, `/accountz`, `/jsz`, `/healthz`, `/raftz`, `/debug/vars`, profiling).
|
||||
|
||||
## Context Findings
|
||||
|
||||
From tracker and codebase inspection:
|
||||
|
||||
- Batch metadata confirmed with:
|
||||
- `dotnet run --project tools/NatsNet.PortTracker -- batch show 22 --db porting.db`
|
||||
- `dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db`
|
||||
- `dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db`
|
||||
- .NET currently has monitoring constants and partial DTOs (`MonitorTypes.cs`, `MonitorSortOptions.cs`, monitor paths in `NatsServer.Listeners.cs`), but most mapped runtime methods are not yet implemented.
|
||||
- Existing mapped test files are mostly placeholder-style in `ImplBacklog` and need behavioral rewrites for the 29 mapped test IDs.
|
||||
- Batch 22 tests span multiple classes (`MonitoringHandlerTests`, `RouteHandlerTests`, `LeafNodeHandlerTests`, `AccountTests`, `EventsHandlerTests`, `JetStreamJwtTests`, `ConfigReloaderTests`), so verification cannot be isolated to one test class.
|
||||
|
||||
## Constraints and Success Criteria
|
||||
|
||||
- Must preserve Go behavior semantics while writing idiomatic .NET 10 C#.
|
||||
- Must follow project standards (`xUnit 3`, `Shouldly`, `NSubstitute`; no FluentAssertions/Moq).
|
||||
- Must avoid stubs and fake-pass tests.
|
||||
- Feature status can move to `verified` only after related test gate is green.
|
||||
- Group work in chunks no larger than ~20 features.
|
||||
|
||||
Success looks like:
|
||||
|
||||
- 70 features implemented and verified (or explicitly deferred with reason where truly blocked).
|
||||
- 29 mapped tests verified with real Arrange/Act/Assert behavior, not placeholders.
|
||||
- Batch can be closed with `batch complete 22` once statuses satisfy PortTracker rules.
|
||||
|
||||
## Approaches
|
||||
|
||||
### Approach A: Single-file monitoring implementation
|
||||
|
||||
Implement all monitoring behavior in one or two large files (for example, `NatsServer.Monitoring.cs` + one test file wave).
|
||||
|
||||
Trade-offs:
|
||||
|
||||
- Pros: fewer new files.
|
||||
- Cons: poor reviewability, high merge risk, difficult to verify incrementally, very high chance of hidden stubs in large diff.
|
||||
|
||||
### Approach B (Recommended): Domain-segmented partials and DTO blocks
|
||||
|
||||
Split monitoring into focused runtime domains with dedicated partial files and matching test waves.
|
||||
|
||||
Trade-offs:
|
||||
|
||||
- Pros: matches the natural endpoint domains in `monitor.go`, enables strong per-group build/test gating, easier status evidence collection.
|
||||
- Cons: adds several files, requires deliberate file map upfront.
|
||||
|
||||
### Approach C: Test-first across all 29 tests before feature work
|
||||
|
||||
Rewrite all 29 tests first, then implement features until all pass.
|
||||
|
||||
Trade-offs:
|
||||
|
||||
- Pros: very fast signal on regressions.
|
||||
- Cons: test set under-represents some large feature surfaces (`healthz`, `raftz`, gateway/account internals), so feature quality still needs per-feature validation loops.
|
||||
|
||||
## Recommended Design
|
||||
|
||||
Use **Approach B**.
|
||||
|
||||
### Architecture
|
||||
|
||||
Implement monitoring in six domain slices, each with a bounded feature group:
|
||||
|
||||
1. Connz core + query decoders + connz handler
|
||||
2. Routez/Subsz/Stacksz/IPQueuesz
|
||||
3. Varz/root/runtime/config helpers
|
||||
4. Gatewayz + Leafz + AccountStatz + response helpers + closed-state rendering
|
||||
5. Accountz + JSz account/detail + Jsz endpoint
|
||||
6. Healthz + expvarz/profilez + raftz
|
||||
|
||||
Each slice follows the same loop: port features -> build -> run related tests -> stub scan -> status updates.
|
||||
|
||||
### Proposed File Map
|
||||
|
||||
Primary production files to create/modify:
|
||||
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.Connz.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.RouteSub.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.Varz.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.GatewayLeaf.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.AccountJsz.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.HealthRaft.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorSortOptions.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs` (for `ClosedState.String` parity)
|
||||
- Modify (if needed for DTO placement):
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Routes/RouteTypes.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/Gateway/GatewayTypes.cs`
|
||||
- `dotnet/src/ZB.MOM.NatsNet.Server/LeafNode/LeafNodeTypes.cs`
|
||||
|
||||
Primary mapped test files:
|
||||
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamJwtTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs`
|
||||
|
||||
### Data Flow
|
||||
|
||||
- HTTP monitor request -> query decode/validation -> domain endpoint function (`Connz`, `Routez`, `Varz`, etc.) -> DTO response projection -> unified response writer.
|
||||
- Endpoint functions read server/account/client state under required locks and project immutable response objects.
|
||||
- Sort and pagination apply after candidate gathering, matching Go behavior by endpoint.
|
||||
|
||||
### Error Handling Strategy
|
||||
|
||||
- Invalid query params return bad request through shared response helper.
|
||||
- Unsupported combinations (for example sort options not valid for state) return explicit errors.
|
||||
- Infra-unavailable behavior in tests remains deferred with explicit reason instead of placeholder implementations.
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
- Rewrite only the mapped 29 test IDs as behavior-valid tests, class by class.
|
||||
- Each feature group uses targeted test filters tied to that domain.
|
||||
- Keep full unit test checkpoint between tasks to catch regressions outside monitor-specific tests.
|
||||
|
||||
### Risks and Mitigations
|
||||
|
||||
- Risk: fake tests pass while behavior is unimplemented.
|
||||
- Mitigation: explicit anti-stub scans for placeholder signatures and literal-only assertions.
|
||||
- Risk: large healthz/raftz surfaces with sparse mapped tests.
|
||||
- Mitigation: per-feature read/port/build loop plus grouped sanity tests and status evidence requirements.
|
||||
- Risk: lock-sensitive endpoint logic causes race regressions.
|
||||
- Mitigation: keep route/leaf/account race tests in the required per-group gate.
|
||||
|
||||
## Design Approval Basis
|
||||
|
||||
This design is based on the explicit user-provided constraints (planning-only, mandatory guardrails, group size limits, and required tracker commands) and is ready for implementation planning with `writeplan`.
|
||||
632
docs/plans/2026-02-27-batch-22-monitoring-implementation-plan.md
Normal file
632
docs/plans/2026-02-27-batch-22-monitoring-implementation-plan.md
Normal file
@@ -0,0 +1,632 @@
|
||||
# Batch 22 Monitoring Implementation Plan
|
||||
|
||||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Port and verify Batch 22 (`Monitoring`) by implementing 70 deferred monitoring features from `server/monitor.go` and replacing/validating 29 mapped deferred tests with real behavioral assertions.
|
||||
|
||||
**Architecture:** Implement monitoring runtime in domain-focused `NatsServer` partial files (`Connz`, `Route/Sub`, `Varz`, `Gateway/Leaf`, `Account/JSz`, `Health/Raft`) and keep monitor DTO/sort/query helpers in `Monitor/*`. Execute in six feature groups (each <=20 IDs), then run mapped test waves and only promote `complete -> verified` once all related tests pass.
|
||||
|
||||
**Tech Stack:** .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (`porting.db`)
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-batch-22-monitoring-design.md`
|
||||
|
||||
---
|
||||
|
||||
## Batch 22 Scope
|
||||
|
||||
- Batch ID: `22`
|
||||
- Name: `Monitoring`
|
||||
- Dependencies: `18`, `19`
|
||||
- Go source: `golang/nats-server/server/monitor.go`
|
||||
- Features: `70`
|
||||
- Tests: `29`
|
||||
|
||||
Reference commands (run before starting work):
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 22 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
|
||||
```
|
||||
|
||||
Primary production files:
|
||||
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.Connz.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.RouteSub.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.Varz.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.GatewayLeaf.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.AccountJsz.cs`
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.HealthRaft.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorSortOptions.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs`
|
||||
|
||||
Primary mapped test files:
|
||||
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamJwtTests.Impltests.cs`
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs`
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY VERIFICATION PROTOCOL
|
||||
|
||||
> **NON-NEGOTIABLE:** Every Batch 22 feature and mapped test must follow this protocol.
|
||||
|
||||
### Per-Feature Verification Loop (REQUIRED for every feature ID)
|
||||
|
||||
1. Read feature metadata and Go implementation first:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature show <feature_id> --db porting.db
|
||||
# then inspect monitor.go around go_line_number/go_line_count
|
||||
```
|
||||
|
||||
2. Write the mapped C# behavior in the target file only (no placeholders).
|
||||
3. Build immediately after each feature (or tight pair of coupled features):
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
|
||||
4. Run the smallest related test filter immediately:
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
|
||||
--filter "FullyQualifiedName~MonitoringHandlerTests|FullyQualifiedName~RouteHandlerTests|FullyQualifiedName~LeafNodeHandlerTests|FullyQualifiedName~AccountTests|FullyQualifiedName~EventsHandlerTests|FullyQualifiedName~JetStreamJwtTests|FullyQualifiedName~ConfigReloaderTests"
|
||||
```
|
||||
|
||||
5. Keep feature ID in `complete-candidate` only if build and related tests are green.
|
||||
6. If red, fix before moving on. Do not stack unresolved failures.
|
||||
|
||||
### Stub Detection Check (REQUIRED after every feature group and test wave)
|
||||
|
||||
Run these checks before any status promotion:
|
||||
|
||||
```bash
|
||||
# Feature/test placeholder detector
|
||||
grep -R -n -E "(NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)|throw new Exception\(\"TODO\"\))" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring*.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Monitor/*.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamJwtTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs
|
||||
|
||||
# Empty-body detector (features)
|
||||
grep -R -n -E "^[[:space:]]*(public|internal|private|protected)[^{;=]*\)[[:space:]]*\{[[:space:]]*\}$" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring*.cs \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/Monitor/*.cs
|
||||
|
||||
# Fake-test detector for known placeholder pattern in ImplBacklog files
|
||||
grep -R -n -E "var goFile = \"server/|ShouldContain\(\"Should\"\)|ShouldNotBeNullOrWhiteSpace\(\);[[:space:]]*$" \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AccountTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/EventsHandlerTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamJwtTests.Impltests.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs
|
||||
```
|
||||
|
||||
Any new hit must be fixed or deferred with explicit reason.
|
||||
|
||||
### Build Gate (REQUIRED after each feature group)
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
```
|
||||
|
||||
`Build succeeded` is mandatory before moving any feature IDs in that group to `complete`.
|
||||
|
||||
### Test Gate (REQUIRED before marking any features verified)
|
||||
|
||||
All related test classes must pass before any Batch 22 feature moves `complete -> verified`:
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.MonitoringHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.RouteHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.LeafNodeHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.EventsHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.JetStreamJwtTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.ConfigReloaderTests"
|
||||
```
|
||||
|
||||
No feature may be `verified` while these related tests fail or remain placeholder-style.
|
||||
|
||||
### Status Update Protocol (REQUIRED)
|
||||
|
||||
- Max `15` IDs per `feature batch-update` or `test batch-update` command.
|
||||
- Required progression:
|
||||
- `deferred/not_started -> stub` when active work starts.
|
||||
- `stub -> complete` only after stub checks + group build gate.
|
||||
- `complete -> verified` only after full related test gate passes.
|
||||
- Evidence required before each status chunk:
|
||||
- successful build output,
|
||||
- successful related test output,
|
||||
- clean stub scan output,
|
||||
- explicit list of IDs being updated.
|
||||
|
||||
Example (feature chunk <=15):
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- \
|
||||
feature batch-update --ids "2166,2167,2168,2169,2170,2171,2172,2173,2174,2175,2176,2177,2178" \
|
||||
--set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
### Checkpoint Protocol Between Tasks (REQUIRED)
|
||||
|
||||
After each major task (every feature group and every test wave):
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db
|
||||
git commit -m "<task checkpoint message>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)
|
||||
|
||||
### Forbidden Patterns
|
||||
|
||||
For Batch 22 mapped features and tests, these are forbidden:
|
||||
|
||||
- `throw new NotImplementedException()`
|
||||
- Empty method bodies for mapped features
|
||||
- `// TODO`, `// PLACEHOLDER`, or temporary fake logic in mapped methods
|
||||
- Trivial default-return stubs for non-trivial behavior (`return null`, `return 0`, `return false`, `return string.Empty`)
|
||||
- Placeholder test bodies that do not execute Batch 22 production code
|
||||
- Literal/self assertions used as fake test pass criteria (for example `"...".ShouldContain("Should")`)
|
||||
- Placeholder signature pattern `var goFile = "server/..."` without real Arrange/Act/Assert on production code
|
||||
|
||||
### Hard Limits
|
||||
|
||||
- Maximum `~20` features per implementation task group
|
||||
- Maximum `15` IDs per status-update command
|
||||
- One active feature-group status cycle at a time (start, implement, gate, update)
|
||||
- Zero tolerance for unresolved stub-scan hits in touched files
|
||||
- Mandatory checkpoint (build + test + commit) between tasks
|
||||
|
||||
### If You Get Stuck (REQUIRED)
|
||||
|
||||
1. Stop on the blocked feature/test ID immediately.
|
||||
2. Remove any partial placeholder code; do not keep a stub.
|
||||
3. Mark as deferred with explicit blocker reason:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status deferred --override "blocked: <specific reason>" --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test update <id> --status deferred --override "blocked: <specific reason>" --db porting.db
|
||||
```
|
||||
|
||||
4. Continue with next unblocked ID.
|
||||
5. Do not write fake-pass tests to bypass blockers.
|
||||
|
||||
---
|
||||
|
||||
## Feature Groups (<=20 IDs each)
|
||||
|
||||
### Group 1 (13 IDs): Connz foundations and query decode
|
||||
|
||||
`2166,2167,2168,2169,2170,2171,2172,2173,2174,2175,2176,2177,2178`
|
||||
|
||||
Scope focus:
|
||||
- `newSubsDetailList`, `newSubsList`
|
||||
- `Connz` core + `ConnInfo.fill`
|
||||
- query decode helpers (`decodeBool`, `decodeUint64`, `decodeInt`, `decodeState`, `decodeSubs`)
|
||||
- `/connz` handler
|
||||
|
||||
### Group 2 (9 IDs): Route/Sub/stack/ipqueue monitoring
|
||||
|
||||
`2179,2180,2181,2182,2183,2184,2185,2186,2187`
|
||||
|
||||
Scope focus:
|
||||
- `Routez`, `Subsz`, sub detail projections
|
||||
- `/routez`, `/subsz`, `/stacksz`, `/ipqueuesz` handlers
|
||||
|
||||
### Group 3 (11 IDs): Varz core and root-level metadata
|
||||
|
||||
`2188,2189,2190,2191,2192,2193,2194,2195,2196,2197,2198`
|
||||
|
||||
Scope focus:
|
||||
- uptime and TLS helper projections
|
||||
- root endpoint output
|
||||
- varz creation and reload/runtime update paths
|
||||
- `/varz` handler
|
||||
|
||||
### Group 4 (10 IDs): Gateway monitor projections and handlers
|
||||
|
||||
`2199,2200,2201,2202,2203,2204,2205,2206,2207,2208`
|
||||
|
||||
Scope focus:
|
||||
- gateway monitor options and inbound/outbound projections
|
||||
- `/gatewayz` handler
|
||||
|
||||
### Group 5 (13 IDs): Leaf/Account monitor surfaces and detail projections
|
||||
|
||||
`2209,2210,2211,2212,2213,2214,2215,2216,2217,2218,2219,2220,2221`
|
||||
|
||||
Scope focus:
|
||||
- `Leafz`, `AccountStatz`, `Accountz`
|
||||
- response helper wrappers (`ResponseHandler`, `handleResponse`)
|
||||
- `ClosedState.String`
|
||||
- account import/export/detail projections (`newExtServiceLatency`, `newExtImport`, `accountInfo`, `accountDetail`)
|
||||
|
||||
### Group 6 (14 IDs): JSz, healthz, expvar/profile, raftz
|
||||
|
||||
`2222,2223,2224,2225,2226,2227,2228,2229,2230,2231,2232,2233,2234,2235`
|
||||
|
||||
Scope focus:
|
||||
- `JszAccount`, `Jsz`, `/jsz`
|
||||
- health type serialization and `/healthz` internals
|
||||
- `/debug/vars` and profile reporting
|
||||
- `/raftz` endpoint and aggregation
|
||||
|
||||
---
|
||||
|
||||
## Mapped Test Waves (29 IDs)
|
||||
|
||||
### Wave 1 (13 IDs): MonitoringHandlerTests
|
||||
|
||||
`2064,2087,2090,2092,2093,2112,2117,2120,2121,2143,2150,2157,2165`
|
||||
|
||||
Target file:
|
||||
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
|
||||
Execution notes:
|
||||
- Replace placeholder methods with real endpoint behavior assertions.
|
||||
- `Benchmark_*` mapped entries must still assert measurable behavior in deterministic unit-test style if kept as tests; if they must remain benchmark-only, keep deferred with explicit reason.
|
||||
|
||||
### Wave 2 (16 IDs): Cross-class monitor dependencies
|
||||
|
||||
`89,318,1393,1394,1930,1964,1980,1981,1982,2004,2772,2815,2831,2837,2851,2857`
|
||||
|
||||
Target files:
|
||||
- `AccountTests.Impltests.cs`
|
||||
- `EventsHandlerTests.Impltests.cs`
|
||||
- `JetStreamJwtTests.Impltests.cs`
|
||||
- `LeafNodeHandlerTests.Impltests.cs`
|
||||
- `ConfigReloaderTests.Impltests.cs`
|
||||
- `RouteHandlerTests.Impltests.cs`
|
||||
|
||||
Execution notes:
|
||||
- Validate each test still maps to Batch 22 features (`Connz`, `Routez`, `Subsz`, `Varz`, `Leafz`, `Accountz`, `Jsz`, `profilez`) and rewrite assertions around those paths.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Preflight and Batch Start
|
||||
|
||||
**Files:**
|
||||
- Read: `docs/standards/dotnet-standards.md`
|
||||
- Read: `docs/plans/2026-02-27-batch-22-monitoring-design.md`
|
||||
- Read: `golang/nats-server/server/monitor.go`
|
||||
|
||||
**Step 1: Confirm scope and dependencies**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 22 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
|
||||
```
|
||||
|
||||
**Step 2: Start batch**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch start 22 --db porting.db
|
||||
```
|
||||
|
||||
**Step 3: Baseline gate**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
|
||||
**Step 4: Commit checkpoint**
|
||||
|
||||
```bash
|
||||
git add porting.db
|
||||
git commit -m "chore(batch22): start monitoring batch"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Implement Feature Group 1 (13 IDs)
|
||||
|
||||
**Files:**
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.Connz.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorSortOptions.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2166,2167,2168,2169,2170,2171,2172,2173,2174,2175,2176,2177,2178" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 13 IDs**
|
||||
|
||||
**Step 3: Run Stub Detection Check + Build Gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2166,2167,2168,2169,2170,2171,2172,2173,2174,2175,2176,2177,2178" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Implement Feature Group 2 (9 IDs)
|
||||
|
||||
**Files:**
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.RouteSub.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorTypes.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2179,2180,2181,2182,2183,2184,2185,2186,2187" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 9 IDs**
|
||||
|
||||
**Step 3: Run Stub Detection Check + Build Gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2179,2180,2181,2182,2183,2184,2185,2186,2187" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Implement Feature Group 3 (11 IDs)
|
||||
|
||||
**Files:**
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.Varz.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorTypes.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2188,2189,2190,2191,2192,2193,2194,2195,2196,2197,2198" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 11 IDs**
|
||||
|
||||
**Step 3: Run Stub Detection Check + Build Gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2188,2189,2190,2191,2192,2193,2194,2195,2196,2197,2198" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Implement Feature Group 4 (10 IDs)
|
||||
|
||||
**Files:**
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.GatewayLeaf.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorTypes.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2199,2200,2201,2202,2203,2204,2205,2206,2207,2208" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 10 IDs**
|
||||
|
||||
**Step 3: Run Stub Detection Check + Build Gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2199,2200,2201,2202,2203,2204,2205,2206,2207,2208" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Implement Feature Group 5 (13 IDs)
|
||||
|
||||
**Files:**
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.AccountJsz.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/ClientTypes.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorTypes.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2209,2210,2211,2212,2213,2214,2215,2216,2217,2218,2219,2220,2221" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 13 IDs**
|
||||
|
||||
**Step 3: Run Stub Detection Check + Build Gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2209,2210,2211,2212,2213,2214,2215,2216,2217,2218,2219,2220,2221" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Implement Feature Group 6 (14 IDs)
|
||||
|
||||
**Files:**
|
||||
- Create/Modify: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring.HealthRaft.cs`
|
||||
- Modify: `dotnet/src/ZB.MOM.NatsNet.Server/Monitor/MonitorTypes.cs`
|
||||
|
||||
**Step 1: Move IDs to `stub`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2222,2223,2224,2225,2226,2227,2228,2229,2230,2231,2232,2233,2234,2235" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Execute Per-Feature Verification Loop for all 14 IDs**
|
||||
|
||||
**Step 3: Run Stub Detection Check + Build Gate**
|
||||
|
||||
**Step 4: Move IDs to `complete`**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2222,2223,2224,2225,2226,2227,2228,2229,2230,2231,2232,2233,2234,2235" --set-status complete --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 8: Implement Test Wave 1 (MonitoringHandler class)
|
||||
|
||||
**Files:**
|
||||
- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs`
|
||||
|
||||
**Mapped IDs:**
|
||||
- `2064,2087,2090,2092,2093,2112,2117,2120,2121,2143,2150,2157,2165`
|
||||
|
||||
**Step 1: Move IDs to `stub` (max 15, one command valid)**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "2064,2087,2090,2092,2093,2112,2117,2120,2121,2143,2150,2157,2165" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Rewrite each mapped test with real Arrange/Act/Assert behavior**
|
||||
|
||||
**Step 3: Run class filter and stub checks**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.ImplBacklog.MonitoringHandlerTests"
|
||||
```
|
||||
|
||||
**Step 4: Move passing IDs to `verified`; keep blocked IDs deferred with reason**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "<passing IDs, max 15>" --set-status verified --db porting.db --execute
|
||||
# for blocked IDs:
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test update <id> --status deferred --override "blocked: <reason>" --db porting.db
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 9: Implement Test Wave 2 (Cross-class mapped tests)
|
||||
|
||||
**Files:**
|
||||
- Modify: `AccountTests.Impltests.cs`
|
||||
- Modify: `EventsHandlerTests.Impltests.cs`
|
||||
- Modify: `JetStreamJwtTests.Impltests.cs`
|
||||
- Modify: `LeafNodeHandlerTests.Impltests.cs`
|
||||
- Modify: `ConfigReloaderTests.Impltests.cs`
|
||||
- Modify: `RouteHandlerTests.Impltests.cs`
|
||||
|
||||
**Mapped IDs:**
|
||||
- `89,318,1393,1394,1930,1964,1980,1981,1982,2004,2772,2815,2831,2837,2851,2857`
|
||||
|
||||
**Step 1: Move IDs to `stub` in chunks <=15**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "89,318,1393,1394,1930,1964,1980,1981,1982,2004,2772,2815,2831,2837,2851" --set-status stub --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "2857" --set-status stub --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 2: Rewrite mapped tests with real production assertions**
|
||||
|
||||
**Step 3: Run per-class filters + related endpoint filters**
|
||||
|
||||
```bash
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~AccountTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~EventsHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~JetStreamJwtTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~LeafNodeHandlerTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ConfigReloaderTests"
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~RouteHandlerTests"
|
||||
```
|
||||
|
||||
**Step 4: Move passing IDs to `verified`, defer blocked IDs with reason**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "<passing IDs chunk 1, max 15>" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test batch-update --ids "<passing IDs chunk 2, max 15>" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 5: Run Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 10: Promote Features to Verified (After Test Gate)
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
|
||||
**Step 1: Run full related test gate (all seven classes)**
|
||||
|
||||
**Step 2: Promote features `2166-2235` from `complete` to `verified` in chunks <=15**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2166,2167,2168,2169,2170,2171,2172,2173,2174,2175,2176,2177,2178,2179,2180" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2181,2182,2183,2184,2185,2186,2187,2188,2189,2190,2191,2192,2193,2194,2195" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2196,2197,2198,2199,2200,2201,2202,2203,2204,2205,2206,2207,2208,2209,2210" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2211,2212,2213,2214,2215,2216,2217,2218,2219,2220,2221,2222,2223,2224,2225" --set-status verified --db porting.db --execute
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids "2226,2227,2228,2229,2230,2231,2232,2233,2234,2235" --set-status verified --db porting.db --execute
|
||||
```
|
||||
|
||||
**Step 3: Checkpoint Protocol**
|
||||
|
||||
---
|
||||
|
||||
## Task 11: Final Batch 22 Closure
|
||||
|
||||
**Files:**
|
||||
- Modify: `porting.db`
|
||||
- Generate: `reports/current.md` (via script)
|
||||
|
||||
**Step 1: Full regression and final stub audit**
|
||||
|
||||
```bash
|
||||
dotnet build dotnet/
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
grep -R -n -E "(NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)|var goFile = \"server/|ShouldContain\(\"Should\"\))" \
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Monitoring*.cs \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog
|
||||
```
|
||||
|
||||
**Step 2: Validate tracker state**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch show 22 --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- batch complete 22 --db porting.db
|
||||
```
|
||||
|
||||
**Step 3: Generate report and commit**
|
||||
|
||||
```bash
|
||||
./reports/generate-report.sh
|
||||
git add dotnet/src/ZB.MOM.NatsNet.Server dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db reports/
|
||||
git commit -m "feat(batch22): complete monitoring endpoints and mapped tests"
|
||||
```
|
||||
Reference in New Issue
Block a user