Matchmaking returns "Session not found" (401) for a valid JWT after a transient MQTT disconnect, with no recovery path

[ChronoFinale]

Matchmaking returns "Session not found" (401) for a player with a valid JWT, with no recovery path

Summary

A player who is correctly authenticated (valid JWT) can be permanently locked out of matchmaking with Session not found (401) after a single transient MQTT disconnect. Retrying does not help, because nothing recreates the in-memory session and the still-valid JWT means the client never re-authenticates. The only workaround is a full client restart.

Root cause

The in-memory session and the stateless JWT have decoupled lifetimes, and the matchmaking route is the only flow that requires the session strictly instead of self-healing.

1. Sessions are in-memory only. src/state/index.ts — export const sessions = new Map<string, PlayerSession>(). No persistence, no rehydration on startup.

2. JWT auth never checks for a session. src/middleware/authenticate.ts only runs verifyJwt(token) and sets req.player. A valid token passes even when the session is gone.

3. A non-lobby disconnect reaps the session immediately. src/features/emqx/emqx.route.ts:

   async function releasePlayerLobbyOrSession(clientid) {
     const session = getSession(clientid)
     if (!session) return
     leaveAllQueues(clientid)
     if (session.lobbyCode) {
       await startGracePeriod(clientid) // lobby members get a grace period
     } else {
       removeSession(clientid)          // everyone else is removed on the spot
     }
   }

   The MQTT clientid is the playerId (the client sends player_id as the MQTT client id), so getSession(clientid) / removeSession(clientid) resolve the real session. A player who is matchmaking — and therefore not yet in a lobby — has their session deleted the instant EMQX reports client.disconnected.

4. Matchmaking requires the session strictly. src/features/matchmaking/matchmaking.route.ts:

   const session = getSession(req.player.playerId)
   if (!session) throw new AppError('Session not found', 401)

   By contrast, ~5 other endpoints call ensureSession() (src/features/auth/auth.service.ts), which rebuilds the session from the DB when it's missing. Matchmaking is the asymmetric one that does not self-heal.

Reproduction

1. Authenticate (Steam) — session created, MQTT connected.
2. Drop the MQTT connection briefly (ordinary network blip). The client default is reconnect = false, so it does not auto-reconnect.
3. EMQX fires client.disconnected; since the player isn't in a lobby, the server calls removeSession immediately.
4. Click matchmake → POST /api/matchmaking/queue with the still-valid JWT → getSession returns nothing → Session not found (401).
5. Retrying never recovers: the JWT is still valid, so the client doesn't re-auth, and nothing else recreates the session.

Impact

A single transient disconnect strands an authenticated player. From the user's side it looks like matchmaking is simply broken; the only fix they have is to fully quit and relaunch the game (which forces a fresh /auth and recreates the session).

Suggested fixes (in order of smallest blast radius)

1. Make matchmaking self-heal like the other routes — use ensureSession(req.player.playerId) instead of strict getSession. A DB-backed (Steam-authed) player would transparently get their session rebuilt instead of a 401. This is the minimal, consistent fix.
2. Don't immediately reap non-lobby sessions on disconnect — give them the same grace period lobby members get, so a brief blip doesn't destroy the session.
3. (Client-side, optional) Treat a 401 Session not found as "re-authenticate, then retry" rather than surfacing it as a terminal error.

Notes / unverified

The mechanism above is confirmed against the code end-to-end (in-memory map, stateless JWT, immediate non-lobby reap, strict matchmaking lookup, clientid == playerId). What is not independently confirmed is that a given user report was caused by this exact path versus another session-loss trigger (e.g. a server restart/redeploy wiping the in-memory map, or a grace-period expiry). All of those funnel into the same end state — valid JWT, no session, strict 401 — so the fixes apply regardless.

[ChronoFinale]

Root cause (simplified) + fix in #33

After digging in, the "Session not found" 401 is one symptom of a single underlying issue. Plain version:

A player's session is just an in-memory cache of their players row. 11 of its 13 fields are a direct copy of that row; the only two that aren't (lobbyCode, connectedAt) are runtime values that should be empty/now after a reconnect anyway. Nothing in a session is unrecoverable — it can always be rebuilt from the DB. The JWT is the real proof of identity; the session is just a cache over it.

The bug: a few gates treat "session not in the in-memory map" as a hard failure instead of rebuilding it. Since the session is only a cache, a cache-miss should trigger a rebuild — not a 401.

When it bites

The session lives only in memory, so it disappears on a server restart, or when the EMQX client.disconnected webhook reaps a non-lobby player. The client's JWT is still valid, so it never re-auths → /queue → empty getSession → 401, and retrying never helps. Only a full game restart fixes it (that triggers /auth/refresh, which already rebuilds the session). A normal crash→relaunch does not hit this — the bug is specifically the "client stays alive but the server-side session is gone" case.

It's broader than matchmaking

The same hasActiveSession-or-deny check sits in the EMQX auth webhook (emqx-auth.service.ts), so a stranded player can't even reconnect to MQTT — they're fully stuck, not just unable to queue.

The fix principle

The codebase already self-heals in most places — /auth/refresh, authenticateWithPlayerId, and several auth endpoints rebuild the session from the DB on a miss. The fix is to apply that consistently: gate on the JWT, and rebuild the session from the DB on a cache-miss instead of erroring. It's cheap (warm path is still an in-memory lookup; DB only touched on a miss) and not a security change (the JWT already proves auth; bans are read fresh from the DB).

Suggested changes

1. Matchmaking routes — done in fix(matchmaking): self-heal a missing session instead of 401 #33: ensureSession() instead of strict getSession(). Minimal, tested.
2. EMQX auth webhook (proposed) — rebuild from the DB instead of denying when hasActiveSession is false, so MQTT reconnection self-heals too (preserving the ToS/ban checks).
3. Client (mod) (proposed) — on a 401 / "Session not found", re-auth once (redeems the refresh token, rebuilds the session) and retry, instead of surfacing a dead error.

Item 1 (#33) is the minimal fix for the reported symptom; items 2 and 3 are the deeper root fix and touch a broader boundary, so flagging them here rather than assuming the change.