@colyseus/core 0.18.3 → 0.18.5

package/src/Room.ts

@@ -56,6 +56,9 @@ export {
 
 const DEFAULT_PATCH_RATE = 1000 / 20; // 20fps (50ms)
 const DEFAULT_SIMULATION_INTERVAL = 1000 / 60; // 60fps (16.66ms)
+
+// Shared so the unarmed `_flushUnreliable` call site stays monomorphic.
+const NOOP = () => {};
 const noneSerializer = new NoneSerializer();
 
 /** Shared `enqueueRaw` options routing a frame onto `_pendingFrames` to ride the
@@ -276,6 +279,45 @@ export class Room<T extends RoomOptions = RoomOptions> {
   #_patchRate: number;
   #_patchInterval: NodeJS.Timeout;
 
+  /**
+   * Frequency to flush `@unreliable` state fields, in milliseconds.
+   *
+   * Those fields never ride a state patch — they go out over the transport's
+   * unreliable channel (a WebTransport datagram), so a dropped frame costs one
+   * stale value instead of stalling the reliable stream behind a retransmit.
+   * Setting this decouples them from {@link patchRate}, which is the point:
+   * 60Hz movement over a 20Hz structural patch.
+   *
+   * KNOWN COST of a rate faster than {@link patchRate}: an entity's ADD travels
+   * the reliable channel, so datagrams sent between patches can reference a
+   * refId the client hasn't been told about yet. Those frames are skipped by the
+   * client's decoder — safe (the ref graph can't desync, since `@unreliable` is
+   * primitives-only) but each one logs `"refId" not found`, and that entity's
+   * first value lands one mutation later. Measured at `patchRate/this` reports
+   * per mid-session spawn. Leave this unset and the flush rides
+   * {@link broadcastPatch}, which ships the ADD first and avoids it entirely.
+   *
+   * Requires a transport with a datagram channel — today only
+   * `@colyseus/h3-transport` (WebTransport), which is **experimental**. Every
+   * WebSocket transport lacks one, and those clients are skipped entirely (the
+   * room warns once), so `@unreliable` fields keep their join-time value there.
+   *
+   * @default null — flush alongside every {@link broadcastPatch}, and only when
+   * the state actually declares an `@unreliable` field.
+   */
+  public unreliablePatchRate: number | null = null;
+  #_unreliablePatchRate: number | null = null;
+  #_unreliablePatchInterval: NodeJS.Timeout;
+
+  /**
+   * The unreliable flush, called unconditionally at the end of every
+   * {@link broadcastPatch}. Stays {@link NOOP} unless the state actually
+   * declares an `@unreliable` field, so a room that never uses the channel
+   * pays an empty call the engine inlines away — and there is no second
+   * entry point that could drift from `broadcastPatch()`.
+   */
+  private _flushUnreliable: () => void = NOOP;
+
   /**
    * Maximum number of messages a client can send to the server per second.
    * If a client sends more messages than this, it will be disconnected.
@@ -420,6 +462,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     this.#_state = this.state;
     this.#_autoDispose = this.autoDispose;
     this.#_patchRate = this.patchRate;
+    this.#_unreliablePatchRate = this.unreliablePatchRate;
     this.#_maxClients = this.maxClients;
 
     Object.defineProperties(this, {
@@ -436,6 +479,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
           }
           this._serializer.reset(newState);
           this.#_state = newState;
+          this._armUnreliablePatches();
         },
       },
 
@@ -479,6 +523,15 @@ export class Room<T extends RoomOptions = RoomOptions> {
           }
         },
       },
+
+      unreliablePatchRate: {
+        enumerable: true,
+        get: () => this.#_unreliablePatchRate,
+        set: (milliseconds: number | null) => {
+          this.#_unreliablePatchRate = milliseconds;
+          this._armUnreliablePatches();
+        },
+      },
     });
 
     // set patch interval, now with the setter
@@ -1300,6 +1353,12 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this._inputController !== undefined ? { sNow } : undefined,
     );
 
+    // Flush `@unreliable` fields over the datagram channel, after the reliable
+    // patch so a spawn's ADD is already on the wire when the datagram mutating
+    // it goes out. No-op unless the state declares such a field, and skipped
+    // when `unreliablePatchRate` gave the flush its own timer.
+    this._flushUnreliable();
+
     // Deliver any per-client `afterNextPatch` frames as standalone frames right
     // after the patch (never coalesced into it). Iterates only the clients that
     // staged frames this cycle (`#pendingFrameClients`), never the full list.
@@ -1321,6 +1380,64 @@ export class Room<T extends RoomOptions = RoomOptions> {
     return hasChanges;
   }
 
+  /**
+   * Encode and send the `@unreliable` state fields over each client's
+   * unreliable channel. Those fields never appear in a {@link broadcastPatch}
+   * frame, and clients on a transport without a datagram channel are skipped.
+   *
+   * Driven automatically once the state declares an `@unreliable` field — right
+   * after each {@link broadcastPatch}, or on its own timer when
+   * {@link unreliablePatchRate} is set. Public so a room driving
+   * `broadcastPatch()` by hand can drive this by hand too.
+   */
+  public broadcastUnreliablePatch() {
+    if (!this.state) {
+      return false;
+    }
+    return this._serializer.applyUnreliablePatches?.(this.clients) ?? false;
+  }
+
+  /**
+   * Decide how the unreliable channel is driven — and, for the rooms that never
+   * touch it, decide to not drive it at all. Runs when the state is assigned
+   * (the serializer knows by then whether any `@unreliable` field exists) and
+   * whenever {@link unreliablePatchRate} changes.
+   *
+   * A room whose state declares no `@unreliable` field leaves
+   * {@link _flushUnreliable} at {@link NOOP}, so its patch tick costs exactly
+   * what it did before this feature existed.
+   */
+  private _armUnreliablePatches() {
+    if (this.#_unreliablePatchInterval) {
+      clearInterval(this.#_unreliablePatchInterval);
+      this.#_unreliablePatchInterval = undefined;
+    }
+
+    const armed = this._serializer?.hasUnreliableFields === true;
+    const rate = this.#_unreliablePatchRate;
+    const dedicated = armed && rate !== null && rate !== 0;
+
+    // Default mode flushes from the patch itself rather than an independent
+    // timer of the same period, which would put the datagram ahead of a spawn's
+    // ADD about half the time.
+    const inline = armed && !dedicated;
+
+    this._flushUnreliable = inline
+      ? () => { this.broadcastUnreliablePatch(); }
+      : NOOP;
+
+    if (dedicated) {
+      this.#_unreliablePatchInterval = setInterval(() => this.broadcastUnreliablePatch(), rate);
+
+    } else if (inline && !this.#_patchRate) {
+      // patchRate 0/null means no patch tick to piggyback on.
+      logger.warn(
+        "@colyseus/core: state has @unreliable fields but patchRate is disabled —" +
+        " set `room.unreliablePatchRate` to flush them, or they will never update."
+      );
+    }
+  }
+
   /**
    * Register a message handler for a specific message type.
    * This method is used to handle messages sent by clients to the room.
@@ -1778,7 +1895,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
    * Allow the specified client to reconnect into the room. Must be used inside `onLeave()` method.
    * If seconds is provided, the reconnection is going to be cancelled after the provided amount of seconds.
    *
-   * @param client - The client that is allowed to reconnect into the room.
+   * @param previousClient - The client that is allowed to reconnect into the room.
    * @param seconds - The time in seconds that the client is allowed to reconnect into the room.
    *
    * @returns Deferred<Client> - The differed is a promise like type.
@@ -2078,6 +2195,11 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this.#_patchInterval = undefined;
     }
 
+    if (this.#_unreliablePatchInterval) {
+      clearInterval(this.#_unreliablePatchInterval);
+      this.#_unreliablePatchInterval = undefined;
+    }
+
     if (this._simulationInterval) {
       clearInterval(this._simulationInterval);
       this._simulationInterval = undefined;
@@ -2170,7 +2292,13 @@ export class Room<T extends RoomOptions = RoomOptions> {
     client.ref.removeListener('close', client.ref['onleave']);
 
     // only effectively close connection when "onLeave" is fulfilled
-    this._onLeave(client, closeCode).then(() => (client as any).leave(closeCode, reason));
+    const ref = client.ref;
+    this._onLeave(client, closeCode).then(() => {
+      // skip if a successful reconnection has transplanted a new ref (#950)
+      if (client.ref === ref) {
+        (client as any).leave(closeCode, reason);
+      }
+    });
   }
 
   private async _onLeave(client: ExtractRoomClient<T>, code?: number): Promise<any> {
@@ -2208,14 +2336,27 @@ export class Room<T extends RoomOptions = RoomOptions> {
       }
     }
 
+    //
+    // A successful reconnection has already replaced this client: the replacement
+    // owns the 'leave' accounting from here on.
+    //
+    // This must be checked before looking up `_reconnections`: allowReconnection()
+    // reassigns `previousClient.reconnectionToken` to the replacement's token, so a
+    // late-resuming _onLeave() would otherwise attach a second #_onAfterLeave() to
+    // the replacement's pending reconnection and decrement ccu twice for one join.
+    //
+    // @ts-ignore (client.state may be modified at onLeave())
+    if (client.state === ClientState.RECONNECTED) {
+      return;
+    }
+
     // check for manual "reconnection" flow
     if (this._reconnections[client.reconnectionToken]) {
       this._reconnections[client.reconnectionToken][1].catch(async () => {
         await this.#_onAfterLeave(client, code, method === this.onDrop);
       });
 
-      // @ts-ignore (client.state may be modified at onLeave())
-    } else if (client.state !== ClientState.RECONNECTED) {
+    } else {
       await this.#_onAfterLeave(client, code, method === this.onDrop);
     }
   }

package/src/RoomMessages.ts

@@ -88,7 +88,8 @@ export class RoomMessages {
 
   /** Per-type StandardSchema validators. Public for the same reason as
    *  {@link events} (`onMessageValidators`). */
-  validators: { [type: string]: StandardSchemaV1 } = {};
+  // null-prototype: keyed by client-supplied message type (colyseus/colyseus#951)
+  validators: { [type: string]: StandardSchemaV1 } = Object.create(null);
 
   constructor(room: Room<any>) {
     this.room = room;

package/src/Transport.ts

@@ -8,7 +8,8 @@ import { StateView } from '@colyseus/schema';
 import type { InputDecoder } from '@colyseus/schema/input';
 
 import { EventEmitter } from 'events';
-import { spliceOne } from './utils/Utils.ts';
+import { debugAndPrintError } from './Debug.ts';
+import { getBearerToken, spliceOne } from './utils/Utils.ts';
 import { ServerError } from './errors/ServerError.ts';
 
 import type { Room } from './Room.ts';
@@ -46,12 +47,129 @@ export abstract class Transport {
     public bindRouter?(router: Router): void;
 }
 
+/**
+ * Intercepts an incoming WebSocket upgrade request, before the handshake.
+ *
+ * Return a `Response` to answer the request instead of upgrading it. Return
+ * nothing to upgrade as usual. The handler may be async, and the handshake waits
+ * for it to resolve.
+ *
+ * `context` is the same shape `onAuth()` receives, read-only here: mutating it
+ * does not carry over to `onAuth()`.
+ *
+ * Not supported by `H3Transport`: WebTransport has no upgrade handshake.
+ *
+ * @example
+ * ```typescript
+ * new uWebSocketsTransport({
+ *   beforeUpgrade: async (request, context) => {
+ *     if (await isBanned(context.ip)) {
+ *       return new Response(null, { status: 403 });
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export type BeforeUpgradeHandler = (
+  request: Request,
+  context: Readonly<AuthContext>,
+) => Response | void | Promise<Response | void>;
+
+/**
+ * Invokes a `beforeUpgrade` handler, resolving with the `Response` to send
+ * instead of upgrading, or `undefined` to proceed with the upgrade.
+ *
+ * Every transport goes through here, so a handler written against one keeps
+ * working on the others. Never rejects: uWebSockets.js aborts the process on an
+ * upgrade handler that yields without responding, and on the other transports a
+ * raw socket left behind leaks a connection.
+ *
+ * @internal
+ */
+export async function runBeforeUpgrade(
+  handler: BeforeUpgradeHandler,
+  url: string, // path, optionally including the query string
+  context: AuthContext,
+): Promise<Response | undefined> {
+  let request: Request;
+
+  try {
+    const host = context.headers.get('host') || 'localhost';
+    request = new Request(`http://${host}${url}`, { headers: context.headers });
+
+  } catch (e: any) {
+    // a `Host` header that isn't a valid authority fails to parse as a URL
+    debugAndPrintError(e);
+    return new Response(null, { status: 400 });
+  }
+
+  try {
+    return (await handler(request, context)) ?? undefined;
+
+  } catch (e: any) {
+    debugAndPrintError(e);
+    return new Response(null, { status: 500 });
+  }
+}
+
+/** Headers as the transport has them: uWebSockets.js and Node give a plain record. */
+type RawHeaders = Headers | Record<string, string | undefined>;
+
+const readHeader = (headers: RawHeaders, name: string) =>
+  (headers instanceof Headers) ? headers.get(name) : headers[name];
+
+/**
+ * Builds the context passed to `beforeUpgrade` and `onAuth`.
+ *
+ * Every transport goes through here, so the context is identical everywhere,
+ * down to how the client address is resolved. `headers` is materialized on
+ * first read: a connection nobody inspects pays nothing for the conversion.
+ *
+ * @internal
+ */
+export function createAuthContext(options: {
+  headers: RawHeaders,
+  token?: string | null,
+  remoteAddress?: string,
+  req?: any,
+}): AuthContext {
+  const source = options.headers;
+  let headers: Headers | undefined;
+
+  return {
+    token: options.token ?? getBearerToken(readHeader(source, 'authorization')),
+    ip: resolveClientIp(source, options.remoteAddress),
+    req: options.req,
+    get headers() {
+      return headers ??= (source instanceof Headers)
+        ? source
+        : new Headers(source as Record<string, string>);
+    },
+  };
+}
+
+/**
+ * A single address, resolved the same way on every transport: `x-forwarded-for`
+ * carries the whole proxy chain, and only its first entry is the client.
+ */
+function resolveClientIp(headers: RawHeaders, remoteAddress?: string): string | undefined {
+  // an empty header counts as absent
+  const firstHop = (name: string) => readHeader(headers, name)?.split(',')[0].trim() || undefined;
+
+  return (
+    firstHop('x-real-ip') ??
+    firstHop('x-forwarded-for') ??
+    firstHop('x-client-ip') ??
+    (remoteAddress || undefined)
+  );
+}
+
 export type AuthContext = {
   token?: string,
+  /** Undefined when no proxy header carries it and the transport has no peer address. */
+  ip: string | undefined;
   headers: Headers,
-  ip: string | string[];
-  // FIXME: each transport may have its own specific properties.
-  // "req" only applies to WebSocketTransport.
+  /** Only set on the HTTP matchmaking request, where it is the `Request` itself. */
   req?: any;
 };
 
@@ -136,6 +254,16 @@ export interface Client<T extends { userData?: any, auth?: any, messages?: Recor
   raw(data: Uint8Array | Buffer, options?: ISendOptions, cb?: (err?: Error) => void): void;
   enqueueRaw(data: Uint8Array | Buffer, options?: ISendOptions): void;
 
+  /**
+   * Send raw bytes over the transport's UNRELIABLE channel — no delivery,
+   * ordering, or duplication guarantee. Used for `@unreliable` state patches.
+   *
+   * Absent on transports with no datagram channel (every WebSocket transport).
+   * Its presence IS the capability check — callers feature-detect rather than
+   * reading a separate flag, and skip clients that can't receive.
+   */
+  rawUnreliable?(data: Uint8Array | Buffer, options?: ISendOptions, cb?: (err?: Error) => void): void;
+
   /**
    * Send a type of message to the client. Messages are encoded with MsgPack and can hold any
    * JSON-serializable data structure.

package/src/index.ts

@@ -56,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, enqueueClientRaw } from './Transport.ts';
+export { type Client, type ClientPrivate, type AuthContext, ClientState, ClientArray, Transport, type ISendOptions, type BeforeUpgradeHandler, runBeforeUpgrade, createAuthContext, connectClientToRoom, enqueueClientRaw } from './Transport.ts';
 
 // Presence
 export { type Presence } from './presence/Presence.ts';

package/src/input/RoomInput.ts

@@ -21,6 +21,20 @@ import { debugAndPrintError } from '../Debug.ts';
  */
 const _inputReflectionCache = new WeakMap<Function, Uint8Array>();
 
+/**
+ * Rebuild one `k`-length series of the unreliable stamp block: `newest` is the
+ * absolute anchor, and each wire delta walks one slot older
+ * (`out[i] = out[i+1] − Δ`). Mirrors the SDK's `_writeSeriesDeltas`.
+ */
+function readSeriesDeltas(buffer: Buffer, it: Iterator, k: number, newest: number): number[] {
+  const out = new Array<number>(k);
+  out[k - 1] = newest;
+  for (let i = k - 2; i >= 0; i--) {
+    out[i] = out[i + 1] - decode.number(buffer, it);
+  }
+  return out;
+}
+
 /**
  * Runtime behind {@link InputAPI}. A class, not a per-`define()` object literal:
  * literal (and `defineProperty`) accessors carry their closure identity in the
@@ -272,11 +286,70 @@ export class RoomInput {
   }
 
   /** Decode a `ROOM_INPUT_UNRELIABLE` redundancy ring — each slot carries its
-   *  framework seq (base seq + position) for ring dedupe, no user seqField. */
-  decodeUnreliable(client: ClientPrivate, buffer: Buffer, _modifiers: number): void {
+   *  framework seq (base seq + position) for ring dedupe, no user seqField.
+   *
+   *  With the TIMED bit, a self-contained lag-comp stamp block precedes the ring:
+   *
+   *      [varint k][uint32 newest][varint Δ]×(k−1)
+   *      [uint16 rdNewest][varint Δrd]×(k−1)        ← BOTH mode only
+   *
+   *  One stamp per slot, because a packet carries k inputs sampled at k
+   *  different instants. The anchor is absolute and the deltas never leave the
+   *  packet, so — unlike the reliable channel's running baseline — no amount of
+   *  loss or reordering can desync it, and an input recovered redundantly from a
+   *  later packet still arrives with its own instant. Stamps are paired
+   *  positionally with `decodeAll`'s oldest→newest yields; a `k` that disagrees
+   *  with the decoded slot count means a malformed packet, so the stamps are
+   *  dropped rather than misapplied (inputs still land, read live). */
+  decodeUnreliable(client: ClientPrivate, buffer: Buffer, modifiers: number): void {
     if (!client._inputDecoder) { return; }
+
+    const it: Iterator = { offset: 1 };
+    let stamps: number[] | undefined;
+    let renderDeltas: number[] | undefined;
+
+    if (modifiers & ProtocolModifier.TIMED) {
+      this.#resolveWireModes();
+      try {
+        const k = decode.number(buffer, it);
+        stamps = readSeriesDeltas(buffer, it, k, decode.uint32(buffer, it));
+        // BOTH mode trails the renderDelta series in the same shape, so each
+        // slot keeps the latency term it was actually sampled with.
+        if (this.#stampReckon && this.#stampRender) {
+          renderDeltas = readSeriesDeltas(buffer, it, k, decode.uint16(buffer, it));
+        }
+      } catch (e: any) {
+        debugAndPrintError(e);
+        return;
+      }
+    }
+
+    let i = 0;
     try {
-      client._inputDecoder.decodeAll(buffer.subarray(1), (_inst, seq) => this.capture(client, 0, 0, seq));
+      const count = client._inputDecoder.decodeAll(buffer.subarray(it.offset), (_inst, seq) => {
+        // Positional pairing — `decodeAll` yields oldest→newest, the order the
+        // block was written in.
+        const slot = i++;
+        const stamp = stamps?.[slot] ?? 0;
+        let renderTime = 0, reckonTime = 0;
+        if (stamp > 0) {
+          if (this.#stampReckon && this.#stampRender) {
+            const rd = renderDeltas?.[slot] ?? 0;
+            reckonTime = stamp;
+            renderTime = stamp > rd ? stamp - rd : 0;
+          } else if (this.#stampReckon) {
+            reckonTime = stamp;
+          } else {
+            renderTime = stamp;
+          }
+        }
+        this.capture(client, renderTime, reckonTime, seq);
+      });
+      if (stamps !== undefined && count !== stamps.length) {
+        debugAndPrintError(new Error(
+          `@colyseus/core: unreliable input stamp block declared ${stamps.length} slots, decoded ${count}`
+        ));
+      }
     } catch (e: any) {
       debugAndPrintError(e);
       return;

package/src/matchmaker/driver.ts

@@ -188,9 +188,10 @@ export interface MatchMakerDriver {
 
   /**
    * Empty the room cache. Used for testing purposes only.
+   * May be asynchronous — callers must await it.
    * @internal Do not call this method yourself.
    */
-  clear(): void;
+  clear(): void | Promise<void>;
 
   /**
    * Boot the room cache medium (if available).
@@ -199,6 +200,7 @@ export interface MatchMakerDriver {
 
   /**
    * Dispose the connection of the room cache medium.
+   * May be asynchronous — callers must await it.
    */
-  shutdown(): void;
+  shutdown(): void | Promise<void>;
 }

package/src/router/default_routes.ts

@@ -1,7 +1,7 @@
-import { createEndpoint, createRouter } from "@colyseus/better-call";
+import { createEndpoint } from "@colyseus/better-call";
+import { createRouter } from "./index.ts";
 import * as matchMaker from "../MatchMaker.ts";
-import { getBearerToken } from "../utils/Utils.ts";
-import { getTransport } from "../Transport.ts";
+import { createAuthContext, getTransport } from "../Transport.ts";
 
 export const postMatchmakeMethod = createEndpoint("/matchmake/:method/:roomName", { method: "POST" }, async (ctx) => {
   // do not accept matchmaking requests if already shutting down
@@ -20,12 +20,7 @@ export const postMatchmakeMethod = createEndpoint("/matchmake/:method/:roomName"
       method,
       roomName,
       clientOptions,
-      {
-        token: getBearerToken(ctx.request.headers.get('authorization')),
-        headers: ctx.request.headers,
-        ip: requestHeaders.get('x-forwarded-for') ?? requestHeaders.get('x-client-ip') ?? requestHeaders.get('x-real-ip'),
-        req: ctx.request as any,
-      },
+      createAuthContext({ headers: requestHeaders, req: ctx.request }),
     );
 
     //

package/src/router/index.ts

@@ -146,11 +146,18 @@ export function createRouter<
   E extends Record<string, Endpoint>,
   Config extends RouterConfig
 >(endpoints: E, config: Config = {} as Config) {
+  const onError = config?.onError;
   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,
+    // Otherwise a malformed body is a 500 plus a stack trace on stderr: log
+    // noise any anonymous client can trigger at will. Matched on the message
+    // because `onError` receives no request context to test against.
+    onError: async (error: unknown) => (error instanceof SyntaxError && error.message.includes('JSON'))
+      ? Response.json({ error: 'malformed request body' }, { status: 400 })
+      : await onError?.(error),
   });
 }
 

package/src/router/node.ts

@@ -13,14 +13,28 @@ import * as matchMaker from '../MatchMaker.ts';
 import { setResponse } from '@colyseus/better-call/node';
 import { postMatchmakeMethod } from './default_routes.ts';
 
+/** Matchmaking options are small — the cap only stops unbounded buffering. */
+const MAX_BODY_SIZE = 1024 * 1024;
+
+const badRequest = (status: number, message: string) =>
+  Object.assign(new Error(message), { status });
+
 function readBody(req: http.IncomingMessage): Promise<any> {
   return new Promise((resolve, reject) => {
     let data = '';
 
     req.on('data', (chunk: Buffer | string) => {
       data += chunk.toString();
+      if (data.length > MAX_BODY_SIZE) {
+        reject(badRequest(413, 'request body too large'));
+        req.destroy();
+      }
+    });
+    // JSON.parse throws on a later tick — uncaught here it kills the process.
+    req.on('end', () => {
+      try { resolve(data ? JSON.parse(data) : {}); }
+      catch { reject(badRequest(400, 'malformed JSON body')); }
     });
-    req.on('end', () => resolve(data ? JSON.parse(data) : {}));
     req.on('error', reject);
   });
 }
@@ -112,10 +126,20 @@ export function createNodeMatchmakingMiddleware() {
 
     const [, method, roomName] = match;
 
+    let body: any;
+    try {
+      body = await readBody(req);
+    } catch (e: any) {
+      // answer here — next() would report a misleading 404 for a bad body
+      res.writeHead(e.status ?? 400, { ...corsHeaders, 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: e.message }));
+      return;
+    }
+
     try {
       const response = await postMatchmakeMethod({
         params: { method, roomName },
-        body: await readBody(req),
+        body,
         headers: req.headers as Record<string, string>,
         request: { headers } as any,
         asResponse: true,