🔁 FireMUD System Architecture: Reconnection Strategy

FireMUD enables seamless gameplay recovery across network interruptions, client reconnects, and backend service restarts — using a layered reconnection model and Redis-backed session state.

🧩 Reconnection Layers

Each layer handles fault tolerance independently. Only client connection loss requires reauthentication. Infra restarts (Proxy, Gateway, Session) are transparent if the client remains connected.

🛰️ Layer Behavior Breakdown

TCP Proxy Service (Telnet Clients)

• Accepts raw TCP input and assembles it into commands
• Buffers input during connection, but clears on disconnect
• No gameplay state is preserved across reconnects — Game Session Service handles recovery

Spring Cloud Gateway (Web Clients)

• Stateless WebSocket router
• Automatically re-establishes backend connections if restarted
• Holds no gameplay, auth, or session state

Proxy and Gateway restarts do not interrupt gameplay as long as the client’s physical connection is maintained.

Game Session Service

• Uses Redis to store and recover session state, including command queues, tick participation, cooldowns, and retry info
• On reconnect, rebinds:
  • Socket connection
  • Tick region context
  • Timers and in-flight actions

🔗 Full structure of Redis session keys is documented in Session Keys and Gameplay Binding

🔐 When Reauthentication Is Required

Clients must send a LOGIN command after any disconnect, such as:

• TCP loss (Telnet clients)
• WebSocket loss (Web clients)

Redis-backed session state enables seamless resumption if valid, or fresh login if expired.

🧭 For full details on LOGIN behavior, argument formats, and session flow, see Authentication & Authorization

👥 Multi-Client and Session Takeover

Gameplay resumes cleanly when a session is resumed — whether due to reconnect or takeover.

🔄 For full takeover behavior, including forced logins from a different client and Redis socket rebinding, see Authentication & Authorization.

🔄 Resume vs Reload Scenarios

🔑 Only client disconnection requires LOGIN. Backend service restarts are invisible unless the physical connection is lost.

🧠 Design Principles

• Redis stores:
  • Socket bindings and session metadata
  • Queued commands and tick state
  • Timers, cooldowns, and retry info
• Game Session Service governs all reconnection, deduplication, and rebinding
• Clients are fully stateless
• Transparent failover is supported across infrastructure layers

📚 Related Documentation

• Tick System and Runtime Design
• Redis Architecture
• Authentication & Authorization