natsdotnet/docs/plans/2026-02-22-base-server-design.md

NATS .NET Base Server Design

Date: 2026-02-22 Scope: Minimal single-node NATS server — pub/sub, queue groups, wildcards. No auth, clustering, JetStream, or monitoring. Target: .NET 10, C# Approach: Bottom-up (Sublist → Parser → Client → Server)

Decisions

• Framework: .NET 10
• I/O: System.IO.Pipelines for zero-copy protocol parsing
• Structure: Library (NATS.Server) + Host (NATS.Server.Host) + Tests (NATS.Server.Tests)
• Test framework: xUnit
• Queue group selection: Round-robin with atomic counter

Solution Layout

natsdotnet/
├── NatsDotNet.sln
├── src/
│   ├── NATS.Server/                 # Core library
│   │   ├── NatsServer.cs            # Server orchestrator
│   │   ├── NatsClient.cs            # Client connection
│   │   ├── NatsOptions.cs           # Configuration
│   │   ├── Protocol/
│   │   │   ├── NatsProtocol.cs      # Constants, op codes
│   │   │   └── NatsParser.cs        # Pipeline-based parser
│   │   └── Subscriptions/
│   │       ├── Subscription.cs
│   │       ├── SubjectMatch.cs
│   │       └── SubList.cs           # Trie + cache
│   └── NATS.Server.Host/            # Console app
│       └── Program.cs
└── tests/
    └── NATS.Server.Tests/

Component Designs

1. SubList (subject matching trie)

Reference: golang/nats-server/server/sublist.go

Structures:

• SubList — root trie + cache (Dictionary<string, SubListResult>) + ReaderWriterLockSlim + atomic genId
• TrieLevel — Dictionary<string, TrieNode> for literal tokens, nullable pwc (*) and fwc (>) pointers
• TrieNode — optional next: TrieLevel, HashSet<Subscription> for plain subs, Dictionary<string, HashSet<Subscription>> for queue subs
• Subscription — client ref, subject, queue, sid, atomic message count, max messages
• SubListResult — Subscription[] plain subs, Subscription[][] queue subs (grouped)

Operations:

• Insert(Subscription) — walk trie by .-split tokens, create nodes, add sub, increment genId (clears cache)
• Remove(Subscription) — reverse, prune empty nodes, increment genId
• Match(ReadOnlySpan<byte>) — cache check (convert to string key on miss), walk trie collecting matches from literal + * + > nodes
• Thread safety: read lock for Match, write lock for Insert/Remove

2. Protocol Parser

Reference: golang/nats-server/server/parser.go

Operates on PipeReader. Scans for \r\n to delimit control lines. Identifies command by first bytes. For PUB/HPUB, reads control line then exactly size bytes of payload + \r\n.

Commands (base server):

Command	Direction	Control line format
INFO	S→C	INFO {json}\r\n
CONNECT	C→S	CONNECT {json}\r\n
PUB	C→S	PUB subject [reply] size\r\n[payload]\r\n
HPUB	C→S	HPUB subject [reply] hdr_size total_size\r\n[hdrs+payload]\r\n
SUB	C→S	SUB subject [queue] sid\r\n
UNSUB	C→S	UNSUB sid [max_msgs]\r\n
MSG	S→C	MSG subject sid [reply] size\r\n[payload]\r\n
HMSG	S→C	HMSG subject sid [reply] hdr_size total_size\r\n[hdrs+payload]\r\n
PING/PONG	Both	PING\r\n / PONG\r\n
+OK / -ERR	S→C	+OK\r\n / -ERR 'msg'\r\n

Design choices:

• Parser returns parsed command structs, does not dispatch
• No string allocation on hot path — subject matching uses Span<byte>
• Max control line: 4096 bytes, max payload: 1MB default (configurable)

3. NatsClient (connection handler)

Reference: golang/nats-server/server/client.go

Fields: unique id, Socket, IDuplexPipe, back-ref to server, subs dict (sid→Subscription), ClientOptions (from CONNECT json), stats (Interlocked counters), SemaphoreSlim for write serialization.

Lifecycle:

1. Server accepts socket, creates NatsClient
2. RunAsync(CancellationToken): send INFO → read loop (parse + dispatch commands)
3. Dispatch: CONNECT→validate, SUB→insert into SubList, UNSUB→remove, PUB→server.ProcessMessage(), PING→PONG
4. On disconnect: remove all subs, remove from server clients dict

Writing: SendMessageAsync() formats MSG/HMSG, acquires write lock, writes to PipeWriter, flushes.

4. NatsServer (orchestrator)

Reference: golang/nats-server/server/server.go

Fields: NatsOptions, TCP listener Socket, ConcurrentDictionary<ulong, NatsClient>, SubList, atomic next client ID, ServerInfo struct, CancellationTokenSource.

Core methods:

• StartAsync() — bind, accept loop
• ProcessMessage(subject, reply, headers, payload, sender) — SubList.Match → deliver to plain subs + pick one per queue group (round-robin)
• RemoveClient(client) — cleanup subs and client dict
• Shutdown() — cancel, close listener, drain

5. NatsOptions

Reference: golang/nats-server/server/opts.go

Minimal for base: Host, Port (default 4222), ServerName, MaxPayload (1MB), MaxControlLine (4096), MaxConnections, PingInterval, MaxPingsOut.

Testing Strategy

Unit tests:

• SubList: insert/remove/match with literals, *, >, queue groups, cache invalidation. Port Go test cases.
• Parser: each command type, malformed input, partial reads, boundary sizes.
• Client protocol: CONNECT handshake, SUB/UNSUB lifecycle, PUB delivery, PING/PONG via loopback sockets.

Integration tests (using NATS.Client.Core NuGet):

• Basic pub/sub, wildcard matching, queue group distribution, fan-out, UNSUB + auto-unsub, PING/PONG.

Module Boundaries (future)

These are explicitly excluded from this design and will be added as separate modules later:

Module	Key files in Go reference
Authentication	auth.go, auth_callout.go, nkey.go, jwt.go
Monitoring HTTP	monitor.go
Clustering/Routes	route.go
Gateways	gateway.go
Leaf Nodes	leafnode.go
JetStream	jetstream.go, stream.go, consumer.go, filestore.go, memstore.go, raft.go
WebSocket	websocket.go
MQTT	mqtt.go
TLS	TLS config in opts.go, various TLS setup in server.go