@colyseus/core 0.17.43 → 0.18.0

package/build/router/index.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/router/index.ts"],
-  "sourcesContent": ["import type express from \"express\";\nimport type { IncomingMessage, ServerResponse } from \"http\";\nimport { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint } from \"@colyseus/better-call\";\nimport { toNodeHandler, getRequest, setResponse } from \"@colyseus/better-call/node\";\nimport { Transport } from \"../Transport.ts\";\nimport { controller } from \"../matchmaker/controller.ts\";\nimport pkg from \"../../package.json\" with { type: \"json\" };\n\nexport {\n  createEndpoint,\n  createMiddleware,\n  createInternalContext,\n\n  // Re-export types needed for declaration emit\n  type Router,\n  type RouterConfig,\n  type Endpoint,\n  type EndpointHandler,\n  type EndpointOptions,\n  type EndpointContext,\n  type StrictEndpoint,\n} from \"@colyseus/better-call\";\n\nexport { toNodeHandler };\n\nexport function bindRouterToTransport(transport: Transport, router: Router, useExpress: boolean) {\n  // add default \"/__healthcheck\" endpoint\n  router.addEndpoint(createEndpoint(\"/__healthcheck\", { method: \"GET\" }, async (ctx) => {\n    return new Response(\"OK\", { status: 200 });\n  }));\n\n  const server = transport.server;\n\n  // check if the server is bound to an express app\n  const expressApp: express.Application = (useExpress)\n    ? transport.getExpressApp() as express.Application\n    // fallback searching for express app in server listeners\n    : server?.listeners('request').find((listener: Function) => listener.name === \"app\" && listener['mountpath'] === '/') as express.Application;\n\n  // add default \"/\" route, if not provided.\n  const hasRootRoute = (\n    // check if express app has a root route\n    (expressApp && expressRootRoute(expressApp) !== undefined) ||\n\n    // check if router has a root route\n    Object.values(router.endpoints).some(endpoint => endpoint.path === \"/\")\n  );\n\n  if (!hasRootRoute) {\n    router.addEndpoint(createEndpoint(\"/\", { method: \"GET\" }, async (ctx) => {\n      return new Response(`Colyseus ${pkg.version}`, { status: 200 });\n    }));\n  }\n\n  // use custom bindRouter method if provided\n  if (!server && transport.bindRouter) {\n    transport.bindRouter(router);\n    return;\n  }\n\n  // which route handler to use\n  // (router + fallback to express, or just router)\n  let next: any;\n\n  if (expressApp) {\n    server.removeListener('request', expressApp);\n\n    next = async (req: IncomingMessage, res: ServerResponse) => {\n      // check if the route is defined in the router\n      // if so, use the router handler, otherwise fallback to express\n      if (router.findRoute(req.method, req.url.split('?')[0]) !== undefined) {\n        const protocol = req.headers[\"x-forwarded-proto\"] || ((req.socket as any).encrypted ? \"https\" : \"http\");\n        const base = `${protocol}://${req.headers[\":authority\"] || req.headers.host}`;\n        const response = await router.handler(getRequest({ base, request: req }));\n        return setResponse(res, response);\n\n      } else {\n        return expressApp['handle'](req, res);\n      }\n    };\n\n  } else {\n    next = toNodeHandler(router.handler);\n  }\n\n  // handle cors headers for all requests by default\n  server.prependListener('request', (req: IncomingMessage, res: ServerResponse) => {\n    const corsHeaders = {\n      ...controller.DEFAULT_CORS_HEADERS,\n      ...controller.getCorsHeaders(new Headers(req.headers as any)),\n    };\n\n    if (req.method === \"OPTIONS\") {\n      res.writeHead(204, corsHeaders);\n      res.end();\n      return;\n    }\n\n    Object.entries(corsHeaders).forEach(([key, value]) => {\n      res.setHeader(key, value);\n    });\n\n    next(req, res);\n  });\n}\n\nfunction expressRootRoute(expressApp: express.Application) {\n  //\n  // express v5 uses `app.router`, express v4 uses `app._router`\n  // check for `app._router` first, then `app.router`\n  //\n  // (express v4 will show a warning if `app.router` is used)\n  //\n  const stack = (expressApp as any)?._router?.stack ?? (expressApp as any)?.router?.stack;\n\n  if (!stack) {\n    return false;\n  }\n\n  return stack.find((layer: any) => layer.match('/') && !['query', 'expressInit'].includes(layer.name));\n}\n\n/**\n * Do not use this directly. This is used internally by `@colyseus/playground`.\n * TODO: refactor. Avoid using globals.\n * @internal\n */\nexport let __globalEndpoints: Record<string, Endpoint> = {};\n\nexport function createRouter<\n  E extends Record<string, Endpoint>,\n  Config extends RouterConfig\n>(endpoints: E, config: Config = {} as Config) {\n  // TODO: refactor. Avoid using globals.\n  __globalEndpoints = endpoints;\n\n  return createBetterCallRouter({ ...endpoints }, config);\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type express from \"express\";\nimport type { IncomingMessage, ServerResponse } from \"http\";\nimport { createHash, timingSafeEqual } from \"node:crypto\";\nimport { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint, createMiddleware, APIError } from \"@colyseus/better-call\";\nimport { toNodeHandler, getRequest, setResponse } from \"@colyseus/better-call/node\";\nimport { Transport } from \"../Transport.ts\";\nimport { controller } from \"../matchmaker/controller.ts\";\nimport pkg from \"../../package.json\" with { type: \"json\" };\n\nexport {\n  createEndpoint,\n  createMiddleware,\n  createInternalContext,\n\n  // Re-export types needed for declaration emit\n  type Router,\n  type RouterConfig,\n  type Endpoint,\n  type EndpointHandler,\n  type EndpointOptions,\n  type EndpointContext,\n  type StrictEndpoint,\n} from \"@colyseus/better-call\";\n\nexport { toNodeHandler };\n\nexport function bindRouterToTransport(transport: Transport, router: Router, useExpress: boolean) {\n  // add default \"/__healthcheck\" endpoint\n  router.addEndpoint(createEndpoint(\"/__healthcheck\", { method: \"GET\" }, async (ctx) => {\n    return new Response(\"OK\", { status: 200 });\n  }));\n\n  const server = transport.server;\n\n  // check if the server is bound to an express app\n  const expressApp: express.Application = (useExpress)\n    ? transport.getExpressApp() as express.Application\n    // fallback searching for express app in server listeners\n    : server?.listeners('request').find((listener: Function) => listener.name === \"app\" && listener['mountpath'] === '/') as express.Application;\n\n  // add default \"/\" route, if not provided.\n  const hasRootRoute = (\n    // check if express app has a root route\n    (expressApp && expressRootRoute(expressApp) !== undefined) ||\n\n    // check if router has a root route\n    Object.values(router.endpoints).some(endpoint => endpoint.path === \"/\")\n  );\n\n  if (!hasRootRoute) {\n    router.addEndpoint(createEndpoint(\"/\", { method: \"GET\" }, async (ctx) => {\n      return new Response(`Colyseus ${pkg.version}`, { status: 200 });\n    }));\n  }\n\n  // use custom bindRouter method if provided\n  if (!server && transport.bindRouter) {\n    transport.bindRouter(router);\n    return;\n  }\n\n  // which route handler to use\n  // (router + fallback to express, or just router)\n  let next: any;\n\n  if (expressApp) {\n    server.removeListener('request', expressApp);\n\n    next = async (req: IncomingMessage, res: ServerResponse) => {\n      // check if the route is defined in the router\n      // if so, use the router handler, otherwise fallback to express\n      if (router.findRoute(req.method, req.url.split('?')[0]) !== undefined) {\n        const protocol = req.headers[\"x-forwarded-proto\"] || ((req.socket as any).encrypted ? \"https\" : \"http\");\n        const base = `${protocol}://${req.headers[\":authority\"] || req.headers.host}`;\n        const response = await router.handler(getRequest({ base, request: req }));\n        return setResponse(res, response);\n\n      } else {\n        return expressApp['handle'](req, res);\n      }\n    };\n\n  } else {\n    next = toNodeHandler(router.handler);\n  }\n\n  // handle cors headers for all requests by default\n  server.prependListener('request', (req: IncomingMessage, res: ServerResponse) => {\n    const corsHeaders = {\n      ...controller.DEFAULT_CORS_HEADERS,\n      ...controller.getCorsHeaders(new Headers(req.headers as any)),\n    };\n\n    if (req.method === \"OPTIONS\") {\n      res.writeHead(204, corsHeaders);\n      res.end();\n      return;\n    }\n\n    Object.entries(corsHeaders).forEach(([key, value]) => {\n      res.setHeader(key, value);\n    });\n\n    next(req, res);\n  });\n}\n\nfunction expressRootRoute(expressApp: express.Application) {\n  //\n  // express v5 uses `app.router`, express v4 uses `app._router`\n  // check for `app._router` first, then `app.router`\n  //\n  // (express v4 will show a warning if `app.router` is used)\n  //\n  const stack = (expressApp as any)?._router?.stack ?? (expressApp as any)?.router?.stack;\n\n  if (!stack) {\n    return false;\n  }\n\n  return stack.find((layer: any) => layer.match('/') && !['query', 'expressInit'].includes(layer.name));\n}\n\nexport function createRouter<\n  E extends Record<string, Endpoint>,\n  Config extends RouterConfig\n>(endpoints: E, config: Config = {} as Config) {\n  return createBetterCallRouter({ ...endpoints }, config);\n}\n\nexport interface BasicAuthOptions {\n  /** username \u2192 password. The common static case. */\n  users?: Record<string, string>;\n  /** Custom validator (e.g. DB-backed). Takes precedence over `users`. */\n  validate?: (username: string, password: string) => boolean | Promise<boolean>;\n  /** Realm shown in the browser prompt. Default 'Restricted'. */\n  realm?: string;\n}\n\n/**\n * HTTP Basic Auth middleware. Drop into any endpoint's `use:` slot to gate\n * it behind a browser credentials prompt:\n *\n *   playground({ use: [basicAuth({ users: { admin: 's3cret' } })] })\n */\nexport function basicAuth(opts: BasicAuthOptions) {\n  const { users, validate } = opts;\n  if (!users && !validate) {\n    throw new Error('[basicAuth] provide `users` or `validate`');\n  }\n  // Realm is interpolated into a header \u2014 strip `\"` so it can't break out.\n  const challenge = `Basic realm=\"${(opts.realm ?? 'Restricted').replace(/\"/g, '')}\", charset=\"UTF-8\"`;\n\n  return createMiddleware(async (ctx) => {\n    const creds = parseBasicHeader(ctx.getHeader('authorization'));\n    const ok = !!creds && (validate\n      ? await validate(creds.username, creds.password)\n      : staticCheck(users!, creds.username, creds.password));\n    if (!ok) {\n      throw new APIError(401, { message: 'authentication required' }, { 'WWW-Authenticate': challenge });\n    }\n  });\n}\n\nfunction parseBasicHeader(header: string | null | undefined) {\n  if (!header) { return null; }\n  const sep = header.indexOf(' ');\n  if (sep < 0 || header.slice(0, sep).toLowerCase() !== 'basic') { return null; }\n  let decoded: string;\n  try { decoded = Buffer.from(header.slice(sep + 1), 'base64').toString('utf8'); } catch { return null; }\n  const colon = decoded.indexOf(':');\n  if (colon < 0) { return null; }\n  return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };\n}\n\nfunction staticCheck(users: Record<string, string>, username: string, password: string): boolean {\n  const expected = Object.prototype.hasOwnProperty.call(users, username) ? users[username] : undefined;\n  // Compare even for an unknown user so reject timing doesn't reveal which\n  // usernames exist.\n  return safeEqual(password, expected ?? '\\0') && expected !== undefined;\n}\n\n// Hash both sides first: equalizes length (timingSafeEqual throws on a\n// length mismatch, which would itself leak the secret's length).\nfunction safeEqual(a: string, b: string): boolean {\n  return timingSafeEqual(\n    createHash('sha256').update(a).digest(),\n    createHash('sha256').update(b).digest(),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// dualModeEndpoints \u2014 shared express-compat layer for @colyseus/admin,\n// @colyseus/monitor, @colyseus/playground. Builds the two local routers\n// (specific = no catch-all, full = everything) and the matching node\n// handlers, then packages the express middleware so the return value works\n// both as `{...spread}` into createRouter AND as `app.use(\"/\", x)` middleware.\n// ---------------------------------------------------------------------------\n\nexport type ExpressMiddleware = (\n  req: IncomingMessage,\n  res: ServerResponse,\n  next: (err?: any) => void,\n) => void;\n\nexport type NodeHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;\n\nexport interface DualModeHelpers {\n  specificRouter: Router;\n  specificHandler: NodeHandler;\n  fullRouter: Router;\n  fullHandler: NodeHandler;\n}\n\nexport function dualModeEndpoints<E extends Record<string, Endpoint>>(\n  endpoints: E,\n  opts: {\n    /** Key in `endpoints` whose path is a catch-all. Excluded from `specificRouter` so it doesn't eat fall-through decisions. */\n    catchAllKey?: keyof E;\n    /** Build the express middleware given the pre-built routers + node handlers. */\n    buildMiddleware: (helpers: DualModeHelpers) => ExpressMiddleware;\n  },\n): ExpressMiddleware & E {\n  const fullRouter = createRouter(endpoints);\n  const fullHandler = toNodeHandler(fullRouter.handler) as NodeHandler;\n\n  const specificEndpoints = opts.catchAllKey\n    ? Object.fromEntries(\n        Object.entries(endpoints).filter(([k]) => k !== opts.catchAllKey),\n      ) as Partial<E>\n    : endpoints;\n  const specificRouter = createRouter(specificEndpoints as E);\n  const specificHandler = toNodeHandler(specificRouter.handler) as NodeHandler;\n\n  const middleware = opts.buildMiddleware({\n    specificRouter, specificHandler, fullRouter, fullHandler,\n  });\n  return Object.assign(middleware, endpoints) as ExpressMiddleware & E;\n}\n"],
+  "mappings": "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",
   "names": ["import_better_call", "pkg", "createBetterCallRouter"]
 }

