@colyseus/core 0.17.44 → 0.18.1

package/src/router/default_routes.ts

@@ -36,6 +36,10 @@ export const postMatchmakeMethod = createEndpoint("/matchmake/:method/:roomName"
     if (transport.protocol !== undefined) {
       response.protocol = transport.protocol;
     }
+    // WebTransport (h3): client pins the self-signed cert via serverCertificateHashes.
+    if (transport.fingerprint !== undefined) {
+      response.fingerprint = transport.fingerprint;
+    }
 
     const json = JSON.stringify(response);
 
@@ -57,5 +61,6 @@ export const postMatchmakeMethod = createEndpoint("/matchmake/:method/:roomName"
 });
 
 export function getDefaultRouter() {
-  return createRouter({ postMatchmakeMethod });
+  // no public docs page — the docs surface is playground's gated /__apidocs
+  return createRouter({ postMatchmakeMethod }, { openapi: { disabled: true } });
 }

package/src/router/index.ts

@@ -1,6 +1,7 @@
 import type express from "express";
 import type { IncomingMessage, ServerResponse } from "http";
-import { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint } from "@colyseus/better-call";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint, createMiddleware, APIError } from "@colyseus/better-call";
 import { toNodeHandler, getRequest, setResponse } from "@colyseus/better-call/node";
 import { Transport } from "../Transport.ts";
 import { controller } from "../matchmaker/controller.ts";
@@ -120,19 +121,124 @@ function expressRootRoute(expressApp: express.Application) {
   return stack.find((layer: any) => layer.match('/') && !['query', 'expressInit'].includes(layer.name));
 }
 
-/**
- * Do not use this directly. This is used internally by `@colyseus/playground`.
- * TODO: refactor. Avoid using globals.
- * @internal
- */
-export let __globalEndpoints: Record<string, Endpoint> = {};
-
 export function createRouter<
   E extends Record<string, Endpoint>,
   Config extends RouterConfig
 >(endpoints: E, config: Config = {} as Config) {
-  // TODO: refactor. Avoid using globals.
-  __globalEndpoints = endpoints;
+  return createBetterCallRouter({ ...endpoints }, {
+    // better-call's /api/reference page dumps the full API surface
+    // unauthenticated — opt back in by passing `openapi` explicitly.
+    openapi: { disabled: true },
+    ...config,
+  });
+}
+
+export interface BasicAuthOptions {
+  /** username → password. The common static case. */
+  users?: Record<string, string>;
+  /** Custom validator (e.g. DB-backed). Takes precedence over `users`. */
+  validate?: (username: string, password: string) => boolean | Promise<boolean>;
+  /** Realm shown in the browser prompt. Default 'Restricted'. */
+  realm?: string;
+}
+
+/**
+ * HTTP Basic Auth middleware. Drop into any endpoint's `use:` slot to gate
+ * it behind a browser credentials prompt:
+ *
+ *   playground({ use: [basicAuth({ users: { admin: 's3cret' } })] })
+ */
+export function basicAuth(opts: BasicAuthOptions) {
+  const { users, validate } = opts;
+  if (!users && !validate) {
+    throw new Error('[basicAuth] provide `users` or `validate`');
+  }
+  // Realm is interpolated into a header — strip `"` so it can't break out.
+  const challenge = `Basic realm="${(opts.realm ?? 'Restricted').replace(/"/g, '')}", charset="UTF-8"`;
+
+  return createMiddleware(async (ctx) => {
+    const creds = parseBasicHeader(ctx.getHeader('authorization'));
+    const ok = !!creds && (validate
+      ? await validate(creds.username, creds.password)
+      : staticCheck(users!, creds.username, creds.password));
+    if (!ok) {
+      throw new APIError(401, { message: 'authentication required' }, { 'WWW-Authenticate': challenge });
+    }
+  });
+}
+
+function parseBasicHeader(header: string | null | undefined) {
+  if (!header) { return null; }
+  const sep = header.indexOf(' ');
+  if (sep < 0 || header.slice(0, sep).toLowerCase() !== 'basic') { return null; }
+  let decoded: string;
+  try { decoded = Buffer.from(header.slice(sep + 1), 'base64').toString('utf8'); } catch { return null; }
+  const colon = decoded.indexOf(':');
+  if (colon < 0) { return null; }
+  return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };
+}
+
+function staticCheck(users: Record<string, string>, username: string, password: string): boolean {
+  const expected = Object.prototype.hasOwnProperty.call(users, username) ? users[username] : undefined;
+  // Compare even for an unknown user so reject timing doesn't reveal which
+  // usernames exist.
+  return safeEqual(password, expected ?? '\0') && expected !== undefined;
+}
 
