dohertj2/natsdotnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add structured logging, Shouldly assertions, CPM, and project documentation

Browse Source 
- Add Microsoft.Extensions.Logging + Serilog to NatsServer and NatsClient
- Convert all test assertions from xUnit Assert to Shouldly
- Add NSubstitute package for future mocking needs
- Introduce Central Package Management via Directory.Packages.props
- Add documentation_rules.md with style guide, generation/update rules, component map
- Generate 10 documentation files across 5 component folders (GettingStarted, Protocol, Subscriptions, Server, Configuration/Operations)
- Update CLAUDE.md with logging, testing, porting, agent model, CPM, and documentation guidance
This commit is contained in:
Joseph Doherty
2026-02-22 21:05:53 -05:00
parent b9f4dec523
commit 539b2b7588
25 changed files with 2734 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
tests/NATS.Server.Tests/ClientTests.cs
View File

@@ -3,6 +3,8 @@ using System.Net;
using System.Net.Sockets;
using System.Text;
using System.Text.Json;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using NATS.Server;
using NATS.Server.Protocol;
@@ -37,7 +39,7 @@ public class ClientTests : IAsyncDisposable
Port = 4222,
};
_natsClient = new NatsClient(1, _serverSocket, new NatsOptions(), serverInfo);
_natsClient = new NatsClient(1, _serverSocket, new NatsOptions(), serverInfo, NullLogger.Instance);
}
public async ValueTask DisposeAsync()
@@ -57,9 +59,9 @@ public class ClientTests : IAsyncDisposable
var n = await _clientSocket.ReceiveAsync(buf, SocketFlags.None);
var response = Encoding.ASCII.GetString(buf, 0, n);
Assert.StartsWith("INFO ", response);
Assert.Contains("server_id", response);
Assert.Contains("\r\n", response);
response.ShouldStartWith("INFO ");
response.ShouldContain("server_id");
response.ShouldContain("\r\n");
await _cts.CancelAsync();
}
@@ -80,7 +82,7 @@ public class ClientTests : IAsyncDisposable
var n = await _clientSocket.ReceiveAsync(buf, SocketFlags.None);
var response = Encoding.ASCII.GetString(buf, 0, n);
Assert.Contains("PONG\r\n", response);
response.ShouldContain("PONG\r\n");
await _cts.CancelAsync();
}

13
tests/NATS.Server.Tests/IntegrationTests.cs
View File

@@ -1,6 +1,7 @@
using System.Net;
using System.Net.Sockets;
using System.Text;
using Microsoft.Extensions.Logging.Abstractions;
using NATS.Client.Core;
using NATS.Server;
@@ -16,7 +17,7 @@ public class IntegrationTests : IAsyncDisposable
public IntegrationTests()
{
_port = GetFreePort();
_server = new NatsServer(new NatsOptions { Port = _port });
_server = new NatsServer(new NatsOptions { Port = _port }, NullLoggerFactory.Instance);
_serverTask = _server.StartAsync(_cts.Token);
Thread.Sleep(200); // Let server start
}
@@ -65,7 +66,7 @@ public class IntegrationTests : IAsyncDisposable
await pub.PublishAsync("test.subject", "Hello NATS!");
var result = await received.Task.WaitAsync(TimeSpan.FromSeconds(5));
Assert.Equal("Hello NATS!", result);
result.ShouldBe("Hello NATS!");
}
[Fact]
@@ -92,7 +93,7 @@ public class IntegrationTests : IAsyncDisposable
await pub.PublishAsync("test.hello", "data");
var result = await received.Task.WaitAsync(TimeSpan.FromSeconds(5));
Assert.Equal("test.hello", result);
result.ShouldBe("test.hello");
}
[Fact]
@@ -119,7 +120,7 @@ public class IntegrationTests : IAsyncDisposable
await pub.PublishAsync("test.foo.bar.baz", "data");
var result = await received.Task.WaitAsync(TimeSpan.FromSeconds(5));
Assert.Equal("test.foo.bar.baz", result);
result.ShouldBe("test.foo.bar.baz");
}
[Fact]
@@ -163,8 +164,8 @@ public class IntegrationTests : IAsyncDisposable
await pub.PublishAsync("fanout", "hello");
await done.Task.WaitAsync(TimeSpan.FromSeconds(5));
Assert.Equal(1, count1);
Assert.Equal(1, count2);
count1.ShouldBe(1);
count2.ShouldBe(1);
}
[Fact]

