feat: add cluster-aware pending request tracking for pull consumers (Gap 3.14)
Adds ProposeWaitingRequest, RegisterClusterPending, RemoveClusterPending, GetClusterPendingRequests, and ClusterPendingCount to PullConsumerEngine, backed by a ConcurrentDictionary keyed by reply subject. Includes 10 xUnit tests covering quorum checks, pending tracking, and concurrent access patterns.
This commit is contained in:
Joseph Doherty
@@ -1,3 +1,5 @@
|
||||
using System.Collections.Concurrent;
|
||||
using NATS.Server.JetStream.Cluster;
|
||||
using NATS.Server.JetStream.Storage;
|
||||
using NATS.Server.JetStream.Models;
|
||||
using NATS.Server.Subscriptions;
|
||||
@@ -93,6 +95,60 @@ public sealed class CompiledFilter
|
||||
|
||||
public sealed class PullConsumerEngine
|
||||
{
|
||||
// Go: consumer.go — cluster-wide pending pull request tracking keyed by reply subject.
|
||||
// Reference: golang/nats-server/server/consumer.go waitingRequestsPending / proposeWaitingRequest
|
||||
private readonly ConcurrentDictionary<string, PullWaitingRequest> _clusterPending =
|
||||
new(StringComparer.Ordinal);
|
||||
|
||||
/// <summary>
|
||||
/// Number of pending pull requests currently tracked across the cluster.
|
||||
/// Go reference: consumer.go — cluster pending count (waitingRequestsPending).
|
||||
/// </summary>
|
||||
public int ClusterPendingCount => _clusterPending.Count;
|
||||
|
||||
/// <summary>
|
||||
/// Proposes a waiting pull request through the consumer's RAFT group.
|
||||
/// Returns true if quorum is available and the request was registered; false otherwise.
|
||||
/// Go reference: consumer.go proposeWaitingRequest — propose via consumer RAFT group.
|
||||
/// </summary>
|
||||
public bool ProposeWaitingRequest(PullWaitingRequest request, RaftGroup group)
|
||||
{
|
||||
if (!group.HasQuorum(group.Peers.Count))
|
||||
return false;
|
||||
|
||||
var replyKey = request.Reply ?? string.Empty;
|
||||
_clusterPending[replyKey] = request;
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Registers a pull request in the cluster pending tracker, keyed by reply subject.
|
||||
/// Go reference: consumer.go — cluster pending registration on proposal acceptance.
|
||||
/// </summary>
|
||||
public void RegisterClusterPending(PullWaitingRequest request)
|
||||
{
|
||||
var replyKey = request.Reply ?? string.Empty;
|
||||
_clusterPending[replyKey] = request;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Removes and returns a pending pull request by its reply subject.
|
||||
/// Returns null if no request is registered for that reply subject.
|
||||
/// Go reference: consumer.go — cluster pending removal on fulfillment or expiry.
|
||||
/// </summary>
|
||||
public PullWaitingRequest? RemoveClusterPending(string replySubject)
|
||||
{
|
||||
_clusterPending.TryRemove(replySubject, out var request);
|
||||
return request;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Returns all currently pending pull requests tracked across the cluster.
|
||||
/// Go reference: consumer.go — enumerate waitingRequestsPending for expiry sweep.
|
||||
/// </summary>
|
||||
public IReadOnlyCollection<PullWaitingRequest> GetClusterPendingRequests()
|
||||
=> _clusterPending.Values.ToArray();
|
||||
|
||||
public async ValueTask<PullFetchBatch> FetchAsync(StreamHandle stream, ConsumerHandle consumer, int batch, CancellationToken ct)
|
||||
=> await FetchAsync(stream, consumer, new PullFetchRequest { Batch = batch }, ct);
|
||||
|
||||
|
||||
@@ -0,0 +1,198 @@
|
||||
using NATS.Server.JetStream.Consumers;
|
||||
using NATS.Server.JetStream.Cluster;
|
||||
using Shouldly;
|
||||
|
||||
namespace NATS.Server.Tests.JetStream.Consumers;
|
||||
|
||||
/// <summary>
|
||||
/// Tests for cluster-aware pending pull request tracking in PullConsumerEngine.
|
||||
/// Go reference: consumer.go proposeWaitingRequest / waitingRequestsPending — cluster-wide
|
||||
/// pending pull request coordination via the consumer RAFT group.
|
||||
/// golang/nats-server/server/consumer.go proposeWaitingRequest
|
||||
/// </summary>
|
||||
public class ClusterPendingRequestTests
|
||||
{
|
||||
// ---------------------------------------------------------------
|
||||
// ProposeWaitingRequest
|
||||
// ---------------------------------------------------------------
|
||||
|
||||
[Fact]
|
||||
public void ProposeWaitingRequest_with_quorum_returns_true()
|
||||
{
|
||||
// Go: consumer.go proposeWaitingRequest — only propose when quorum available.
|
||||
var engine = new PullConsumerEngine();
|
||||
var group = new RaftGroup
|
||||
{
|
||||
Name = "test-group",
|
||||
Peers = ["peer-1", "peer-2", "peer-3"],
|
||||
};
|
||||
var request = new PullWaitingRequest { Batch = 10, Reply = "reply.test.1" };
|
||||
|
||||
var result = engine.ProposeWaitingRequest(request, group);
|
||||
|
||||
result.ShouldBeTrue();
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ProposeWaitingRequest_without_quorum_returns_false()
|
||||
{
|
||||
// Go: consumer.go proposeWaitingRequest — no quorum (0 peers means quorum = 1, but 0 < 1).
|
||||
var engine = new PullConsumerEngine();
|
||||
var group = new RaftGroup
|
||||
{
|
||||
Name = "empty-group",
|
||||
Peers = [],
|
||||
};
|
||||
var request = new PullWaitingRequest { Batch = 5, Reply = "reply.noquorum" };
|
||||
|
||||
var result = engine.ProposeWaitingRequest(request, group);
|
||||
|
||||
result.ShouldBeFalse();
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ProposeWaitingRequest_registers_in_cluster_pending()
|
||||
{
|
||||
// Go: consumer.go — after a successful proposal, the request must appear in the
|
||||
// cluster pending map so it can be fulfilled or expired.
|
||||
var engine = new PullConsumerEngine();
|
||||
var group = new RaftGroup
|
||||
{
|
||||
Name = "test-group",
|
||||
Peers = ["peer-1", "peer-2", "peer-3"],
|
||||
};
|
||||
var request = new PullWaitingRequest { Batch = 4, Reply = "reply.reg" };
|
||||
|
||||
engine.ProposeWaitingRequest(request, group);
|
||||
|
||||
var pending = engine.GetClusterPendingRequests();
|
||||
pending.ShouldContain(r => r.Reply == "reply.reg");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Multiple_proposals_tracked_independently()
|
||||
{
|
||||
// Go: consumer.go — each reply subject is an independent pending slot;
|
||||
// proposals with different reply subjects must not overwrite each other.
|
||||
var engine = new PullConsumerEngine();
|
||||
var group = new RaftGroup
|
||||
{
|
||||
Name = "test-group",
|
||||
Peers = ["peer-1", "peer-2", "peer-3"],
|
||||
};
|
||||
|
||||
engine.ProposeWaitingRequest(new PullWaitingRequest { Batch = 1, Reply = "reply.A" }, group);
|
||||
engine.ProposeWaitingRequest(new PullWaitingRequest { Batch = 2, Reply = "reply.B" }, group);
|
||||
engine.ProposeWaitingRequest(new PullWaitingRequest { Batch = 3, Reply = "reply.C" }, group);
|
||||
|
||||
engine.ClusterPendingCount.ShouldBe(3);
|
||||
var pending = engine.GetClusterPendingRequests();
|
||||
pending.ShouldContain(r => r.Reply == "reply.A" && r.Batch == 1);
|
||||
pending.ShouldContain(r => r.Reply == "reply.B" && r.Batch == 2);
|
||||
pending.ShouldContain(r => r.Reply == "reply.C" && r.Batch == 3);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------
|
||||
// ClusterPendingCount
|
||||
// ---------------------------------------------------------------
|
||||
|
||||
[Fact]
|
||||
public void ClusterPendingCount_tracks_pending_requests()
|
||||
{
|
||||
// Go: consumer.go — ClusterPendingCount reflects the current size of the pending map.
|
||||
var engine = new PullConsumerEngine();
|
||||
engine.ClusterPendingCount.ShouldBe(0);
|
||||
|
||||
engine.RegisterClusterPending(new PullWaitingRequest { Batch = 1, Reply = "r1" });
|
||||
engine.RegisterClusterPending(new PullWaitingRequest { Batch = 2, Reply = "r2" });
|
||||
engine.RegisterClusterPending(new PullWaitingRequest { Batch = 3, Reply = "r3" });
|
||||
|
||||
engine.ClusterPendingCount.ShouldBe(3);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ClusterPendingCount_decrements_on_remove()
|
||||
{
|
||||
// Go: consumer.go — removing a request via reply subject decrements the pending count.
|
||||
var engine = new PullConsumerEngine();
|
||||
engine.RegisterClusterPending(new PullWaitingRequest { Batch = 5, Reply = "decrement.reply" });
|
||||
engine.ClusterPendingCount.ShouldBe(1);
|
||||
|
||||
engine.RemoveClusterPending("decrement.reply");
|
||||
|
||||
engine.ClusterPendingCount.ShouldBe(0);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------
|
||||
// RegisterClusterPending
|
||||
// ---------------------------------------------------------------
|
||||
|
||||
[Fact]
|
||||
public void RegisterClusterPending_adds_request_by_reply()
|
||||
{
|
||||
// Go: consumer.go — pending requests are keyed by reply subject for O(1) lookup.
|
||||
var engine = new PullConsumerEngine();
|
||||
var request = new PullWaitingRequest { Batch = 7, Reply = "register.reply.subject" };
|
||||
|
||||
engine.RegisterClusterPending(request);
|
||||
|
||||
var retrieved = engine.RemoveClusterPending("register.reply.subject");
|
||||
retrieved.ShouldNotBeNull();
|
||||
retrieved.Batch.ShouldBe(7);
|
||||
retrieved.Reply.ShouldBe("register.reply.subject");
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------
|
||||
// RemoveClusterPending
|
||||
// ---------------------------------------------------------------
|
||||
|
||||
[Fact]
|
||||
public void RemoveClusterPending_returns_and_removes_request()
|
||||
{
|
||||
// Go: consumer.go — RemoveClusterPending both returns the request and removes it
|
||||
// from the map so it is not fulfilled twice.
|
||||
var engine = new PullConsumerEngine();
|
||||
engine.RegisterClusterPending(new PullWaitingRequest { Batch = 3, Reply = "remove.me" });
|
||||
|
||||
var removed = engine.RemoveClusterPending("remove.me");
|
||||
|
||||
removed.ShouldNotBeNull();
|
||||
removed.Reply.ShouldBe("remove.me");
|
||||
engine.ClusterPendingCount.ShouldBe(0);
|
||||
// Second removal should return null — the entry is gone.
|
||||
engine.RemoveClusterPending("remove.me").ShouldBeNull();
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void RemoveClusterPending_returns_null_for_unknown()
|
||||
{
|
||||
// Go: consumer.go — attempting to remove an unknown reply subject is a no-op.
|
||||
var engine = new PullConsumerEngine();
|
||||
|
||||
var result = engine.RemoveClusterPending("does.not.exist");
|
||||
|
||||
result.ShouldBeNull();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------
|
||||
// GetClusterPendingRequests
|
||||
// ---------------------------------------------------------------
|
||||
|
||||
[Fact]
|
||||
public void GetClusterPendingRequests_returns_all_pending()
|
||||
{
|
||||
// Go: consumer.go — GetClusterPendingRequests is used for expiry sweeps and
|
||||
// diagnostics; it must return every currently pending request.
|
||||
var engine = new PullConsumerEngine();
|
||||
engine.RegisterClusterPending(new PullWaitingRequest { Batch = 1, Reply = "bulk.a" });
|
||||
engine.RegisterClusterPending(new PullWaitingRequest { Batch = 2, Reply = "bulk.b" });
|
||||
engine.RegisterClusterPending(new PullWaitingRequest { Batch = 3, Reply = "bulk.c" });
|
||||
|
||||
var all = engine.GetClusterPendingRequests();
|
||||
|
||||
all.Count.ShouldBe(3);
|
||||
all.Select(r => r.Reply).ShouldContain("bulk.a");
|
||||
all.Select(r => r.Reply).ShouldContain("bulk.b");
|
||||
all.Select(r => r.Reply).ShouldContain("bulk.c");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user