@colyseus/core 0.17.0 → 0.17.1

package/src/matchmaker/controller.ts

@@ -0,0 +1,64 @@
+/**
+ * Matchmaking controller
+ * (for interoperability between different http frameworks, e.g. express, uWebSockets.js, etc)
+ */
+
+import { ErrorCode } from '../Protocol.ts';
+import { ServerError } from '../errors/ServerError.ts';
+import * as matchMaker from '../MatchMaker.ts';
+import type { AuthContext } from '../Transport.ts';
+
+export default {
+  DEFAULT_CORS_HEADERS: {
+    'Access-Control-Allow-Headers': 'Origin, X-Requested-With, Content-Type, Accept, Authorization',
+    'Access-Control-Allow-Methods': 'OPTIONS, POST, GET',
+    'Access-Control-Allow-Credentials': 'true',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Max-Age': '2592000',
+    // ...
+  },
+
+  exposedMethods: ['joinOrCreate', 'create', 'join', 'joinById', 'reconnect'],
+  allowedRoomNameChars: /([a-zA-Z_\-0-9]+)/gi,
+  matchmakeRoute: 'matchmake',
+
+  /**
+   * You can manually change the default corsHeaders by overwriting the `getCorsHeaders()` method:
+   *    ```
+   *    import { matchMaker } from "@colyseus/core";
+   *    matchMaker.controller.getCorsHeaders = function(headers) {
+   *      if (headers.get('referer') !== "xxx") {
+   *      }
+   *
+   *      return {
+   *        'Access-Control-Allow-Origin': 'safedomain.com',
+   *      }
+   *    }
+   *    ```
+   */
+  getCorsHeaders(headers: Headers): { [header: string]: string } {
+    return {
+      ['Access-Control-Allow-Origin']: headers.get("origin") || "*",
+    };
+  },
+
+  async invokeMethod(
+    method: string,
+    roomName: string,
+    clientOptions: matchMaker.ClientOptions = {},
+    authOptions?: AuthContext,
+  ) {
+    if (this.exposedMethods.indexOf(method) === -1) {
+      throw new ServerError(ErrorCode.MATCHMAKE_NO_HANDLER, `invalid method "${method}"`);
+    }
+
+    try {
+      return await matchMaker[method](roomName, clientOptions, authOptions);
+
+    } catch (e: any) {
+      throw new ServerError(e.code || ErrorCode.MATCHMAKE_UNHANDLED, e.message);
+    }
+  }
+
+}
+

package/src/matchmaker/driver.ts