-  return createBetterCallRouter({ ...endpoints }, config);
+// Hash both sides first: equalizes length (timingSafeEqual throws on a
+// length mismatch, which would itself leak the secret's length).
+function safeEqual(a: string, b: string): boolean {
+  return timingSafeEqual(
+    createHash('sha256').update(a).digest(),
+    createHash('sha256').update(b).digest(),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// dualModeEndpoints — shared express-compat layer for @colyseus/admin,
+// @colyseus/monitor, @colyseus/playground. Builds the two local routers
+// (specific = no catch-all, full = everything) and the matching node
+// handlers, then packages the express middleware so the return value works
+// both as `{...spread}` into createRouter AND as `app.use("/", x)` middleware.
+// ---------------------------------------------------------------------------
+
+export type ExpressMiddleware = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next: (err?: any) => void,
+) => void;
+
+export type NodeHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+export interface DualModeHelpers {
+  specificRouter: Router;
+  specificHandler: NodeHandler;
+  fullRouter: Router;
+  fullHandler: NodeHandler;
+}
+
+export function dualModeEndpoints<E extends Record<string, Endpoint>>(
+  endpoints: E,
+  opts: {
+    /** Key in `endpoints` whose path is a catch-all. Excluded from `specificRouter` so it doesn't eat fall-through decisions. */
+    catchAllKey?: keyof E;
+    /** Build the express middleware given the pre-built routers + node handlers. */
+    buildMiddleware: (helpers: DualModeHelpers) => ExpressMiddleware;
+  },
+): ExpressMiddleware & E {
+  const fullRouter = createRouter(endpoints);
+  const fullHandler = toNodeHandler(fullRouter.handler) as NodeHandler;
+
+  const specificEndpoints = opts.catchAllKey
+    ? Object.fromEntries(
+        Object.entries(endpoints).filter(([k]) => k !== opts.catchAllKey),
+      ) as Partial<E>
+    : endpoints;
+  const specificRouter = createRouter(specificEndpoints as E);
+  const specificHandler = toNodeHandler(specificRouter.handler) as NodeHandler;
+
+  const middleware = opts.buildMiddleware({
+    specificRouter, specificHandler, fullRouter, fullHandler,
+  });
+  return Object.assign(middleware, endpoints) as ExpressMiddleware & E;
 }

package/src/serializer/NoneSerializer.ts

@@ -1,16 +1,16 @@
 import type { Client } from '../Transport.ts';
-import type { Serializer } from './Serializer.ts';
+import type { PatchTimingContext, Serializer } from './Serializer.ts';
 
 export class NoneSerializer<T= any> implements Serializer<T> {
   public id: string = 'none';
 
   public reset(data: any) {}
 
-  public getFullState(client?: Client) {
+  public getFullState(_client?: Client, _timing?: PatchTimingContext) {
     return null;
   }
 
-  public applyPatches(clients: Client[], state: T): boolean {
+  public applyPatches(_clients: Client[], _state: T, _timing?: PatchTimingContext): boolean {
     return false;
   }
 }

package/src/serializer/SchemaSerializer.ts

@@ -1,11 +1,85 @@
-import { Protocol } from '@colyseus/shared-types';
+import { Protocol, ProtocolModifier } from '@colyseus/shared-types';
 
-import type { Serializer } from './Serializer.ts';
-import { type Client, ClientState } from '../Transport.ts';
+import type { PatchTimingContext, Serializer } from './Serializer.ts';
+import { type Client, type ClientPrivate, ClientState } from '../Transport.ts';
 
-import { type Iterator, Encoder, dumpChanges, Reflection, Schema, StateView } from '@colyseus/schema';
+import { type Iterator, encode, Encoder, dumpChanges, Reflection, Schema, StateView } from '@colyseus/schema';
 import { debugPatch } from '../Debug.ts';
 
+/**
+ * Size of the {@link ProtocolModifier.TIMED} prefix that follows the
+ * protocol byte:
+ *   `[uint32 sNow][uint32 inputSeq]`
+ *
+ *   - `sNow`     — server clock as **milliseconds since room start**
+ *     (`room.clock.elapsedTime`), NOT raw `performance.now()`. A portable,
+ *     language-agnostic integer (C/C#/Lua have no `performance.now()`); the
+ *     server's own time-keyed logic uses the SAME `clock.elapsedTime` so the
+ *     client's reconstructed `serverNow()` stays in phase. Wraps at u32
+ *     (~49.7 days uptime) — irrelevant per session. Drives the client clock
+ *     offset / `serverNow()`.
+ *   - `inputSeq` — seq VALUE of the last input CONSUMED into the authoritative
+ *     state (the input buffer's `ackSeq`, i.e. last-PROCESSED input). Reliable:
+ *     equals the consumed count (inputs are sequenced implicitly by receive
+ *     order). Unreliable: the framework wire seq, so a fully-dropped input
+ *     doesn't make the ack lag the client's sent seq by the lost count. This
+ *     single number is the canonical reconciliation ack ("the sequence number
+ *     of the last input the server processed"); the client prunes its
+ *     pending-input buffer against it AND derives RTT from its round-trip
+ *     (`now − sendTime(inputSeq)`). No separate received-seq / received-time —
+ *     RTT-from-the-processed-ack is round-trip-inclusive, which is the standard.
+ */
+const TIMED_PREFIX_SIZE = 8;
+
+/**
+ * Construct a per-recipient TIMED buffer:
+ *   `[code|TIMED][sNow][inputSeq][...schema bytes]`
+ *
+ * `encodedBody` is the shared encoded buffer whose byte 0 already holds the
+ * base protocol code (ROOM_STATE or ROOM_STATE_PATCH); bytes 1.. are the
+ * schema payload. We construct a fresh per-client Buffer so the transport
+ * never sees a buffer that might mutate between queue and send.
+ *
+ * Uses the schema `encode.*` helpers to keep the wire layout symmetric with
+ * the SDK's `decode.*`-driven reader.
+ */
+function buildTimedFrame(
+  encodedBody: Uint8Array,
+  sNow: number,
+  inputSeq: number,
+): Buffer {
+  const schemaPayload = encodedBody.subarray(1);
+  const out = Buffer.allocUnsafe(1 + TIMED_PREFIX_SIZE + schemaPayload.length);
+  out[0] = encodedBody[0] | ProtocolModifier.TIMED;
+  const it: Iterator = { offset: 1 };
+  encode.uint32(out, sNow >>> 0, it); // ms since room start (clock.elapsedTime)
+  encode.uint32(out, inputSeq >>> 0, it);
+  out.set(schemaPayload, it.offset);
+  return out;
+}
+
+/** Seq VALUE of the last input consumed from the client's buffer — the
+ *  reconciliation ack (and RTT correlation key). Reliable: equals the consumed
+ *  count; unreliable: the framework wire seq (so packet loss doesn't skew it).
+ *  0 when the room doesn't buffer input. */
+function clientProcessedInputSeq(client: Client): number {
+  return (client as Client & ClientPrivate)._inputBuffer?.ackSeq ?? 0;
+}
+
+/**
+ * Send a per-recipient patch frame: a TIMED-prefixed buffer when `timing` is set,
+ * else the shared `encodedBody` passed straight through (no per-client copy). Any
+ * `afterNextPatch` frames staged on `client._pendingFrames` are NOT coalesced here
+ * — they go out standalone right after the patch via `Room._flushPendingClientFrames`.
+ */
+function sendClientFrame(client: Client, encodedBody: Uint8Array, timing?: PatchTimingContext): void {
+  if (timing) {
+    client.raw(buildTimedFrame(encodedBody, timing.sNow, clientProcessedInputSeq(client)));
+  } else {
+    client.raw(encodedBody);
+  }
+}
+
 const SHARED_VIEW = {};
 
 export class SchemaSerializer<T extends Schema> implements Serializer<T> {
@@ -38,27 +112,29 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
     }
   }
 
-  public getFullState(client?: Client) {
+  public getFullState(client?: Client, timing?: PatchTimingContext) {
     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;
+    const body = (this.hasFilters && client?.view)
+      ? this.encoder.encodeAllView(
+          client.view,
+          this.sharedOffsetCache.offset,
+          { ...this.sharedOffsetCache },
+          this.fullEncodeBuffer
+        )
+      : this.fullEncodeCache;
+
+    if (timing && client) {
+      return buildTimedFrame(body, timing.sNow, clientProcessedInputSeq(client));
     }
+    return body;
   }
 
-  public applyPatches(clients: Client[]) {
+  public applyPatches(clients: Client[], _state?: unknown, timing?: PatchTimingContext) {
     let numClients = clients.length;
 
     if (numClients === 0) {
@@ -92,11 +168,26 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
           this.encoder.sharedBuffer[0] = Protocol.ROOM_STATE_PATCH;
 
           clientsWithViewChange.forEach((client) => {
-            client.raw(this.encoder.encodeView(client.view, sharedOffset, it));
+            const encodedView = this.encoder.encodeView(client.view, sharedOffset, it);
+            sendClientFrame(client, encodedView, timing);
           });
         }
       }
 
+      // Heartbeat: clients that advertised CLIENT_TIMING still need
+      // periodic timing samples to keep their clock offset / RTT estimate
+      // fresh during quiet ticks. Emit a TIMED-prefixed ROOM_STATE_PATCH
+      // with an empty schema body — 1 byte protocol + 12 bytes prefix.
+      // No-op for rooms without `defineInput()` (timing is undefined).
+      if (timing) {
+        const heartbeatBody = Buffer.from([Protocol.ROOM_STATE_PATCH]);
+        for (let i = 0; i < clients.length; i++) {
+          const client = clients[i];
+          if (client.state !== ClientState.JOINED) continue;
+          sendClientFrame(client, heartbeatBody, timing);
+        }
+      }
+
       // skip patching state if:
       // - no clients are connected
       // - no changes were made
@@ -129,7 +220,7 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
           continue;
         }
 
-        client.raw(encodedChanges);
+        sendClientFrame(client, encodedChanges, timing);
       }
 
     } else {
@@ -159,7 +250,7 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
           this.encodedViews.set(view, encodedView);
         }
 
-        client.raw(encodedView);
+        sendClientFrame(client, encodedView, timing);
       }
 
       // clear views