package/build/router/index.d.ts

@@ -1,15 +1,10 @@
+import type { IncomingMessage, ServerResponse } from "http";
 import { type Endpoint, type Router, type RouterConfig } from "@colyseus/better-call";
 import { toNodeHandler } from "@colyseus/better-call/node";
 import { Transport } from "../Transport.ts";
 export { createEndpoint, createMiddleware, createInternalContext, type Router, type RouterConfig, type Endpoint, type EndpointHandler, type EndpointOptions, type EndpointContext, type StrictEndpoint, } from "@colyseus/better-call";
 export { toNodeHandler };
 export declare function bindRouterToTransport(transport: Transport, router: Router, useExpress: boolean): void;
-/**
- * Do not use this directly. This is used internally by `@colyseus/playground`.
- * TODO: refactor. Avoid using globals.
- * @internal
- */
-export declare let __globalEndpoints: Record<string, Endpoint>;
 export declare function createRouter<E extends Record<string, Endpoint>, Config extends RouterConfig>(endpoints: E, config?: Config): {
     handler: (request: Request) => Promise<Response>;
     endpoints: E;
@@ -162,3 +157,32 @@ export declare function createRouter<E extends Record<string, Endpoint>, 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 declare function basicAuth(opts: BasicAuthOptions): <InputCtx extends import("@colyseus/better-call").MiddlewareInputContext<import("@colyseus/better-call").MiddlewareOptions>>(inputContext: InputCtx) => Promise<void>;
+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 declare 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;

package/build/router/index.mjs

@@ -1,12 +1,13 @@
 // packages/core/src/router/index.ts
-import { createRouter as createBetterCallRouter, createEndpoint } from "@colyseus/better-call";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createRouter as createBetterCallRouter, createEndpoint, createMiddleware, APIError } from "@colyseus/better-call";
 import { toNodeHandler, getRequest, setResponse } from "@colyseus/better-call/node";
 import "../Transport.mjs";
 import { controller } from "../matchmaker/controller.mjs";
 import pkg from "../../package.json" with { type: "json" };
 import {
   createEndpoint as createEndpoint2,
-  createMiddleware,
+  createMiddleware as createMiddleware2,
   createInternalContext
 } from "@colyseus/better-call";
 function bindRouterToTransport(transport, router, useExpress) {
@@ -68,17 +69,76 @@ function expressRootRoute(expressApp) {
   }
   return stack.find((layer) => layer.match("/") && !["query", "expressInit"].includes(layer.name));
 }
-var __globalEndpoints = {};
 function createRouter(endpoints, config = {}) {
-  __globalEndpoints = endpoints;
   return createBetterCallRouter({ ...endpoints }, config);
 }
+function basicAuth(opts) {
+  const { users, validate } = opts;
+  if (!users && !validate) {
+    throw new Error("[basicAuth] provide `users` or `validate`");
+  }
+  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) {
+  if (!header) {
+    return null;
+  }
+  const sep = header.indexOf(" ");
+  if (sep < 0 || header.slice(0, sep).toLowerCase() !== "basic") {
+    return null;
+  }
+  let decoded;
+  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, username, password) {
+  const expected = Object.prototype.hasOwnProperty.call(users, username) ? users[username] : void 0;
+  return safeEqual(password, expected ?? "\0") && expected !== void 0;
+}
+function safeEqual(a, b) {
+  return timingSafeEqual(
+    createHash("sha256").update(a).digest(),
+    createHash("sha256").update(b).digest()
+  );
+}
+function dualModeEndpoints(endpoints, opts) {
+  const fullRouter = createRouter(endpoints);
+  const fullHandler = toNodeHandler(fullRouter.handler);
+  const specificEndpoints = opts.catchAllKey ? Object.fromEntries(
+    Object.entries(endpoints).filter(([k]) => k !== opts.catchAllKey)
+  ) : endpoints;
+  const specificRouter = createRouter(specificEndpoints);
+  const specificHandler = toNodeHandler(specificRouter.handler);
+  const middleware = opts.buildMiddleware({
+    specificRouter,
+    specificHandler,
+    fullRouter,
+    fullHandler
+  });
+  return Object.assign(middleware, endpoints);
+}
 export {
-  __globalEndpoints,
+  basicAuth,
   bindRouterToTransport,
   createEndpoint2 as createEndpoint,
   createInternalContext,
-  createMiddleware,
+  createMiddleware2 as createMiddleware,
   createRouter,
+  dualModeEndpoints,
   toNodeHandler
 };

