redapricot/PROTOCOL.md

redapricot (红杏) wire protocol

redapricot is a central-hub P2P tunnel that speaks (an extension of) the Minecraft Java Edition protocol. This document is the normative wire spec that the Java server (the hub) and the Go client both implement. It is self-contained: everything needed to write an interoperable implementation is here.

There are three roles:

Role	Language	Description
Server	Java	The central hub. Accepts every inbound TCP connection (players and clients) on one port.
Client	Go	Registers routing patterns with the hub and forwards player traffic to real destinations.
Player	any	An ordinary Minecraft client connecting through the hub.

   Player ──MC──▶ Hub(server) ══WorkerConn(1:1)══▶ Client ──MC──▶ Destination
                    ▲   registers patterns / receives control requests   │
                    └────────────── Control Session ────────────────────┘

Security is intentionally lightweight: the goal is connectivity, not confidentiality against a determined attacker. The single shared secret is the PSK (pre-shared key), a UTF-8 passphrase configured on the hub and every client.

---

1. Primitive data types

These follow the Minecraft protocol exactly.

Type	Encoding
VarInt	LEB128, 7 data bits per byte, high bit = continuation, little-endian groups, two's-complement, max 5 bytes.
String	VarInt byte-length of the UTF-8 encoding, followed by the UTF-8 bytes.
U16	unsigned 16-bit, big-endian.
I64	signed 64-bit, big-endian.
Bytes[N]	exactly N raw bytes, no length prefix.
u8	single unsigned byte.

2. Minecraft packet framing (plaintext)

Every connection begins as an ordinary Minecraft connection. An uncompressed Minecraft packet is:

[Length: VarInt][PacketID: VarInt][Data...]      Length = len(PacketID)+len(Data)

redapricot never enables Minecraft compression on the hub link. Player traffic that is compressed end-to-end (negotiated between the player and the real destination) is irrelevant — the hub forwards raw bytes and never inspects anything past the Handshake.

2.1 Handshake

The first packet on every connection is the Handshake (packet id 0x00, Handshaking state):

ProtocolVersion : VarInt
ServerAddress   : String   (≤ 255)
ServerPort      : U16
Intent          : VarInt

The hub reads exactly one Handshake packet and dispatches on Intent:

Intent	Meaning
17	redapricot session establishment (control session or worker conn).
18	Reserved for redapricot management/status. Never matched against patterns. The reference hub replies with a status line and closes.
anything else	Player connection. ServerAddress is matched against the registered regex PATTERNs (§5.1).

For Intent == 18 the hub replies with a Minecraft status-response packet and closes — the same shape a player receives for a status query (Intent 1), so the port can be probed with ordinary tooling:

[Len: VarInt][PacketID 0x00][JSON: String]

The JSON is a minimal status payload, e.g. {"description":{"text":"redapricot hub"},"version":{"name":"redapricot","protocol":767},"players":{"max":0,"online":0}}. It is the one reply the hub sends in plaintext: Intent 18 never negotiates encryption or any other redapricot state.

For Intent == 17 the hub additionally requires ServerAddress == lowercase_hex(SHA3-224(PSK)) — a 56-character hex string. This is the first (cheap) proof that the peer knows the PSK. A mismatch closes the connection.

For player connections the hub normalizes ServerAddress before matching: lower-cased, and any trailing . or Forge/FML \0-suffix (host\0FML\0) stripped to the bare hostname. The resulting hostname is then tested against the registered regex patterns (§5.1).

3. Encryption

Immediately after the Intent == 17 Handshake, the connection switches to an encrypted, self-delimiting frame stream. redapricot uses ChaCha20 (RFC 8439, 32-bit block counter, 96-bit nonce) as a raw stream cipher applied to frame payloads (no Poly1305 tag — padding/space overhead is minimized, matching the design goal).

Each direction is an independent ChaCha20 keystream. Keys are derived from a "phase key" PK (raw bytes) as:

keyC2S = SHA3-256(PK ‖ 0x01)      # client → server
keyS2C = SHA3-256(PK ‖ 0x02)      # server → client
nonce  = 0x00 × 12                # both directions
counter starts at 0               # both directions

