natsnet/docs/plans/2026-03-01-deferred-features-design.md

Deferred Features Implementation Design

Date: 2026-03-01 Status: Draft Scope: 363 deferred features + 1 stub across 6 batches

Context

After completing batches 16-41, 363 features remain deferred (plus 1 stub). These were deferred because they require server runtime infrastructure — event dispatch loops, HTTP monitoring endpoints, MQTT session management, and account resolver dispatch.

Current state: 82.0% complete (5694/6942 items). This work targets bringing features to ~92% (all 363 + 1 stub → verified).

884 deferred tests (mostly integration/cluster tests) are out of scope — they remain deferred for a future integration testing phase.

Decisions

• Implementation depth: Full method bodies ported from Go to idiomatic C#. Methods will be functionally correct and will work once server runtime boots, but won't be exercised by tests yet.
• Tests: No new unit tests for these features. All 884 deferred tests remain deferred.
• Execution: Parallel Claude Code Sonnet agents with isolation: "worktree", 2-3 concurrent.
• PortTracker updates: Run audit after each batch merge to promote features to verified.

Batch Structure

Batch 42: Foundation Helpers (54 features)

MsgTrace full implementation (28), GatewayInterestMode.String (1), monitor standalone helpers (25).

Target files:

• MessageTrace/MsgTrace.cs (new or extend existing MsgTraceTypes.cs)
• Monitor/MonitorHelpers.cs (new)
• Gateway/GatewayTypes.cs (extend)

Feature IDs:

• MsgTrace: 2406-2413, 2420-2439
• Gateway: 1265
• Monitor helpers: 2166-2167, 2170-2171, 2173-2177, 2181-2182, 2188-2189, 2194, 2196, 2200, 2202-2204, 2206-2207, 2213-2214, 2216, 2219

Dependencies: None (foundation layer)

Batch 43: Accounts Resolvers & Service Latency (37 features)

Account resolver implementations (URL, Dir, CacheDir), service export timers, latency tracking, JWT/claims validation, tracing headers.

Target files:

• Accounts/AccountResolver.cs (extend with URL, Dir, CacheDir implementations)
• Accounts/Account.ServiceExports.cs (new or extend)
• Accounts/AccountTypes.cs (extend)
• NatsServer.Accounts.cs (extend)

Feature IDs: 150, 183, 208-209, 215, 250-253, 258-261, 306-307, 310, 316, 318-320, 326-328, 330-331, 334-339, 341, 343, 345-347, 349

Dependencies: None (foundation layer)

Batch 44: Events Core & Dispatch (46 features)

Event system foundation: helpers, ServerInfo capabilities, ClientInfo factory methods, internal send/receive loops, system subscription infrastructure.

Target files:

• Events/EventHelpers.cs (new)
• Events/EventTypes.cs (extend ServerInfo, ClientInfo)
• NatsServer.Events.cs (new partial — core dispatch)

Feature IDs:

• Helpers: 863, 882, 890-891, 912, 935, 939, 945-947
• ServerInfo: 854-859
• ClientInfo: 860-862
• pubMsg: 864
• client: 875
• Account: 920
• Server dispatch: 865-866, 868, 871-874, 876-878, 892-893, 909, 927-934, 937-938, 948

Dependencies: Batch 42 (MsgTrace types used by event sending)

Batch 45: Events Server Methods (42 features)

All remaining Server.* event methods: stats broadcasting, remote server tracking, account connection events, OCSP events, reload config notifications.

Target files:

• NatsServer.Events.cs (extend)
• NatsServer.EventsRemote.cs (new partial — remote server handling)

Feature IDs: 879-881, 883-889, 894-895, 897-905, 907-908, 910-911, 913-914, 917-919, 921, 923, 925-926, 936, 940-944, 949-950

Dependencies: Batch 44 (uses core dispatch infrastructure)

Batch 46: Monitor Endpoints (45 features)

HTTP monitoring endpoint implementations: Varz, Connz, Routez, Subsz, Gatewayz, Leafz, Accountz, Jsz, Healthz, Raftz, plus handler wrappers and type methods.

Target files:

• NatsServer.Monitor.cs (new partial — all endpoint methods)
• Monitor/MonitorTypes.cs (extend with fill/String/Marshal methods)

Feature IDs: 2168-2169, 2172, 2178-2180, 2183-2187, 2190-2193, 2195, 2197-2199, 2201, 2205, 2208-2212, 2215, 2217-2218, 2220-2235

Dependencies: Batch 42 (monitor helpers)

Batch 47: MQTT Full Runtime (139 features)

Complete MQTT implementation: mqttJSA (JetStream API bridge, 22), mqttSession (session lifecycle, 15), mqttAccountSessionManager (retained messages, session persistence, 26), Server.mqtt* (connection handling, 17), client.mqtt* (protocol parsing, 24), standalone helpers (35).

Target files:

• Mqtt/MqttJsa.cs (new — JetStream API bridge)
• Mqtt/MqttSession.cs (new — session state machine)
• Mqtt/MqttAccountSessionManager.cs (new — account-level session manager)
• Mqtt/MqttHandler.cs (extend — server-side handlers)
• Mqtt/MqttReader.cs (extend — protocol parsing)
• Mqtt/MqttWriter.cs (extend — protocol writing)
• NatsServer.Mqtt.cs (new partial — server integration)
• ClientConnection.Mqtt.cs (new partial — client-side methods)

Feature IDs: 2252-2255, 2257-2268, 2269-2290, 2291-2327, 2328-2404 (all 139 mqtt.go deferred features)

Dependencies: Batches 44+45 (MQTT uses event infrastructure for advisories)

Stub Feature (added to Batch 42)

• Feature 2962: scheduler.go:getScheduledMessages — currently stub, implement fully

Execution Plan

Wave 1 (parallel)

• Batch 42 (Foundation Helpers, 54 features)
• Batch 43 (Accounts, 37 features)

Wave 2 (parallel, after Wave 1)

• Batch 44 (Events Core, 46 features)
• Batch 46 (Monitor Endpoints, 45 features)

Wave 3 (after Batch 44)

• Batch 45 (Events Server, 42 features)

Wave 4 (after Batch 45)

• Batch 47 (MQTT Runtime, 139 features)

Post-Execution

After all batches merge:

1. Run dotnet build dotnet/ to confirm compilation
2. Run dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ to confirm no regressions
3. Reset deferred→unknown in porting.db, re-run audit
4. Generate final report

Expected Outcome

• Features: 3263 + 363 + 1 = 3627 verified (vs 3673 total = 98.7%)
• Remaining: 22 complete, 24 n/a = stable
• Tests: 2066 verified + audit promotions (deferred integration tests remain)