@colyseus/core 0.17.42 → 0.18.0

package/src/Transport.ts

@@ -5,6 +5,7 @@ import type { Router } from '@colyseus/better-call';
 
 import { ErrorCode } from '@colyseus/shared-types';
 import { StateView } from '@colyseus/schema';
+import type { InputDecoder } from '@colyseus/schema/input';
 
 import { EventEmitter } from 'events';
 import { spliceOne } from './utils/Utils.ts';
@@ -90,15 +91,10 @@ export interface Client<T extends { userData?: any, auth?: any, messages?: Recor
 
   ref: EventEmitter;
 
-  /**
-   * @deprecated use `sessionId` instead.
-   */
-  id: string;
-
   /**
    * Unique id per session.
    */
-  sessionId: string; // TODO: remove sessionId on version 1.0.0
+  sessionId: string;
 
   /**
    * Connection state
@@ -198,15 +194,87 @@ export interface ClientPrivate {
    */
   _numMessagesLastSecond?: number;
   _lastMessageTime?: number;
+
+  /**
+   * Per-client input Schema instance, allocated on join when the Room
+   * declares `input`. Mutated in-place by {@link _inputDecoder} on each
+   * incoming ROOM_INPUT_* packet.
+   *
+   * Typed loosely (`any`) so duplicate `@colyseus/schema` installs don't
+   * trigger type-identity errors against user-defined input classes.
+   */
+  _input?: any;
+  _inputDecoder?: InputDecoder;
+
+  /**
+   * Per-client buffer of cloned input snapshots, allocated on join when
+   * `Room.inputOptions.bufferMaxSize > 0`. Populated on each decoded frame.
+   */
+  _inputBuffer?: import('./input/InputBuffer.ts').InputBufferImpl;
+
+  /**
+   * Cached per-client accessor returned by `room.input(sessionId)`. Built
+   * once at join (when the Room called `defineInput()`), so the public API
+   * call is a Map lookup + property read with no per-call allocation.
+   */
+  _inputAccessor?: import('./input/InputBuffer.ts').InputAccessor;
+
+  /**
+   * Used for rate limiting ROOM_INPUT_* packets via maxInputsPerSecond,
+   * independent of maxMessagesPerSecond.
+   */
+  _numInputsLastSecond?: number;
+  _lastInputTime?: number;
 }
 
 export class ClientArray<C extends Client = Client> extends Array<C> {
+  /**
+   * Secondary index for O(1) lookup by sessionId. Kept in sync by the
+   * mutating methods overridden below. Direct index assignment
+   * (`arr[i] = client`) and `arr.length = 0` bypass this index — use
+   * `push` / `splice` / `delete` / `pop` / `shift` / `unshift` instead.
+   */
+  private _byId: Map<string, C> = new Map();
+
   public getById(sessionId: string): C | undefined {
-    return this.find((client) => client.sessionId === sessionId);
+    return this._byId.get(sessionId);
   }
 
   public delete(client: C): boolean {
-    return spliceOne(this, this.indexOf(client));
+    const removed = spliceOne(this, this.indexOf(client));
+    if (removed) this._byId.delete(client.sessionId);
+    return removed;
+  }
+
+  public push(...items: C[]): number {
+    for (let i = 0; i < items.length; i++) this._byId.set(items[i].sessionId, items[i]);
+    return super.push(...items);
+  }
+
+  public pop(): C | undefined {
+    const removed = super.pop();
+    if (removed !== undefined) this._byId.delete(removed.sessionId);
+    return removed;
+  }
+
+  public shift(): C | undefined {
+    const removed = super.shift();
+    if (removed !== undefined) this._byId.delete(removed.sessionId);
+    return removed;
+  }
+
+  public unshift(...items: C[]): number {
+    for (let i = 0; i < items.length; i++) this._byId.set(items[i].sessionId, items[i]);
+    return super.unshift(...items);
+  }
+
+  public splice(start: number, deleteCount?: number, ...items: C[]): C[] {
+    const removed = (deleteCount === undefined)
+      ? super.splice(start)
+      : super.splice(start, deleteCount, ...items);
+    for (let i = 0; i < removed.length; i++) this._byId.delete(removed[i].sessionId);
+    for (let i = 0; i < items.length; i++) this._byId.set(items[i].sessionId, items[i]);
+    return removed;
   }
 }
 

