Networks & proxies

There are two supported ways to run Teho on a network. Pick one per network.

#A · Backends only

Install TehoAPI.jar on each backend and nothing on the proxy. Each backend runs its own HelloRequest -> Hello -> Welcome when the player arrives. State from the previous backend is cleared by the new Welcome.

#B · Proxy plugin plus backends

Install the proxy plugin, then set the same secret everywhere:

proxy:
  secret: "a long random string shared by the proxy and every backend"

Player-info forwarding is required: Velocity modern forwarding or BungeeCord ip_forward. Firewall your backends as usual.

#What happens on join

1. The client handshakes with the proxy. The proxy answers with a Welcome that carries the network's server-name.
2. When the player connects to a backend, the proxy sends that backend a handoff on the teho:proxy channel: the player's UUID, the negotiated protocol and capabilities, the client's Hello fields and the session id.
3. The backend creates the session from the handoff, fires TehoPlayerReadyEvent and applies its presets. The client does not handshake again.

#What happens on a server switch

• The proxy sends the client a Reset, which clears the old server's waypoints, HUD and rules.
• It then re-sends the network-level state it set itself, such as staff grants, network rules and anything set through TehoApi on the proxy.
• If a backend sends its own Reset, the proxy re-applies its state about 100 ms later.

#Client replies still reach backends

Client frames other than Hello, such as consent results, staff tool state, key presses and UI events, are handled on the proxy and also relayed to the current backend inside signed relays. TehoConsentEvent, TehoStaffToolEvent and TehoClientEvent therefore fire on both layers. Frames from a backend to the client pass through the proxy unchanged.

#How the proxy channel is secured

• Every teho:proxy message is signed with HMAC-SHA256 over a domain prefix plus the body, using your secret.
• Messages are bound to the player's UUID, valid for ±30 seconds and single-use, enforced with a nonce replay cache.
• Backends drop any message that fails a check and log the reason at most every 10 seconds.
• The proxy drops any teho:proxy frame a client tries to send, and ignores a Hello inside a relay, even a chunked one.

#Pick one layer per feature

ModuleRules and StaffGrant are full replaces on the client. Let the proxy own network-wide staff tools and rules, and let backends own game features such as waypoints, HUD and notifications. If both layers set rules, the last frame the client received wins.