@colyseus/core 0.17.0 → 0.17.1

package/src/serializer/SchemaSerializer.ts

@@ -0,0 +1,194 @@
+import type { Serializer } from './Serializer.ts';
+import { type Client, ClientState } from '../Transport.ts';
+
+import { type Iterator, Encoder, dumpChanges, Reflection, Schema, StateView } from '@colyseus/schema';
+import { debugPatch } from '../Debug.ts';
+import { Protocol } from '../Protocol.ts';
+
+const SHARED_VIEW = {};
+
+export class SchemaSerializer<T extends Schema> implements Serializer<T> {
+  public id = 'schema';
+
+  protected encoder: Encoder<T>;
+  protected hasFilters: boolean = false;
+
+  protected handshakeCache: Uint8Array;
+
+  // flag to avoid re-encoding full state if no changes were made
+  protected needFullEncode: boolean = true;
+
+  // TODO: make this optional. allocating a new buffer for each room may not be always necessary.
+  protected fullEncodeBuffer: Uint8Array = new Uint8Array(Encoder.BUFFER_SIZE);
+  protected fullEncodeCache: Uint8Array;
+  protected sharedOffsetCache: Iterator = { offset: 0 };
+
+  protected encodedViews: Map<StateView | typeof SHARED_VIEW, Uint8Array>;
+
+  public reset(newState: T & Schema) {
+    this.encoder = new Encoder(newState);
+    this.hasFilters = this.encoder.context.hasFilters;
+
+    // cache ROOM_STATE byte as part of the encoded buffer
+    this.fullEncodeBuffer[0] = Protocol.ROOM_STATE;
+
+    if (this.hasFilters) {
+      this.encodedViews = new Map();
+    }
+  }
+
+  public getFullState(client?: Client) {
+    if (this.needFullEncode || this.encoder.root.changes.next !== undefined) {
+      this.sharedOffsetCache = { offset: 1 };
+      this.fullEncodeCache = this.encoder.encodeAll(this.sharedOffsetCache, this.fullEncodeBuffer);
+      this.needFullEncode = false;
+    }
+
+    if (this.hasFilters && client?.view) {
+      return this.encoder.encodeAllView(
+        client.view,
+        this.sharedOffsetCache.offset,
+        { ...this.sharedOffsetCache },
+        this.fullEncodeBuffer
+      );
+
+    } else {
+      return this.fullEncodeCache;
+    }
+  }
+
+  public applyPatches(clients: Client[]) {
+    let numClients = clients.length;
+
+    if (numClients === 0) {
+      // skip patching and clear changes
+      this.encoder.discardChanges();
+      return false;
+    }
+
+    if (!this.encoder.hasChanges) {
+
+      // check if views have changes (manual add() or remove() items)
+      if (this.hasFilters) {
+        //
+        // FIXME: refactor this to avoid duplicating code.
+        //
+        // it's probably better to have 2 different 'applyPatches' methods.
+        // (one for handling state with filters, and another for handling state without filters)
+        //
+        const clientsWithViewChange = clients.filter((client) => {
+          return client.state === ClientState.JOINED && client.view?.changes.size > 0
+        });
+
+        if (clientsWithViewChange.length > 0) {
+          const it: Iterator = { offset: 1 };
+
+          const sharedOffset = it.offset;
+          this.encoder.sharedBuffer[0] = Protocol.ROOM_STATE_PATCH;
+
+          clientsWithViewChange.forEach((client) => {
+            client.raw(this.encoder.encodeView(client.view, sharedOffset, it));
+          });
+        }
+      }
+
+      // skip patching state if:
+      // - no clients are connected
+      // - no changes were made
+      // - no "filtered changes" were made when using filters
+      return false;
+    }
+
+    this.needFullEncode = true;
+
+    // dump changes for patch debugging
+    if (debugPatch.enabled) {
+      (debugPatch as any).dumpChanges = dumpChanges(this.encoder.state);
+    }
+
+    // get patch bytes
+    const it: Iterator = { offset: 1 };
+    this.encoder.sharedBuffer[0] = Protocol.ROOM_STATE_PATCH;
+
+    // encode changes once, for all clients
+    const encodedChanges = this.encoder.encode(it);
+
+    if (!this.hasFilters) {
+      while (numClients--) {
+        const client = clients[numClients];
+
+        //
+        // FIXME: avoid this check for each client
+        //
+        if (client.state !== ClientState.JOINED) {
+          continue;
+        }
+
+        client.raw(encodedChanges);
+      }
+
+    } else {
+      // cache shared offset
+      const sharedOffset = it.offset;
+
+      // encode state multiple times, for each client
+      while (numClients--) {
+        const client = clients[numClients];
+
+        //
+        // FIXME: avoid this check for each client
+        //
+        if (client.state !== ClientState.JOINED) {
+          continue;
+        }
+
+        const view = client.view || SHARED_VIEW;
+
+        let encodedView = this.encodedViews.get(view);
+
+        // allow to pass the same encoded view for multiple clients
+        if (encodedView === undefined) {
+          encodedView = (view === SHARED_VIEW)
+            ? encodedChanges
+            : this.encoder.encodeView(client.view, sharedOffset, it);
+          this.encodedViews.set(view, encodedView);
+        }
+
+        client.raw(encodedView);
+      }
+
+      // clear views
+      this.encodedViews.clear();
+    }
+
+    // discard changes after sending
+    this.encoder.discardChanges();
+
+    // debug patches
+    if (debugPatch.enabled) {
+      debugPatch(
+        '%d bytes sent to %d clients, %j',
+        encodedChanges.length,
+        clients.length,
+        (debugPatch as any).dumpChanges,
+      );
+    }
+
+    return true;
+  }
+
+  public handshake() {
+    /**
+     * Cache handshake to avoid encoding it for each client joining
+     */
+    if (!this.handshakeCache) {
+      //
+      // TODO: re-use handshake buffer for all rooms of same type (?)
+      //
+      this.handshakeCache = (this.encoder.state && Reflection.encode(this.encoder));
+    }
+
+    return this.handshakeCache;
+  }
+
+}

