Hydra proxy and client work update
1 view
Skip to first unread message
Brazil
Mar 23, 2026, 11:51:22 AMMar 23
to tinymux
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
Subject: Hydra proxy and client work update
Alongside the 2.14.0.5 server release, there has been a large amount
of work on the Hydra persistent connection proxy and the client suite.
None of this is in the server distribution yet, but it is all in the
tinymux repository on GitHub for anyone who wants to look or play.
Hydra Proxy
- -----------
Hydra is a persistent connection proxy that sits between MUX clients
and the server. It maintains your session even when your client
disconnects -- scroll-back is preserved and replayed when you
reconnect. Think of it as a MUX-aware tmux/screen.
The proxy was designed, implemented, reviewed, and hardened over the
course of this development cycle:
Architecture:
- GANL-based telnet back-door connects to MUX; front-door accepts
client connections via raw telnet, WebSocket (RFC 6455), and gRPC.
- Embedded grpc-web server for browser clients (no Envoy required).
- Session manager with token-based authentication.
- Multi-link sessions with automatic reconnect and backoff.
- Process manager for launching and monitoring local game instances.
Security:
- AEAD-encrypted scroll-back persistence (AES-256-GCM).
- Split key hierarchy: player-derived keys for scroll-back data.
- Master key management: environment variable, permission checks,
auto-generation.
- TLS on all front-door listeners by default.
- Browser session tokens in sessionStorage (not localStorage).
- Connection rate limits and login lockout.
- Per-session memory cap (maxScrollbackMemoryMb).
Protocol:
- Full GMCP forwarding between client and server.
- GMCP synthesis: Core.Hello, Core.KeepAlive, Hydra.Links.
- GMCP state cache with replay on client attach.
- Color and charset translation in the telnet bridge.
- ANSI SGR to PUA color conversion (co_parse_ansi).
- ColorFormat negotiation via SetPreferences.
- Deferred color rendering at per-subscriber read time.
- Terminal size reporting for legacy and grpc-web clients.
- NAWS forwarding.
Reviewed and hardened:
- Two full code review rounds with all findings resolved.
- Replaced all raw send() with GANL postWrite via safeWrite helper.
- Centralized GMCP and NAWS frame builders.
- Standardized session ID naming across the codebase.
- Fixed stream race, IAC escape, O(N) memory, strerror issues.
- Deferred link reconnection until player authenticates after
restart.
gRPC API (hydra.proto):
- 18 RPCs covering session lifecycle, game management, credentials,
and admin operations.
- Bidirectional GameSession stream for real-time I/O.
- Proto enums for state fields (replaced string encoding).
- GetScrollBack with color format support.
Client Suite
- ------------
Six clients now have Hydra/gRPC transport alongside their existing
direct-connect capability:
- TitanFugue (TF) -- the original TinyMUX client, Tcl/Tk.
- Console -- Windows command-line client.
- Win32GUI -- Windows native GUI client.
- Android -- Kotlin, with World Manager UI for Hydra.
- iOS -- Swift, gRPC transport.
- HTML5/Web -- JavaScript, grpc-web transport.
All clients gained:
- Hydra session management commands (/hconnect, /hdetach, /hcreate,
/hsessions, /hattach, etc.).
- Auto-reconnect on gRPC stream failure.
- SetPreferences on stream open (color format, terminal size).
- Scroll-back fetch on reconnect.
- Keepalive pings and credential management.
- Process management commands (start/stop/restart local games).
- Per-world logging (/log -w).
TF-specific:
- Session persistence across client restart.
- Fixed hardcoded terminal size.
- Fixed plaintext gRPC and send_naws color tracking.
Android-specific:
- Fixed inputChannel lifecycle and resend preferences on reconnect.
HTML5-specific:
- Live grpc-web Subscribe streaming with session persistence.
- Fixed color format encoding.
Other Work
- ----------
- TinyMUX 2.14 Code Review Report and Strategic Roadmap (docs/).
- Parser compatibility study: profiles, percent-substitution matrix,
escape oracles, noeval brace-group backslash handling.
- Parser control options documentation.
- JIT specs updated: Level 4 re-entrancy deferred, Phase 3 complete.
- Softcode accessor redesign spec for comsys and mail modules.
All of this is on the master branch at:
https://github.com/brazilofmux/tinymux
- -- Brazil
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCgAdFiEE8GWFNwJrhRGk25uvF80K5PxQP7EFAmnBYVQACgkQF80K5PxQ
P7FgDg/+OqmKiquPDhtyuGUeqzhhwAL8HJ9n7TfVmtCxIXY21dpKlYikFF4wjqqB
9k2O4VNfforXzv4RWG2hCjRV2NpcF6F88+OQi8Hwd+Kpkoe6yu/oui91V+ScOYIV
biYqgLgh99ihF15zrSlqTaRQtBTPWAtviQ0yRLQNQCcWi7yhtwPTzSGR6umCJwcy
7X015/kyka5b7BIt0BxeBhOsFaO+ZsKMPWudbzp/lrADEmACxT3PEODFKEPkaFSJ
669ku9xOa+ydm5Wj5P1CtLV4Kaj2xv4NF5RPdrtwFBX8oOmGfk6e78ZJfuhvJUJn
gxqg6dEui/KEBlMzrqBa5qySbJEv29/+TRgRUe5qukIdl8Y8QKejF+X7m24D4JBB
+FdHvjg8JXZlJ2VO8Llh8dTCAeoFkpT7JvkYPNN1tT3mha/yljf+bgdZ4WfLGrC6
ue0/BG9N64oltuEj1m5+DLjopDbKa2LtlUSEwHPezllXnFDrUa7umXJt2Tl+bNXQ
xMv8SJjH7IBZh1GJhL2yQmBDXD29Ob4wB1G4HoOVgOpQrlqPMEwRdMhXwdNAm1dc
zpRea0VU7oMM3/PSXmRJS1Xx5idxfGBi3S64fOyO3jlhE3MzOiZZ5Pp+FabKhdO2
hB3WFopL19SFTFzFZ58E8hGTPuRQsXwH/8vSPTAVvLOgwfbQnIY=
=gDAD
-----END PGP SIGNATURE-----
Hash: SHA512
Subject: Hydra proxy and client work update
Alongside the 2.14.0.5 server release, there has been a large amount
of work on the Hydra persistent connection proxy and the client suite.
None of this is in the server distribution yet, but it is all in the
tinymux repository on GitHub for anyone who wants to look or play.
Hydra Proxy
- -----------
Hydra is a persistent connection proxy that sits between MUX clients
and the server. It maintains your session even when your client
disconnects -- scroll-back is preserved and replayed when you
reconnect. Think of it as a MUX-aware tmux/screen.
The proxy was designed, implemented, reviewed, and hardened over the
course of this development cycle:
Architecture:
- GANL-based telnet back-door connects to MUX; front-door accepts
client connections via raw telnet, WebSocket (RFC 6455), and gRPC.
- Embedded grpc-web server for browser clients (no Envoy required).
- Session manager with token-based authentication.
- Multi-link sessions with automatic reconnect and backoff.
- Process manager for launching and monitoring local game instances.
Security:
- AEAD-encrypted scroll-back persistence (AES-256-GCM).
- Split key hierarchy: player-derived keys for scroll-back data.
- Master key management: environment variable, permission checks,
auto-generation.
- TLS on all front-door listeners by default.
- Browser session tokens in sessionStorage (not localStorage).
- Connection rate limits and login lockout.
- Per-session memory cap (maxScrollbackMemoryMb).
Protocol:
- Full GMCP forwarding between client and server.
- GMCP synthesis: Core.Hello, Core.KeepAlive, Hydra.Links.
- GMCP state cache with replay on client attach.
- Color and charset translation in the telnet bridge.
- ANSI SGR to PUA color conversion (co_parse_ansi).
- ColorFormat negotiation via SetPreferences.
- Deferred color rendering at per-subscriber read time.
- Terminal size reporting for legacy and grpc-web clients.
- NAWS forwarding.
Reviewed and hardened:
- Two full code review rounds with all findings resolved.
- Replaced all raw send() with GANL postWrite via safeWrite helper.
- Centralized GMCP and NAWS frame builders.
- Standardized session ID naming across the codebase.
- Fixed stream race, IAC escape, O(N) memory, strerror issues.
- Deferred link reconnection until player authenticates after
restart.
gRPC API (hydra.proto):
- 18 RPCs covering session lifecycle, game management, credentials,
and admin operations.
- Bidirectional GameSession stream for real-time I/O.
- Proto enums for state fields (replaced string encoding).
- GetScrollBack with color format support.
Client Suite
- ------------
Six clients now have Hydra/gRPC transport alongside their existing
direct-connect capability:
- TitanFugue (TF) -- the original TinyMUX client, Tcl/Tk.
- Console -- Windows command-line client.
- Win32GUI -- Windows native GUI client.
- Android -- Kotlin, with World Manager UI for Hydra.
- iOS -- Swift, gRPC transport.
- HTML5/Web -- JavaScript, grpc-web transport.
All clients gained:
- Hydra session management commands (/hconnect, /hdetach, /hcreate,
/hsessions, /hattach, etc.).
- Auto-reconnect on gRPC stream failure.
- SetPreferences on stream open (color format, terminal size).
- Scroll-back fetch on reconnect.
- Keepalive pings and credential management.
- Process management commands (start/stop/restart local games).
- Per-world logging (/log -w).
TF-specific:
- Session persistence across client restart.
- Fixed hardcoded terminal size.
- Fixed plaintext gRPC and send_naws color tracking.
Android-specific:
- Fixed inputChannel lifecycle and resend preferences on reconnect.
HTML5-specific:
- Live grpc-web Subscribe streaming with session persistence.
- Fixed color format encoding.
Other Work
- ----------
- TinyMUX 2.14 Code Review Report and Strategic Roadmap (docs/).
- Parser compatibility study: profiles, percent-substitution matrix,
escape oracles, noeval brace-group backslash handling.
- Parser control options documentation.
- JIT specs updated: Level 4 re-entrancy deferred, Phase 3 complete.
- Softcode accessor redesign spec for comsys and mail modules.
All of this is on the master branch at:
https://github.com/brazilofmux/tinymux
- -- Brazil
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCgAdFiEE8GWFNwJrhRGk25uvF80K5PxQP7EFAmnBYVQACgkQF80K5PxQ
P7FgDg/+OqmKiquPDhtyuGUeqzhhwAL8HJ9n7TfVmtCxIXY21dpKlYikFF4wjqqB
9k2O4VNfforXzv4RWG2hCjRV2NpcF6F88+OQi8Hwd+Kpkoe6yu/oui91V+ScOYIV
biYqgLgh99ihF15zrSlqTaRQtBTPWAtviQ0yRLQNQCcWi7yhtwPTzSGR6umCJwcy
7X015/kyka5b7BIt0BxeBhOsFaO+ZsKMPWudbzp/lrADEmACxT3PEODFKEPkaFSJ
669ku9xOa+ydm5Wj5P1CtLV4Kaj2xv4NF5RPdrtwFBX8oOmGfk6e78ZJfuhvJUJn
gxqg6dEui/KEBlMzrqBa5qySbJEv29/+TRgRUe5qukIdl8Y8QKejF+X7m24D4JBB
+FdHvjg8JXZlJ2VO8Llh8dTCAeoFkpT7JvkYPNN1tT3mha/yljf+bgdZ4WfLGrC6
ue0/BG9N64oltuEj1m5+DLjopDbKa2LtlUSEwHPezllXnFDrUa7umXJt2Tl+bNXQ
xMv8SJjH7IBZh1GJhL2yQmBDXD29Ob4wB1G4HoOVgOpQrlqPMEwRdMhXwdNAm1dc
zpRea0VU7oMM3/PSXmRJS1Xx5idxfGBi3S64fOyO3jlhE3MzOiZZ5Pp+FabKhdO2
hB3WFopL19SFTFzFZ58E8hGTPuRQsXwH/8vSPTAVvLOgwfbQnIY=
=gDAD
-----END PGP SIGNATURE-----
Reply all
Reply to author
Forward
0 new messages