package/src/serializer/Serializer.ts

@@ -1,9 +1,20 @@
 import type { Client } from '../Transport.ts';
 
+/**
+ * Per-tick timing context, populated by the Room when
+ * {@link Room.defineInput} was called. The serializer uses it to emit a
+ * {@link ProtocolModifier.TIMED} prefix for clients that advertised
+ * the {@link HandshakeSection.CLIENT_TIMING} capability.
+ */
+export interface PatchTimingContext {
+  /** `performance.now()` at the moment the patch is being applied. */
+  sNow: number;
+}
+
 export interface Serializer<T> {
   id: string;
   reset(data: any): void;
-  getFullState(client?: Client): Uint8Array;
-  applyPatches(clients: Client[], state: T): boolean;
+  getFullState(client?: Client, timing?: PatchTimingContext): Uint8Array;
+  applyPatches(clients: Client[], state: T, timing?: PatchTimingContext): boolean;
   handshake?(): Uint8Array;
 }

package/src/utils/DevMode.ts

@@ -31,11 +31,24 @@ export async function reloadFromCache() {
   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);
+    let roomHistory: any;
+    let recreatedRoom: Room;
+    let recreatedRoomListing: any;
+
+    try {
+      roomHistory = JSON.parse(value);
+      debugDevMode("restoring room %s (%s)", roomHistory.roomName, roomId);
+
+      recreatedRoomListing = await handleCreateRoom(roomHistory.roomName, roomHistory.clientOptions, roomId);
+      recreatedRoom = getLocalRoomById(recreatedRoomListing.roomId);
+
+    } catch (e: any) {
+      // unrestorable entry (e.g. room type renamed/removed) — drop it
+      // instead of wedging the boot
+      debugAndPrintError(`❌ couldn't restore room '${roomId}':\n${e.stack}`);
+      await presence.hdel(getRoomRestoreListKey(), roomId);
+      continue;
+    }
 
     // Restore previous state
     if (roomHistory.hasOwnProperty("state")) {
@@ -144,14 +157,6 @@ export async function cacheRoomHistory(rooms: { [roomId: string]: Room }) {
   }
 }
 
-export async function getPreviousProcessId(hostname: string = '') {
-  return await presence.hget(getProcessRestoreKey(), hostname);
-}
-
 export function getRoomRestoreListKey() {
   return 'roomhistory';
 }
-
-export function getProcessRestoreKey() {
-  return 'processhistory';
-}