feat(sessions): replay-on-reconnect with ReplayGap sentinel

2026-06-16 07:22:19 -04:00
parent 042f5e3d82
commit 36ab8d15f1
7 changed files with 736 additions and 29 deletions
@@ -572,6 +572,110 @@ public sealed class SessionEventDistributorTests
            "isOnlySubscriber must be true for a lone external subscriber in single-subscriber mode.");
    }

+    [Fact]
+    public async Task RegisterWithReplay_WithinRetainedWindow_ReturnsNewerEvents_NoGap_ThenLive()
+    {
+        Channel<MxEvent> source = Channel.CreateUnbounded<MxEvent>();
+        await using SessionEventDistributor distributor = CreateDistributor(
+            source.Reader,
+            replayBufferCapacity: 10,
+            replayRetentionSeconds: 0);
+        await distributor.StartAsync(CancellationToken.None);
+
+        // A primer subscriber forces the pump to retain events 1..5 deterministically.
+        using IEventSubscriberLease primer = distributor.Register();
+        for (ulong sequence = 1; sequence <= 5; sequence++)
+        {
+            source.Writer.TryWrite(Event(sequence));
+            _ = await ReadOneAsync(primer.Reader);
+        }
+
+        // Resume after sequence 2: retained window [1..5] still covers it — no gap, replay 3..5.
+        using IEventSubscriberLease resume = distributor.RegisterWithReplay(
+            2,
+            out IReadOnlyList<MxEvent> replay,
+            out bool gap,
+            out ulong oldestAvailable,
+            out ulong liveResume);
+
+        Assert.False(gap);
+        Assert.Equal(new ulong[] { 3, 4, 5 }, replay.Select(e => e.WorkerSequence));
+        Assert.Equal(5ul, liveResume);
+        Assert.Equal(1ul, oldestAvailable);
+
+        // A subsequent live event flows to the resumed subscriber's channel.
+        source.Writer.TryWrite(Event(6));
+        MxEvent live = await ReadOneAsync(resume.Reader);
+        Assert.Equal(6ul, live.WorkerSequence);
+    }
+
+    [Fact]
+    public async Task RegisterWithReplay_BelowOldestRetained_ReportsGap_AndOldestAvailable()
+    {
+        Channel<MxEvent> source = Channel.CreateUnbounded<MxEvent>();
+        await using SessionEventDistributor distributor = CreateDistributor(
+            source.Reader,
+            replayBufferCapacity: 3,
+            replayRetentionSeconds: 0);
+        await distributor.StartAsync(CancellationToken.None);
+
+        using IEventSubscriberLease primer = distributor.Register();
+        for (ulong sequence = 1; sequence <= 5; sequence++)
+        {
+            source.Writer.TryWrite(Event(sequence));
+            _ = await ReadOneAsync(primer.Reader);
+        }
+
+        // Capacity 3 retains 3,4,5; events 1,2 were evicted. Resume after 0 => gap, oldest=3.
+        using IEventSubscriberLease resume = distributor.RegisterWithReplay(
+            0,
+            out IReadOnlyList<MxEvent> replay,
+            out bool gap,
+            out ulong oldestAvailable,
+            out ulong liveResume);
+
+        Assert.True(gap);
+        Assert.Equal(3ul, oldestAvailable);
+        Assert.Equal(new ulong[] { 3, 4, 5 }, replay.Select(e => e.WorkerSequence));
+        Assert.Equal(5ul, liveResume);
+    }
+
+    [Fact]
+    public async Task RegisterWithReplay_NothingRetainedNewer_LiveResumeEqualsAfterSequence_NoGap()
+    {
+        Channel<MxEvent> source = Channel.CreateUnbounded<MxEvent>();
+        await using SessionEventDistributor distributor = CreateDistributor(
+            source.Reader,
+            replayBufferCapacity: 10,
+            replayRetentionSeconds: 0);
+        await distributor.StartAsync(CancellationToken.None);
+
+        using IEventSubscriberLease primer = distributor.Register();
+        for (ulong sequence = 1; sequence <= 3; sequence++)
+        {
+            source.Writer.TryWrite(Event(sequence));
+            _ = await ReadOneAsync(primer.Reader);
+        }
+
+        // Resume after 3 (newest retained): nothing newer, fully caught up — no gap, empty
+        // replay, and the live filter resumes after the requested watermark unchanged.
+        using IEventSubscriberLease resume = distributor.RegisterWithReplay(
+            3,
+            out IReadOnlyList<MxEvent> replay,
+            out bool gap,
+            out ulong oldestAvailable,
+            out ulong liveResume);
+
+        Assert.False(gap);
+        Assert.Empty(replay);
+        Assert.Equal(3ul, liveResume);
+        Assert.Equal(1ul, oldestAvailable);
+
+        source.Writer.TryWrite(Event(4));
+        MxEvent live = await ReadOneAsync(resume.Reader);
+        Assert.Equal(4ul, live.WorkerSequence);
+    }
+
    private static async Task DrainUntilFaultAsync(ChannelReader<MxEvent> reader)
    {
        // Drains any buffered events, then surfaces the channel's completion fault (if any)