@colyseus/core 0.17.0 → 0.17.1

package/src/errors/RoomExceptions.ts

@@ -0,0 +1,141 @@
+import type { ExtractMessageType, Room } from '../Room.ts';
+
+export type RoomMethodName = 'onCreate'
+  | 'onAuth'
+  | 'onJoin'
+  | 'onLeave'
+  | 'onDispose'
+  | 'onMessage'
+  | 'setSimulationInterval'
+  | 'setInterval'
+  | 'setTimeout';
+
+export type RoomException<R extends Room = Room> =
+  OnCreateException<R> |
+  OnAuthException<R> |
+  OnJoinException<R> |
+  OnLeaveException<R> |
+  OnDisposeException |
+  OnMessageException<R> |
+  SimulationIntervalException |
+  TimedEventException;
+
+export class OnCreateException<R extends Room = Room> extends Error {
+  options: Parameters<R['onCreate']>[0];
+  constructor(
+    cause: Error,
+    message: string,
+    options:  Parameters<R['onCreate']>[0],
+  ) {
+    super(message, { cause });
+    this.name = 'OnCreateException';
+    this.options = options;
+  }
+}
+
+export class OnAuthException<R extends Room = Room> extends Error {
+  client: Parameters<R['onAuth']>[0];
+  options: Parameters<R['onAuth']>[1];
+  constructor(
+    cause: Error,
+    message: string,
+    client: Parameters<R['onAuth']>[0],
+    options: Parameters<R['onAuth']>[1],
+  ) {
+    super(message, { cause });
+    this.name = 'OnAuthException';
+    this.client = client;
+    this.options = options;
+  }
+}
+
+export class OnJoinException<R extends Room = Room> extends Error {
+  client: Parameters<R['onJoin']>[0];
+  options: Parameters<R['onJoin']>[1];
+  auth: Parameters<R['onJoin']>[2];
+  constructor(
+    cause: Error,
+    message: string,
+    client: Parameters<R['onJoin']>[0],
+    options: Parameters<R['onJoin']>[1],
+    auth: Parameters<R['onJoin']>[2],
+  ) {
+    super(message, { cause });
+    this.name = 'OnJoinException';
+    this.client = client;
+    this.options = options;
+    this.auth = auth;
+  }
+}
+
+export class OnLeaveException<R extends Room = Room> extends Error {
+  client: Parameters<R['onLeave']>[0];
+  consented: Parameters<R['onLeave']>[1];
+  constructor(
+    cause: Error,
+    message: string,
+    client: Parameters<R['onLeave']>[0],
+    consented: Parameters<R['onLeave']>[1],
+  ) {
+    super(message, { cause });
+    this.name = 'OnLeaveException';
+    this.client = client;
+    this.consented = consented;
+  }
+}
+
+export class OnDisposeException extends Error {
+  constructor(
+    cause: Error,
+    message: string,
+  ) {
+    super(message, { cause });
+    this.name = 'OnDisposeException';
+  }
+}
+
+export class OnMessageException<R extends Room, MessageType extends keyof R['messages'] = keyof R['messages']> extends Error {
+  client: R['~client'];
+  payload: ExtractMessageType<R['messages'][MessageType]>;
+  type: MessageType;
+  constructor(
+    cause: Error,
+    message: string,
+    client: R['~client'],
+    payload: ExtractMessageType<R['messages'][MessageType]>,
+    type: MessageType,
+  ) {
+    super(message, { cause });
+    this.name = 'OnMessageException';
+    this.client = client;
+    this.payload = payload;
+    this.type = type;
+  }
+
+  public isType<T extends keyof R['messages']>(type: T): this is OnMessageException<R, T> {
+    return (this.type as string) === type;
+  }
+}
+
+export class SimulationIntervalException extends Error {
+  constructor(
+    cause: Error,
+    message: string,
+  ) {
+    super(message, { cause });
+    this.name = 'SimulationIntervalException';
+  }
+}
+
+export class TimedEventException extends Error {
+  public args: any[];
+  constructor(
+    cause: Error,
+    message: string,
+    ...args: any[]
+  ) {
+    super(message, { cause });
+    this.name = 'TimedEventException';
+    this.args = args;
+  }
+}

package/src/errors/SeatReservationError.ts

@@ -0,0 +1,5 @@
+export class SeatReservationError extends Error {
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/errors/ServerError.ts

@@ -0,0 +1,17 @@
+import { ErrorCode } from '../Protocol.ts';
+
+export class ServerError extends Error {
+  public code: number;
+
+  constructor(code: number = ErrorCode.MATCHMAKE_UNHANDLED, message?: string) {
+    super(message);
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ServerError);
+    }
+
+    this.name = 'ServerError';
+    this.code = code;
+  }
+}

