@couch-kit/runtime 0.0.0

package/src/runtime.ts

@@ -0,0 +1,425 @@
+import {
+  DEFAULT_DISCONNECT_TIMEOUT,
+  InternalActionTypes,
+  MessageTypes,
+  createGameReducer,
+  isValidSecret,
+  type GameReducer,
+  type HostMessage,
+  type IAction,
+  type IGameState,
+  type InternalAction,
+} from "@couch-kit/core";
+import { authorizeClientAction } from "./action-authorization.js";
+import {
+  BroadcastScheduler,
+  DEFAULT_STATE_THROTTLE_MS,
+  createStateUpdateMessage,
+} from "./broadcast-scheduler.js";
+import { isValidClientMessage } from "./message-validation.js";
+import { ActionRateLimiter } from "./rate-limiter.js";
+import {
+  HostSessionManager,
+  type JoinSessionPayload,
+} from "./session-manager.js";
+
+/** Minimal message-delivery surface required by the authoritative runtime. */
+export interface GameRuntimeTransport {
+  send(connectionId: string, message: HostMessage): void;
+  broadcast(message: HostMessage): void;
+}
+
+/** Configuration shared by every authoritative Couch Kit host transport. */
+export interface GameHostRuntimeConfig<
+  S extends IGameState,
+  A extends IAction,
+> {
+  initialState: S;
+  reducer: GameReducer<S, A>;
+  debug?: boolean;
+  /** Timeout before a disconnected player is permanently removed. */
+  disconnectTimeout?: number;
+  /** Minimum interval between full-state broadcasts. */
+  stateThrottleMs?: number;
+  onPlayerJoined?: (playerId: string, name: string) => void;
+  onPlayerLeft?: (playerId: string) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Owns the canonical game state and protocol lifecycle independently of React
+ * Native, WebSockets, or any future WebRTC transport.
+ */
+export class GameHostRuntime<S extends IGameState, A extends IAction> {
+  private config: GameHostRuntimeConfig<S, A>;
+  private readonly reducer: GameReducer<S, A | InternalAction<S>>;
+  private state: S;
+  private transport: GameRuntimeTransport | null;
+  private readonly listeners = new Set<() => void>();
+  private readonly sessionManager: HostSessionManager;
+  private readonly rateLimiter = new ActionRateLimiter();
+  private readonly broadcastScheduler: BroadcastScheduler;
+  private readonly assetsLoaded = new Map<string, boolean>();
+  private readonly activeConnections = new Map<string, number>();
+  private readonly joinedConnections = new Set<string>();
+  private readonly pendingJoins = new Set<string>();
+  private actionQueue: unknown[] = [];
+  private stateDirty = false;
+  private nextConnectionGeneration = 1;
+
+  constructor(
+    config: GameHostRuntimeConfig<S, A>,
+    transport: GameRuntimeTransport | null = null,
+  ) {
+    this.config = config;
+    this.state = config.initialState;
+    this.reducer = createGameReducer(config.reducer);
+    this.transport = transport;
+    this.sessionManager = new HostSessionManager({
+      getDisconnectTimeout: () =>
+        this.config.disconnectTimeout ?? DEFAULT_DISCONNECT_TIMEOUT,
+    });
+    this.broadcastScheduler = new BroadcastScheduler({
+      stateThrottleMs: config.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS,
+    });
+  }
+
+  /** Returns the current canonical state snapshot. */
+  readonly getState = (): S => this.state;
+
+  /** Subscribes to canonical state changes. */
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /** Replaces the active message transport without resetting game state. */
+  setTransport(transport: GameRuntimeTransport | null): void {
+    this.transport = transport;
+    if (transport && this.stateDirty) {
+      this.broadcastScheduler.schedule(this.broadcastState);
+    }
+  }
+
+  /** Updates mutable callbacks and timing options while preserving state. */
+  updateConfig(config: GameHostRuntimeConfig<S, A>): void {
+    this.config = config;
+    this.broadcastScheduler.setStateThrottleMs(
+      config.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS,
+    );
+  }
+
+  /** Dispatches a trusted action originating from the host display. */
+  readonly dispatch = (action: A): void => {
+    this.applyAction(action);
+  };
+
+  /** Records a newly opened transport connection for optional debug logging. */
+  handleConnection(connectionId: string): void {
+    this.activeConnections.set(connectionId, this.nextConnectionGeneration++);
+    this.log(`[GameRuntime] Client connected: ${connectionId}`);
+  }
+
+  /** Validates and processes one parsed client protocol message. */
+  async handleMessage(
+    connectionId: string,
+    rawMessage: unknown,
+  ): Promise<void> {
+    const connectionGeneration = this.activeConnections.get(connectionId);
+    if (connectionGeneration === undefined) {
+      this.log(
+        `[GameRuntime] Ignoring message from inactive connection: ${connectionId}`,
+      );
+      return;
+    }
+
+    if (!isValidClientMessage(rawMessage)) {
+      this.log(
+        `[GameRuntime] Invalid message from ${connectionId}:`,
+        rawMessage,
+      );
+      this.send(connectionId, {
+        type: MessageTypes.ERROR,
+        payload: {
+          code: "INVALID_MESSAGE",
+          message: "Malformed message",
+        },
+      });
+      return;
+    }
+
+    const message = rawMessage;
+    this.log(`[GameRuntime] Msg from ${connectionId}:`, message);
+
+    switch (message.type) {
+      case MessageTypes.JOIN: {
+        const { secret, ...payload } = message.payload;
+
+        if (!secret || typeof secret !== "string" || !isValidSecret(secret)) {
+          this.send(connectionId, {
+            type: MessageTypes.ERROR,
+            payload: {
+              code: "INVALID_SECRET",
+              message: "Invalid or missing session secret",
+            },
+          });
+          return;
+        }
+
+        if (
+          this.joinedConnections.has(connectionId) ||
+          this.pendingJoins.has(connectionId)
+        ) {
+          this.send(connectionId, {
+            type: MessageTypes.ERROR,
+            payload: {
+              code: "ALREADY_JOINED",
+              message: "This connection has already joined the game",
+            },
+          });
+          return;
+        }
+
+        this.pendingJoins.add(connectionId);
+        try {
+          const { playerId, isReconnect, action } =
+            await this.sessionManager.handleJoin<S>(
+              connectionId,
+              message.payload as JoinSessionPayload,
+              () => this.state.players,
+            );
+
+          if (
+            this.activeConnections.get(connectionId) !== connectionGeneration
+          ) {
+            this.sessionManager.abandonConnection(connectionId);
+            return;
+          }
+
+          this.applyAction(action);
+          this.joinedConnections.add(connectionId);
+          this.assetsLoaded.set(playerId, false);
+          this.invokeLifecycleCallback(
+            "onPlayerJoined",
+            this.config.onPlayerJoined
+              ? () => {
+                  this.config.onPlayerJoined?.(playerId, payload.name);
+                }
+              : undefined,
+          );
+
+          if (isReconnect) {
+            this.send(connectionId, {
+              type: MessageTypes.RECONNECTED,
+              payload: {
+                playerId,
+                state: this.state,
+              },
+            });
+          } else {
+            this.send(connectionId, {
+              type: MessageTypes.WELCOME,
+              payload: {
+                playerId,
+                state: this.state,
+                serverTime: Date.now(),
+              },
+            });
+          }
+        } catch (error) {
+          this.log("[GameRuntime] Failed to derive player ID:", error);
+          this.send(connectionId, {
+            type: MessageTypes.ERROR,
+            payload: {
+              code: "JOIN_FAILED",
+              message: "Failed to process join request",
+            },
+          });
+        } finally {
+          this.pendingJoins.delete(connectionId);
+        }
+        break;
+      }
+
+      case MessageTypes.ACTION: {
+        const actionPayload = message.payload as A;
+        const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
+        const authorization = authorizeClientAction(
+          actionPayload.type,
+          playerId,
+        );
+
+        if (authorization.kind === "reject") {
+          this.log(
+            `[GameRuntime] Rejected action from ${connectionId} ` +
+              `(${authorization.code}):`,
+            actionPayload.type,
+          );
+          this.send(connectionId, {
+            type: MessageTypes.ERROR,
+            payload: {
+              code: authorization.code,
+              message: authorization.message,
+            },
+          });
+          return;
+        }
+
+        if (!this.rateLimiter.record(connectionId).allowed) {
+          this.log(`[GameRuntime] Rate limited ${connectionId}`);
+          this.send(connectionId, {
+            type: MessageTypes.ERROR,
+            payload: {
+              code: "RATE_LIMITED",
+              message: "Too many actions, slow down",
+            },
+          });
+          return;
+        }
+
+        this.applyAction({
+          ...actionPayload,
+          playerId: authorization.playerId,
+        } as A);
+        this.actionQueue.push(actionPayload);
+        break;
+      }
+
+      case MessageTypes.PING:
+        this.send(connectionId, {
+          type: MessageTypes.PONG,
+          payload: {
+            id: message.payload.id,
+            origTimestamp: message.payload.timestamp,
+            serverTime: Date.now(),
+          },
+        });
+        break;
+
+      case MessageTypes.ASSETS_LOADED: {
+        const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
+        if (playerId) {
+          this.assetsLoaded.set(playerId, true);
+          this.log(`[GameRuntime] Assets loaded for ${playerId}`);
+        }
+        break;
+      }
+    }
+  }
+
+  /** Processes a transport disconnect and starts session recovery cleanup. */
+  handleDisconnect(connectionId: string): void {
+    this.log(`[GameRuntime] Client disconnected: ${connectionId}`);
+    this.activeConnections.delete(connectionId);
+    this.joinedConnections.delete(connectionId);
+    this.rateLimiter.reset(connectionId);
+
+    const result = this.sessionManager.handleDisconnect<S>(connectionId);
+    if (result.kind === "unknown") return;
+
+    this.assetsLoaded.delete(result.playerId);
+    if (result.kind === "stale") return;
+
+    this.applyAction(result.action);
+    this.invokeLifecycleCallback(
+      "onPlayerLeft",
+      this.config.onPlayerLeft
+        ? () => {
+            this.config.onPlayerLeft?.(result.playerId);
+          }
+        : undefined,
+    );
+    this.sessionManager.scheduleRemoval(
+      result.playerId,
+      result.secret,
+      (playerId) => {
+        this.applyAction({
+          type: InternalActionTypes.PLAYER_REMOVED,
+          payload: { playerId },
+        } as InternalAction<S>);
+      },
+    );
+  }
+
+  /** Surfaces transport failures through the configured host callback. */
+  handleError(error: Error): void {
+    this.log("[GameRuntime] Transport error:", error);
+    this.notifyError(error);
+  }
+
+  /** Cancels runtime timers and releases transport-specific state. */
+  stop(): void {
+    this.broadcastScheduler.cancel();
+    this.sessionManager.clearRemovalTimers();
+    this.rateLimiter.clear();
+    this.activeConnections.clear();
+    this.joinedConnections.clear();
+    this.pendingJoins.clear();
+    this.transport = null;
+  }
+
+  private applyAction(action: A | InternalAction<S>): void {
+    const nextState = this.reducer(this.state, action);
+    if (Object.is(nextState, this.state)) return;
+
+    this.state = nextState;
+    this.stateDirty = true;
+
+    for (const listener of this.listeners) {
+      listener();
+    }
+
+    this.broadcastScheduler.schedule(this.broadcastState);
+  }
+
+  private readonly broadcastState = (): void => {
+    if (!this.transport) return;
+
+    const actions = this.actionQueue;
+    this.actionQueue = [];
+    this.stateDirty = false;
+    this.transport.broadcast(createStateUpdateMessage(this.state, actions));
+  };
+
+  private send(connectionId: string, message: HostMessage): void {
+    this.transport?.send(connectionId, message);
+  }
+
+  private invokeLifecycleCallback(
+    name: string,
+    callback: (() => void) | undefined,
+  ): void {
+    if (!callback) return;
+
+    try {
+      callback();
+    } catch (error) {
+      const cause = error instanceof Error ? error : new Error(String(error));
+      this.notifyError(
+        new Error(`${name} callback failed: ${cause.message}`, { cause }),
+      );
+    }
+  }
+
+  private notifyError(error: Error): void {
+    const onError = this.config.onError;
+    if (!onError) {
+      console.error("[GameRuntime] Unhandled error:", error);
+      return;
+    }
+
+    try {
+      onError(error);
+    } catch (callbackError) {
+      console.error("[GameRuntime] onError callback failed:", callbackError);
+    }
+  }
+
+  private log(...args: unknown[]): void {
+    if (this.config.debug) {
+      console.log(...args);
+    }
+  }
+}

package/src/session-manager.ts

@@ -0,0 +1,202 @@
+import {
+  DEFAULT_DISCONNECT_TIMEOUT,
+  InternalActionTypes,
+  derivePlayerId,
+  derivePlayerIdLegacy,
+  type IGameState,
+  type InternalAction,
+} from "@couch-kit/core";
+
+export interface SessionTimerScheduler<TTimer> {
+  setTimeout(callback: () => void, delayMs: number): TTimer;
+  clearTimeout(timer: TTimer): void;
+}
+
+const defaultSessionTimerScheduler: SessionTimerScheduler<
+  ReturnType<typeof setTimeout>
+> = {
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer),
+};
+
+export interface JoinSessionPayload {
+  name: string;
+  avatar?: string;
+  secret: string;
+}
+
+export interface HostSessionManagerOptions<TTimer> {
+  disconnectTimeout?: number;
+  getDisconnectTimeout?: () => number;
+  scheduler?: SessionTimerScheduler<TTimer>;
+  derivePlayerId?: (secret: string) => Promise<string>;
+  derivePlayerIdLegacy?: (secret: string) => string;
+}
+
+export type JoinSessionResult<S extends IGameState> = {
+  playerId: string;
+  socketId: string;
+  secret: string;
+  isReconnect: boolean;
+  action: InternalAction<S>;
+};
+
+export type DisconnectSessionResult<S extends IGameState> =
+  | { kind: "unknown" }
+  | { kind: "stale"; playerId: string; secret: string }
+  | {
+      kind: "left";
+      playerId: string;
+      secret: string;
+      action: InternalAction<S>;
+    };
+
+type PlayersSource<S extends IGameState> = S["players"] | (() => S["players"]);
+
+/**
+ * Tracks transport-neutral player sessions by secret and connection ID,
+ * including reconnects and delayed cleanup of disconnected players.
+ */
+export class HostSessionManager<TTimer = ReturnType<typeof setTimeout>> {
+  private readonly sessions = new Map<string, string>();
+  private readonly reverseMap = new Map<string, string>();
+  private readonly cleanupTimers = new Map<string, TTimer>();
+  private readonly socketIdToPlayerId = new Map<string, string>();
+  private readonly scheduler: SessionTimerScheduler<TTimer>;
+  private readonly getDisconnectTimeout: () => number;
+  private readonly derivePlayerIdFn: (secret: string) => Promise<string>;
+  private readonly derivePlayerIdLegacyFn: (secret: string) => string;
+
+  constructor(options: HostSessionManagerOptions<TTimer> = {}) {
+    this.scheduler =
+      options.scheduler ??
+      (defaultSessionTimerScheduler as unknown as SessionTimerScheduler<TTimer>);
+    this.getDisconnectTimeout =
+      options.getDisconnectTimeout ??
+      (() => options.disconnectTimeout ?? DEFAULT_DISCONNECT_TIMEOUT);
+    this.derivePlayerIdFn = options.derivePlayerId ?? derivePlayerId;
+    this.derivePlayerIdLegacyFn =
+      options.derivePlayerIdLegacy ?? derivePlayerIdLegacy;
+  }
+
+  async handleJoin<S extends IGameState>(
+    socketId: string,
+    payload: JoinSessionPayload,
+    playersSource: PlayersSource<S>,
+  ): Promise<JoinSessionResult<S>> {
+    const hashedId = await this.derivePlayerIdFn(payload.secret);
+    const players =
+      typeof playersSource === "function" ? playersSource() : playersSource;
+    let playerId = hashedId;
+
+    const legacyId = this.derivePlayerIdLegacyFn(payload.secret);
+    if (!players[playerId] && players[legacyId]) {
+      playerId = legacyId;
+    }
+
+    this.socketIdToPlayerId.set(socketId, playerId);
+    this.sessions.set(payload.secret, socketId);
+    this.reverseMap.set(socketId, payload.secret);
+    this.cancelRemoval(playerId);
+
+    const isReconnect = !!players[playerId];
+    const action = isReconnect
+      ? ({
+          type: InternalActionTypes.PLAYER_RECONNECTED,
+          payload: { playerId },
+        } as InternalAction<S>)
+      : ({
+          type: InternalActionTypes.PLAYER_JOINED,
+          payload: { id: playerId, name: payload.name, avatar: payload.avatar },
+        } as InternalAction<S>);
+
+    return {
+      playerId,
+      socketId,
+      secret: payload.secret,
+      isReconnect,
+      action,
+    };
+  }
+
+  handleDisconnect<S extends IGameState>(
+    socketId: string,
+  ): DisconnectSessionResult<S> {
+    const playerId = this.socketIdToPlayerId.get(socketId);
+    this.socketIdToPlayerId.delete(socketId);
+
+    const secret = this.reverseMap.get(socketId);
+    this.reverseMap.delete(socketId);
+
+    if (!playerId || !secret) return { kind: "unknown" };
+
+    if (this.sessions.get(secret) !== socketId) {
+      return { kind: "stale", playerId, secret };
+    }
+
+    return {
+      kind: "left",
+      playerId,
+      secret,
+      action: {
+        type: InternalActionTypes.PLAYER_LEFT,
+        payload: { playerId },
+      } as InternalAction<S>,
+    };
+  }
+
+  scheduleRemoval(
+    playerId: string,
+    secret: string,
+    onRemove: (playerId: string) => void,
+  ): void {
+    const timer = this.scheduler.setTimeout(() => {
+      this.cleanupTimers.delete(playerId);
+      this.sessions.delete(secret);
+      onRemove(playerId);
+    }, this.getDisconnectTimeout());
+
+    this.cleanupTimers.set(playerId, timer);
+  }
+
+  cancelRemoval(playerId: string): void {
+    const existingTimer = this.cleanupTimers.get(playerId);
+    if (existingTimer) {
+      this.scheduler.clearTimeout(existingTimer);
+      this.cleanupTimers.delete(playerId);
+    }
+  }
+
+  clearRemovalTimers(): void {
+    for (const timer of this.cleanupTimers.values()) {
+      this.scheduler.clearTimeout(timer);
+    }
+    this.cleanupTimers.clear();
+  }
+
+  getPlayerIdForSocket(socketId: string): string | undefined {
+    const secret = this.reverseMap.get(socketId);
+    if (!secret || this.sessions.get(secret) !== socketId) {
+      return undefined;
+    }
+    return this.socketIdToPlayerId.get(socketId);
+  }
+
+  abandonConnection(socketId: string): void {
+    const secret = this.reverseMap.get(socketId);
+    this.socketIdToPlayerId.delete(socketId);
+    this.reverseMap.delete(socketId);
+
+    if (secret && this.sessions.get(secret) === socketId) {
+      this.sessions.delete(secret);
+    }
+  }
+
+  getSocketIdForSecret(secret: string): string | undefined {
+    return this.sessions.get(secret);
+  }
+
+  hasPendingRemoval(playerId: string): boolean {
+    return this.cleanupTimers.has(playerId);
+  }
+}