Skip to content

Releases: Hybrowse/hyrouter

v1.0.0

01 Feb 17:48
@Krymonota Krymonota
v1.0.0
619a69b

Choose a tag to compare

View all tags
v1.0.0 Latest
Latest

Overview

This is the initial release of Hyrouter — a highly flexible, plugin-driven Layer 7 referral router and QUIC entrypoint for Hytale.

Hyrouter gives you a clean “front door” for a backend fleet: it accepts an incoming QUIC connection, inspects minimal metadata (TLS SNI + the first Connect packet), applies routing rules and optional plugins, and then either:

  • Denies the connection with a Hytale Disconnect packet, or
  • Redirects the client to a backend using a Hytale ClientReferral packet.

Hyrouter is not a reverse proxy and does not forward gameplay traffic.

Important client compatibility note

Due to a client-side bug, redirects via ClientReferral only work correctly starting with Hytale client version pre-release/2026.01.29 (expected to ship broadly in the next regular client release / Patch 3).

Highlights

  • SNI / hostname routing
    • Route matching via TLS SNI (match.hostname / match.hostnames)
    • Wildcard support using Go path.Match semantics (e.g. *.example.com)
  • Built-in load balancing per route
    • Strategies: round_robin, random, weighted, least_loaded, p2c (power-of-two-choices)
  • Pre-selection controls for backend choice
    • Candidate filtering, sorting, and limiting
    • Fallback selection attempts if filters yield no candidates
  • Dynamic backend discovery
    • Kubernetes discovery (Pods / EndpointSlices)
    • Agones discovery (observe mode + allocate mode)
  • Plugin system (gRPC + WASM)
    • Deterministic plugin ordering
    • Stages: deny → route → mutate
    • Plugins can deny connections, override routing decisions, and attach referral content
  • Optional signed referral envelope
    • Fixed, versioned referral envelope wrapping plugin referral content
    • Optional HMAC-SHA256 signing for backend verification
  • Stateless data plane
    • No required DB/Redis
    • No gameplay proxying (lower operational cost and complexity)

Connection flow (high level)

  • QUIC handshake + ALPN negotiation (recommended hytale/* to pick the highest hytale/<n> offered by the client)
  • Hyrouter reads the first framed packet: Connect (packet ID 0)
  • Routing is selected (SNI rules + load balancing + optional plugins)
  • Hyrouter sends:
    • ClientReferral (packet ID 18) on success, or
    • Disconnect (packet ID 1) when denied / no viable backend
  • Stream closes immediately

Configuration & operations

  • YAML and JSON configuration support
  • Development configs included under dev/:
    • baseline, plugin demo, Kubernetes discovery examples, Agones observe/allocate examples
  • Optional localized disconnect messages (messages.disconnect_locales)
  • TLS behavior:
    • Uses configured cert/key when provided
    • Generates a short-lived self-signed certificate for development if omitted
    • Requests (but does not require) a client certificate; fingerprint is exposed to plugins
  • Logging verbosity via -log-level (debug|info|warn|error)

Docker / Images

  • Docker Hub: hybrowse/hyrouter
  • GHCR: ghcr.io/hybrowse/hyrouter

Example run (mount your config):

docker run --rm \
  -p 5520:5520/udp \
  -v $(pwd)/config.yaml:/app/config.yaml \
  hybrowse/hyrouter:v1.0.0

Docs

Security Notes

  • Do not post tokens/credentials or sensitive backend details in issues.
  • Please report vulnerabilities via GitHub Security Advisories.
Assets 2
Loading