package/src/index.ts

@@ -0,0 +1,81 @@
+import { ClockTimer as Clock, Delayed } from '@colyseus/timer';
+
+// Core classes
+export { Server, defineRoom, defineServer, type ServerOptions, type SDKTypes } from './Server.ts';
+export { Room, room, RoomInternalState, validate, type RoomOptions, type MessageHandlerWithFormat, type ExtractMessageType, type Messages, type ExtractRoomState, type ExtractRoomMetadata, type ExtractRoomClient } from './Room.ts';
+export { Protocol, ErrorCode, getMessageBytes, CloseCode } from './Protocol.ts';
+export { RegisteredHandler } from './matchmaker/RegisteredHandler.ts';
+export { ServerError } from './errors/ServerError.ts';
+
+export {
+  type RoomException,
+  type RoomMethodName,
+  OnCreateException,
+  OnAuthException,
+  OnJoinException,
+  OnLeaveException,
+  OnDisposeException,
+  OnMessageException,
+  SimulationIntervalException,
+  TimedEventException,
+} from './errors/RoomExceptions.ts';
+
+// MatchMaker
+import * as matchMaker from './MatchMaker.ts';
+export { matchMaker };
+export { updateLobby, subscribeLobby } from './matchmaker/Lobby.ts';
+
+// Driver
+export * from './matchmaker/LocalDriver/LocalDriver.ts';
+export { initializeRoomCache } from './matchmaker/driver.ts';
+
+// Transport
+export { type Client, type ClientPrivate, type AuthContext, ClientState, ClientArray, Transport, type ISendOptions, connectClientToRoom } from './Transport.ts';
+
+// Presence
+export { type Presence } from './presence/Presence.ts';
+export { LocalPresence } from './presence/LocalPresence.ts';
+
+// Serializers
+export { type Serializer } from './serializer/Serializer.ts';
+export { SchemaSerializer } from './serializer/SchemaSerializer.ts';
+// export { SchemaSerializerDebug } from './serializer/SchemaSerializerDebug.ts';
+
+// Utilities
+export { Clock, Delayed };
+export { generateId, Deferred, HttpServerMock, spliceOne, getBearerToken } from './utils/Utils.ts';
+export { isDevMode } from './utils/DevMode.ts';
+
+// IPC
+export { subscribeIPC, requestFromIPC } from './IPC.ts';
+
+// Debug
+export {
+  debugMatchMaking,
+  debugMessage,
+  debugPatch,
+  debugError,
+  debugConnection,
+  debugDriver,
+  debugPresence,
+  debugAndPrintError,
+} from './Debug.ts';
+
+// Default rooms
+export { LobbyRoom } from './rooms/LobbyRoom.ts';
+export { RelayRoom } from './rooms/RelayRoom.ts';
+export { RankedQueueRoom, type RankedQueueOptions, type MatchGroup, type MatchTeam, type ClientQueueData } from './rooms/RankedQueueRoom.ts';
+
+// Router / Endpoints
+export {
+  createEndpoint,
+  createInternalContext,
+  createMiddleware,
+  createRouter,
+  toNodeHandler,
+  __globalEndpoints,
+  type Router,
+} from './router/index.ts';
+
+// Abstract logging support
+export { logger } from './Logger.ts';

package/src/matchmaker/Lobby.ts

