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

docs: add mqtt connection type implementation plan and task tracking

Browse Source
This commit is contained in:
Joseph Doherty
2026-02-23 08:49:24 -05:00
parent 71f7f569b9
commit 6228f748ab
3 changed files with 2590 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1642
docs/plans/2026-02-23-jetstream-full-parity-plan.md Normal file
View File

File diff suppressed because it is too large Load Diff

933
docs/plans/2026-02-23-mqtt-connection-type-plan.md Normal file
View File

@@ -0,0 +1,933 @@
# MQTT Connection Type Parity + Config Parsing Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.
**Goal:** Port Go-compatible MQTT connection-type handling for JWT `allowed_connection_types`, add `/connz` `mqtt_client` filtering, parse all Go `MQTTOpts` config fields, and expand `MqttOptsVarz` monitoring output — with tests and docs updates.
**Architecture:** Thread a connection-type value into auth context and enforce Go-style allowed-connection-type semantics in `JwtAuthenticator`. Add connz query-option filtering for `mqtt_client` across open and closed connections. Parse the full `mqtt {}` config block into a new `MqttOptions` model following the existing `ParseTls()` pattern in `ConfigProcessor`. Expand `MqttOptsVarz` and wire into `/varz`. Keep behavior backward-compatible and transport-agnostic so MQTT runtime plumbing can be added later without changing auth/monitoring/config semantics.
**Tech Stack:** .NET 10, xUnit 3, Shouldly, ASP.NET minimal APIs, System.Text.Json.
---
### Task 1: Add failing JWT connection-type behavior tests
**Files:**
- Modify: `tests/NATS.Server.Tests/JwtAuthenticatorTests.cs`
**Step 1: Write the failing tests**
Add these 5 test methods to the existing `JwtAuthenticatorTests` class. Each test must build a valid operator/account/user JWT chain (reuse the existing helper pattern from other tests in the file). The user JWT's `nats.allowed_connection_types` array controls which connection types are permitted.
```csharp
[Fact]
public async Task Allowed_connection_types_allows_standard_context()
{
// Build valid operator/account/user JWT chain.
// User JWT includes: "allowed_connection_types":["STANDARD"]
// Context sets ConnectionType = "STANDARD".
// Assert Authenticate() is not null.
}
[Fact]
public async Task Allowed_connection_types_rejects_mqtt_only_for_standard_context()
{
// User JWT includes: "allowed_connection_types":["MQTT"]
// Context sets ConnectionType = "STANDARD".
// Assert Authenticate() is null.
}
[Fact]
public async Task Allowed_connection_types_allows_known_even_with_unknown_values()
{
// User JWT includes: ["STANDARD", "SOME_NEW_TYPE"]
// Context sets ConnectionType = "STANDARD".
// Assert Authenticate() is not null.
}
[Fact]
public async Task Allowed_connection_types_rejects_when_only_unknown_values_present()
{
// User JWT includes: ["SOME_NEW_TYPE"]
// Context sets ConnectionType = "STANDARD".
// Assert Authenticate() is null.
}
[Fact]
public async Task Allowed_connection_types_is_case_insensitive_for_input_values()
{
// User JWT includes: ["standard"]
// Context sets ConnectionType = "STANDARD".
// Assert Authenticate() is not null.
}
```
**Step 2: Run test to verify it fails**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~JwtAuthenticatorTests.Allowed_connection_types" -v minimal`
Expected: FAIL (current implementation ignores `allowed_connection_types`).
**Step 3: Commit test-only checkpoint**
```bash
git add tests/NATS.Server.Tests/JwtAuthenticatorTests.cs
git commit -m "test: add failing jwt allowed connection type coverage"
```
---
### Task 2: Implement auth connection-type model and Go-style allowed-type conversion
**Files:**
- Modify: `src/NATS.Server/Auth/IAuthenticator.cs` (line 11-16: add `ConnectionType` property to `ClientAuthContext`)
- Create: `src/NATS.Server/Auth/Jwt/JwtConnectionTypes.cs`
- Modify: `src/NATS.Server/Auth/JwtAuthenticator.cs` (insert check after step 7 revocation check, before step 8 permissions, around line 97)
- Modify: `src/NATS.Server/NatsClient.cs` (line 382-387: add `ConnectionType` to auth context construction)
**Step 1: Add connection type to auth context**
In `src/NATS.Server/Auth/IAuthenticator.cs`, add the `ConnectionType` property to `ClientAuthContext`. Note: this requires adding a `using NATS.Server.Auth.Jwt;` at the top of the file.
```csharp
public sealed class ClientAuthContext
{
public required ClientOptions Opts { get; init; }
public required byte[] Nonce { get; init; }
public string ConnectionType { get; init; } = JwtConnectionTypes.Standard;
public X509Certificate2? ClientCertificate { get; init; }
}
```
**Step 2: Create JWT connection-type constants + converter helper**
Create new file `src/NATS.Server/Auth/Jwt/JwtConnectionTypes.cs`:
```csharp
namespace NATS.Server.Auth.Jwt;
/// <summary>
/// Known connection type constants matching Go server/client.go.
/// Used for JWT allowed_connection_types claim validation.
/// Reference: golang/nats-server/server/client.go connectionType constants.
/// </summary>
internal static class JwtConnectionTypes
{
public const string Standard = "STANDARD";
public const string Websocket = "WEBSOCKET";
public const string Leafnode = "LEAFNODE";
public const string LeafnodeWs = "LEAFNODE_WS";
public const string Mqtt = "MQTT";
public const string MqttWs = "MQTT_WS";
public const string InProcess = "INPROCESS";
private static readonly HashSet<string> Known =
[
Standard, Websocket, Leafnode, LeafnodeWs, Mqtt, MqttWs, InProcess,
];
/// <summary>
/// Converts a list of connection type strings (from JWT claims) into a set of
/// known valid types plus a flag indicating unknown values were present.
/// Reference: Go server/client.go convertAllowedConnectionTypes.
/// </summary>
public static (HashSet<string> Valid, bool HasUnknown) Convert(IEnumerable<string>? values)
{
var valid = new HashSet<string>(StringComparer.Ordinal);
var hasUnknown = false;
if (values is null) return (valid, false);
foreach (var raw in values)
{
var up = (raw ?? string.Empty).Trim().ToUpperInvariant();
if (up.Length == 0) continue;
if (Known.Contains(up)) valid.Add(up);
else hasUnknown = true;
}
return (valid, hasUnknown);
}
}
```
**Step 3: Enforce allowed connection types in JWT auth**
In `src/NATS.Server/Auth/JwtAuthenticator.cs`, insert the following block after the revocation check (step 7, around line 96) and before the permissions build (step 8):
```csharp
// 7b. Check allowed connection types
var (allowedTypes, hasUnknown) = JwtConnectionTypes.Convert(userClaims.Nats?.AllowedConnectionTypes);
if (allowedTypes.Count == 0)
{
if (hasUnknown)
return null; // unknown-only list should reject
}
else
{
var connType = string.IsNullOrWhiteSpace(context.ConnectionType)
? JwtConnectionTypes.Standard
: context.ConnectionType.ToUpperInvariant();
if (!allowedTypes.Contains(connType))
return null;
}
```
**Step 4: Set auth context connection type in client connect path**
In `src/NATS.Server/NatsClient.cs` around line 382, add `ConnectionType` to the existing `ClientAuthContext` construction:
```csharp
var context = new ClientAuthContext
{
Opts = ClientOpts,
Nonce = _nonce ?? [],
ConnectionType = JwtConnectionTypes.Standard,
ClientCertificate = TlsState?.PeerCert,
};
```
Add `using NATS.Server.Auth.Jwt;` at the top of the file.
**Step 5: Run tests to verify pass**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~JwtAuthenticatorTests.Allowed_connection_types" -v minimal`
Expected: PASS.
**Step 6: Commit implementation checkpoint**
```bash
git add src/NATS.Server/Auth/IAuthenticator.cs src/NATS.Server/Auth/Jwt/JwtConnectionTypes.cs src/NATS.Server/Auth/JwtAuthenticator.cs src/NATS.Server/NatsClient.cs
git commit -m "feat: enforce jwt allowed connection types with go-compatible semantics"
```
---
### Task 3: Add failing connz mqtt_client filter tests
**Files:**
- Modify: `tests/NATS.Server.Tests/MonitorTests.cs`
**Step 1: Write the failing tests**
Add these 2 test methods to the existing `MonitorTests` class. These test the `/connz?mqtt_client=<id>` query parameter filtering.
```csharp
[Fact]
public async Task Connz_filters_by_mqtt_client_for_open_connections()
{
// Start server with monitoring port.
// Connect a regular NATS client (no MQTT ID).
// Query /connz?mqtt_client=some-id.
// Assert num_connections == 0 (no client has that MQTT ID).
}
[Fact]
public async Task Connz_filters_by_mqtt_client_for_closed_connections()
{
// Start server with monitoring port.
// Query /connz?state=closed&mqtt_client=missing-id.
// Assert num_connections == 0.
}
```
**Step 2: Run tests to verify expected failure mode**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~MonitorTests.Connz_filters_by_mqtt_client" -v minimal`
Expected: FAIL (query option not implemented yet — `mqtt_client` param ignored, so all connections returned).
**Step 3: Commit test-only checkpoint**
```bash
git add tests/NATS.Server.Tests/MonitorTests.cs
git commit -m "test: add failing connz mqtt_client filter coverage"
```
---
### Task 4: Implement connz mqtt_client filtering and closed snapshot support
**Files:**
- Modify: `src/NATS.Server/Monitoring/Connz.cs` (line 191-210: add `MqttClient` to `ConnzOptions`)
- Modify: `src/NATS.Server/Monitoring/ConnzHandler.cs` (line 148-201: parse query param; line 18-29: apply filter after collection but before sort)
- Modify: `src/NATS.Server/Monitoring/ClosedClient.cs` (line 6-25: add `MqttClient` property)
- Modify: `src/NATS.Server/NatsServer.cs` (line 695-714: add `MqttClient` to closed snapshot)
**Step 1: Add `MqttClient` to `ConnzOptions`**
In `src/NATS.Server/Monitoring/Connz.cs`, add after `FilterSubject` property (line 205):
```csharp
public string MqttClient { get; set; } = "";
```
**Step 2: Parse `mqtt_client` query param in handler**
In `src/NATS.Server/Monitoring/ConnzHandler.cs` `ParseQueryParams` method, add after the existing `limit` parse block (around line 198):
```csharp
if (q.TryGetValue("mqtt_client", out var mqttClient))
opts.MqttClient = mqttClient.ToString();
```
**Step 3: Apply `mqtt_client` filter in `HandleConnz`**
In `src/NATS.Server/Monitoring/ConnzHandler.cs` `HandleConnz` method, add after the closed connections collection block (after line 29) and before the sort validation (line 32):
```csharp
// Filter by MQTT client ID
if (!string.IsNullOrEmpty(opts.MqttClient))
connInfos = connInfos.Where(c => c.MqttClient == opts.MqttClient).ToList();
```
**Step 4: Add `MqttClient` to `ClosedClient` model**
In `src/NATS.Server/Monitoring/ClosedClient.cs`, add after line 24 (`TlsCipherSuite`):
```csharp
public string MqttClient { get; init; } = "";
```
**Step 5: Add `MqttClient` to closed snapshot creation in `NatsServer.RemoveClient`**
In `src/NATS.Server/NatsServer.cs` around line 713 (inside the `new ClosedClient { ... }` block), add:
```csharp
MqttClient = "", // populated when MQTT transport is implemented
```
**Step 6: Add `MqttClient` to `BuildClosedConnInfo`**
In `src/NATS.Server/Monitoring/ConnzHandler.cs` `BuildClosedConnInfo` method (line 119-146), add to the `new ConnInfo { ... }` initializer:
```csharp
MqttClient = closed.MqttClient,
```
**Step 7: Run connz mqtt filter tests**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~MonitorTests.Connz_filters_by_mqtt_client" -v minimal`
Expected: PASS.
**Step 8: Commit implementation checkpoint**
```bash
git add src/NATS.Server/Monitoring/Connz.cs src/NATS.Server/Monitoring/ConnzHandler.cs src/NATS.Server/Monitoring/ClosedClient.cs src/NATS.Server/NatsServer.cs
git commit -m "feat: add connz mqtt_client filtering"
```
---
### Task 5: Verification checkpoint for JWT + connz tasks
**Step 1: Run all JWT connection-type tests**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~JwtAuthenticatorTests.Allowed_connection_types" -v minimal`
Expected: PASS.
**Step 2: Run all connz tests**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~MonitorTests.Connz" -v minimal`
Expected: PASS.
**Step 3: Run full test suite**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj -v minimal`
Expected: PASS (no regressions).
---
### Task 6: Add MqttOptions model and config parsing
**Files:**
- Create: `src/NATS.Server/MqttOptions.cs`
- Modify: `src/NATS.Server/NatsOptions.cs` (line 116-117: add `Mqtt` property)
- Modify: `src/NATS.Server/Configuration/ConfigProcessor.cs` (line 248: add `mqtt` case; add `ParseMqtt` + `ParseMqttAuth` + `ParseMqttTls` + `ToDouble` methods)
**Step 1: Create `MqttOptions` model**
Create new file `src/NATS.Server/MqttOptions.cs`. This matches Go `MQTTOpts` struct (golang/nats-server/server/opts.go:613-707):
```csharp
namespace NATS.Server;
/// <summary>
/// MQTT protocol configuration options.
/// Corresponds to Go server/opts.go MQTTOpts struct.
/// Config is parsed and stored but no MQTT listener is started yet.
/// </summary>
public sealed class MqttOptions
{
// Network
public string Host { get; set; } = "";
public int Port { get; set; }
// Auth override (MQTT-specific, separate from global auth)
public string? NoAuthUser { get; set; }
public string? Username { get; set; }
public string? Password { get; set; }
public string? Token { get; set; }
public double AuthTimeout { get; set; }
// TLS
public string? TlsCert { get; set; }
public string? TlsKey { get; set; }
public string? TlsCaCert { get; set; }
public bool TlsVerify { get; set; }
public double TlsTimeout { get; set; } = 2.0;
public bool TlsMap { get; set; }
public HashSet<string>? TlsPinnedCerts { get; set; }
// JetStream integration
public string? JsDomain { get; set; }
public int StreamReplicas { get; set; }
public int ConsumerReplicas { get; set; }
public bool ConsumerMemoryStorage { get; set; }
public TimeSpan ConsumerInactiveThreshold { get; set; }
// QoS
public TimeSpan AckWait { get; set; } = TimeSpan.FromSeconds(30);
public ushort MaxAckPending { get; set; }
public TimeSpan JsApiTimeout { get; set; } = TimeSpan.FromSeconds(5);
public bool HasTls => TlsCert != null && TlsKey != null;
}
```
**Step 2: Add `Mqtt` property to `NatsOptions`**
In `src/NATS.Server/NatsOptions.cs`, add before the `HasTls` property (around line 117):
```csharp
// MQTT configuration (parsed from config, no listener yet)
public MqttOptions? Mqtt { get; set; }
```
**Step 3: Add `ToDouble` helper to `ConfigProcessor`**
In `src/NATS.Server/Configuration/ConfigProcessor.cs`, add after the `ToString` helper (around line 654):
```csharp
private static double ToDouble(object? value) => value switch
{
double d => d,
long l => l,
int i => i,
string s when double.TryParse(s, NumberStyles.Float, CultureInfo.InvariantCulture, out var d) => d,
_ => throw new FormatException($"Cannot convert {value?.GetType().Name ?? "null"} to double"),
};
```
**Step 4: Add `mqtt` case to `ProcessKey` switch**
In `src/NATS.Server/Configuration/ConfigProcessor.cs`, replace the default case comment at line 248:
```csharp
// MQTT
case "mqtt":
if (value is Dictionary<string, object?> mqttDict)
ParseMqtt(mqttDict, opts, errors);
break;
// Unknown keys silently ignored (cluster, jetstream, gateway, leafnode, etc.)
default:
break;
```
**Step 5: Add `ParseMqtt` method**
Add this method after `ParseTags` (around line 621). It follows the exact key/alias structure from Go `parseMQTT` (opts.go:5443-5541):
```csharp
// ─── MQTT parsing ─────────────────────────────────────────────
private static void ParseMqtt(Dictionary<string, object?> dict, NatsOptions opts, List<string> errors)
{
var mqtt = opts.Mqtt ?? new MqttOptions();
foreach (var (key, value) in dict)
{
switch (key.ToLowerInvariant())
{
case "listen":
var (host, port) = ParseHostPort(value);
if (host is not null) mqtt.Host = host;
if (port is not null) mqtt.Port = port.Value;
break;
case "port":
mqtt.Port = ToInt(value);
break;
case "host" or "net":
mqtt.Host = ToString(value);
break;
case "no_auth_user":
mqtt.NoAuthUser = ToString(value);
break;
case "tls":
if (value is Dictionary<string, object?> tlsDict)
ParseMqttTls(tlsDict, mqtt, errors);
break;
case "authorization" or "authentication":
if (value is Dictionary<string, object?> authDict)
ParseMqttAuth(authDict, mqtt, errors);
break;
case "ack_wait" or "ackwait":
mqtt.AckWait = ParseDuration(value);
break;
case "js_api_timeout" or "api_timeout":
mqtt.JsApiTimeout = ParseDuration(value);
break;
case "max_ack_pending" or "max_pending" or "max_inflight":
var pending = ToInt(value);
if (pending < 0 || pending > 0xFFFF)
errors.Add($"mqtt max_ack_pending invalid value {pending}, should be in [0..{0xFFFF}] range");
else
mqtt.MaxAckPending = (ushort)pending;
break;
case "js_domain":
mqtt.JsDomain = ToString(value);
break;
case "stream_replicas":
mqtt.StreamReplicas = ToInt(value);
break;
case "consumer_replicas":
mqtt.ConsumerReplicas = ToInt(value);
break;
case "consumer_memory_storage":
mqtt.ConsumerMemoryStorage = ToBool(value);
break;
case "consumer_inactive_threshold" or "consumer_auto_cleanup":
mqtt.ConsumerInactiveThreshold = ParseDuration(value);
break;
default:
// Unknown MQTT keys silently ignored
break;
}
}
opts.Mqtt = mqtt;
}
private static void ParseMqttAuth(Dictionary<string, object?> dict, MqttOptions mqtt, List<string> errors)
{
foreach (var (key, value) in dict)
{
switch (key.ToLowerInvariant())
{
case "user" or "username":
mqtt.Username = ToString(value);
break;
case "pass" or "password":
mqtt.Password = ToString(value);
break;
case "token":
mqtt.Token = ToString(value);
break;
case "timeout":
mqtt.AuthTimeout = ToDouble(value);
break;
default:
break;
}
}
}
private static void ParseMqttTls(Dictionary<string, object?> dict, MqttOptions mqtt, List<string> errors)
{
foreach (var (key, value) in dict)
{
switch (key.ToLowerInvariant())
{
case "cert_file":
mqtt.TlsCert = ToString(value);
break;
case "key_file":
mqtt.TlsKey = ToString(value);
break;
case "ca_file":
mqtt.TlsCaCert = ToString(value);
break;
case "verify":
mqtt.TlsVerify = ToBool(value);
break;
case "verify_and_map":
var map = ToBool(value);
mqtt.TlsMap = map;
if (map) mqtt.TlsVerify = true;
break;
case "timeout":
mqtt.TlsTimeout = ToDouble(value);
break;
case "pinned_certs":
if (value is List<object?> pinnedList)
{
var certs = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
foreach (var item in pinnedList)
{
if (item is string s)
certs.Add(s.ToLowerInvariant());
}
mqtt.TlsPinnedCerts = certs;
}
break;
default:
break;
}
}
}
```
**Step 6: Build to verify compilation**
Run: `dotnet build`
Expected: Build succeeded.
**Step 7: Commit**
```bash
git add src/NATS.Server/MqttOptions.cs src/NATS.Server/NatsOptions.cs src/NATS.Server/Configuration/ConfigProcessor.cs
git commit -m "feat: add mqtt config model and parser for all Go MQTTOpts fields"
```
---
### Task 7: Add MQTT config parsing tests
**Files:**
- Create: `tests/NATS.Server.Tests/TestData/mqtt.conf`
- Modify: `tests/NATS.Server.Tests/ConfigProcessorTests.cs`
**Step 1: Create MQTT test config file**
Create `tests/NATS.Server.Tests/TestData/mqtt.conf`:
```
mqtt {
listen: "10.0.0.1:1883"
no_auth_user: "mqtt_default"
authorization {
user: "mqtt_user"
pass: "mqtt_pass"
token: "mqtt_token"
timeout: 3.0
}
tls {
cert_file: "/path/to/mqtt-cert.pem"
key_file: "/path/to/mqtt-key.pem"
ca_file: "/path/to/mqtt-ca.pem"
verify: true
timeout: 5.0
}
ack_wait: "60s"
max_ack_pending: 2048
js_domain: "mqtt-domain"
js_api_timeout: "10s"
stream_replicas: 3
consumer_replicas: 1
consumer_memory_storage: true
consumer_inactive_threshold: "5m"
}
```
Ensure this file is copied to output: check that `.csproj` has a wildcard for TestData, or add:
```xml
<ItemGroup>
<None Update="TestData\**" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
```
**Step 2: Add MQTT config tests**
Add to `tests/NATS.Server.Tests/ConfigProcessorTests.cs`:
```csharp
// ─── MQTT config ────────────────────────────────────────────
[Fact]
public void MqttConf_ListenHostAndPort()
{
var opts = ConfigProcessor.ProcessConfigFile(TestDataPath("mqtt.conf"));
opts.Mqtt.ShouldNotBeNull();
opts.Mqtt!.Host.ShouldBe("10.0.0.1");
opts.Mqtt.Port.ShouldBe(1883);
}
[Fact]
public void MqttConf_NoAuthUser()
{
var opts = ConfigProcessor.ProcessConfigFile(TestDataPath("mqtt.conf"));
opts.Mqtt.ShouldNotBeNull();
opts.Mqtt!.NoAuthUser.ShouldBe("mqtt_default");
}
[Fact]
public void MqttConf_Authorization()
{
var opts = ConfigProcessor.ProcessConfigFile(TestDataPath("mqtt.conf"));
opts.Mqtt.ShouldNotBeNull();
opts.Mqtt!.Username.ShouldBe("mqtt_user");
opts.Mqtt.Password.ShouldBe("mqtt_pass");
opts.Mqtt.Token.ShouldBe("mqtt_token");
opts.Mqtt.AuthTimeout.ShouldBe(3.0);
}
[Fact]
public void MqttConf_Tls()
{
var opts = ConfigProcessor.ProcessConfigFile(TestDataPath("mqtt.conf"));
opts.Mqtt.ShouldNotBeNull();
opts.Mqtt!.TlsCert.ShouldBe("/path/to/mqtt-cert.pem");
opts.Mqtt.TlsKey.ShouldBe("/path/to/mqtt-key.pem");
opts.Mqtt.TlsCaCert.ShouldBe("/path/to/mqtt-ca.pem");
opts.Mqtt.TlsVerify.ShouldBeTrue();
opts.Mqtt.TlsTimeout.ShouldBe(5.0);
opts.Mqtt.HasTls.ShouldBeTrue();
}
[Fact]
public void MqttConf_QosSettings()
{
var opts = ConfigProcessor.ProcessConfigFile(TestDataPath("mqtt.conf"));
opts.Mqtt.ShouldNotBeNull();
opts.Mqtt!.AckWait.ShouldBe(TimeSpan.FromSeconds(60));
opts.Mqtt.MaxAckPending.ShouldBe((ushort)2048);
opts.Mqtt.JsApiTimeout.ShouldBe(TimeSpan.FromSeconds(10));
}
[Fact]
public void MqttConf_JetStreamSettings()
{
var opts = ConfigProcessor.ProcessConfigFile(TestDataPath("mqtt.conf"));
opts.Mqtt.ShouldNotBeNull();
opts.Mqtt!.JsDomain.ShouldBe("mqtt-domain");
opts.Mqtt.StreamReplicas.ShouldBe(3);
opts.Mqtt.ConsumerReplicas.ShouldBe(1);
opts.Mqtt.ConsumerMemoryStorage.ShouldBeTrue();
opts.Mqtt.ConsumerInactiveThreshold.ShouldBe(TimeSpan.FromMinutes(5));
}
[Fact]
public void MqttConf_MaxAckPendingValidation_ReportsError()
{
var ex = Should.Throw<ConfigProcessorException>(() =>
ConfigProcessor.ProcessConfig("""
mqtt {
max_ack_pending: 70000
}
"""));
ex.Errors.ShouldContain(e => e.Contains("max_ack_pending"));
}
[Fact]
public void MqttConf_Aliases()
{
// Test alias keys: "ackwait" (alias for "ack_wait"), "net" (alias for "host"),
// "max_inflight" (alias for "max_ack_pending"), "consumer_auto_cleanup" (alias)
var opts = ConfigProcessor.ProcessConfig("""
mqtt {
net: "127.0.0.1"
port: 1884
ackwait: "45s"
max_inflight: 500
api_timeout: "8s"
consumer_auto_cleanup: "10m"
}
""");
opts.Mqtt.ShouldNotBeNull();
opts.Mqtt!.Host.ShouldBe("127.0.0.1");
opts.Mqtt.Port.ShouldBe(1884);
opts.Mqtt.AckWait.ShouldBe(TimeSpan.FromSeconds(45));
opts.Mqtt.MaxAckPending.ShouldBe((ushort)500);
opts.Mqtt.JsApiTimeout.ShouldBe(TimeSpan.FromSeconds(8));
opts.Mqtt.ConsumerInactiveThreshold.ShouldBe(TimeSpan.FromMinutes(10));
}
[Fact]
public void MqttConf_Absent_ReturnsNull()
{
var opts = ConfigProcessor.ProcessConfig("port: 4222");
opts.Mqtt.ShouldBeNull();
}
```
**Step 3: Run MQTT config tests**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~ConfigProcessorTests.MqttConf" -v minimal`
Expected: PASS.
**Step 4: Commit**
```bash
git add tests/NATS.Server.Tests/TestData/mqtt.conf tests/NATS.Server.Tests/ConfigProcessorTests.cs
git commit -m "test: add mqtt config parsing coverage"
```
---
### Task 8: Expand MqttOptsVarz and wire into /varz
**Files:**
- Modify: `src/NATS.Server/Monitoring/Varz.cs` (lines 350-360: expand `MqttOptsVarz`)
- Modify: `src/NATS.Server/Monitoring/VarzHandler.cs` (line 67-124: populate MQTT block from options)
**Step 1: Expand `MqttOptsVarz` class**
In `src/NATS.Server/Monitoring/Varz.cs`, replace the existing minimal `MqttOptsVarz` (lines 350-360) with the full Go-compatible struct (matching Go server/monitor.go:1365-1378):
```csharp
/// <summary>
/// MQTT configuration monitoring information.
/// Corresponds to Go server/monitor.go MQTTOptsVarz struct.
/// </summary>
public sealed class MqttOptsVarz
{
[JsonPropertyName("host")]
public string Host { get; set; } = "";
[JsonPropertyName("port")]
public int Port { get; set; }
[JsonPropertyName("no_auth_user")]
public string NoAuthUser { get; set; } = "";
[JsonPropertyName("auth_timeout")]
public double AuthTimeout { get; set; }
[JsonPropertyName("tls_map")]
public bool TlsMap { get; set; }
[JsonPropertyName("tls_timeout")]
public double TlsTimeout { get; set; }
[JsonPropertyName("tls_pinned_certs")]
public string[] TlsPinnedCerts { get; set; } = [];
[JsonPropertyName("js_domain")]
public string JsDomain { get; set; } = "";
[JsonPropertyName("ack_wait")]
public long AckWait { get; set; }
[JsonPropertyName("max_ack_pending")]
public ushort MaxAckPending { get; set; }
}
```
Note: Go's `AckWait` is serialized as `time.Duration` (nanoseconds as int64). We follow the same pattern used for `PingInterval` and `WriteDeadline` in the existing Varz class.
**Step 2: Populate MQTT block in VarzHandler**
In `src/NATS.Server/Monitoring/VarzHandler.cs`, add MQTT population to the `return new Varz { ... }` block (around line 123, after `HttpReqStats`):
```csharp
Mqtt = BuildMqttVarz(),
```
And add the helper method to `VarzHandler`:
```csharp
private MqttOptsVarz BuildMqttVarz()
{
var mqtt = _options.Mqtt;
if (mqtt is null)
return new MqttOptsVarz();
return new MqttOptsVarz
{
Host = mqtt.Host,
Port = mqtt.Port,
NoAuthUser = mqtt.NoAuthUser ?? "",
AuthTimeout = mqtt.AuthTimeout,
TlsMap = mqtt.TlsMap,
TlsTimeout = mqtt.TlsTimeout,
TlsPinnedCerts = mqtt.TlsPinnedCerts?.ToArray() ?? [],
JsDomain = mqtt.JsDomain ?? "",
AckWait = (long)mqtt.AckWait.TotalNanoseconds,
MaxAckPending = mqtt.MaxAckPending,
};
}
```
**Step 3: Build to verify compilation**
Run: `dotnet build`
Expected: Build succeeded.
**Step 4: Add varz MQTT test**
In `tests/NATS.Server.Tests/MonitorTests.cs`, add a test that verifies the MQTT section appears in `/varz` response. If there's an existing varz test pattern, follow it. Otherwise add:
```csharp
[Fact]
public async Task Varz_includes_mqtt_config_when_set()
{
// Start server with monitoring enabled and mqtt config set.
// GET /varz.
// Assert response contains "mqtt" block with expected host/port values.
}
```
The exact test implementation depends on how the existing varz tests create and query the server — follow the existing pattern in MonitorTests.cs.
**Step 5: Run full test suite**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj -v minimal`
Expected: PASS.
**Step 6: Commit**
```bash
git add src/NATS.Server/Monitoring/Varz.cs src/NATS.Server/Monitoring/VarzHandler.cs tests/NATS.Server.Tests/MonitorTests.cs
git commit -m "feat: expand mqtt varz monitoring with all Go-compatible fields"
```
---
### Task 9: Final verification and differences.md update
**Files:**
- Modify: `differences.md`
**Step 1: Run full test suite**
Run: `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj -v minimal`
Expected: PASS (all tests green, no regressions).
**Step 2: Update parity document**
Edit `differences.md`:
1. In the **Connection Types** table (section 2), update the MQTT row:
```markdown
| MQTT clients | Y | Partial | JWT connection-type constants + config parsing; no MQTT transport yet |
```
2. In the **Connz Response** table (section 7), update the MQTT client ID filtering row:
```markdown
| MQTT client ID filtering | Y | Y | `mqtt_client` query param filters open and closed connections |
```
3. In the **Missing Options Categories** (section 6), replace the "WebSocket/MQTT options" line:
```markdown
- WebSocket options
- ~~MQTT options~~ — `mqtt {}` config block parsed with all Go `MQTTOpts` fields; no listener yet
```
4. In the **Auth Mechanisms** table (section 5), add note to JWT row:
```markdown
| JWT validation | Y | Y | ... + `allowed_connection_types` enforcement with Go-compatible semantics |
```
**Step 3: Commit docs update**
```bash
git add differences.md
git commit -m "docs: update differences.md for mqtt connection type parity"
```

15
docs/plans/2026-02-23-mqtt-connection-type-plan.md.tasks.json Normal file
View File

@@ -0,0 +1,15 @@
{
"planPath": "docs/plans/2026-02-23-mqtt-connection-type-plan.md",
"tasks": [
{"id": 2, "subject": "Task 1: Add failing JWT connection-type behavior tests", "status": "pending"},
{"id": 3, "subject": "Task 2: Implement auth connection-type model and Go-style conversion", "status": "pending", "blockedBy": [2]},
{"id": 4, "subject": "Task 3: Add failing connz mqtt_client filter tests", "status": "pending", "blockedBy": [3]},
{"id": 5, "subject": "Task 4: Implement connz mqtt_client filtering", "status": "pending", "blockedBy": [4]},
{"id": 6, "subject": "Task 5: Verification checkpoint for JWT + connz tasks", "status": "pending", "blockedBy": [5]},
{"id": 7, "subject": "Task 6: Add MqttOptions model and config parsing", "status": "pending", "blockedBy": [6]},
{"id": 8, "subject": "Task 7: Add MQTT config parsing tests", "status": "pending", "blockedBy": [7]},
{"id": 9, "subject": "Task 8: Expand MqttOptsVarz and wire into /varz", "status": "pending", "blockedBy": [8]},
{"id": 10, "subject": "Task 9: Final verification and differences.md update", "status": "pending", "blockedBy": [9]}
],
"lastUpdated": "2026-02-23T00:00:00Z"
}