@@ -0,0 +1,191 @@
+import type { Room } from "@colyseus/core";
+
+/**
+ * Sort options for room queries.
+ */
+export interface SortOptions {
+  [fieldName: string]: 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
+}
+
+/**
+ * Built-in room cache fields that can be used for sorting.
+ */
+export type IRoomCacheSortByKeys = 'clients' | 'maxClients' | 'createdAt';
+
+/**
+ * Built-in room cache fields that can be used for filtering.
+ */
+export type IRoomCacheFilterByKeys = 'clients' | 'maxClients' | 'processId';
+
+/**
+ * Extract metadata type from Room type
+ */
+export type ExtractMetadata<RoomType extends Room> = RoomType['~metadata'];
+
+/**
+ * Generates a unique lock ID based on filter options.
+ */
+export function getLockId(filterOptions: any) {
+  return Object.keys(filterOptions).map((key) => `${key}:${filterOptions[key]}`).join("-");
+}
+
+/**
+ * Initialize a room cache which contains CRUD operations for room listings.
+ *
+ * @internal
+ * @param initialValues - Predefined room properties.
+ * @returns RoomData - New room cache.
+ */
+export function initializeRoomCache(initialValues: Partial<IRoomCache> = {}): IRoomCache {
+  return {
+    clients: 0,
+    maxClients: Infinity,
+    locked: false,
+    private: false,
+    metadata: undefined,
+    createdAt: (initialValues && initialValues.createdAt) ? new Date(initialValues.createdAt) : new Date(),
+    unlisted: false,
+    ...initialValues,
+  } as IRoomCache;
+}
+
+export interface IRoomCache<Metadata = any> {
+  /**
+   * Room name.
+   */
+  name: string;
+
+  /**
+   * Unique identifier for the room.
+   */
+  roomId: string;
+
+  /**
+   * Process id where the room is running.
+   */
+  processId: string;
+
+  /**
+   * Number of clients connected to this room.
+   */
+  clients: number;
+
+  /**
+   * Maximum number of clients allowed to join the room.
+   */
+  maxClients: number;
+
+  /**
+   * Indicates if the room is locked (i.e. join requests are rejected).
+   */
+  locked?: boolean;
+
+  /**
+   * Indicates if the room is private
+   * Private rooms can't be joined via `join()` or `joinOrCreate()`.
+   */
+  private?: boolean;
+
+  /**
+   * Public address of the server.
+   */
+  publicAddress?: string;
+
+  /**
+   * Do not show this room in lobby listing.
+   */
+  unlisted?: boolean;
+
+  /**
+   * Metadata associated with the room.
+   */
+  metadata?: Metadata;
+
+  /**
+   * When the room was created.
+   */
+  createdAt?: Date;
+}
+
+export interface MatchMakerDriver {
+  /**
+   * Check if a room exists in room cache.
+   *
+   * @param roomId - The room id.
+   *
+   * @returns Promise<boolean> | boolean - A promise or a boolean value indicating if the room exists.
+   */
+  has(roomId: string): Promise<boolean> | boolean;
+
+  /**
+   * Query rooms in room cache for given conditions.
+   *
+   * @param conditions - Filtering conditions.
+   *
+   * @returns Promise<IRoomCache[]> | IRoomCache[] - A promise or an object contaning room metadata list.
+   */
+  query<T extends Room = any>(
+    conditions: Partial<IRoomCache & ExtractMetadata<T>>,
+    sortOptions?: SortOptions
+  ): Promise<Array<IRoomCache<ExtractMetadata<T>>>> | Array<IRoomCache<ExtractMetadata<T>>>;
+
+  /**
+   * Clean up rooms in room cache by process id.
+   * @param processId - The process id.
+   */
+  cleanup?(processId: string): Promise<void>;
+
+  /**
+   * Query for a room in room cache for given conditions.
+   *
+   * @param conditions - Filtering conditions.
+   *
+   * @returns `IRoomCache` - An object contaning filtered room metadata.
+   */
+  findOne<T extends Room = any>(
+    conditions: Partial<IRoomCache & ExtractMetadata<T>>,
+    sortOptions?: SortOptions
+  ): Promise<IRoomCache<ExtractMetadata<T>>>;
+
+  /**
+   * Remove a room from room cache.
+   *
+   * @param roomId - The room id.
+   */
+  remove(roomId: string): Promise<boolean> | boolean;
+
+  /**
+   * Update a room in room cache.
+   *
+   * @param IRoomCache - The room to update.
+   * @param operations - The operations to update the room.
+   */
+  update(
+    room: IRoomCache,
+    operations: Partial<{ $set: Partial<IRoomCache>, $inc: Partial<IRoomCache> }>
+  ): Promise<boolean> | boolean;
+
+  /**
+   * Persist a room in room cache.
+   *
+   * @param room - The room to persist.
+   * @param create - If true, create a new record. If false (default), update existing record.
+   */
+  persist(room: IRoomCache, create?: boolean): Promise<boolean> | boolean;
+
+  /**
+   * Empty the room cache. Used for testing purposes only.
+   * @internal Do not call this method yourself.
+   */
+  clear(): void;
+
+  /**
+   * Boot the room cache medium (if available).
+   */
+  boot?(): Promise<void>;
+
+  /**
+   * Dispose the connection of the room cache medium.
+   */
+  shutdown(): void;
+}

package/src/presence/LocalPresence.ts

