Fragmentation

MOSH fragmentation allows a logical message payload to be larger than a single on-wire frame.

The MOSH protocol standard limits the maximum encoded frame size to 1470 bytes. That full frame includes:

• 13-byte fixed header
• payload
• 2-byte CRC footer

That means the largest unfragmented payload is:

1470 - 13 - 2 = 1455 bytes

Any payload larger than 1455 bytes must be split into multiple fragment frames before transmission.

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

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.

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

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.

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.

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.