@colyseus/core 0.18.6 → 0.18.8

package/src/Server.ts

@@ -11,7 +11,7 @@ import { Deferred, registerGracefulShutdown, dynamicImport, type Type } from './
 
 import type { Presence } from "./presence/Presence.ts";
 
-import { setTransport, Transport } from './Transport.ts';
+import { getTransport, setTransport, Transport } from './Transport.ts';
 import { logger, setLogger } from './Logger.ts';
 import { setDevMode, isDevMode } from './utils/DevMode.ts';
 import { type Router, bindRouterToTransport, createRouter } from './router/index.ts';
@@ -125,8 +125,6 @@ export class Server<
 
   protected _onTransportReady = new Deferred<Transport>();
 
-  private _originalRoomOnMessage: typeof Room.prototype['_onMessage'] | null = null;
-
   // Implicit default for callers that omit explicit Server reference — e.g.
   // `playground()` reads `Server.current.router.endpoints` at request time.
   // Last-construction wins; multi-server setups should reference instances
@@ -384,7 +382,7 @@ export class Server<
       // this is going to lock all rooms and wait for them to be disposed
       await matchMaker.gracefullyShutdown();
 
-      this.transport.shutdown();
+      this.transport?.shutdown();
       this.presence?.shutdown();
       await this.driver?.shutdown();
 
@@ -403,29 +401,19 @@ export class Server<
 
   /**
    * Add simulated latency between client and server.
+   *
+   * May be called at any time — before or after `listen()`. Also available
+   * via the `COLYSEUS_LATENCY` environment variable (round-trip ms), which
+   * overrides calls made before the server boots.
+   *
    * @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);
-    };
+    // transport may still be resolving (constructor's attach() imports the default one)
+    this._onTransportReady.then(
+      (transport) => applySimulatedLatency(transport, milliseconds),
+      () => {/* missing-transport error already surfaces via attach()/listen() */},
+    );
   }
 
   /**
@@ -447,6 +435,11 @@ export class Server<
   private async _bootServices(): Promise<void> {
     const { beforeListen, database, express } = this.options;
 
+    // boot runs after module evaluation, so the env var wins over
+    // simulateLatency() calls made at the top level of user code
+    const envLatency = parseLatencyEnv();
+    if (envLatency !== undefined) { this.simulateLatency(envLatency); }
+
     if (beforeListen) { await beforeListen(); }
     if (database) { await database.boot(); }
 
@@ -505,6 +498,55 @@ export class Server<
     () => Promise.resolve()
 }
 
+let _originalRoomOnMessage: typeof Room.prototype['_onMessage'] | null = null;
+
+/**
+ * Applies both halves of the round-trip latency simulation: delays the
+ * transport's outgoing messages and the Room's incoming message handling.
+ *
+ * Prefer `server.simulateLatency()` — this is the shared core behind it, the
+ * dev-mode `defineServer()` object and the `COLYSEUS_LATENCY` env var, where
+ * no `Server` instance (or transport, yet) may exist.
+ */
+export function applySimulatedLatency(transport: Transport | undefined, 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);
+  transport?.simulateLatency(halfwayMS);
+
+  if (_originalRoomOnMessage == null) {
+    _originalRoomOnMessage = Room.prototype['_onMessage'];
+  }
+
+  const originalOnMessage = _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);
+  };
+}
+
+/**
+ * Reads the `COLYSEUS_LATENCY` environment variable (round-trip milliseconds).
+ * Returns `undefined` when absent or empty; a non-numeric value warns and is ignored.
+ */
+export function parseLatencyEnv(): number | undefined {
+  const value = process.env.COLYSEUS_LATENCY;
+  if (value === undefined || value === '') { return undefined; }
+
+  const milliseconds = Number(value);
+  if (isNaN(milliseconds)) {
+    logger.warn(`📶️❗ Ignoring COLYSEUS_LATENCY: expected a number of milliseconds, got ${JSON.stringify(value)}.`);
+    return undefined;
+  }
+  return milliseconds;
+}
+
 export type RoomDefinitions = Record<string, RegisteredHandler | Type<Room>>;
 
 function isRegisteredHandler(value: RegisteredHandler | Type<Room>): value is RegisteredHandler {
@@ -562,6 +604,8 @@ export function defineServer<
       options: serverOptions,
       router: routes,
       '~rooms': rooms,
+      // the vite plugin registers the transport before importing user code
+      simulateLatency: (milliseconds: number) => applySimulatedLatency(getTransport(), milliseconds),
     } as unknown as Server<T, R>;
   }
 

package/src/index.ts

