feat(network): offload packet codec to an async strand pool

[wu-vincent]

Closes #356.

What this does

Splices an ABI-compatible AsyncBatchedNetworkPeer into each connection's peer chain in place of BDS's BatchedNetworkPeer (via an onNewIncomingConnection hook), moving that connection's decrypt/decompress/compress/encrypt onto a boost::asio worker pool once the connection authenticates. Modelled on Netty: the pool is an EventLoopGroup, and each connection binds to one EventLoop (a serialized strand) that handles both directions.

It derives from a full layout reconstruction of BatchedNetworkPeer (344 bytes, mAsyncEnabled at +0x150) so BDS's enableAsyncFlush writes the inherited flag — which gates activation: the whole handshake (encryption/compression setup) stays synchronous on the main thread, so there's no async window to race. PacketSendEvent/PacketReceiveEvent and packet patching always fire on the main thread; only the inner-chain codec runs on the event loop.

Thread-safe receive (BufferedRakNetPeer)

The inner chain ends at BDS's RakNetNetworkPeer, which keeps each connection's received packets in an unsynchronized per-peer buffer (mReadBufferDatas), filled by RakNetConnector::runEvents → newData() on the main thread. Decoding inbound packets on the strand would call RakNetNetworkPeer::_receivePacket from a worker and race that buffer.

To keep RakNet's buffer main-thread-only, a lightweight BufferedRakNetPeer is spliced at the bottom of the chain, wrapping the RakNetNetworkPeer:

• its update() runs on the main thread (the per-tick update chain — the same thread as newData) and drains RakNet's buffer into a single-producer/single-consumer queue;
• its _receivePacket() runs on the strand during decrypt/decompress and just pops that queue.

So the strand-side codec never touches RakNet's buffer. The inner-chain update() runs on the main thread (it forwards, does RakNet telemetry, and the drain) — mirroring BDS's own async model, where the codec sendPacket runs on a worker while update() runs on main.

Data flow

• Send (main → strand): sendPacket fires PacketSendEvent + patching and batches on the main thread; flush() extracts the batch and posts peer_->sendPacket (compress → encrypt → RakNet) to the strand.
• Receive (main → strand → main): BufferedRakNetPeer::update() drains RakNet on the main thread into its SPSC queue; a recvLoop on the strand pulls from it through decrypt/decompress into a second SPSC queue; the main-thread _sortAndPacketizeEvents pops the decoded queue and fires PacketReceiveEvent in arrival order.

NetworkPeer gains default chain-forwarding implementations for the pass-through virtuals so wrapper peers (BufferedRakNetPeer) need not reimplement them. AsyncBatchedNetworkPeer uses enable_shared_from_this so an in-flight task keeps the peer alive across teardown. The EventLoopGroup is RAII, owned by EndstoneServer via unique_ptr (ctor starts the workers, dtor joins them).

Builds and links cleanly on Windows (endstone_runtime.dll); the layout static_assert holds, and the server accepts connections / gameplay on 1.26.20.5.

Thread-safety summary

Every piece of mutable state has a single owning lane, crossing lanes only through the two SPSC queues:

• RakNet read buffer (mReadBufferDatas): main only (newData + BufferedRakNetPeer::update poll).
• Codec (compress / decompress / encrypt / decrypt): strand only, serialized per connection (a connection's cipher/HMAC chain is inherently serial).
• Plugin events (PacketSend/ReceiveEvent, packet patching): main only.
• Two SPSC queues (raw-from-RakNet, decoded-to-main): one producer / one consumer each; the strand serializes its side and provides happens-before between handlers even though it hops worker threads.
• Send batch / Batched decode buffers: main-only / strand-only, with a clean handoff at activation.
• activated_: main only (non-atomic by design); recv_scheduled_: atomic, single-in-flight recvLoop guard.

Verified against BDS 1.26.10.4

• Codec update() does no send-side work. CompressedNetworkPeer/EncryptedNetworkPeer don't override update()/flush(); they inherit NetworkPeer::update(), which is literally if (mPeer) mPeer->update();. So running the inner-chain update() on the main thread only forwards (plus the BufferedRakNetPeer drain + RakNet telemetry) and never touches codec state — making it safe alongside the strand codec. (This is also why the forwarding defaults added to NetworkPeer match BDS exactly.)
• Off-main teardown is safe. The inner-chain destructors are pure memory cleanup + atomic refcount ops: ~RakNetNetworkPeer frees its read/send buffers (no RakPeer close, no connector deregistration), ~EncryptedNetworkPeer frees its cipher/HMAC state, etc. So when the last shared_from_this() ref drops on a worker thread at teardown, destroying the chain there is fine.

Remaining / follow-ups

• [network] worker-thread-count config knob (currently auto = cpu - 2).
• 50+ connection load test (ordering / teardown validation).

🤖 Generated with Claude Code