@couch-kit/runtime 0.0.0

package/lib/rate-limiter.d.ts

@@ -0,0 +1,32 @@
+/** Maximum actions per rate-limit window. */
+export declare const RATE_LIMIT_MAX = 60;
+/** Rate-limit window duration (ms). */
+export declare const RATE_LIMIT_WINDOW = 1000;
+export interface RateLimitInfo {
+    count: number;
+    windowStart: number;
+}
+export interface RateLimitResult extends RateLimitInfo {
+    allowed: boolean;
+}
+export interface ActionRateLimiterOptions {
+    maxActions?: number;
+    windowMs?: number;
+    now?: () => number;
+}
+/**
+ * Per-connection action limiter that preserves the host provider's original
+ * fixed-window algorithm.
+ */
+export declare class ActionRateLimiter {
+    private readonly maxActions;
+    private readonly windowMs;
+    private readonly now;
+    private readonly limits;
+    constructor(options?: ActionRateLimiterOptions);
+    record(socketId: string): RateLimitResult;
+    reset(socketId: string): void;
+    clear(): void;
+    get(socketId: string): RateLimitInfo | undefined;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/lib/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAE/C,OAAO,GAAE,wBAA6B;IAMlD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe;IAiBzC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI7B,KAAK,IAAI,IAAI;IAIb,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;CAGjD"}

package/lib/runtime.d.ts

@@ -0,0 +1,68 @@
+import { type GameReducer, type HostMessage, type IAction, type IGameState } from "@couch-kit/core";
+/** 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 declare class GameHostRuntime<S extends IGameState, A extends IAction> {
+    private config;
+    private readonly reducer;
+    private state;
+    private transport;
+    private readonly listeners;
+    private readonly sessionManager;
+    private readonly rateLimiter;
+    private readonly broadcastScheduler;
+    private readonly assetsLoaded;
+    private readonly activeConnections;
+    private readonly joinedConnections;
+    private readonly pendingJoins;
+    private actionQueue;
+    private stateDirty;
+    private nextConnectionGeneration;
+    constructor(config: GameHostRuntimeConfig<S, A>, transport?: GameRuntimeTransport | null);
+    /** Returns the current canonical state snapshot. */
+    readonly getState: () => S;
+    /** Subscribes to canonical state changes. */
+    readonly subscribe: (listener: () => void) => (() => void);
+    /** Replaces the active message transport without resetting game state. */
+    setTransport(transport: GameRuntimeTransport | null): void;
+    /** Updates mutable callbacks and timing options while preserving state. */
+    updateConfig(config: GameHostRuntimeConfig<S, A>): void;
+    /** Dispatches a trusted action originating from the host display. */
+    readonly dispatch: (action: A) => void;
+    /** Records a newly opened transport connection for optional debug logging. */
+    handleConnection(connectionId: string): void;
+    /** Validates and processes one parsed client protocol message. */
+    handleMessage(connectionId: string, rawMessage: unknown): Promise<void>;
+    /** Processes a transport disconnect and starts session recovery cleanup. */
+    handleDisconnect(connectionId: string): void;
+    /** Surfaces transport failures through the configured host callback. */
+    handleError(error: Error): void;
+    /** Cancels runtime timers and releases transport-specific state. */
+    stop(): void;
+    private applyAction;
+    private readonly broadcastState;
+    private send;
+    private invokeLifecycleCallback;
+    private notifyError;
+    private log;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/lib/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/lib/session-manager.d.ts

@@ -0,0 +1,63 @@
+import { type IGameState, type InternalAction } from "@couch-kit/core";
+export interface SessionTimerScheduler<TTimer> {
+    setTimeout(callback: () => void, delayMs: number): TTimer;
+    clearTimeout(timer: TTimer): void;
+}
+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 declare class HostSessionManager<TTimer = ReturnType<typeof setTimeout>> {
+    private readonly sessions;
+    private readonly reverseMap;
+    private readonly cleanupTimers;
+    private readonly socketIdToPlayerId;
+    private readonly scheduler;
+    private readonly getDisconnectTimeout;
+    private readonly derivePlayerIdFn;
+    private readonly derivePlayerIdLegacyFn;
+    constructor(options?: HostSessionManagerOptions<TTimer>);
+    handleJoin<S extends IGameState>(socketId: string, payload: JoinSessionPayload, playersSource: PlayersSource<S>): Promise<JoinSessionResult<S>>;
+    handleDisconnect<S extends IGameState>(socketId: string): DisconnectSessionResult<S>;
+    scheduleRemoval(playerId: string, secret: string, onRemove: (playerId: string) => void): void;
+    cancelRemoval(playerId: string): void;
+    clearRemovalTimers(): void;
+    getPlayerIdForSocket(socketId: string): string | undefined;
+    abandonConnection(socketId: string): void;
+    getSocketIdForSecret(secret: string): string | undefined;
+    hasPendingRemoval(playerId: string): boolean;
+}
+export {};
+//# sourceMappingURL=session-manager.d.ts.map

package/lib/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@couch-kit/runtime",
+  "version": "0.0.0",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "description": "Transport-neutral authoritative game runtime for Couch Kit hosts",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faluciano/react-native-couch-kit.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/faluciano/react-native-couch-kit#readme",
+  "keywords": [
+    "couch-kit",
+    "party-game",
+    "game-runtime",
+    "websocket",
+    "webrtc"
+  ],
+  "main": "./dist/index.js",
+  "types": "./lib/index.d.ts",
+  "react-native": "./dist/index.js",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "react-native": {
+        "types": "./lib/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "types": "./lib/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "lib",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target browser --external @couch-kit/core && bun build ./src/index.ts --outfile ./dist/index.cjs --target browser --format cjs --external @couch-kit/core && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist lib"
+  },
+  "dependencies": {
+    "@couch-kit/core": "0.9.2"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.0"
+  }
+}

