diff --git a/docs/plans/2026-02-26-phase7-design.md b/docs/plans/2026-02-26-phase7-design.md new file mode 100644 index 0000000..b548c3d --- /dev/null +++ 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. diff --git a/reports/current.md b/reports/current.md index ebd499f..ee3f30a 100644 --- 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) diff --git a/reports/report_a0c9c00.md b/reports/report_a0c9c00.md new file mode 100644 index 0000000..ee3f30a --- /dev/null +++ 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%)**