feat(sidecar): add routed data endpoints

- Add negotiated control, realtime, and bulk-stream profiles with bounded scheduling and backend-independent routing.
- Stream large payloads with windowed acknowledgements, backpressure, retries, cancellation, timeouts, and end-to-end integrity checks.
- Prefer confirmed routes for typed messages while retaining legacy delivery for older peers and canonicalizing relayed sender identities.

Author: BAKAOLC

src/Networking/Sidecar/Core/Handlers/RitsuLibSidecarBuiltInHandlers.cs

@@ -5,15 +5,6 @@ namespace STS2RitsuLib.Networking.Sidecar
 {
     internal static class RitsuLibSidecarBuiltInHandlers
     {
-        private const RitsuLibSidecarPeerFeatures SupportedFeatures =
-            RitsuLibSidecarPeerFeatures.ChunkedStreams |
-            RitsuLibSidecarPeerFeatures.ManagedNetActions |
-            RitsuLibSidecarPeerFeatures.BrotliPayloadCompression |
-            RitsuLibSidecarPeerFeatures.ModelRightClickV2 |
-            RitsuLibSidecarPeerFeatures.DeveloperActionsV1 |
-            RitsuLibSidecarInternalPeerFeatures.MonsterIntentActionsV1 |
-            RitsuLibSidecarInternalPeerFeatures.ExtendedDeveloperStateActionsV1;
-
         private static readonly RitsuLibSidecarChunkReassembly Chunks = new();
 
         internal static void Register()
@@ -145,7 +136,7 @@ private static void OnHandshake(RitsuLibSidecarDispatchContext ctx)
                 buf.AsSpan(),
                 selected,
                 ok,
-                SupportedFeatures);
+                RitsuLibSidecarSupportedFeatures.All);
             var rm = RunManager.Instance;
             if (ctx.IsHostIngest)
                 RitsuLibSidecarHighLevelSend.TrySendAsHostToPeer(
@@ -162,7 +153,7 @@ private static void OnHandshake(RitsuLibSidecarDispatchContext ctx)
                     RitsuLibSidecarDeliverySemantics.StableSync);
 
             RitsuLibFramework.Logger.Debug(
-                $"[Sidecar] Handshake ack sent target={ctx.SenderNetId}, opcode={RitsuLibSidecarControlOpcodes.HandshakeAck}, payloadLen={buf.Length}, selectedWire={selected}, ok={ok}, senderFeatures={SupportedFeatures}");
+                $"[Sidecar] Handshake ack sent target={ctx.SenderNetId}, opcode={RitsuLibSidecarControlOpcodes.HandshakeAck}, payloadLen={buf.Length}, selectedWire={selected}, ok={ok}, senderFeatures={RitsuLibSidecarSupportedFeatures.All}");
         }
 
         private static void OnHandshakeAck(RitsuLibSidecarDispatchContext ctx)

src/Networking/Sidecar/Core/Messaging/RitsuLibSidecarTypedMessages.cs

@@ -1,4 +1,5 @@
 using System.Text.Json;
+using MegaCrit.Sts2.Core.Multiplayer;
 using MegaCrit.Sts2.Core.Multiplayer.Game;
 using MegaCrit.Sts2.Core.Multiplayer.Transport;
 using MegaCrit.Sts2.Core.Runs;
