docs: Phase 7 design — porting verification approach

Defines two-layer test strategy (unit vs server-integration/deferred), 10-session structure, schema extension adding deferred status, and completion criteria for Phase 7.
2026-02-26 18:38:28 -05:00
parent a0c9c0094c
commit d09de1c5cf
3 changed files with 182 additions and 1 deletions
--- a/docs/plans/2026-02-26-phase7-design.md
+++ b/docs/plans/2026-02-26-phase7-design.md
@@ -0,0 +1,144 @@
+# Phase 7: Porting Verification — Design
+
+**Date:** 2026-02-26
+**Scope:** Verify all ported code through targeted testing; mark server-integration tests as `deferred`
+
+---
+
+## Context
+
+After Phase 6 (23 porting sessions + 93 stub completions), the DB state entering Phase 7:
+
+| Item | Count |
+|------|-------|
+| Features complete | 3,596 / 3,673 (77 n_a) |
+| Unit tests complete | 319 |
+| Unit tests stub | 224 |
+| Unit tests not_started | 2,533 |
+| Unit tests n_a | 181 |
+| Unit tests total | 3,257 |
+
+635 unit tests currently pass. 166 `NotImplementedException` stubs remain in the server — the .NET server is not yet runnable end-to-end.
+
+---
+
+## Key Design Decision: Two Test Layers
+
+Go test files (`jetstream_test.go`, `monitor_test.go`, etc.) all use `RunBasicJetStreamServer()` / `RunServer()` — they start a real NATS server over TCP, then connect via NATS client. These are server-integration tests regardless of whether they target a single node or a cluster.
+
+| Layer | Tests | Treatment |
+|-------|-------|-----------|
+| **Unit** | Pure component logic (no server startup) | Port & verify in Phase 7 |
+| **Server-integration** | Require running NatsServer + NATS client | Status `deferred` |
+
+---
+
+## Schema Extension
+
+Add `deferred` to the `unit_tests.status` CHECK constraint:
+
+```sql
+-- Migration: add 'deferred' to unit_tests status enum
+-- Recreate table with updated constraint or use SQLite trigger workaround
+```
+
+`deferred` = test blocked on running server or cluster infrastructure. Distinct from `n_a` (not applicable to this port).
+
+---
+
+## Test Classification
+
+### Unit Tests to Port (~631 new tests)
+
+| Go source file | Not-started / Stub | Component |
+|---|---|---|
+| `opts_test.go` | 77 stubs + remaining | Config parsing / binding |
+| `jwt_test.go` | 88 stubs | JWT decode / validate |
+| `auth_test.go` | 6 stubs | Auth handler logic |
+| `auth_callout_test.go` | 31 stubs | Auth callout types / helpers |
+| `signal_test.go` | 16 stubs | Signal handler registration |
+| `log_test.go` | 3 stubs | Logger behaviour |
+| `config_check_test.go` | 3 stubs | Config validation |
+| `memstore_test.go` | 41 not_started | Memory store logic |
+| `store_test.go` | 17 not_started | Store interface contract |
+| `filestore_test.go` | 249 not_started | File store read/write/purge |
+| `jetstream_errors_test.go` | 4 not_started | Error type checks |
+| `jetstream_versioning_test.go` | 18 not_started | Version compatibility |
+| `jetstream_batching_test.go` | 29 not_started | Batching logic |
+| `dirstore_test.go` | 12 not_started | JWT directory store |
+| `accounts_test.go` | 31 not_started | Account logic (unit subset) |
+| `thw` module | 6 not_started | Time hash wheel |
+
+### Server-Integration Tests → `deferred` (~1,799 tests)
+
+| Go source file | Count | Deferred reason |
+|---|---|---|
+| `jetstream_test.go` | 320 | Needs running server |
+| `jetstream_consumer_test.go` | 161 | Needs running server |
+| `monitor_test.go` | 103 | HTTP monitoring endpoints |
+| `reload_test.go` | 73 | Live config reload |
+| `routes_test.go` | 70 | Multi-server routing |
+| `events_test.go` | 52 | Server event bus |
+| `server_test.go` | 20 | Server lifecycle |
+| `jetstream_cluster_*` (×4) | 456 | Multi-node cluster |
+| `mqtt_test.go` + extras | ~162 | MQTT server |
+| `websocket_test.go` | 109 | WebSocket server |
+| `raft_test.go` | 104 | Raft consensus |
+| `leafnode_test.go` + proxy | 120 | Leaf node infrastructure |
+| `gateway_test.go` | 88 | Gateway infrastructure |
+| `jetstream_super_cluster_test.go` | 47 | Super-cluster |
+| `norace_*` tests | ~141 | Race-detector / timing |
+| Benchmark tests | ~20 | Performance only |
+| Other cluster/misc | ~53 | Cluster infrastructure |
+
+---
+
+## Session Structure (10 sessions)
+
+| Session | Scope | New tests | Source files |
+|---------|-------|-----------|---|
+| **P7-01** | Schema migration + small module verification | 0 new (114 existing) | ats, avl, certidp, gsl, pse, stree, thw, tpm |
+| **P7-02** | Opts & config stubs + remaining opts tests | ~95 | `opts_test.go` |
+| **P7-03** | JWT stubs | 88 | `jwt_test.go` |
+| **P7-04** | Auth stubs + auth callout stubs | 37 | `auth_test.go`, `auth_callout_test.go`, `config_check_test.go` |
+| **P7-05** | Signal + log stubs | 19 | `signal_test.go`, `log_test.go` |
+| **P7-06** | Store unit tests — memory + interface | ~58 | `memstore_test.go`, `store_test.go` |
+| **P7-07** | File store unit tests (first half) | ~125 | `filestore_test.go` lines 1–~4,000 |
+| **P7-08** | File store unit tests (second half) | ~124 | `filestore_test.go` remainder |
+| **P7-09** | JetStream unit tests — errors, versioning, batching, dirstore, accounts | ~94 | `jetstream_errors_test.go`, `jetstream_versioning_test.go`, `jetstream_batching_test.go`, `dirstore_test.go`, `accounts_test.go` |
+| **P7-10** | Mark deferred, integration tests, DB final update, Phase 7 close | — | DB sweep + Gitea milestones 7 & 8 |
+
+**Total new tests written: ~640**
+
+---
+
+## Verification Flow (per session)
+
+1. Write / fill tests → build → run → confirm green
+2. Mark tests `complete` in DB (new tests) then `verified`
+3. Mark small modules `verified` in DB (P7-01); server module at P7-10
+4. `./reports/generate-report.sh` → commit
+
+---
+
+## Integration Tests (P7-10)
+
+Replace the placeholder `UnitTest1.cs` with `NatsServerBehaviorTests.cs`. Tests run against the **Go NATS server** (not the .NET server) to establish a behavioral baseline:
+
+- Basic pub/sub
+- Wildcard matching (`foo.*`, `foo.>`)
+- Queue groups
+- Connect/disconnect lifecycle
+- Protocol error handling
+
+---
+
+## Completion Definition
+
+Phase 7 is complete when:
+- All non-`n_a`, non-`deferred` tests are `verified`
+- `dotnet run --project tools/NatsNet.PortTracker -- phase check 7 --db porting.db` passes
+- Gitea issues #45–#52 closed
+- Gitea milestones 7 and 8 closed
+
+The ~1,799 `deferred` tests remain for a future phase once the .NET server is end-to-end runnable.
--- a/reports/current.md
+++ b/reports/current.md
@@ -1,6 +1,6 @@
 # NATS .NET Porting Status Report

-Generated: 2026-02-26 22:49:14 UTC
+Generated: 2026-02-26 23:38:28 UTC

 ## Modules (12 total)

--- a/reports/report_a0c9c00.md
+++ b/reports/report_a0c9c00.md
@@ -0,0 +1,37 @@
+# NATS .NET Porting Status Report
+
+Generated: 2026-02-26 23:38:28 UTC
+
+## Modules (12 total)
+
+| Status | Count |
+|--------|-------|
+| complete | 11 |
+| not_started | 1 |
+
+## Features (3673 total)
+
+| Status | Count |
+|--------|-------|
+| complete | 3596 |
+| n_a | 77 |
+
+## Unit Tests (3257 total)
+
+| Status | Count |
+|--------|-------|
+| complete | 319 |
+| n_a | 181 |
+| not_started | 2533 |
+| stub | 224 |
+
+## Library Mappings (36 total)
+
+| Status | Count |
+|--------|-------|
+| mapped | 36 |
+
+
+## Overall Progress
+
+**4184/6942 items complete (60.3%)**