package/build/router/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/router/index.ts"],
-  "sourcesContent": ["import type express from \"express\";\nimport type { IncomingMessage, ServerResponse } from \"http\";\nimport { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint } from \"@colyseus/better-call\";\nimport { toNodeHandler, getRequest, setResponse } from \"@colyseus/better-call/node\";\nimport { Transport } from \"../Transport.ts\";\nimport { controller } from \"../matchmaker/controller.ts\";\nimport pkg from \"../../package.json\" with { type: \"json\" };\n\nexport {\n  createEndpoint,\n  createMiddleware,\n  createInternalContext,\n\n  // Re-export types needed for declaration emit\n  type Router,\n  type RouterConfig,\n  type Endpoint,\n  type EndpointHandler,\n  type EndpointOptions,\n  type EndpointContext,\n  type StrictEndpoint,\n} from \"@colyseus/better-call\";\n\nexport { toNodeHandler };\n\nexport function bindRouterToTransport(transport: Transport, router: Router, useExpress: boolean) {\n  // add default \"/__healthcheck\" endpoint\n  router.addEndpoint(createEndpoint(\"/__healthcheck\", { method: \"GET\" }, async (ctx) => {\n    return new Response(\"OK\", { status: 200 });\n  }));\n\n  const server = transport.server;\n\n  // check if the server is bound to an express app\n  const expressApp: express.Application = (useExpress)\n    ? transport.getExpressApp() as express.Application\n    // fallback searching for express app in server listeners\n    : server?.listeners('request').find((listener: Function) => listener.name === \"app\" && listener['mountpath'] === '/') as express.Application;\n\n  // add default \"/\" route, if not provided.\n  const hasRootRoute = (\n    // check if express app has a root route\n    (expressApp && expressRootRoute(expressApp) !== undefined) ||\n\n    // check if router has a root route\n    Object.values(router.endpoints).some(endpoint => endpoint.path === \"/\")\n  );\n\n  if (!hasRootRoute) {\n    router.addEndpoint(createEndpoint(\"/\", { method: \"GET\" }, async (ctx) => {\n      return new Response(`Colyseus ${pkg.version}`, { status: 200 });\n    }));\n  }\n\n  // use custom bindRouter method if provided\n  if (!server && transport.bindRouter) {\n    transport.bindRouter(router);\n    return;\n  }\n\n  // which route handler to use\n  // (router + fallback to express, or just router)\n  let next: any;\n\n  if (expressApp) {\n    server.removeListener('request', expressApp);\n\n    next = async (req: IncomingMessage, res: ServerResponse) => {\n      // check if the route is defined in the router\n      // if so, use the router handler, otherwise fallback to express\n      if (router.findRoute(req.method, req.url.split('?')[0]) !== undefined) {\n        const protocol = req.headers[\"x-forwarded-proto\"] || ((req.socket as any).encrypted ? \"https\" : \"http\");\n        const base = `${protocol}://${req.headers[\":authority\"] || req.headers.host}`;\n        const response = await router.handler(getRequest({ base, request: req }));\n        return setResponse(res, response);\n\n      } else {\n        return expressApp['handle'](req, res);\n      }\n    };\n\n  } else {\n    next = toNodeHandler(router.handler);\n  }\n\n  // handle cors headers for all requests by default\n  server.prependListener('request', (req: IncomingMessage, res: ServerResponse) => {\n    const corsHeaders = {\n      ...controller.DEFAULT_CORS_HEADERS,\n      ...controller.getCorsHeaders(new Headers(req.headers as any)),\n    };\n\n    if (req.method === \"OPTIONS\") {\n      res.writeHead(204, corsHeaders);\n      res.end();\n      return;\n    }\n\n    Object.entries(corsHeaders).forEach(([key, value]) => {\n      res.setHeader(key, value);\n    });\n\n    next(req, res);\n  });\n}\n\nfunction expressRootRoute(expressApp: express.Application) {\n  //\n  // express v5 uses `app.router`, express v4 uses `app._router`\n  // check for `app._router` first, then `app.router`\n  //\n  // (express v4 will show a warning if `app.router` is used)\n  //\n  const stack = (expressApp as any)?._router?.stack ?? (expressApp as any)?.router?.stack;\n\n  if (!stack) {\n    return false;\n  }\n\n  return stack.find((layer: any) => layer.match('/') && !['query', 'expressInit'].includes(layer.name));\n}\n\n/**\n * Do not use this directly. This is used internally by `@colyseus/playground`.\n * TODO: refactor. Avoid using globals.\n * @internal\n */\nexport let __globalEndpoints: Record<string, Endpoint> = {};\n\nexport function createRouter<\n  E extends Record<string, Endpoint>,\n  Config extends RouterConfig\n>(endpoints: E, config: Config = {} as Config) {\n  // TODO: refactor. Avoid using globals.\n  __globalEndpoints = endpoints;\n\n  return createBetterCallRouter({ ...endpoints }, config);\n}\n"],
-  "mappings": "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",
-  "names": ["createEndpoint"]
+  "sourcesContent": ["import type express from \"express\";\nimport type { IncomingMessage, ServerResponse } from \"http\";\nimport { createHash, timingSafeEqual } from \"node:crypto\";\nimport { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint, createMiddleware, APIError } from \"@colyseus/better-call\";\nimport { toNodeHandler, getRequest, setResponse } from \"@colyseus/better-call/node\";\nimport { Transport } from \"../Transport.ts\";\nimport { controller } from \"../matchmaker/controller.ts\";\nimport pkg from \"../../package.json\" with { type: \"json\" };\n\nexport {\n  createEndpoint,\n  createMiddleware,\n  createInternalContext,\n\n  // Re-export types needed for declaration emit\n  type Router,\n  type RouterConfig,\n  type Endpoint,\n  type EndpointHandler,\n  type EndpointOptions,\n  type EndpointContext,\n  type StrictEndpoint,\n} from \"@colyseus/better-call\";\n\nexport { toNodeHandler };\n\nexport function bindRouterToTransport(transport: Transport, router: Router, useExpress: boolean) {\n  // add default \"/__healthcheck\" endpoint\n  router.addEndpoint(createEndpoint(\"/__healthcheck\", { method: \"GET\" }, async (ctx) => {\n    return new Response(\"OK\", { status: 200 });\n  }));\n\n  const server = transport.server;\n\n  // check if the server is bound to an express app\n  const expressApp: express.Application = (useExpress)\n    ? transport.getExpressApp() as express.Application\n    // fallback searching for express app in server listeners\n    : server?.listeners('request').find((listener: Function) => listener.name === \"app\" && listener['mountpath'] === '/') as express.Application;\n\n  // add default \"/\" route, if not provided.\n  const hasRootRoute = (\n    // check if express app has a root route\n    (expressApp && expressRootRoute(expressApp) !== undefined) ||\n\n    // check if router has a root route\n    Object.values(router.endpoints).some(endpoint => endpoint.path === \"/\")\n  );\n\n  if (!hasRootRoute) {\n    router.addEndpoint(createEndpoint(\"/\", { method: \"GET\" }, async (ctx) => {\n      return new Response(`Colyseus ${pkg.version}`, { status: 200 });\n    }));\n  }\n\n  // use custom bindRouter method if provided\n  if (!server && transport.bindRouter) {\n    transport.bindRouter(router);\n    return;\n  }\n\n  // which route handler to use\n  // (router + fallback to express, or just router)\n  let next: any;\n\n  if (expressApp) {\n    server.removeListener('request', expressApp);\n\n    next = async (req: IncomingMessage, res: ServerResponse) => {\n      // check if the route is defined in the router\n      // if so, use the router handler, otherwise fallback to express\n      if (router.findRoute(req.method, req.url.split('?')[0]) !== undefined) {\n        const protocol = req.headers[\"x-forwarded-proto\"] || ((req.socket as any).encrypted ? \"https\" : \"http\");\n        const base = `${protocol}://${req.headers[\":authority\"] || req.headers.host}`;\n        const response = await router.handler(getRequest({ base, request: req }));\n        return setResponse(res, response);\n\n      } else {\n        return expressApp['handle'](req, res);\n      }\n    };\n\n  } else {\n    next = toNodeHandler(router.handler);\n  }\n\n  // handle cors headers for all requests by default\n  server.prependListener('request', (req: IncomingMessage, res: ServerResponse) => {\n    const corsHeaders = {\n      ...controller.DEFAULT_CORS_HEADERS,\n      ...controller.getCorsHeaders(new Headers(req.headers as any)),\n    };\n\n    if (req.method === \"OPTIONS\") {\n      res.writeHead(204, corsHeaders);\n      res.end();\n      return;\n    }\n\n    Object.entries(corsHeaders).forEach(([key, value]) => {\n      res.setHeader(key, value);\n    });\n\n    next(req, res);\n  });\n}\n\nfunction expressRootRoute(expressApp: express.Application) {\n  //\n  // express v5 uses `app.router`, express v4 uses `app._router`\n  // check for `app._router` first, then `app.router`\n  //\n  // (express v4 will show a warning if `app.router` is used)\n  //\n  const stack = (expressApp as any)?._router?.stack ?? (expressApp as any)?.router?.stack;\n\n  if (!stack) {\n    return false;\n  }\n\n  return stack.find((layer: any) => layer.match('/') && !['query', 'expressInit'].includes(layer.name));\n}\n\nexport function createRouter<\n  E extends Record<string, Endpoint>,\n  Config extends RouterConfig\n>(endpoints: E, config: Config = {} as Config) {\n  return createBetterCallRouter({ ...endpoints }, config);\n}\n\nexport interface BasicAuthOptions {\n  /** username \u2192 password. The common static case. */\n  users?: Record<string, string>;\n  /** Custom validator (e.g. DB-backed). Takes precedence over `users`. */\n  validate?: (username: string, password: string) => boolean | Promise<boolean>;\n  /** Realm shown in the browser prompt. Default 'Restricted'. */\n  realm?: string;\n}\n\n/**\n * HTTP Basic Auth middleware. Drop into any endpoint's `use:` slot to gate\n * it behind a browser credentials prompt:\n *\n *   playground({ use: [basicAuth({ users: { admin: 's3cret' } })] })\n */\nexport function basicAuth(opts: BasicAuthOptions) {\n  const { users, validate } = opts;\n  if (!users && !validate) {\n    throw new Error('[basicAuth] provide `users` or `validate`');\n  }\n  // Realm is interpolated into a header \u2014 strip `\"` so it can't break out.\n  const challenge = `Basic realm=\"${(opts.realm ?? 'Restricted').replace(/\"/g, '')}\", charset=\"UTF-8\"`;\n\n  return createMiddleware(async (ctx) => {\n    const creds = parseBasicHeader(ctx.getHeader('authorization'));\n    const ok = !!creds && (validate\n      ? await validate(creds.username, creds.password)\n      : staticCheck(users!, creds.username, creds.password));\n    if (!ok) {\n      throw new APIError(401, { message: 'authentication required' }, { 'WWW-Authenticate': challenge });\n    }\n  });\n}\n\nfunction parseBasicHeader(header: string | null | undefined) {\n  if (!header) { return null; }\n  const sep = header.indexOf(' ');\n  if (sep < 0 || header.slice(0, sep).toLowerCase() !== 'basic') { return null; }\n  let decoded: string;\n  try { decoded = Buffer.from(header.slice(sep + 1), 'base64').toString('utf8'); } catch { return null; }\n  const colon = decoded.indexOf(':');\n  if (colon < 0) { return null; }\n  return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };\n}\n\nfunction staticCheck(users: Record<string, string>, username: string, password: string): boolean {\n  const expected = Object.prototype.hasOwnProperty.call(users, username) ? users[username] : undefined;\n  // Compare even for an unknown user so reject timing doesn't reveal which\n  // usernames exist.\n  return safeEqual(password, expected ?? '\\0') && expected !== undefined;\n}\n\n// Hash both sides first: equalizes length (timingSafeEqual throws on a\n// length mismatch, which would itself leak the secret's length).\nfunction safeEqual(a: string, b: string): boolean {\n  return timingSafeEqual(\n    createHash('sha256').update(a).digest(),\n    createHash('sha256').update(b).digest(),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// dualModeEndpoints \u2014 shared express-compat layer for @colyseus/admin,\n// @colyseus/monitor, @colyseus/playground. Builds the two local routers\n// (specific = no catch-all, full = everything) and the matching node\n// handlers, then packages the express middleware so the return value works\n// both as `{...spread}` into createRouter AND as `app.use(\"/\", x)` middleware.\n// ---------------------------------------------------------------------------\n\nexport type ExpressMiddleware = (\n  req: IncomingMessage,\n  res: ServerResponse,\n  next: (err?: any) => void,\n) => void;\n\nexport type NodeHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;\n\nexport interface DualModeHelpers {\n  specificRouter: Router;\n  specificHandler: NodeHandler;\n  fullRouter: Router;\n  fullHandler: NodeHandler;\n}\n\nexport function dualModeEndpoints<E extends Record<string, Endpoint>>(\n  endpoints: E,\n  opts: {\n    /** Key in `endpoints` whose path is a catch-all. Excluded from `specificRouter` so it doesn't eat fall-through decisions. */\n    catchAllKey?: keyof E;\n    /** Build the express middleware given the pre-built routers + node handlers. */\n    buildMiddleware: (helpers: DualModeHelpers) => ExpressMiddleware;\n  },\n): ExpressMiddleware & E {\n  const fullRouter = createRouter(endpoints);\n  const fullHandler = toNodeHandler(fullRouter.handler) as NodeHandler;\n\n  const specificEndpoints = opts.catchAllKey\n    ? Object.fromEntries(\n        Object.entries(endpoints).filter(([k]) => k !== opts.catchAllKey),\n      ) as Partial<E>\n    : endpoints;\n  const specificRouter = createRouter(specificEndpoints as E);\n  const specificHandler = toNodeHandler(specificRouter.handler) as NodeHandler;\n\n  const middleware = opts.buildMiddleware({\n    specificRouter, specificHandler, fullRouter, fullHandler,\n  });\n  return Object.assign(middleware, endpoints) as ExpressMiddleware & E;\n}\n"],
+  "mappings": "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",
+  "names": ["createEndpoint", "createMiddleware"]
 }