Using distinct keys per direction avoids a two-time-pad while keeping the nonce trivially fixed. Each side keeps two ChaCha20 instances (one encrypt, one decrypt) and feeds bytes through them incrementally; the keystream position is maintained across writes.

There are two phases:

• Phase A — PK = PSK (the configured passphrase, UTF-8 bytes).
• Phase B — PK = REKEY (see §4), used for the remainder of the connection.

3.1 Encrypted frames

Once encryption is on, the connection speaks length-prefixed frames:

[Length: VarInt]            # PLAINTEXT (not encrypted)
[Payload: Bytes[Length]]    # ciphertext (ChaCha20)

Only the payload is encrypted; the Length prefix is sent in the clear. The cipher is a continuous per-direction keystream: each frame's payload advances the keystream by exactly Length bytes (the length prefix consumes no keystream). This keeps framing trivial — a reader reads a plaintext VarInt, then decrypts exactly that many following bytes as one unit — and lets the cipher phase switch (§4) happen cleanly on a frame boundary without ever decrypting a later frame's bytes with the wrong key. Max payload length is 1 MiB; larger closes the connection.

4. Session establishment (Intent 17)

The first frame is sent by the peer that opened the connection (client → server) and is encrypted with Phase A. Its payload is the Rekey message:

Magic     : u8       # 0x01 = control session, 0x02 = worker conn
RandLen   : VarInt    # 8 ≤ RandLen ≤ 64
Rand      : Bytes[RandLen]   # cryptographically random
Timestamp : I64       # client's epoch milliseconds
Flags     : VarInt    # feature flags; bit 0x01 (STREAM_FC) MUST be set
RecvWindow: VarInt    # client's per-connection receive window, bytes (§7.3)

Flags is a bitfield of features.

Bit	Name	Meaning
0x01	STREAM_FC	Per-connection flow control (§7.3). Mandatory.
0x02	WORKER_HEARTBEAT	Connection-level PING/PONG on worker conns (§7.4). Optional.
0x04	STREAM_RESUME	Stream resumption (§7.5): a worker-conn drop hangs the player rather than closing it. Optional.

STREAM_FC is mandatory: RecvWindow advertises the client's per-connection receive window in bytes and must be positive. The hub closes the connection if the flag is missing, RecvWindow is absent or non-positive, or the fields are malformed.

Optional bits are negotiated: the hub echoes in SessionReady only those it accepts, and the client enables a feature only when its bit comes back. A hub that does not know WORKER_HEARTBEAT simply omits the bit and the client falls back to TCP keepalive alone.

The hub:

1. Decrypts frame 1 with Phase A.
2. Rejects (closes) if |now − Timestamp| > timestampWindowMs (default 30000), or if RandLen is out of range.
3. Computes REKEY = Rand ‖ Timestamp (the 8 timestamp bytes big-endian appended to Rand — the Magic byte is not included).
4. Switches both its ciphers to Phase B keys derived from REKEY.

The client, after sending frame 1 with Phase A, likewise switches both its ciphers to Phase B. In practice only frame 1 uses Phase A; every later frame (both directions) is Phase B, counters reset to 0.

The hub then sends one Phase-B frame to confirm success:

SessionReady : payload = [ 0x00, Flags: VarInt, RecvWindow: VarInt,
                           ResumeGraceMs: VarInt ]   # only when STREAM_RESUME is set

The hub echoes the accepted flags (STREAM_FC set) followed by its own per-connection receive window. A client must reject a SessionReady without the STREAM_FC flag or without a positive window (an unsupported hub).

ResumeGraceMs is present only when the hub accepts STREAM_RESUME, and states how long it will hang a player waiting for that player's stream to be reattached (§7.5). The client clamps its own retry budget below this value. Advertising it rather than assuming matching configuration is deliberate: the client must always give up first, and if the hub instead dropped a hung player while the client was still reattaching, the failure would be a silent hang rather than an error. A hub that sets the flag but omits the field is treated as not supporting resumption.

A hub that rejects the session simply closes the TCP connection (optionally after a Phase-B Error frame, §6). After SessionReady:

• Magic == 0x01 → the connection is a Control Session (§5).
• Magic == 0x02 → the connection is a Worker Conn (§7).

5. Control session messages

After SessionReady, a control session exchanges control messages, one per encrypted frame. Frame payload:

Type : u8
...  : type-specific fields