package/src/serializer/SchemaSerializerDebug.ts

@@ -0,0 +1,148 @@
+/**
+ * This serializer is a copy of SchemaSerializer,
+ * but it writes debug information to a file.
+ *
+ * This script must be used
+ */
+
+import fs from 'fs';
+import { Schema, dumpChanges, Iterator } from '@colyseus/schema';
+import { SchemaSerializer } from './SchemaSerializer.ts';
+import { Client, ClientState  } from "../Transport.ts";
+import { Protocol} from '../Protocol.ts';
+import { debugPatch } from '../Debug.ts';
+
+/*
+const SHARED_VIEW = {};
+
+export class SchemaSerializerDebug<T> extends SchemaSerializer<T> {
+  protected debugStream: fs.WriteStream;
+
+  constructor(fileName: string = "schema-debug.txt") {
+    super();
+
+    try { fs.unlinkSync(fileName); } catch (e) {}
+    this.debugStream = fs.createWriteStream(fileName, { flags: "a" });
+  }
+
+  public getFullState(client?: Client): Buffer {
+    const buf = super.getFullState(client);
+    this.debugStream.write(`state:${client.sessionId}:${Array.from(buf).slice(1).join(",")}\n`);
+    return buf;
+  }
+
+  public applyPatches(clients: Client[]) {
+    let numClients = clients.length;
+
+    const debugChangesDeep = Schema.debugChangesDeep(this.encoder.state);
+
+    if (
+      numClients == 0 ||
+      (
+        this.encoder.root.changes.size === 0 &&
+        (!this.hasFilters || this.encoder.root.filteredChanges.size === 0)
+      )
+    ) {
+      // skip patching state if:
+      // - no clients are connected
+      // - no changes were made
+      // - no "filtered changes" were made when using filters
+      return false;
+    }
+
+    this.needFullEncode = true;
+
+    // dump changes for patch debugging
+    if (debugPatch.enabled) {
+      (debugPatch as any).dumpChanges = dumpChanges(this.encoder.state);
+    }
+
+    // get patch bytes
+    const it: Iterator = { offset: 1 };
+    this.encoder.sharedBuffer[0] = Protocol.ROOM_STATE_PATCH;
+
+    // encode changes once, for all clients
+    const encodedChanges = this.encoder.encode(it);
+
+    if (!this.hasFilters) {
+      while (numClients--) {
+        const client = clients[numClients];
+
+        //
+        // FIXME: avoid this check for each client
+        //
+        if (client.state !== ClientState.JOINED) {
+          continue;
+        }
+
+        debugChangesDeep.split("\n").forEach((line) => {
+          this.debugStream.write(`#${client.sessionId}:${line}\n`);
+        });
+        this.debugStream.write(`patch:${client.sessionId}:${Array.from(encodedChanges).slice(1).join(",")}\n`);
+
+        client.raw(encodedChanges);
+      }
+
+    } else {
+      // cache shared offset
+      const sharedOffset = it.offset;
+
+      // encode state multiple times, for each client
+      while (numClients--) {
+        const client = clients[numClients];
+
+        //
+        // FIXME: avoid this check for each client
+        //
+        if (client.state !== ClientState.JOINED) {
+          continue;
+        }
+
+        const view = client.view || SHARED_VIEW;
+
+        let encodedView = this.views.get(view);
+
+        // allow to pass the same encoded view for multiple clients
+        if (encodedView === undefined) {
+          encodedView = (view === SHARED_VIEW)
+            ? encodedChanges
+            : this.encoder.encodeView(client.view, sharedOffset, it);
+          this.views.set(view, encodedView);
+        }
+
+        debugChangesDeep.split("\n").forEach((line) => {
+          this.debugStream.write(`#${client.sessionId}:${line}\n`);
+        });
+        this.debugStream.write(`patch:${client.sessionId}:${Array.from(encodedView).slice(1).join(",")}\n`);
+
+        client.raw(encodedView);
+      }
+
+      // clear views
+      this.views.clear();
+    }
+
+    // discard changes after sending
+    this.encoder.discardChanges();
+
+    // debug patches
+    if (debugPatch.enabled) {
+      debugPatch(
+        '%d bytes sent to %d clients, %j',
+        encodedChanges.length,
+        clients.length,
+        (debugPatch as any).dumpChanges,
+      );
+    }
+
+    return true;
+  }
+
+  public handshake(): Buffer {
+    const buf = super.handshake();
+    this.debugStream.write(`handshake:${Array.from(buf).join(",")}\n`);
+    return buf;
+  }
+}
+
+*/