package/build/utils/Env.cjs

@@ -36,33 +36,29 @@ __export(Env_exports, {
   isColyseusCloud: () => isColyseusCloud
 });
 module.exports = __toCommonJS(Env_exports);
-var import_os = __toESM(require("os"), 1);
 var import_LocalPresence = require("../presence/LocalPresence.cjs");
 var import_LocalDriver = require("../matchmaker/LocalDriver/LocalDriver.cjs");
 var import_Logger = require("../Logger.cjs");
 function isColyseusCloud() {
   return process.env.COLYSEUS_CLOUD !== void 0;
 }
-function shouldUseRedisOnCloud() {
-  return import_os.default.cpus().length > 1 || process.env.REDIS_URI !== void 0;
-}
 async function getDefaultPresence() {
-  if (isColyseusCloud() && shouldUseRedisOnCloud()) {
+  if (isColyseusCloud()) {
     try {
       const RedisPresence = await import("@colyseus/redis-presence");
       return new RedisPresence.RedisPresence(process.env.REDIS_URI);
     } catch (e) {
       console.error(e);
       import_Logger.logger.warn("");
-      import_Logger.logger.warn("\u274C could not initialize RedisPresence.");
-      import_Logger.logger.warn("\u{1F449} npm install --save @colyseus/redis-presence");
+      import_Logger.logger.warn("\u274C could not initialize RedisDriver.");
+      import_Logger.logger.warn("\u{1F449} npm install --save @colyseus/redis-driver");
       import_Logger.logger.warn("");
     }
   }
   return new import_LocalPresence.LocalPresence();
 }
 async function getDefaultDriver() {
-  if (isColyseusCloud() && shouldUseRedisOnCloud()) {
+  if (isColyseusCloud()) {
     try {
       const RedisDriver = await import("@colyseus/redis-driver");
       return new RedisDriver.RedisDriver(process.env.REDIS_URI);

package/build/utils/Env.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/Env.ts"],
-  "sourcesContent": ["import os from 'os';\nimport { LocalPresence } from '../presence/LocalPresence.ts';\nimport { LocalDriver, type MatchMakerDriver } from '../matchmaker/LocalDriver/LocalDriver.ts';\nimport { logger } from '../Logger.ts';\nimport type { Presence } from '../presence/Presence.ts';\n\nexport function isColyseusCloud(): boolean {\n  return process.env.COLYSEUS_CLOUD !== undefined;\n}\n\n// On Colyseus Cloud, only opt into Redis when there's more than one CPU\n// (multi-process deploys) or when REDIS_URI is explicitly provided.\n// Single-CPU instances without REDIS_URI keep using Local presence/driver.\nfunction shouldUseRedisOnCloud(): boolean {\n  return os.cpus().length > 1 || process.env.REDIS_URI !== undefined;\n}\n\nexport async function getDefaultPresence(): Promise<Presence> {\n  if (isColyseusCloud() && shouldUseRedisOnCloud()) {\n    try {\n      const RedisPresence = await import('@colyseus/redis-presence');\n      return new RedisPresence.RedisPresence(process.env.REDIS_URI);\n    } catch (e) {\n      console.error(e);\n      logger.warn(\"\");\n      logger.warn(\"\u274C could not initialize RedisPresence.\");\n      logger.warn(\"\uD83D\uDC49 npm install --save @colyseus/redis-presence\");\n      logger.warn(\"\");\n    }\n  }\n  return new LocalPresence();\n}\n\nexport async function getDefaultDriver(): Promise<MatchMakerDriver> {\n  if (isColyseusCloud() && shouldUseRedisOnCloud()) {\n    try {\n      const RedisDriver = await import('@colyseus/redis-driver');\n      return new RedisDriver.RedisDriver(process.env.REDIS_URI);\n    } catch (e) {\n      console.error(e);\n      logger.warn(\"\");\n      logger.warn(\"\u274C could not initialize RedisDriver.\");\n      logger.warn(\"\uD83D\uDC49 npm install --save @colyseus/redis-driver\");\n      logger.warn(\"\");\n    }\n  }\n  return new LocalDriver();\n}\n\nexport function getDefaultPublicAddress(): string | undefined {\n  if (isColyseusCloud()) {\n    let port = 2567;\n\n    //\n    // Multiple processes: Use NODE_APP_INSTANCE to play nicely with pm2\n    //\n    port += Number(process.env.NODE_APP_INSTANCE || \"0\");\n\n    return process.env.SUBDOMAIN + \".\" + process.env.SERVER_NAME + \"/\" + port;\n\n  } else {\n    return undefined;\n  }\n}"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gBAAe;AACf,2BAA8B;AAC9B,yBAAmD;AACnD,oBAAuB;AAGhB,SAAS,kBAA2B;AACzC,SAAO,QAAQ,IAAI,mBAAmB;AACxC;AAKA,SAAS,wBAAiC;AACxC,SAAO,UAAAA,QAAG,KAAK,EAAE,SAAS,KAAK,QAAQ,IAAI,cAAc;AAC3D;AAEA,eAAsB,qBAAwC;AAC5D,MAAI,gBAAgB,KAAK,sBAAsB,GAAG;AAChD,QAAI;AACF,YAAM,gBAAgB,MAAM,OAAO,0BAA0B;AAC7D,aAAO,IAAI,cAAc,cAAc,QAAQ,IAAI,SAAS;AAAA,IAC9D,SAAS,GAAG;AACV,cAAQ,MAAM,CAAC;AACf,2BAAO,KAAK,EAAE;AACd,2BAAO,KAAK,4CAAuC;AACnD,2BAAO,KAAK,uDAAgD;AAC5D,2BAAO,KAAK,EAAE;AAAA,IAChB;AAAA,EACF;AACA,SAAO,IAAI,mCAAc;AAC3B;AAEA,eAAsB,mBAA8C;AAClE,MAAI,gBAAgB,KAAK,sBAAsB,GAAG;AAChD,QAAI;AACF,YAAM,cAAc,MAAM,OAAO,wBAAwB;AACzD,aAAO,IAAI,YAAY,YAAY,QAAQ,IAAI,SAAS;AAAA,IAC1D,SAAS,GAAG;AACV,cAAQ,MAAM,CAAC;AACf,2BAAO,KAAK,EAAE;AACd,2BAAO,KAAK,0CAAqC;AACjD,2BAAO,KAAK,qDAA8C;AAC1D,2BAAO,KAAK,EAAE;AAAA,IAChB;AAAA,EACF;AACA,SAAO,IAAI,+BAAY;AACzB;AAEO,SAAS,0BAA8C;AAC5D,MAAI,gBAAgB,GAAG;AACrB,QAAI,OAAO;AAKX,YAAQ,OAAO,QAAQ,IAAI,qBAAqB,GAAG;AAEnD,WAAO,QAAQ,IAAI,YAAY,MAAM,QAAQ,IAAI,cAAc,MAAM;AAAA,EAEvE,OAAO;AACL,WAAO;AAAA,EACT;AACF;",
-  "names": ["os"]
+  "sourcesContent": ["import { LocalPresence } from '../presence/LocalPresence.ts';\nimport { LocalDriver, type MatchMakerDriver } from '../matchmaker/LocalDriver/LocalDriver.ts';\nimport { logger } from '../Logger.ts';\nimport type { Presence } from '../presence/Presence.ts';\n\nexport function isColyseusCloud(): boolean {\n  return process.env.COLYSEUS_CLOUD !== undefined;\n}\n\nexport async function getDefaultPresence(): Promise<Presence> {\n  if (isColyseusCloud()) {\n    try {\n      const RedisPresence = await import('@colyseus/redis-presence');\n      return new RedisPresence.RedisPresence(process.env.REDIS_URI);\n    } catch (e) {\n      console.error(e);\n      logger.warn(\"\");\n      logger.warn(\"\u274C could not initialize RedisDriver.\");\n      logger.warn(\"\uD83D\uDC49 npm install --save @colyseus/redis-driver\");\n      logger.warn(\"\");\n    }\n  }\n  return new LocalPresence();\n}\n\nexport async function getDefaultDriver(): Promise<MatchMakerDriver> {\n  if (isColyseusCloud()) {\n    try {\n      const RedisDriver = await import('@colyseus/redis-driver');\n      return new RedisDriver.RedisDriver(process.env.REDIS_URI);\n    } catch (e) {\n      console.error(e);\n      logger.warn(\"\");\n      logger.warn(\"\u274C could not initialize RedisDriver.\");\n      logger.warn(\"\uD83D\uDC49 npm install --save @colyseus/redis-driver\");\n      logger.warn(\"\");\n    }\n  }\n  return new LocalDriver();\n}\n\nexport function getDefaultPublicAddress(): string | undefined {\n  if (isColyseusCloud()) {\n    let port = 2567;\n\n    //\n    // Multiple processes: Use NODE_APP_INSTANCE to play nicely with pm2\n    //\n    port += Number(process.env.NODE_APP_INSTANCE || \"0\");\n\n    return process.env.SUBDOMAIN + \".\" + process.env.SERVER_NAME + \"/\" + port;\n\n  } else {\n    return undefined;\n  }\n}"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,2BAA8B;AAC9B,yBAAmD;AACnD,oBAAuB;AAGhB,SAAS,kBAA2B;AACzC,SAAO,QAAQ,IAAI,mBAAmB;AACxC;AAEA,eAAsB,qBAAwC;AAC5D,MAAI,gBAAgB,GAAG;AACrB,QAAI;AACF,YAAM,gBAAgB,MAAM,OAAO,0BAA0B;AAC7D,aAAO,IAAI,cAAc,cAAc,QAAQ,IAAI,SAAS;AAAA,IAC9D,SAAS,GAAG;AACV,cAAQ,MAAM,CAAC;AACf,2BAAO,KAAK,EAAE;AACd,2BAAO,KAAK,0CAAqC;AACjD,2BAAO,KAAK,qDAA8C;AAC1D,2BAAO,KAAK,EAAE;AAAA,IAChB;AAAA,EACF;AACA,SAAO,IAAI,mCAAc;AAC3B;AAEA,eAAsB,mBAA8C;AAClE,MAAI,gBAAgB,GAAG;AACrB,QAAI;AACF,YAAM,cAAc,MAAM,OAAO,wBAAwB;AACzD,aAAO,IAAI,YAAY,YAAY,QAAQ,IAAI,SAAS;AAAA,IAC1D,SAAS,GAAG;AACV,cAAQ,MAAM,CAAC;AACf,2BAAO,KAAK,EAAE;AACd,2BAAO,KAAK,0CAAqC;AACjD,2BAAO,KAAK,qDAA8C;AAC1D,2BAAO,KAAK,EAAE;AAAA,IAChB;AAAA,EACF;AACA,SAAO,IAAI,+BAAY;AACzB;AAEO,SAAS,0BAA8C;AAC5D,MAAI,gBAAgB,GAAG;AACrB,QAAI,OAAO;AAKX,YAAQ,OAAO,QAAQ,IAAI,qBAAqB,GAAG;AAEnD,WAAO,QAAQ,IAAI,YAAY,MAAM,QAAQ,IAAI,cAAc,MAAM;AAAA,EAEvE,OAAO;AACL,WAAO;AAAA,EACT;AACF;",
+  "names": []
 }

package/build/utils/Env.mjs

@@ -1,31 +1,27 @@
 // packages/core/src/utils/Env.ts
-import os from "os";
 import { LocalPresence } from "../presence/LocalPresence.mjs";
 import { LocalDriver } from "../matchmaker/LocalDriver/LocalDriver.mjs";
 import { logger } from "../Logger.mjs";
 function isColyseusCloud() {
   return process.env.COLYSEUS_CLOUD !== void 0;
 }
-function shouldUseRedisOnCloud() {
-  return os.cpus().length > 1 || process.env.REDIS_URI !== void 0;
-}
 async function getDefaultPresence() {
-  if (isColyseusCloud() && shouldUseRedisOnCloud()) {
+  if (isColyseusCloud()) {
     try {
       const RedisPresence = await import("@colyseus/redis-presence");
       return new RedisPresence.RedisPresence(process.env.REDIS_URI);
     } catch (e) {
       console.error(e);
       logger.warn("");
-      logger.warn("\u274C could not initialize RedisPresence.");
-      logger.warn("\u{1F449} npm install --save @colyseus/redis-presence");
+      logger.warn("\u274C could not initialize RedisDriver.");
+      logger.warn("\u{1F449} npm install --save @colyseus/redis-driver");
       logger.warn("");
     }
   }
   return new LocalPresence();
 }
 async function getDefaultDriver() {
-  if (isColyseusCloud() && shouldUseRedisOnCloud()) {
+  if (isColyseusCloud()) {
     try {
       const RedisDriver = await import("@colyseus/redis-driver");
       return new RedisDriver.RedisDriver(process.env.REDIS_URI);

package/build/utils/Env.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/Env.ts"],
-  "sourcesContent": ["import os from 'os';\nimport { LocalPresence } from '../presence/LocalPresence.ts';\nimport { LocalDriver, type MatchMakerDriver } from '../matchmaker/LocalDriver/LocalDriver.ts';\nimport { logger } from '../Logger.ts';\nimport type { Presence } from '../presence/Presence.ts';\n\nexport function isColyseusCloud(): boolean {\n  return process.env.COLYSEUS_CLOUD !== undefined;\n}\n\n// On Colyseus Cloud, only opt into Redis when there's more than one CPU\n// (multi-process deploys) or when REDIS_URI is explicitly provided.\n// Single-CPU instances without REDIS_URI keep using Local presence/driver.\nfunction shouldUseRedisOnCloud(): boolean {\n  return os.cpus().length > 1 || process.env.REDIS_URI !== undefined;\n}\n\nexport async function getDefaultPresence(): Promise<Presence> {\n  if (isColyseusCloud() && shouldUseRedisOnCloud()) {\n    try {\n      const RedisPresence = await import('@colyseus/redis-presence');\n      return new RedisPresence.RedisPresence(process.env.REDIS_URI);\n    } catch (e) {\n      console.error(e);\n      logger.warn(\"\");\n      logger.warn(\"\u274C could not initialize RedisPresence.\");\n      logger.warn(\"\uD83D\uDC49 npm install --save @colyseus/redis-presence\");\n      logger.warn(\"\");\n    }\n  }\n  return new LocalPresence();\n}\n\nexport async function getDefaultDriver(): Promise<MatchMakerDriver> {\n  if (isColyseusCloud() && shouldUseRedisOnCloud()) {\n    try {\n      const RedisDriver = await import('@colyseus/redis-driver');\n      return new RedisDriver.RedisDriver(process.env.REDIS_URI);\n    } catch (e) {\n      console.error(e);\n      logger.warn(\"\");\n      logger.warn(\"\u274C could not initialize RedisDriver.\");\n      logger.warn(\"\uD83D\uDC49 npm install --save @colyseus/redis-driver\");\n      logger.warn(\"\");\n    }\n  }\n  return new LocalDriver();\n}\n\nexport function getDefaultPublicAddress(): string | undefined {\n  if (isColyseusCloud()) {\n    let port = 2567;\n\n    //\n    // Multiple processes: Use NODE_APP_INSTANCE to play nicely with pm2\n    //\n    port += Number(process.env.NODE_APP_INSTANCE || \"0\");\n\n    return process.env.SUBDOMAIN + \".\" + process.env.SERVER_NAME + \"/\" + port;\n\n  } else {\n    return undefined;\n  }\n}"],
-  "mappings": ";AAAA,OAAO,QAAQ;AACf,SAAS,qBAAqB;AAC9B,SAAS,mBAA0C;AACnD,SAAS,cAAc;AAGhB,SAAS,kBAA2B;AACzC,SAAO,QAAQ,IAAI,mBAAmB;AACxC;AAKA,SAAS,wBAAiC;AACxC,SAAO,GAAG,KAAK,EAAE,SAAS,KAAK,QAAQ,IAAI,cAAc;AAC3D;AAEA,eAAsB,qBAAwC;AAC5D,MAAI,gBAAgB,KAAK,sBAAsB,GAAG;AAChD,QAAI;AACF,YAAM,gBAAgB,MAAM,OAAO,0BAA0B;AAC7D,aAAO,IAAI,cAAc,cAAc,QAAQ,IAAI,SAAS;AAAA,IAC9D,SAAS,GAAG;AACV,cAAQ,MAAM,CAAC;AACf,aAAO,KAAK,EAAE;AACd,aAAO,KAAK,4CAAuC;AACnD,aAAO,KAAK,uDAAgD;AAC5D,aAAO,KAAK,EAAE;AAAA,IAChB;AAAA,EACF;AACA,SAAO,IAAI,cAAc;AAC3B;AAEA,eAAsB,mBAA8C;AAClE,MAAI,gBAAgB,KAAK,sBAAsB,GAAG;AAChD,QAAI;AACF,YAAM,cAAc,MAAM,OAAO,wBAAwB;AACzD,aAAO,IAAI,YAAY,YAAY,QAAQ,IAAI,SAAS;AAAA,IAC1D,SAAS,GAAG;AACV,cAAQ,MAAM,CAAC;AACf,aAAO,KAAK,EAAE;AACd,aAAO,KAAK,0CAAqC;AACjD,aAAO,KAAK,qDAA8C;AAC1D,aAAO,KAAK,EAAE;AAAA,IAChB;AAAA,EACF;AACA,SAAO,IAAI,YAAY;AACzB;AAEO,SAAS,0BAA8C;AAC5D,MAAI,gBAAgB,GAAG;AACrB,QAAI,OAAO;AAKX,YAAQ,OAAO,QAAQ,IAAI,qBAAqB,GAAG;AAEnD,WAAO,QAAQ,IAAI,YAAY,MAAM,QAAQ,IAAI,cAAc,MAAM;AAAA,EAEvE,OAAO;AACL,WAAO;AAAA,EACT;AACF;",
+  "sourcesContent": ["import { LocalPresence } from '../presence/LocalPresence.ts';\nimport { LocalDriver, type MatchMakerDriver } from '../matchmaker/LocalDriver/LocalDriver.ts';\nimport { logger } from '../Logger.ts';\nimport type { Presence } from '../presence/Presence.ts';\n\nexport function isColyseusCloud(): boolean {\n  return process.env.COLYSEUS_CLOUD !== undefined;\n}\n\nexport async function getDefaultPresence(): Promise<Presence> {\n  if (isColyseusCloud()) {\n    try {\n      const RedisPresence = await import('@colyseus/redis-presence');\n      return new RedisPresence.RedisPresence(process.env.REDIS_URI);\n    } catch (e) {\n      console.error(e);\n      logger.warn(\"\");\n      logger.warn(\"\u274C could not initialize RedisDriver.\");\n      logger.warn(\"\uD83D\uDC49 npm install --save @colyseus/redis-driver\");\n      logger.warn(\"\");\n    }\n  }\n  return new LocalPresence();\n}\n\nexport async function getDefaultDriver(): Promise<MatchMakerDriver> {\n  if (isColyseusCloud()) {\n    try {\n      const RedisDriver = await import('@colyseus/redis-driver');\n      return new RedisDriver.RedisDriver(process.env.REDIS_URI);\n    } catch (e) {\n      console.error(e);\n      logger.warn(\"\");\n      logger.warn(\"\u274C could not initialize RedisDriver.\");\n      logger.warn(\"\uD83D\uDC49 npm install --save @colyseus/redis-driver\");\n      logger.warn(\"\");\n    }\n  }\n  return new LocalDriver();\n}\n\nexport function getDefaultPublicAddress(): string | undefined {\n  if (isColyseusCloud()) {\n    let port = 2567;\n\n    //\n    // Multiple processes: Use NODE_APP_INSTANCE to play nicely with pm2\n    //\n    port += Number(process.env.NODE_APP_INSTANCE || \"0\");\n\n    return process.env.SUBDOMAIN + \".\" + process.env.SERVER_NAME + \"/\" + port;\n\n  } else {\n    return undefined;\n  }\n}"],
+  "mappings": ";AAAA,SAAS,qBAAqB;AAC9B,SAAS,mBAA0C;AACnD,SAAS,cAAc;AAGhB,SAAS,kBAA2B;AACzC,SAAO,QAAQ,IAAI,mBAAmB;AACxC;AAEA,eAAsB,qBAAwC;AAC5D,MAAI,gBAAgB,GAAG;AACrB,QAAI;AACF,YAAM,gBAAgB,MAAM,OAAO,0BAA0B;AAC7D,aAAO,IAAI,cAAc,cAAc,QAAQ,IAAI,SAAS;AAAA,IAC9D,SAAS,GAAG;AACV,cAAQ,MAAM,CAAC;AACf,aAAO,KAAK,EAAE;AACd,aAAO,KAAK,0CAAqC;AACjD,aAAO,KAAK,qDAA8C;AAC1D,aAAO,KAAK,EAAE;AAAA,IAChB;AAAA,EACF;AACA,SAAO,IAAI,cAAc;AAC3B;AAEA,eAAsB,mBAA8C;AAClE,MAAI,gBAAgB,GAAG;AACrB,QAAI;AACF,YAAM,cAAc,MAAM,OAAO,wBAAwB;AACzD,aAAO,IAAI,YAAY,YAAY,QAAQ,IAAI,SAAS;AAAA,IAC1D,SAAS,GAAG;AACV,cAAQ,MAAM,CAAC;AACf,aAAO,KAAK,EAAE;AACd,aAAO,KAAK,0CAAqC;AACjD,aAAO,KAAK,qDAA8C;AAC1D,aAAO,KAAK,EAAE;AAAA,IAChB;AAAA,EACF;AACA,SAAO,IAAI,YAAY;AACzB;AAEO,SAAS,0BAA8C;AAC5D,MAAI,gBAAgB,GAAG;AACrB,QAAI,OAAO;AAKX,YAAQ,OAAO,QAAQ,IAAI,qBAAqB,GAAG;AAEnD,WAAO,QAAQ,IAAI,YAAY,MAAM,QAAQ,IAAI,cAAc,MAAM;AAAA,EAEvE,OAAO;AACL,WAAO;AAAA,EACT;AACF;",
   "names": []
 }

package/build/utils/UserSessionIndex.cjs

@@ -0,0 +1,162 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/core/src/utils/UserSessionIndex.ts
+var UserSessionIndex_exports = {};
+__export(UserSessionIndex_exports, {
+  USER_ROOMS_KEY_PREFIX: () => USER_ROOMS_KEY_PREFIX,
+  listUserSessions: () => listUserSessions,
+  releaseRoomLeave: () => releaseRoomLeave,
+  releaseUserSession: () => releaseUserSession,
+  sweepRoomDispose: () => sweepRoomDispose,
+  trackRoomJoin: () => trackRoomJoin,
+  trackUserSession: () => trackUserSession,
+  userRoomsKey: () => userRoomsKey
+});
+module.exports = __toCommonJS(UserSessionIndex_exports);
+var USER_ROOMS_KEY_PREFIX = "colyseus:user-rooms:";
+function userRoomsKey(userId) {
+  return USER_ROOMS_KEY_PREFIX + userId;
+}
+var tracked = /* @__PURE__ */ new WeakMap();
+function getTrackingMap(room) {
+  let map = tracked.get(room);
+  if (!map) {
+    map = /* @__PURE__ */ new Map();
+    tracked.set(room, map);
+  }
+  return map;
+}
+function resolveUserId(client) {
+  return client.userId ?? client.auth?.id;
+}
+async function trackUserSession(presence, userId, sessionId, entry) {
+  try {
+    await presence.hset(userRoomsKey(userId), sessionId, JSON.stringify(entry));
+  } catch {
+  }
+}
+async function releaseUserSession(presence, userId, sessionId) {
+  try {
+    await presence.hdel(userRoomsKey(userId), sessionId);
+  } catch {
+  }
+}
+function trackRoomJoin(room, client) {
+  if (!room.presence) {
+    return;
+  }
+  const userId = resolveUserId(client);
+  if (!userId) {
+    return;
+  }
+  getTrackingMap(room).set(client.sessionId, userId);
+  const entry = {
+    roomId: room.roomId,
+    roomName: room.roomName,
+    joinedAt: Date.now()
+  };
+  void trackUserSession(room.presence, userId, client.sessionId, entry);
+}
+function releaseRoomLeave(room, client) {
+  if (!room.presence) {
+    return;
+  }
+  const map = tracked.get(room);
+  const userId = map?.get(client.sessionId);
+  if (!userId || !map) {
+    return;
+  }
+  map.delete(client.sessionId);
+  void releaseUserSession(room.presence, userId, client.sessionId);
+}
+async function sweepRoomDispose(room) {
+  if (!room.presence) {
+    return;
+  }
+  const map = tracked.get(room);
+  if (!map || map.size === 0) {
+    return;
+  }
+  const pending = [];
+  for (const [sessionId, userId] of map) {
+    pending.push(releaseUserSession(room.presence, userId, sessionId));
+  }
+  map.clear();
+  await Promise.all(pending);
+}
+async function listUserSessions(presence, findRooms, userId, options = {}) {
+  const reconcile = options.reconcile === true;
+  const removeStale = reconcile && options.removeStale === true;
+  let raw;
+  try {
+    raw = await presence.hgetall(userRoomsKey(userId));
+  } catch {
+    return [];
+  }
+  const fields = Object.keys(raw);
+  if (fields.length === 0) {
+    return [];
+  }
+  const staleSessions = [];
+  const parsed = [];
+  for (const sessionId of fields) {
+    try {
+      parsed.push({ sessionId, entry: JSON.parse(raw[sessionId]) });
+    } catch {
+      staleSessions.push(sessionId);
+    }
+  }
+  if (!reconcile) {
+    return parsed.map(({ sessionId, entry }) => ({ sessionId, ...entry }));
+  }
+  const live = parsed.length > 0 ? await findRooms(parsed.map((p) => p.entry.roomId)) : /* @__PURE__ */ new Map();
+  const result = [];
+  for (const { sessionId, entry } of parsed) {
+    const room = live.get(entry.roomId);
+    if (!room) {
+      staleSessions.push(sessionId);
+      continue;
+    }
+    const info = { sessionId, ...entry };
+    if (room.processId !== void 0) {
+      info.processId = room.processId;
+    }
+    result.push(info);
+  }
+  if (removeStale && staleSessions.length > 0) {
+    const key = userRoomsKey(userId);
+    void Promise.all(
+      staleSessions.map((s) => presence.hdel(key, s))
+    ).catch(() => {
+    });
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  USER_ROOMS_KEY_PREFIX,
+  listUserSessions,
+  releaseRoomLeave,
+  releaseUserSession,
+  sweepRoomDispose,
+  trackRoomJoin,
+  trackUserSession,
+  userRoomsKey
+});

package/build/utils/UserSessionIndex.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/UserSessionIndex.ts"],
+  "sourcesContent": ["/**\n * User \u2192 active sessions index: \"which active rooms is user X in?\"\n *\n * Without this, answering that question would require fanning out\n * `getInspectorView()` across every running room \u2014 O(rooms) per lookup.\n * Instead, each Room writes a small Presence hash entry on `_onJoin` and\n * removes it on `_onAfterLeave` / dispose. The admin endpoint reads the\n * hash with a single `hgetall`, then reconciles against the matchmaker's\n * live room listing to drop stale entries left behind by hard crashes\n * (no `onLeave` ran).\n *\n * Hash schema:\n *   key:   colyseus:user-rooms:{userId}\n *   field: sessionId\n *   value: JSON `{ roomId, roomName, joinedAt }` (joinedAt is unix ms)\n *\n * Anonymous clients (no userId resolvable) are skipped \u2014 the index is\n * for forensic / support workflows, not anonymous traffic. A Room can\n * also opt out wholesale by setting `trackUserSessions = false` (e.g.\n * a high-volume relay room that doesn't want to pay the Presence\n * write per join).\n *\n * Per-Room state (which sessionIds have an entry, and under which userId)\n * lives in a module-level WeakMap rather than as a field on Room itself.\n * Two reasons:\n *\n *   1. Room.ts stays thin \u2014 it only knows about three call points\n *      (`trackRoomJoin`, `releaseRoomLeave`, `sweepRoomDispose`) and\n *      doesn't have to carry an extra Map field or two private helper\n *      methods solely for this concern.\n *   2. The WeakMap is GC-tied to the Room \u2014 when a Room instance is\n *      collected, its entries vanish automatically. No explicit teardown\n *      hook needed beyond the dispose sweep that drains Presence.\n *\n * @internal\n */\nimport type { Presence } from '../presence/Presence.ts';\n\nexport const USER_ROOMS_KEY_PREFIX = 'colyseus:user-rooms:';\n\nexport function userRoomsKey(userId: string): string {\n  return USER_ROOMS_KEY_PREFIX + userId;\n}\n\n/**\n * What's serialized into the Presence hash value (sessionId is the\n * hash field key, not part of the body). Internal write-side shape.\n */\nexport interface UserRoomEntry {\n  roomId: string;\n  roomName: string;\n  joinedAt: number;\n}\n\n/**\n * Public read-side shape returned by `listUserSessions`: a parsed\n * `UserRoomEntry` plus its sessionId, optionally enriched with\n * `processId` when reconcile against the matchmaker was on.\n */\nexport interface UserSessionInfo extends UserRoomEntry {\n  sessionId: string;\n  /**\n   * Process hosting the room, per the matchmaker. Populated only\n   * when `listUserSessions` was called with `reconcile: true` AND\n   * the room is still in the matchmaker roster.\n   */\n  processId?: string;\n}\n\n/**\n * Structural subset of `Room` needed by the index. Lets this module\n * avoid importing `Room` (which would create a cycle) while still\n * staying typed at the call site.\n */\ninterface InspectorRoomShape {\n  roomId: string;\n  roomName: string;\n  presence: Presence;\n}\n\n/**\n * Structural subset of a Client we read at join/leave. `userId` and\n * `auth` are both optional \u2014 the index simply skips clients without\n * either, which is the correct \"anonymous traffic doesn't show up\n * in support tooling\" behavior.\n */\ninterface InspectorClientShape {\n  sessionId: string;\n  userId?: string;\n  auth?: { id?: string } | null;\n}\n\n/**\n * sessionId \u2192 userId for clients currently registered in the index,\n * scoped per Room. WeakMap-keyed so a forgotten Room takes its tracking\n * map with it.\n */\nconst tracked = new WeakMap<InspectorRoomShape, Map<string, string>>();\n\nfunction getTrackingMap(room: InspectorRoomShape): Map<string, string> {\n  let map = tracked.get(room);\n  if (!map) {\n    map = new Map();\n    tracked.set(room, map);\n  }\n  return map;\n}\n\nfunction resolveUserId(client: InspectorClientShape): string | undefined {\n  return client.userId ?? client.auth?.id;\n}\n\n/**\n * Best-effort: write the join entry. Errors are swallowed because the\n * index is observability metadata \u2014 a Presence outage shouldn't reject\n * a player's join. Exposed as a pure helper for tests + the admin\n * endpoint; `trackRoomJoin` is the Room-flavored entrypoint.\n */\nexport async function trackUserSession(\n  presence: Presence,\n  userId: string,\n  sessionId: string,\n  entry: UserRoomEntry,\n): Promise<void> {\n  try {\n    await presence.hset(userRoomsKey(userId), sessionId, JSON.stringify(entry));\n  } catch {\n    // intentional: see fn-doc\n  }\n}\n\n/**\n * Best-effort: remove the join entry. Errors are swallowed so a Presence\n * blip doesn't bubble into `_onAfterLeave` / `_dispose`.\n */\nexport async function releaseUserSession(\n  presence: Presence,\n  userId: string,\n  sessionId: string,\n): Promise<void> {\n  try {\n    await presence.hdel(userRoomsKey(userId), sessionId);\n  } catch {\n    // intentional: see fn-doc\n  }\n}\n\n/**\n * Record `client`'s join under `room` in the reverse index. No-op for\n * clients with no resolvable userId (anonymous), and when the room\n * carries no presence (shouldn't happen \u2014 defensive for unit tests).\n *\n * Fire-and-forget against Presence; the in-memory tracking map updates\n * synchronously so a follow-up `releaseRoomLeave` always finds the\n * right userId even if the Presence write is still in flight.\n */\nexport function trackRoomJoin(room: InspectorRoomShape, client: InspectorClientShape): void {\n  if (!room.presence) { return; }\n  const userId = resolveUserId(client);\n  if (!userId) { return; }\n  getTrackingMap(room).set(client.sessionId, userId);\n  const entry: UserRoomEntry = {\n    roomId: room.roomId,\n    roomName: room.roomName,\n    joinedAt: Date.now(),\n  };\n  void trackUserSession(room.presence, userId, client.sessionId, entry);\n}\n\n/**\n * Drop `client`'s entry from the reverse index. Idempotent \u2014 no-op\n * when the client wasn't tracked (anonymous, or tracking failed at\n * join time).\n */\nexport function releaseRoomLeave(room: InspectorRoomShape, client: InspectorClientShape): void {\n  if (!room.presence) { return; }\n  const map = tracked.get(room);\n  const userId = map?.get(client.sessionId);\n  if (!userId || !map) { return; }\n  map.delete(client.sessionId);\n  void releaseUserSession(room.presence, userId, client.sessionId);\n}\n\n/**\n * Sweep any still-tracked sessions for `room`. Called during dispose to\n * cover the case where `disconnect()` races the per-client `_onAfterLeave`\n * path \u2014 the read-side reconcile handles cross-process crash recovery,\n * but this is the cheap deterministic cleanup for a clean local dispose.\n *\n * Awaits the pending `hdel`s so the caller can sequence against \"the\n * index is now coherent\" \u2014 the dispose path uses that ordering.\n */\nexport async function sweepRoomDispose(room: InspectorRoomShape): Promise<void> {\n  if (!room.presence) { return; }\n  const map = tracked.get(room);\n  if (!map || map.size === 0) { return; }\n  const pending: Promise<void>[] = [];\n  for (const [sessionId, userId] of map) {\n    pending.push(releaseUserSession(room.presence, userId, sessionId));\n  }\n  map.clear();\n  await Promise.all(pending);\n}\n\n/**\n * Minimal shape of a matchmaker room record needed for reconcile \u2014\n * keeps this module decoupled from the matchmaker / driver types.\n * `matchMaker.query()`'s actual return (`IRoomCache[]`) is structurally\n * a supertype of this, so callers can pass `matchMaker.query` directly.\n */\ninterface MatchmakerRoomLike {\n  roomId: string;\n  processId?: string;\n}\n\nexport interface ListUserSessionsOptions {\n  /**\n   * Drop entries whose `roomId` is no longer in the matchmaker roster\n   * (the index can lag a crashed process). When `true`, the returned\n   * entries also carry `processId` from the live room record.\n   *\n   * Off by default \u2014 most callers (kick everyone, count) don't need it\n   * and the extra `matchMaker.query` round-trip isn't free.\n   */\n  reconcile?: boolean;\n\n  /**\n   * Fire-and-forget `hdel` for stale entries \u2014 those dropped by\n   * reconcile (matchmaker doesn't know the room anymore) plus any\n   * with corrupt JSON. Lets read endpoints self-heal the index on\n   * each call. No-op when `reconcile` is `false`.\n   */\n  removeStale?: boolean;\n}\n\n/**\n * Read the user \u2192 active sessions index. Pure helper \u2014 the\n * `Presence` + matchmaker batch lookup are injected so this module\n * stays free of matchmaker imports (and so unit tests can drive it\n * with fake deps).\n *\n * Wire-op count per call:\n *   - 1 HGETALL on the user's hash (always).\n *   - 1 batch room lookup when `reconcile: true` AND there are\n *     entries to verify; skipped otherwise.\n *\n * Bounded at 2 wire ops regardless of the user's session count.\n */\nexport async function listUserSessions(\n  presence: Presence,\n  findRooms: (roomIds: string[]) => Promise<Map<string, MatchmakerRoomLike>>,\n  userId: string,\n  options: ListUserSessionsOptions = {},\n): Promise<UserSessionInfo[]> {\n  const reconcile = options.reconcile === true;\n  const removeStale = reconcile && options.removeStale === true;\n\n  let raw: Record<string, string>;\n  try {\n    raw = await presence.hgetall(userRoomsKey(userId));\n  } catch {\n    // Presence outage \u2014 observability shouldn't bring down the caller.\n    return [];\n  }\n  const fields = Object.keys(raw);\n  if (fields.length === 0) { return []; }\n\n  const staleSessions: string[] = [];\n  const parsed: Array<{ sessionId: string; entry: UserRoomEntry }> = [];\n  for (const sessionId of fields) {\n    try {\n      parsed.push({ sessionId, entry: JSON.parse(raw[sessionId]) as UserRoomEntry });\n    } catch {\n      // Corrupt JSON \u2014 index drift. Removable even without reconcile.\n      staleSessions.push(sessionId);\n    }\n  }\n\n  if (!reconcile) {\n    return parsed.map(({ sessionId, entry }) => ({ sessionId, ...entry }));\n  }\n\n  // One batch lookup for the K roomIds we care about. K = entries\n  // surviving the JSON.parse stage, not cluster size.\n  const live = parsed.length > 0\n    ? await findRooms(parsed.map((p) => p.entry.roomId))\n    : new Map<string, MatchmakerRoomLike>();\n\n  const result: UserSessionInfo[] = [];\n  for (const { sessionId, entry } of parsed) {\n    const room = live.get(entry.roomId);\n    if (!room) {\n      // Matchmaker doesn't know this roomId anymore \u2014 stale entry\n      // from a crashed process. Drop it (and remove if requested).\n      staleSessions.push(sessionId);\n      continue;\n    }\n    const info: UserSessionInfo = { sessionId, ...entry };\n    if (room.processId !== undefined) { info.processId = room.processId; }\n    result.push(info);\n  }\n\n  if (removeStale && staleSessions.length > 0) {\n    const key = userRoomsKey(userId);\n    void Promise.all(\n      staleSessions.map((s) => presence.hdel(key, s)),\n    ).catch(() => { /* presence outage, swallow */ });\n  }\n\n  return result;\n}\n"],
+  "mappings": "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",
+  "names": []
+}