@colyseus/core 0.17.0 → 0.17.1

package/src/Server.ts

@@ -0,0 +1,325 @@
+import greeting from "@colyseus/greeting-banner";
+
+import { debugAndPrintError } from './Debug.ts';
+import * as matchMaker from './MatchMaker.ts';
+import { RegisteredHandler } from './matchmaker/RegisteredHandler.ts';
+
+import { type OnCreateOptions, Room } from './Room.ts';
+import { registerGracefulShutdown, type Type } from './utils/Utils.ts';
+
+import type { Presence } from "./presence/Presence.ts";
+import { LocalPresence } from './presence/LocalPresence.ts';
+import { LocalDriver } from './matchmaker/LocalDriver/LocalDriver.ts';
+
+import { Transport } from './Transport.ts';
+import { logger, setLogger } from './Logger.ts';
+import { setDevMode, isDevMode } from './utils/DevMode.ts';
+import { bindRouterToServer, type Router } from './router/index.ts';
+import { getDefaultRouter } from "./router/default_routes.ts";
+
+export type ServerOptions = {
+  publicAddress?: string,
+  presence?: Presence,
+  driver?: matchMaker.MatchMakerDriver,
+  transport?: Transport,
+  gracefullyShutdown?: boolean,
+  logger?: any;
+
+  /**
+   * Custom function to determine which process should handle room creation.
+   * Default: assign new rooms the process with least amount of rooms created
+   */
+  selectProcessIdToCreateRoom?: matchMaker.SelectProcessIdCallback;
+
+  /**
+   * If enabled, rooms are going to be restored in the server-side upon restart,
+   * clients are going to automatically re-connect when server reboots.
+   *
+   * Beware of "schema mismatch" issues. When updating Schema structures and
+   * reloading existing data, you may see "schema mismatch" errors in the
+   * client-side.
+   *
+   * (This operation is costly and should not be used in a production
+   * environment)
+   */
+  devMode?: boolean,
+
+  /**
+   * Display greeting message on server start.
+   * Default: true
+   */
+  greet?: boolean,
+};
+
+/**
+ * Exposed types for the client-side SDK.
+ */
+export interface SDKTypes<
+  RoomTypes extends Record<string, RegisteredHandler> = any,
+  Routes extends Router = any
+> {
+  '~rooms': RoomTypes;
+  '~routes': Routes;
+}
+
+export class Server<
+  RoomTypes extends Record<string, RegisteredHandler> = any,
+  Routes extends Router = any
+> implements SDKTypes<RoomTypes, Routes> {
+  '~rooms': RoomTypes;
+  '~routes': Routes;
+
+  public transport: Transport;
+  public router: Routes;
+  public options: ServerOptions;
+
+  protected presence: Presence;
+  protected driver: matchMaker.MatchMakerDriver;
+
+  protected port: number;
+  protected greet: boolean;
+
+  private _originalRoomOnMessage: typeof Room.prototype['_onMessage'] | null = null;
+
+  constructor(options: ServerOptions = {}) {
+    const {
+      gracefullyShutdown = true,
+      greet = true
+    } = options;
+
+    setDevMode(options.devMode === true);
+
+    this.presence = options.presence || new LocalPresence();
+    this.driver = options.driver || new LocalDriver();
+    this.options = options;
+    this.greet = greet;
+
+    this.attach(options);
+
+    matchMaker.setup(
+      this.presence,
+      this.driver,
+      options.publicAddress,
+      options.selectProcessIdToCreateRoom,
+    );
+
+    if (gracefullyShutdown) {
+      registerGracefulShutdown((err) => this.gracefullyShutdown(true, err));
+    }
+
+    if (options.logger) {
+      setLogger(options.logger);
+    }
+  }
+
+  public attach(options: ServerOptions) {
+    this.transport = options.transport || this.getDefaultTransport(options);
+    delete options.transport;
+  }
+
+  /**
+   * Bind the server into the port specified.
+   *
+   * @param port
+   * @param hostname
+   * @param backlog
+   * @param listeningListener
+   */
+  public async listen(port: number, hostname?: string, backlog?: number, listeningListener?: Function) {
+    this.port = port;
+
+    //
+    // Make sure matchmaker is ready before accepting connections
+    // (isDevMode: matchmaker may take extra milliseconds to restore the rooms)
+    //
+    await matchMaker.accept();
+
+    /**
+     * Greetings!
+     */
+    if (this.greet) {
+      console.log(greeting);
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      this.transport.listen(port, hostname, backlog, (err) => {
+        const server = this.transport.server;
+
+        // default router is used if no router is provided
+        if (!this.router) {
+          this.router = getDefaultRouter() as unknown as Routes;
+
+        } else {
+          // make sure default routes are included
+          // https://github.com/Bekacru/better-call/pull/67
+          this.router = this.router.extend({ ...getDefaultRouter().endpoints }) as unknown as Routes;
+        }
+
+        if (server) {
+          server.on('error', (err) => reject(err));
+          bindRouterToServer(server, this.router);
+        }
+
+        if (listeningListener) {
+          listeningListener(err);
+        }
+
+        if (err) {
+          reject(err);
+
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Define a new type of room for matchmaking.
+   *
+   * @param name public room identifier for match-making.
+   * @param roomClass Room class definition
+   * @param defaultOptions default options for `onCreate`
+   */
+  public define<T extends Type<Room>>(
+    roomClass: T,
+    defaultOptions?: OnCreateOptions<T>,
+  ): RegisteredHandler
+  public define<T extends Type<Room>>(
+    name: string,
+    roomClass: T,
+    defaultOptions?: OnCreateOptions<T>,
+  ): RegisteredHandler
+  public define<T extends Type<Room>>(
+    nameOrHandler: string | T,
+    handlerOrOptions: T | OnCreateOptions<T>,
+    defaultOptions?: OnCreateOptions<T>,
+  ): RegisteredHandler {
+    const name = (typeof(nameOrHandler) === "string")
+      ? nameOrHandler
+      : nameOrHandler.name;
+
+    const roomClass = (typeof(nameOrHandler) === "string")
+      ? handlerOrOptions
+      : nameOrHandler;
+
+    const options = (typeof(nameOrHandler) === "string")
+      ? defaultOptions
+      : handlerOrOptions;
+
+    return matchMaker.defineRoomType(name, roomClass, options);
+  }
+
+  /**
+   * Remove a room definition from matchmaking.
+   * This method does not destroy any room. It only dissallows matchmaking
+   */
+  public removeRoomType(name: string): void {
+    matchMaker.removeRoomType(name);
+  }
+
+  public async gracefullyShutdown(exit: boolean = true, err?: Error) {
+    if (matchMaker.state === matchMaker.MatchMakerState.SHUTTING_DOWN) {
+      return;
+    }
+
+    try {
+      // custom "before shutdown" method
+      await this.onBeforeShutdownCallback();
+
+      // this is going to lock all rooms and wait for them to be disposed
+      await matchMaker.gracefullyShutdown();
+
+      this.transport.shutdown();
+      this.presence.shutdown();
+      await this.driver.shutdown();
+
+      // custom "after shutdown" method
+      await this.onShutdownCallback();
+
+    } catch (e) {
+      debugAndPrintError(`error during shutdown: ${e}`);
+
+    } finally {
+      if (exit) {
+        process.exit((err && !isDevMode) ? 1 : 0);
+      }
+    }
+  }
+
+  /**
+   * Add simulated latency between client and server.
+   * @param milliseconds round trip latency in milliseconds.
+   */
+  public simulateLatency(milliseconds: number) {
+    if (milliseconds > 0) {
+      logger.warn(`📶️❗ Colyseus latency simulation enabled → ${milliseconds}ms latency for round trip.`);
+    } else {
+      logger.warn(`📶️❗ Colyseus latency simulation disabled.`);
+    }
+
+    const halfwayMS = (milliseconds / 2);
+    this.transport.simulateLatency(halfwayMS);
+
+    if (this._originalRoomOnMessage == null) {
+      this._originalRoomOnMessage = Room.prototype['_onMessage'];
+    }
+
+    const originalOnMessage = this._originalRoomOnMessage;
+
+    Room.prototype['_onMessage'] = milliseconds <= Number.EPSILON ? originalOnMessage : function (this: Room, client, buffer) {
+      // uWebSockets.js: duplicate buffer because it is cleared at native layer before the timeout.
+      const cachedBuffer = Buffer.from(buffer);
+      setTimeout(() => originalOnMessage.call(this, client, cachedBuffer), halfwayMS);
+    };
+  }
+
+  /**
+   * Register a callback that is going to be executed before the server shuts down.
+   * @param callback
+   */
+  public onShutdown(callback: () => void | Promise<any>) {
+    this.onShutdownCallback = callback;
+  }
+
+  public onBeforeShutdown(callback: () => void | Promise<any>) {
+    this.onBeforeShutdownCallback = callback;
+  }
+
+  protected getDefaultTransport(_: any): Transport {
+    throw new Error("Please provide a 'transport' layer. Default transport not set.");
+  }
+
+  protected onShutdownCallback: () => void | Promise<any> =
+    () => Promise.resolve()
+
+  protected onBeforeShutdownCallback: () => void | Promise<any> =
+    () => Promise.resolve()
+}
+
+export function defineServer<
+  T extends Record<string, RegisteredHandler>,
+  R extends Router
+>(
+  roomHandlers: T,
+  router?: R,
+  serverOptions?: ServerOptions
+): Server<T, R> {
+  const server = new Server<T, R>(serverOptions);
+
+  server.router = router;
+
+  for (const [name, handler] of Object.entries(roomHandlers)) {
+    handler.name = name;
+    matchMaker.addRoomType(handler);
+  }
+
+  return server;
+}
+
+export function defineRoom<T extends Type<Room>>(
+  roomKlass: T,
+  defaultOptions?: Parameters<NonNullable<InstanceType<T>['onCreate']>>[0],
+): RegisteredHandler<T> {
+  return new RegisteredHandler(roomKlass, defaultOptions);
+}

package/src/Stats.ts

@@ -0,0 +1,107 @@
+import { MatchMakerState, presence, processId, state } from './MatchMaker.ts';
+
+export type Stats = {
+  roomCount: number;
+  ccu: number;
+}
+
+export let local: Stats = {
+  roomCount: 0,
+  ccu: 0,
+};
+
+export async function fetchAll() {
+  // TODO: cache this value to avoid querying too often
+  const allStats: Array<Stats & { processId: string }> = [];
+  const allProcesses = await presence.hgetall(getRoomCountKey());
+
+  for (let remoteProcessId in allProcesses) {
+    if (remoteProcessId === processId) {
+      allStats.push({ processId, roomCount: local.roomCount, ccu: local.ccu, });
+
+    } else {
+      const [roomCount, ccu] = allProcesses[remoteProcessId].split(',').map(Number);
+      allStats.push({ processId: remoteProcessId, roomCount, ccu });
+    }
+  }
+
+  return allStats;
+}
+
+let lastPersisted = 0;
+let persistTimeout = undefined;
+const persistInterval = 1000;
+
+export function persist(forceNow: boolean = false) {
+  // skip if shutting down
+  if (state === MatchMakerState.SHUTTING_DOWN) {
+    return;
+  }
+
+  /**
+   * Avoid persisting more than once per second.
+   */
+  const now = Date.now();
+
+  if (forceNow || (now - lastPersisted > persistInterval)) {
+    lastPersisted = now;
+    return presence.hset(getRoomCountKey(), processId, `${local.roomCount},${local.ccu}`);
+
+  } else {
+    clearTimeout(persistTimeout);
+    persistTimeout = setTimeout(persist, persistInterval);
+  }
+}
+
+export function reset(_persist: boolean = true) {
+  local.roomCount = 0;
+  local.ccu = 0;
+
+  if (_persist) {
+    lastPersisted = 0;
+    clearTimeout(persistTimeout);
+    persist();
+  }
+
+  //
+  // Attach local metrics to PM2 (if available)
+  //
+  import('@pm2/io').then((io) => {
+    io.default.metric({ id: 'app/stats/ccu', name: 'ccu', value: () => local.ccu });
+    io.default.metric({ id: 'app/stats/roomcount', name: 'roomcount', value: () => local.roomCount });
+  }).catch(() => { });
+}
+
+export function excludeProcess(_processId: string) {
+  return presence.hdel(getRoomCountKey(), _processId);
+}
+
+export async function getGlobalCCU() {
+  const allStats = await fetchAll();
+  return allStats.reduce((prev, next) => prev + next.ccu, 0);
+}
+
+/**
+ * Auto-persist every minute.
+ */
+let autoPersistInterval = undefined;
+
+export function setAutoPersistInterval() {
+  const interval = 60 * 1000;// 1 minute
+
+  autoPersistInterval = setInterval(() => {
+    const now = Date.now();
+
+    if (now - lastPersisted > interval) {
+      persist();
+    }
+  }, interval);
+}
+
+export function clearAutoPersistInterval() {
+  clearInterval(autoPersistInterval);
+}
+
+function getRoomCountKey() {
+  return 'roomcount';
+}

package/src/Transport.ts

@@ -0,0 +1,207 @@
+import * as http from 'http';
+import * as https from 'https';
+
+import { StateView } from '@colyseus/schema';
+import { EventEmitter } from 'events';
+import { spliceOne } from './utils/Utils.ts';
+import { ServerError } from './errors/ServerError.ts';
+import { ErrorCode } from './Protocol.ts';
+import type { Room } from './Room.ts';
+
+export abstract class Transport {
+    public protocol?: string;
+    public server?: http.Server | https.Server;
+
+    public abstract listen(port?: number, hostname?: string, backlog?: number, listeningListener?: Function): this;
+    public abstract shutdown(): void;
+
+    public abstract simulateLatency(milliseconds: number): void;
+}
+
+export type AuthContext = {
+  token?: string,
+  headers: Headers,
+  ip: string | string[];
+  // FIXME: each transport may have its own specific properties.
+  // "req" only applies to WebSocketTransport.
+  req?: any;
+};
+
+export interface ISendOptions {
+  afterNextPatch?: boolean;
+}
+
+export const ClientState = { JOINING: 0, JOINED: 1, RECONNECTED: 2, LEAVING: 3, CLOSED: 4 } as const;
+export type ClientState = (typeof ClientState)[keyof typeof ClientState];
+
+// Helper types to extract properties from the Client type parameter
+type ExtractClientUserData<T> = T extends { userData: infer U } ? U : T;
+type ExtractClientAuth<T> = T extends { auth: infer A } ? A : any;
+type ExtractClientMessages<T> = T extends { messages: infer M } ? M : any;
+
+// Helper type to make message required when the message type demands it
+export type MessageArgs<M, Options> =
+  unknown extends M ? [message?: M, options?: Options] :  // Handle 'any' type (backwards compatibility)
+  [M] extends [never] ? [message?: M, options?: Options] :
+  [M] extends [void] ? [message?: M, options?: Options] :
+  [M] extends [undefined] ? [message?: M, options?: Options] :
+  undefined extends M ? [message?: M, options?: Options] :
+  [message: M, options?: Options];
+
+/**
+ * The client instance from the server-side is responsible for the transport layer between the server and the client.
+ * It should not be confused with the Client from the client-side SDK, as they have completely different purposes!
+ * You operate on client instances from `this.clients`, `Room#onJoin()`, `Room#onLeave()` and `Room#onMessage()`.
+ *
+ * - This is the raw WebSocket connection coming from the `ws` package. There are more methods available which aren't
+ *  encouraged to use along with Colyseus.
+ */
+export interface Client<T extends { userData?: any, auth?: any, messages?: Record<string | number, any> } = any> {
+  '~messages': ExtractClientMessages<T>;
+
+  ref: EventEmitter;
+
+  /**
+   * @deprecated use `sessionId` instead.
+   */
+  id: string;
+
+  /**
+   * Unique id per session.
+   */
+  sessionId: string; // TODO: remove sessionId on version 1.0.0
+
+  /**
+   * Connection state
+   */
+  state: ClientState;
+
+  /**
+   * Optional: when using `@view()` decorator in your state properties, this will be the view instance for this client.
+   */
+  view?: StateView;
+
+  /**
+   * User-defined data can be attached to the Client instance through this variable.
+   * - Can be used to store custom data about the client's connection. userData is not synchronized with the client,
+   * and should be used only to keep player-specific with its connection.
+   */
+  userData?: ExtractClientUserData<T>;
+
+  /**
+   * auth data provided by your `onAuth`
+   */
+  auth?: ExtractClientAuth<T>;
+
+  /**
+   * Reconnection token used to re-join the room after onLeave + allowReconnection().
+   *
+   * IMPORTANT:
+   *    This is not the full reconnection token the client provides for the server.
+   *    The format provided by .reconnect() from the client-side must follow: "${roomId}:${reconnectionToken}"
+   */
+  reconnectionToken: string;
+
+  // TODO: move these to ClientPrivate
+  raw(data: Uint8Array | Buffer, options?: ISendOptions, cb?: (err?: Error) => void): void;
+  enqueueRaw(data: Uint8Array | Buffer, options?: ISendOptions): void;
+
+  /**
+   * Send a type of message to the client. Messages are encoded with MsgPack and can hold any
+   * JSON-serializable data structure.
+   *
+   * @param type String or Number identifier the client SDK will use to receive this message
+   * @param message Message payload. (automatically encoded with msgpack.)
+   * @param options
+   */
+  send<K extends keyof this['~messages']>(
+    type: K,
+    ...args: MessageArgs<this['~messages'][K], ISendOptions>
+  ): void;
+
+  /**
+   * Send raw bytes to this specific client.
+   *
+   * @param type String or Number identifier the client SDK will use to receive this message
+   * @param bytes Raw byte array payload
+   * @param options
+   */
+  sendBytes(type: string | number, bytes: Buffer | Uint8Array, options?: ISendOptions): void;
+
+  /**
+   * Disconnect this client from the room.
+   *
+   * @param code Custom close code. Default value is 1000.
+   * @param data
+   * @see [Leave room](https://docs.colyseus.io/room#leave-room)
+   */
+  leave(code?: number, data?: string): void;
+
+  /**
+   * @deprecated Use .leave() instead.
+   */
+  close(code?: number, data?: string): void;
+
+  /**
+   * Triggers `onError` with specified code to the client-side.
+   *
+   * @param code
+   * @param message
+   */
+  error(code: number, message?: string): void;
+}
+
+/**
+ * Private properties of the Client instance.
+ * Only accessible internally by the framework, should not be encouraged/auto-completed for the user.
+ *
+ * TODO: refactor this.
+ * @private
+ */
+export interface ClientPrivate {
+  readyState: number; // TODO: remove readyState on version 1.0.0. Use only "state" instead.
+  _enqueuedMessages?: any[];
+  _afterNextPatchQueue: Array<[string | number | Client, ArrayLike<any>]>;
+  _joinedAt: number; // "elapsedTime" when the client joined the room.
+
+  /**
+   * Used for rate limiting via maxMessagesPerSecond.
+   */
+  _numMessagesLastSecond?: number;
+  _lastMessageTime?: number;
+}
+
+export class ClientArray<C extends Client = Client> extends Array<C> {
+  public getById(sessionId: string): C | undefined {
+    return this.find((client) => client.sessionId === sessionId);
+  }
+
+  public delete(client: C): boolean {
+    return spliceOne(this, this.indexOf(client));
+  }
+}
+
+/**
+ * Shared internal method to connect a Client into a Room.
+ * Validates seat reservation and joins the client to the room.
+ *
+ * @remarks
+ * **⚠️ This is an internal API and not intended for end-user use.**
+ *
+ * @internal
+ */
+export async function connectClientToRoom(
+  room: Room | undefined,
+  client: Client & ClientPrivate,
+  authContext: AuthContext,
+  connectionOptions: {
+    reconnectionToken?: string;
+    skipHandshake?: boolean;
+  },
+): Promise<void> {
+  if (!room || !room.hasReservedSeat(client.sessionId, connectionOptions.reconnectionToken)) {
+    throw new ServerError(ErrorCode.MATCHMAKE_EXPIRED, 'seat reservation expired.');
+  }
+
+  await room['_onJoin'](client, authContext, connectionOptions);
+}