@colyseus/core 0.17.44 → 0.18.1

package/src/Server.ts

@@ -14,7 +14,7 @@ import type { Presence } from "./presence/Presence.ts";
 import { setTransport, Transport } from './Transport.ts';
 import { logger, setLogger } from './Logger.ts';
 import { setDevMode, isDevMode } from './utils/DevMode.ts';
-import { type Router, bindRouterToTransport } from './router/index.ts';
+import { type Router, bindRouterToTransport, createRouter } from './router/index.ts';
 import { prereadRequestBodies } from './router/node.ts';
 import { type SDKTypes as SharedSDKTypes } from '@colyseus/shared-types';
 import { getDefaultRouter } from './router/default_routes.ts';
@@ -33,6 +33,29 @@ export type ServerOptions = {
    */
   beforeListen?: () => Promise<void> | void,
 
+  /**
+   * Booted before `matchMaker.accept()`. Structural so `@colyseus/core` keeps
+   * no runtime dep on `@colyseus/database` — any `{ boot(): Promise<void> }`
+   * works. The optional `applyRouterDefaults` is invoked after boot with the
+   * user's router so the database can contribute endpoints (e.g. auth routes).
+   */
+  database?: {
+    boot(): Promise<void>;
+    applyRouterDefaults?(router: Router): Router | Promise<Router>;
+  },
+
+  /**
+   * Mount `@colyseus/auth` routes into the router. Pass an options object
+   * (forwarded to `auth.endpoints(...)`) to wire it explicitly — useful when
+   * `database` is not in use. `false` disables auto-mounting even if a
+   * `database` is present and would have provided defaults.
+   */
+  auth?: false | {
+    settings?: Record<string, any>;
+    oauth?: boolean | { cookieSecret?: string };
+    prefix?: string;
+  },
+
   /**
    * Optional callback to configure Express routes.
    * When provided, the transport layer will initialize an Express-compatible app
@@ -104,6 +127,12 @@ export class Server<
 
   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
+  // explicitly.
+  static current: Server<any, any> | undefined;
+
   constructor(options: ServerOptions = {}) {
     const {
       gracefullyShutdown = true,
@@ -115,6 +144,8 @@ export class Server<
     this.options = options;
     this.greet = greet;
 
+    (Server as { current: Server<any, any> | undefined }).current = this as Server<any, any>;
+
     this.attach(options);
 
     // Pass options.presence/driver through as-is (possibly undefined).
@@ -141,14 +172,8 @@ export class Server<
 
   public async attach(options: ServerOptions) {
     this.transport = options.transport || await this.getDefaultTransport(options);
-
-    // Initialize Express if callback is provided
-    if (options.express && this.transport.getExpressApp) {
-      const expressApp = await this.transport.getExpressApp();
-      await options.express(expressApp);
-    }
-
-    // Resolve the promise when the transport is ready
+    // `options.express` runs in `listen()` after `database.boot()` so user
+    // code reading `database.auth.settings` etc. finds services instantiated.
     this._onTransportReady.resolve(this.transport);
   }
 
@@ -161,9 +186,7 @@ export class Server<
    * @param listeningListener
    */
   public async listen(port: number | string, hostname?: string, backlog?: number, listeningListener?: Function) {
-    if (this.options.beforeListen) {
-      await this.options.beforeListen();
-    }
+    await this._bootServices();
 
     //
     // if Colyseus Cloud is detected, use @colyseus/tools to listen
@@ -254,9 +277,7 @@ export class Server<
    * ```
    */
   public async serverless(): Promise<HttpServer> {
-    if (this.options.beforeListen) {
-      await this.options.beforeListen();
-    }
+    await this._bootServices();
 
     // transport (and its HTTP server) must be ready before binding routes
     await this._onTransportReady;
@@ -419,6 +440,52 @@ export class Server<
     this.onBeforeShutdownCallback = callback;
   }
 
+  // Boot sequence shared by listen() and serverless(): user `beforeListen`
+  // hook, database boot, framework router defaults (auth/db endpoints), then
+  // the express app. serverless() needs this too — its exported server still
+  // serves the express callback and auth/database routes.
+  private async _bootServices(): Promise<void> {
+    const { beforeListen, database, express } = this.options;
+
+    if (beforeListen) { await beforeListen(); }
+    if (database) { await database.boot(); }
+
+    await this._applyRouterDefaults();
+
+    if (express) {
+      await this._onTransportReady;
+      if (this.transport.getExpressApp) {
+        const expressApp = await this.transport.getExpressApp();
+        await express(expressApp);
+      }
+    }
+  }
+
+  // Extend the user's router with framework-contributed endpoints. An explicit
+  // `auth` option wins over the database's `applyRouterDefaults` so a non-DB
+  // setup can still auto-mount @colyseus/auth, and a DB user can opt out.
+  private async _applyRouterDefaults(): Promise<void> {
+    const { auth, database } = this.options;
+    const wantsAuth = auth !== undefined && auth !== false;
+    const wantsDatabase = auth === undefined && !!database?.applyRouterDefaults;
+    if (!wantsAuth && !wantsDatabase) { return; }
+
+    // Boot an empty router if the user didn't pass `routes` — the framework's
+    // default routes get layered on later in the `transport.listen()` callback.
+    this.router ??= createRouter({}) as unknown as Routes;
+
+    if (wantsAuth) {
+      const authMod: any = await dynamicImport('@colyseus/auth').catch(() => undefined);
+      const endpointsFn = authMod?.auth?.endpoints ?? authMod?.default?.auth?.endpoints;
+      if (typeof endpointsFn === 'function') {
+        this.router = (this.router as Router).extend(endpointsFn(auth)) as Routes;
+      }
+    } else {
+      const updated = await database!.applyRouterDefaults!(this.router as Router);
+      if (updated) { this.router = updated as Routes; }
+    }
+  }
+
   protected async getDefaultTransport(options: any): Promise<Transport> {
     try {
       const module = await dynamicImport('@colyseus/ws-transport');

package/src/Transport.ts

@@ -5,6 +5,7 @@ import type { Router } from '@colyseus/better-call';
 
 import { ErrorCode } from '@colyseus/shared-types';
 import { StateView } from '@colyseus/schema';
+import type { InputDecoder } from '@colyseus/schema/input';
 
 import { EventEmitter } from 'events';
 import { spliceOne } from './utils/Utils.ts';
@@ -18,6 +19,11 @@ export function getTransport() { return _transport; }
 
 export abstract class Transport {
     public protocol?: string;
+    /** Self-signed cert SHA-256 hash (byte array), surfaced to clients in the
+     *  matchmake response so a WebTransport client can pin it via
+     *  `serverCertificateHashes`. Set by transports that generate their own cert
+     *  (h3). Undefined for transports using a CA-trusted cert. */
+    public fingerprint?: number[];
     public server?: http.Server | https.Server;
 
     public abstract listen(port?: number | string, hostname?: string, backlog?: number, listeningListener?: Function): this;
@@ -90,15 +96,10 @@ export interface Client<T extends { userData?: any, auth?: any, messages?: Recor
 
   ref: EventEmitter;
 
-  /**
-   * @deprecated use `sessionId` instead.
-   */
-  id: string;
-
   /**
    * Unique id per session.
    */
-  sessionId: string; // TODO: remove sessionId on version 1.0.0
+  sessionId: string;
 
   /**
    * Connection state
@@ -190,7 +191,6 @@ export interface Client<T extends { userData?: any, auth?: any, messages?: Recor
 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.
 
   /**
@@ -198,15 +198,178 @@ export interface ClientPrivate {
    */
   _numMessagesLastSecond?: number;
   _lastMessageTime?: number;
+
+  /**
+   * Per-client input Schema instance, allocated on join when the Room
+   * declares `input`. Mutated in-place by {@link _inputDecoder} on each
+   * incoming ROOM_INPUT_* packet.
+   *
+   * Typed loosely (`any`) so duplicate `@colyseus/schema` installs don't
+   * trigger type-identity errors against user-defined input classes.
+   */
+  _input?: any;
+  _inputDecoder?: InputDecoder;
+
+  /**
+   * Per-client buffer of cloned input snapshots, allocated on join when
+   * `Room.inputOptions.bufferMaxSize > 0`. Populated on each decoded frame.
+   */
+  _inputBuffer?: import('./input/InputBuffer.ts').InputBufferImpl;
+
+  /**
+   * Cached per-client accessor returned by `room.input(sessionId)`. Built
+   * once at join (when the Room called `defineInput()`), so the public API
+   * call is a Map lookup + property read with no per-call allocation.
+   */
+  _inputAccessor?: import('./input/types.ts').InputAccessor;
+
+  /**
+   * Used for rate limiting ROOM_INPUT_* packets via maxInputsPerSecond,
+   * independent of maxMessagesPerSecond.
+   */
+  _numInputsLastSecond?: number;
+  _lastInputTime?: number;
+
+  /**
+   * `performance.now()` recorded when the most recent ROOM_INPUT_* packet
+   * from this client was received. Drives the per-recipient `lastTReceived`
+   * field of the {@link ProtocolModifier.TIMED} state prefix.
+   *
+   * `0` until the client has sent its first input.
+   */
+  _lastInputReceivedAt?: number;
+
+  /**
+   * Monotonic count of *reliable* inputs successfully received from this
+   * client. Echoed back in the TIMED prefix as `lastInputSeq` so the
+   * client can correlate to its own send-time table and compute RTT.
+   * Stays at the default `0` until the client sends its first reliable
+   * input.
+   *
+   * Only ROOM_INPUT_RELIABLE bumps this — unreliable's redundant-ring
+   * pattern would double-count.
+   */
+  _receivedInputCount?: number;
+
+  /**
+   * Running baseline for the DELTA-CODED lag-comp stamp on ROOM_INPUT_RELIABLE
+   * frames (the {@link ProtocolModifier.TIMED} prefix). Each frame carries only
+   * the signed change from the previous stamp; this accumulates them back into
+   * the absolute timeline value. Zeroed on (re)connect alongside the SDK's own
+   * baseline so the first delta after a reset is absolute. `0` until allocated.
+   */
+  _reckonBaseline?: number;
+
+  /**
+   * @internal Per-client raw frames staged to ride out right AFTER this client's
+   * next state patch — per-client `afterNextPatch` messages. Lazily allocated.
+   * Pushed by {@link enqueueClientRaw} (the `afterNextPatch` path), flushed as
+   * standalone frames after the patch by {@link Room._flushPendingClientFrames}.
+   * Room-level `broadcast` `afterNextPatch` uses the Room's own queue instead, not
+   * this buffer.
+   */
+  _pendingFrames?: Uint8Array[];
+
+  /**
+   * @internal Back-reference to the Room's "clients with staged frames" list,
+   * shared by reference at join. {@link enqueueClientRaw} pushes the client here
+   * on its first staged frame of a cycle, so the after-patch flush iterates just
+   * those clients rather than scanning every client.
+   */
+  _pendingFrameClients?: Array<Client & ClientPrivate>;
+}
+
+/**
+ * The framework-level send path shared by every transport's `enqueueRaw` — the
+ * single source of truth so each transport implements only the wire-level `raw`.
+ * Routes a raw frame by where it should go:
+ *
+ *  - `afterNextPatch` → stage onto the per-client {@link ClientPrivate._pendingFrames}
+ *    buffer, sent as a standalone frame right AFTER the next state patch; a
+ *    no-allocation push into a reused array. The client announces itself to the
+ *    Room's {@link ClientPrivate._pendingFrameClients} list on its first staged
+ *    frame of a cycle.
+ *  - before JOIN → buffer in `_enqueuedMessages` until the JOIN_ROOM handshake flushes.
+ *  - otherwise → send now via the transport's `raw`.
+ *
+ * @internal
+ */
+export function enqueueClientRaw(
+  client: Client & ClientPrivate,
+  data: Uint8Array | Buffer,
+  options?: ISendOptions,
+): void {
+  if (options?.afterNextPatch) {
+    let frames = client._pendingFrames;
+    if (frames === undefined) { frames = client._pendingFrames = []; }
+    if (frames.length === 0) { client._pendingFrameClients?.push(client); } // first frame this cycle
+    frames.push(data);
+    return;
+  }
+  if (client.state !== ClientState.JOINED) {
+    // During `onJoin` / `onReconnect` the client can't register onMessage
+    // handlers yet — buffer until JOIN_ROOM has been sent.
+    client._enqueuedMessages?.push(data);
+    return;
+  }
+  client.raw(data, options);
 }
 
 export class ClientArray<C extends Client = Client> extends Array<C> {
+  /**
+   * Secondary index for O(1) lookup by sessionId. Kept in sync by the
+   * mutating methods overridden below. Direct index assignment
+   * (`arr[i] = client`) and `arr.length = 0` bypass this index — use
+   * `push` / `splice` / `delete` / `pop` / `shift` / `unshift` instead.
+   */
+  private _byId: Map<string, C> = new Map();
+
+  /** The client for `sessionId`, or `undefined` — O(1). The canonical per-session
+   *  lookup (mirrors `room.inputs.get(sessionId)`). */
+  public get(sessionId: string): C | undefined {
+    return this._byId.get(sessionId);
+  }
+
+  /** @deprecated Use {@link get}. */
   public getById(sessionId: string): C | undefined {
-    return this.find((client) => client.sessionId === sessionId);
+    return this._byId.get(sessionId);
   }
 
   public delete(client: C): boolean {
-    return spliceOne(this, this.indexOf(client));
+    const removed = spliceOne(this, this.indexOf(client));
+    if (removed) this._byId.delete(client.sessionId);
+    return removed;
+  }
+
+  public push(...items: C[]): number {
+    for (let i = 0; i < items.length; i++) this._byId.set(items[i].sessionId, items[i]);
+    return super.push(...items);
+  }
+
+  public pop(): C | undefined {
+    const removed = super.pop();
+    if (removed !== undefined) this._byId.delete(removed.sessionId);
+    return removed;
+  }
+
+  public shift(): C | undefined {
+    const removed = super.shift();
+    if (removed !== undefined) this._byId.delete(removed.sessionId);
+    return removed;
+  }
+
+  public unshift(...items: C[]): number {
+    for (let i = 0; i < items.length; i++) this._byId.set(items[i].sessionId, items[i]);
+    return super.unshift(...items);
+  }
+
+  public splice(start: number, deleteCount?: number, ...items: C[]): C[] {
+    const removed = (deleteCount === undefined)
+      ? super.splice(start)
+      : super.splice(start, deleteCount, ...items);
+    for (let i = 0; i < removed.length; i++) this._byId.delete(removed[i].sessionId);
+    for (let i = 0; i < items.length; i++) this._byId.set(items[i].sessionId, items[i]);
+    return removed;
   }
 }
 

package/src/errors/RoomExceptions.ts

@@ -9,7 +9,8 @@ export type RoomMethodName = 'onCreate'
   | 'onReconnect'
   | 'onDispose'
   | 'onMessage'
-  | 'setSimulationInterval'
+  | 'setTimestep'
+  | 'setFixedTimestep'
   | 'setInterval'
   | 'setTimeout';
 
@@ -22,7 +23,7 @@ export type RoomException<R extends Room = Room> =
   OnReconnectException<R> |
   OnDisposeException |
   OnMessageException<R> |
-  SimulationIntervalException |
+  TimestepException |
   TimedEventException;
 
 export class OnCreateException<R extends Room = Room> extends Error {
@@ -151,16 +152,29 @@ export class OnMessageException<R extends Room, MessageType extends keyof R['mes
   }
 }
 
-export class SimulationIntervalException extends Error {
+/** Thrown when a {@link Room.setTimestep} or {@link Room.setFixedTimestep} tick
+ *  callback throws (or rejects). Reported to `onUncaughtException` with the
+ *  originating method as `methodName` (`'setTimestep'` / `'setFixedTimestep'`). */
+export class TimestepException extends Error {
   constructor(
     cause: Error,
     message: string,
   ) {
     super(message, { cause });
-    this.name = 'SimulationIntervalException';
+    this.name = 'TimestepException';
   }
 }
 
+/** 
+ * @deprecated Renamed to {@link TimestepException} (it now covers both
+ * `setTimestep` and `setFixedTimestep`). Kept as an alias for backwards
+ *  compatibility — `instanceof` checks against either name still match. 
+ * 
+ * TODO: remove this on 1.0
+ */
+export const SimulationIntervalException = TimestepException;
+export type SimulationIntervalException = TimestepException;
+
 export class TimedEventException extends Error {
   public args: any[];
   constructor(

package/src/index.ts

@@ -3,16 +3,30 @@ import { ClockTimer as Clock, Delayed } from '@colyseus/timer';
 // Shared types - re-export from @colyseus/shared-types for convenience
 export {
   Protocol,
+  ProtocolModifier,
   ErrorCode,
   CloseCode,
+  ResponseStatus,
   type InferState,
   type ExtractRoomMessages,
   type ExtractRoomClientMessages,
+  type MessageContext,
+  type Rejection,
+  type Resolution,
+  type ExtractRejectReason,
+  type ExtractResponseType,
 } from '@colyseus/shared-types';
 
 // Core classes
 export { Server, defineRoom, defineServer, registerRoomDefinitions, unregisterRoomDefinitions, type RoomDefinitions, type ServerOptions, type SDKTypes } from './Server.ts';
-export { Room, room, RoomInternalState, validate, type RoomOptions, type MessageHandlerWithFormat, type Messages, type ExtractRoomState, type ExtractRoomMetadata, type ExtractRoomClient } from './Room.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';
+export { Rewind, RewindView, type RewindOptions, type RewindMode } from './Rewind.ts';
+export {
+  RoomPlugin, definePlugins, attachToTestRoom,
+  type RoomPluginOrder, type PluginDependencies, type RoomPluginClass,
+} from './RoomPlugin.ts';
 export { getMessageBytes } from './Protocol.ts';
 export { RegisteredHandler } from './matchmaker/RegisteredHandler.ts';
 export { ServerError } from './errors/ServerError.ts';
@@ -26,6 +40,7 @@ export {
   OnLeaveException,
   OnDisposeException,
   OnMessageException,
+  TimestepException,
   SimulationIntervalException,
   TimedEventException,
 } from './errors/RoomExceptions.ts';
@@ -41,7 +56,7 @@ 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';
+export { type Client, type ClientPrivate, type AuthContext, ClientState, ClientArray, Transport, type ISendOptions, connectClientToRoom, enqueueClientRaw } from './Transport.ts';
 
 // Presence
 export { type Presence } from './presence/Presence.ts';
@@ -82,8 +97,10 @@ export {
   createInternalContext,
   createMiddleware,
   createRouter,
+  basicAuth,
+  type BasicAuthOptions,
   toNodeHandler,
-  __globalEndpoints,
+  dualModeEndpoints,
   type Router,
   type RouterConfig,
   type Endpoint,
@@ -91,6 +108,9 @@ export {
   type EndpointOptions,
   type EndpointContext,
   type StrictEndpoint,
+  type ExpressMiddleware,
+  type NodeHandler,
+  type DualModeHelpers,
 } from './router/index.ts';
 
 // Abstract logging support