# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

redapricot is a central-hub P2P tunnel that speaks an *extension* of the Minecraft Java
Edition protocol. A **hub** (Java/Vert.x, one public TCP port) forwards players to a
**client** (Go) sitting next to a real Minecraft server behind NAT. Everything — players
and clients alike — arrives on the same port; the hub tells them apart by the handshake
`Intent` field (`17` = redapricot, `18` reserved, anything else = player).

Two implementations of one wire protocol live in this repo, so **most changes are
cross-language**. `PROTOCOL.md` is the normative spec; `docs/architecture.md` explains the
design rationale.

## Build

`scripts/build.sh` builds both sides (hub via `installDist`, client into `bin/`). It
auto-discovers a JDK/Gradle under `~/.sdkman/candidates/`.

**Gradle needs an explicit `JAVA_HOME` in this environment** — it is not inherited:

```bash
JAVA_HOME=$HOME/.sdkman/candidates/java/current gradle -p server installDist
JAVA_HOME=$HOME/.sdkman/candidates/java/current gradle -p server test
JAVA_HOME=$HOME/.sdkman/candidates/java/current gradle -p server shadowJar   # fat jar
go build ./...                                                                # Go side
```

## Test

```bash
./scripts/e2e.sh                          # build both, Go unit tests, then e2e
go test ./client/... -count=1             # Go unit tests (codec, crypto, pool, shaper, velocity)
go test ./e2e/... -count=1 -v -timeout 300s
go test ./e2e/ -run TestRoundTrip -v      # one e2e test
go test ./client/ -run TestShaperEnforcesRate -v
```

The e2e suite spawns the **real Java hub as a subprocess** from
`server/build/install/redapricot-server` (via `-cp lib/* io.icybear.redapricot.Main`) and
runs the Go client in-process against a mock destination. It fails fast if the hub has not
been installed, so **rebuild the hub after touching Java** or e2e silently tests stale
bytecode. `resolveJava` skips the suite when no JDK is found (`JAVA_HOME`, SDKMAN, `PATH`).

Timing-sensitive suites (`e2e/bandwidth_test.go`, `client/shaper_test.go`,
`e2e/slowstream_test.go`, `e2e/resilience_test.go`, `e2e/resume_test.go`) assert on rates
and recovery deadlines; give them slack rather than tightening thresholds. The resume tests
are load-sensitive — a busy machine (a gradle daemon in the background) shifts the races
they exercise, so run them a few times rather than trusting a single pass.

## Architecture

### Connection kinds (all on one port)

| First handshake | Becomes |
|---|---|
| `Intent 17`, rekey magic `0x01` | **control session** — pattern registration, `ControlRequest`, Ping/Pong |
| `Intent 17`, rekey magic `0x02` | **worker conn** — one player, 1:1 |
| any other intent | **player** — hostname regex-matched, then tunneled |

Session establishment (both kinds): plaintext handshake whose `Server Address` is
`hex(SHA3-224(PSK))` → one frame encrypted with PSK-derived keys carrying
`magic ‖ rand ‖ timestamp ‖ flags ‖ window` → **both sides switch ciphers** to keys derived
from `rand‖ts` → hub replies `SessionReady` echoing accepted flags and its window.

### Player handoff

The hub pauses and buffers a matched player socket, mints a random 16-byte **CID**, and
sends `ControlRequest(CID, matchedPattern, ip, port)` down the control session. The client
dials a dedicated worker conn, `SYN`s it with that CID, dials the destination, and the hub
binds the pending player to that conn. The CID's secrecy (it only ever travels encrypted
over the control session) is what authorizes the takeover — there is no other client
identity check. The hub echoes **the matched pattern string, not the player's hostname**,
so the client can look it up directly in its route table; the buffered handshake is
forwarded verbatim so the backend sees the original hostname.

### Code map

- `server/src/main/java/io/icybear/redapricot/` — `HubConnection` (per-socket state machine:
  handshake parse → dispatch → rekey → control/worker/player), `Hub` (pattern registry, CID
  table, pending players), `ControlSession`, `WorkerConn` (1:1 tunnel + flow-control state),
  `net/EncryptedFrames`, `crypto/Crypto`, `util/` (VarInt, ProtoReader/Writer, Hex).
- `client/` — `client.go` (control session, reconnect, dispatch), `worker.go` (1:1
  dial, `WorkerConn`, `Stream` and its two goroutines), `shaper.go` (egress rate cap),
  `velocity.go` (Velocity modern-forwarding interception), `proxyproto.go` (HAProxy v2),
  `config.go` (config + all protocol constants), `wire/` (VarInt/MC codec, SHA3+ChaCha20,
  `FramedConn`).
- `cmd/redapricot-client/` — binary entrypoint; `e2e/` — integration harness.

### Threading

- **Hub:** a single Vert.x verticle instance, so the pattern registry, CID table, and all
  per-connection state are touched by one event loop and need no locking. Never introduce a
  blocking call there.
