Reuse CultMesh snapshot connections

This commit is contained in:
Meta Vens 2026-07-10 06:37:10 +01:00
commit 905c5254b4
4 changed files with 282 additions and 8 deletions

View file

@ -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;
}
/// <summary>
/// Reuses one connected CultNet schema client for an ordered sequence of snapshot requests.
/// </summary>
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<CultNetSnapshotResponseRawMessage>? _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<CultNetSnapshotResponseRawMessage>(OnResponse);
_client.OnCultNet<CultNetErrorMessage>(OnError);
var (host, port) = CultNetSchemaWriteForwarder.ParseEndpoint(endpoint);
_client.Connect(host, port);
}
/// <summary>Fetches one raw snapshot while retaining the underlying endpoint connection.</summary>
public async Task<CultNetSnapshotResponseRawMessage> FetchSnapshotAsync(
IReadOnlyList<string>? schemaIds = null,
IReadOnlyList<string>? 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<CultNetSnapshotResponseRawMessage>(
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();
}
}
/// <summary>Fetches and decodes typed documents over the retained endpoint connection.</summary>
public async Task<IReadOnlyList<TDocument>> FetchDocumentsAsync<TDocument>(
IReadOnlyList<string>? recordKeys = null,
IReadOnlyList<string>? schemaIds = null)
where TDocument : class
{
var descriptor = CultDocumentRegistry.Shared.GetRequired<TDocument>();
var resolvedSchemas = schemaIds ?? (recordKeys is { Count: > 0 } ? null : new[] { descriptor.SchemaId });
var snapshot = await FetchSnapshotAsync(resolvedSchemas, recordKeys).ConfigureAwait(false);
return CultMesh.DecodeSnapshotDocuments<TDocument>(snapshot, _registry);
}
/// <summary>Closes the retained endpoint connection and rejects any active request.</summary>
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));
}
}
/// <summary>
/// Options for a typed remote snapshot surface bound to one CultNet endpoint.
/// </summary>
@ -499,6 +627,20 @@ namespace GameCult.Mesh
return new CultMeshSnapshotEndpoint(endpoint, options);
}
/// <summary>
/// Opens one reusable CultNet snapshot connection for ordered bulk document transfer.
/// </summary>
public static CultMeshSnapshotSession SnapshotSession(
string endpoint,
CultMeshSnapshotRequestOptions? options = null,
CultNetDocumentRegistry? registry = null)
{
return new CultMeshSnapshotSession(
endpoint,
options ?? new CultMeshSnapshotRequestOptions(),
registry);
}
/// <summary>
/// Describes one typed document to bind from a CultMesh snapshot endpoint.
/// </summary>
@ -667,7 +809,7 @@ namespace GameCult.Mesh
return DecodeSnapshotDocuments<TDocument>(snapshot, registry ?? new CultNetDocumentRegistry());
}
private static Func<ICultNetSchemaClient> CreateSnapshotClient(
internal static Func<ICultNetSchemaClient> 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<CultNetSnapshotResponseRawMessage> WaitForSnapshotResponseAsync(
internal static async Task<CultNetSnapshotResponseRawMessage> WaitForSnapshotResponseAsync(
Task<CultNetSnapshotResponseRawMessage> responseTask,
string endpoint,
CultMeshSnapshotRequestOptions options,
@ -735,7 +901,7 @@ namespace GameCult.Mesh
return await responseTask.ConfigureAwait(false);
}
private static string[]? CleanSnapshotFilter(IReadOnlyList<string>? values)
internal static string[]? CleanSnapshotFilter(IReadOnlyList<string>? values)
{
if (values is not { Count: > 0 })
return null;

View file

@ -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<byte>()
@ -1131,7 +1133,17 @@ namespace GameCult.Networking
/// </summary>
public CultNetRudpPacket CreateAck()
{
return CreatePacket(CultNetRudpPacketType.Ack, "control", Array.Empty<byte>(), 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<byte>()
};
}
/// <summary>
@ -1425,6 +1437,17 @@ namespace GameCult.Networking
return delivered;
}
private IReadOnlyList<CultNetRudpDeliveredFrame> DrainUnblockedOrdered()
{
var delivered = new List<CultNetRudpDeliveredFrame>();
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());
}

View file

@ -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<MeshNoteDocument>(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<MeshNoteDocument>(firstKey));
await sourceCache.UpsertAsync(
new MeshNoteDocument { Schema = "tests.mesh_note.v1", Text = "second", Revision = 2 },
new CultRecordHandle<MeshNoteDocument>(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<MeshNoteDocument>(new[] { firstKey.Value });
var second = await session.FetchDocumentsAsync<MeshNoteDocument>(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;
}

View file

@ -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()
{