package/src/action-authorization.ts

@@ -0,0 +1,55 @@
+import { InternalActionTypes } from "@couch-kit/core";
+
+/** Error codes surfaced when a client ACTION is rejected before dispatch. */
+export type ActionRejectionCode = "FORBIDDEN_ACTION" | "NOT_JOINED";
+
+/** Outcome of authorizing an inbound client ACTION message. */
+export type ActionAuthorization =
+  | { kind: "allow"; playerId: string }
+  | { kind: "reject"; code: ActionRejectionCode; message: string };
+
+const INTERNAL_ACTION_TYPES = new Set<string>([
+  InternalActionTypes.HYDRATE,
+  InternalActionTypes.PLAYER_JOINED,
+  InternalActionTypes.PLAYER_LEFT,
+  InternalActionTypes.PLAYER_RECONNECTED,
+  InternalActionTypes.PLAYER_REMOVED,
+]);
+
+/**
+ * Decide whether an inbound client ACTION may be dispatched by the runtime.
+ *
+ * Rejects, in order:
+ * - **Internal action types** — clients must not be able to inject framework
+ *   actions (`__HYDRATE__`, `__PLAYER_JOINED__`, etc.) to forge state.
+ * - **Un-joined sockets** — a socket with no resolved player ID never completed
+ *   a JOIN, so its actions have no owner and must not mutate state.
+ *
+ * The decision is pure so it can be unit-tested without a WebSocket or React.
+ *
+ * @param actionType - The `type` field of the client's action payload.
+ * @param resolvedPlayerId - The player ID cached for the socket at JOIN time, or
+ *   `undefined` if the socket has not joined.
+ */
+export function authorizeClientAction(
+  actionType: string,
+  resolvedPlayerId: string | undefined,
+): ActionAuthorization {
+  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 };
+}

package/src/broadcast-scheduler.ts

