16kbUDP

Lightweight UDP‑based protocol with random magic, 16 KB fragmentation, optional zlib compression, CRC32 integrity check, and reliable stream abstraction powered by udp-stream.

---

Technical features

• Dynamic Magic Number – a random 16‑bit signature generated once per process (rand::random::<u16>() | 1). Every packet starts with this magic, making spoofing harder.

• Fixed 17‑byte header – contains magic, flags, 64‑bit message ID, fragment index, total fragments, and payload length. All fields are big‑endian.

• 16 KB packet limit – maximum packet size is 16 KiB; 17 bytes are reserved for the header, leaving 16 367 bytes for payload per fragment. This matches typical network MTU constraints.

• Automatic fragmentation & reassembly – messages larger than the payload limit are split into fragments. Each fragment carries the same message ID and total fragment count. The receiver collects fragments until all are received, then reassembles the original message.

• Optional zlib compression – compression can be enabled per message. The protocol compares compressed size vs. original and uses the smaller one. Compression level is configurable via ProtocolConfig.

• Reliability via udp-stream – instead of TCP, this protocol runs on top of UDP using the udp-stream crate, which provides a TCP‑like reliable, ordered stream abstraction over UDP. This combines the low latency of UDP with the convenience of stream‑oriented I/O.

• CRC32 integrity check – a 32‑bit CRC of the original data is prepended to the payload before compression (if enabled). On the receiver side, after reassembly and decompression, the CRC is verified. Mismatch causes an error, guaranteeing data integrity.

• Read timeout – all read operations are wrapped with tokio::time::timeout (configurable via read_timeout), preventing indefinite blocking on a stuck connection.

• Denial‑of‑Service protection – limits are placed on the number of active assemblers (max_assemblers) and completed message entries (max_completed). When exceeded, the oldest entries are evicted. This prevents memory exhaustion from malicious or misbehaving peers.

• Unique message IDs – 64‑bit message IDs are used, with the initial value generated randomly (rand::random::<u64>()) per Protocol instance. This eliminates collisions across different connections and simplifies reassembly.

• Duplex communication – a single Protocol instance can both send and receive messages over the same UDP stream.

• Asynchronous I/O (Tokio) – all network operations are non‑blocking, enabling high concurrency and scalability.

• Configurable – ProtocolConfig allows tuning of compression, timeouts, and limits.

• Simple public API – just send_message(data, compress) and receive_message() hide all fragmentation, compression, CRC, and reassembly details.

---

Example cargo run

[2026-09-01T11:19:42.225Z INFO  protocol] Server started on 127.0.0.1:8080
[2026-09-01T11:19:42.433Z INFO  protocol] Client connecting...
[2026-09-01T11:19:42.434Z INFO  protocol] Client: sending 30000 bytes with compression enabled
[2026-09-01T11:19:42.434Z INFO  protocol] Sending message 1687703051419411827 (size: 30000 bytes, compression: on)
[2026-09-01T11:19:42.435Z INFO  protocol] Message 1687703051419411827 compressed: 30004 -> 58 bytes
[2026-09-01T11:19:42.435Z INFO  protocol] Message 1687703051419411827 split into 1 fragments (max payload 16367 bytes)
[2026-09-01T11:19:42.436Z INFO  protocol] All fragments for message 1687703051419411827 sent
[2026-09-01T11:19:42.436Z INFO  protocol] Client: message sent
[2026-09-01T11:19:42.436Z INFO  protocol] Connection from 127.0.0.1:51848
[2026-09-01T11:19:42.436Z INFO  protocol] Message 1687703051419411827 assembled from 1 fragments, size 58 bytes, compressed: yes
[2026-09-01T11:19:42.437Z INFO  protocol] Message 1687703051419411827 decompressed: 58 -> 30004 bytes
[2026-09-01T11:19:42.437Z INFO  protocol] Message 1687703051419411827 fully assembled
[2026-09-01T11:19:42.437Z INFO  protocol] CRC check passed for message 1687703051419411827
[2026-09-01T11:19:42.437Z INFO  protocol] Server received message of 30000 bytes
[2026-09-01T11:19:42.437Z INFO  protocol] Sending message 8096899198721678054 (size: 30000 bytes, compression: on)
[2026-09-01T11:19:42.438Z INFO  protocol] Message 8096899198721678054 compressed: 30004 -> 58 bytes
[2026-09-01T11:19:42.438Z INFO  protocol] Message 8096899198721678054 split into 1 fragments (max payload 16367 bytes)
[2026-09-01T11:19:42.438Z INFO  protocol] All fragments for message 8096899198721678054 sent
[2026-09-01T11:19:42.439Z INFO  protocol] Message 8096899198721678054 assembled from 1 fragments, size 58 bytes, compressed: yes
[2026-09-01T11:19:42.439Z INFO  protocol] Message 8096899198721678054 decompressed: 58 -> 30004 bytes
[2026-09-01T11:19:42.439Z INFO  protocol] Message 8096899198721678054 fully assembled
[2026-09-01T11:19:42.440Z INFO  protocol] CRC check passed for message 8096899198721678054
[2026-09-01T11:19:42.440Z INFO  protocol] Client: received response of 30000 bytes
[2026-09-01T11:19:42.440Z INFO  protocol] Client: data matches, test passed!
[2026-09-01T11:19:42.440Z INFO  protocol] Client closed connection