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(mux)══▶ 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 == 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-stream receive window, bytes (§7.3)

Flags is a bitfield of features.

Bit	Name	Meaning
0x01	STREAM_FC	Per-stream flow control (§7.3). Mandatory.
0x02	WORKER_HEARTBEAT	Mux-level PING/PONG on worker conns (§7.4). Optional.

STREAM_FC is mandatory: RecvWindow advertises the client's per-stream 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 ]

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

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	(none) — 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.

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 & multiplexing

A Worker Conn (Magic == 0x02) carries player↔destination traffic for many players over one TCP connection using a minimal stream multiplexer. The unit of work is a stream. Stream ids are assigned by the client (the only side that opens streams), unique per worker conn, starting at 1 and increasing.

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

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

FrameType	Name	Direction	Data
0x00	SYN	C → S	CID: Bytes[16] — open a stream to take over the pending player identified by CID.
0x01	DATA	both	raw tunneled bytes for the stream.
0x02	FIN	both	(empty) — graceful close of the stream (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 on reserved StreamID 0 (§7.4).
0x06	PONG	both	Nonce: I64 — echoes the probe's nonce (§7.4).

There is no explicit SYN-ACK: success is implied by the hub forwarding the buffered Handshake as the stream's first DATA; failure is an RST.

7.1 Stream allocation (client side)

The client keeps a pool of 1 ≤ N ≤ max_conn worker conns (max_conn configurable, 1..8). The pool grows breadth-first: spreading streams over several connections keeps any single TCP connection from becoming the shared point of failure for every player on the tunnel. To place a new stream:

1. Pick the worker conn with the fewest active streams, and use it.
2. If that conn already carries at least one stream and poolSize + dialsInFlight < max_conn, dial another worker conn in the background. The stream just placed is not delayed by that dial; the new conn becomes the least-loaded one and picks up subsequent streams.
3. Once the pool is at max_conn, streams stack on the least-loaded conn. Exceeding 8 active streams there is logged as pool saturation.

Only when the pool is empty does a caller dial synchronously, and then exactly one caller dials while the others wait for its result. A dial is never performed while holding the pool lock: session establishment is network I/O, and one unresponsive hub must not be able to block unrelated players.

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, allocates a worker conn + StreamID, and sends SYN(StreamID, 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, StreamID) ↔ 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 on the stream; 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 for its aggregate bandwidth; per-stream fairness is governed by the credit windows of §7.3.

7.3 Per-stream flow control

Every stream 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 per stream; 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 on the stream (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 stream's source socket only; the shared worker conn is never paused because of a single stream. A receiver that observes more than W un-credited bytes on a stream may reset it (RST) as a protocol violation.
• Senders should also cap individual DATA payloads (the reference implementations use 32 KiB) so one stream cannot monopolize 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 for an unknown stream id 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 mux PING/PONG frames on the reserved StreamID 0. On timeout the client closes the conn; its streams are reset and it is dropped from the pool, so the next player gets a freshly dialed connection.
• 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 (§3.2) 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 whole multiplexed connection inside one write.

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
}

streamWindowBytes (optional, default 262144, clamped to [32768, 8388608]) is the hub's advertised per-stream 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.

9.2 Client — JSON

{
  "server": "127.0.0.1:25565",
  "psk": "change-me",
  "maxConn": 4,
  "pingIntervalMs": 20000,
  "streamWindowBytes": 262144,
  "mappings": [
    { "pattern": "mc\\.example\\.com", "destination": "127.0.0.1:25566", "proxyProtocol": true }
  ]
}

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

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
pool growth	breadth-first: grow to max_conn before stacking
saturation threshold (logged)	active streams > 8 at max_conn
max worker conns	max_conn ∈ [1,8]
feature flag: per-stream flow control	0x01 (mandatory)
feature flag: worker heartbeat	0x02 (negotiated)
heartbeat timeout	3 × pingIntervalMs
hub session idle timeout	90000 ms (0 disables)
stream window default / bounds	256 KiB, clamped to [32 KiB, 8 MiB]
WND grant batching (reference)	one grant per window/2 consumed
DATA chunk cap (reference)	32 KiB