@@ -18,7 +18,7 @@ export {
 } from '@colyseus/shared-types';
 
 // Core classes
-export { Server, defineRoom, defineServer, registerRoomDefinitions, unregisterRoomDefinitions, type RoomDefinitions, type ServerOptions, type SDKTypes } from './Server.ts';
+export { Server, defineRoom, defineServer, registerRoomDefinitions, unregisterRoomDefinitions, applySimulatedLatency, parseLatencyEnv, type RoomDefinitions, type ServerOptions, type SDKTypes } from './Server.ts';
 export { Room, RoomInternalState, validate, type RoomOptions, type DefineInputOptions, type SimulationCallback, type FixedTimestepCallback, type StepContext, type MessageHandlerWithFormat, type Messages, type ExtractRoomState, type ExtractRoomMetadata, type ExtractRoomClient } from './Room.ts';
 export { InputBufferImpl, compileSanitizer } from './input/InputBuffer.ts';
 export { type InputAccessor, type InputAPI, type NormalizedInputOptions, type ConsumeOptions, type IdleInput, type IdleContext, type SanitizeInput, type NumericFieldsOf } from './input/types.ts';

package/src/presence/LocalPresence.ts

@@ -10,12 +10,13 @@ type Callback = (...args: any[]) => void;
 export class LocalPresence implements Presence {
     public subscriptions: EventEmitter = new EventEmitter();
 
-    public data: {[roomName: string]: string[]} = {};
-    public hash: {[roomName: string]: {[key: string]: string}} = {};
+    // null-proto: keys are caller-controlled, must never resolve through Object.prototype
+    public data: {[roomName: string]: string[]} = Object.create(null);
+    public hash: {[roomName: string]: {[key: string]: string}} = Object.create(null);
 
-    public keys: {[name: string]: string | number} = {};
+    public keys: {[name: string]: string | number} = Object.create(null);
 
-    private timeouts: {[name: string]: NodeJS.Timeout} = {};
+    private timeouts: {[name: string]: NodeJS.Timeout} = Object.create(null);
 
     constructor() {
       //
@@ -140,7 +141,7 @@ export class LocalPresence implements Presence {
     }
 
     public async sinter(...keys: string[]) {
-      const intersection: {[value: string]: number} = {};
+      const intersection: {[value: string]: number} = Object.create(null);
 
       for (let i = 0, l = keys.length; i < l; i++) {
         (await this.smembers(keys[i])).forEach((member) => {
@@ -161,13 +162,13 @@ export class LocalPresence implements Presence {
     }
 
     public hset(key: string, field: string, value: string) {
-        if (!this.hash[key]) { this.hash[key] = {}; }
+        if (!this.hash[key]) { this.hash[key] = Object.create(null); }
         this.hash[key][field] = value;
         return Promise.resolve(true);
     }
 
     public hincrby(key: string, field: string, incrBy: number) {
-        if (!this.hash[key]) { this.hash[key] = {}; }
+        if (!this.hash[key]) { this.hash[key] = Object.create(null); }
         let value = Number(this.hash[key][field] || '0');
         value += incrBy;
         this.hash[key][field] = value.toString();
@@ -175,7 +176,7 @@ export class LocalPresence implements Presence {
     }
 
     public hincrbyex(key: string, field: string, incrBy: number, expireInSeconds: number) {
-        if (!this.hash[key]) { this.hash[key] = {}; }
+        if (!this.hash[key]) { this.hash[key] = Object.create(null); }
         let value = Number(this.hash[key][field] || '0');
         value += incrBy;
         this.hash[key][field] = value.toString();
@@ -202,7 +203,7 @@ export class LocalPresence implements Presence {
     }
 
     public async hgetall(key: string) {
-        return this.hash[key] || {};
+        return { ...this.hash[key] }; // fresh plain object, like redis
     }
 
     public hdel(key: string, field: any) {

package/src/utils/DevMode.ts

@@ -14,8 +14,14 @@ export function hasDevModeCache() {
   return fs.existsSync(DEVMODE_CACHE_FILE_PATH);
 }
 
+// presence dictionaries are keyed by caller-controlled strings: rebuild them null-proto
+const nullProto = (_: string, value: any) =>
+  (value && typeof value === 'object' && !Array.isArray(value))
+    ? Object.assign(Object.create(null), value)
+    : value;
+
 export function getDevModeCache() {
-  return JSON.parse(fs.readFileSync(DEVMODE_CACHE_FILE_PATH, 'utf8')) || {};
+  return JSON.parse(fs.readFileSync(DEVMODE_CACHE_FILE_PATH, 'utf8'), nullProto) || {};
 }
 
 export function writeDevModeCache(cache: any) {