diff --git a/src/GameCult.Mesh/CultMeshSnapshots.cs b/src/GameCult.Mesh/CultMeshSnapshots.cs
index 5b01c8b2..8926ec50 100644
--- a/src/GameCult.Mesh/CultMeshSnapshots.cs
+++ b/src/GameCult.Mesh/CultMeshSnapshots.cs
@@ -1,6 +1,7 @@
using System;
using System.Collections.Generic;
using System.Linq;
+using System.Threading;
using System.Threading.Tasks;
using GameCult.Caching;
using GameCult.Caching.MessagePack;
@@ -60,6 +61,133 @@ namespace GameCult.Mesh
public long RudpResendDelayMs { get; set; } = 25;
}
+ ///
+ /// Reuses one connected CultNet schema client for an ordered sequence of snapshot requests.
+ ///
+ public sealed class CultMeshSnapshotSession : IDisposable
+ {
+ private readonly string _endpoint;
+ private readonly CultMeshSnapshotRequestOptions _defaults;
+ private readonly ICultNetSchemaClient _client;
+ private readonly CultNetDocumentRegistry _registry;
+ private readonly SemaphoreSlim _requests = new(1, 1);
+ private readonly object _completionLock = new();
+ private TaskCompletionSource? _completion;
+ private string? _messageId;
+ private bool _disposed;
+
+ internal CultMeshSnapshotSession(
+ string endpoint,
+ CultMeshSnapshotRequestOptions options,
+ CultNetDocumentRegistry? registry)
+ {
+ _endpoint = string.IsNullOrWhiteSpace(endpoint)
+ ? throw new ArgumentException("Value must be non-empty.", nameof(endpoint))
+ : endpoint;
+ _defaults = CultMesh.CloneSnapshotRequestOptions(options);
+ _registry = registry ?? new CultNetDocumentRegistry();
+ _client = CultMesh.CreateSnapshotClient(endpoint, _defaults)();
+ _client.OnCultNet(OnResponse);
+ _client.OnCultNet(OnError);
+ var (host, port) = CultNetSchemaWriteForwarder.ParseEndpoint(endpoint);
+ _client.Connect(host, port);
+ }
+
+ /// Fetches one raw snapshot while retaining the underlying endpoint connection.
+ public async Task FetchSnapshotAsync(
+ IReadOnlyList? schemaIds = null,
+ IReadOnlyList? recordKeys = null)
+ {
+ ThrowIfDisposed();
+ await _requests.WaitAsync().ConfigureAwait(false);
+ try
+ {
+ await CultMesh.WaitForSnapshotClientConnectionAsync(
+ _client,
+ _endpoint,
+ _defaults.ConnectTimeout)
+ .ConfigureAwait(false);
+ var options = CultMesh.CloneSnapshotRequestOptions(_defaults);
+ options.SchemaIds = schemaIds ?? options.SchemaIds;
+ options.RecordKeys = recordKeys ?? options.RecordKeys;
+ var messageId = CultMesh.CreateSnapshotMessageId(options);
+ var completion = new TaskCompletionSource(
+ TaskCreationOptions.RunContinuationsAsynchronously);
+ lock (_completionLock)
+ {
+ _messageId = messageId;
+ _completion = completion;
+ }
+ _client.SendCultNet(new CultNetSnapshotRequestMessage
+ {
+ MessageId = messageId,
+ SchemaIds = CultMesh.CleanSnapshotFilter(options.SchemaIds),
+ RecordKeys = CultMesh.CleanSnapshotFilter(options.RecordKeys),
+ ShardId = string.IsNullOrWhiteSpace(options.ShardId) ? null : options.ShardId,
+ ShardEpoch = options.ShardEpoch
+ });
+ return await CultMesh.WaitForSnapshotResponseAsync(
+ completion.Task,
+ _endpoint,
+ options,
+ messageId)
+ .ConfigureAwait(false);
+ }
+ finally
+ {
+ lock (_completionLock)
+ {
+ _messageId = null;
+ _completion = null;
+ }
+ _requests.Release();
+ }
+ }
+
+ /// Fetches and decodes typed documents over the retained endpoint connection.
+ public async Task> FetchDocumentsAsync(
+ IReadOnlyList? recordKeys = null,
+ IReadOnlyList? schemaIds = null)
+ where TDocument : class
+ {
+ var descriptor = CultDocumentRegistry.Shared.GetRequired();
+ var resolvedSchemas = schemaIds ?? (recordKeys is { Count: > 0 } ? null : new[] { descriptor.SchemaId });
+ var snapshot = await FetchSnapshotAsync(resolvedSchemas, recordKeys).ConfigureAwait(false);
+ return CultMesh.DecodeSnapshotDocuments(snapshot, _registry);
+ }
+
+ /// Closes the retained endpoint connection and rejects any active request.
+ public void Dispose()
+ {
+ if (_disposed) return;
+ _disposed = true;
+ lock (_completionLock)
+ _completion?.TrySetException(new ObjectDisposedException(nameof(CultMeshSnapshotSession)));
+ _client.Dispose();
+ _requests.Dispose();
+ }
+
+ private void OnResponse(CultNetSnapshotResponseRawMessage response)
+ {
+ lock (_completionLock)
+ {
+ if (string.Equals(response.MessageId, _messageId, StringComparison.Ordinal))
+ _completion?.TrySetResult(response);
+ }
+ }
+
+ private void OnError(CultNetErrorMessage error)
+ {
+ lock (_completionLock)
+ _completion?.TrySetException(new InvalidOperationException(error.Error));
+ }
+
+ private void ThrowIfDisposed()
+ {
+ if (_disposed) throw new ObjectDisposedException(nameof(CultMeshSnapshotSession));
+ }
+ }
+
///
/// Options for a typed remote snapshot surface bound to one CultNet endpoint.
///
@@ -499,6 +627,20 @@ namespace GameCult.Mesh
return new CultMeshSnapshotEndpoint(endpoint, options);
}
+ ///
+ /// Opens one reusable CultNet snapshot connection for ordered bulk document transfer.
+ ///
+ public static CultMeshSnapshotSession SnapshotSession(
+ string endpoint,
+ CultMeshSnapshotRequestOptions? options = null,
+ CultNetDocumentRegistry? registry = null)
+ {
+ return new CultMeshSnapshotSession(
+ endpoint,
+ options ?? new CultMeshSnapshotRequestOptions(),
+ registry);
+ }
+
///
/// Describes one typed document to bind from a CultMesh snapshot endpoint.
///
@@ -667,7 +809,7 @@ namespace GameCult.Mesh
return DecodeSnapshotDocuments(snapshot, registry ?? new CultNetDocumentRegistry());
}
- private static Func CreateSnapshotClient(
+ internal static Func CreateSnapshotClient(
string endpoint,
CultMeshSnapshotRequestOptions options)
{
@@ -693,7 +835,31 @@ namespace GameCult.Mesh
};
}
- private static string CreateSnapshotMessageId(CultMeshSnapshotRequestOptions options)
+ internal static CultMeshSnapshotRequestOptions CloneSnapshotRequestOptions(
+ CultMeshSnapshotRequestOptions? source)
+ {
+ if (source == null) return new CultMeshSnapshotRequestOptions();
+ return new CultMeshSnapshotRequestOptions
+ {
+ SchemaIds = source.SchemaIds,
+ RecordKeys = source.RecordKeys,
+ ShardId = source.ShardId,
+ ShardEpoch = source.ShardEpoch,
+ ResponseTimeout = source.ResponseTimeout,
+ ConnectTimeout = source.ConnectTimeout,
+ MessageIdPrefix = source.MessageIdPrefix,
+ Security = source.Security,
+ ConfigureClient = source.ConfigureClient,
+ CreateClient = source.CreateClient,
+ RudpRuntimeId = source.RudpRuntimeId,
+ RudpConnectionId = source.RudpConnectionId,
+ RudpConnectPayload = source.RudpConnectPayload,
+ RudpMaxFragmentBytes = source.RudpMaxFragmentBytes,
+ RudpResendDelayMs = source.RudpResendDelayMs
+ };
+ }
+
+ internal static string CreateSnapshotMessageId(CultMeshSnapshotRequestOptions options)
{
var prefix = string.IsNullOrWhiteSpace(options.MessageIdPrefix)
? "cultmesh:snapshot"
@@ -701,7 +867,7 @@ namespace GameCult.Mesh
return $"{prefix}:{Guid.NewGuid():N}";
}
- private static async Task WaitForSnapshotClientConnectionAsync(
+ internal static async Task WaitForSnapshotClientConnectionAsync(
ICultNetSchemaClient client,
string endpoint,
TimeSpan timeout)
@@ -716,7 +882,7 @@ namespace GameCult.Mesh
}
}
- private static async Task WaitForSnapshotResponseAsync(
+ internal static async Task WaitForSnapshotResponseAsync(
Task responseTask,
string endpoint,
CultMeshSnapshotRequestOptions options,
@@ -735,7 +901,7 @@ namespace GameCult.Mesh
return await responseTask.ConfigureAwait(false);
}
- private static string[]? CleanSnapshotFilter(IReadOnlyList? values)
+ internal static string[]? CleanSnapshotFilter(IReadOnlyList? values)
{
if (values is not { Count: > 0 })
return null;
diff --git a/src/GameCult.Networking/CultNetTransport.cs b/src/GameCult.Networking/CultNetTransport.cs
index 98da8562..a17d7e78 100644
--- a/src/GameCult.Networking/CultNetTransport.cs
+++ b/src/GameCult.Networking/CultNetTransport.cs
@@ -1079,9 +1079,11 @@ namespace GameCult.Networking
if (packet.PacketType == CultNetRudpPacketType.Ack || packet.PacketType == CultNetRudpPacketType.Pong)
{
- RememberReceived(packet.Sequence);
+ if (packet.PacketType == CultNetRudpPacketType.Pong)
+ RememberReceived(packet.Sequence);
return new CultNetRudpReceiveResult
{
+ Delivered = DrainUnblockedOrdered(),
Pong = packet.PacketType == CultNetRudpPacketType.Pong,
PongPayload = packet.PacketType == CultNetRudpPacketType.Pong
? packet.Payload ?? Array.Empty()
@@ -1131,7 +1133,17 @@ namespace GameCult.Networking
///
public CultNetRudpPacket CreateAck()
{
- return CreatePacket(CultNetRudpPacketType.Ack, "control", Array.Empty(), reliable: false, ordered: false, sequenced: false);
+ var (ack, ackMask) = AckState();
+ return new CultNetRudpPacket
+ {
+ PacketType = CultNetRudpPacketType.Ack,
+ ConnectionId = ConnectionId,
+ Sequence = 0,
+ Ack = ack,
+ AckMask = ackMask,
+ ChannelId = "control",
+ Payload = Array.Empty()
+ };
}
///
@@ -1425,6 +1437,17 @@ namespace GameCult.Networking
return delivered;
}
+ private IReadOnlyList DrainUnblockedOrdered()
+ {
+ var delivered = new List();
+ foreach (var channelId in _orderedBuffers.Keys.ToArray())
+ {
+ SkipReceivedNonChannelSequences(channelId);
+ delivered.AddRange(DrainOrdered(channelId));
+ }
+ return delivered;
+ }
+
private void SkipReceivedNonChannelSequences(string channelId)
{
if (!_orderedNextSequenceByChannel.TryGetValue(channelId, out var next))
@@ -1891,7 +1914,9 @@ namespace GameCult.Networking
}
var delivered = _deliveredFrames.Count > 0 ? _deliveredFrames.Dequeue() : null;
- if (packet.PacketType == CultNetRudpPacketType.Accept || delivered != null)
+ if (packet.PacketType == CultNetRudpPacketType.Accept ||
+ packet.PacketType == CultNetRudpPacketType.Data ||
+ delivered != null)
{
SendPacket(_session.CreateAck());
}
diff --git a/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs b/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
index dca59b42..e7f20bd9 100644
--- a/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
+++ b/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
@@ -2820,6 +2820,35 @@ public sealed class CultMeshStreamingTests
requests.Should().ContainSingle().Which.RecordKeys.Should().Equal(key.Value);
}
+ [Test]
+ public async Task SnapshotSession_ReusesOneConnectedClientAcrossOrderedRequests()
+ {
+ var sourceCache = new CultCache();
+ var registry = new CultNetDocumentRegistry(CultDocumentRegistry.Shared);
+ registry.Register(CultNetDocumentBinding.ForDocument(sourceCache.Registry));
+ var firstKey = new CultRecordKey("mesh-note:session-first");
+ var secondKey = new CultRecordKey("mesh-note:session-second");
+ await sourceCache.UpsertAsync(
+ new MeshNoteDocument { Schema = "tests.mesh_note.v1", Text = "first", Revision = 1 },
+ new CultRecordHandle(firstKey));
+ await sourceCache.UpsertAsync(
+ new MeshNoteDocument { Schema = "tests.mesh_note.v1", Text = "second", Revision = 2 },
+ new CultRecordHandle(secondKey));
+ var client = new MeshSnapshotSchemaClient(request =>
+ registry.CreateRawSnapshotResponse(sourceCache, request.MessageId, request));
+
+ using var session = CultMesh.SnapshotSession(
+ "cultnet://session.test:3075",
+ new CultMeshSnapshotRequestOptions { CreateClient = () => client },
+ registry);
+ var first = await session.FetchDocumentsAsync(new[] { firstKey.Value });
+ var second = await session.FetchDocumentsAsync(new[] { secondKey.Value });
+
+ client.ConnectCount.Should().Be(1);
+ first.Should().ContainSingle().Which.Text.Should().Be("first");
+ second.Should().ContainSingle().Which.Text.Should().Be("second");
+ }
+
[Test]
public async Task DocumentRegistryHelpers_CreateTypedNetworkRegistriesForAliases()
{
@@ -3743,9 +3772,11 @@ internal sealed class MeshSnapshotSchemaClient : ICultNetSchemaClient
}
public bool Connected { get; private set; }
+ public int ConnectCount { get; private set; }
public void Connect(string host, int port)
{
+ ConnectCount++;
Connected = true;
}
diff --git a/tests/GameCult.Networking.Tests/NetworkingTests.cs b/tests/GameCult.Networking.Tests/NetworkingTests.cs
index 95282196..526c3fa6 100644
--- a/tests/GameCult.Networking.Tests/NetworkingTests.cs
+++ b/tests/GameCult.Networking.Tests/NetworkingTests.cs
@@ -682,9 +682,12 @@ namespace GameCult.Networking.Tests
Assert.That(client.PendingReliableSequences, Is.Empty);
var ack = client.CreateAck();
+ Assert.That(ack.Sequence, Is.Zero);
Assert.That(ack.Ack, Is.EqualTo(100));
server.Receive(ack, 30);
Assert.That(server.PendingReliableSequences, Is.Empty);
+ var firstData = client.Send("schema", Encoding.UTF8.GetBytes("after-ack"));
+ Assert.That(firstData.Sequence, Is.EqualTo(2));
}
[Test]
@@ -842,6 +845,55 @@ namespace GameCult.Networking.Tests
Is.EqualTo(new[] { "second", "third" }));
}
+ [Test]
+ public void RudpSession_SequencedControlPacketReleasesBufferedOrderedFrame()
+ {
+ var receiver = new CultNetRudpSession(new CultNetRudpSessionOptions
+ {
+ ConnectionId = 199,
+ InitialSequence = 1
+ });
+ receiver.Receive(new CultNetRudpPacket
+ {
+ PacketType = CultNetRudpPacketType.Accept,
+ ConnectionId = 199,
+ Sequence = 100,
+ ChannelId = "control"
+ });
+ var first = receiver.Receive(new CultNetRudpPacket
+ {
+ PacketType = CultNetRudpPacketType.Data,
+ ConnectionId = 199,
+ Sequence = 101,
+ ChannelId = "schema",
+ Reliable = true,
+ Ordered = true,
+ Payload = Encoding.UTF8.GetBytes("first")
+ });
+ var buffered = receiver.Receive(new CultNetRudpPacket
+ {
+ PacketType = CultNetRudpPacketType.Data,
+ ConnectionId = 199,
+ Sequence = 103,
+ ChannelId = "schema",
+ Reliable = true,
+ Ordered = true,
+ Payload = Encoding.UTF8.GetBytes("second")
+ });
+ var released = receiver.Receive(new CultNetRudpPacket
+ {
+ PacketType = CultNetRudpPacketType.Pong,
+ ConnectionId = 199,
+ Sequence = 102,
+ ChannelId = "control"
+ });
+
+ Assert.That(first.Delivered, Has.Count.EqualTo(1));
+ Assert.That(buffered.Delivered, Is.Empty);
+ Assert.That(released.Delivered, Has.Count.EqualTo(1));
+ Assert.That(Encoding.UTF8.GetString(released.Delivered[0].Payload), Is.EqualTo("second"));
+ }
+
[Test]
public void RudpSession_SkipsControlPacketsWhileOrderingSchemaPayloads()
{