package/src/serializer/Serializer.ts

@@ -0,0 +1,9 @@
+import type { Client } from '../Transport.ts';
+
+export interface Serializer<T> {
+  id: string;
+  reset(data: any): void;
+  getFullState(client?: Client): Uint8Array;
+  applyPatches(clients: Client[], state: T): boolean;
+  handshake?(): Uint8Array;
+}

package/src/utils/DevMode.ts

@@ -0,0 +1,133 @@
+import fs from 'fs';
+import path from 'path';
+import { type Schema, MapSchema, ArraySchema, SetSchema, CollectionSchema, $childType } from '@colyseus/schema';
+import { logger } from '../Logger.ts';
+import { debugAndPrintError, debugDevMode } from '../Debug.ts';
+import { getLocalRoomById, handleCreateRoom, presence, remoteRoomCall } from '../MatchMaker.ts';
+import type { Room } from '../Room.ts';
+
+const DEVMODE_CACHE_FILE_PATH = path.resolve(".devmode.json");
+
+export let isDevMode: boolean = false;
+
+export function hasDevModeCache() {
+  return fs.existsSync(DEVMODE_CACHE_FILE_PATH);
+}
+
+export function getDevModeCache() {
+  return JSON.parse(fs.readFileSync(DEVMODE_CACHE_FILE_PATH, 'utf8')) || {};
+}
+
+export function writeDevModeCache(cache: any) {
+  fs.writeFileSync(DEVMODE_CACHE_FILE_PATH, JSON.stringify(cache, null, 2), 'utf8');
+}
+
+export function setDevMode(bool: boolean) {
+  isDevMode = bool;
+}
+
+export async function reloadFromCache() {
+  const roomHistoryList = Object.entries(await presence.hgetall(getRoomRestoreListKey()));
+  debugDevMode("rooms to restore: %i", roomHistoryList.length);
+
+  for (const [roomId, value] of roomHistoryList) {
+    const roomHistory = JSON.parse(value);
+    debugDevMode("restoring room %s (%s)", roomHistory.roomName, roomId);
+
+    const recreatedRoomListing = await handleCreateRoom(roomHistory.roomName, roomHistory.clientOptions, roomId);
+    const recreatedRoom = getLocalRoomById(recreatedRoomListing.roomId);
+
+    // Restore previous state
+    if (roomHistory.hasOwnProperty("state")) {
+      try {
+        const rawState = JSON.parse(roomHistory.state);
+        logger.debug(`📋 room '${roomId}' state =>`, rawState);
+
+        (recreatedRoom.state as Schema).restore(rawState);
+      } catch (e: any) {
+        debugAndPrintError(`❌ couldn't restore room '${roomId}' state:\n${e.stack}`);
+      }
+    }
+
+    // Reserve seats for clients from cached history
+    if (roomHistory.clients) {
+      for (const clientData of roomHistory.clients) {
+        // TODO: need to restore each client's StateView as well
+        // reserve seat for 20 seconds
+        const { sessionId, reconnectionToken } = clientData;
+        await remoteRoomCall(recreatedRoomListing.roomId, '_reserveSeat', [sessionId, {}, {}, 20, false, reconnectionToken]);
+      }
+    }
+
+    // call `onRestoreRoom` with custom 'cache'd property.
+    recreatedRoom.onRestoreRoom?.(roomHistory["cache"]);
+
+    logger.debug(`🔄 room '${roomId}' has been restored with ${roomHistory.clients?.length || 0} reserved seats: ${roomHistory.clients?.map((c: any) => c.sessionId).join(", ")}`);
+  }
+
+  if (roomHistoryList.length > 0) {
+    logger.debug("✅", roomHistoryList.length, "room(s) have been restored.");
+  }
+}
+
+export async function cacheRoomHistory(rooms: { [roomId: string]: Room }) {
+  for (const room of Object.values(rooms)) {
+    const roomHistoryResult = await presence.hget(getRoomRestoreListKey(), room.roomId);
+    if (roomHistoryResult) {
+      try {
+        const roomHistory = JSON.parse(roomHistoryResult);
+
+        // custom cache method
+        roomHistory["cache"] = room.onCacheRoom?.();
+
+        // encode state
+        debugDevMode("caching room %s (%s)", room.roomName, room.roomId);
+
+        if (room.state) {
+          roomHistory["state"] = JSON.stringify(room.state);
+        }
+
+        // cache active clients with their reconnection tokens
+        // TODO: need to cache each client's StateView as well
+        const activeClients = room.clients.map((client) => ({
+          sessionId: client.sessionId,
+          reconnectionToken: client.reconnectionToken,
+        }));
+
+        // collect active client sessionIds to avoid duplicates
+        const activeSessionIds = new Set(activeClients.map((c) => c.sessionId));
+
+        // also cache reserved seats (they don't have reconnectionTokens yet)
+        // filter out reserved seats that are already active clients (from devMode reconnection)
+        const reservedSeats = Object.keys(room['_reservedSeats'])
+          .filter((sessionId) => !activeSessionIds.has(sessionId))
+          .map((sessionId) => ({
+            sessionId,
+            reconnectionToken: undefined,
+          }));
+
+        roomHistory["clients"] = activeClients.concat(reservedSeats);
+
+        await presence.hset(getRoomRestoreListKey(), room.roomId, JSON.stringify(roomHistory));
+
+        // Rewrite updated room history
+        logger.debug(`💾 caching room '${room.roomId}' (clients: ${room.clients.length}, has state: ${roomHistory["state"] !== undefined ? "yes" : "no"})`);
+
+      } catch (e: any) {
+        debugAndPrintError(`❌ couldn't cache room '${room.roomId}', due to:\n${e.stack}`);
+      }
+    }
+  }
+}
+
+export async function getPreviousProcessId(hostname: string = '') {
+  return await presence.hget(getProcessRestoreKey(), hostname);
+}
+
+export function getRoomRestoreListKey() {
+  return 'roomhistory';
+}
+
+export function getProcessRestoreKey() {
+  return 'processhistory';
+}

