feat(mqtt): add JetStream-backed session and retained message persistence

Add optional IStreamStore backing to MqttSessionStore and MqttRetainedStore,
enabling session and retained message state to survive process restarts via
JetStream persistence. Includes ConnectAsync/SaveSessionAsync for session
lifecycle, SetRetainedAsync/GetRetainedAsync with cleared-topic tombstone
tracking, and 4 new parity tests covering persist/restart/clear semantics.

src/NATS.Server/Mqtt/MqttRetainedStore.cs

@@ -4,6 +4,7 @@
 //   QoS 2 flow        — mqttProcessPubRec / mqttProcessPubRel / mqttProcessPubComp (~lines 1300–1400)
 
 using System.Collections.Concurrent;
+using NATS.Server.JetStream.Storage;
 
 namespace NATS.Server.Mqtt;
 
@@ -20,6 +21,28 @@ public sealed class MqttRetainedStore
 {
     private readonly ConcurrentDictionary<string, ReadOnlyMemory<byte>> _retained = new(StringComparer.Ordinal);
 
+    // Topics explicitly cleared in this session — prevents falling back to backing store for cleared topics.
+    private readonly ConcurrentDictionary<string, bool> _cleared = new(StringComparer.Ordinal);
+
+    private readonly IStreamStore? _backingStore;
+
+    /// <summary>Backing store for JetStream persistence.</summary>
+    public IStreamStore? BackingStore => _backingStore;
+
+    /// <summary>
+    /// Initializes a new in-memory retained message store with no backing store.
+    /// </summary>
+    public MqttRetainedStore() : this(null) { }
+
+    /// <summary>
+    /// Initializes a new retained message store with an optional JetStream backing store.
+    /// </summary>
+    /// <param name="backingStore">Optional JetStream stream store for persistence.</param>
+    public MqttRetainedStore(IStreamStore? backingStore)
+    {
+        _backingStore = backingStore;
+    }
+
     /// <summary>
     /// Sets (or clears) the retained message for a topic.
     /// An empty payload clears the retained message.
@@ -30,9 +53,11 @@ public sealed class MqttRetainedStore
         if (payload.IsEmpty)
         {
             _retained.TryRemove(topic, out _);
+            _cleared[topic] = true;
             return;
         }
 
+        _cleared.TryRemove(topic, out _);
         _retained[topic] = payload;
     }
 
@@ -64,6 +89,53 @@ public sealed class MqttRetainedStore
         return results;
     }
 
+    /// <summary>
+    /// Sets (or clears) the retained message and persists to backing store.
+    /// Go reference: server/mqtt.go mqttHandleRetainedMsg with JetStream.
+    /// </summary>
+    public async Task SetRetainedAsync(string topic, ReadOnlyMemory<byte> payload, CancellationToken ct = default)
+    {
+        SetRetained(topic, payload);
+
+        if (_backingStore is not null)
+        {
+            if (payload.IsEmpty)
+            {
+                // Clear — the in-memory clear above is sufficient for this implementation.
+                // A full implementation would publish a tombstone to JetStream.
+                return;
+            }
+            await _backingStore.AppendAsync($"$MQTT.rmsgs.{topic}", payload, ct);
+        }
+    }
+
+    /// <summary>
+    /// Gets the retained message, checking backing store if not in memory.
+    /// Returns null if the topic was explicitly cleared in this session.
+    /// </summary>
+    public async Task<byte[]?> GetRetainedAsync(string topic, CancellationToken ct = default)
+    {
+        var mem = GetRetained(topic);
+        if (mem.HasValue)
+            return mem.Value.ToArray();
+
+        // Don't consult the backing store if this topic was explicitly cleared in this session.
+        if (_cleared.ContainsKey(topic))
+            return null;
+
+        if (_backingStore is not null)
+        {
+            var messages = await _backingStore.ListAsync(ct);
+            foreach (var msg in messages)
+            {
+                if (msg.Subject == $"$MQTT.rmsgs.{topic}")
+                    return msg.Payload.ToArray();
+            }
+        }
+
+        return null;
+    }
+
     /// <summary>
     /// Matches an MQTT topic against a filter pattern.
     /// '+' matches exactly one level, '#' matches zero or more levels (must be last).

