Packet Framing — Magic Terminator

This short note explains how packets are framed and reassembled in the network packages, at a logical level. The framing strategy is simple and robust to transport fragmentation or aggregation.

Concept

  • Each logical packet is a payload of bytes that the application wants to send (JSON or binary).

  • Before sending, the library appends a configurable terminator string (the “magic value”) to the end of the payload. The default value in the project config is PACKET_END.

  • The terminator is applied as bytes (UTF-8 encoding of the configured string) and therefore forms a unique byte suffix that marks the end of a logical packet.

Why an end terminator

  • Transports like WebSocket and RTC DataChannels may split or combine application messages into arbitrary chunks. A terminator lets a receiver reliably detect the end of each logical packet regardless of how the transport fragments or aggregates bytes.

  • Using a short, human-readable terminator makes debugging easier.

  • The terminator is configurable so you can pick a value that does not collide with your payload contents (especially important if using raw or binary payloads).

Sender logic

  1. Serialize the application message into bytes (e.g., JSON => UTF-8 bytes, or a binary codec output).

  2. Append the configured terminator bytes to the end of the payload.

  3. Send the resulting buffer on the transport (WebSocket or DataChannel).

Receiver logic

  1. Accumulate incoming chunks of bytes into a per-connection buffer.

  2. Repeatedly search the accumulated buffer for the terminator sequence.

  3. For each occurrence, extract bytes from buffer start up to (but not including) the terminator — this is a complete logical packet.

  4. Remove the extracted packet and trailing terminator from the buffer and continue searching; keep any leftover bytes (partial packet) for the next incoming chunk.