# Wiresocket Protocol Specification
> **DRAFT** — This document reflects implementation as of 2026-02-26 and is pending formal review.
Version: 1 (`noisePrologue = "wiresocket v1"`)
---
## 1. Overview
Wiresocket is a WireGuard-inspired, encrypted UDP event-stream protocol.
It provides a bidirectional, multi-channel event stream between a client and
server over a single UDP socket.
**Key properties:**
- **Transport**: UDP (connectionless)
- **Encryption**: Noise IK over X25519 / ChaCha20-Poly1305 / BLAKE2s
- **Authentication**: Both static keys (server always; client optionally)
- **Multiplexing**: up to 256 independent channels per session (channel IDs 0–255)
- **Fragmentation**: frames exceeding one UDP datagram are split across up to 65 535 fragments
- **DoS mitigation**: WireGuard-style cookies (XChaCha20-Poly1305)
- **Replay protection**: 4096-entry sliding window
- **Reliable delivery**: optional per-channel sequencing, cumulative + selective ACKs (SACK), retransmit with exponential backoff, and window-based flow control
- **Rate limiting**: optional per-session send rate cap (token bucket; configurable bytes-per-second)
All multi-byte integers are **little-endian** unless stated otherwise.
---
## 2. Cryptographic Primitives
| Primitive | Algorithm | Notes |
|---|---|---|
| DH | X25519 (RFC 7748) | Low-order-point rejection enforced |
| AEAD (handshake) | ChaCha20-Poly1305 (RFC 8439) | |
| AEAD (transport) | ChaCha20-Poly1305 | One AEAD instance per direction, cached per session |
| AEAD (cookie reply) | XChaCha20-Poly1305 | 24-byte random nonce |
| Hash | BLAKE2s-256 | |
| MAC | Keyed BLAKE2s-256 | `BLAKE2s(key=K, data=D)` |
| KDF | HKDF-BLAKE2s | See §2.1 |
| Keypairs | X25519 | RFC 7748 clamping applied |
### 2.1 KDF
```
prk = MAC(key=ck, data=input)
T[1] = MAC(key=prk, data=0x01)
T[i] = MAC(key=prk, data=T[i-1] || byte(i))
```
`kdf2(ck, input)` returns `(T[1], T[2])`.
`kdf3(ck, input)` returns `(T[1], T[2], T[3])`.
### 2.2 Initial chaining key and hash
```
initialCK = "Noise_IK_25519_ChaChaPoly_BLAKE2s" (zero-padded to 32 bytes)
initialH = HASH(initialCK || "wiresocket v1")
```
Both are computed once at process startup.
### 2.3 AEAD nonce
Transport AEAD nonces are 12 bytes:
```
nonce[0:4] = 0x00 0x00 0x00 0x00
nonce[4:12] = counter (uint64 LE)
```
### 2.4 MAC1 derivation
```
mac1_key = HASH("mac1----" || receiver_static_pub)
MAC1 = MAC(mac1_key, message_body)[0:16]
```
`message_body` is everything in the serialised message before the MAC fields.
### 2.5 MAC2 derivation
```
MAC2 = MAC(key=cookie[0:16] zero-extended to 32 bytes, data=message_body)[0:16]
```
---
## 3. Packet Types
The first byte of every UDP datagram is a **type tag**:
| Value | Name | Size (bytes) |
|---|---|---|
| 1 | HandshakeInit | 148 |
| 2 | HandshakeResp | 92 |
| 3 | CookieReply | 64 |
| 4 | Data | 16 + ciphertext |
| 5 | Disconnect | 32 (16 header + 16 AEAD tag) |
| 6 | Keepalive | 32 (16 header + 16 AEAD tag) |
| 7 | DataFragment | 16 + ciphertext |
---
## 4. Wire Formats
### 4.1 HandshakeInit (type 1, 148 bytes)
Sent by the initiator to begin a session.
```
Offset Size Field
------ ---- -----
0 1 type = 0x01
1 3 reserved (zero)
4 4 sender_index uint32 LE — initiator's session token
8 32 ephemeral initiator ephemeral public key (X25519)
40 48 encrypted_static AEAD(initiator static pub key, 32 plain + 16 tag)
88 28 encrypted_timestamp AEAD(TAI64N timestamp, 12 plain + 16 tag)
116 16 mac1 MAC1 keyed by responder's static pub
132 16 mac2 MAC2 keyed by cookie (zeros if no cookie)
```
`sender_index` is a random 32-bit token chosen by the initiator.
It is used as `receiver_index` in all subsequent packets the server sends
to this session.
`encrypted_timestamp` carries a 12-byte TAI64N timestamp
(`uint64 BE seconds` || `uint32 BE nanoseconds`).
The TAI epoch offset applied is `0x4000000000000000`.
The responder rejects timestamps more than ±180 seconds from its own clock.
### 4.2 HandshakeResp (type 2, 92 bytes)
Sent by the responder in reply to a valid HandshakeInit.
```
Offset Size Field
------ ---- -----
0 1 type = 0x02
1 3 reserved (zero)
4 4 sender_index uint32 LE — responder's session token
8 4 receiver_index uint32 LE — echoes initiator's sender_index
12 32 ephemeral responder ephemeral public key (X25519)
44 16 encrypted_nil AEAD(empty plaintext) — 0 plain + 16 tag
60 16 mac1 MAC1 keyed by initiator's static pub
76 16 mac2 MAC2 keyed by cookie (zeros if no cookie)
```
### 4.3 CookieReply (type 3, 64 bytes)
Sent by the server instead of HandshakeResp when under load.
The cookie must be used in MAC2 of the retried HandshakeInit.
```
Offset Size Field
------ ---- -----
0 1 type = 0x03
1 3 reserved (zero)
4 4 receiver_index uint32 LE — echoes initiator's sender_index
8 24 nonce random 24-byte XChaCha20 nonce
32 32 encrypted_cookie XChaCha20-Poly1305(cookie, 16 plain + 16 tag)
```
The XChaCha20-Poly1305 key is the MAC1 from the HandshakeInit zero-extended
to 32 bytes. Only the genuine initiator (who knows its own MAC1) can decrypt
the cookie.
### 4.4 Data (type 4)
Carries one encrypted Frame. Total size: `16 + len(plaintext) + 16`.
```
Offset Size Field
------ ---- -----
0 1 type = 0x04
1 3 reserved (zero)
4 4 receiver_index uint32 LE — recipient's session token
8 8 counter uint64 LE — monotonic send counter
16 N+16 ciphertext ChaCha20-Poly1305(frame_bytes, N plain + 16 tag)
```
AAD is empty. The nonce is constructed from `counter` (see §2.3).
### 4.5 Disconnect (type 5, 32 bytes)
Authenticated graceful shutdown notification. Same header layout as Data
with an AEAD over empty plaintext.
```
Offset Size Field
------ ---- -----
0 1 type = 0x05
1 3 reserved (zero)
4 4 receiver_index uint32 LE
8 8 counter uint64 LE
16 16 AEAD tag ChaCha20-Poly1305(empty) — 0 plain + 16 tag
```
### 4.6 Keepalive (type 6, 32 bytes)
Liveness probe. Same layout as Disconnect with type 6.
```
Offset Size Field
------ ---- -----
0 1 type = 0x06
1 3 reserved (zero)
4 4 receiver_index uint32 LE
8 8 counter uint64 LE
16 16 AEAD tag ChaCha20-Poly1305(empty) — 0 plain + 16 tag
```
A keepalive is sent whenever no data has been exchanged for `KeepaliveInterval`
(default 10 s). The counter participates in replay protection.
### 4.7 DataFragment (type 7)
Carries one encrypted fragment of a large Frame.
Total size: `16 + 8 + len(frag_data) + 16`.
```
Offset Size Field
------ ---- -----
0 1 type = 0x07
1 3 reserved (zero)
4 4 receiver_index uint32 LE
8 8 counter uint64 LE
16 N+24 ciphertext ChaCha20-Poly1305(frag_plain, (8+M) plain + 16 tag)
```
The **plaintext** inside the ciphertext has its own sub-header:
```
Plain offset Size Field
------------ ---- -----
0 4 frame_id uint32 LE — unique per frame within a session
4 2 frag_index uint16 LE — zero-based index of this fragment
6 2 frag_count uint16 LE — total number of fragments (1–65535)
8 M frag_data raw fragment bytes
```
`frame_id` is a monotonically increasing counter scoped to the sending session.
All fragments of the same frame share the same `frame_id`.
---
## 5. Noise IK Handshake
The handshake follows the **Noise IK** pattern
(`Noise_IK_25519_ChaChaPoly_BLAKE2s`):
```
Pre-messages:
-> s (responder's static public key known to initiator out-of-band)
Messages:
-> e, es, s, ss (HandshakeInit)
<- e, ee, se (HandshakeResp)
```
### 5.1 Symmetric State
Both sides maintain a symmetric state `(ck, h, k, nonce)`:
- `ck` — chaining key, starts as `initialCK`
- `h` — transcript hash, starts as `initialH`
- `k` — current AEAD key (empty until first `mixKey`)
- `nonce` — per-key counter, reset to 0 on each `mixKey`
**`mixHash(data)`**: `h = HASH(h || data)`
**`mixKey(dh_out)`**: `(ck, k) = kdf2(ck, dh_out)` ; `nonce = 0`
**`encryptAndHash(plain)`**: `c = AEAD_Seal(k, nonce++, h, plain)` ; `mixHash(c)` ; return `c`
**`decryptAndHash(cipher)`**: `p = AEAD_Open(k, nonce++, h, cipher)` ; `mixHash(cipher)` ; return `p`
### 5.2 Initiator: CreateInit
Starting state: `ck = initialCK`, `h = HASH(initialCK || "wiresocket v1")`.
```
Pre-message:
mixHash(responder_static_pub)
Message construction:
mixHash(e_pub) # -> e
(ck, k) = kdf2(ck, DH(e_priv, s_resp_pub)) # -> es
encrypted_static = encryptAndHash(s_init_pub) # -> s
(ck, k) = kdf2(ck, DH(s_init_priv, s_resp_pub)) # -> ss
encrypted_timestamp = encryptAndHash(TAI64N())
mac1 = MAC1(responder_static_pub, msg_body_without_macs)
mac2 = MAC2(cookie, msg_body_without_mac2) # zero if no cookie
```
### 5.3 Responder: ConsumeInit
```
Pre-message:
mixHash(local_static_pub)
Verification and processing:
verify MAC1
mixHash(e_init_pub) # -> e
(ck, k) = kdf2(ck, DH(s_resp_priv, e_init_pub)) # -> es
s_init_pub = decryptAndHash(encrypted_static) # -> s
(ck, k) = kdf2(ck, DH(s_resp_priv, s_init_pub)) # -> ss
timestamp = decryptAndHash(encrypted_timestamp)
validate timestamp within ±180 s
```
### 5.4 Responder: CreateResp
Continues immediately after ConsumeInit.
```
mixHash(e_resp_pub) # -> e
(ck, k) = kdf2(ck, DH(e_resp_priv, e_init_pub)) # -> ee
(ck, k) = kdf2(ck, DH(e_resp_priv, s_init_pub)) # -> se
encrypted_nil = encryptAndHash(empty)
mac1 = MAC1(initiator_static_pub, resp_body_without_macs)
mac2 = 0 (no cookie in response)
```
### 5.5 Initiator: ConsumeResp
```
mixHash(e_resp_pub) # <- e
(ck, k) = kdf2(ck, DH(e_init_priv, e_resp_pub)) # <- ee
(ck, k) = kdf2(ck, DH(s_init_priv, e_resp_pub)) # <- se
decryptAndHash(encrypted_nil) # proves responder identity
```
### 5.6 Transport Key Derivation (SPLIT)
After both sides complete the handshake:
```
(T_initiator_send, T_initiator_recv) = kdf2(ck, empty)
```
- Initiator sends with `T_initiator_send`, receives with `T_initiator_recv`.
- Responder sends with `T_initiator_recv`, receives with `T_initiator_send`.
---
## 6. Cookie / DoS Mitigation
When the server is under load, it may respond to HandshakeInit with a
CookieReply instead of HandshakeResp.
### 6.1 Cookie derivation (server side)
The server maintains a 32-byte `cookie_secret` rotated every 2 minutes.
```
cookie_key = MAC(key=cookie_secret, data="cookie--" || server_static_pub)
cookie = MAC(key=cookie_key, data=client_addr_string)[0:16]
```
`client_addr_string` is the client's UDP address formatted as `"ip:port"`.
### 6.2 CookieReply construction
```
key = mac1_from_HandshakeInit zero-extended to 32 bytes
nonce = random 24 bytes
encrypted_cookie = XChaCha20-Poly1305-Seal(key, nonce, cookie, aad=empty)
```
### 6.3 MAC2 retry
On receiving a CookieReply, the initiator decrypts the cookie and retries
HandshakeInit with:
```
MAC2 = MAC2(cookie, message_body_without_mac2)[0:16]
```
The server accepts a HandshakeInit with a valid MAC2 even under load.
---
## 7. Session Lifecycle
```
Client Server
| |
|------ HandshakeInit --------->|
| | (may send CookieReply if under load)
|<----- HandshakeResp ----------|
| |
| [session established] |
| |
|<===== Data / Fragments ======>|
|<===== Keepalives ============>|
| |
|------ Disconnect ------------>| (or timeout)
```
### 7.1 Session indices
Each side independently picks a random 32-bit `session_index`.
The sender places the **recipient's** index in every outgoing data packet's
`receiver_index` field so the recipient can route it to the correct session.
### 7.2 Send counter
The sender maintains a monotonically increasing 64-bit counter starting at 0.
The counter is used both as the AEAD nonce and for the receiver's replay window.
When the counter reaches `2^64 - 1` it wraps to 0 and the session is closed,
forcing a new handshake.
### 7.3 Timeouts and keepalives
| Parameter | Default | Description |
|---|---|---|
| `KeepaliveInterval` | 10 s | Send keepalive if data idle for this long |
| `SessionTimeout` | 180 s | Close session if no packet received for this long |
| `RekeyAfterTime` | 180 s | Initiate new handshake after this session age |
| `RekeyAfterMessages` | 2^60 | Initiate new handshake after this many packets sent |
Each side enforces its own timeout independently.
Keepalive receipt does **not** reset the data-idle timer; a peer that only
sends keepalives will still receive them in return.
---
## 8. Replay Protection
Incoming data, keepalive, disconnect, and fragment packets are all subject to
replay protection using a 4096-entry sliding window implemented as a
`[64]uint64` bitmap (64 words × 64 bits).
```
Window covers: [head - 4095, head]
```
- If `counter > head`: accepted (new high-water mark).
- If `counter < head - 4095`: rejected (too old).
- Otherwise: check bitmask. If bit already set: rejected (duplicate).
The window is updated (`head` advanced, bitmap updated) only after AEAD
decryption succeeds. `head` is stored atomically for a lock-free fast path
on the common case of strictly in-order delivery.
**Why 4096 entries?** On Linux, `sendFragments` allocates all N fragment
counters in a tight loop *before* the `sendmmsg` batch is written to the
socket. A concurrent keepalive send can steal a counter mid-loop and arrive
at the peer before the fragment batch, causing the peer's `head` to advance
past the early fragment counters. With the original 64-entry window, a
difference ≥ 64 triggered spurious replay rejections and permanent event
loss. A 4096-entry window safely accommodates the maximum in-flight fragment
count with ample headroom.
---
## 9. Fragmentation
Frames whose serialised plaintext exceeds `maxFragPayload` bytes are split
into multiple DataFragment packets.
### 9.1 Default MTU parameters
| Parameter | Value | Derivation |
|---|---|---|
| Default MaxPacketSize | 1232 bytes | IPv6 min path MTU (1280) − IPv6 header (40) − UDP header (8) |
| Default maxFragPayload | 1192 bytes | 1232 − DataHeader(16) − FragmentHeader(8) − AEADTag(16) |
| Maximum fragments per frame | 65 535 | `frag_count` is uint16 |
| Maximum frame size at default MTU | ≈ 78 MB | 65 535 × 1192 bytes |
### 9.2 Reassembly
The receiver maintains a map of partial frames keyed by `frame_id`.
When all `frag_count` fragments for a `frame_id` arrive, the payloads are
concatenated in `frag_index` order and the result is decoded as a Frame.
Incomplete fragment sets are garbage-collected after `2 × KeepaliveInterval`
of inactivity. At most `MaxIncompleteFrames` (default 64, configurable per
`ServerConfig`/`DialConfig`) partial frames are buffered per session; excess
fragments are silently dropped.
Duplicate fragments (same `frame_id` + `frag_index`) are ignored.
---
## 10. Frame Wire Format
A **Frame** is the plaintext inside a Data or reassembled DataFragment packet.
It uses a custom encoding that is a strict subset of Protocol Buffers wire
format, allowing standard proto decoders to parse it as an extension of the
proto schema.
```
Byte 0: channel_id (uint8, raw — not proto-encoded)
Bytes 1..N: events (field-1 LEN records, one per event)
[optional] Seq (field-2 varint) — omitted when 0 (unreliable)
[optional] AckSeq (field-3 varint) — omitted when 0
[optional] AckBitmap (field-4 I64 LE) — omitted when 0
[optional] WindowSize (field-5 varint) — omitted when 0
```
Each event body is encoded as a Protocol Buffers–style LEN field:
```
varint(0x0A) # field=1, wire type=2 (LEN) → event body follows
varint(len(event_body)) # byte length of event body
event_body[0] # event type (uint8, 0–254 app-defined; 255 internal)
event_body[1:] # opaque payload bytes (may be empty)
```
The reliability fields are appended after all events using these proto tags:
```
varint(0x10) # field=2, wire type=0 (varint) → Seq (uint32)
varint(0x18) # field=3, wire type=0 (varint) → AckSeq (uint32)
varint(0x21) # field=4, wire type=1 (I64 LE) → AckBitmap (uint64)
varint(0x28) # field=5, wire type=0 (varint) → WindowSize (uint32)
```
All four reliability fields are zero-omitted, preserving backward
compatibility with peers that implement only unreliable delivery.
A **standalone ACK** frame carries no events (`Events` is empty) and has
`Seq == 0`; it carries only `AckSeq`, `AckBitmap`, and `WindowSize`.
Multiple events may be packed into a single Frame (coalescing).
### 10.1 Channel IDs
| Value | Usage |
|---|---|
| 0 | Default channel |
| 1–254 | Application-defined channels |
| 255 | Internal (`channelCloseType`) |
Event type 255 (`channelCloseType`) on any channel signals that the remote
peer has closed that channel. The receiver evicts the channel and signals any
blocked `Recv` callers with an error.
---
## 11. Reliable Delivery
Reliable delivery is opt-in per channel via `Channel.SetReliable(ReliableCfg)`.
Channels that do not call `SetReliable` have zero overhead; all reliability
fields in their frames are zero and ignored on receipt.
### 11.1 Sequence numbers
Sequence numbers are `uint32`, starting at **1** (0 is reserved to mean
"unreliable"). The sender assigns a monotonically increasing sequence number
to each outgoing frame in `preSend`. Sequence numbers reset to 1 whenever
the underlying session reconnects (persistent connections).
### 11.2 Cumulative ACK
`AckSeq` carries the **next expected** sequence number (TCP-style). A value
of `AckSeq = N` means the receiver has received all frames with
`seq ∈ [1, N-1]` in order and is waiting for `seq == N`. The sender frees
all pending frames with `seq < AckSeq`.
### 11.3 Selective ACK (SACK)
`AckBitmap` is a 64-bit SACK bitmap. Bit `i` (LSB = bit 0) is set when
the frame with sequence number `AckSeq + i + 1` has been received out of
order. The sender uses this to free selectively acknowledged frames without
waiting for gap-filling retransmits.
The receiver maintains an out-of-order (OOO) buffer of at most
`reliableOOOWindow = 64` slots. Frames arriving more than 64 positions ahead
of the expected sequence are dropped.
### 11.4 Flow control (window)
`WindowSize` reports how many additional frames the sender of the ACK can
accept (receive-buffer headroom). The remote sender blocks when
`numPending >= peerWindow`. `WindowSize` is updated dynamically as the
receiver's channel buffer drains. The initial window equals the configured
`ReliableCfg.WindowSize` (default 256).
### 11.5 ACK timing
ACKs are **piggybacked** on outgoing data frames whenever possible: before
a data frame is sent, any pending ACK state is consumed and written into
the frame's `AckSeq`/`AckBitmap`/`WindowSize` fields at no extra cost.
When no data is ready to send, a **standalone ACK** is dispatched after at
most `ACKDelay` (default 20 ms) by a `time.AfterFunc` timer.
### 11.6 Retransmit
A single retransmit timer (`time.AfterFunc`) is armed per channel after any
frame is sent. On firing it retransmits the oldest unACKed frame and
reschedules itself with **exponential backoff** (RTO doubles each retry,
capped at `maxRTO = 30 s`). After `MaxRetries` (default 10) consecutive
retransmit attempts the channel is closed.
The retransmit timer is reset to `BaseRTO` (default 200 ms) whenever an ACK
frees at least one frame.
### 11.7 Reconnect behaviour
When a persistent `Conn` reconnects, `reset()` is called on every channel
that has a `reliableState`. This purges all pending frames, resets `nextSeq`
to 1, restores `peerWindow` to the configured maximum, and broadcasts on the
flow-control condition variable to unblock any goroutines waiting in
`preSend`. The receiver-side `expectSeq` is also reset to 1 and the OOO
buffer is cleared.
In-flight frames that had not been ACKed before the reconnect are discarded;
the application layer is responsible for any end-to-end retransmission policy
across reconnects.
---
## 12. Numeric Limits
| Constant | Value |
|---|---|
| `sizeHandshakeInit` | 148 bytes |
| `sizeHandshakeResp` | 92 bytes |
| `sizeCookieReply` | 64 bytes |
| `sizeDataHeader` | 16 bytes |
| `sizeFragmentHeader` | 8 bytes |
| `sizeAEADTag` | 16 bytes |
| `sizeKeepalive` / `sizeDisconnect` | 32 bytes |
| `defaultMaxPacketSize` | 1232 bytes |
| `defaultMaxFragPayload` | 1192 bytes |
| `MaxIncompleteFrames` (default) | 64 (configurable) |
| `windowWords` | 64 |
| `windowSize` (replay) | 4096 (= 64 words × 64 bits) |
| `maxTimestampSkew` | 180 s |
| `cookieRotation` | 2 min |
| `rekeyAfterTime` | 180 s |
| `rekeyAfterMessages` | 2^60 |
| Maximum fragments per frame | 65 535 |
| Maximum channels | 256 (IDs 0–255) |
| `defaultReliableWindow` | 256 frames |
| `defaultBaseRTO` | 200 ms |
| `defaultMaxRetries` | 10 |
| `defaultACKDelay` | 20 ms |
| `maxRTO` | 30 s |
| `reliableOOOWindow` | 64 slots |
---
## 13. Implementation Notes
### Batch sends (Linux)
On Linux, outgoing fragments are sent in a single `sendmmsg(2)` syscall via
`ipv4.PacketConn.WriteBatch` (IPv4 sockets) or `ipv6.PacketConn.WriteBatch`
(IPv6 sockets). On other platforms, fragments are sent in a loop of
individual `sendmsg` calls.
### Batch receives
Incoming UDP datagrams are read in batches of up to 64 (server) or 16
(client) messages per `recvmmsg(2)` syscall via `ipv4.PacketConn.ReadBatch`.
### Buffer pools
Send and receive paths use `sync.Pool`-backed byte slices to reduce GC
pressure. AEAD operations write ciphertext and plaintext in-place into pool
buffers; no additional allocation occurs on the hot path when buffers have
sufficient capacity.
### Socket buffers
Both client and server request 4 MiB `SO_RCVBUF` / `SO_SNDBUF`. On Linux,
this may be silently clamped by `net.core.rmem_max` / `wmem_max`
(default ≈ 208 KiB). To guarantee the full 4 MiB, either raise the sysctl:
```bash
sysctl -w net.core.rmem_max=4194304
sysctl -w net.core.wmem_max=4194304
```
or use `SO_RCVBUFFORCE` (requires `CAP_NET_ADMIN`).
In Docker, pass `--sysctl net.core.rmem_max=4194304`.
### Rate limiting
When `SendRateLimitBPS` is non-zero in `ServerConfig` or `DialConfig`, a
token-bucket limiter is installed on the session's send path. The burst
capacity is 2× the per-second rate, allowing short bursts to proceed at
full wire speed. The limiter is checked in `session.send()` and
`session.sendFragments()` before each write; it sleeps on a timer when
tokens are exhausted and aborts early if the session closes.
### Pipeline sizing (`ProbeUDPRecvBufSize`)
Benchmark and high-throughput pipeline code should call
`wiresocket.ProbeUDPRecvBufSize(requested int) int` to determine the actual
achievable receive-buffer size before computing `inflightCap`. On Linux
without `CAP_NET_ADMIN`, `SO_RCVBUF` is clamped by `net.core.rmem_max`; the
probe function creates a temporary loopback socket, applies
`SO_RCVBUFFORCE` (falling back to `SO_RCVBUF`), reads back the result with
`getsockopt`, and divides by 2 to undo the kernel's automatic doubling. On
other platforms it returns `requested` unchanged. Using the probed value
prevents the in-flight frame count from exceeding what the kernel buffer can
hold, avoiding packet loss under burst sends.
npub145…kgem6
2026-02-26 13:29:13 CET
Author Public Key
npub145z4thm7mae9xth3ag498dsrvvj6dnuau4jnrd8rjkn5fedvqx7qrkgem6Seen on
wss://nos.lolPublished at
2026-02-26 13:29:13 CETEvent JSON
{
"id": "69c1e619bcd8f30084997c8178f02a20a6392a83182d00fff4204ff29484cc93",
"pubkey": "ad0555df7edf72532ef1ea2a53b6036325a6cf9de56531b4e395a744e5ac01bc",
"created_at": 1772108953,
"kind": 1,
"tags": [
[
"client",
"smesh",
"https://smesh.mleku.dev"
]
],
"content": "# Wiresocket Protocol Specification\n\n\u003e **DRAFT** — This document reflects implementation as of 2026-02-26 and is pending formal review.\n\nVersion: 1 (`noisePrologue = \"wiresocket v1\"`)\n\n---\n\n## 1. Overview\n\nWiresocket is a WireGuard-inspired, encrypted UDP event-stream protocol.\nIt provides a bidirectional, multi-channel event stream between a client and\nserver over a single UDP socket.\n\n**Key properties:**\n\n- **Transport**: UDP (connectionless)\n- **Encryption**: Noise IK over X25519 / ChaCha20-Poly1305 / BLAKE2s\n- **Authentication**: Both static keys (server always; client optionally)\n- **Multiplexing**: up to 256 independent channels per session (channel IDs 0–255)\n- **Fragmentation**: frames exceeding one UDP datagram are split across up to 65 535 fragments\n- **DoS mitigation**: WireGuard-style cookies (XChaCha20-Poly1305)\n- **Replay protection**: 4096-entry sliding window\n- **Reliable delivery**: optional per-channel sequencing, cumulative + selective ACKs (SACK), retransmit with exponential backoff, and window-based flow control\n- **Rate limiting**: optional per-session send rate cap (token bucket; configurable bytes-per-second)\n\nAll multi-byte integers are **little-endian** unless stated otherwise.\n\n---\n\n## 2. Cryptographic Primitives\n\n| Primitive | Algorithm | Notes |\n|---|---|---|\n| DH | X25519 (RFC 7748) | Low-order-point rejection enforced |\n| AEAD (handshake) | ChaCha20-Poly1305 (RFC 8439) | |\n| AEAD (transport) | ChaCha20-Poly1305 | One AEAD instance per direction, cached per session |\n| AEAD (cookie reply) | XChaCha20-Poly1305 | 24-byte random nonce |\n| Hash | BLAKE2s-256 | |\n| MAC | Keyed BLAKE2s-256 | `BLAKE2s(key=K, data=D)` |\n| KDF | HKDF-BLAKE2s | See §2.1 |\n| Keypairs | X25519 | RFC 7748 clamping applied |\n\n### 2.1 KDF\n\n```\nprk = MAC(key=ck, data=input)\nT[1] = MAC(key=prk, data=0x01)\nT[i] = MAC(key=prk, data=T[i-1] || byte(i))\n```\n\n`kdf2(ck, input)` returns `(T[1], T[2])`.\n`kdf3(ck, input)` returns `(T[1], T[2], T[3])`.\n\n### 2.2 Initial chaining key and hash\n\n```\ninitialCK = \"Noise_IK_25519_ChaChaPoly_BLAKE2s\" (zero-padded to 32 bytes)\ninitialH = HASH(initialCK || \"wiresocket v1\")\n```\n\nBoth are computed once at process startup.\n\n### 2.3 AEAD nonce\n\nTransport AEAD nonces are 12 bytes:\n\n```\nnonce[0:4] = 0x00 0x00 0x00 0x00\nnonce[4:12] = counter (uint64 LE)\n```\n\n### 2.4 MAC1 derivation\n\n```\nmac1_key = HASH(\"mac1----\" || receiver_static_pub)\nMAC1 = MAC(mac1_key, message_body)[0:16]\n```\n\n`message_body` is everything in the serialised message before the MAC fields.\n\n### 2.5 MAC2 derivation\n\n```\nMAC2 = MAC(key=cookie[0:16] zero-extended to 32 bytes, data=message_body)[0:16]\n```\n\n---\n\n## 3. Packet Types\n\nThe first byte of every UDP datagram is a **type tag**:\n\n| Value | Name | Size (bytes) |\n|---|---|---|\n| 1 | HandshakeInit | 148 |\n| 2 | HandshakeResp | 92 |\n| 3 | CookieReply | 64 |\n| 4 | Data | 16 + ciphertext |\n| 5 | Disconnect | 32 (16 header + 16 AEAD tag) |\n| 6 | Keepalive | 32 (16 header + 16 AEAD tag) |\n| 7 | DataFragment | 16 + ciphertext |\n\n---\n\n## 4. Wire Formats\n\n### 4.1 HandshakeInit (type 1, 148 bytes)\n\nSent by the initiator to begin a session.\n\n```\nOffset Size Field\n------ ---- -----\n0 1 type = 0x01\n1 3 reserved (zero)\n4 4 sender_index uint32 LE — initiator's session token\n8 32 ephemeral initiator ephemeral public key (X25519)\n40 48 encrypted_static AEAD(initiator static pub key, 32 plain + 16 tag)\n88 28 encrypted_timestamp AEAD(TAI64N timestamp, 12 plain + 16 tag)\n116 16 mac1 MAC1 keyed by responder's static pub\n132 16 mac2 MAC2 keyed by cookie (zeros if no cookie)\n```\n\n`sender_index` is a random 32-bit token chosen by the initiator.\nIt is used as `receiver_index` in all subsequent packets the server sends\nto this session.\n\n`encrypted_timestamp` carries a 12-byte TAI64N timestamp\n(`uint64 BE seconds` || `uint32 BE nanoseconds`).\nThe TAI epoch offset applied is `0x4000000000000000`.\nThe responder rejects timestamps more than ±180 seconds from its own clock.\n\n### 4.2 HandshakeResp (type 2, 92 bytes)\n\nSent by the responder in reply to a valid HandshakeInit.\n\n```\nOffset Size Field\n------ ---- -----\n0 1 type = 0x02\n1 3 reserved (zero)\n4 4 sender_index uint32 LE — responder's session token\n8 4 receiver_index uint32 LE — echoes initiator's sender_index\n12 32 ephemeral responder ephemeral public key (X25519)\n44 16 encrypted_nil AEAD(empty plaintext) — 0 plain + 16 tag\n60 16 mac1 MAC1 keyed by initiator's static pub\n76 16 mac2 MAC2 keyed by cookie (zeros if no cookie)\n```\n\n### 4.3 CookieReply (type 3, 64 bytes)\n\nSent by the server instead of HandshakeResp when under load.\nThe cookie must be used in MAC2 of the retried HandshakeInit.\n\n```\nOffset Size Field\n------ ---- -----\n0 1 type = 0x03\n1 3 reserved (zero)\n4 4 receiver_index uint32 LE — echoes initiator's sender_index\n8 24 nonce random 24-byte XChaCha20 nonce\n32 32 encrypted_cookie XChaCha20-Poly1305(cookie, 16 plain + 16 tag)\n```\n\nThe XChaCha20-Poly1305 key is the MAC1 from the HandshakeInit zero-extended\nto 32 bytes. Only the genuine initiator (who knows its own MAC1) can decrypt\nthe cookie.\n\n### 4.4 Data (type 4)\n\nCarries one encrypted Frame. Total size: `16 + len(plaintext) + 16`.\n\n```\nOffset Size Field\n------ ---- -----\n0 1 type = 0x04\n1 3 reserved (zero)\n4 4 receiver_index uint32 LE — recipient's session token\n8 8 counter uint64 LE — monotonic send counter\n16 N+16 ciphertext ChaCha20-Poly1305(frame_bytes, N plain + 16 tag)\n```\n\nAAD is empty. The nonce is constructed from `counter` (see §2.3).\n\n### 4.5 Disconnect (type 5, 32 bytes)\n\nAuthenticated graceful shutdown notification. Same header layout as Data\nwith an AEAD over empty plaintext.\n\n```\nOffset Size Field\n------ ---- -----\n0 1 type = 0x05\n1 3 reserved (zero)\n4 4 receiver_index uint32 LE\n8 8 counter uint64 LE\n16 16 AEAD tag ChaCha20-Poly1305(empty) — 0 plain + 16 tag\n```\n\n### 4.6 Keepalive (type 6, 32 bytes)\n\nLiveness probe. Same layout as Disconnect with type 6.\n\n```\nOffset Size Field\n------ ---- -----\n0 1 type = 0x06\n1 3 reserved (zero)\n4 4 receiver_index uint32 LE\n8 8 counter uint64 LE\n16 16 AEAD tag ChaCha20-Poly1305(empty) — 0 plain + 16 tag\n```\n\nA keepalive is sent whenever no data has been exchanged for `KeepaliveInterval`\n(default 10 s). The counter participates in replay protection.\n\n### 4.7 DataFragment (type 7)\n\nCarries one encrypted fragment of a large Frame.\nTotal size: `16 + 8 + len(frag_data) + 16`.\n\n```\nOffset Size Field\n------ ---- -----\n0 1 type = 0x07\n1 3 reserved (zero)\n4 4 receiver_index uint32 LE\n8 8 counter uint64 LE\n16 N+24 ciphertext ChaCha20-Poly1305(frag_plain, (8+M) plain + 16 tag)\n```\n\nThe **plaintext** inside the ciphertext has its own sub-header:\n\n```\nPlain offset Size Field\n------------ ---- -----\n0 4 frame_id uint32 LE — unique per frame within a session\n4 2 frag_index uint16 LE — zero-based index of this fragment\n6 2 frag_count uint16 LE — total number of fragments (1–65535)\n8 M frag_data raw fragment bytes\n```\n\n`frame_id` is a monotonically increasing counter scoped to the sending session.\nAll fragments of the same frame share the same `frame_id`.\n\n---\n\n## 5. Noise IK Handshake\n\nThe handshake follows the **Noise IK** pattern\n(`Noise_IK_25519_ChaChaPoly_BLAKE2s`):\n\n```\nPre-messages:\n -\u003e s (responder's static public key known to initiator out-of-band)\n\nMessages:\n -\u003e e, es, s, ss (HandshakeInit)\n \u003c- e, ee, se (HandshakeResp)\n```\n\n### 5.1 Symmetric State\n\nBoth sides maintain a symmetric state `(ck, h, k, nonce)`:\n\n- `ck` — chaining key, starts as `initialCK`\n- `h` — transcript hash, starts as `initialH`\n- `k` — current AEAD key (empty until first `mixKey`)\n- `nonce` — per-key counter, reset to 0 on each `mixKey`\n\n**`mixHash(data)`**: `h = HASH(h || data)`\n\n**`mixKey(dh_out)`**: `(ck, k) = kdf2(ck, dh_out)` ; `nonce = 0`\n\n**`encryptAndHash(plain)`**: `c = AEAD_Seal(k, nonce++, h, plain)` ; `mixHash(c)` ; return `c`\n\n**`decryptAndHash(cipher)`**: `p = AEAD_Open(k, nonce++, h, cipher)` ; `mixHash(cipher)` ; return `p`\n\n### 5.2 Initiator: CreateInit\n\nStarting state: `ck = initialCK`, `h = HASH(initialCK || \"wiresocket v1\")`.\n\n```\nPre-message:\n mixHash(responder_static_pub)\n\nMessage construction:\n mixHash(e_pub) # -\u003e e\n (ck, k) = kdf2(ck, DH(e_priv, s_resp_pub)) # -\u003e es\n encrypted_static = encryptAndHash(s_init_pub) # -\u003e s\n (ck, k) = kdf2(ck, DH(s_init_priv, s_resp_pub)) # -\u003e ss\n encrypted_timestamp = encryptAndHash(TAI64N())\n mac1 = MAC1(responder_static_pub, msg_body_without_macs)\n mac2 = MAC2(cookie, msg_body_without_mac2) # zero if no cookie\n```\n\n### 5.3 Responder: ConsumeInit\n\n```\nPre-message:\n mixHash(local_static_pub)\n\nVerification and processing:\n verify MAC1\n mixHash(e_init_pub) # -\u003e e\n (ck, k) = kdf2(ck, DH(s_resp_priv, e_init_pub)) # -\u003e es\n s_init_pub = decryptAndHash(encrypted_static) # -\u003e s\n (ck, k) = kdf2(ck, DH(s_resp_priv, s_init_pub)) # -\u003e ss\n timestamp = decryptAndHash(encrypted_timestamp)\n validate timestamp within ±180 s\n```\n\n### 5.4 Responder: CreateResp\n\nContinues immediately after ConsumeInit.\n\n```\n mixHash(e_resp_pub) # -\u003e e\n (ck, k) = kdf2(ck, DH(e_resp_priv, e_init_pub)) # -\u003e ee\n (ck, k) = kdf2(ck, DH(e_resp_priv, s_init_pub)) # -\u003e se\n encrypted_nil = encryptAndHash(empty)\n mac1 = MAC1(initiator_static_pub, resp_body_without_macs)\n mac2 = 0 (no cookie in response)\n```\n\n### 5.5 Initiator: ConsumeResp\n\n```\n mixHash(e_resp_pub) # \u003c- e\n (ck, k) = kdf2(ck, DH(e_init_priv, e_resp_pub)) # \u003c- ee\n (ck, k) = kdf2(ck, DH(s_init_priv, e_resp_pub)) # \u003c- se\n decryptAndHash(encrypted_nil) # proves responder identity\n```\n\n### 5.6 Transport Key Derivation (SPLIT)\n\nAfter both sides complete the handshake:\n\n```\n(T_initiator_send, T_initiator_recv) = kdf2(ck, empty)\n```\n\n- Initiator sends with `T_initiator_send`, receives with `T_initiator_recv`.\n- Responder sends with `T_initiator_recv`, receives with `T_initiator_send`.\n\n---\n\n## 6. Cookie / DoS Mitigation\n\nWhen the server is under load, it may respond to HandshakeInit with a\nCookieReply instead of HandshakeResp.\n\n### 6.1 Cookie derivation (server side)\n\nThe server maintains a 32-byte `cookie_secret` rotated every 2 minutes.\n\n```\ncookie_key = MAC(key=cookie_secret, data=\"cookie--\" || server_static_pub)\ncookie = MAC(key=cookie_key, data=client_addr_string)[0:16]\n```\n\n`client_addr_string` is the client's UDP address formatted as `\"ip:port\"`.\n\n### 6.2 CookieReply construction\n\n```\nkey = mac1_from_HandshakeInit zero-extended to 32 bytes\nnonce = random 24 bytes\nencrypted_cookie = XChaCha20-Poly1305-Seal(key, nonce, cookie, aad=empty)\n```\n\n### 6.3 MAC2 retry\n\nOn receiving a CookieReply, the initiator decrypts the cookie and retries\nHandshakeInit with:\n\n```\nMAC2 = MAC2(cookie, message_body_without_mac2)[0:16]\n```\n\nThe server accepts a HandshakeInit with a valid MAC2 even under load.\n\n---\n\n## 7. Session Lifecycle\n\n```\nClient Server\n | |\n |------ HandshakeInit ---------\u003e|\n | | (may send CookieReply if under load)\n |\u003c----- HandshakeResp ----------|\n | |\n | [session established] |\n | |\n |\u003c===== Data / Fragments ======\u003e|\n |\u003c===== Keepalives ============\u003e|\n | |\n |------ Disconnect ------------\u003e| (or timeout)\n```\n\n### 7.1 Session indices\n\nEach side independently picks a random 32-bit `session_index`.\nThe sender places the **recipient's** index in every outgoing data packet's\n`receiver_index` field so the recipient can route it to the correct session.\n\n### 7.2 Send counter\n\nThe sender maintains a monotonically increasing 64-bit counter starting at 0.\nThe counter is used both as the AEAD nonce and for the receiver's replay window.\nWhen the counter reaches `2^64 - 1` it wraps to 0 and the session is closed,\nforcing a new handshake.\n\n### 7.3 Timeouts and keepalives\n\n| Parameter | Default | Description |\n|---|---|---|\n| `KeepaliveInterval` | 10 s | Send keepalive if data idle for this long |\n| `SessionTimeout` | 180 s | Close session if no packet received for this long |\n| `RekeyAfterTime` | 180 s | Initiate new handshake after this session age |\n| `RekeyAfterMessages` | 2^60 | Initiate new handshake after this many packets sent |\n\nEach side enforces its own timeout independently.\n\nKeepalive receipt does **not** reset the data-idle timer; a peer that only\nsends keepalives will still receive them in return.\n\n---\n\n## 8. Replay Protection\n\nIncoming data, keepalive, disconnect, and fragment packets are all subject to\nreplay protection using a 4096-entry sliding window implemented as a\n`[64]uint64` bitmap (64 words × 64 bits).\n\n```\nWindow covers: [head - 4095, head]\n```\n\n- If `counter \u003e head`: accepted (new high-water mark).\n- If `counter \u003c head - 4095`: rejected (too old).\n- Otherwise: check bitmask. If bit already set: rejected (duplicate).\n\nThe window is updated (`head` advanced, bitmap updated) only after AEAD\ndecryption succeeds. `head` is stored atomically for a lock-free fast path\non the common case of strictly in-order delivery.\n\n**Why 4096 entries?** On Linux, `sendFragments` allocates all N fragment\ncounters in a tight loop *before* the `sendmmsg` batch is written to the\nsocket. A concurrent keepalive send can steal a counter mid-loop and arrive\nat the peer before the fragment batch, causing the peer's `head` to advance\npast the early fragment counters. With the original 64-entry window, a\ndifference ≥ 64 triggered spurious replay rejections and permanent event\nloss. A 4096-entry window safely accommodates the maximum in-flight fragment\ncount with ample headroom.\n\n---\n\n## 9. Fragmentation\n\nFrames whose serialised plaintext exceeds `maxFragPayload` bytes are split\ninto multiple DataFragment packets.\n\n### 9.1 Default MTU parameters\n\n| Parameter | Value | Derivation |\n|---|---|---|\n| Default MaxPacketSize | 1232 bytes | IPv6 min path MTU (1280) − IPv6 header (40) − UDP header (8) |\n| Default maxFragPayload | 1192 bytes | 1232 − DataHeader(16) − FragmentHeader(8) − AEADTag(16) |\n| Maximum fragments per frame | 65 535 | `frag_count` is uint16 |\n| Maximum frame size at default MTU | ≈ 78 MB | 65 535 × 1192 bytes |\n\n### 9.2 Reassembly\n\nThe receiver maintains a map of partial frames keyed by `frame_id`.\nWhen all `frag_count` fragments for a `frame_id` arrive, the payloads are\nconcatenated in `frag_index` order and the result is decoded as a Frame.\n\nIncomplete fragment sets are garbage-collected after `2 × KeepaliveInterval`\nof inactivity. At most `MaxIncompleteFrames` (default 64, configurable per\n`ServerConfig`/`DialConfig`) partial frames are buffered per session; excess\nfragments are silently dropped.\n\nDuplicate fragments (same `frame_id` + `frag_index`) are ignored.\n\n---\n\n## 10. Frame Wire Format\n\nA **Frame** is the plaintext inside a Data or reassembled DataFragment packet.\nIt uses a custom encoding that is a strict subset of Protocol Buffers wire\nformat, allowing standard proto decoders to parse it as an extension of the\nproto schema.\n\n```\nByte 0: channel_id (uint8, raw — not proto-encoded)\nBytes 1..N: events (field-1 LEN records, one per event)\n[optional] Seq (field-2 varint) — omitted when 0 (unreliable)\n[optional] AckSeq (field-3 varint) — omitted when 0\n[optional] AckBitmap (field-4 I64 LE) — omitted when 0\n[optional] WindowSize (field-5 varint) — omitted when 0\n```\n\nEach event body is encoded as a Protocol Buffers–style LEN field:\n\n```\nvarint(0x0A) # field=1, wire type=2 (LEN) → event body follows\nvarint(len(event_body)) # byte length of event body\nevent_body[0] # event type (uint8, 0–254 app-defined; 255 internal)\nevent_body[1:] # opaque payload bytes (may be empty)\n```\n\nThe reliability fields are appended after all events using these proto tags:\n\n```\nvarint(0x10) # field=2, wire type=0 (varint) → Seq (uint32)\nvarint(0x18) # field=3, wire type=0 (varint) → AckSeq (uint32)\nvarint(0x21) # field=4, wire type=1 (I64 LE) → AckBitmap (uint64)\nvarint(0x28) # field=5, wire type=0 (varint) → WindowSize (uint32)\n```\n\nAll four reliability fields are zero-omitted, preserving backward\ncompatibility with peers that implement only unreliable delivery.\n\nA **standalone ACK** frame carries no events (`Events` is empty) and has\n`Seq == 0`; it carries only `AckSeq`, `AckBitmap`, and `WindowSize`.\n\nMultiple events may be packed into a single Frame (coalescing).\n\n### 10.1 Channel IDs\n\n| Value | Usage |\n|---|---|\n| 0 | Default channel |\n| 1–254 | Application-defined channels |\n| 255 | Internal (`channelCloseType`) |\n\nEvent type 255 (`channelCloseType`) on any channel signals that the remote\npeer has closed that channel. The receiver evicts the channel and signals any\nblocked `Recv` callers with an error.\n\n---\n\n## 11. Reliable Delivery\n\nReliable delivery is opt-in per channel via `Channel.SetReliable(ReliableCfg)`.\nChannels that do not call `SetReliable` have zero overhead; all reliability\nfields in their frames are zero and ignored on receipt.\n\n### 11.1 Sequence numbers\n\nSequence numbers are `uint32`, starting at **1** (0 is reserved to mean\n\"unreliable\"). The sender assigns a monotonically increasing sequence number\nto each outgoing frame in `preSend`. Sequence numbers reset to 1 whenever\nthe underlying session reconnects (persistent connections).\n\n### 11.2 Cumulative ACK\n\n`AckSeq` carries the **next expected** sequence number (TCP-style). A value\nof `AckSeq = N` means the receiver has received all frames with\n`seq ∈ [1, N-1]` in order and is waiting for `seq == N`. The sender frees\nall pending frames with `seq \u003c AckSeq`.\n\n### 11.3 Selective ACK (SACK)\n\n`AckBitmap` is a 64-bit SACK bitmap. Bit `i` (LSB = bit 0) is set when\nthe frame with sequence number `AckSeq + i + 1` has been received out of\norder. The sender uses this to free selectively acknowledged frames without\nwaiting for gap-filling retransmits.\n\nThe receiver maintains an out-of-order (OOO) buffer of at most\n`reliableOOOWindow = 64` slots. Frames arriving more than 64 positions ahead\nof the expected sequence are dropped.\n\n### 11.4 Flow control (window)\n\n`WindowSize` reports how many additional frames the sender of the ACK can\naccept (receive-buffer headroom). The remote sender blocks when\n`numPending \u003e= peerWindow`. `WindowSize` is updated dynamically as the\nreceiver's channel buffer drains. The initial window equals the configured\n`ReliableCfg.WindowSize` (default 256).\n\n### 11.5 ACK timing\n\nACKs are **piggybacked** on outgoing data frames whenever possible: before\na data frame is sent, any pending ACK state is consumed and written into\nthe frame's `AckSeq`/`AckBitmap`/`WindowSize` fields at no extra cost.\n\nWhen no data is ready to send, a **standalone ACK** is dispatched after at\nmost `ACKDelay` (default 20 ms) by a `time.AfterFunc` timer.\n\n### 11.6 Retransmit\n\nA single retransmit timer (`time.AfterFunc`) is armed per channel after any\nframe is sent. On firing it retransmits the oldest unACKed frame and\nreschedules itself with **exponential backoff** (RTO doubles each retry,\ncapped at `maxRTO = 30 s`). After `MaxRetries` (default 10) consecutive\nretransmit attempts the channel is closed.\n\nThe retransmit timer is reset to `BaseRTO` (default 200 ms) whenever an ACK\nfrees at least one frame.\n\n### 11.7 Reconnect behaviour\n\nWhen a persistent `Conn` reconnects, `reset()` is called on every channel\nthat has a `reliableState`. This purges all pending frames, resets `nextSeq`\nto 1, restores `peerWindow` to the configured maximum, and broadcasts on the\nflow-control condition variable to unblock any goroutines waiting in\n`preSend`. The receiver-side `expectSeq` is also reset to 1 and the OOO\nbuffer is cleared.\n\nIn-flight frames that had not been ACKed before the reconnect are discarded;\nthe application layer is responsible for any end-to-end retransmission policy\nacross reconnects.\n\n---\n\n## 12. Numeric Limits\n\n| Constant | Value |\n|---|---|\n| `sizeHandshakeInit` | 148 bytes |\n| `sizeHandshakeResp` | 92 bytes |\n| `sizeCookieReply` | 64 bytes |\n| `sizeDataHeader` | 16 bytes |\n| `sizeFragmentHeader` | 8 bytes |\n| `sizeAEADTag` | 16 bytes |\n| `sizeKeepalive` / `sizeDisconnect` | 32 bytes |\n| `defaultMaxPacketSize` | 1232 bytes |\n| `defaultMaxFragPayload` | 1192 bytes |\n| `MaxIncompleteFrames` (default) | 64 (configurable) |\n| `windowWords` | 64 |\n| `windowSize` (replay) | 4096 (= 64 words × 64 bits) |\n| `maxTimestampSkew` | 180 s |\n| `cookieRotation` | 2 min |\n| `rekeyAfterTime` | 180 s |\n| `rekeyAfterMessages` | 2^60 |\n| Maximum fragments per frame | 65 535 |\n| Maximum channels | 256 (IDs 0–255) |\n| `defaultReliableWindow` | 256 frames |\n| `defaultBaseRTO` | 200 ms |\n| `defaultMaxRetries` | 10 |\n| `defaultACKDelay` | 20 ms |\n| `maxRTO` | 30 s |\n| `reliableOOOWindow` | 64 slots |\n\n---\n\n## 13. Implementation Notes\n\n### Batch sends (Linux)\n\nOn Linux, outgoing fragments are sent in a single `sendmmsg(2)` syscall via\n`ipv4.PacketConn.WriteBatch` (IPv4 sockets) or `ipv6.PacketConn.WriteBatch`\n(IPv6 sockets). On other platforms, fragments are sent in a loop of\nindividual `sendmsg` calls.\n\n### Batch receives\n\nIncoming UDP datagrams are read in batches of up to 64 (server) or 16\n(client) messages per `recvmmsg(2)` syscall via `ipv4.PacketConn.ReadBatch`.\n\n### Buffer pools\n\nSend and receive paths use `sync.Pool`-backed byte slices to reduce GC\npressure. AEAD operations write ciphertext and plaintext in-place into pool\nbuffers; no additional allocation occurs on the hot path when buffers have\nsufficient capacity.\n\n### Socket buffers\n\nBoth client and server request 4 MiB `SO_RCVBUF` / `SO_SNDBUF`. On Linux,\nthis may be silently clamped by `net.core.rmem_max` / `wmem_max`\n(default ≈ 208 KiB). To guarantee the full 4 MiB, either raise the sysctl:\n\n```bash\nsysctl -w net.core.rmem_max=4194304\nsysctl -w net.core.wmem_max=4194304\n```\n\nor use `SO_RCVBUFFORCE` (requires `CAP_NET_ADMIN`).\nIn Docker, pass `--sysctl net.core.rmem_max=4194304`.\n\n### Rate limiting\n\nWhen `SendRateLimitBPS` is non-zero in `ServerConfig` or `DialConfig`, a\ntoken-bucket limiter is installed on the session's send path. The burst\ncapacity is 2× the per-second rate, allowing short bursts to proceed at\nfull wire speed. The limiter is checked in `session.send()` and\n`session.sendFragments()` before each write; it sleeps on a timer when\ntokens are exhausted and aborts early if the session closes.\n\n### Pipeline sizing (`ProbeUDPRecvBufSize`)\n\nBenchmark and high-throughput pipeline code should call\n`wiresocket.ProbeUDPRecvBufSize(requested int) int` to determine the actual\nachievable receive-buffer size before computing `inflightCap`. On Linux\nwithout `CAP_NET_ADMIN`, `SO_RCVBUF` is clamped by `net.core.rmem_max`; the\nprobe function creates a temporary loopback socket, applies\n`SO_RCVBUFFORCE` (falling back to `SO_RCVBUF`), reads back the result with\n`getsockopt`, and divides by 2 to undo the kernel's automatic doubling. On\nother platforms it returns `requested` unchanged. Using the probed value\nprevents the in-flight frame count from exceeding what the kernel buffer can\nhold, avoiding packet loss under burst sends.",
"sig": "e1f40f877ebffa0b4b21ff8fbfb945170af2ab154d0c3d8f341454a570837e4d74d34a4648360f48f510bd6474f707129c5805c97de5f3b89d3e595bd5794889"
}