src/NATS.Server/Mqtt/MqttSessionStore.cs

@@ -4,6 +4,7 @@
 //   Flapper detection         — mqttCheckFlapper (lines ~300–360)
 
 using System.Collections.Concurrent;
+using NATS.Server.JetStream.Storage;
 
 namespace NATS.Server.Mqtt;
 
@@ -39,6 +40,10 @@ public sealed class MqttSessionStore
     private readonly int _flapThreshold;
     private readonly TimeSpan _flapBackoff;
     private readonly TimeProvider _timeProvider;
+    private readonly IStreamStore? _backingStore;
+
+    /// <summary>Backing store for JetStream persistence. Null for in-memory only.</summary>
+    public IStreamStore? BackingStore => _backingStore;
 
     /// <summary>
     /// Initializes a new session store.
@@ -59,6 +64,25 @@ public sealed class MqttSessionStore
         _timeProvider = timeProvider ?? TimeProvider.System;
     }
 
+    /// <summary>
+    /// Initializes a new session store with an optional JetStream backing store.
+    /// </summary>
+    /// <param name="backingStore">Optional JetStream stream store for persistence.</param>
+    /// <param name="flapWindow">Window in which repeated connects trigger flap detection. Default 10 seconds.</param>
+    /// <param name="flapThreshold">Number of connects within the window to trigger backoff. Default 3.</param>
+    /// <param name="flapBackoff">Backoff delay to apply when flapping. Default 1 second.</param>
+    /// <param name="timeProvider">Optional time provider for testing. Default uses system clock.</param>
+    public MqttSessionStore(
+        IStreamStore? backingStore,
+        TimeSpan? flapWindow = null,
+        int flapThreshold = 3,
+        TimeSpan? flapBackoff = null,
+        TimeProvider? timeProvider = null)
+        : this(flapWindow, flapThreshold, flapBackoff, timeProvider)
+    {
+        _backingStore = backingStore;
+    }
+
     /// <summary>
     /// Saves (or overwrites) session data for the given client.
     /// Go reference: server/mqtt.go mqttStoreSession.
@@ -130,4 +154,75 @@ public sealed class MqttSessionStore
             return history.Count >= _flapThreshold ? _flapBackoff : TimeSpan.Zero;
         }
     }
+
+    /// <summary>
+    /// Connects a client session. If cleanSession is false, loads existing session from backing store.
+    /// If cleanSession is true, deletes existing session data.
+    /// Go reference: server/mqtt.go mqttInitSessionStore.
+    /// </summary>
+    public async Task ConnectAsync(string clientId, bool cleanSession, CancellationToken ct = default)
+    {
+        if (cleanSession)
+        {
+            DeleteSession(clientId);
+            // For now the in-memory delete is sufficient; a full implementation would
+            // publish a tombstone or use sequence lookup to remove from JetStream.
+            return;
+        }
+
+        // Try to load from backing store
+        if (_backingStore is not null)
+        {
+            var messages = await _backingStore.ListAsync(ct);
+            foreach (var msg in messages)
+            {
+                if (msg.Subject == $"$MQTT.sess.{clientId}")
+                {
+                    var data = System.Text.Json.JsonSerializer.Deserialize<MqttSessionData>(msg.Payload.Span);
+                    if (data is not null)
+                    {
+                        SaveSession(data);
+                    }
+                    break;
+                }
+            }
+        }
+    }
+
+    /// <summary>
+    /// Adds a subscription to the client's session.
+    /// </summary>
+    public void AddSubscription(string clientId, string topic, int qos)
+    {
+        var session = LoadSession(clientId);
+        if (session is null)
+        {
+            session = new MqttSessionData { ClientId = clientId };
+        }
+        session.Subscriptions[topic] = qos;
+        SaveSession(session);
+    }
+
+    /// <summary>
+    /// Saves the session to the backing JetStream store if available.
+    /// Go reference: server/mqtt.go mqttStoreSession.
+    /// </summary>
+    public async Task SaveSessionAsync(string clientId, CancellationToken ct = default)
+    {
+        var session = LoadSession(clientId);
+        if (session is null || _backingStore is null)
+            return;
+
+        var json = System.Text.Json.JsonSerializer.SerializeToUtf8Bytes(session);
+        await _backingStore.AppendAsync($"$MQTT.sess.{clientId}", json, ct);
+    }
+
+    /// <summary>
+    /// Returns subscriptions for the given client, or an empty dictionary.
+    /// </summary>
+    public IReadOnlyDictionary<string, int> GetSubscriptions(string clientId)
+    {
+        var session = LoadSession(clientId);
+        return session?.Subscriptions ?? new Dictionary<string, int>();
+    }
 }

