@couch-kit/runtime 0.0.0

package/README.md

@@ -0,0 +1,11 @@
+# @couch-kit/runtime
+
+Transport-neutral authoritative game runtime for Couch Kit hosts.
+
+The runtime owns canonical game state, player sessions, action authorization,
+rate limiting, and throttled state broadcasts. Platform packages provide the
+connection transport, such as the React Native WebSocket host or a future
+browser WebRTC host.
+
+Most applications should use `@couch-kit/host` rather than constructing the
+runtime directly.

package/dist/index.cjs

@@ -0,0 +1,601 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  isValidClientMessage: () => isValidClientMessage,
+  frameByteLength: () => frameByteLength,
+  createStateUpdateMessage: () => createStateUpdateMessage,
+  authorizeClientAction: () => authorizeClientAction,
+  RATE_LIMIT_WINDOW: () => RATE_LIMIT_WINDOW,
+  RATE_LIMIT_MAX: () => RATE_LIMIT_MAX,
+  HostSessionManager: () => HostSessionManager,
+  GameHostRuntime: () => GameHostRuntime,
+  DEFAULT_STATE_THROTTLE_MS: () => DEFAULT_STATE_THROTTLE_MS,
+  DEFAULT_MAX_MESSAGE_BYTES: () => DEFAULT_MAX_MESSAGE_BYTES,
+  BroadcastScheduler: () => BroadcastScheduler,
+  ActionRateLimiter: () => ActionRateLimiter
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/action-authorization.ts
+var import_core = require("@couch-kit/core");
+var INTERNAL_ACTION_TYPES = new Set([
+  import_core.InternalActionTypes.HYDRATE,
+  import_core.InternalActionTypes.PLAYER_JOINED,
+  import_core.InternalActionTypes.PLAYER_LEFT,
+  import_core.InternalActionTypes.PLAYER_RECONNECTED,
+  import_core.InternalActionTypes.PLAYER_REMOVED
+]);
+function authorizeClientAction(actionType, resolvedPlayerId) {
+  if (INTERNAL_ACTION_TYPES.has(actionType)) {
+    return {
+      kind: "reject",
+      code: "FORBIDDEN_ACTION",
+      message: "Internal action types cannot be dispatched by clients"
+    };
+  }
+  if (!resolvedPlayerId) {
+    return {
+      kind: "reject",
+      code: "NOT_JOINED",
+      message: "You must JOIN before dispatching actions"
+    };
+  }
+  return { kind: "allow", playerId: resolvedPlayerId };
+}
+// src/broadcast-scheduler.ts
+var import_core2 = require("@couch-kit/core");
+var DEFAULT_STATE_THROTTLE_MS = 33;
+var defaultTimerScheduler = {
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer)
+};
+
+class BroadcastScheduler {
+  stateThrottleMs;
+  scheduler;
+  timer = null;
+  constructor(options = {}) {
+    this.stateThrottleMs = options.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS;
+    this.scheduler = options.scheduler ?? defaultTimerScheduler;
+  }
+  schedule(callback) {
+    this.cancel();
+    this.timer = this.scheduler.setTimeout(() => {
+      this.timer = null;
+      callback();
+    }, this.stateThrottleMs);
+  }
+  cancel() {
+    if (this.timer) {
+      this.scheduler.clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  setStateThrottleMs(stateThrottleMs) {
+    this.stateThrottleMs = stateThrottleMs;
+  }
+  hasPendingBroadcast() {
+    return this.timer !== null;
+  }
+}
+function createStateUpdateMessage(newState, actions, timestamp = Date.now()) {
+  return {
+    type: import_core2.MessageTypes.STATE_UPDATE,
+    payload: {
+      newState,
+      timestamp,
+      ...actions.length === 1 ? { action: actions[0] } : actions.length > 1 ? { action: actions } : {}
+    }
+  };
+}
+// src/message-validation.ts
+var import_core3 = require("@couch-kit/core");
+var DEFAULT_MAX_MESSAGE_BYTES = 256 * 1024;
+function frameByteLength(data) {
+  if (typeof data !== "string")
+    return data.byteLength;
+  let bytes = 0;
+  for (let i = 0;i < data.length; i++) {
+    const code = data.charCodeAt(i);
+    if (code < 128) {
+      bytes += 1;
+    } else if (code < 2048) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      bytes += 4;
+      i++;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+function isValidClientMessage(msg) {
+  if (typeof msg !== "object" || msg === null)
+    return false;
+  const m = msg;
+  if (typeof m.type !== "string")
+    return false;
+  switch (m.type) {
+    case import_core3.MessageTypes.JOIN:
+      return typeof m.payload === "object" && m.payload !== null && typeof m.payload.name === "string";
+    case import_core3.MessageTypes.ACTION:
+      return typeof m.payload === "object" && m.payload !== null && typeof m.payload.type === "string";
+    case import_core3.MessageTypes.PING:
+      return typeof m.payload === "object" && m.payload !== null && typeof m.payload.id === "string" && typeof m.payload.timestamp === "number";
+    case import_core3.MessageTypes.ASSETS_LOADED:
+      return m.payload === true;
+    default:
+      return false;
+  }
+}
+// src/rate-limiter.ts
+var RATE_LIMIT_MAX = 60;
+var RATE_LIMIT_WINDOW = 1000;
+
+class ActionRateLimiter {
+  maxActions;
+  windowMs;
+  now;
+  limits = new Map;
+  constructor(options = {}) {
+    this.maxActions = options.maxActions ?? RATE_LIMIT_MAX;
+    this.windowMs = options.windowMs ?? RATE_LIMIT_WINDOW;
+    this.now = options.now ?? Date.now;
+  }
+  record(socketId) {
+    const now = this.now();
+    let rateInfo = this.limits.get(socketId);
+    if (!rateInfo || now - rateInfo.windowStart > this.windowMs) {
+      rateInfo = { count: 0, windowStart: now };
+      this.limits.set(socketId, rateInfo);
+    }
+    rateInfo.count++;
+    return {
+      ...rateInfo,
+      allowed: rateInfo.count <= this.maxActions
+    };
+  }
+  reset(socketId) {
+    this.limits.delete(socketId);
+  }
+  clear() {
+    this.limits.clear();
+  }
+  get(socketId) {
+    return this.limits.get(socketId);
+  }
+}
+// src/runtime.ts
+var import_core5 = require("@couch-kit/core");
+
+// src/session-manager.ts
+var import_core4 = require("@couch-kit/core");
+var defaultSessionTimerScheduler = {
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer)
+};
+
+class HostSessionManager {
+  sessions = new Map;
+  reverseMap = new Map;
+  cleanupTimers = new Map;
+  socketIdToPlayerId = new Map;
+  scheduler;
+  getDisconnectTimeout;
+  derivePlayerIdFn;
+  derivePlayerIdLegacyFn;
+  constructor(options = {}) {
+    this.scheduler = options.scheduler ?? defaultSessionTimerScheduler;
+    this.getDisconnectTimeout = options.getDisconnectTimeout ?? (() => options.disconnectTimeout ?? import_core4.DEFAULT_DISCONNECT_TIMEOUT);
+    this.derivePlayerIdFn = options.derivePlayerId ?? import_core4.derivePlayerId;
+    this.derivePlayerIdLegacyFn = options.derivePlayerIdLegacy ?? import_core4.derivePlayerIdLegacy;
+  }
+  async handleJoin(socketId, payload, playersSource) {
+    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: import_core4.InternalActionTypes.PLAYER_RECONNECTED,
+      payload: { playerId }
+    } : {
+      type: import_core4.InternalActionTypes.PLAYER_JOINED,
+      payload: { id: playerId, name: payload.name, avatar: payload.avatar }
+    };
+    return {
+      playerId,
+      socketId,
+      secret: payload.secret,
+      isReconnect,
+      action
+    };
+  }
+  handleDisconnect(socketId) {
+    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: import_core4.InternalActionTypes.PLAYER_LEFT,
+        payload: { playerId }
+      }
+    };
+  }
+  scheduleRemoval(playerId, secret, onRemove) {
+    const timer = this.scheduler.setTimeout(() => {
+      this.cleanupTimers.delete(playerId);
+      this.sessions.delete(secret);
+      onRemove(playerId);
+    }, this.getDisconnectTimeout());
+    this.cleanupTimers.set(playerId, timer);
+  }
+  cancelRemoval(playerId) {
+    const existingTimer = this.cleanupTimers.get(playerId);
+    if (existingTimer) {
+      this.scheduler.clearTimeout(existingTimer);
+      this.cleanupTimers.delete(playerId);
+    }
+  }
+  clearRemovalTimers() {
+    for (const timer of this.cleanupTimers.values()) {
+      this.scheduler.clearTimeout(timer);
+    }
+    this.cleanupTimers.clear();
+  }
+  getPlayerIdForSocket(socketId) {
+    const secret = this.reverseMap.get(socketId);
+    if (!secret || this.sessions.get(secret) !== socketId) {
+      return;
+    }
+    return this.socketIdToPlayerId.get(socketId);
+  }
+  abandonConnection(socketId) {
+    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) {
+    return this.sessions.get(secret);
+  }
+  hasPendingRemoval(playerId) {
+    return this.cleanupTimers.has(playerId);
+  }
+}
+
+// src/runtime.ts
+class GameHostRuntime {
+  config;
+  reducer;
+  state;
+  transport;
+  listeners = new Set;
+  sessionManager;
+  rateLimiter = new ActionRateLimiter;
+  broadcastScheduler;
+  assetsLoaded = new Map;
+  activeConnections = new Map;
+  joinedConnections = new Set;
+  pendingJoins = new Set;
+  actionQueue = [];
+  stateDirty = false;
+  nextConnectionGeneration = 1;
+  constructor(config, transport = null) {
+    this.config = config;
+    this.state = config.initialState;
+    this.reducer = import_core5.createGameReducer(config.reducer);
+    this.transport = transport;
+    this.sessionManager = new HostSessionManager({
+      getDisconnectTimeout: () => this.config.disconnectTimeout ?? import_core5.DEFAULT_DISCONNECT_TIMEOUT
+    });
+    this.broadcastScheduler = new BroadcastScheduler({
+      stateThrottleMs: config.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS
+    });
+  }
+  getState = () => this.state;
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+  setTransport(transport) {
+    this.transport = transport;
+    if (transport && this.stateDirty) {
+      this.broadcastScheduler.schedule(this.broadcastState);
+    }
+  }
+  updateConfig(config) {
+    this.config = config;
+    this.broadcastScheduler.setStateThrottleMs(config.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS);
+  }
+  dispatch = (action) => {
+    this.applyAction(action);
+  };
+  handleConnection(connectionId) {
+    this.activeConnections.set(connectionId, this.nextConnectionGeneration++);
+    this.log(`[GameRuntime] Client connected: ${connectionId}`);
+  }
+  async handleMessage(connectionId, rawMessage) {
+    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: import_core5.MessageTypes.ERROR,
+        payload: {
+          code: "INVALID_MESSAGE",
+          message: "Malformed message"
+        }
+      });
+      return;
+    }
+    const message = rawMessage;
+    this.log(`[GameRuntime] Msg from ${connectionId}:`, message);
+    switch (message.type) {
+      case import_core5.MessageTypes.JOIN: {
+        const { secret, ...payload } = message.payload;
+        if (!secret || typeof secret !== "string" || !import_core5.isValidSecret(secret)) {
+          this.send(connectionId, {
+            type: import_core5.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: import_core5.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(connectionId, message.payload, () => 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: import_core5.MessageTypes.RECONNECTED,
+              payload: {
+                playerId,
+                state: this.state
+              }
+            });
+          } else {
+            this.send(connectionId, {
+              type: import_core5.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: import_core5.MessageTypes.ERROR,
+            payload: {
+              code: "JOIN_FAILED",
+              message: "Failed to process join request"
+            }
+          });
+        } finally {
+          this.pendingJoins.delete(connectionId);
+        }
+        break;
+      }
+      case import_core5.MessageTypes.ACTION: {
+        const actionPayload = message.payload;
+        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: import_core5.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: import_core5.MessageTypes.ERROR,
+            payload: {
+              code: "RATE_LIMITED",
+              message: "Too many actions, slow down"
+            }
+          });
+          return;
+        }
+        this.applyAction({
+          ...actionPayload,
+          playerId: authorization.playerId
+        });
+        this.actionQueue.push(actionPayload);
+        break;
+      }
+      case import_core5.MessageTypes.PING:
+        this.send(connectionId, {
+          type: import_core5.MessageTypes.PONG,
+          payload: {
+            id: message.payload.id,
+            origTimestamp: message.payload.timestamp,
+            serverTime: Date.now()
+          }
+        });
+        break;
+      case import_core5.MessageTypes.ASSETS_LOADED: {
+        const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
+        if (playerId) {
+          this.assetsLoaded.set(playerId, true);
+          this.log(`[GameRuntime] Assets loaded for ${playerId}`);
+        }
+        break;
+      }
+    }
+  }
+  handleDisconnect(connectionId) {
+    this.log(`[GameRuntime] Client disconnected: ${connectionId}`);
+    this.activeConnections.delete(connectionId);
+    this.joinedConnections.delete(connectionId);
+    this.rateLimiter.reset(connectionId);
+    const result = this.sessionManager.handleDisconnect(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: import_core5.InternalActionTypes.PLAYER_REMOVED,
+        payload: { playerId }
+      });
+    });
+  }
+  handleError(error) {
+    this.log("[GameRuntime] Transport error:", error);
+    this.notifyError(error);
+  }
+  stop() {
+    this.broadcastScheduler.cancel();
+    this.sessionManager.clearRemovalTimers();
+    this.rateLimiter.clear();
+    this.activeConnections.clear();
+    this.joinedConnections.clear();
+    this.pendingJoins.clear();
+    this.transport = null;
+  }
+  applyAction(action) {
+    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);
+  }
+  broadcastState = () => {
+    if (!this.transport)
+      return;
+    const actions = this.actionQueue;
+    this.actionQueue = [];
+    this.stateDirty = false;
+    this.transport.broadcast(createStateUpdateMessage(this.state, actions));
+  };
+  send(connectionId, message) {
+    this.transport?.send(connectionId, message);
+  }
+  invokeLifecycleCallback(name, callback) {
+    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 }));
+    }
+  }
+  notifyError(error) {
+    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);
+    }
+  }
+  log(...args) {
+    if (this.config.debug) {
+      console.log(...args);
+    }
+  }
+}