natsnet/docs/plans/2026-02-26-phase7-design.md

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:

-- 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.