@@ -72,10 +73,24 @@ public readonly record struct SidecarTypedMessageReceivedEvent(
     ///     </para>
     ///     <para xml:lang="zh-CN">用于类型化 Sidecar 描述符注册、冲突检查、订阅及便捷发送的注册表。</para>
     /// </summary>
+    /// <remarks>
+    ///     <para xml:lang="en">
+    ///         Registered descriptors receive a bounded routed-endpoint compatibility bridge when local capacity permits.
+    ///         Convenience sends prefer the routed path for each compatible, route-confirmed recipient and use the legacy
+    ///         opcode path only for recipients or payloads that cannot use it. Split broadcasts never send both paths to
+    ///         the same recipient.
+    ///     </para>
+    ///     <para xml:lang="zh-CN">
+    ///         本地容量允许时，已注册描述符会获得有界的路由端点兼容桥。便捷发送会针对每个兼容且已确认路由的
+    ///         接收方优先使用新路径，仅在接收方或载荷不适用时回退旧操作码路径；拆分广播绝不会向同一接收方
+    ///         同时发送两条路径。
+    ///     </para>
+    /// </remarks>
     public static class RitsuLibSidecarTypedMessageRegistry
     {
         private static readonly Lock Gate = new();
         private static readonly Dictionary<ulong, RegistrationBase> Registrations = [];
+        private static int _migrationEndpointCount;
 
         /// <summary>
         ///     <para xml:lang="en">Raised after any typed message is successfully deserialized and dispatched.</para>
@@ -100,6 +115,7 @@ public static ulong Register<T>(RitsuLibSidecarMessageDescriptor<T> descriptor)
             ArgumentException.ThrowIfNullOrEmpty(descriptor.MessageKey);
             ArgumentNullException.ThrowIfNull(descriptor.Serialize);
             ArgumentNullException.ThrowIfNull(descriptor.Deserialize);
+            RitsuLibSidecarProtocol.EnsureDefaultHandlers();
 
             var opcode = RitsuLibSidecarOpcodes.For(descriptor.ModuleId, descriptor.MessageKey);
             lock (Gate)
@@ -121,6 +137,7 @@ public static ulong Register<T>(RitsuLibSidecarMessageDescriptor<T> descriptor)
                     descriptor.Serialize,
                     descriptor.Deserialize,
                     descriptor.Delivery);
+                TryAttachMigrationEndpoint(opcode, reg);
                 Registrations[opcode] = reg;
                 RitsuLibSidecarBus.RegisterHandler(opcode, ctx => HandleDispatch(opcode, reg, in ctx));
             }
@@ -170,8 +187,18 @@ public static bool SendToHost<T>(INetGameService? netService, RitsuLibSidecarMes
             T message)
         {
             var opcode = Register(descriptor);
-            var payload = descriptor.Serialize(message);
-            return RitsuLibSidecarHighLevelSend.TrySendAsClient(netService, opcode, payload, descriptor.Delivery);
+            var registration = GetRegistration<T>(opcode);
+            var payload = SerializePayload(registration, message);
+            if (CanUseRoutedPath(netService) && registration.EndpointHandle is { } endpoint)
+            {
+                var result = endpoint.SendToHost(payload);
+                if (result.IsAccepted)
+                    return true;
+                if (!ShouldFallbackToLegacy(result.Status))
+                    return false;
+            }
+
+            return RitsuLibSidecarHighLevelSend.TrySendAsClient(netService, opcode, payload, registration.Delivery);
         }
 
         /// <summary>
@@ -181,9 +208,7 @@ public static bool SendToHost<T>(INetGameService? netService, RitsuLibSidecarMes
         public static bool SendToHost<T>(RunManager? runManager, RitsuLibSidecarMessageDescriptor<T> descriptor,
             T message)
         {
-            var opcode = Register(descriptor);
-            var payload = descriptor.Serialize(message);
-            return RitsuLibSidecarHighLevelSend.TrySendAsClient(runManager, opcode, payload, descriptor.Delivery);
+            return SendToHost(runManager?.NetService, descriptor, message);
         }
 
         /// <summary>
@@ -194,9 +219,19 @@ public static bool SendToPeer<T>(INetGameService? netService, ulong peerNetId,
             RitsuLibSidecarMessageDescriptor<T> descriptor, T message)
         {
             var opcode = Register(descriptor);
-            var payload = descriptor.Serialize(message);
+            var registration = GetRegistration<T>(opcode);
+            var payload = SerializePayload(registration, message);
+            if (CanUseRoutedPath(netService) && registration.EndpointHandle is { } endpoint)
+            {
+                var result = endpoint.SendToPeer(peerNetId, payload);
+                if (result.IsAccepted)
+                    return true;
+                if (!ShouldFallbackToLegacy(result.Status))
+                    return false;
+            }
+
             return RitsuLibSidecarHighLevelSend.TrySendAsHostToPeer(netService, peerNetId, opcode, payload,
-                descriptor.Delivery);
+                registration.Delivery);
         }
 
         /// <summary>