Type	Name	Direction	Fields
0x00	SessionReady	S → C	Flags: VarInt, RecvWindow: VarInt, ResumeGraceMs: VarInt (only when the hub accepted STREAM_RESUME) — the confirmation frame from §4
0x01	Register	C → S	Pattern: String
0x02	Unregister	C → S	Pattern: String
0x03	RegisterAck	S → C	Pattern: String, Status: u8 (0 = ok, 1 = invalid pattern)
0x04	ControlRequest	S → C	CID: Bytes[16], Pattern: String, PlayerIP: String, PlayerPort: U16
0x05	Ping	C → S	Nonce: I64
0x06	Pong	S → C	Nonce: I64

• Register / Unregister: the client may (un)register a PATTERN at any time. A PATTERN is a regular expression (§5.1) and is stored verbatim — the exact string is the registry key (never normalized, so regex metacharacters are preserved). Re-registering the identical pattern string reassigns it to the newest session (last writer wins); Unregister only removes it if the requesting session still owns it.
• RegisterAck: acknowledges a Register. Status is 0 on success, or 1 if the pattern is not a valid regular expression (in which case nothing is registered). The Pattern echoes the string that was registered.
• ControlRequest: emitted by the hub when a player Handshake matches a PATTERN this session registered. Pattern is the registered pattern string that matched (echoed verbatim), not the player's hostname — so the client can look the pattern up in its own route table. CID is 16 cryptographically-random bytes generated by the hub, unique to that pending player. PlayerIP/PlayerPort are the player's source address (used for HAProxy v2).
• Ping/Pong: optional keepalive so idle control sessions survive NAT timeouts. The client pings periodically; the hub echoes the nonce.

5.1 Pattern matching

A registered PATTERN is a regular expression (the reference hub uses java.util.regex). Matching is:

• Case-insensitive — patterns are compiled with a case-insensitive flag, and the player hostname is lower-cased during normalization (§2.1).
• Whole-string (anchored) — the pattern must match the entire normalized hostname, as if wrapped in ^…$. mc\.example\.com matches mc.example.com but not mc.example.com.evil or sub.mc.example.com.
• First match wins — the hostname is tested against every registered pattern; the first that matches routes the player. If several patterns overlap, which one wins is unspecified.

Because the pattern is a regex, a literal dot must be escaped (mc\.example\.com); an unescaped . is the regex "any character" wildcard. A pattern that fails to compile is rejected at Register time with RegisterAck status 1.

5.2 Orphaned routes (control-session outage)

When a control session closes, its registrations are not deleted straight away. They are marked orphaned and kept for registrationGraceMs.

This costs nothing on the wire — it is entirely hub-side behaviour — but it closes a gap that is otherwise very visible. A client whose control session dies reconnects with backoff, and until it re-registers the hub has no route for it, so every player arriving in that window is told there is no such server. The players already tunneled are unaffected, since they ride worker conns, which a control-session close never touches.

While a route is orphaned:

• a player matching it is held — paused, with its handshake buffered exactly as for a normal pending player — and no ControlRequest is sent, because there is no session to send it to;
• a player that was already pending when the session closed is moved into the same held state rather than being dropped;
• when any client registers that pattern again, the hub delivers the ControlRequest it never sent and the player proceeds normally. The held player's deadline switches from the registration grace to pendingTimeoutMs at that point, since it is now waiting for a worker rather than for a route.

If the grace expires with no client having re-registered, the route and every player held on it are dropped. registrationGraceMs: 0 disables the mechanism and restores the immediate-drop behaviour.

Note the hub cannot distinguish "this client is reconnecting" from "this client is gone for good" — that is what the grace period is a bet on. It is bounded on the client side too: the reference client retries immediately on a control-session drop and caps its backoff at 10s, so the bet is usually settled in well under a second.

6. Error frame (any redapricot connection)

At any time either side may send, then close:

Type : u8 = 0x7F
Msg  : String

Purely informational; the receiver logs it.

7. Worker conn

A Worker Conn (Magic == 0x02) carries player↔destination traffic for exactly one player. The TCP connection is the tunnel: there is no stream id and no multiplexer. The client dials a fresh worker conn for each ControlRequest (and for each resumption attempt).

Each encrypted frame on a worker conn carries one tunnel frame:

FrameType : u8
Data      : Bytes[...]     # remainder of the frame payload

FrameType	Name	Direction	Data
0x00	SYN	C → S	CID: Bytes[16] — take over the pending player identified by CID.
0x01	DATA	both	raw tunneled bytes.
0x02	FIN	both	(empty) — graceful close (both directions). This is the "disconnect" the hub sends when the player leaves.
0x03	RST	both	(optional 1 byte reason) — abnormal close (e.g. CID unknown/expired, destination dial failed).
0x04	WND	both	Delta: VarInt — flow-control credit grant (§7.3).
0x05	PING	both	Nonce: I64 — liveness probe (§7.4).
0x06	PONG	both	Nonce: I64 — echoes the probe's nonce (§7.4).
0x07	RESUME	C → S	CID: Bytes[16], Accepted: I64, Delivered: I64 — reattach a hung player to this conn (§7.5).
0x08	RESUME_ACK	S → C	Accepted: I64, Delivered: I64, NewCID: Bytes[16] — the reattach succeeded (§7.5).

The first business frame after SessionReady must be SYN or RESUME. A second bind on an already-bound conn is a protocol violation: the hub replies RST and closes. There is no explicit SYN-ACK: success is implied by the hub forwarding the buffered Handshake as the first DATA; failure is an RST.

RST reason codes. The byte remains optional — a peer that predates it sends none, and a receiver must tolerate its absence — but distinguishing the reasons matters for resumption, where "this stream is gone" and "someone else already took it" call for opposite responses.

Code	Name	Meaning
0x00	UNSPECIFIED	No reason given (also the meaning of an absent byte).
0x01	UNKNOWN_STREAM	CID unknown or expired, or the hub restarted. Terminal: stop retrying.
0x02	ALREADY_BOUND	Another reattach already claimed this stream. Do not tear down.
0x03	RESUME_ABANDONED	The peer gave up reattaching.
0x04	FLOW_CONTROL	The peer exceeded its advertised window.
0x05	DIAL_FAILED	The client could not reach the destination.

7.1 Tunnel allocation (client side)

The client dials one worker conn per player, up to a configurable maxTunnels cap (default 256, clamped to [1, 4096]). There is no pool and no least-loaded placement: a ControlRequest either gets its own TCP connection or is dropped (the hub then closes the player when pendingTimeoutMs fires).

A dial is never performed while holding the live-set lock: session establishment is network I/O, and one unresponsive hub must not be able to block unrelated players. Each dial is independent and bounded by the session-establishment deadline (§7.4); callers are not serialized behind a single in-flight handshake.

7.2 End-to-end player flow

1. Player connects to the hub and sends a Handshake with a matching ServerAddress and Intent ∉ {17,18}.
2. Hub normalizes the address, finds the registering control session, generates CID, pauses the player socket, buffers everything read so far (the raw Handshake plus any pipelined bytes), and sends ControlRequest on the control session. If no SYN arrives within pendingTimeoutMs (default 10000) the pending entry is dropped and the player socket closed.
3. The client receives ControlRequest, looks up the destination for Pattern, dials a dedicated worker conn, and sends SYN(CID). In parallel it dials the destination and (if configured) writes a HAProxy v2 header (§8) carrying PlayerIP:PlayerPort.
4. The hub matches CID to the pending player, binds workerConn ↔ playerSocket, forwards the buffered bytes as DATA, and resumes the player socket. Subsequent player bytes become DATA frames; DATA frames from the client are written to the player socket. If CID is unknown/expired the hub replies RST.
5. When the player disconnects the hub sends FIN; the client closes the destination. When the destination closes, the client sends FIN; the hub closes the player socket. RST is treated the same way (hard close).

Data on a worker conn is subject to that TCP connection's back-pressure. Credit windows of §7.3 bound how many bytes may be in flight on that one tunnel.

7.3 Per-connection flow control

Every worker conn carries an independent credit window per direction:

