Differences

This shows you the differences between two versions of the page.

--- mosh:protocol:layers:transport:fragmentation [2026/05/02 03:30] – created mosh
+++ mosh:protocol:layers:transport:fragmentation [2026/05/12 02:11] (current) – mosh
@@ Line 1: / Line 1: @@
-===== Fragmentation =====
+====== Fragmentation ======
-Fragmentation allows large payloads to be split into multiple frames when they exceed transport or protocol limits.
+MOSH fragmentation allows a logical message payload to be larger than a single on-wire frame.
-Responsibilities include:
+===== Why Fragmentation Exists =====
-Splitting payloads into ordered fragments
+The MOSH protocol standard limits the maximum encoded frame size to **1470 bytes**. That full frame includes:
-Assigning fragment identifiers and sequence indices
-Reassembly of complete messages on the receiving side
+  * 13-byte fixed header
-Handling missing or out-of-order fragments
+  * payload
+  * 2-byte CRC footer
+That means the largest unfragmented payload is:
+- 13 - 2 = 1455 bytes
+Any payload larger than **1455 bytes** must be split into multiple fragment frames before transmission.
+===== Fragment Format =====
+A fragment is still a normal MOSH frame, but it has the `FLAG_IS_FRAGMENT` bit set and uses the first 4 bytes of its payload as a fragment header:
+  * byte 0: fragment index
+  * byte 1: fragment count
+  * byte 2: original payload length, low byte
+  * byte 3: original payload length, high byte
+The remaining payload bytes in the fragment are fragment data.
+For a transport with a 1470-byte frame limit:
+  * max frame size: 1470
+  * fixed header: 13
+  * footer: 2
+  * payload area per fragment: 1455
+  * fragment header: 4
+  * usable data per fragment: 1451
+===== Send Path =====
+When a frame is sent, MOSH first checks whether the encoded frame would exceed the transport's maximum frame length.
+If it fits:
+  * the frame is sent as-is
+If it does not fit:
+  * the payload is split into multiple fragments
+  * each fragment gets the same message ID, source, destination, context, and TTL
+  * the fragment flag is set
+  * each fragment carries part of the original payload
+This means a large logical payload is transmitted as a sequence of smaller wire-safe frames.
+===== Receive Path =====
+On receipt, each frame is decoded normally.
+If the fragment flag is not set:
+  * the frame is delivered immediately
+If the fragment flag is set:
+  * the fragment is stored in a reassembly buffer
+  * fragments are grouped by source network ID, source node ID, and message ID
+  * once all fragments are present, the original payload is rebuilt in fragment-index order
+  * the fragment flag is cleared
+  * the completed frame is delivered as a normal logical frame
+===== Reassembly Rules =====
+A fragment set is considered valid only if:
+  * fragment count is not zero
+  * fragment index is less than fragment count
+  * all fragments agree on the original payload length
+  * the total reassembled payload length matches the declared original length
+If the fragment metadata changes mid-stream, or the final payload length does not match, the reassembly buffer is discarded.
+===== Limits =====
+There are two important limits:
+  * **Wire frame limit**: 1470 bytes maximum encoded frame size
+  * **Logical payload limit**: up to 65535 bytes, because original payload length is stored as a 16-bit value in the fragment header
+In practice, the true upper limit is also constrained by available RAM, especially on embedded devices such as the ESP32.
+===== Current Behavior =====
+On the current MOSH implementation:
+  * large logical payloads are fragmented automatically before send
+  * received fragments are reassembled automatically
+  * completed frames are exposed to higher-level code as normal non-fragmented logical frames
+As a result, application code can work with large payloads without needing to manually split or reassemble them.
-Fragmentation is optional and may be disabled on constrained devices or simple transports.