rollback-netcode 0.0.4

package/dist/session/session.js

@@ -0,0 +1,1294 @@
+/**
+ * High-level session manager that orchestrates the rollback engine and transport.
+ *
+ * Handles room management, player join/leave, message routing, and desync detection.
+ */
+import { DEFAULT_SESSION_CONFIG, ErrorSource, PauseReason, PlayerConnectionState, PlayerRole, SessionState, Topology, asPlayerId, asTick, playerIdToPeerId, validatePlayerId, validateSessionConfig, } from "../types.js";
+import { createDebugLogger } from "../debug.js";
+import { encodeMessage } from "../protocol/encoding.js";
+import { isReliableMessage, } from "../protocol/messages.js";
+import { RollbackEngine, } from "../rollback/engine.js";
+import { RateLimiter } from "../utils/rate-limiter.js";
+import { DesyncManager } from "./desync-manager.js";
+import { DEFAULT_LAG_REPORT_COOLDOWN_TICKS, LagMonitor, } from "./lag-monitor.js";
+import { createDisconnectReport, createDropPlayer, createHash, createInput, createJoinAccept, createJoinReject, createJoinRequest, createLagReport, createPause, createPing, createPlayerJoined, createPlayerLeft, createPong, createResume, createResumeCountdown, createStateSync, createSync, createSyncRequest, } from "./message-builders.js";
+import { MessageRouter } from "./message-router.js";
+import { PlayerManager } from "./player-manager.js";
+import { createTopologyStrategy } from "./topology.js";
+/** Interval for cleaning up stale rate limit entries (in milliseconds) */
+const RATE_LIMIT_CLEANUP_INTERVAL_MS = 60000;
+/**
+ * Generate a cryptographically random room ID.
+ * Uses crypto.randomUUID() for unpredictable room IDs.
+ */
+function generateRoomId() {
+    // Use crypto.randomUUID() for secure random IDs
+    // Falls back to a less secure method if crypto is unavailable
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        // Take first 8 characters of UUID for shorter room codes
+        return crypto.randomUUID().slice(0, 8);
+    }
+    // Fallback for environments without crypto.randomUUID
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let id = "";
+    for (let i = 0; i < 8; i++) {
+        id += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return id;
+}
+/**
+ * Session manager that coordinates the rollback engine with network transport.
+ */
+export class Session {
+    game;
+    transport;
+    config;
+    engine;
+    eventHandlers = new Map();
+    _localPlayerId;
+    topologyStrategy;
+    debug;
+    // Extracted components
+    playerManager;
+    desyncManager;
+    lagMonitor;
+    joinRateLimiter;
+    messageRouter;
+    _state = SessionState.Disconnected;
+    _isHost = false;
+    _roomId = null;
+    _localRole = PlayerRole.Player;
+    lastHashBroadcastTick = asTick(-1);
+    inputRedundancy;
+    /** Timer for periodic rate limit cleanup */
+    rateLimitCleanupTimer = null;
+    /** Buffer for deferred hash comparison (processed after rollback in tick()) */
+    pendingHashMessages = [];
+    /** Tracks players whose playerJoined event has been emitted to prevent duplicates during resimulation */
+    emittedJoinEvents = new Set();
+    /** Number of RTT samples to keep for averaging */
+    static RTT_SAMPLE_COUNT = 5;
+    /** RTT tracking: peerId -> { pendingPings: Map<timestamp, sendTime>, rtt: number } */
+    peerRttData = new Map();
+    /**
+     * Create a new session.
+     * @throws ValidationError if config values are invalid
+     */
+    constructor(options) {
+        this.game = options.game;
+        this.transport = options.transport;
+        this.config = { ...DEFAULT_SESSION_CONFIG, ...options.config };
+        // Validate configuration
+        validateSessionConfig(this.config);
+        this._localPlayerId =
+            options.localPlayerId ?? asPlayerId(this.transport.localPeerId);
+        // Validate local player ID
+        validatePlayerId(this._localPlayerId);
+        // Create topology strategy
+        this.topologyStrategy = createTopologyStrategy(this.config.topology);
+        // Create debug logger
+        this.debug = createDebugLogger(this.config.debug);
+        // Warn about Mesh topology with many players
+        if (this.config.topology === Topology.Mesh && this.config.maxPlayers > 4) {
+            console.warn("[rollback-netcode] Mesh topology with >4 players is not recommended. " +
+                "Mesh requires N×(N-1)/2 connections which scales poorly. " +
+                "Consider using Star topology for better performance.");
+        }
+        // Initialize extracted components
+        this.playerManager = new PlayerManager();
+        this.desyncManager = new DesyncManager({
+            topology: this.config.topology,
+            desyncAuthority: this.config.desyncAuthority,
+            hashInterval: this.config.hashInterval,
+        });
+        this.lagMonitor = new LagMonitor({
+            threshold: this.config.lagReportThreshold,
+            cooldownTicks: DEFAULT_LAG_REPORT_COOLDOWN_TICKS,
+        });
+        this.joinRateLimiter = new RateLimiter({
+            maxRequests: this.config.joinRateLimitRequests,
+            windowMs: this.config.joinRateLimitWindowMs,
+        });
+        this.inputRedundancy = this.config.inputRedundancy;
+        // Create message router with handlers
+        this.messageRouter = new MessageRouter(this.createMessageHandlers(), this.handleDecodeError.bind(this));
+        const engineConfig = {
+            game: this.game,
+            localPlayerId: this._localPlayerId,
+            snapshotHistorySize: this.config.snapshotHistorySize,
+            maxSpeculationTicks: this.config.maxSpeculationTicks,
+            // During resimulation, emit playerJoined when crossing a player's joinTick
+            // so the game layer can re-add players that were lost during snapshot restore.
+            // Skip if we've already emitted for this player (prevents duplicate events).
+            onPlayerAddDuringResimulation: (playerId, _tick) => {
+                if (this.emittedJoinEvents.has(playerId)) {
+                    return; // Already emitted, skip duplicate
+                }
+                const playerInfo = this.playerManager.getPlayer(playerId);
+                if (playerInfo) {
+                    this.emittedJoinEvents.add(playerId);
+                    this.emit("playerJoined", playerInfo);
+                }
+            },
+            // During resimulation, emit playerLeft when crossing a player's leaveTick
+            onPlayerRemoveDuringResimulation: (playerId, _tick) => {
+                const playerInfo = this.playerManager.getPlayer(playerId);
+                if (playerInfo) {
+                    this.emit("playerLeft", playerInfo);
+                }
+            },
+            // When rollback occurs, clear emittedJoinEvents for players whose joinTick
+            // is after the restore tick, since they need to be re-added during resimulation
+            onRollback: (restoreTick) => {
+                for (const playerId of this.emittedJoinEvents) {
+                    const playerInfo = this.playerManager.getPlayer(playerId);
+                    if (playerInfo &&
+                        playerInfo.joinTick !== null &&
+                        playerInfo.joinTick > restoreTick) {
+                        this.emittedJoinEvents.delete(playerId);
+                    }
+                }
+            },
+        };
+        if (options.inputPredictor) {
+            engineConfig.inputPredictor = options.inputPredictor;
+        }
+        this.engine = new RollbackEngine(engineConfig);
+        // Initialize local player info
+        this.playerManager.addPlayer({
+            id: this._localPlayerId,
+            connectionState: PlayerConnectionState.Connected,
+            joinTick: null,
+            leaveTick: null,
+            isHost: false,
+            role: PlayerRole.Player,
+        });
+        // Setup transport callbacks
+        this.transport.onMessage = this.handleMessage.bind(this);
+        this.transport.onConnect = this.handlePeerConnect.bind(this);
+        this.transport.onDisconnect = this.handlePeerDisconnect.bind(this);
+        // Setup keepalive callback if transport supports it
+        const transportWithKeepalive = this.transport;
+        if ("onKeepalivePing" in transportWithKeepalive) {
+            transportWithKeepalive.onKeepalivePing = (peerId) => {
+                this.sendPing(peerId);
+            };
+        }
+        // Start periodic rate limit cleanup (unref to not block process exit)
+        this.rateLimitCleanupTimer = setInterval(() => {
+            this.joinRateLimiter.cleanup();
+        }, RATE_LIMIT_CLEANUP_INTERVAL_MS);
+        if (this.rateLimitCleanupTimer.unref) {
+            this.rateLimitCleanupTimer.unref();
+        }
+    }
+    /**
+     * Create message handlers bound to this session.
+     */
+    createMessageHandlers() {
+        return {
+            onInput: (msg) => this.handleInputMessage(msg),
+            onHash: (msg) => this.handleHashMessage(msg),
+            onSync: (msg) => this.handleSyncMessage(msg),
+            onSyncRequest: (msg) => this.handleSyncRequest(msg),
+            onJoinRequest: (msg, peerId) => this.handleJoinRequest(peerId, msg),
+            onJoinAccept: (msg) => this.handleJoinAccept(msg),
+            onJoinReject: (msg) => this.handleJoinReject(msg),
+            onPlayerJoined: (msg) => this.handlePlayerJoined(msg),
+            onPlayerLeft: (msg) => this.handlePlayerLeft(msg),
+            onPause: (msg) => this.handlePause(msg),
+            onResume: (msg) => this.handleResume(msg),
+            onPing: (msg, peerId) => this.handlePing(peerId, msg),
+            onPong: (msg, peerId) => this.handlePong(peerId, msg),
+            onDisconnectReport: (msg) => this.handleDisconnectReport(msg),
+            onLagReport: (msg) => this.handleLagReport(msg),
+            onResumeCountdown: (msg) => this.handleResumeCountdown(msg),
+            onDropPlayer: (msg) => this.handleDropPlayer(msg),
+        };
+    }
+    /**
+     * Current session state.
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Map of all players in the session.
+     */
+    get players() {
+        return this.playerManager.asReadonlyMap();
+    }
+    /**
+     * Local player's ID.
+     */
+    get localPlayerId() {
+        return this._localPlayerId;
+    }
+    /**
+     * Whether this session is the host.
+     */
+    get isHost() {
+        return this._isHost;
+    }
+    /**
+     * Current room ID (null if not in a room).
+     */
+    get roomId() {
+        return this._roomId;
+    }
+    /**
+     * Local player's role in the session.
+     */
+    get localRole() {
+        return this._localRole;
+    }
+    /**
+     * Set the local player's role.
+     * Must be called before joining a room or starting the game.
+     *
+     * @param role - The role to set ('pilot' or 'spectator')
+     * @throws Error if called while in a room
+     */
+    setLocalRole(role) {
+        if (this._state !== SessionState.Disconnected) {
+            throw new Error("Cannot change role while in a room");
+        }
+        this._localRole = role;
+        const localPlayer = this.playerManager.getPlayer(this.localPlayerId);
+        if (localPlayer) {
+            localPlayer.role = role;
+        }
+    }
+    /**
+     * Current tick from the engine.
+     */
+    get currentTick() {
+        return this.engine.currentTick;
+    }
+    /**
+     * Confirmed tick from the engine.
+     */
+    get confirmedTick() {
+        return this.engine.confirmedTick;
+    }
+    /**
+     * Get connection quality metrics for a player.
+     *
+     * @param playerId - The player's ID
+     * @returns Connection metrics or null if not available
+     */
+    getPlayerMetrics(playerId) {
+        // Local player doesn't have network metrics
+        if (playerId === this.localPlayerId) {
+            return null;
+        }
+        const peerId = playerIdToPeerId(playerId);
+        // Check if transport supports metrics
+        if (this.transport.getConnectionMetrics) {
+            return this.transport.getConnectionMetrics(peerId);
+        }
+        return null;
+    }
+    /**
+     * Destroy the session and clean up resources.
+     * Call this when the session is no longer needed.
+     */
+    destroy() {
+        this.leaveRoom();
+        // Stop rate limit cleanup timer
+        if (this.rateLimitCleanupTimer) {
+            clearInterval(this.rateLimitCleanupTimer);
+            this.rateLimitCleanupTimer = null;
+        }
+        // Clear component state
+        this.joinRateLimiter.clear();
+        this.lagMonitor.clear();
+        this.desyncManager.clear();
+        this.pendingHashMessages = [];
+        // Remove transport callbacks
+        this.transport.onMessage = null;
+        this.transport.onConnect = null;
+        this.transport.onDisconnect = null;
+    }
+    /**
+     * Create a new room and become the host.
+     *
+     * @returns The room ID
+     */
+    async createRoom() {
+        if (this._state !== SessionState.Disconnected) {
+            throw new Error("Already in a room or connecting");
+        }
+        this._roomId = generateRoomId();
+        this._isHost = true;
+        // Update local player to be host
+        const localPlayer = this.playerManager.getPlayer(this.localPlayerId);
+        if (localPlayer) {
+            localPlayer.isHost = true;
+            localPlayer.joinTick = asTick(0);
+        }
+        this.setState(SessionState.Lobby);
+        return this._roomId;
+    }
+    /**
+     * Join an existing room.
+     *
+     * @param roomId - The room ID to join
+     * @param hostPeerId - The host's peer ID
+     */
+    async joinRoom(roomId, hostPeerId) {
+        if (this._state !== SessionState.Disconnected) {
+            throw new Error("Already in a room or connecting");
+        }
+        this._roomId = roomId;
+        this._isHost = false;
+        this.setState(SessionState.Connecting);
+        // Connect to host
+        await this.transport.connect(hostPeerId);
+        // Send join request with role
+        this.sendToHost(createJoinRequest(this.localPlayerId, this._localRole));
+    }
+    /**
+     * Leave the current room.
+     */
+    leaveRoom() {
+        if (this._state === SessionState.Disconnected) {
+            return;
+        }
+        // Notify other players
+        if (this._state === SessionState.Playing) {
+            this.broadcast(createPlayerLeft(this.localPlayerId, this.engine.currentTick), true);
+        }
+        // Disconnect from all peers
+        this.transport.disconnectAll();
+        // Reset state
+        this._roomId = null;
+        this._isHost = false;
+        this.playerManager.clear();
+        this.emittedJoinEvents.clear();
+        this.engine.reset();
+        // Re-add local player
+        this.playerManager.addPlayer({
+            id: this.localPlayerId,
+            connectionState: PlayerConnectionState.Connected,
+            joinTick: null,
+            leaveTick: null,
+            isHost: false,
+            role: PlayerRole.Player,
+        });
+        this.setState(SessionState.Disconnected);
+    }
+    /**
+     * Start the game (host only).
+     * Transitions from lobby to playing state.
+     */
+    start() {
+        if (!this._isHost) {
+            throw new Error("Only the host can start the game");
+        }
+        if (this._state !== SessionState.Lobby) {
+            throw new Error("Can only start from lobby state");
+        }
+        // Set join ticks for all players, but only add players to engine
+        const startTick = asTick(0);
+        for (const player of this.playerManager) {
+            player.joinTick = startTick;
+            // Only players contribute inputs - spectators run simulation but don't send inputs
+            if (player.role === PlayerRole.Player) {
+                this.engine.addPlayer(player.id, startTick);
+            }
+        }
+        // Send state sync to all players
+        const state = this.engine.getState();
+        this.broadcast(createStateSync(state.tick, state.state, this.engine.getCurrentHash(), state.playerTimeline), true);
+        this.setState(SessionState.Playing);
+        this.emit("gameStart");
+    }
+    /**
+     * Pause the game (host only).
+     */
+    pause(reason = PauseReason.PlayerRequest) {
+        if (!this._isHost) {
+            throw new Error("Only the host can pause");
+        }
+        if (this._state !== SessionState.Playing) {
+            return;
+        }
+        this.broadcast(createPause(this.localPlayerId, this.engine.currentTick, reason), true);
+        this.setState(SessionState.Paused);
+    }
+    /**
+     * Resume the game (host only).
+     */
+    resume() {
+        if (!this._isHost) {
+            throw new Error("Only the host can resume");
+        }
+        if (this._state !== SessionState.Paused) {
+            return;
+        }
+        this.broadcast(createResume(this.localPlayerId, this.engine.currentTick), true);
+        this.setState(SessionState.Playing);
+    }
+    /**
+     * Send a resume countdown to all players (host only).
+     * Use this before calling resume() to give players time to prepare.
+     *
+     * @param secondsRemaining - Number of seconds until resume
+     */
+    sendResumeCountdown(secondsRemaining) {
+        if (!this._isHost) {
+            throw new Error("Only the host can send resume countdown");
+        }
+        if (this._state !== SessionState.Paused) {
+            return;
+        }
+        this.broadcast(createResumeCountdown(secondsRemaining), true);
+        // Also emit locally so host's game layer can react
+        this.emit("resumeCountdown", secondsRemaining);
+    }
+    /**
+     * Drop a player from the game (host only).
+     * Use this to remove a disconnected or lagging player and allow the game to continue.
+     *
+     * @param playerId - The player to drop
+     * @param metadata - Optional metadata (e.g., AI replacement info)
+     */
+    dropPlayer(playerId, metadata) {
+        if (!this._isHost) {
+            throw new Error("Only the host can drop players");
+        }
+        const player = this.playerManager.getPlayer(playerId);
+        if (!player) {
+            return;
+        }
+        // Mark player as disconnected locally
+        this.markPlayerDisconnected(playerId);
+        // Broadcast DropPlayer to all other players
+        this.broadcast(createDropPlayer(playerId, metadata), true);
+        // Emit locally
+        this.emit("playerDropped", playerId, metadata);
+    }
+    /**
+     * Advance the simulation by one tick.
+     * Call this at your game's tick rate (e.g., 60 times per second).
+     *
+     * @param localInput - The local player's input for this tick (required for pilots, ignored for spectators)
+     * @returns Tick result with rollback info
+     */
+    tick(localInput) {
+        if (this._state !== SessionState.Playing) {
+            return {
+                tick: this.engine.currentTick,
+                rolledBack: false,
+            };
+        }
+        const currentTick = this.engine.currentTick;
+        // Only players send inputs
+        if (this._localRole === PlayerRole.Player) {
+            if (!localInput) {
+                throw new Error("Players must provide input");
+            }
+            // Set local input
+            this.engine.setLocalInput(currentTick, localInput);
+            // Broadcast local input to all peers
+            this.broadcastInput(currentTick, localInput);
+        }
+        // Run the engine tick (both pilots and spectators run simulation)
+        const result = this.engine.tick();
+        // Handle rollback errors (e.g., "cannot rollback: no snapshots available")
+        // A failed rollback means we couldn't correct a misprediction, which may lead to desync
+        if (result.error) {
+            this.debug.warn("Rollback error", {
+                tick: result.tick,
+                error: result.error.message,
+            });
+            this.emitError(result.error, {
+                source: ErrorSource.Engine,
+                recoverable: true,
+                details: {
+                    tick: result.tick,
+                    rollbackTarget: result.error.tick,
+                },
+            });
+            // Non-hosts should request sync to recover from potential desync
+            if (!this._isHost) {
+                this.requestSync();
+            }
+        }
+        // Log rollback if it occurred
+        if (result.rolledBack && result.rollbackTicks !== undefined) {
+            this.debug.log("Rollback triggered", {
+                tick: result.tick,
+                rollbackTicks: result.rollbackTicks,
+            });
+            // Clear pending hashes for rolled-back ticks
+            // Both our state and the sender's state may have changed
+            const rollbackToTick = asTick(result.tick - result.rollbackTicks);
+            this.pendingHashMessages = this.pendingHashMessages.filter((h) => h.tick < rollbackToTick);
+        }
+        // Process deferred hash comparisons (after rollback has corrected state)
+        this.processPendingHashComparisons();
+        // Periodic hash broadcast for desync detection
+        this.maybeBroadcastHash();
+        // Periodic lag check and report (guests only, in host-authority mode)
+        this.checkAndReportLag();
+        return result;
+    }
+    /**
+     * Request state sync from host (for desync recovery).
+     */
+    requestSync() {
+        if (this._isHost) {
+            return; // Host doesn't need to request sync
+        }
+        this.sendToHost(createSyncRequest(this.localPlayerId, this.engine.currentTick, this.engine.getCurrentHash()));
+    }
+    /**
+     * Register an event handler.
+     */
+    on(event, handler) {
+        if (!this.eventHandlers.has(event)) {
+            this.eventHandlers.set(event, new Set());
+        }
+        this.eventHandlers.get(event)?.add(handler);
+    }
+    /**
+     * Remove an event handler.
+     */
+    off(event, handler) {
+        this.eventHandlers.get(event)?.delete(handler);
+    }
+    /**
+     * Remove all event handlers.
+     *
+     * Optionally specify an event type to only remove handlers for that event.
+     * Call this during cleanup to prevent memory leaks.
+     *
+     * @param event - Optional event type to clear handlers for
+     */
+    removeAllListeners(event) {
+        if (event !== undefined) {
+            this.eventHandlers.delete(event);
+        }
+        else {
+            this.eventHandlers.clear();
+        }
+    }
+    /**
+     * Emit an event to all registered handlers.
+     */
+    emit(event, ...args) {
+        const handlers = this.eventHandlers.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(...args);
+                }
+                catch (handlerError) {
+                    // Avoid infinite recursion: don't emit error events for errors in error handlers
+                    if (event !== "error") {
+                        this.emitError(handlerError instanceof Error
+                            ? handlerError
+                            : new Error(String(handlerError)), {
+                            source: ErrorSource.Session,
+                            recoverable: true,
+                            details: { event },
+                        });
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Emit an error event with context.
+     */
+    emitError(error, context) {
+        this.emit("error", error, context);
+    }
+    /**
+     * Valid state transitions for the session state machine.
+     *
+     * State machine:
+     * ```
+     *   Disconnected ──→ Connecting ──→ Lobby ──→ Playing ⇄ Paused
+     *        ↑               │            │         │         │
+     *        └───────────────┴────────────┴─────────┴─────────┘
+     *                    (any state can go to Disconnected)
+     * ```
+     */
+    static VALID_TRANSITIONS = new Map([
+        [
+            SessionState.Disconnected,
+            new Set([SessionState.Connecting, SessionState.Lobby]),
+        ],
+        [
+            SessionState.Connecting,
+            new Set([
+                SessionState.Lobby,
+                SessionState.Playing,
+                SessionState.Disconnected,
+            ]),
+        ],
+        [
+            SessionState.Lobby,
+            new Set([SessionState.Playing, SessionState.Disconnected]),
+        ],
+        [
+            SessionState.Playing,
+            new Set([SessionState.Paused, SessionState.Disconnected]),
+        ],
+        [
+            SessionState.Paused,
+            new Set([SessionState.Playing, SessionState.Disconnected]),
+        ],
+    ]);
+    /**
+     * Update session state and emit event.
+     * Validates that the transition is allowed by the state machine.
+     * @throws Error if the transition is not valid
+     */
+    setState(newState) {
+        const oldState = this._state;
+        if (oldState === newState)
+            return;
+        // Validate transition - fail fast on invalid transitions
+        const validNextStates = Session.VALID_TRANSITIONS.get(oldState);
+        if (!validNextStates?.has(newState)) {
+            throw new Error(`Invalid state transition: ${SessionState[oldState]} → ${SessionState[newState]}`);
+        }
+        this._state = newState;
+        this.emit("stateChange", newState, oldState);
+    }
+    /**
+     * Handle decode error from message router.
+     */
+    handleDecodeError(error, peerId, dataLength) {
+        this.emitError(error, {
+            source: ErrorSource.Protocol,
+            recoverable: true,
+            details: { peerId, dataLength },
+        });
+    }
+    /**
+     * Handle incoming message from transport.
+     */
+    handleMessage(peerId, data) {
+        // Record peer response for keepalive tracking
+        const transportWithMetrics = this.transport;
+        transportWithMetrics.recordPeerResponse?.(peerId);
+        // Route through message router
+        this.messageRouter.route(peerId, data);
+    }
+    /**
+     * Handle peer connection.
+     */
+    handlePeerConnect(peerId) {
+        this.debug.log("Peer connected", { peerId });
+        // Update player state if known
+        const playerId = asPlayerId(peerId);
+        this.playerManager.markConnected(playerId);
+    }
+    /**
+     * Handle peer disconnection.
+     */
+    handlePeerDisconnect(peerId) {
+        this.debug.log("Peer disconnected", { peerId });
+        // Clean up RTT tracking data
+        this.peerRttData.delete(peerId);
+        const playerId = asPlayerId(peerId);
+        // In host-authority mode, guests report to host instead of handling locally
+        if (this.desyncManager.isHostAuthority && !this._isHost) {
+            this.sendToHost(createDisconnectReport(playerId));
+            return;
+        }
+        // Host or star topology or peer mode: handle directly
+        this.markPlayerDisconnected(playerId);
+    }
+    /**
+     * Mark a player as disconnected and handle cleanup.
+     */
+    markPlayerDisconnected(playerId) {
+        const player = this.playerManager.getPlayer(playerId);
+        if (!player)
+            return;
+        player.connectionState = PlayerConnectionState.Disconnected;
+        if (this._state === SessionState.Playing) {
+            player.leaveTick = this.engine.currentTick;
+            // Only remove players from engine (spectators were never added)
+            if (player.role === PlayerRole.Player) {
+                this.engine.removePlayer(playerId, player.leaveTick);
+            }
+            // Clear join event tracking so if player rejoins later, we emit again
+            this.emittedJoinEvents.delete(playerId);
+            this.emit("playerLeft", player);
+            // If host in host-authority mode, broadcast PlayerLeft to all
+            if (this._isHost && this.desyncManager.isHostAuthority) {
+                this.broadcast(createPlayerLeft(playerId, player.leaveTick), true);
+            }
+        }
+    }
+    /**
+     * Handle disconnect report from a guest (host only, mesh+host-authority mode).
+     */
+    handleDisconnectReport(message) {
+        if (!this._isHost)
+            return;
+        this.debug.log("Received disconnect report", {
+            disconnectedPeerId: message.disconnectedPeerId,
+        });
+        this.markPlayerDisconnected(message.disconnectedPeerId);
+    }
+    /**
+     * Handle lag report from a guest (host only).
+     */
+    handleLagReport(message) {
+        if (!this._isHost)
+            return;
+        // Emit event for game layer to handle (pause decision, kick UI, etc.)
+        this.emit("lagReport", message.laggyPlayerId, message.ticksBehind);
+    }
+    /**
+     * Check for lagging players and report to host (guests only, when lag threshold is set).
+     */
+    checkAndReportLag() {
+        // Only guests report lag in host-authority mode
+        if (this._isHost)
+            return;
+        if (!this.lagMonitor.isEnabled)
+            return;
+        const currentTick = this.engine.currentTick;
+        // Check each remote player's confirmed tick
+        for (const player of this.playerManager) {
+            if (player.id === this.localPlayerId)
+                continue;
+            if (player.role !== PlayerRole.Player)
+                continue;
+            if (player.connectionState !== PlayerConnectionState.Connected)
+                continue;
+            const confirmedTick = this.engine.getConfirmedTickForPlayer(player.id);
+            if (confirmedTick === undefined)
+                continue;
+            const ticksBehind = currentTick - confirmedTick;
+            const lagReport = this.lagMonitor.checkPlayer(player.id, ticksBehind, currentTick);
+            if (lagReport) {
+                this.sendToHost(createLagReport(lagReport.laggyPlayerId, lagReport.ticksBehind));
+                this.debug.log("Sent lag report", {
+                    laggyPlayerId: lagReport.laggyPlayerId,
+                    ticksBehind: lagReport.ticksBehind,
+                });
+            }
+        }
+    }
+    /**
+     * Handle resume countdown message.
+     */
+    handleResumeCountdown(message) {
+        this.emit("resumeCountdown", message.secondsRemaining);
+    }
+    /**
+     * Handle drop player message.
+     */
+    handleDropPlayer(message) {
+        this.markPlayerDisconnected(message.playerId);
+        this.emit("playerDropped", message.playerId, message.metadata);
+    }
+    /**
+     * Handle input message from remote player.
+     */
+    handleInputMessage(message) {
+        for (const { tick, input } of message.inputs) {
+            this.engine.receiveRemoteInput(message.playerId, tick, input);
+        }
+        // Log once per message, not per input (reduces noise)
+        if (message.inputs.length > 0) {
+            this.debug.trace("Inputs received", {
+                playerId: message.playerId,
+                count: message.inputs.length,
+                ticks: message.inputs.map((i) => i.tick),
+            });
+        }
+        // Check if we should relay inputs based on topology
+        if (this.topologyStrategy.shouldRelayInput(message.playerId, this._isHost)) {
+            const targets = this.topologyStrategy.getRelayTargets(message.playerId, this.transport.connectedPeers);
+            if (targets.length > 0) {
+                const encoded = encodeMessage(message);
+                for (const peerId of targets) {
+                    this.transport.send(peerId, encoded, false);
+                }
+            }
+        }
+    }
+    /**
+     * Handle hash message for desync detection.
+     */
+    handleHashMessage(message) {
+        // Host-authority mode: host collects and compares immediately
+        if (this.desyncManager.isHostAuthority) {
+            if (this._isHost) {
+                this.recordHashAndCheckDesync(message.tick, message.playerId, message.hash);
+            }
+            // Guests don't compare hashes in host-authority mode
+            return;
+        }
+        // Peer mode: defer comparison until after rollback in tick()
+        // Store the hash for later comparison
+        this.pendingHashMessages.push({
+            tick: message.tick,
+            playerId: message.playerId,
+            hash: message.hash,
+        });
+    }
+    /**
+     * Process pending hash comparisons after rollback has corrected state.
+     * Called from tick() after engine.tick() completes.
+     */
+    processPendingHashComparisons() {
+        if (this.pendingHashMessages.length === 0) {
+            return;
+        }
+        const currentTick = this.engine.currentTick;
+        const confirmedTick = this.engine.confirmedTick;
+        const remaining = [];
+        // Prune threshold: discard hashes older than 2x hashInterval
+        // These are too old to be useful and prevent memory growth
+        const pruneThreshold = asTick(Math.max(0, currentTick - this.config.hashInterval * 2));
+        for (const pending of this.pendingHashMessages) {
+            // Prune old hashes that are no longer relevant
+            if (pending.tick < pruneThreshold) {
+                continue;
+            }
+            // Only compare if the hash tick is confirmed (all inputs received)
+            // This ensures we won't roll back and change our hash for this tick
+            if (pending.tick > confirmedTick) {
+                // Not confirmed yet, keep for later
+                remaining.push(pending);
+                continue;
+            }
+            // Compare hashes (our state should now be correct after rollback)
+            const localHash = this.engine.getHash(pending.tick);
+            const desyncResult = this.desyncManager.checkPeerDesync(pending.tick, localHash, pending.hash, pending.playerId);
+            if (desyncResult) {
+                this.debug.warn("Desync detected", {
+                    tick: pending.tick,
+                    localHash: desyncResult.localHash,
+                    remoteHash: desyncResult.remoteHash,
+                    remotePlayer: pending.playerId,
+                });
+                this.emit("desync", pending.tick, desyncResult.localHash, desyncResult.remoteHash);
+                // Request sync if we're not the host
+                if (!this._isHost) {
+                    this.requestSync();
+                }
+            }
+        }
+        this.pendingHashMessages = remaining;
+    }
+    /**
+     * Handle sync message (state synchronization).
+     */
+    handleSyncMessage(message) {
+        this.engine.setState(message.tick, message.state, message.playerTimeline);
+        // Clear pending hash comparisons since our state has been reset
+        this.pendingHashMessages = [];
+        // Update player list from timeline
+        for (const entry of message.playerTimeline) {
+            // Determine connection state from leaveTick
+            const connectionState = entry.leaveTick !== null
+                ? PlayerConnectionState.Disconnected
+                : PlayerConnectionState.Connected;
+            if (!this.playerManager.hasPlayer(entry.playerId)) {
+                // Add new player
+                this.playerManager.addPlayer({
+                    id: entry.playerId,
+                    connectionState,
+                    joinTick: entry.joinTick,
+                    leaveTick: entry.leaveTick,
+                    isHost: false,
+                    role: PlayerRole.Player, // Default to player; role info may come from elsewhere
+                });
+            }
+            else {
+                // Update existing player's state from authoritative timeline
+                // This handles the case where JoinAccept added the player before StateSync
+                const existingPlayer = this.playerManager.getPlayer(entry.playerId);
+                if (existingPlayer) {
+                    existingPlayer.connectionState = connectionState;
+                    existingPlayer.joinTick = entry.joinTick;
+                    existingPlayer.leaveTick = entry.leaveTick;
+                }
+            }
+        }
+        if (this._state === SessionState.Connecting ||
+            this._state === SessionState.Lobby) {
+            this.setState(SessionState.Playing);
+            this.emit("gameStart");
+        }
+    }
+    /**
+     * Handle sync request (host only).
+     *
+     * IMPORTANT: When a sync is requested, we broadcast the authoritative state
+     * to ALL players, not just the requester. This ensures all players are
+     * synchronized to the same tick, preventing tick divergence issues that
+     * can occur with latency:
+     *
+     * Without broadcast-to-all:
+     * 1. Player-2 desyncs, requests sync from host at tick X
+     * 2. With latency, host responds with state at tick X+3
+     * 3. Player-2 resets to tick X+3, but player-1/3 are at tick X+6
+     * 4. Player-1/3's input redundancy doesn't cover tick X+3
+     * 5. Player-2 can't advance confirmedTick -> max speculation -> deadlock
+     *
+     * With broadcast-to-all:
+     * - All players reset to the same tick simultaneously
+     * - No tick divergence, no deadlock
+     */
+    handleSyncRequest(message) {
+        if (!this._isHost)
+            return;
+        const state = this.engine.getState();
+        const syncMsg = createSync(state.tick, state.state, this.engine.getCurrentHash(), state.playerTimeline);
+        // Broadcast sync to ALL players to prevent tick divergence
+        // The requesting player needs the state, but other players also need
+        // to synchronize to avoid getting stuck at max speculation
+        this.broadcast(syncMsg, true);
+        // Reset host's buffers and tick counters to match the synced state
+        // (game state is already correct, so use resetForSync instead of setState
+        // to avoid unnecessary serialize/deserialize round-trip)
+        this.engine.resetForSync(state.tick, state.playerTimeline);
+        this.pendingHashMessages = [];
+    }
+    /**
+     * Handle join request (host only).
+     */
+    handleJoinRequest(peerId, message) {
+        if (!this._isHost || !this._roomId)
+            return;
+        const playerId = message.playerId;
+        // Check rate limiting
+        if (this.joinRateLimiter.checkAndRecord(peerId)) {
+            this.sendToPeer(peerId, createJoinReject(playerId, "Too many join requests, please wait"), true);
+            return;
+        }
+        // Check if room is full (only count connected players, not disconnected ones)
+        if (this.playerManager.getConnectedPlayers().length >= this.config.maxPlayers) {
+            this.sendToPeer(peerId, createJoinReject(playerId, "Room is full"), true);
+            return;
+        }
+        // Accept the join
+        this.sendToPeer(peerId, createJoinAccept(playerId, this._roomId, { tickRate: this.config.tickRate, maxPlayers: this.config.maxPlayers }, this.playerManager.getPlayerIds()), true);
+        // Add player
+        const playerRole = message.role ?? PlayerRole.Player;
+        const playerInfo = {
+            id: playerId,
+            connectionState: PlayerConnectionState.Connected,
+            joinTick: this._state === SessionState.Playing ? this.engine.currentTick : null,
+            leaveTick: null,
+            isHost: false,
+            role: playerRole,
+        };
+        this.playerManager.addPlayer(playerInfo);
+        // Only add players to the engine (spectators don't contribute inputs)
+        if (this._state === SessionState.Playing &&
+            playerInfo.joinTick !== null &&
+            playerRole === PlayerRole.Player) {
+            this.engine.addPlayer(playerId, playerInfo.joinTick);
+        }
+        // Emit playerJoined BEFORE sending StateSync so the game layer can
+        // add the new player to its state before serialization.
+        // Track that we've emitted to prevent duplicate events during resimulation.
+        this.emittedJoinEvents.add(playerId);
+        this.emit("playerJoined", playerInfo);
+        // Send current game state to the joining player if game is in progress
+        // This is critical for mid-game joins - the new player needs the full state
+        if (this._state === SessionState.Playing) {
+            const state = this.engine.getState();
+            this.sendToPeer(peerId, createStateSync(state.tick, state.state, this.engine.getCurrentHash(), state.playerTimeline), true);
+        }
+        // Notify other players about the new join
+        if (this._state === SessionState.Playing && playerInfo.joinTick !== null) {
+            this.broadcast(createPlayerJoined(playerId, playerRole, playerInfo.joinTick), true);
+        }
+    }
+    /**
+     * Handle join accept.
+     */
+    handleJoinAccept(message) {
+        // Only transition to Lobby if we're still in Connecting state.
+        // If we're already in Playing (from receiving StateSync first due to message reordering),
+        // we should not go backwards to Lobby.
+        if (this._state === SessionState.Connecting) {
+            this.setState(SessionState.Lobby);
+        }
+        // Add existing players
+        for (const playerId of message.players) {
+            if (!this.playerManager.hasPlayer(playerId)) {
+                this.playerManager.addPlayer({
+                    id: playerId,
+                    connectionState: PlayerConnectionState.Connected,
+                    joinTick: null,
+                    leaveTick: null,
+                    isHost: playerId === message.players[0], // First player is host
+                    role: PlayerRole.Player, // Default; actual role will come from PlayerJoined
+                });
+            }
+        }
+    }
+    /**
+     * Handle join reject.
+     */
+    handleJoinReject(message) {
+        this.setState(SessionState.Disconnected);
+        this.emitError(new Error(`Join rejected: ${message.reason}`), {
+            source: ErrorSource.Session,
+            recoverable: false,
+            details: { reason: message.reason, playerId: message.playerId },
+        });
+    }
+    /**
+     * Handle player joined notification.
+     */
+    handlePlayerJoined(message) {
+        const playerInfo = {
+            id: message.playerId,
+            connectionState: PlayerConnectionState.Connected,
+            joinTick: message.joinTick,
+            leaveTick: null,
+            isHost: false,
+            role: message.role,
+        };
+        this.playerManager.addPlayer(playerInfo);
+        // Only add players to the engine (spectators don't contribute inputs)
+        if (message.role === PlayerRole.Player) {
+            this.engine.addPlayer(message.playerId, message.joinTick);
+        }
+        // Track that we've emitted to prevent duplicate events during resimulation
+        this.emittedJoinEvents.add(message.playerId);
+        this.emit("playerJoined", playerInfo);
+    }
+    /**
+     * Handle player left notification.
+     */
+    handlePlayerLeft(message) {
+        const player = this.playerManager.getPlayer(message.playerId);
+        if (player) {
+            player.leaveTick = message.leaveTick;
+            player.connectionState = PlayerConnectionState.Disconnected;
+            this.engine.removePlayer(message.playerId, message.leaveTick);
+            // Clear join event tracking so if player rejoins later, we emit again
+            this.emittedJoinEvents.delete(message.playerId);
+            this.emit("playerLeft", player);
+            // In Star topology, host must relay PlayerLeft to other peers
+            // (similar to how PlayerJoined is broadcast)
+            if (this._isHost && this.config.topology === Topology.Star) {
+                this.broadcast(createPlayerLeft(message.playerId, message.leaveTick), true);
+            }
+        }
+    }
+    /**
+     * Handle pause message.
+     */
+    handlePause(_message) {
+        this.setState(SessionState.Paused);
+    }
+    /**
+     * Handle resume message.
+     */
+    handleResume(_message) {
+        this.setState(SessionState.Playing);
+    }
+    /**
+     * Handle ping message - respond with pong.
+     */
+    handlePing(peerId, message) {
+        // Respond with pong containing the original timestamp
+        this.transport.send(peerId, encodeMessage(createPong(message.timestamp)), false);
+    }
+    /**
+     * Handle pong message - calculate RTT.
+     */
+    handlePong(peerId, message) {
+        const data = this.peerRttData.get(peerId);
+        if (!data)
+            return;
+        const sentAt = data.pendingPings.get(message.timestamp);
+        if (sentAt === undefined)
+            return;
+        // Calculate RTT
+        const rtt = Date.now() - sentAt;
+        data.pendingPings.delete(message.timestamp);
+        // Update running average
+        data.samples.push(rtt);
+        if (data.samples.length > Session.RTT_SAMPLE_COUNT) {
+            data.samples.shift();
+        }
+        data.rtt = data.samples.reduce((a, b) => a + b, 0) / data.samples.length;
+    }
+    /**
+     * Send a ping to a peer for RTT measurement.
+     *
+     * @param peerId - The peer to ping
+     */
+    sendPing(peerId) {
+        const timestamp = Date.now();
+        this.transport.send(peerId, encodeMessage(createPing(timestamp)), false);
+        // Track the ping locally for RTT calculation
+        let data = this.peerRttData.get(peerId);
+        if (!data) {
+            data = { pendingPings: new Map(), rtt: 0, samples: [] };
+            this.peerRttData.set(peerId, data);
+        }
+        data.pendingPings.set(timestamp, timestamp);
+    }
+    /**
+     * Get the measured RTT to a peer in milliseconds.
+     * Returns 0 if no RTT data is available yet.
+     *
+     * @param peerId - The peer to get RTT for
+     */
+    getRtt(peerId) {
+        return this.peerRttData.get(peerId)?.rtt ?? 0;
+    }
+    /**
+     * Broadcast input to all peers with redundancy.
+     */
+    broadcastInput(tick, input) {
+        const inputs = [];
+        // Add current tick
+        inputs.push({ tick, input });
+        // Add previous ticks for redundancy
+        for (let i = 1; i < this.inputRedundancy; i++) {
+            const prevTick = asTick(tick - i);
+            if (prevTick >= 0) {
+                const prevInput = this.engine.getLocalInput(prevTick);
+                if (prevInput) {
+                    inputs.push({ tick: prevTick, input: prevInput });
+                }
+            }
+        }
+        this.broadcast(createInput(this.localPlayerId, inputs), false);
+    }
+    /**
+     * Maybe broadcast hash for desync detection.
+     *
+     * IMPORTANT: We only broadcast hashes for CONFIRMED ticks, not just completed ticks.
+     * A completed tick may have used predicted inputs that turn out to be wrong.
+     * Broadcasting a hash based on predictions would cause false desync detections
+     * when compared against a peer who has the actual inputs.
+     *
+     * We find the most recent hash-interval tick that is confirmed and broadcast that.
+     */
+    maybeBroadcastHash() {
+        const confirmedTick = this.engine.confirmedTick;
+        // Find the most recent hash-interval tick that is confirmed
+        // For example, if confirmedTick is 37 and hashInterval is 30, we want tick 30
+        const hashTick = asTick(Math.floor(confirmedTick / this.config.hashInterval) *
+            this.config.hashInterval);
+        // Only broadcast if:
+        // - hashTick is positive (we have something to hash)
+        // - We haven't already broadcast this tick
+        if (hashTick > 0 && hashTick !== this.lastHashBroadcastTick) {
+            this.lastHashBroadcastTick = hashTick;
+            // Get the hash from the snapshot at hashTick
+            const hash = this.engine.getHash(hashTick);
+            if (hash === undefined) {
+                // Snapshot not available (pruned) - skip this hash
+                return;
+            }
+            const hashMsg = createHash(this.localPlayerId, hashTick, hash);
+            // Host-authority in mesh: guests send to host only, host collects
+            if (this.desyncManager.isHostAuthority) {
+                if (this._isHost) {
+                    // Host records own hash and checks for desync
+                    this.recordHashAndCheckDesync(hashTick, this.localPlayerId, hash);
+                }
+                else {
+                    // Guest sends hash to host only
+                    this.sendToHost(hashMsg);
+                }
+            }
+            else {
+                // Peer mode or star topology: broadcast to all
+                this.broadcast(hashMsg, true);
+            }
+        }
+    }
+    /**
+     * Record a hash from a player and check for desync (host-authority mode).
+     */
+    recordHashAndCheckDesync(tick, playerId, hash) {
+        if (!this._isHost)
+            return;
+        // Record the hash
+        this.desyncManager.recordHash(tick, playerId, hash);
+        // Check if we have hashes from all active players
+        const activePlayers = this.playerManager.getActivePlayers();
+        if (!this.desyncManager.hasAllHashes(tick, activePlayers.length)) {
+            return; // Still waiting for more hashes
+        }
+        // Check for desyncs
+        const desyncs = this.desyncManager.checkDesyncs(tick, this.localPlayerId);
+        if (desyncs.length > 0) {
+            // Log all detected desyncs
+            for (const desync of desyncs) {
+                this.debug.warn("Desync detected by host", {
+                    tick: desync.tick,
+                    playerId: desync.desyncedPlayerId,
+                    hostHash: desync.referenceHash,
+                    playerHash: desync.playerHash,
+                });
+                this.emit("desync", desync.tick, desync.referenceHash, desync.playerHash);
+            }
+            // Broadcast authoritative state to ALL players to prevent tick divergence
+            // (see handleSyncRequest for detailed explanation of why this is necessary)
+            const state = this.engine.getState();
+            const syncMsg = createSync(state.tick, state.state, this.engine.getCurrentHash(), state.playerTimeline);
+            this.broadcast(syncMsg, true);
+            // Reset host's buffers and tick counters to match the synced state
+            // (use resetForSync instead of setState to avoid unnecessary deserialize)
+            this.engine.resetForSync(state.tick, state.playerTimeline);
+            this.pendingHashMessages = [];
+        }
+        // Cleanup old tick entries
+        this.desyncManager.pruneOldHashes(tick);
+    }
+    /**
+     * Send a message to all connected peers.
+     */
+    broadcast(message, reliable) {
+        const encoded = encodeMessage(message);
+        this.transport.broadcast(encoded, reliable);
+    }
+    /**
+     * Send a message to a specific peer.
+     */
+    sendToPeer(peerId, message, reliable) {
+        const encoded = encodeMessage(message);
+        this.transport.send(peerId, encoded, reliable);
+    }
+    /**
+     * Send a message to the host.
+     */
+    sendToHost(message) {
+        // Find the host player
+        const host = this.playerManager.findHost();
+        if (host && host.id !== this.localPlayerId) {
+            this.sendToPeer(host.id, message, isReliableMessage(message));
+            return;
+        }
+        // If we can't find the host by player info, send to first connected peer
+        const peers = this.transport.connectedPeers;
+        if (peers.size > 0) {
+            const hostPeerId = peers.values().next().value;
+            this.sendToPeer(hostPeerId, message, isReliableMessage(message));
+        }
+    }
+}
+/**
+ * Convenience function to create a session.
+ */
+export function createSession(options) {
+    return new Session(options);
+}
+//# sourceMappingURL=session.js.map