13
tests/NATS.Server.Tests/NATS.Server.Tests.csproj
View File

@@ -5,15 +5,18 @@
</PropertyGroup>
<ItemGroup>
<PackageReference Include="coverlet.collector" Version="6.0.4" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
<PackageReference Include="NATS.Client.Core" Version="2.7.2" />
<PackageReference Include="xunit" Version="2.9.3" />
<PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
<PackageReference Include="coverlet.collector" />
<PackageReference Include="Microsoft.NET.Test.Sdk" />
<PackageReference Include="NATS.Client.Core" />
<PackageReference Include="NSubstitute" />
<PackageReference Include="Shouldly" />
<PackageReference Include="xunit" />
<PackageReference Include="xunit.runner.visualstudio" />
</ItemGroup>
<ItemGroup>
<Using Include="Xunit" />
<Using Include="Shouldly" />
</ItemGroup>
<ItemGroup>

102
tests/NATS.Server.Tests/ParserTests.cs
View File

@@ -40,117 +40,117 @@ public class ParserTests
public async Task Parse_PING()
{
var cmds = await ParseAsync("PING\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Ping, cmds[0].Type);
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Ping);
}
[Fact]
public async Task Parse_PONG()
{
var cmds = await ParseAsync("PONG\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Pong, cmds[0].Type);
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Pong);
}
[Fact]
public async Task Parse_CONNECT()
{
var cmds = await ParseAsync("CONNECT {\"verbose\":false,\"echo\":true}\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Connect, cmds[0].Type);
Assert.Contains("verbose", Encoding.ASCII.GetString(cmds[0].Payload.ToArray()));
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Connect);
Encoding.ASCII.GetString(cmds[0].Payload.ToArray()).ShouldContain("verbose");
}
[Fact]
public async Task Parse_SUB_without_queue()
{
var cmds = await ParseAsync("SUB foo 1\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Sub, cmds[0].Type);
Assert.Equal("foo", cmds[0].Subject);
Assert.Null(cmds[0].Queue);
Assert.Equal("1", cmds[0].Sid);
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Sub);
cmds[0].Subject.ShouldBe("foo");
cmds[0].Queue.ShouldBeNull();
cmds[0].Sid.ShouldBe("1");
}
[Fact]
public async Task Parse_SUB_with_queue()
{
var cmds = await ParseAsync("SUB foo workers 1\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Sub, cmds[0].Type);
Assert.Equal("foo", cmds[0].Subject);
Assert.Equal("workers", cmds[0].Queue);
Assert.Equal("1", cmds[0].Sid);
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Sub);
cmds[0].Subject.ShouldBe("foo");
cmds[0].Queue.ShouldBe("workers");
cmds[0].Sid.ShouldBe("1");
}
[Fact]
public async Task Parse_UNSUB()
{
var cmds = await ParseAsync("UNSUB 1\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Unsub, cmds[0].Type);
Assert.Equal("1", cmds[0].Sid);
Assert.Equal(-1, cmds[0].MaxMessages);
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Unsub);
cmds[0].Sid.ShouldBe("1");
cmds[0].MaxMessages.ShouldBe(-1);
}
[Fact]
public async Task Parse_UNSUB_with_max()
{
var cmds = await ParseAsync("UNSUB 1 5\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Unsub, cmds[0].Type);
Assert.Equal("1", cmds[0].Sid);
Assert.Equal(5, cmds[0].MaxMessages);
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Unsub);
cmds[0].Sid.ShouldBe("1");
cmds[0].MaxMessages.ShouldBe(5);
}
[Fact]
public async Task Parse_PUB_with_payload()
{
var cmds = await ParseAsync("PUB foo 5\r\nHello\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Pub, cmds[0].Type);
Assert.Equal("foo", cmds[0].Subject);
Assert.Null(cmds[0].ReplyTo);
Assert.Equal("Hello", Encoding.ASCII.GetString(cmds[0].Payload.ToArray()));
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Pub);
cmds[0].Subject.ShouldBe("foo");
cmds[0].ReplyTo.ShouldBeNull();
Encoding.ASCII.GetString(cmds[0].Payload.ToArray()).ShouldBe("Hello");
}
[Fact]
public async Task Parse_PUB_with_reply()
{
var cmds = await ParseAsync("PUB foo reply 5\r\nHello\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Pub, cmds[0].Type);
Assert.Equal("foo", cmds[0].Subject);
Assert.Equal("reply", cmds[0].ReplyTo);
Assert.Equal("Hello", Encoding.ASCII.GetString(cmds[0].Payload.ToArray()));
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Pub);
cmds[0].Subject.ShouldBe("foo");
cmds[0].ReplyTo.ShouldBe("reply");
Encoding.ASCII.GetString(cmds[0].Payload.ToArray()).ShouldBe("Hello");
}
[Fact]
public async Task Parse_multiple_commands()
{
var cmds = await ParseAsync("PING\r\nPONG\r\nSUB foo 1\r\n");
Assert.Equal(3, cmds.Count);
Assert.Equal(CommandType.Ping, cmds[0].Type);
Assert.Equal(CommandType.Pong, cmds[1].Type);
Assert.Equal(CommandType.Sub, cmds[2].Type);
cmds.Count.ShouldBe(3);
cmds[0].Type.ShouldBe(CommandType.Ping);
cmds[1].Type.ShouldBe(CommandType.Pong);
cmds[2].Type.ShouldBe(CommandType.Sub);
}
[Fact]
public async Task Parse_PUB_zero_payload()
{
var cmds = await ParseAsync("PUB foo 0\r\n\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Pub, cmds[0].Type);
Assert.Empty(cmds[0].Payload.ToArray());
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Pub);
cmds[0].Payload.ToArray().ShouldBeEmpty();
}
[Fact]
public async Task Parse_case_insensitive()
{
var cmds = await ParseAsync("ping\r\npub FOO 3\r\nabc\r\n");
Assert.Equal(2, cmds.Count);
Assert.Equal(CommandType.Ping, cmds[0].Type);
Assert.Equal(CommandType.Pub, cmds[1].Type);
cmds.Count.ShouldBe(2);
cmds[0].Type.ShouldBe(CommandType.Ping);
cmds[1].Type.ShouldBe(CommandType.Pub);
}
[Fact]
@@ -161,17 +161,17 @@ public class ParserTests
var payload = "Hello";
var total = header.Length + payload.Length;
var cmds = await ParseAsync($"HPUB foo {header.Length} {total}\r\n{header}{payload}\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.HPub, cmds[0].Type);
Assert.Equal("foo", cmds[0].Subject);
Assert.Equal(header.Length, cmds[0].HeaderSize);
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.HPub);
cmds[0].Subject.ShouldBe("foo");
cmds[0].HeaderSize.ShouldBe(header.Length);
}
[Fact]
public async Task Parse_INFO()
{
var cmds = await ParseAsync("INFO {\"server_id\":\"test\"}\r\n");
Assert.Single(cmds);
Assert.Equal(CommandType.Info, cmds[0].Type);
cmds.ShouldHaveSingleItem();
cmds[0].Type.ShouldBe(CommandType.Info);
}
}