@@ -0,0 +1,68 @@
+import * as matchMaker from '../MatchMaker.ts';
+
+import type { Room } from '../Room.ts';
+import type { IRoomCache } from './driver.ts';
+
+const LOBBY_CHANNEL = '$lobby';
+
+/*
+ * TODO: refactor this on 1.0
+ *
+ * Some users might be relying on "1" = "removed" from the lobby due to this workaround: https://github.com/colyseus/colyseus/issues/617
+ * Though, for consistency, we should invert as "0" = "invisible" and "1" = "visible".
+ *
+ * - rename "removed" to "isVisible" and swap the logic
+ * - emit "visibility-change" with inverted value (isVisible)
+ * - update "subscribeLobby" to check "1" as "isVisible" instead of "removed"
+ */
+
+export function updateLobby<T extends Room>(room: T, removed: boolean = false) {
+  const listing = room['_listing'];
+
+  if (listing.unlisted || !listing.roomId) {
+    return;
+  }
+
+  if (removed) {
+    matchMaker.presence.publish(LOBBY_CHANNEL, `${listing.roomId},1`);
+  } else if (!listing.private) {
+    matchMaker.presence.publish(LOBBY_CHANNEL, `${listing.roomId},0`);
+  }
+}
+
+export async function subscribeLobby(callback: (roomId: string, roomListing: IRoomCache) => void) {
+  // Track removed roomIds to prevent race conditions where pending queries
+  // complete after a room has been removed
+  const removedRoomIds = new Set<string>();
+
+  const cb = async (message: string) => {
+    const [roomId, isRemove] = message.split(',');
+
+    if (isRemove === '1') {
+      // Mark as removed and process immediately
+      removedRoomIds.add(roomId);
+      callback(roomId, null);
+
+      // Clean up after a short timeout to prevent memory leaks
+      setTimeout(() => removedRoomIds.delete(roomId), 2000);
+
+    } else {
+      // Clear removed status - room might be coming back (e.g., visibility change)
+      removedRoomIds.delete(roomId);
+
+      const room = (await matchMaker.query({ roomId }))[0];
+
+      // Check if room was removed while we were querying
+      // See "updating metadata should not cause race condition" test in LobbyRoom.test.ts
+      if (removedRoomIds.has(roomId)) {
+        return;
+      }
+
+      callback(roomId, room);
+    }
+  };
+
+  await matchMaker.presence.subscribe(LOBBY_CHANNEL, cb);
+
+  return () => matchMaker.presence.unsubscribe(LOBBY_CHANNEL, cb);
+}

package/src/matchmaker/LocalDriver/LocalDriver.ts

@@ -0,0 +1,92 @@
+import { debugMatchMaking } from '../../Debug.ts';
+import type { IRoomCache, SortOptions, MatchMakerDriver } from '../driver.ts';
+import { Query } from './Query.ts';
+
+// re-export
+export type { IRoomCache, SortOptions, MatchMakerDriver };
+
+export class LocalDriver implements MatchMakerDriver {
+  public rooms: IRoomCache[] = [];
+
+  public has(roomId: string) {
+    return this.rooms.some((room) => room.roomId === roomId);
+  }
+
+  public query(conditions: Partial<IRoomCache>, sortOptions?: SortOptions) {
+    const query = new Query<IRoomCache>(this.rooms, conditions);
+
+    if (sortOptions) {
+      query.sort(sortOptions);
+    }
+
+    return query.filter(conditions);
+  }
+
+  public cleanup(processId: string) {
+    const cachedRooms = this.query({ processId });
+    debugMatchMaking("removing stale rooms by processId %s (%s rooms found)", processId, cachedRooms.length);
+
+    cachedRooms.forEach((room) => this.remove(room.roomId));
+    return Promise.resolve();
+  }
+
+  public findOne(conditions: Partial<IRoomCache>, sortOptions?: SortOptions) {
+    const query = new Query<IRoomCache>(this.rooms, conditions);
+
+    if (sortOptions) {
+      query.sort(sortOptions);
+    }
+
+    return query as unknown as Promise<IRoomCache>;
+  }
+
+  public update(room: IRoomCache, operations: Partial<{ $set: Partial<IRoomCache>, $inc: Partial<IRoomCache> }>) {
+    if (operations.$set) {
+      for (const field in operations.$set) {
+        if (operations.$set.hasOwnProperty(field)) {
+          room[field] = operations.$set[field];
+        }
+      }
+    }
+
+    if (operations.$inc) {
+      for (const field in operations.$inc) {
+        if (operations.$inc.hasOwnProperty(field)) {
+          room[field] += operations.$inc[field];
+        }
+      }
+    }
+
+    return true;
+  }
+
+  public persist(room: IRoomCache, create: boolean = false) {
+    // if (this.rooms.indexOf(room) !== -1) {
+    //   // already in the list
+    //   return true;
+    // }
+
+    if (!create) { return false; }
+
+    // add to the list
+    this.rooms.push(room);
+
+    return true;
+  }
+
+  public remove(roomId: string) {
+    const roomIndex = this.rooms.findIndex((room) => room.roomId === roomId);
+    if (roomIndex !== -1) {
+      this.rooms.splice(roomIndex, 1);
+      return true;
+    }
+    return false;
+  }
+
+  public clear() {
+    this.rooms = [];
+  }
+
+  public shutdown() {
+  }
+}

package/src/matchmaker/LocalDriver/Query.ts