package/src/utils/StandardSchema.ts

@@ -0,0 +1,20 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export type { StandardSchemaV1 };
+
+export function standardValidate<T extends StandardSchemaV1>(
+    schema: T,
+    input: StandardSchemaV1.InferInput<T>
+): StandardSchemaV1.InferOutput<T> {
+    let result = schema['~standard'].validate(input);
+
+    if (result instanceof Promise) {
+        throw new Error('Schema validation must be synchronous');
+    }
+
+    // if the `issues` field exists, the validation failed
+    if (result.issues) {
+        throw new Error(JSON.stringify(result.issues, null, 2));
+    }
+
+    return (result as StandardSchemaV1.SuccessResult<StandardSchemaV1.InferOutput<T>>).value;
+}

package/src/utils/Utils.ts

@@ -0,0 +1,169 @@
+import { nanoid } from 'nanoid';
+
+import { EventEmitter } from "events";
+import { type RoomException, type RoomMethodName } from '../errors/RoomExceptions.ts';
+
+import { debugAndPrintError, debugMatchMaking } from '../Debug.ts';
+
+export type Type<T> = new (...args: any[]) => T;
+export type MethodName<T> = string & {
+  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never
+}[keyof T];
+
+/**
+ * Utility type that extracts the return type of a method or the type of a property
+ * from a given class/object type.
+ *
+ * - If the key is a method, returns the awaited return type of that method
+ * - If the key is a property, returns the type of that property
+ */
+export type ExtractMethodOrPropertyType<
+  TClass,
+  TKey extends keyof TClass
+> = TClass[TKey] extends (...args: any[]) => infer R
+  ? Awaited<R>
+  : TClass[TKey];
+
+// remote room call timeouts
+export const REMOTE_ROOM_SHORT_TIMEOUT = Number(process.env.COLYSEUS_PRESENCE_SHORT_TIMEOUT || 2000);
+export const MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME = Number(process.env.COLYSEUS_MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME || 0.5);
+
+export function generateId(length: number = 9) {
+  return nanoid(length);
+}
+
+export function getBearerToken(authHeader: string) {
+  return (authHeader && authHeader.startsWith("Bearer ") && authHeader.substring(7, authHeader.length)) || undefined;
+}
+
+// nodemon sends SIGUSR2 before reloading
+// (https://github.com/remy/nodemon#controlling-shutdown-of-your-script)
+//
+const signals: NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGUSR2'];
+
+export function registerGracefulShutdown(callback: (err?: Error) => void) {
+  /**
+   * Gracefully shutdown on uncaught errors
+   */
+  process.on('uncaughtException', (err) => {
+    debugAndPrintError(err);
+    callback(err);
+  });
+
+  signals.forEach((signal) =>
+    process.once(signal, () => callback()));
+}
+
+export function retry<T = any>(
+  cb: Function,
+  maxRetries: number = 3,
+  errorWhiteList: any[] = [],
+  retries: number = 0,
+) {
+  return new Promise<T>((resolve, reject) => {
+    cb()
+      .then(resolve)
+      .catch((e: any) => {
+        if (
+          errorWhiteList.indexOf(e.constructor) !== -1 &&
+          retries++ < maxRetries
+        ) {
+          setTimeout(() => {
+            debugMatchMaking("retrying due to error (error: %s, retries: %s, maxRetries: %s)", e.message, retries, maxRetries);
+            retry<T>(cb, maxRetries, errorWhiteList, retries).
+              then(resolve).
+              catch((e2) => reject(e2));
+          }, Math.floor(Math.random() * Math.pow(2, retries) * 400));
+
+        } else {
+          reject(e);
+        }
+      });
+  });
+}
+
+export function spliceOne(arr: any[], index: number): boolean {
+  // manually splice availableRooms array
+  // http://jsperf.com/manual-splice
+  if (index === -1 || index >= arr.length) {
+    return false;
+  }
+
+  const len = arr.length - 1;
+  for (let i = index; i < len; i++) {
+    arr[i] = arr[i + 1];
+  }
+
+  arr.length = len;
+  return true;
+}
+
+export class Deferred<T = any> {
+  public promise: Promise<T>;
+
+  public resolve: Function;
+  public reject: Function;
+
+  constructor(promise?: Promise<T>) {
+    this.promise = promise ?? new Promise<T>((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+    });
+  }
+
+  public then(onFulfilled?: (value: T) => any, onRejected?: (reason: any) => any) {
+    return this.promise.then(onFulfilled, onRejected);
+  }
+
+  public catch(func: (value: any) => any) {
+    return this.promise.catch(func);
+  }
+
+  static reject (reason?: any) {
+    return new Deferred(Promise.reject(reason));
+  }
+
+  static resolve<T = any>(value?: T) {
+    return new Deferred<T>(Promise.resolve(value));
+  }
+
+}
+
+export function merge(a: any, ...objs: any[]): any {
+  for (let i = 0, len = objs.length; i < len; i++) {
+    const b = objs[i];
+    for (const key in b) {
+      if (b.hasOwnProperty(key)) {
+        a[key] = b[key];
+      }
+    }
+  }
+  return a;
+}
+
+export function wrapTryCatch(
+  method: Function,
+  onError: (error: RoomException, methodName: RoomMethodName) => void,
+  exceptionClass: Type<RoomException>,
+  methodName: RoomMethodName,
+  rethrow: boolean = false,
+  ...additionalErrorArgs: any[]
+) {
+  return (...args: any[]) => {
+    try {
+      const result = method(...args);
+      if (typeof (result?.catch) === "function") {
+        return result.catch((e: Error) => {
+          onError(new exceptionClass(e, e.message, ...args, ...additionalErrorArgs), methodName);
+          if (rethrow) { throw e; }
+        });
+      }
+      return result;
+    } catch (e: any) {
+      onError(new exceptionClass(e, e.message, ...args, ...additionalErrorArgs), methodName);
+      if (rethrow) { throw e; }
+    }
+  };
+}
+
+export class HttpServerMock extends EventEmitter {}

package/src/utils/nanoevents.ts

@@ -0,0 +1,20 @@
+export const createNanoEvents = () => ({
+    emit(event: string, ...args: any[]) {
+      for (
+        let callbacks = this.events[event] || [],
+          i = 0,
+          length = callbacks.length;
+        i < length;
+        i++
+      ) {
+        callbacks[i](...args)
+      }
+    },
+    events: {},
+    on(event: string, cb: (...args: any[]) => void) {
+      ;(this.events[event] ||= []).push(cb)
+      return () => {
+        this.events[event] = this.events[event]?.filter(i => cb !== i)
+      }
+    }
+  })