9
tests/NATS.Server.Tests/ServerTests.cs
View File

@@ -1,6 +1,7 @@
using System.Net;
using System.Net.Sockets;
using System.Text;
using Microsoft.Extensions.Logging.Abstractions;
using NATS.Server;
namespace NATS.Server.Tests;
@@ -15,7 +16,7 @@ public class ServerTests : IAsyncDisposable
{
// Use random port
_port = GetFreePort();
_server = new NatsServer(new NatsOptions { Port = _port });
_server = new NatsServer(new NatsOptions { Port = _port }, NullLoggerFactory.Instance);
}
public async ValueTask DisposeAsync()
@@ -54,7 +55,7 @@ public class ServerTests : IAsyncDisposable
using var client = await ConnectClientAsync();
var response = await ReadLineAsync(client);
Assert.StartsWith("INFO ", response);
response.ShouldStartWith("INFO ");
await _cts.CancelAsync();
}
@@ -84,7 +85,7 @@ public class ServerTests : IAsyncDisposable
var n = await sub.ReceiveAsync(buf, SocketFlags.None);
var msg = Encoding.ASCII.GetString(buf, 0, n);
Assert.Contains("MSG foo 1 5\r\nHello\r\n", msg);
msg.ShouldContain("MSG foo 1 5\r\nHello\r\n");
await _cts.CancelAsync();
}
@@ -110,7 +111,7 @@ public class ServerTests : IAsyncDisposable
var n = await sub.ReceiveAsync(buf, SocketFlags.None);
var msg = Encoding.ASCII.GetString(buf, 0, n);
Assert.Contains("MSG foo.bar 1 5\r\n", msg);
msg.ShouldContain("MSG foo.bar 1 5\r\n");
await _cts.CancelAsync();
}
}