@@ -0,0 +1,83 @@
+import { MessageTypes, type HostMessage } from "@couch-kit/core";
+
+/** Default state broadcast throttle (~30fps). */
+export const DEFAULT_STATE_THROTTLE_MS = 33;
+
+export type StateUpdateMessage = Extract<
+  HostMessage,
+  { type: typeof MessageTypes.STATE_UPDATE }
+>;
+
+export interface TimerScheduler<TTimer> {
+  setTimeout(callback: () => void, delayMs: number): TTimer;
+  clearTimeout(timer: TTimer): void;
+}
+
+const defaultTimerScheduler: TimerScheduler<ReturnType<typeof setTimeout>> = {
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer),
+};
+
+export interface BroadcastSchedulerOptions<TTimer> {
+  stateThrottleMs?: number;
+  scheduler?: TimerScheduler<TTimer>;
+}
+
+/**
+ * Debounced state-broadcast scheduler used by the authoritative runtime.
+ * Rapid state changes are coalesced into one broadcast after the latest change.
+ */
+export class BroadcastScheduler<TTimer = ReturnType<typeof setTimeout>> {
+  private stateThrottleMs: number;
+  private readonly scheduler: TimerScheduler<TTimer>;
+  private timer: TTimer | null = null;
+
+  constructor(options: BroadcastSchedulerOptions<TTimer> = {}) {
+    this.stateThrottleMs = options.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS;
+    this.scheduler =
+      options.scheduler ??
+      (defaultTimerScheduler as unknown as TimerScheduler<TTimer>);
+  }
+
+  schedule(callback: () => void): void {
+    this.cancel();
+    this.timer = this.scheduler.setTimeout(() => {
+      this.timer = null;
+      callback();
+    }, this.stateThrottleMs);
+  }
+
+  cancel(): void {
+    if (this.timer) {
+      this.scheduler.clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  setStateThrottleMs(stateThrottleMs: number): void {
+    this.stateThrottleMs = stateThrottleMs;
+  }
+
+  hasPendingBroadcast(): boolean {
+    return this.timer !== null;
+  }
+}
+
+export function createStateUpdateMessage(
+  newState: unknown,
+  actions: readonly unknown[],
+  timestamp: number = Date.now(),
+): StateUpdateMessage {
+  return {
+    type: MessageTypes.STATE_UPDATE,
+    payload: {
+      newState,
+      timestamp,
+      ...(actions.length === 1
+        ? { action: actions[0] }
+        : actions.length > 1
+          ? { action: actions }
+          : {}),
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./action-authorization.js";
+export * from "./broadcast-scheduler.js";
+export * from "./message-validation.js";
+export * from "./rate-limiter.js";
+export * from "./runtime.js";
+export * from "./session-manager.js";

package/src/message-validation.ts

@@ -0,0 +1,94 @@
+import { MessageTypes, type ClientMessage } from "@couch-kit/core";
+
+/**
+ * Default maximum size (in bytes) of an inbound client message. Frames larger
+ * than this are discarded before `JSON.parse`, bounding the memory a single
+ * malicious LAN client can force the runtime to allocate. Generous enough for
+ * data-URI avatars in JOIN payloads while blocking multi-megabyte abuse.
+ */
+export const DEFAULT_MAX_MESSAGE_BYTES = 256 * 1024;
+
+/**
+ * Compute the UTF-8 byte length of a raw WebSocket frame payload.
+ *
+ * For binary frames the `ArrayBuffer.byteLength` is exact. For text frames the
+ * UTF-8 size is counted directly from the JS string without allocating an
+ * encoder buffer, so an oversized frame can be rejected cheaply.
+ */
+export function frameByteLength(data: string | ArrayBuffer): number {
+  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 < 0x80) {
+      bytes += 1;
+    } else if (code < 0x800) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      // High surrogate: a full pair encodes to 4 UTF-8 bytes.
+      bytes += 4;
+      i++; // Skip the paired low surrogate.
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+
+type ClientMessageOf<TType extends ClientMessage["type"]> = Extract<
+  ClientMessage,
+  { type: TType }
+>;
+
+export type ValidatedClientMessage =
+  | {
+      type: typeof MessageTypes.JOIN;
+      payload: {
+        name: string;
+        secret?: unknown;
+        avatar?: unknown;
+        [key: string]: unknown;
+      };
+    }
+  | ClientMessageOf<"ACTION">
+  | ClientMessageOf<"PING">
+  | ClientMessageOf<"ASSETS_LOADED">;
+
+/**
+ * Validates that an incoming message has the expected shape.
+ * Returns true if the message has a processable client-message shape.
+ */
+export function isValidClientMessage(
+  msg: unknown,
+): msg is ValidatedClientMessage {
+  if (typeof msg !== "object" || msg === null) return false;
+  const m = msg as Record<string, unknown>;
+  if (typeof m.type !== "string") return false;
+
+  switch (m.type) {
+    case MessageTypes.JOIN:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).name === "string"
+      );
+    case MessageTypes.ACTION:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).type === "string"
+      );
+    case MessageTypes.PING:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).id === "string" &&
+        typeof (m.payload as Record<string, unknown>).timestamp === "number"
+      );
+    case MessageTypes.ASSETS_LOADED:
+      return m.payload === true;
+    default:
+      return false;
+  }
+}

package/src/rate-limiter.ts

@@ -0,0 +1,66 @@
+/** Maximum actions per rate-limit window. */
+export const RATE_LIMIT_MAX = 60;
+
+/** Rate-limit window duration (ms). */
+export const RATE_LIMIT_WINDOW = 1000;
+
+export interface RateLimitInfo {
+  count: number;
+  windowStart: number;
+}
+
+export interface RateLimitResult extends RateLimitInfo {
+  allowed: boolean;
+}
+
+export interface ActionRateLimiterOptions {
+  maxActions?: number;
+  windowMs?: number;
+  now?: () => number;
+}
+
+/**
+ * Per-connection action limiter that preserves the host provider's original
+ * fixed-window algorithm.
+ */
+export class ActionRateLimiter {
+  private readonly maxActions: number;
+  private readonly windowMs: number;
+  private readonly now: () => number;
+  private readonly limits = new Map<string, RateLimitInfo>();
+
+  constructor(options: ActionRateLimiterOptions = {}) {
+    this.maxActions = options.maxActions ?? RATE_LIMIT_MAX;
+    this.windowMs = options.windowMs ?? RATE_LIMIT_WINDOW;
+    this.now = options.now ?? Date.now;
+  }
+
+  record(socketId: string): RateLimitResult {
+    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: string): void {
+    this.limits.delete(socketId);
+  }
+
+  clear(): void {
+    this.limits.clear();
+  }
+
+  get(socketId: string): RateLimitInfo | undefined {
+    return this.limits.get(socketId);
+  }
+}