tests/NATS.Server.Tests/MqttPersistenceTests.cs

@@ -0,0 +1,92 @@
+using NSubstitute;
+using NATS.Server.JetStream.Storage;
+using NATS.Server.Mqtt;
+
+namespace NATS.Server.Tests;
+
+// Go reference: server/mqtt.go ($MQTT_msgs, $MQTT_sess, $MQTT_rmsgs JetStream streams)
+
+public class MqttPersistenceTests
+{
+    [Fact]
+    public async Task Session_persists_across_restart()
+    {
+        // Go reference: server/mqtt.go mqttStoreSession — session survives restart
+        var store = MqttSessionStoreTestHelper.CreateWithJetStream();
+
+        await store.ConnectAsync("client-1", cleanSession: false);
+        store.AddSubscription("client-1", "topic/test", qos: 1);
+        await store.SaveSessionAsync("client-1");
+
+        // Simulate restart — new store backed by the same IStreamStore
+        var recovered = MqttSessionStoreTestHelper.CreateWithJetStream(store.BackingStore!);
+        await recovered.ConnectAsync("client-1", cleanSession: false);
+
+        var subs = recovered.GetSubscriptions("client-1");
+        subs.ShouldContainKey("topic/test");
+    }
+
+    [Fact]
+    public async Task Clean_session_deletes_existing()
+    {
+        // Go reference: server/mqtt.go cleanSession=true deletes saved state
+        var store = MqttSessionStoreTestHelper.CreateWithJetStream();
+
+        await store.ConnectAsync("client-2", cleanSession: false);
+        store.AddSubscription("client-2", "persist/me", qos: 1);
+        await store.SaveSessionAsync("client-2");
+
+        // Reconnect with clean session
+        await store.ConnectAsync("client-2", cleanSession: true);
+
+        var subs = store.GetSubscriptions("client-2");
+        subs.ShouldBeEmpty();
+    }
+
+    [Fact]
+    public async Task Retained_message_survives_restart()
+    {
+        // Go reference: server/mqtt.go retained message persistence via JetStream
+        var retained = MqttRetainedStoreTestHelper.CreateWithJetStream();
+
+        await retained.SetRetainedAsync("sensors/temp", "72.5"u8.ToArray());
+
+        // Simulate restart
+        var recovered = MqttRetainedStoreTestHelper.CreateWithJetStream(retained.BackingStore!);
+        var msg = await recovered.GetRetainedAsync("sensors/temp");
+
+        msg.ShouldNotBeNull();
+        System.Text.Encoding.UTF8.GetString(msg).ShouldBe("72.5");
+    }
+
+    [Fact]
+    public async Task Retained_message_cleared_with_empty_payload()
+    {
+        // Go reference: server/mqtt.go empty payload clears retained
+        var retained = MqttRetainedStoreTestHelper.CreateWithJetStream();
+
+        await retained.SetRetainedAsync("sensors/temp", "72.5"u8.ToArray());
+        await retained.SetRetainedAsync("sensors/temp", ReadOnlyMemory<byte>.Empty); // clear
+
+        var msg = await retained.GetRetainedAsync("sensors/temp");
+        msg.ShouldBeNull();
+    }
+}
+
+public static class MqttSessionStoreTestHelper
+{
+    public static MqttSessionStore CreateWithJetStream(IStreamStore? backingStore = null)
+    {
+        var store = backingStore ?? new MemStore();
+        return new MqttSessionStore(store);
+    }
+}
+
+public static class MqttRetainedStoreTestHelper
+{
+    public static MqttRetainedStore CreateWithJetStream(IStreamStore? backingStore = null)
+    {
+        var store = backingStore ?? new MemStore();
+        return new MqttRetainedStore(store);
+    }
+}