@@ -0,0 +1,331 @@
+
+import { EventEmitter } from 'events';
+import { spliceOne } from '../utils/Utils.ts';
+import type { Presence } from './Presence.ts';
+
+import { hasDevModeCache, isDevMode, getDevModeCache, writeDevModeCache } from '../utils/DevMode.ts';
+
+type Callback = (...args: any[]) => void;
+
+export class LocalPresence implements Presence {
+    public subscriptions = new EventEmitter();
+
+    public data: {[roomName: string]: string[]} = {};
+    public hash: {[roomName: string]: {[key: string]: string}} = {};
+
+    public keys: {[name: string]: string | number} = {};
+
+    private timeouts: {[name: string]: NodeJS.Timeout} = {};
+
+    constructor() {
+      //
+      // reload from local cache on devMode
+      //
+      if (
+        isDevMode &&
+        hasDevModeCache()
+      ) {
+        const cache = getDevModeCache();
+        if (cache.data) { this.data = cache.data; }
+        if (cache.hash) { this.hash = cache.hash; }
+        if (cache.keys) { this.keys = cache.keys; }
+      }
+    }
+
+    public subscribe(topic: string, callback: (...args: any[]) => void) {
+        this.subscriptions.on(topic, callback);
+        return Promise.resolve(this);
+    }
+
+    public unsubscribe(topic: string, callback?: Callback) {
+        if (callback)  {
+            this.subscriptions.removeListener(topic, callback);
+
+        } else {
+            this.subscriptions.removeAllListeners(topic);
+        }
+
+        return this;
+    }
+
+    public publish(topic: string, data: any) {
+        this.subscriptions.emit(topic, data);
+        return this;
+    }
+
+    public async channels (pattern?: string) {
+      let eventNames = this.subscriptions.eventNames() as string[];
+      if (pattern) {
+        //
+        // This is a limited glob pattern to regexp implementation.
+        // If needed, we can use a full implementation like picomatch: https://github.com/micromatch/picomatch/
+        //
+        const regexp = new RegExp(
+          pattern.
+            replaceAll(".", "\\.").
+            replaceAll("$", "\\$").
+            replaceAll("*", ".*").
+            replaceAll("?", "."),
+          "i"
+        );
+        eventNames = eventNames.filter((eventName) => regexp.test(eventName));
+      }
+      return eventNames;
+    }
+
+    public async exists(key: string): Promise<boolean> {
+        return (
+          this.keys[key] !== undefined ||
+          this.data[key] !== undefined ||
+          this.hash[key] !== undefined
+        );
+    }
+
+    public set(key: string, value: string) {
+        this.keys[key] = value;
+    }
+
+    public setex(key: string, value: string, seconds: number) {
+        this.keys[key] = value;
+        this.expire(key, seconds);
+    }
+
+    public expire(key: string, seconds: number) {
+        // ensure previous timeout is clear before setting another one.
+        if (this.timeouts[key]) {
+            clearTimeout(this.timeouts[key]);
+        }
+        this.timeouts[key] = setTimeout(() => {
+            delete this.keys[key];
+            delete this.timeouts[key];
+        }, seconds * 1000);
+    }
+
+    public get(key: string) {
+        return this.keys[key];
+    }
+
+    public del(key: string) {
+        delete this.keys[key];
+        delete this.data[key];
+        delete this.hash[key];
+    }
+
+    public sadd(key: string, value: any) {
+        if (!this.data[key]) {
+            this.data[key] = [];
+        }
+
+        if (this.data[key].indexOf(value) === -1) {
+            this.data[key].push(value);
+        }
+    }
+
+    public async smembers(key: string): Promise<string[]> {
+        return this.data[key] || [];
+    }
+
+    public async sismember(key: string, field: string) {
+        return this.data[key] && this.data[key].includes(field) ? 1 : 0;
+    }
+
+    public srem(key: string, value: any) {
+        if (this.data[key]) {
+            spliceOne(this.data[key], this.data[key].indexOf(value));
+        }
+    }
+
+    public scard(key: string) {
+        return (this.data[key] || []).length;
+    }
+
+    public async sinter(...keys: string[]) {
+      const intersection: {[value: string]: number} = {};
+
+      for (let i = 0, l = keys.length; i < l; i++) {
+        (await this.smembers(keys[i])).forEach((member) => {
+          if (!intersection[member]) {
+            intersection[member] = 0;
+          }
+
+          intersection[member]++;
+        });
+      }
+
+      return Object.keys(intersection).reduce((prev, curr) => {
+        if (intersection[curr] > 1) {
+          prev.push(curr);
+        }
+        return prev;
+      }, []);
+    }
+
+    public hset(key: string, field: string, value: string) {
+        if (!this.hash[key]) { this.hash[key] = {}; }
+        this.hash[key][field] = value;
+        return Promise.resolve(true);
+    }
+
+    public hincrby(key: string, field: string, incrBy: number) {
+        if (!this.hash[key]) { this.hash[key] = {}; }
+        let value = Number(this.hash[key][field] || '0');
+        value += incrBy;
+        this.hash[key][field] = value.toString();
+        return Promise.resolve(value);
+    }
+
+    public hincrbyex(key: string, field: string, incrBy: number, expireInSeconds: number) {
+        if (!this.hash[key]) { this.hash[key] = {}; }
+        let value = Number(this.hash[key][field] || '0');
+        value += incrBy;
+        this.hash[key][field] = value.toString();
+
+        //
+        // FIXME: delete only hash[key][field]
+        // (we can't use "HEXPIRE" in Redis because it's only available since Redis version 7.4.0+)
+        //
+        if (this.timeouts[key]) {
+          clearTimeout(this.timeouts[key]);
+        }
+        this.timeouts[key] = setTimeout(() => {
+            delete this.hash[key];
+            delete this.timeouts[key];
+        }, expireInSeconds * 1000);
+
+        return Promise.resolve(value);
+    }
+
+    public async hget(key: string, field: string) {
+        return (typeof(this.hash[key]) === 'object')
+          ? this.hash[key][field] ?? null
+          : null;
+    }
+
+    public async hgetall(key: string) {
+        return this.hash[key] || {};
+    }
+
+    public hdel(key: string, field: any) {
+        const success = this.hash?.[key]?.[field] !== undefined;
+        if (success) {
+            delete this.hash[key][field];
+        }
+        return Promise.resolve(success);
+    }
+
+    public async hlen(key: string) {
+        return this.hash[key] && Object.keys(this.hash[key]).length || 0;
+    }
+
+    public async incr(key: string) {
+        if (!this.keys[key]) {
+            this.keys[key] = 0;
+        }
+        (this.keys[key] as number)++;
+        return Promise.resolve(this.keys[key] as number);
+    }
+
+    public async decr(key: string) {
+        if (!this.keys[key]) {
+            this.keys[key] = 0;
+        }
+        (this.keys[key] as number)--;
+        return Promise.resolve(this.keys[key] as number);
+    }
+
+    public llen(key: string) {
+      return Promise.resolve((this.data[key] && this.data[key].length) || 0);
+    }
+
+    public rpush(key: string, ...values: string[]): Promise<number> {
+      if (!this.data[key]) { this.data[key] = []; }
+
+      let lastLength: number = 0;
+
+      values.forEach(value => {
+        lastLength = this.data[key].push(value);
+      });
+
+      return Promise.resolve(lastLength);
+    }
+
+    public lpush(key: string, ...values: string[]): Promise<number> {
+      if (!this.data[key]) { this.data[key] = []; }
+
+      let lastLength: number = 0;
+
+      values.forEach(value => {
+        lastLength = this.data[key].unshift(value);
+      });
+
+      return Promise.resolve(lastLength);
+    }
+
+    public lpop(key: string): Promise<string> {
+      return Promise.resolve(Array.isArray(this.data[key])
+        ? this.data[key].shift()
+        : null);
+    }
+
+    public rpop(key: string): Promise<string | null> {
+      return Promise.resolve(this.data[key].pop());
+    }
+
+    public brpop(...args: [...keys: string[], timeoutInSeconds: number]): Promise<[string, string] | null> {
+      const keys = args.slice(0, -1) as string[];
+      const timeoutInSeconds = args[args.length - 1] as number;
+
+      const getFirstPopulated = (): [string, string] | null => {
+        const keyWithValue = keys.find(key => this.data[key] && this.data[key].length > 0);
+        if (keyWithValue) {
+          return [keyWithValue, this.data[keyWithValue].pop()];
+        } else {
+          return null;
+        }
+      }
+
+      const firstPopulated = getFirstPopulated();
+
+      if (firstPopulated) {
+        // return first populated key + item
+        return Promise.resolve(firstPopulated);
+
+      } else {
+        // 8 retries per second
+        const maxRetries = timeoutInSeconds * 8;
+
+        let tries = 0;
+        return new Promise((resolve) => {
+          const interval = setInterval(() => {
+            tries++;
+
+            const firstPopulated = getFirstPopulated();
+            if (firstPopulated) {
+              clearInterval(interval);
+              return resolve(firstPopulated);
+
+            } else if (tries >= maxRetries) {
+              clearInterval(interval);
+              return resolve(null);
+            }
+
+          }, (timeoutInSeconds * 1000) / maxRetries);
+        });
+      }
+    }
+
+    public setMaxListeners(number: number) {
+      this.subscriptions.setMaxListeners(number);
+    }
+
+    public shutdown() {
+      if (isDevMode) {
+        writeDevModeCache({
+          data: this.data,
+          hash: this.hash,
+          keys: this.keys
+        });
+      }
+    }
+
+}