Add C# CultNet transport port

This commit is contained in:
Meta Vens 2026-06-14 21:59:09 +01:00
commit 8ce89688e2
4 changed files with 307 additions and 110 deletions

View file

@ -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`.

View file

@ -0,0 +1,213 @@
using System;
using System.Buffers.Binary;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
namespace GameCult.Networking
{
/// <summary>
/// Transfer counters for a CultNet transport connection.
/// </summary>
public sealed class CultNetTransportStats
{
/// <summary>
/// Gets the number of payload frames sent through the connection.
/// </summary>
public long FramesSent { get; internal set; }
/// <summary>
/// Gets the number of payload frames received through the connection.
/// </summary>
public long FramesReceived { get; internal set; }
/// <summary>
/// Gets the number of bytes sent, including transport framing.
/// </summary>
public long BytesSent { get; internal set; }
/// <summary>
/// Gets the number of bytes received, including transport framing.
/// </summary>
public long BytesReceived { get; internal set; }
internal CultNetTransportStats Snapshot()
{
return new CultNetTransportStats
{
FramesSent = FramesSent,
FramesReceived = FramesReceived,
BytesSent = BytesSent,
BytesReceived = BytesReceived
};
}
}
/// <summary>
/// Payload delivered by a CultNet transport connection.
/// </summary>
public sealed class CultNetTransportFrame
{
/// <summary>
/// Gets or sets the logical transport channel.
/// </summary>
public string ChannelId { get; set; } = "schema";
/// <summary>
/// Gets or sets the raw payload bytes carried by the frame.
/// </summary>
public byte[] Payload { get; set; } = Array.Empty<byte>();
}
/// <summary>
/// Options for creating a TCP framed transport profile.
/// </summary>
public sealed class TcpFramedTransportProfileOptions
{
/// <summary>
/// Gets or sets the advertised transport id.
/// </summary>
public string TransportId { get; set; } = "tcp-framed";
/// <summary>
/// Gets or sets the advertised host.
/// </summary>
public string? Host { get; set; }
/// <summary>
/// Gets or sets the advertised port.
/// </summary>
public int? Port { get; set; }
/// <summary>
/// Gets or sets the maximum payload size for the schema channel.
/// </summary>
public int? MaxPayloadBytes { get; set; }
/// <summary>
/// Gets or sets the maximum fragment size for the schema channel.
/// </summary>
public int? MaxFragmentBytes { get; set; }
}
/// <summary>
/// Helpers for creating CultNet transport profile documents.
/// </summary>
public static class CultNetTransportProfiles
{
/// <summary>
/// Creates a profile for the current length-prefixed TCP schema lane.
/// </summary>
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
}
]
}
]
};
}
}
/// <summary>
/// Transport connection for the current TCP length-prefixed CultNet schema lane.
/// </summary>
public sealed class TcpFramedTransportConnection
{
private const int HeaderBytes = 4;
private readonly Stream _stream;
private readonly CultNetTransportStats _stats = new CultNetTransportStats();
/// <summary>
/// Initializes a TCP framed transport over an existing stream.
/// </summary>
public TcpFramedTransportConnection(Stream stream, CultNetTransportProfile profile)
{
_stream = stream ?? throw new ArgumentNullException(nameof(stream));
Profile = profile ?? throw new ArgumentNullException(nameof(profile));
}
/// <summary>
/// Gets the profile this connection implements.
/// </summary>
public CultNetTransportProfile Profile { get; }
/// <summary>
/// Gets a snapshot of the current transfer counters.
/// </summary>
public CultNetTransportStats Stats => _stats.Snapshot();
/// <summary>
/// Sends a schema-channel payload.
/// </summary>
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++;
}
/// <summary>
/// Receives the next schema-channel payload.
/// </summary>
public async Task<CultNetTransportFrame> 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;
}
}
}
}

View file

@ -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<CultNetHelloMessage>(stream, CultNetSchemaVersions.Hello);
var remoteHello = await ExpectMessageAsync<CultNetHelloMessage>(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<CultNetSchemaCatalogResponseMessage>(stream, CultNetSchemaVersions.SchemaCatalogResponse);
var catalog = await ExpectMessageAsync<CultNetSchemaCatalogResponseMessage>(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<CultNetSnapshotResponseRawMessage>(stream, CultNetSchemaVersions.SnapshotResponseRaw);
var snapshot = await ExpectMessageAsync<CultNetSnapshotResponseRawMessage>(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<object> MutateRemoteNoteAsync(
NetworkStream stream,
TcpFramedTransportConnection transport,
CultCache cache,
CultNetDocumentRegistry documentRegistry,
string runtimeId,
@ -274,16 +276,16 @@ static async Task<object> MutateRemoteNoteAsync(
AppendBody = $" Decorated by {runtimeId}.",
AppendTag = $"decorated:{runtimeId}"
};
await SendMessageAsync(stream, documentRegistry.CreateRawDocumentPutMessage(
await SendMessageAsync(transport, documentRegistry.CreateRawDocumentPutMessage(
$"{runtimeId}-decorate-put",
new CultRecordHandle<CultNetInteropMutationIntent>(new CultRecordKey(intent.IntentId)),
intent));
await documentRegistry.ApplyRawDocumentPutMessageAsync<CultNetInteropMutationReceipt>(
cache,
await ExpectMessageAsync<CultNetDocumentPutRawMessage>(stream, CultNetSchemaVersions.DocumentPutRaw));
await ExpectMessageAsync<CultNetDocumentPutRawMessage>(transport, CultNetSchemaVersions.DocumentPutRaw));
var mutated = await documentRegistry.ApplyRawDocumentPutMessageAsync<CultNetInteropNote>(
cache,
await ExpectMessageAsync<CultNetDocumentPutRawMessage>(stream, CultNetSchemaVersions.DocumentPutRaw));
await ExpectMessageAsync<CultNetDocumentPutRawMessage>(transport, CultNetSchemaVersions.DocumentPutRaw));
return new
{
schemaVersion = mutated.SchemaVersion,
@ -296,7 +298,7 @@ static async Task<object> MutateRemoteNoteAsync(
}
static async Task<object> FireRemoteWeaponAsync(
NetworkStream stream,
TcpFramedTransportConnection transport,
CultCache cache,
CultNetDocumentRegistry documentRegistry,
string runtimeId,
@ -308,13 +310,13 @@ static async Task<object> FireRemoteWeaponAsync(
CharacterId = remoteRuntimeId,
WeaponId = "interop-rifle"
};
await SendMessageAsync(stream, documentRegistry.CreateRawDocumentPutMessage(
await SendMessageAsync(transport, documentRegistry.CreateRawDocumentPutMessage(
$"{runtimeId}-fire-put",
new CultRecordHandle<CultNetInteropFireCommand>(new CultRecordKey(command.CommandId)),
command));
var receipt = await documentRegistry.ApplyRawDocumentPutMessageAsync<CultNetInteropFireReceipt>(
cache,
await ExpectMessageAsync<CultNetDocumentPutRawMessage>(stream, CultNetSchemaVersions.DocumentPutRaw));
await ExpectMessageAsync<CultNetDocumentPutRawMessage>(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<CultNetInteropMutationReceipt>(new CultRecordKey(receipt.IntentId)),
receipt,
options), cancellationToken);
await SendMessageAsync(stream, documentRegistry.CreateRawDocumentPutMessage(
await SendMessageAsync(transport, documentRegistry.CreateRawDocumentPutMessage(
$"{config.RuntimeId}-mutated-note",
new CultRecordHandle<CultNetInteropNote>(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<CultNetInteropFireReceipt>(new CultRecordKey(receipt.CommandId)),
receipt,
@ -607,21 +560,32 @@ static CultNetSchemaCatalogResponseMessage CreateCatalogResponse(
};
}
static async Task SendMessageAsync<TMessage>(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<TMessage>(
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<TMessage> ExpectMessageAsync<TMessage>(NetworkStream stream, string expectedSchemaVersion)
static async Task<TMessage> ExpectMessageAsync<TMessage>(
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<TMessage> ExpectMessageAsync<TMessage>(NetworkStream stream, s
?? throw new InvalidOperationException($"Expected {typeof(TMessage).Name} but received {message.GetType().Name}.");
}
static async Task<ICultNetSchemaMessage> ReadMessageAsync(NetworkStream stream, CancellationToken cancellationToken)
static async Task<ICultNetSchemaMessage> 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)

View file

@ -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<InvalidOperationException>(
async () => await sender.SendAsync("unreliable", Array.Empty<byte>())),
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()
{