• Each side advertised its receive window W (bytes) at session setup. A sender may have at most W un-credited DATA bytes outstanding; the initial budget is W, spent as DATA is sent (Data length only — SYN/FIN/RST frames are free) starting with the very first DATA (including the hub's forwarded handshake).
• The receiver returns credit with WND(Delta) once bytes are delivered to the terminal socket (written to the player / destination connection), not when they are merely buffered. Receivers should batch grants (the reference implementations send one WND per W/2 bytes consumed).
• A sender whose window is exhausted pauses reading that player's source socket only. A receiver that observes more than W un-credited bytes may reset the tunnel (RST) as a protocol violation.
• Senders should also cap individual DATA payloads (the reference implementations use 32 KiB) so one write cannot occupy the link for a full 1-MiB frame.

Both windows may differ (each side enforces the one its peer advertised). Delta must be positive; a WND on an unbound worker conn is ignored.

7.4 Liveness

TCP alone cannot tell a healthy idle connection from a dead one. When a stateful middlebox forgets an established flow — conntrack expiry, a firewall reload, a cloud load balancer's idle timeout — it sends neither FIN nor RST. Both ends keep a socket that will never again carry a byte, and a reader parked on it waits forever. Without an application-level probe the client cannot notice: its worker conn stays in the pool, the hub keeps routing players to a control session nobody reads, and service does not return until the client process is restarted.

Every established session is therefore covered by a heartbeat:

• Control session — the client sends Ping every pingIntervalMs and the hub answers Pong. If no Pong arrives for 3 × pingIntervalMs, the client closes the session, which triggers its normal reconnect with backoff.
• Worker conns — when WORKER_HEARTBEAT was negotiated, the same exchange runs as connection-level PING/PONG frames. On timeout the client closes the conn. The player is reset, unless STREAM_RESUME was negotiated, in which case it is hung and reattached over a fresh conn instead (§7.5).
• Hub side — an established redapricot session that receives no frame for sessionIdleTimeoutMs (default 90000, 0 disables) is closed. Player connections are never subject to this.

Both ends also enable TCP keepalive, which catches the narrower case of a peer that has become unreachable at the IP layer.

Session establishment (§4) is bounded by a single deadline covering the dial, the Rekey write and the SessionReady read, and every frame write is bounded too — a peer that stops reading must not be able to park a write forever.

7.5 Stream resumption (STREAM_RESUME)

A worker conn is only the middle leg of the player it carries. When it dies, both terminal sockets — the player's and the destination's — are usually still healthy, so resetting the tunnel discards working connections because a replaceable transport failed.

With STREAM_RESUME negotiated, a worker-conn drop instead hangs the player:

• the hub pauses the player socket, keeps its state, and holds it for ResumeGraceMs from the moment of the first hang (an absolute deadline, so a flapping client cannot extend it indefinitely);
• the client keeps the destination socket open and reattaches over a fresh worker conn by sending RESUME with the player's CID;
• the hub answers RESUME_ACK, or RST(UNKNOWN_STREAM) if it holds no such player — which is also what a client gets from a hub that has restarted.

Resumption is byte-exact, and must be. Frames handed to a dying socket are lost with no notification, and the frame cipher cannot be resynchronized, so each side replays whatever the other did not receive. Splicing the stream even one byte off corrupts the tunneled protocol.

Three offsets are tracked per direction, and they are not interchangeable:

Offset	Meaning	Used for
Sent	bytes handed to the wire	the end of the retained region
Accepted	bytes taken off the wire toward the terminal socket	where to replay from
Delivered	bytes actually written to the terminal socket	how to restate the window

Each side retains the bytes between what the peer has credited and what it has sent. This costs no new bound: flow control (§7.3) already caps outstanding bytes at one window, so the retained region is the outstanding region.

On reattach both sides replay [peer's Accepted, Sent) and set SendWindow = W − (Sent − peer's Delivered), then discard their own pending credit — the exchanged Delivered already carries everything those deltas would have, so emitting both would grant the same bytes twice.

Two rules deserve emphasis, because the obvious simplifications are wrong:

• Accepted, not Delivered, is the replay point. Delivery is signalled asynchronously on both sides and stops being reported exactly when a connection dies; replaying from it would re-send bytes the peer already has.
• Delivered, not credited, sizes the window. Credit travels as deltas, and the grants in flight when the connection died are gone for good. A window derived from them is permanently short — and if a full window was outstanding at the drop, permanently zero, which deadlocks: nothing can be sent, so no credit can ever come back.

RESUME_ACK carries a freshly minted NewCID, which replaces the old one. A CID therefore stays single-use even though a player may be reattached many times, so a leaked CID grants no more than the outage in which it was observed.

Resumption is hub-instance-affine: a CID means nothing to a second hub behind an L4 load balancer, which answers RST(UNKNOWN_STREAM) and lets the client tear down at once. Because the grace period holds player sockets and their buffers, a hub bounds the number of hung players and the bytes they retain, dropping the oldest first when either cap is reached.

8. HAProxy protocol v2 (optional)

When a mapping has proxyProtocol: true, the client prepends a PROXY v2 header to the destination connection before any tunneled bytes, so the real server sees the player's true source address.

Signature : 0D 0A 0D 0A 00 0D 0A 51 55 49 54 0A     (12 bytes)
VerCmd    : 0x21                                     (v2, PROXY command)
FamProto  : 0x11 (TCP/IPv4) | 0x21 (TCP/IPv6)
Len       : U16  (length of the address block)
Addresses : IPv4 → srcAddr[4] dstAddr[4] srcPort[2] dstPort[2]   (12 bytes)
            IPv6 → srcAddr[16] dstAddr[16] srcPort[2] dstPort[2] (36 bytes)

src is the player; dst is the destination the client dialed. Ports are big-endian.

9. Configuration

9.1 Hub (server) — JSON

{
  "listen": "0.0.0.0:25565",
  "psk": "change-me",
  "timestampWindowMs": 30000,
  "pendingTimeoutMs": 10000,
  "streamWindowBytes": 262144,
  "sessionIdleTimeoutMs": 90000,
  "streamResume": true,
  "resumeGraceMs": 20000,
  "maxParkedStreams": 256,
  "statsIntervalMs": 0,
  "registrationGraceMs": 15000,
  "playerRatePerSec": 8,
  "playerBurst": 16,
  "maxPlayersPerIp": 64
}

streamWindowBytes (optional, default 262144, clamped to [32768, 8388608]) is the hub's advertised per-connection receive window (§7.3).

sessionIdleTimeoutMs (optional, default 90000) closes an established control session or worker conn that has gone silent for that long (§7.4). It must stay comfortably above the client's pingIntervalMs; 0 disables the watchdog.

streamResume (optional, default true) offers STREAM_RESUME (§7.5). With it false the hub never echoes the flag and behaves exactly as a hub that predates the feature, allocating no retained regions.

resumeGraceMs (optional, default 20000) is how long a hung player is held, and is advertised in SessionReady. It must exceed the client's own grace by at least one dial, which is why the client clamps itself against the advertised value rather than its own configuration.

maxParkedStreams (optional, default 256) and maxParkedBytes (default maxParkedStreams × 2 × streamWindowBytes) bound what hung players may cost; past either the oldest are dropped.

statsIntervalMs (optional, default 0 = off) logs a periodic line with live and parked stream counts, retained bytes, and the pattern count.

registrationGraceMs (optional, default 15000) is how long a closed control session's routes are kept as orphaned rather than deleted (§5.2). 0 disables it, restoring the behaviour of dropping routes the instant a session closes.

playerRatePerSec (optional, default 8) and playerBurst (optional, default 16) are a per-IP token bucket applied only to player connections (any handshake whose Intent is not 17 or 18). One arrival consumes one token; without a token the socket is closed after the handshake, before match, CID minting, or pause. Unmatched hostnames still consume a token — otherwise a hostname scan is a free flood. Intent 17 is never admitted through the limiter: every worker conn comes from the client's one address, and limiting those would be the hub throttling its own client. playerRatePerSec: 0 turns the bucket off.

maxPlayersPerIp (optional, default 64) caps concurrent player sockets from one address (pending + live + parked). 0 disables the cap. Addresses are matched exactly; IPv6 /64 aggregation is out of scope.

9.2 Client — JSON

{
  "server": "127.0.0.1:25565",
  "psk": "change-me",
  "maxTunnels": 256,
  "pingIntervalMs": 20000,
  "streamWindowBytes": 262144,
  "maxBandwidth": "20mbps",
  "streamResume": true,
  "resumeGraceMs": 15000,
  "statsIntervalMs": 0,
  "mappings": [
    { "pattern": "mc\\.example\\.com", "destination": "127.0.0.1:25566", "proxyProtocol": true }
  ]
}

maxTunnels (optional, default 256, clamped to [1, 4096]) is how many concurrent 1:1 worker connections the client will hold. A ControlRequest arriving at the cap is dropped. The older maxConn key (the mux-era pool size, clamped 1–8) is ignored if present: treating it as a player cap would silently limit a previously-working config to a handful of players.

streamWindowBytes (optional, default 262144, clamped to [32768, 8388608]) is the client's advertised per-connection receive window (§7.3).

streamResume (optional, default true) offers STREAM_RESUME (§7.5). With it false the client never offers the flag, never retains a byte for retransmission, and behaves exactly as a client that predates the feature.

resumeGraceMs (optional, default 15000, minimum 2000) is how long a hung stream keeps trying to reattach, clamped below the hub's advertised grace. The default is chosen against the backend, not the tunnel: a hung player stops answering the game server's KeepAlive, and vanilla disconnects a silent client at 30s, so a longer grace would only resume sessions the backend then kicks.

statsIntervalMs (optional, default 0 = off) logs a periodic diagnostics line and a per-stream summary at close, reporting how long each stream spent blocked on the flow-control window versus the bandwidth cap, and the heartbeat round-trip time per conn. These distinguish a slow backend from a saturated uplink from a bad path, which throughput alone cannot.

maxBandwidth (optional, default unlimited) caps the aggregate rate at which the client sends DATA to the hub, shared fairly across tunnels. Accepts "20mbps" (decimal bit units), "2MB/s" (binary byte units), or a bare number of bytes per second; the minimum is 8192 B/s. This is a purely local policy and has no effect on the wire format — a shaped client is indistinguishable from a slow one, and the hub needs no support for it. Only DATA is paced; control frames are never delayed.

Each pattern is a regular expression (§5.1) matched against the whole normalized player hostname, case-insensitively. Escape literal dots (mc\.example\.com, which is mc\\.example\\.com in JSON); an unescaped . matches any character. Use ordinary regex to route wildcards, e.g. .*\.example\.com for every subdomain or (alpha|beta)\.mc\.net for a fixed set.

velocitySecret (optional, per mapping) makes the client speak Velocity "modern forwarding" towards that destination: during the Minecraft login phase it swallows the backend's velocity:player_info Login Plugin Request and answers with an HMAC-SHA256-signed payload carrying the player's real IP, username and UUID (the UUID claimed in Login Start, or the offline-mode UUID for protocols that carry none). Set it to the backend's proxies.velocity.secret. This is purely client↔destination behavior — it does not appear on the tunnel wire, and the exchange is invisible to the player.

10. Constants summary

Name	Value
redapricot Handshake intent	17
reserved management intent	18
Handshake address for Intent 17	hex(SHA3-224(PSK))
cipher	ChaCha20 (RFC 8439), 12-byte zero nonce, per-direction key, payload-only
frame length prefix	plaintext VarInt
key derivation	SHA3-256(PK ‖ 0x01) c→s, SHA3-256(PK ‖ 0x02) s→c
rekey material	Rand ‖ Timestamp(I64 BE)
Magic: control / worker	0x01 / 0x02
RegisterAck status: ok / invalid pattern	0x00 / 0x01
pattern matching	case-insensitive, whole-string regex; first match wins
CID length	16 bytes
max frame payload	1 MiB
worker framing	FrameType + payload; no stream id
max concurrent worker conns	maxTunnels, default 256, clamped [1, 4096]
player IP rate / burst / concurrent	8 /s, burst 16, maxPlayersPerIp 64 (Intent ∉ {17, 18} only)
feature flag: per-connection flow control	0x01 (mandatory)
feature flag: worker heartbeat	0x02 (negotiated)
heartbeat timeout	3 × pingIntervalMs
hub session idle timeout	90000 ms (0 disables)
connection window default / bounds	256 KiB, clamped to [32 KiB, 8 MiB]
feature flag: stream resumption	0x04 (negotiated)
RESUME / RESUME_ACK	0x07 / 0x08
resume grace: hub / client default	20000 ms / 15000 ms (hub value advertised)
retained region per tunnel per direction	bounded by the connection window
WND grant batching (reference)	one grant per window/2 consumed
DATA chunk cap (reference)	32 KiB