@@ -0,0 +1,94 @@
+import type { IRoomCache, SortOptions } from '../driver.ts';
+
+export class Query<T extends IRoomCache> {
+  private $rooms: T[];
+  private conditions: any;
+  private sortOptions?: SortOptions;
+
+  constructor(rooms: any[], conditions) {
+    this.$rooms = rooms.slice(0);
+    this.conditions = conditions;
+  }
+
+  public sort(options: SortOptions) {
+    // Store sort options instead of sorting immediately
+    // This allows filtering first, then sorting fewer items
+    this.sortOptions = options;
+    return this;
+  }
+
+  private applySort(rooms: T[]): T[] {
+    if (!this.sortOptions) {
+      return rooms;
+    }
+
+    return rooms.sort((room1: T, room2: T) => {
+      for (const field in this.sortOptions) {
+        const direction = this.sortOptions[field];
+        if (room1.hasOwnProperty(field)) {
+          /**
+           * IRoomCache field
+           */
+          if (direction === 1 || direction === 'asc' || direction === 'ascending') {
+            if (room1[field] > room2[field]) { return 1; }
+            if (room1[field] < room2[field]) { return -1; }
+
+          } else {
+            if (room1[field] > room2[field]) { return -1; }
+            if (room1[field] < room2[field]) { return 1; }
+          }
+        } else if (room1.metadata?.hasOwnProperty(field)) {
+          /**
+           * metadata field
+           */
+          if (direction === 1 || direction === 'asc' || direction === 'ascending') {
+            if (room1.metadata[field] > room2.metadata[field]) { return 1; }
+            if (room1.metadata[field] < room2.metadata[field]) { return -1; }
+          } else {
+            if (room1.metadata[field] > room2.metadata[field]) { return -1; }
+            if (room1.metadata[field] < room2.metadata[field]) { return 1; }
+          }
+        }
+      }
+      return 0;
+    });
+  }
+
+  private applyFilter(rooms: T[], conditions: any): T[] {
+    return rooms.filter(((room) => {
+      for (const field in conditions) {
+        if (conditions.hasOwnProperty(field)) {
+          // Check if field exists in room (IRoomCache base fields)
+          if (room.hasOwnProperty(field)) {
+            if (room[field] !== conditions[field]) {
+              return false;
+            }
+          } else if (room.metadata?.hasOwnProperty(field)) {
+            // Check if field exists in metadata
+            if (room.metadata[field] !== conditions[field]) {
+              return false;
+            }
+          } else {
+            // Field doesn't exist in room or metadata
+            return false;
+          }
+        }
+      }
+      return true;
+    }));
+  }
+
+  public filter(conditions: any) {
+    // Filter first to reduce the number of items to sort
+    const filtered = this.applyFilter(this.$rooms, conditions);
+    return this.applySort(filtered);
+  }
+
+  public then(resolve, reject) {
+    // Filter first to reduce the number of items to sort
+    const filtered = this.applyFilter(this.$rooms, this.conditions);
+    const sorted = this.applySort(filtered);
+    const result: any = sorted[0];
+    return resolve(result);
+  }
+}

package/src/matchmaker/RegisteredHandler.ts