50
tests/NATS.Server.Tests/SubListTests.cs
View File

@@ -15,9 +15,9 @@ public class SubListTests
sl.Insert(sub);
var r = sl.Match("foo.bar");
Assert.Single(r.PlainSubs);
Assert.Same(sub, r.PlainSubs[0]);
Assert.Empty(r.QueueSubs);
r.PlainSubs.ShouldHaveSingleItem();
r.PlainSubs[0].ShouldBeSameAs(sub);
r.QueueSubs.ShouldBeEmpty();
}
[Fact]
@@ -27,7 +27,7 @@ public class SubListTests
sl.Insert(MakeSub("foo.bar"));
var r = sl.Match("foo.baz");
Assert.Empty(r.PlainSubs);
r.PlainSubs.ShouldBeEmpty();
}
[Fact]
@@ -37,9 +37,9 @@ public class SubListTests
var sub = MakeSub("foo.*");
sl.Insert(sub);
Assert.Single(sl.Match("foo.bar").PlainSubs);
Assert.Single(sl.Match("foo.baz").PlainSubs);
Assert.Empty(sl.Match("foo.bar.baz").PlainSubs);
sl.Match("foo.bar").PlainSubs.ShouldHaveSingleItem();
sl.Match("foo.baz").PlainSubs.ShouldHaveSingleItem();
sl.Match("foo.bar.baz").PlainSubs.ShouldBeEmpty();
}
[Fact]
@@ -49,9 +49,9 @@ public class SubListTests
var sub = MakeSub("foo.>");
sl.Insert(sub);
Assert.Single(sl.Match("foo.bar").PlainSubs);
Assert.Single(sl.Match("foo.bar.baz").PlainSubs);
Assert.Empty(sl.Match("foo").PlainSubs);
sl.Match("foo.bar").PlainSubs.ShouldHaveSingleItem();
sl.Match("foo.bar.baz").PlainSubs.ShouldHaveSingleItem();
sl.Match("foo").PlainSubs.ShouldBeEmpty();
}
[Fact]
@@ -60,9 +60,9 @@ public class SubListTests
var sl = new SubList();
sl.Insert(MakeSub(">"));
Assert.Single(sl.Match("foo").PlainSubs);
Assert.Single(sl.Match("foo.bar").PlainSubs);
Assert.Single(sl.Match("foo.bar.baz").PlainSubs);
sl.Match("foo").PlainSubs.ShouldHaveSingleItem();
sl.Match("foo.bar").PlainSubs.ShouldHaveSingleItem();
sl.Match("foo.bar.baz").PlainSubs.ShouldHaveSingleItem();
}
[Fact]
@@ -75,7 +75,7 @@ public class SubListTests
sl.Insert(MakeSub(">", sid: "4"));
var r = sl.Match("foo.bar");
Assert.Equal(4, r.PlainSubs.Length);
r.PlainSubs.Length.ShouldBe(4);
}
[Fact]
@@ -84,10 +84,10 @@ public class SubListTests
var sl = new SubList();
var sub = MakeSub("foo.bar");
sl.Insert(sub);
Assert.Single(sl.Match("foo.bar").PlainSubs);
sl.Match("foo.bar").PlainSubs.ShouldHaveSingleItem();
sl.Remove(sub);
Assert.Empty(sl.Match("foo.bar").PlainSubs);
sl.Match("foo.bar").PlainSubs.ShouldBeEmpty();
}
[Fact]
@@ -99,19 +99,19 @@ public class SubListTests
sl.Insert(MakeSub("foo.bar", queue: "loggers", sid: "3"));
var r = sl.Match("foo.bar");
Assert.Empty(r.PlainSubs);
Assert.Equal(2, r.QueueSubs.Length); // 2 queue groups
r.PlainSubs.ShouldBeEmpty();
r.QueueSubs.Length.ShouldBe(2); // 2 queue groups
}
[Fact]
public void Count_tracks_subscriptions()
{
var sl = new SubList();
Assert.Equal(0u, sl.Count);
sl.Count.ShouldBe(0u);
sl.Insert(MakeSub("foo", sid: "1"));
sl.Insert(MakeSub("bar", sid: "2"));
Assert.Equal(2u, sl.Count);
sl.Count.ShouldBe(2u);
sl.Remove(MakeSub("foo", sid: "1"));
// Remove by reference won't work — we need the same instance
@@ -123,9 +123,9 @@ public class SubListTests
var sl = new SubList();
var sub = MakeSub("foo");
sl.Insert(sub);
Assert.Equal(1u, sl.Count);
sl.Count.ShouldBe(1u);
sl.Remove(sub);
Assert.Equal(0u, sl.Count);
sl.Count.ShouldBe(0u);
}
[Fact]
@@ -136,13 +136,13 @@ public class SubListTests
// Prime the cache
var r1 = sl.Match("foo.bar");
Assert.Single(r1.PlainSubs);
r1.PlainSubs.ShouldHaveSingleItem();
// Insert a wildcard that matches — cache should be invalidated
sl.Insert(MakeSub("foo.*", sid: "2"));
var r2 = sl.Match("foo.bar");
Assert.Equal(2, r2.PlainSubs.Length);
r2.PlainSubs.Length.ShouldBe(2);
}
[Fact]
@@ -154,6 +154,6 @@ public class SubListTests
sl.Insert(MakeSub("foo.bar.*", sid: "3"));
var r = sl.Match("foo.bar.baz");
Assert.Equal(3, r.PlainSubs.Length);
r.PlainSubs.Length.ShouldBe(3);
}
}

6
tests/NATS.Server.Tests/SubjectMatchTests.cs
View File

@@ -23,7 +23,7 @@ public class SubjectMatchTests
[InlineData("foo\tbar", false)] // no tabs
public void IsValidSubject(string subject, bool expected)
{
Assert.Equal(expected, SubjectMatch.IsValidSubject(subject));
SubjectMatch.IsValidSubject(subject).ShouldBe(expected);
}
[Theory]
@@ -35,7 +35,7 @@ public class SubjectMatchTests
[InlineData("*", false)]
public void IsValidPublishSubject(string subject, bool expected)
{
Assert.Equal(expected, SubjectMatch.IsValidPublishSubject(subject));
SubjectMatch.IsValidPublishSubject(subject).ShouldBe(expected);
}
[Theory]
@@ -52,6 +52,6 @@ public class SubjectMatchTests
[InlineData("foo.bar", "foo.bar.>", false)]
public void MatchLiteral(string literal, string pattern, bool expected)
{
Assert.Equal(expected, SubjectMatch.MatchLiteral(literal, pattern));
SubjectMatch.MatchLiteral(literal, pattern).ShouldBe(expected);
}
}