@@ -207,9 +242,40 @@ public static bool Broadcast<T>(INetGameService? netService, RitsuLibSidecarMess
             T message)
         {
             var opcode = Register(descriptor);
-            var payload = descriptor.Serialize(message);
-            return RitsuLibSidecarHighLevelSend.TrySendAsHostBroadcast(netService, opcode, payload,
-                descriptor.Delivery);
+            var registration = GetRegistration<T>(opcode);
+            var payload = SerializePayload(registration, message);
+            if (!CanUseRoutedPath(netService) ||
+                netService is not NetHostGameService { IsConnected: true } host ||
+                registration.EndpointHandle is not { } endpoint)
+                return RitsuLibSidecarHighLevelSend.TrySendAsHostBroadcast(
+                    netService,
+                    opcode,
+                    payload,
+                    registration.Delivery);
+
+            var routedParticipants = endpoint.GetParticipantsSnapshot().ToHashSet();
+            foreach (var peer in host.ConnectedPeers)
+            {
+                if (!peer.readyForBroadcasting ||
+                    !RitsuLibSidecarSessionManager.CanSendToPeer(peer.peerId))
+                    continue;
+
+                if (routedParticipants.Contains(peer.peerId))
+                {
+                    var result = endpoint.SendToPeer(peer.peerId, payload);
+                    if (result.IsAccepted || !ShouldFallbackToLegacy(result.Status))
+                        continue;
+                }
+
+                RitsuLibSidecarHighLevelSend.TrySendAsHostToPeer(
+                    netService,
+                    peer.peerId,
+                    opcode,
+                    payload,
+                    registration.Delivery);
+            }
+
+            return true;
         }
 
         /// <summary>
@@ -219,24 +285,93 @@ public static bool Broadcast<T>(INetGameService? netService, RitsuLibSidecarMess
         public static bool Broadcast<T>(RunManager? runManager, RitsuLibSidecarMessageDescriptor<T> descriptor,
             T message)
         {
-            var opcode = Register(descriptor);
-            var payload = descriptor.Serialize(message);
-            return RitsuLibSidecarHighLevelSend.TrySendAsHostBroadcast(runManager, opcode, payload,
-                descriptor.Delivery);
+            return Broadcast(runManager?.NetService, descriptor, message);
+        }
+
+        private static void TryAttachMigrationEndpoint<T>(ulong opcode, Registration<T> registration)
+        {
+            if (_migrationEndpointCount >= RitsuLibSidecarEndpointPolicy.MaxLegacyTypedMigrationEndpoints)
+                return;
+            var deliveryProfile = ResolveDeliveryProfile(registration.Delivery);
+            var maxPayloadBytes = deliveryProfile == RitsuLibSidecarDeliveryProfile.Control
+                ? RitsuLibSidecarEndpointPolicy.MaxControlPayloadBytes
+                : RitsuLibSidecarEndpointPolicy.MaxRealtimePayloadBytes;
+            try
+            {
+                var endpoint = RitsuLibSidecarEndpoints.Register(
+                    new(
+                        "ritsulib.typed",
+                        $"message/{opcode:x16}",
+                        1,
+                        1,
+                        deliveryProfile,
+                        RitsuLibSidecarEndpointTopology.HostAuthority,
+                        maxPayloadBytes,
+                        RitsuLibSidecarEndpointDispatchMode.ReceiveThread),
+                    message => HandleEndpointDispatch(opcode, registration, message));
+                registration.AttachEndpoint(endpoint);
+                _migrationEndpointCount++;
+            }
+            catch (InvalidOperationException ex)
+            {
+                RitsuLibSidecarRepeatedWarningLog.Warn(
+                    $"typed-endpoint-unavailable:opcode={opcode}:{ex.Message}",
+                    $"[Sidecar] Routed typed-message endpoint unavailable opcode={opcode}; legacy path remains active: {ex.Message}");
+            }
+        }
+
+        private static void HandleEndpointDispatch<T>(
+            ulong opcode,
+            Registration<T> registration,
+            RitsuLibSidecarEndpointMessage endpointMessage)
+        {
+            var deliveryProfile = ResolveDeliveryProfile(registration.Delivery);
+            if (!RitsuLibSidecarEndpointTransport.TryGetNetworkParameters(
+                    deliveryProfile,
+                    out var transferMode,
+                    out var channel))
+                return;
+            HandlePayload(
+                opcode,
+                registration,
+                endpointMessage.Payload.Span,
+                endpointMessage.OriginalSenderNetId,
+                transferMode,
+                channel,
+                RitsuLibSidecarSessionManager.CurrentNetService is NetHostGameService);
         }
 
         private static void HandleDispatch<T>(ulong opcode, Registration<T> registration,
             in RitsuLibSidecarDispatchContext context)
+        {
+            HandlePayload(
+                opcode,
+                registration,
+                context.Payload.Span,
+                context.SenderNetId,
+                context.TransferMode,
+                context.Channel,
+                context.IsHostIngest);
+        }
+
+        private static void HandlePayload<T>(
+            ulong opcode,
+            Registration<T> registration,
+            ReadOnlySpan<byte> payload,
+            ulong senderNetId,
+            NetTransferMode transferMode,
+            int channel,
+            bool isHostIngest)
         {
             T message;
             try
             {
-                message = registration.Deserialize(context.Payload.Span);
+                message = registration.Deserialize(payload);
             }
             catch (Exception ex) when (RitsuLibExceptionPolicy.IsRecoverable(ex))
             {
                 RitsuLibSidecarRepeatedWarningLog.Warn(
-                    $"typed-deserialize:opcode={opcode}:sender={context.SenderNetId}:{ex.GetType().FullName}:{ex.Message}",
+                    $"typed-deserialize:opcode={opcode}:sender={senderNetId}:{ex.GetType().FullName}:{ex.Message}",
                     $"[Sidecar] Typed message deserialize failed opcode={opcode}: {ex.Message}");
                 return;
             }
@@ -249,15 +384,54 @@ private static void HandleDispatch<T>(ulong opcode, Registration<T> registration
 
             var typedContext = new RitsuLibSidecarTypedDispatchContext<T>(
                 message,
-                context.SenderNetId,
-                context.TransferMode,
-                context.Channel,
-                context.IsHostIngest);
+                senderNetId,
+                transferMode,
+                channel,
+                isHostIngest);
             foreach (var handler in handlers)
                 handler(typedContext);
 
             TypedMessageReceived?.Invoke(
-                new(opcode, registration.ModuleId, registration.MessageKey, context.SenderNetId));
+                new(opcode, registration.ModuleId, registration.MessageKey, senderNetId));
+        }
+
+        private static Registration<T> GetRegistration<T>(ulong opcode)
+        {
+            lock (Gate)
+            {
+                return Registrations.TryGetValue(opcode, out var registration) &&
+                       registration is Registration<T> typed
+                    ? typed
+                    : throw new InvalidOperationException(
+                        "Typed descriptor registered with incompatible payload type.");
+            }
+        }
+
+        private static byte[] SerializePayload<T>(Registration<T> registration, T message)
+        {
+            return registration.Serialize(message)
+                   ?? throw new InvalidOperationException("Typed message serializer returned null.");
+        }
+
+        private static bool CanUseRoutedPath(INetGameService? netService)
+        {
+            return ReferenceEquals(netService, RitsuLibSidecarSessionManager.CurrentNetService);
+        }
+
+        private static bool ShouldFallbackToLegacy(RitsuLibSidecarSendStatus status)
+        {
+            return status is RitsuLibSidecarSendStatus.RouteUnavailable
+                or RitsuLibSidecarSendStatus.ProfileUnsupported
+                or RitsuLibSidecarSendStatus.PayloadTooLarge
+                or RitsuLibSidecarSendStatus.DestinationUnavailable;
+        }
+
+        private static RitsuLibSidecarDeliveryProfile ResolveDeliveryProfile(
+            RitsuLibSidecarDeliverySemantics delivery)
+        {
+            return delivery == RitsuLibSidecarDeliverySemantics.BestEffort
+                ? RitsuLibSidecarDeliveryProfile.RealtimeDatagram
+                : RitsuLibSidecarDeliveryProfile.Control;
         }
 
         private abstract class RegistrationBase(string moduleId, string messageKey)