@@ -0,0 +1,172 @@
+import { EventEmitter } from 'events';
+import { logger } from '../Logger.ts';
+import { Room } from './../Room.ts';
+import { updateLobby } from './Lobby.ts';
+
+import type { IRoomCache, SortOptions, IRoomCacheFilterByKeys, IRoomCacheSortByKeys, ExtractMetadata } from './driver.ts';
+import type { Client } from '../Transport.ts';
+import type { Type } from "../utils/Utils.ts";
+
+export const INVALID_OPTION_KEYS: Array<keyof IRoomCache> = [
+  'clients',
+  'locked',
+  'private',
+  // 'maxClients', - maxClients can be useful as filter options
+  'metadata',
+  'name',
+  'processId',
+  'roomId',
+];
+
+/**
+ * Type for filterBy that supports both onCreate options and metadata fields
+ */
+type FilterByKeys<RoomType extends Room> =
+  | IRoomCacheFilterByKeys
+  | (ExtractMetadata<RoomType> extends object
+      ? keyof ExtractMetadata<RoomType> & string
+      : never)
+
+/**
+ * Type for sortBy that supports room cache fields and metadata fields
+ */
+type SortByKeys<RoomType extends Room> =
+  | IRoomCacheSortByKeys
+  | (ExtractMetadata<RoomType> extends object
+      ? keyof ExtractMetadata<RoomType> & string
+      : never);
+
+export interface RegisteredHandlerEvents<RoomType extends Type<Room> = any> {
+  create: [room: InstanceType<RoomType>];
+  lock: [room: InstanceType<RoomType>];
+  unlock: [room: InstanceType<RoomType>];
+  join: [room: InstanceType<RoomType>, client: Client];
+  leave: [room: InstanceType<RoomType>, client: Client, willDispose: boolean];
+  dispose: [room: InstanceType<RoomType>];
+  'visibility-change': [room: InstanceType<RoomType>, isVisible: boolean];
+  'metadata-change': [room: InstanceType<RoomType>];
+}
+
+export class RegisteredHandler<
+  RoomType extends Type<Room> = any
+> extends EventEmitter<RegisteredHandlerEvents<RoomType>> {
+  '~room': RoomType;
+
+  public klass: RoomType;
+  public options: any;
+
+  public name: string;
+  public filterOptions: Array<FilterByKeys<InstanceType<RoomType>>> = [];
+  public sortOptions?: SortOptions;
+
+  public realtimeListingEnabled: boolean = false;
+
+  constructor(klass: RoomType, options?: any) {
+    super();
+
+    this.klass = klass;
+    this.options = options;
+
+    if (typeof(klass) !== 'function') {
+      logger.debug('You are likely not importing your room class correctly.');
+      throw new Error(`class is expected but ${typeof(klass)} was provided.`);
+    }
+  }
+
+  public enableRealtimeListing() {
+    this.realtimeListingEnabled = true;
+    this.on('create', (room) => updateLobby(room));
+    this.on('lock', (room) => updateLobby(room));
+    this.on('unlock', (room) => updateLobby(room));
+    this.on('join', (room) => updateLobby(room));
+    this.on('leave', (room, _, willDispose) => {
+      if (!willDispose) {
+        updateLobby(room);
+      }
+    });
+    this.on('visibility-change', (room, isVisible) => updateLobby(room, isVisible));
+    this.on('metadata-change', (room) => updateLobby(room));
+    this.on('dispose', (room) => updateLobby(room, true));
+    return this;
+  }
+
+  /**
+   * Define which fields should be used for filtering rooms.
+   * Supports both onCreate options and metadata fields using dot notation.
+   *
+   * @example
+   * // Filter by IRoomCache fields
+   * .filterBy(['maxClients'])
+   *
+   * @example
+   * // Filter by metadata fields
+   * .filterBy(['difficulty', 'metadata.region'])
+   *
+   * @example
+   * // Mix both
+   * .filterBy(['mode', 'difficulty', 'maxClients'])
+   */
+  public filterBy<T extends FilterByKeys<InstanceType<RoomType>>>(
+    options: T[]
+  ) {
+    this.filterOptions = options;
+    return this;
+  }
+
+  /**
+   * Define how rooms should be sorted when querying.
+   * Supports both room cache fields and metadata fields using dot notation.
+   *
+   * @example
+   * // Sort by number of clients (descending)
+   * .sortBy({ clients: -1 })
+   *
+   * @example
+   * // Sort by metadata field
+   * .sortBy({ 'metadata.rating': -1 })
+   *
+   * @example
+   * // Multiple sort criteria
+   * .sortBy({ 'metadata.skillLevel': 1, clients: -1 })
+   */
+  public sortBy<T extends SortByKeys<InstanceType<RoomType>>>(
+    options: { [K in T]: SortOptions[string] }
+  ): this {
+    this.sortOptions = options as unknown as SortOptions;
+    return this;
+  }
+
+  public getMetadataFromOptions(options: any) {
+    const metadata = this.getFilterOptions(options);
+
+    if (this.sortOptions) {
+      for (const field in this.sortOptions) {
+        if (field in options && !(field in metadata)) {
+          metadata[field] = options[field];
+        }
+      }
+    }
+
+    return Object.keys(metadata).length > 0 ? { metadata } : {};
+  }
+
+  /**
+   * Extract filter options from client options.
+   */
+  public getFilterOptions(options: any) {
+    return this.filterOptions.reduce((prev, curr, i, arr) => {
+      const field = String(arr[i]);
+
+      // Handle regular (non-metadata) fields
+      if (options.hasOwnProperty(field)) {
+        if (INVALID_OPTION_KEYS.indexOf(field as any) !== -1) {
+          logger.warn(`option "${field}" has internal usage and is going to be ignored.`);
+        } else {
+          prev[field] = options[field];
+        }
+      }
+
+      return prev;
+    }, {});
+  }
+}