Enhance sidecar networking with patches, logging, and trailer support#26
Merged
Conversation
…nced multiplayer support - Introduced a comprehensive sidecar networking system, including new classes for handling chunked data transmission, selective NACKs, and reassembly of data streams. - Added `RitsuLibSidecar` for building sidecar envelopes and managing opcode dispatching. - Implemented `RitsuLibSidecarChunkReassembly` to manage the reassembly of chunked data streams, improving data integrity during transmission. - Created handlers for various sidecar control opcodes, enhancing the responsiveness and reliability of multiplayer interactions. - Established diagnostic logging for checksum validation and divergence detection, ensuring robust error handling and debugging capabilities. - Updated `PatcherSetup` to register new patches related to sidecar networking, integrating them into the existing patching framework.
…cking and cancellation features - Added `GetPendingWaiterCount` method to retrieve the number of active waiters for asynchronous operations. - Implemented `CancelAllPendingWaits` to clear all pending waiters and complete their tasks as canceled, improving resource management. - Introduced `RitsuLibSidecarChunkStreamSendProgress` and `RitsuLibSidecarChunkReceiveProgress` records to track progress during chunked data transmission and reception. - Updated chunk handling methods to notify progress, enhancing user feedback during data transfers. - Integrated logging for inbound and outbound packets, improving diagnostics and monitoring capabilities.
…y handshake - Introduced `RitsuLibSidecarLobbyHelloPatch` to send a sidecar handshake after lobby construction, enabling early network communication before the `RunManager` assigns a `NetService`. - Updated `PatcherSetup` to register the new patch, enhancing multiplayer lobby functionality. - Refactored existing methods to improve the handling of network service interactions during lobby setup.
…nections - Introduced `TrySendAsHostBroadcastToAllConnected` method to enable the host to broadcast messages to all connected clients, enhancing communication during lobby setup. - Updated `RitsuLibSidecarLobbyHelloPatch` to ensure proper handshake after a client connects to the lobby, improving multiplayer synchronization. - Registered the new `RitsuLibSidecarStartRunLobbyHostClientConnectedPatch` in `PatcherSetup`, facilitating seamless lobby interactions.
…cleanup - Registered new patches: `RitsuLibSidecarStartRunLobbyHostClientDisconnectedPatch` and `RitsuLibSidecarPreRunCapabilityGatePatch` to improve lobby and capability handling. - Removed obsolete files related to chunked data handling and connection exchange, streamlining the sidecar networking codebase. - Introduced `RitsuLibSidecarProtocol` to manage default handler installations, ensuring robust sidecar communication. - Added `RitsuLibSidecarReceivePipeline` for improved packet processing and dispatching, enhancing overall network performance.
…ication - Added `RitsuLibSidecarNativeTrailerLayout` to define the structure of the native trailer for network packets. - Implemented `RitsuLibSidecarNativeTrailerEvidence` to manage trailer evidence and support packet processing. - Registered new patches: `RitsuLibSidecarNativeTrailerSendPatch` for appending trailers to outgoing packets and `RitsuLibSidecarNativeTrailerValidationRoute` for validating incoming trailers. - Updated existing patches to observe inbound trailers, enhancing the sidecar's ability to handle native trailer data. - Enhanced `PatcherSetup` to include the new trailer-related patches, improving overall sidecar functionality.
…ostics - Added detailed debug and info logging for various sidecar events, including selective NACKs, reassembly completions, and handshake processes. - Updated `RitsuLibSidecarNetDiagnosticsOptions` to remove obsolete tracing options, streamlining diagnostic settings. - Refactored logging levels in `RitsuLibSidecarNetTrace` to improve clarity and reduce verbosity in logs. - Enhanced `RitsuLibSidecarConnectionExchange` to log handshake events, improving traceability of connection states.
…tiveTrailerEvidence - Enhanced trailer detection by implementing TryLocateTrailerStart method to accurately locate the start of the trailer in packet bytes. - Updated payload length calculation to use the newly determined trailer start, ensuring correct processing of incoming packets. - Refactored trailer extraction logic to improve clarity and maintainability of the code.
There was a problem hiding this comment.
Pull request overview
This PR adds a new “Sidecar” networking layer to STS2-RitsuLib, integrating with the vanilla multiplayer transport via Harmony patches and providing a structured envelope protocol, opcode dispatch, capability discovery/validation, and higher-level utilities (typed messaging, request/reply, chunking, diagnostics, config sync).
Changes:
- Introduces a sidecar envelope wire format (magic + version + flags + opcode + extension + payload) with optional gzip, delivery semantics tagging, and header correlation support.
- Adds core runtime infrastructure: send helpers, opcode bus + waiters, typed message registry, request/reply helpers, chunked streaming + gap recovery, and diagnostics/trace counters.
- Hooks into vanilla networking lifecycle via patches (receive demux, trailer evidence, lobby bind/peer connect tracking, pre-run capability gate, checksum divergence relay), plus a patch-info ID de-duplication improvement.
Reviewed changes
Copilot reviewed 75 out of 75 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| RitsuLibFramework.PatcherSetup.cs | Registers new sidecar-related patches into the framework patcher setup. |
| Patching/Models/IPatchMethod.cs | Improves patch info ID generation to avoid duplicate IDs when multiple targets share type+method name. |
| Networking/Sidecar/Transport/Policy/RitsuLibSidecarTransportTracePaths.cs | Defines trace “path” string constants for transport-level logging. |
| Networking/Sidecar/Transport/Core/RitsuLibSidecarSend.cs | Low-level raw envelope send helpers (client→host, host→peer, broadcasts) with tracing/counters. |
| Networking/Sidecar/Transport/Core/RitsuLibSidecarNetworkMapping.cs | Maps delivery semantics to transport mode/channel. |
| Networking/Sidecar/Transport/Core/RitsuLibSidecarHighLevelSend.cs | Higher-level send helpers that build delivery-tagged envelopes and pick channel/mode. |
| Networking/Sidecar/Transport/Core/RitsuLibSidecarControlPeerSend.cs | Internal helper for sending control opcodes to the correct net peer (host/client). |
| Networking/Sidecar/Session/Models/RitsuLibSidecarReachabilityModels.cs | Reachability enum + session/peer/handshake event record payloads. |
| Networking/Sidecar/Session/Lifecycle/RitsuLibSidecarNetworkingLifecycle.cs | Hooks lifecycle and per-frame processing to keep sidecar session state aligned with net service. |
| Networking/Sidecar/Session/Core/RitsuLibSidecarSessionManager.cs | Central sidecar session state: net service observation, peer reachability/features, provider routing. |
| Networking/Sidecar/Session/Core/RitsuLibSidecarConnectionSession.cs | Caches per-peer feature flags from handshake results. |
| Networking/Sidecar/Session/Core/RitsuLibSidecarConnectionExchange.cs | Initiates handshake control traffic once peers are deemed reachable. |
| Networking/Sidecar/Services/Config/RitsuLibSidecarConfigSyncService.cs | Host-authoritative config topic sync over sidecar typed messages (snapshot + request/decision). |
| Networking/Sidecar/Protocol/RitsuLibSidecarWireFlags.cs | Wire flags definition (e.g., gzip). |
| Networking/Sidecar/Protocol/RitsuLibSidecarWire.cs | Wire constants and helpers (magic, versions, caps, opcode peek). |
| Networking/Sidecar/Protocol/RitsuLibSidecarEnvelope.cs | Envelope build + parse, including header extension handling and gzip support. |
| Networking/Sidecar/Protocol/RitsuLibSidecarDeliverySemantics.cs | Delivery intent enum stored in header extension (best-effort vs stable sync). |
| Networking/Sidecar/Protocol/RitsuLibSidecarControlOpcodes.cs | Reserved opcode assignments for control-plane sidecar messages. |
| Networking/Sidecar/Protocol/RitsuLibSidecarCompression.cs | Gzip compress/decompress helpers used by envelope logic. |
| Networking/Sidecar/Protocol/Policy/RitsuLibSidecarPeerFeatures.cs | Feature-bit flags exchanged in handshake. |
| Networking/Sidecar/Protocol/Policy/RitsuLibSidecarOpcodes.cs | Stable mod/message opcode generation via hashing. |
| Networking/Sidecar/Protocol/Policy/RitsuLibSidecarControlOpcodeLayout.cs | Internal numeric layout for control opcodes. |
| Networking/Sidecar/Protocol/Layout/RitsuLibSidecarHandshakeLayout.cs | Binary offsets/sizes for handshake and handshake-ack payloads. |
| Networking/Sidecar/Protocol/Layout/RitsuLibSidecarHandshakeBinary.cs | Read/write handshake + ack payloads. |
| Networking/Sidecar/Protocol/Layout/RitsuLibSidecarEnvelopeLayout.cs | Binary offsets/sizes for envelope fields and extension subfields. |
| Networking/Sidecar/Protocol/Layout/RitsuLibSidecarChunkSelectiveNackLayout.cs | Binary layout for selective-NACK message header/ranges. |
| Networking/Sidecar/Protocol/Layout/RitsuLibSidecarChunkFrameLayout.cs | Binary layout for chunk frame header. |
| Networking/Sidecar/Protocol/Layout/RitsuLibSidecarBinaryLayout.cs | Shared primitive-size constants (byte/u16/u32/u64, KiB/MiB). |
| Networking/Sidecar/Protocol/Header/RitsuLibSidecarRequestCorrelation.cs | Correlation ID allocation + pack/unpack into header extension. |
| Networking/Sidecar/Protocol/Header/RitsuLibSidecarHeaderExtension.cs | Reads delivery semantics tag from header extension. |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkTransferNotifications.cs | Receive-side progress notification event for chunked streams. |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkStreamProgress.cs | Record structs for chunk send/reassembly progress reporting. |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkStream.cs | Chunked sending: segmentation + registration for retransmit support. |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkSendKind.cs | Internal enum describing chunk send direction (client/host unicast/broadcast). |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkReassembly.cs | Receiver-side chunk reassembly state machine + stale eviction. |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkOutboundRegistry.cs | Tracks outbound chunk frames for selective retransmit; TTL drop scheduling. |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkGapScheduler.cs | Debounced gap report scheduling (selective NACK emission). |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkGapBinary.cs | Binary encoding/decoding for selective NACK and reassembly-done payloads. |
| Networking/Sidecar/Protocol/Chunk/RitsuLibSidecarChunkBinary.cs | Binary encoding/decoding for chunk frame payload (includes CRC32). |
| Networking/Sidecar/Patches/RitsuLibSidecarPreRunCapabilityGatePatch.cs | Pre-run patch that validates required capabilities and can block BeginRun under “Fail”. |
| Networking/Sidecar/Patches/RitsuLibSidecarNetHostReceivePatch.cs | Host receive prefix to demux sidecar envelopes before vanilla NetMessageBus. |
| Networking/Sidecar/Patches/RitsuLibSidecarNetClientReceivePatch.cs | Client receive prefix to demux sidecar envelopes before vanilla NetMessageBus. |
| Networking/Sidecar/Patches/RitsuLibSidecarNativeTrailerSendPatch.cs | Transport send prefixes that append a native trailer marker to vanilla packets. |
| Networking/Sidecar/Patches/RitsuLibSidecarLobbyHelloPatch.cs | Lobby ctor + connect/disconnect patches to bind session manager and track peers early. |
| Networking/Sidecar/Patches/RitsuLibSidecarChecksumDivergenceRelayPatch.cs | Host hook to trigger coordinated diagnostic dump when vanilla checksum mismatch occurs. |
| Networking/Sidecar/Discovery/State/RitsuLibSidecarNativeTrailerEvidence.cs | Tracks trailer evidence per peer and triggers reachability refresh. |
| Networking/Sidecar/Discovery/State/RitsuLibSidecarCapabilityHints.cs | Manual reachability hint storage used by discovery routing. |
| Networking/Sidecar/Discovery/Routes/RitsuLibSidecarSteamLobbyValidationRoute.cs | Steam lobby member-data route for reachability discovery. |
| Networking/Sidecar/Discovery/Routes/RitsuLibSidecarNativeTrailerValidationRoute.cs | Native trailer evidence route for reachability discovery. |
| Networking/Sidecar/Discovery/Routes/RitsuLibSidecarManualHintValidationRoute.cs | Manual hint route for reachability discovery. |
| Networking/Sidecar/Discovery/Policy/RitsuLibSidecarDiscoveryPolicy.cs | Defines discovery route names, ordering, and reason strings. |
| Networking/Sidecar/Discovery/Layout/RitsuLibSidecarNativeTrailerLayout.cs | Binary layout for the appended native trailer marker. |
| Networking/Sidecar/Discovery/Contracts/RitsuLibSidecarCapabilityValidationRoute.cs | Interface contract for reachability validation routes. |
| Networking/Sidecar/Discovery/Contracts/RitsuLibSidecarCapabilityMarkers.cs | Constants for Steam lobby member-data markers. |
| Networking/Sidecar/Diagnostics/Trace/RitsuLibSidecarTrafficCounters.cs | Process-wide counters for observed sidecar traffic. |
| Networking/Sidecar/Diagnostics/Trace/RitsuLibSidecarPacketLog.cs | Bridge to trace inbound parsed packets. |
| Networking/Sidecar/Diagnostics/Trace/RitsuLibSidecarNetTrace.cs | Logger-backed trace helpers for inbound/outbound sidecar traffic. |
| Networking/Sidecar/Diagnostics/Trace/RitsuLibSidecarNetDiagnosticsOptions.cs | Diagnostics tunables (e.g., incomplete chunk retention window). |
| Networking/Sidecar/Diagnostics/Policy/RitsuLibSidecarDiagnosticPolicy.cs | Diagnostic policy constants (relay tags). |
| Networking/Sidecar/Diagnostics/Layout/RitsuLibSidecarDiagnosticRelayLayout.cs | Binary layout for diagnostic relay payload. |
| Networking/Sidecar/Diagnostics/Core/RitsuLibSidecarDiagnosticPayload.cs | Build/parse helpers for diagnostic relay payload. |
| Networking/Sidecar/Diagnostics/Core/RitsuLibSidecarChecksumDiagnostics.cs | Hooks checksum divergence and emits/handles sidecar diagnostic relay messages. |
| Networking/Sidecar/Core/Scheduling/RitsuLibSidecarGodotMainLoopScheduling.cs | Main-loop defer helpers + Task continuation marshaling. |
| Networking/Sidecar/Core/RitsuLibSidecarReceivePipeline.cs | Receive demux pipeline: parse envelope, trace/counters, dispatch via bus. |
| Networking/Sidecar/Core/RitsuLibSidecarProtocol.cs | One-time registration of built-in handlers and lifecycle hooks. |
| Networking/Sidecar/Core/Messaging/RitsuLibSidecarTypedMessages.cs | Typed message descriptor + registry, subscriptions, and convenience send APIs. |
| Networking/Sidecar/Core/Messaging/RitsuLibSidecarRequestReply.cs | Request/reply helpers built on bus waiters + correlation extension. |
| Networking/Sidecar/Core/Messaging/RitsuLibSidecarMessageBinding.cs | Convenience binding of codecs/processors onto bus, optionally on Godot main loop. |
| Networking/Sidecar/Core/Messaging/RitsuLibSidecarDispatchContext.cs | Dispatch context struct encapsulating transport metadata + parsed envelope. |
| Networking/Sidecar/Core/Messaging/RitsuLibSidecarCodecAbstractions.cs | Interfaces for message codecs and sync processors. |
| Networking/Sidecar/Core/Handlers/RitsuLibSidecarBuiltInHandlers.cs | Built-in handlers for handshake, chunk reassembly, diagnostics relay. |
| Networking/Sidecar/Core/Dispatch/RitsuLibSidecarBus.cs | Central opcode dispatch and waiter-based async “wait for next” support. |
| Networking/Sidecar/Core/Capabilities/RitsuLibSidecarRequiredCapabilities.cs | Registry + validator for required capabilities (warn/fail policy). |
| Networking/Sidecar/Core/Api/RitsuLibSidecarEvents.cs | Disposable subscribe/unsubscribe façade for sidecar events. |
| Networking/Sidecar/Core/Api/RitsuLibSidecar.cs | Public envelope builder APIs (with/without delivery tagging). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ssion management - Refactored `ValidatePeers` method to utilize a more efficient structure for capability checks, improving clarity and performance. - Updated `NoteHandshakeFromPeer` to include a parameter for handshake acceptance, allowing for better reachability management based on handshake results. - Enhanced `RitsuLibSidecarConfigSyncService` with improved error handling during JSON deserialization, ensuring robustness in state management. - Introduced a `TryDeserialize` method to simplify and centralize JSON parsing logic, enhancing maintainability across the service.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces several new static classes that provide core infrastructure for the Sidecar networking layer, including event subscription helpers, opcode dispatch, envelope construction, and required capability validation. These additions are designed to centralize and simplify common networking operations for consumers of the Sidecar API.
Key changes include:
Event and Handler Infrastructure:
RitsuLibSidecarEvents, a static class with helper methods to subscribe and unsubscribe from various session, peer, handshake, message, config, and capability events, returning disposable subscriptions for easy management.RitsuLibSidecarBus, a static class for registering, unregistering, and dispatching opcode handlers, supporting synchronous and asynchronous (waiter-based) dispatch, waiter cancellation, and handler clearing.Envelope and Capability Management:
RitsuLibSidecar, a static class for building sidecar envelopes, including support for delivery semantics and optional payload compression.RitsuLibSidecarRequiredCapabilities, a static class for registering required capability checks, validating peer capabilities, and raising events after validation runs. Includes supporting record types and an enum for policy configuration.