@@ -278,6 +452,12 @@ private sealed class Registration<T>(
             public Func<ReadOnlySpan<byte>, T> Deserialize { get; } = deserialize;
             public RitsuLibSidecarDeliverySemantics Delivery { get; } = delivery;
             public List<Action<RitsuLibSidecarTypedDispatchContext<T>>> Handlers { get; } = [];
+            public RitsuLibSidecarEndpointHandle? EndpointHandle { get; private set; }
+
+            public void AttachEndpoint(RitsuLibSidecarEndpointHandle endpoint)
+            {
+                EndpointHandle = endpoint;
+            }
         }
 
         private sealed class Subscription(Action dispose) : IDisposable

src/Networking/Sidecar/Core/RitsuLibSidecarProtocol.cs

@@ -52,6 +52,7 @@ public static void EnsureDefaultHandlers()
                     RitsuLibSidecarSessionManager.EnsureProvidersBootstrapped();
                     RitsuLibSidecarBuiltInHandlers.Register();
                     RitsuLibSidecarSyncMessages.RegisterBuiltInHandler();
+                    RitsuLibSidecarEndpointProtocol.EnsureRegistered();
                     ModRightClickRegistry.RegisterBuiltInSyncDescriptors();
                     RitsuDebugActionProtocol.EnsureHandlersRegistered();
                     RitsuLibSidecarNetworkingLifecycle.EnsureHooksInstalled();