- **Client:** one goroutine reads each connection; `WriteFrame` is mutex-serialized. Each
  tunnel has exactly two goroutines — `run` (destination → hub) and `writeLoop` (the *only*
  writer to the destination, draining a queue fed by the worker readLoop). The readLoop must
  never write to a destination: WND is granted only after the dest write completes, and a
  stalled backend must not stall heartbeat / FIN dispatch on that conn.

## Invariants to preserve when editing

- **Constants are mirrored** in `client/config.go` and `server/.../Protocol.java`. Changing
  one without the other is a silent protocol break; update `PROTOCOL.md` too.
- **The frame length prefix is plaintext, the payload is encrypted.** This is deliberate: a
  reader always knows how many ciphertext bytes belong to the current frame, which makes the
  rekey cipher switch unambiguous. Do not encrypt the length.
- **Per-direction keys, fixed zero nonce** (`SHA3-256(phaseKey ‖ 0x01)` c2s,
  `‖ 0x02` s2c). Both directions must never share a keystream. Go `x/crypto/chacha20` and
  Java JCE `ChaCha20` are byte-identical here, and unit tests on both sides pin the same
  SHA3-224 vector — keep that pinning if you touch crypto.
- **Per-connection flow control is mandatory.** The hub rejects a session whose rekey lacks
  `FLAG_STREAM_FC`; the client rejects a hub that does not echo it. Credit is granted back
  (`WND`) only as bytes are actually written to the terminal socket, batched at half-window.
- **One worker conn carries one player.** There is no stream id. The first business frame
  after `SessionReady` is `SYN` or `RESUME`; a second bind on the same conn is a protocol
  violation. `PING`/`PONG` are connection-scoped frames.
- **Only DATA is shaped** by `client/shaper.go`. Delaying `FIN`, `WND`, or `PONG` would trip
  the very liveness detection the heartbeat exists for. The shaper is client-local and
  invisible on the wire.
- **Each player gets its own worker dial**, up to `maxTunnels` (default 256). A dial is
  never performed while holding the live-set lock: session establishment is network I/O,
  and one unresponsive hub must not block unrelated players.
- **The hub IP limiter is player-only.** Intent 17 (control + workers) is never
  admitted through it — those sockets share the client's one address. Unmatched
  player hostnames still consume a token. `0` turns each knob off.
- **Liveness is explicit everywhere:** every session heartbeats (drop after
  `3 × pingIntervalMs`), every socket write is bounded, establishment has a deadline. A
  silently blackholed path (NAT forgetting a flow, no FIN/RST) must recover without operator
  action — `TestBlackholedPathRecovers` guards this.
- **Stream resumption is byte-exact or it is nothing** (`PROTOCOL.md §7.5`,
  `client/resume.go`, `WorkerConn.handleResume`). A worker-conn drop hangs the player and
  reattaches over a fresh conn. Three offsets are tracked per direction and are
  *not* interchangeable: replay from the peer's **accepted** offset, restate the window from
  its **delivered** offset, and never size the window from **credited** — the grants in
  flight when the conn died are gone for good, and a window derived from them can be
  permanently zero, which deadlocks. `TestResumePreservesByteStream` guards this.
- **The retained region needs no cap of its own.** Flow control already bounds outstanding
  bytes to one window, so the retransmit buffer *is* the outstanding region. Anything that
  lets a sender exceed its window silently makes it unbounded.
- **Hub-side socket handlers must route through `st.worker`, never through a captured
  conn.** A lambda installed in `handleSyn` closes over `this`; after a reattach it would
  write into the dead conn's transport, where sends are dropped silently and the player goes
  mute with nothing logged.
- **A closed control session orphans its routes rather than deleting them**
  (`PROTOCOL.md §5.2`, `Hub.removeSession`). Players arriving during the client's
  reconnect are held and replayed once it re-registers, instead of being told there
  is no such server. Two traps: `Hub.match` must surface the orphaned state rather
  than hand back a dead `ControlSession` (`EncryptedFrames.send` drops silently on a
  closed transport, so the player would hang with no request ever sent), and a held
  player's deadline is the registration grace, not `pendingTimeoutMs` — whichever is
  shorter fires first and closes the socket.
- **The off switches must reach the hot path, not just the wire.** `streamResume: false`
  allocates no retained region and `statsIntervalMs: 0` allocates no counters, so both cost
  one predictable branch. `TestResumeDisabledAllocatesNothing` guards the first.

## Conventions

- Comments here explain *why*, often citing the failure they prevent, and reference
  `PROTOCOL.md §N`. Match that when adding code on either side.
- Wire-visible behaviour changes need: both implementations, `PROTOCOL.md`, an e2e test, and
  usually a note in `docs/architecture.md` and the README config tables.
- Java uses Lombok (freefair plugin) and Log4j2; JUL is routed through Log4j2 both via
  `applicationDefaultJvmArgs` and programmatically in `Main` for the `java -jar` path.