diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index 48a0e2b6..3073a01d 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -137,6 +137,10 @@ lets the runtimes stop guessing what kind of pipe a peer is offering. Current progress: - Steps 1-3 are live in C#, TypeScript, Rust, and Python. +- C# now has the shared `tcp_framed` transport profile helper plus a + `TcpFramedTransportConnection` with schema-channel `SendAsync`, + `ReceiveAsync`, and transfer stats. The C# interop peer advertises and uses + that shared port instead of owning raw TCP frame I/O directly. - TypeScript has the first narrow transport connection port: `TcpFramedTransportConnection` owns length-prefixed frame delivery, exposes frame/close/error events, `send(channel, payload)`, `close`, and transfer @@ -150,7 +154,7 @@ Current progress: `TcpFramedTransportConnection` with schema-channel `send`, `receive`, and transfer stats. The Rust interop peer advertises and uses that shared port instead of owning raw TCP frame I/O directly. -- The remaining parity work is to add equivalent ports to C# and Kotlin, deepen +- The remaining parity work is to add the equivalent port to Kotlin, deepen Python's server-side use of its port, and move each runtime's existing TCP/LiteNetLib/WebSocket bodies behind those ports before implementing `rudp`. diff --git a/src/GameCult.Networking/CultNetTransport.cs b/src/GameCult.Networking/CultNetTransport.cs new file mode 100644 index 00000000..cfafa6b3 --- /dev/null +++ b/src/GameCult.Networking/CultNetTransport.cs @@ -0,0 +1,213 @@ +using System; +using System.Buffers.Binary; +using System.IO; +using System.Threading; +using System.Threading.Tasks; + +namespace GameCult.Networking +{ + /// + /// Transfer counters for a CultNet transport connection. + /// + public sealed class CultNetTransportStats + { + /// + /// Gets the number of payload frames sent through the connection. + /// + public long FramesSent { get; internal set; } + /// + /// Gets the number of payload frames received through the connection. + /// + public long FramesReceived { get; internal set; } + /// + /// Gets the number of bytes sent, including transport framing. + /// + public long BytesSent { get; internal set; } + /// + /// Gets the number of bytes received, including transport framing. + /// + public long BytesReceived { get; internal set; } + + internal CultNetTransportStats Snapshot() + { + return new CultNetTransportStats + { + FramesSent = FramesSent, + FramesReceived = FramesReceived, + BytesSent = BytesSent, + BytesReceived = BytesReceived + }; + } + } + + /// + /// Payload delivered by a CultNet transport connection. + /// + public sealed class CultNetTransportFrame + { + /// + /// Gets or sets the logical transport channel. + /// + public string ChannelId { get; set; } = "schema"; + /// + /// Gets or sets the raw payload bytes carried by the frame. + /// + public byte[] Payload { get; set; } = Array.Empty(); + } + + /// + /// Options for creating a TCP framed transport profile. + /// + public sealed class TcpFramedTransportProfileOptions + { + /// + /// Gets or sets the advertised transport id. + /// + public string TransportId { get; set; } = "tcp-framed"; + /// + /// Gets or sets the advertised host. + /// + public string? Host { get; set; } + /// + /// Gets or sets the advertised port. + /// + public int? Port { get; set; } + /// + /// Gets or sets the maximum payload size for the schema channel. + /// + public int? MaxPayloadBytes { get; set; } + /// + /// Gets or sets the maximum fragment size for the schema channel. + /// + public int? MaxFragmentBytes { get; set; } + } + + /// + /// Helpers for creating CultNet transport profile documents. + /// + public static class CultNetTransportProfiles + { + /// + /// Creates a profile for the current length-prefixed TCP schema lane. + /// + public static CultNetTransportProfile CreateTcpFramed( + string runtimeId, + TcpFramedTransportProfileOptions? options = null) + { + if (string.IsNullOrWhiteSpace(runtimeId)) throw new ArgumentException("Runtime id is required.", nameof(runtimeId)); + options ??= new TcpFramedTransportProfileOptions(); + return new CultNetTransportProfile + { + RuntimeId = runtimeId, + Transports = + [ + new CultNetTransportDescriptor + { + TransportId = string.IsNullOrWhiteSpace(options.TransportId) + ? "tcp-framed" + : options.TransportId, + Protocol = "tcp_framed", + Host = options.Host, + Port = options.Port, + WireContracts = [CultNetWireContracts.SchemaV0], + Channels = + [ + new CultNetTransportChannel + { + ChannelId = "schema", + Delivery = "reliable", + Ordering = "ordered", + MaxPayloadBytes = options.MaxPayloadBytes, + MaxFragmentBytes = options.MaxFragmentBytes + } + ] + } + ] + }; + } + } + + /// + /// Transport connection for the current TCP length-prefixed CultNet schema lane. + /// + public sealed class TcpFramedTransportConnection + { + private const int HeaderBytes = 4; + private readonly Stream _stream; + private readonly CultNetTransportStats _stats = new CultNetTransportStats(); + + /// + /// Initializes a TCP framed transport over an existing stream. + /// + public TcpFramedTransportConnection(Stream stream, CultNetTransportProfile profile) + { + _stream = stream ?? throw new ArgumentNullException(nameof(stream)); + Profile = profile ?? throw new ArgumentNullException(nameof(profile)); + } + + /// + /// Gets the profile this connection implements. + /// + public CultNetTransportProfile Profile { get; } + + /// + /// Gets a snapshot of the current transfer counters. + /// + public CultNetTransportStats Stats => _stats.Snapshot(); + + /// + /// Sends a schema-channel payload. + /// + public async Task SendAsync(string channelId, byte[] payload, CancellationToken cancellationToken = default) + { + if (!string.Equals(channelId, "schema", StringComparison.Ordinal)) + { + throw new InvalidOperationException($"tcp_framed transport only supports the schema channel, got \"{channelId}\"."); + } + + if (payload == null) throw new ArgumentNullException(nameof(payload)); + var header = new byte[HeaderBytes]; + BinaryPrimitives.WriteUInt32BigEndian(header, checked((uint)payload.Length)); + await _stream.WriteAsync(header, cancellationToken).ConfigureAwait(false); + await _stream.WriteAsync(payload, cancellationToken).ConfigureAwait(false); + await _stream.FlushAsync(cancellationToken).ConfigureAwait(false); + _stats.BytesSent += HeaderBytes + payload.Length; + _stats.FramesSent++; + } + + /// + /// Receives the next schema-channel payload. + /// + public async Task ReceiveAsync(CancellationToken cancellationToken = default) + { + var header = new byte[HeaderBytes]; + await ReadExactlyAsync(header, cancellationToken).ConfigureAwait(false); + var payloadLength = checked((int)BinaryPrimitives.ReadUInt32BigEndian(header)); + var payload = new byte[payloadLength]; + await ReadExactlyAsync(payload, cancellationToken).ConfigureAwait(false); + _stats.BytesReceived += HeaderBytes + payloadLength; + _stats.FramesReceived++; + return new CultNetTransportFrame + { + ChannelId = "schema", + Payload = payload + }; + } + + private async Task ReadExactlyAsync(byte[] buffer, CancellationToken cancellationToken) + { + var offset = 0; + while (offset < buffer.Length) + { + var read = await _stream.ReadAsync(buffer.AsMemory(offset, buffer.Length - offset), cancellationToken) + .ConfigureAwait(false); + if (read == 0) + { + throw new EndOfStreamException(); + } + + offset += read; + } + } + } +} diff --git a/tests/GameCult.Networking.InteropPeer/Program.cs b/tests/GameCult.Networking.InteropPeer/Program.cs index ad9c05a9..13e7d5f1 100644 --- a/tests/GameCult.Networking.InteropPeer/Program.cs +++ b/tests/GameCult.Networking.InteropPeer/Program.cs @@ -1,5 +1,4 @@ using System; -using System.Buffers.Binary; using System.Collections.Generic; using System.Globalization; using System.IO; @@ -183,8 +182,11 @@ static async Task DialAsync(DialConfig config) using var client = new TcpClient(); await client.ConnectAsync(config.TargetHost, config.TargetPort); using var stream = client.GetStream(); + var transport = new TcpFramedTransportConnection( + stream, + CreateTcpFramedTransportProfile(config.RuntimeId, config.TargetHost, config.TargetPort)); - await SendMessageAsync(stream, new CultNetHelloMessage + await SendMessageAsync(transport, new CultNetHelloMessage { RuntimeId = config.RuntimeId, RuntimeKind = config.RuntimeKind, @@ -196,24 +198,24 @@ static async Task DialAsync(DialConfig config) SupportedMessageVersions = [InteropPeerShared.InteropSchemaVersion], SupportsSchemaCatalog = true }); - var remoteHello = await ExpectMessageAsync(stream, CultNetSchemaVersions.Hello); + var remoteHello = await ExpectMessageAsync(transport, CultNetSchemaVersions.Hello); - await SendMessageAsync(stream, new CultNetSchemaCatalogRequestMessage + await SendMessageAsync(transport, new CultNetSchemaCatalogRequestMessage { MessageId = $"{config.RuntimeId}-catalog", IncludeSchemaJson = true, SchemaIds = [schemaRegistration.SchemaId], Kinds = ["document_payload"] }); - var catalog = await ExpectMessageAsync(stream, CultNetSchemaVersions.SchemaCatalogResponse); + var catalog = await ExpectMessageAsync(transport, CultNetSchemaVersions.SchemaCatalogResponse); - await SendMessageAsync(stream, new CultNetSnapshotRequestMessage + await SendMessageAsync(transport, new CultNetSnapshotRequestMessage { MessageId = $"{config.RuntimeId}-snapshot", SchemaIds = [schemaRegistration.SchemaId], RecordKeys = [$"note:{remoteHello.RuntimeId}"] }); - var snapshot = await ExpectMessageAsync(stream, CultNetSchemaVersions.SnapshotResponseRaw); + var snapshot = await ExpectMessageAsync(transport, CultNetSchemaVersions.SnapshotResponseRaw); await documentRegistry.ApplyRawSnapshotResponseAsync(cache, snapshot); var note = cache.AllEntries @@ -224,8 +226,8 @@ static async Task DialAsync(DialConfig config) string.Equals(schema.SchemaId, schemaRegistration.SchemaId, StringComparison.Ordinal) && string.Equals(schema.DocumentType, InteropPeerShared.InteropDocumentType, StringComparison.Ordinal)); - var mutation = await MutateRemoteNoteAsync(stream, cache, documentRegistry, config.RuntimeId, note); - var fireReceipt = await FireRemoteWeaponAsync(stream, cache, documentRegistry, config.RuntimeId, remoteHello.RuntimeId); + var mutation = await MutateRemoteNoteAsync(transport, cache, documentRegistry, config.RuntimeId, note); + var fireReceipt = await FireRemoteWeaponAsync(transport, cache, documentRegistry, config.RuntimeId, remoteHello.RuntimeId); WriteJsonLine(new { @@ -261,7 +263,7 @@ static async Task DialAsync(DialConfig config) } static async Task MutateRemoteNoteAsync( - NetworkStream stream, + TcpFramedTransportConnection transport, CultCache cache, CultNetDocumentRegistry documentRegistry, string runtimeId, @@ -274,16 +276,16 @@ static async Task MutateRemoteNoteAsync( AppendBody = $" Decorated by {runtimeId}.", AppendTag = $"decorated:{runtimeId}" }; - await SendMessageAsync(stream, documentRegistry.CreateRawDocumentPutMessage( + await SendMessageAsync(transport, documentRegistry.CreateRawDocumentPutMessage( $"{runtimeId}-decorate-put", new CultRecordHandle(new CultRecordKey(intent.IntentId)), intent)); await documentRegistry.ApplyRawDocumentPutMessageAsync( cache, - await ExpectMessageAsync(stream, CultNetSchemaVersions.DocumentPutRaw)); + await ExpectMessageAsync(transport, CultNetSchemaVersions.DocumentPutRaw)); var mutated = await documentRegistry.ApplyRawDocumentPutMessageAsync( cache, - await ExpectMessageAsync(stream, CultNetSchemaVersions.DocumentPutRaw)); + await ExpectMessageAsync(transport, CultNetSchemaVersions.DocumentPutRaw)); return new { schemaVersion = mutated.SchemaVersion, @@ -296,7 +298,7 @@ static async Task MutateRemoteNoteAsync( } static async Task FireRemoteWeaponAsync( - NetworkStream stream, + TcpFramedTransportConnection transport, CultCache cache, CultNetDocumentRegistry documentRegistry, string runtimeId, @@ -308,13 +310,13 @@ static async Task FireRemoteWeaponAsync( CharacterId = remoteRuntimeId, WeaponId = "interop-rifle" }; - await SendMessageAsync(stream, documentRegistry.CreateRawDocumentPutMessage( + await SendMessageAsync(transport, documentRegistry.CreateRawDocumentPutMessage( $"{runtimeId}-fire-put", new CultRecordHandle(new CultRecordKey(command.CommandId)), command)); var receipt = await documentRegistry.ApplyRawDocumentPutMessageAsync( cache, - await ExpectMessageAsync(stream, CultNetSchemaVersions.DocumentPutRaw)); + await ExpectMessageAsync(transport, CultNetSchemaVersions.DocumentPutRaw)); return new { schemaVersion = receipt.SchemaVersion, @@ -364,33 +366,7 @@ static async Task RunDiscoveryServerAsync(Socket socket, ServeConfig config, Can TcpPort = config.TcpPort, WireContract = CultNetWireContracts.SchemaV0, SupportedDocumentTypes = [InteropPeerShared.InteropDocumentType], - TransportProfiles = - [ - new CultNetTransportProfile - { - RuntimeId = config.RuntimeId, - Transports = - [ - new CultNetTransportDescriptor - { - TransportId = "interop-tcp", - Protocol = "tcp_framed", - Host = config.AdvertiseHost, - Port = config.TcpPort, - WireContracts = [CultNetWireContracts.SchemaV0], - Channels = - [ - new CultNetTransportChannel - { - ChannelId = "schema", - Delivery = "reliable", - Ordering = "ordered" - } - ] - } - ] - } - ], + TransportProfiles = [CreateTcpFramedTransportProfile(config.RuntimeId, config.AdvertiseHost, config.TcpPort)], SupportsSchemaCatalog = true }; var announceBytes = MessagePackSerializer.Serialize(announce, CultNetSchemaMessageSerialization.Options); @@ -437,12 +413,15 @@ static async Task RunTcpServerAsync( try { using var stream = ownedClient.GetStream(); + var transport = new TcpFramedTransportConnection( + stream, + CreateTcpFramedTransportProfile(config.RuntimeId, config.AdvertiseHost, config.TcpPort)); while (!cancellationToken.IsCancellationRequested) { ICultNetSchemaMessage message; try { - message = await ReadMessageAsync(stream, cancellationToken); + message = await ReadMessageAsync(transport, cancellationToken); } catch (EndOfStreamException) { @@ -452,7 +431,7 @@ static async Task RunTcpServerAsync( switch (message) { case CultNetHelloMessage: - await SendMessageAsync(stream, new CultNetHelloMessage + await SendMessageAsync(transport, new CultNetHelloMessage { RuntimeId = config.RuntimeId, RuntimeKind = config.RuntimeKind, @@ -462,42 +441,16 @@ static async Task RunTcpServerAsync( SupportedDocumentTypes = [InteropPeerShared.InteropDocumentType], SupportedMutationContracts = [InteropPeerShared.InteractionContract()], SupportedMessageVersions = [InteropPeerShared.InteropSchemaVersion], - TransportProfiles = - [ - new CultNetTransportProfile - { - RuntimeId = config.RuntimeId, - Transports = - [ - new CultNetTransportDescriptor - { - TransportId = "interop-tcp", - Protocol = "tcp_framed", - Host = config.AdvertiseHost, - Port = config.TcpPort, - WireContracts = [CultNetWireContracts.SchemaV0], - Channels = - [ - new CultNetTransportChannel - { - ChannelId = "schema", - Delivery = "reliable", - Ordering = "ordered" - } - ] - } - ] - } - ], + TransportProfiles = [CreateTcpFramedTransportProfile(config.RuntimeId, config.AdvertiseHost, config.TcpPort)], SupportsSchemaCatalog = true }, cancellationToken); break; case CultNetSchemaCatalogRequestMessage catalogRequest: - await SendMessageAsync(stream, CreateCatalogResponse(customSchemaRegistry, catalogRequest), cancellationToken); + await SendMessageAsync(transport, CreateCatalogResponse(customSchemaRegistry, catalogRequest), cancellationToken); break; case CultNetSnapshotRequestMessage snapshotRequest: await SendMessageAsync( - stream, + transport, documentRegistry.CreateRawSnapshotResponse( cache, snapshotRequest.MessageId, @@ -512,7 +465,7 @@ static async Task RunTcpServerAsync( cancellationToken); break; case CultNetDocumentPutRawMessage rawPut: - await HandleRawPutAsync(stream, config, cache, documentRegistry, rawPut, cancellationToken); + await HandleRawPutAsync(transport, config, cache, documentRegistry, rawPut, cancellationToken); break; } } @@ -526,7 +479,7 @@ static async Task RunTcpServerAsync( } static async Task HandleRawPutAsync( - NetworkStream stream, + TcpFramedTransportConnection transport, ServeConfig config, CultCache cache, CultNetDocumentRegistry documentRegistry, @@ -553,12 +506,12 @@ static async Task HandleRawPutAsync( Tags = note.Tags }; var options = ResponseOptions(config, "mutation"); - await SendMessageAsync(stream, documentRegistry.CreateRawDocumentPutMessage( + await SendMessageAsync(transport, documentRegistry.CreateRawDocumentPutMessage( $"{config.RuntimeId}-mutation-receipt", new CultRecordHandle(new CultRecordKey(receipt.IntentId)), receipt, options), cancellationToken); - await SendMessageAsync(stream, documentRegistry.CreateRawDocumentPutMessage( + await SendMessageAsync(transport, documentRegistry.CreateRawDocumentPutMessage( $"{config.RuntimeId}-mutated-note", new CultRecordHandle(new CultRecordKey(note.DocumentId)), note, @@ -577,7 +530,7 @@ static async Task HandleRawPutAsync( ShotsFired = 1, AmmoRemaining = 29 }; - await SendMessageAsync(stream, documentRegistry.CreateRawDocumentPutMessage( + await SendMessageAsync(transport, documentRegistry.CreateRawDocumentPutMessage( $"{config.RuntimeId}-fire-receipt", new CultRecordHandle(new CultRecordKey(receipt.CommandId)), receipt, @@ -607,21 +560,32 @@ static CultNetSchemaCatalogResponseMessage CreateCatalogResponse( }; } -static async Task SendMessageAsync(NetworkStream stream, TMessage message, CancellationToken cancellationToken = default) +static CultNetTransportProfile CreateTcpFramedTransportProfile(string runtimeId, string host, int port) +{ + return CultNetTransportProfiles.CreateTcpFramed(runtimeId, new TcpFramedTransportProfileOptions + { + TransportId = "interop-tcp", + Host = host, + Port = port + }); +} + +static async Task SendMessageAsync( + TcpFramedTransportConnection transport, + TMessage message, + CancellationToken cancellationToken = default) where TMessage : ICultNetSchemaMessage { var payload = CultNetSchemaMessageSerialization.Serialize(message); - var header = new byte[4]; - BinaryPrimitives.WriteUInt32BigEndian(header, checked((uint)payload.Length)); - await stream.WriteAsync(header, cancellationToken); - await stream.WriteAsync(payload, cancellationToken); - await stream.FlushAsync(cancellationToken); + await transport.SendAsync("schema", payload, cancellationToken); } -static async Task ExpectMessageAsync(NetworkStream stream, string expectedSchemaVersion) +static async Task ExpectMessageAsync( + TcpFramedTransportConnection transport, + string expectedSchemaVersion) where TMessage : class, ICultNetSchemaMessage { - var message = await ReadMessageAsync(stream, CancellationToken.None); + var message = await ReadMessageAsync(transport, CancellationToken.None); if (!string.Equals(message.SchemaVersion, expectedSchemaVersion, StringComparison.Ordinal)) { throw new InvalidOperationException($"Expected {expectedSchemaVersion} but received {message.SchemaVersion}."); @@ -631,29 +595,12 @@ static async Task ExpectMessageAsync(NetworkStream stream, s ?? throw new InvalidOperationException($"Expected {typeof(TMessage).Name} but received {message.GetType().Name}."); } -static async Task ReadMessageAsync(NetworkStream stream, CancellationToken cancellationToken) +static async Task ReadMessageAsync( + TcpFramedTransportConnection transport, + CancellationToken cancellationToken) { - var header = new byte[4]; - await ReadExactlyAsync(stream, header, cancellationToken); - var payloadLength = checked((int)BinaryPrimitives.ReadUInt32BigEndian(header)); - var payload = new byte[payloadLength]; - await ReadExactlyAsync(stream, payload, cancellationToken); - return CultNetSchemaMessageSerialization.Deserialize(payload); -} - -static async Task ReadExactlyAsync(Stream stream, byte[] buffer, CancellationToken cancellationToken) -{ - var offset = 0; - while (offset < buffer.Length) - { - var read = await stream.ReadAsync(buffer.AsMemory(offset, buffer.Length - offset), cancellationToken); - if (read == 0) - { - throw new EndOfStreamException(); - } - - offset += read; - } + var frame = await transport.ReceiveAsync(cancellationToken); + return CultNetSchemaMessageSerialization.Deserialize(frame.Payload); } static Socket CreateDiscoverySocket(int port, IPAddress multicastGroup) diff --git a/tests/GameCult.Networking.Tests/NetworkingTests.cs b/tests/GameCult.Networking.Tests/NetworkingTests.cs index 6520db76..f2ba6880 100644 --- a/tests/GameCult.Networking.Tests/NetworkingTests.cs +++ b/tests/GameCult.Networking.Tests/NetworkingTests.cs @@ -223,6 +223,39 @@ namespace GameCult.Networking.Tests Assert.That(roundTrip.TransportProfiles[0].Transports[0].Channels[0].Ordering, Is.EqualTo("ordered")); } + [Test] + public async Task TcpFramedTransportConnection_CarriesSchemaPayloadsWithStats() + { + var payload = Encoding.UTF8.GetBytes("cultnet-payload"); + var profile = CultNetTransportProfiles.CreateTcpFramed( + "csharp-transport", + new TcpFramedTransportProfileOptions + { + TransportId = "test-tcp" + }); + using var stream = new MemoryStream(); + var sender = new TcpFramedTransportConnection(stream, profile); + + await sender.SendAsync("schema", payload); + + Assert.That(sender.Stats.FramesSent, Is.EqualTo(1)); + Assert.That(sender.Stats.BytesSent, Is.EqualTo(payload.Length + 4)); + Assert.That( + Assert.ThrowsAsync( + async () => await sender.SendAsync("unreliable", Array.Empty())), + Is.Not.Null); + + stream.Position = 0; + var receiver = new TcpFramedTransportConnection(stream, profile); + var frame = await receiver.ReceiveAsync(); + + Assert.That(frame.ChannelId, Is.EqualTo("schema")); + Assert.That(frame.Payload, Is.EqualTo(payload)); + Assert.That(receiver.Stats.FramesReceived, Is.EqualTo(1)); + Assert.That(receiver.Stats.BytesReceived, Is.EqualTo(frame.Payload.Length + 4)); + Assert.That(receiver.Profile.Transports[0].Protocol, Is.EqualTo("tcp_framed")); + } + [Test] public void CultNetSchemaMessageSerialization_RoundTrips_RawSnapshotResponse() {