package/src/index.ts

@@ -13,6 +13,10 @@ export {
 // Core classes
 export { Server, defineRoom, defineServer, registerRoomDefinitions, unregisterRoomDefinitions, type RoomDefinitions, type ServerOptions, type SDKTypes } from './Server.ts';
 export { Room, room, RoomInternalState, validate, type RoomOptions, type MessageHandlerWithFormat, type Messages, type ExtractRoomState, type ExtractRoomMetadata, type ExtractRoomClient } from './Room.ts';
+export {
+  RoomPlugin, definePlugins, attachToTestRoom,
+  type RoomPluginOrder, type PluginDependencies, type RoomPluginClass,
+} from './RoomPlugin.ts';
 export { getMessageBytes } from './Protocol.ts';
 export { RegisteredHandler } from './matchmaker/RegisteredHandler.ts';
 export { ServerError } from './errors/ServerError.ts';
@@ -82,8 +86,10 @@ export {
   createInternalContext,
   createMiddleware,
   createRouter,
+  basicAuth,
+  type BasicAuthOptions,
   toNodeHandler,
-  __globalEndpoints,
+  dualModeEndpoints,
   type Router,
   type RouterConfig,
   type Endpoint,
@@ -91,6 +97,9 @@ export {
   type EndpointOptions,
   type EndpointContext,
   type StrictEndpoint,
+  type ExpressMiddleware,
+  type NodeHandler,
+  type DualModeHelpers,
 } from './router/index.ts';
 
 // Abstract logging support

package/src/input/InputBuffer.ts

@@ -0,0 +1,192 @@
+import type { ClientPrivate } from '../Transport.ts';
+
+/**
+ * Names of fields on `I` whose values are `number` — used by
+ * `Room.defineInput()` to constrain `seqField` to actually-numeric fields
+ * on the input schema. Filters out booleans, strings, methods, etc.
+ */
+export type NumericFieldsOf<I> = {
+  [K in keyof I]: I[K] extends number ? (K extends string ? K : never) : never;
+}[keyof I];
+
+/**
+ * Internal: input configuration captured by `Room.defineInput()`. The schema
+ * constructor is stored here so the runtime doesn't need to know it through
+ * the public `room.input` (which is now a callable accessor).
+ *
+ * @internal
+ */
+export interface InputOptions {
+  /**
+   * Schema constructor used to allocate per-client input instances on join.
+   * Captured by `defineInput()` from its `type` argument.
+   *
+   * Typed loosely (`new () => any`) to sidestep type-identity issues across
+   * duplicate `@colyseus/schema` installs; the runtime calls
+   * `instance.clone()` and friends, which match by shape.
+   */
+  ctor: new () => any;
+
+  /**
+   * Name of a monotonically-increasing numeric field on the input schema used
+   * to order and dedupe incoming frames. When set, the framework:
+   * - Drops redundant frames (`input[seqField]` ≤ the last-seen value are
+   *   discarded before they enter the buffer). Matches the unreliable-mode
+   *   ring-redundancy pattern out of the box.
+   * - Powers `room.input(sessionId).at(value)` lookups.
+   *
+   * Despite the name, "seq" here is broader than an integer counter — any
+   * monotonic numeric field works:
+   * - **Sequence counter** (`"seq"`, `"tick"`, `"frame"`) — typical for
+   *   lockstep / rollback netcode (Photon Quantum, GGPO).
+   * - **Timestamp** (`"timestamp"`, milliseconds or seconds) — useful for
+   *   variable-rate clients, lag compensation, hit registration (Unreal CMC
+   *   uses float-seconds timestamps via `FSavedMove_Character.TimeStamp`).
+   *
+   * Whichever you use, the field must increase monotonically across frames
+   * for dedupe to work.
+   */
+  seqField?: string;
+
+  /**
+   * > 0 enables per-client buffering of cloned snapshots — required for
+   * `room.input(sessionId).drain() / .peek() / .at()` to return populated
+   * data. Oldest drops on overflow. Set to `0` to disable (`.latest` still
+   * works).
+   */
+  bufferMaxSize: number;
+}
+
+/**
+ * Per-client input accessor returned by `room.input(sessionId)`. Combines the
+ * latest decoded instance with the (optional) snapshot ring buffer.
+ *
+ * - {@link latest} — the bound Schema instance, mutated in place by the
+ *   decoder. Cheapest read; use when only the most recent state matters.
+ * - {@link drain} / {@link peek} / {@link at} — populated when
+ *   `defineInput()` was called with `bufferMaxSize > 0` (default 32).
+ *   Use for rollback netcode / lockstep where every frame matters.
+ *
+ * Returned for unknown sessionIds and rooms without `defineInput()` is a
+ * frozen no-op accessor (latest=undefined, drain/peek=[], at=undefined,
+ * size=0, clear=no-op).
+ */
+export interface InputAccessor<I = any> {
+  /** Latest decoded input. `undefined` when unknown sessionId or no input declared. */
+  readonly latest: I | undefined;
+
+  /**
+   * Find the buffered snapshot whose `[seqField]` equals `value`. The field
+   * name is the Room's `defineInput()` `seqField`. Linear scan — cheap for
+   * typical buffer sizes; not intended for very large rings. Returns
+   * `undefined` when no match is buffered (or `seqField` isn't configured).
+   *
+   * Useful for tick-aligned retrieval (lockstep, rollback).
+   */
+  at(value: number): I | undefined;
+
+  /** Take everything buffered (oldest → newest) and clear. Snapshots are safe to retain. */
+  drain(): I[];
+
+  /** Read everything buffered without consuming. */
+  peek(): I[];
+
+  /** Number of snapshots currently buffered. */
+  readonly size: number;
+
+  /** Drop all buffered snapshots (also resets the dedupe tracker). */
+  clear(): void;
+}
+
+/**
+ * Callable returned by `Room.defineInput()`. Assign it to `this.input` and
+ * call `room.input(sessionId)` per tick to read each client's latest input
+ * and/or buffered snapshots.
+ */
+export type InputAPI<I = any> = (sessionId: string) => InputAccessor<I>;
+
+/** @internal */
+export class InputBufferImpl<I = any> {
+  private _items: I[] = [];
+  private _lastSeq: number = -Infinity;
+  private readonly _maxSize: number;
+  private readonly _seqField: string | undefined;
+
+  constructor(maxSize: number, seqField: string | undefined) {
+    this._maxSize = maxSize;
+    this._seqField = seqField;
+  }
+
+  push(snapshot: I): void {
+    this._items.push(snapshot);
+    if (this._items.length > this._maxSize) { this._items.shift(); }
+  }
+
+  /** Returns true if `value` hasn't been seen, and updates the last-seen marker. */
+  accept(value: number): boolean {
+    if (value <= this._lastSeq) { return false; }
+    this._lastSeq = value;
+    return true;
+  }
+
+  drain(): I[] {
+    const out = this._items;
+    this._items = [];
+    return out;
+  }
+
+  peek(): I[] {
+    return this._items.slice();
+  }
+
+  at(value: number): I | undefined {
+    if (this._seqField === undefined) { return undefined; }
+    for (let i = 0; i < this._items.length; i++) {
+      if ((this._items[i] as any)[this._seqField] === value) { return this._items[i]; }
+    }
+    return undefined;
+  }
+
+  get size(): number {
+    return this._items.length;
+  }
+
+  clear(): void {
+    this._items.length = 0;
+    this._lastSeq = -Infinity;
+  }
+}
+
+/**
+ * Default per-client accessor. Reads `_input` and `_inputBuffer` off the
+ * client at access time — both are nullable until the room declares input
+ * via `defineInput()`. Cached as `client._inputAccessor` at join, so
+ * `room.input(sessionId)` is a Map lookup + property read.
+ *
+ * @internal
+ */
+export class InputAccessorImpl<I = any> implements InputAccessor<I> {
+  private _client: ClientPrivate;
+  constructor(client: ClientPrivate) { this._client = client; }
+  get latest(): I | undefined { return this._client._input as I | undefined; }
+  at(value: number): I | undefined { return this._client._inputBuffer?.at(value) as I | undefined; }
+  drain(): I[] { return (this._client._inputBuffer?.drain() ?? []) as I[]; }
+  peek(): I[] { return (this._client._inputBuffer?.peek() ?? []) as I[]; }
+  get size(): number { return this._client._inputBuffer?.size ?? 0; }
+  clear(): void { this._client._inputBuffer?.clear(); }
+}
+
+/**
+ * Returned by `room.input(sessionId)` for unknown sessions and for rooms
+ * that didn't call `defineInput()`.
+ *
+ * @internal
+ */
+export const NO_OP_INPUT_ACCESSOR: InputAccessor<any> = Object.freeze({
+  latest: undefined,
+  at: () => undefined,
+  drain: () => [],
+  peek: () => [],
+  size: 0,
+  clear: () => {},
+});

package/src/internal.ts

@@ -0,0 +1,46 @@
+/**
+ * Framework-internal entry — symbols used by the bundled `colyseus`
+ * plugins (track-user-sessions, unique-session) and the admin
+ * backend, but NOT part of `@colyseus/core`'s public surface.
+ *
+ * Third parties should reach for `TrackUserSessionsPlugin` and its
+ * `listUserSessions` static instead — the raw helpers below are
+ * implementation details and can change between minor versions.
+ *
+ * Resolved via the `./*` wildcard in `packages/core/package.json`.
+ *
+ * @internal
+ */
+import * as matchMaker from './MatchMaker.ts';
+import {
+  listUserSessions,
+  type ListUserSessionsOptions,
+  type UserSessionInfo,
+} from './utils/UserSessionIndex.ts';
+
+export {
+  userRoomsKey,
+  USER_ROOMS_KEY_PREFIX,
+  trackUserSession,
+  releaseUserSession,
+  trackRoomJoin,
+  releaseRoomLeave,
+  sweepRoomDispose,
+  listUserSessions,
+  type UserRoomEntry,
+  type UserSessionInfo,
+  type ListUserSessionsOptions,
+} from './utils/UserSessionIndex.ts';
+
+/**
+ * `listUserSessions` wired to the live `matchMaker` — what
+ * `TrackUserSessionsPlugin.listUserSessions` and the admin backend
+ * actually call. The pure `listUserSessions` is kept exported above
+ * so unit tests can drive it with fake presence + findRooms.
+ */
+export function listUserSessionsLive(
+  userId: string,
+  options?: ListUserSessionsOptions,
+): Promise<UserSessionInfo[]> {
+  return listUserSessions(matchMaker.presence, matchMaker.findRoomsByIds, userId, options);
+}

package/src/matchmaker/LocalDriver/LocalDriver.ts

@@ -40,6 +40,16 @@ export class LocalDriver implements MatchMakerDriver {
     return query as unknown as Promise<IRoomCache>;
   }
 
+  public async findByIds(roomIds: string[]): Promise<Map<string, IRoomCache>> {
+    const result = new Map<string, IRoomCache>();
+    if (roomIds.length === 0) { return result; }
+    const wanted = new Set(roomIds);
+    for (const room of this.rooms) {
+      if (wanted.has(room.roomId)) { result.set(room.roomId, room); }
+    }
+    return result;
+  }
+
   public update(room: IRoomCache, operations: Partial<{ $set: Partial<IRoomCache>, $inc: Partial<IRoomCache> }>) {
     if (operations.$set) {
       for (const field in operations.$set) {

package/src/matchmaker/driver.ts

@@ -147,6 +147,19 @@ export interface MatchMakerDriver {
     sortOptions?: SortOptions
   ): Promise<IRoomCache<ExtractRoomCacheMetadata<T>>>;
 
+  /**
+   * Batch-resolve room caches by roomId in a single backend round
+   * trip. Missing roomIds are absent from the returned map. Used by
+   * hot paths (per-join uniqueness check, by-user reverse-index
+   * lookups) where K serial `findOne` calls would multiply round
+   * trips needlessly.
+   *
+   * @param roomIds - Room ids to look up.
+   *
+   * @returns Map keyed by roomId of the rooms that were found.
+   */
+  findByIds(roomIds: string[]): Promise<Map<string, IRoomCache>>;
+
   /**
    * Remove a room from room cache.
    *

package/src/rooms/LobbyRoom.ts

@@ -31,25 +31,29 @@ export interface LobbyOptions {
   filter?: FilterInput;
 }
 
+export type LobbyMessages = {
+  filter: (client: LobbyClient, filter: FilterInput) => void;
+};
+
 export class LobbyRoom<Metadata = any> extends Room {
   public rooms: IRoomCache<Metadata>[] = [];
   public unsubscribeLobby: () => void;
 
   public clientOptions: { [sessionId: string]: LobbyOptions } = {};
 
-  messages = {
-    filter: (client: LobbyClient, filter: FilterInput) => {
+  declare messages: LobbyMessages;
+
+  public async onCreate(options: any) {
+    // prevent LobbyRoom to notify itself
+    this['_listing'].unlisted = true;
+
+    this.onMessage('filter', (client, filter) => {
       const clientOptions = this.clientOptions[client.sessionId];
       if (!clientOptions) { return; }
 
       clientOptions.filter = filter;
       client.send('rooms', this.filterItemsForClient(clientOptions));
-    }
-  }
-
-  public async onCreate(options: any) {
-    // prevent LobbyRoom to notify itself
-    this['_listing'].unlisted = true;
+    });
 
     this.unsubscribeLobby = await subscribeLobby((roomId, data) => {
       const roomIndex = this.rooms.findIndex((room) => room.roomId === roomId);

package/src/rooms/RelayRoom.ts

@@ -1,26 +1,20 @@
 import { CloseCode } from '@colyseus/shared-types';
-import { defineTypes, MapSchema, Schema } from '@colyseus/schema';
+import { schema, t, type SchemaType } from '@colyseus/schema';
 
 import { Room } from '../Room.ts';
 import type { Client } from '../Transport.ts';
 
-class Player extends Schema {
-  public connected: boolean;
-  public name: string;
-  public sessionId: string;
-}
-defineTypes(Player, {
-  connected: 'boolean',
-  name: 'string',
-  sessionId: 'string',
+export const Player = schema({
+  connected: t.boolean(),
+  name: t.string(),
+  sessionId: t.string(),
 });
+export type Player = SchemaType<typeof Player>;
 
-class State extends Schema {
-  public players = new MapSchema<Player>();
-}
-defineTypes(State, {
-  players: { map: Player },
+export const State = schema({
+  players: t.map(Player),
 });
+export type State = SchemaType<typeof State>;
 
 /**
  * client.joinOrCreate("relayroom", {

package/src/router/index.ts

@@ -1,6 +1,7 @@
 import type express from "express";
 import type { IncomingMessage, ServerResponse } from "http";
-import { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint } from "@colyseus/better-call";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint, createMiddleware, APIError } from "@colyseus/better-call";
 import { toNodeHandler, getRequest, setResponse } from "@colyseus/better-call/node";
 import { Transport } from "../Transport.ts";
 import { controller } from "../matchmaker/controller.ts";
@@ -120,19 +121,119 @@ function expressRootRoute(expressApp: express.Application) {
   return stack.find((layer: any) => layer.match('/') && !['query', 'expressInit'].includes(layer.name));
 }
 
-/**
- * Do not use this directly. This is used internally by `@colyseus/playground`.
- * TODO: refactor. Avoid using globals.
- * @internal
- */
-export let __globalEndpoints: Record<string, Endpoint> = {};
-
 export function createRouter<
   E extends Record<string, Endpoint>,
   Config extends RouterConfig
 >(endpoints: E, config: Config = {} as Config) {
-  // TODO: refactor. Avoid using globals.
-  __globalEndpoints = endpoints;
-
   return createBetterCallRouter({ ...endpoints }, config);
 }
+
+export interface BasicAuthOptions {
+  /** username → password. The common static case. */
+  users?: Record<string, string>;
+  /** Custom validator (e.g. DB-backed). Takes precedence over `users`. */
+  validate?: (username: string, password: string) => boolean | Promise<boolean>;
+  /** Realm shown in the browser prompt. Default 'Restricted'. */
+  realm?: string;
+}
+
+/**
+ * HTTP Basic Auth middleware. Drop into any endpoint's `use:` slot to gate
+ * it behind a browser credentials prompt:
+ *
+ *   playground({ use: [basicAuth({ users: { admin: 's3cret' } })] })
+ */
+export function basicAuth(opts: BasicAuthOptions) {
+  const { users, validate } = opts;
+  if (!users && !validate) {
+    throw new Error('[basicAuth] provide `users` or `validate`');
+  }
+  // Realm is interpolated into a header — strip `"` so it can't break out.
+  const challenge = `Basic realm="${(opts.realm ?? 'Restricted').replace(/"/g, '')}", charset="UTF-8"`;
+
+  return createMiddleware(async (ctx) => {
+    const creds = parseBasicHeader(ctx.getHeader('authorization'));
+    const ok = !!creds && (validate
+      ? await validate(creds.username, creds.password)
+      : staticCheck(users!, creds.username, creds.password));
+    if (!ok) {
+      throw new APIError(401, { message: 'authentication required' }, { 'WWW-Authenticate': challenge });
+    }
+  });
+}
+
+function parseBasicHeader(header: string | null | undefined) {
+  if (!header) { return null; }
+  const sep = header.indexOf(' ');
+  if (sep < 0 || header.slice(0, sep).toLowerCase() !== 'basic') { return null; }
+  let decoded: string;
+  try { decoded = Buffer.from(header.slice(sep + 1), 'base64').toString('utf8'); } catch { return null; }
+  const colon = decoded.indexOf(':');
+  if (colon < 0) { return null; }
+  return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };
+}
+
+function staticCheck(users: Record<string, string>, username: string, password: string): boolean {
+  const expected = Object.prototype.hasOwnProperty.call(users, username) ? users[username] : undefined;
+  // Compare even for an unknown user so reject timing doesn't reveal which
+  // usernames exist.
+  return safeEqual(password, expected ?? '\0') && expected !== undefined;
+}
+
+// Hash both sides first: equalizes length (timingSafeEqual throws on a
+// length mismatch, which would itself leak the secret's length).
+function safeEqual(a: string, b: string): boolean {
+  return timingSafeEqual(
+    createHash('sha256').update(a).digest(),
+    createHash('sha256').update(b).digest(),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// dualModeEndpoints — shared express-compat layer for @colyseus/admin,
+// @colyseus/monitor, @colyseus/playground. Builds the two local routers
+// (specific = no catch-all, full = everything) and the matching node
+// handlers, then packages the express middleware so the return value works
+// both as `{...spread}` into createRouter AND as `app.use("/", x)` middleware.
+// ---------------------------------------------------------------------------
+
+export type ExpressMiddleware = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next: (err?: any) => void,
+) => void;
+
+export type NodeHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+export interface DualModeHelpers {
+  specificRouter: Router;
+  specificHandler: NodeHandler;
+  fullRouter: Router;
+  fullHandler: NodeHandler;
+}
+
+export function dualModeEndpoints<E extends Record<string, Endpoint>>(
+  endpoints: E,
+  opts: {
+    /** Key in `endpoints` whose path is a catch-all. Excluded from `specificRouter` so it doesn't eat fall-through decisions. */
+    catchAllKey?: keyof E;
+    /** Build the express middleware given the pre-built routers + node handlers. */
+    buildMiddleware: (helpers: DualModeHelpers) => ExpressMiddleware;
+  },
+): ExpressMiddleware & E {
+  const fullRouter = createRouter(endpoints);
+  const fullHandler = toNodeHandler(fullRouter.handler) as NodeHandler;
+
+  const specificEndpoints = opts.catchAllKey
+    ? Object.fromEntries(
+        Object.entries(endpoints).filter(([k]) => k !== opts.catchAllKey),
+      ) as Partial<E>
+    : endpoints;
+  const specificRouter = createRouter(specificEndpoints as E);
+  const specificHandler = toNodeHandler(specificRouter.handler) as NodeHandler;
+
+  const middleware = opts.buildMiddleware({
+    specificRouter, specificHandler, fullRouter, fullHandler,
+  });
+  return Object.assign(middleware, endpoints) as ExpressMiddleware & E;
+}