@yyyu-star/arcade-kit 0.0.0-stage → 0.10.2

package/src/testing.ts

@@ -0,0 +1,300 @@
+/**
+ * 测试和本地试用的假平台钱包（0.8.0，不部署）：游戏的 workerd 测试、冒烟、本地 `wrangler dev` 里代替平台的钱包，各游戏共用这一份。
+ *
+ * 只复刻游戏碰得到的接口形状和关键规则，不复刻平台的细枝末节（计量、熔断档、流水、战绩怎么存、管理员调规则）：
+ * - `WalletService`：游戏经服务绑定调的四个方法（docs/platform-backend.md 5.9"给游戏的 RPC"）。绑定的 `props.game` 必须写，
+ *   参数里的 `game` 要和它一致，不然 `bad_game`。这里不维护游戏名单：平台认不认这个游戏是平台的事，假钱包只核对两边一致；
+ * - `FakeBank`：一人一个 DO，存钱包（5.9"存储"的简化）。带入、结回、放弃按 `游戏:ref` 一份一份（5.9"带入""结回"）：
+ *   只结一次（结完再结 `no_stake`）、余额够这次才能带（`no_funds`）、同一个 `ref` 补码要同档同 mode、操作 id 按游戏去重（`dup`）、
+ *   到期原样退回（`expired`）、client 模式每个游戏每天净赢最多 `WIN_UNITS` 份（`capped`）；
+ * - 结回带的小结 `stats` 按 5.10 的上限检查（JSON ≤ 256 字节、必填字段、称号和自定义数的格式），不合格回 `statsIgnored`、钱照常结；
+ *   收下的记在 `FakeBank.stats` 里给测试核对；
+ * - `walletHttp`：浏览器的 `GET /api/wallet`、`POST /api/wallet/relief`（15.9），认平台的会话 cookie，cookie 的值就当 userId。
+ *
+ * 平台改了钱包接口（参数、错误码、规则），平台 PR 的描述里写"影响 kit/testing"，由维护者安排 kit 跟上；一个 PR 只改一个模块。
+ *
+ * 游戏怎么接：测试 Worker 的主模块 `export { FakeBank, WalletService } from 'arcade-kit/testing'`，wrangler 配置里
+ * 加 DO 绑定 `FAKE_BANK`（class_name `FakeBank`），`WALLET` 服务绑定指回这个 Worker 自己：
+ * `{ "binding": "WALLET", "service": "<测试 Worker 名>", "entrypoint": "WalletService", "props": { "game": "<游戏 id>" } }`。
+ */
+import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
+import { SESSION_COOKIE } from './internal.js';
+
+/** 新号送多少、补给补到多少、client 模式每天净赢最多几份：平台的默认值（5.9，管理员可调的那几个数按默认算） */
+export const NEW_BALANCE = 10_000;
+export const RELIEF_TO = 2_000;
+export const WIN_UNITS = 10;
+/** 各档一份多少（economy.md 第 2 节） */
+export const TIERS = { small: 2_000, mid: 10_000, big: 50_000, lux: 200_000 } as const;
+export type Tier = keyof typeof TIERS;
+export type Mode = 'server' | 'client';
+
+const DAY_MS = 86_400_000;
+const ID = /^[A-Za-z0-9_-]{8,64}$/;
+/** 结回最多是带上桌的加 20 份（平台只防写错） */
+const SETTLE_EXTRA_UNITS = 20;
+
+export interface Stake {
+  game: string;
+  ref: string;
+  tier: Tier;
+  amount: number;
+  mode: Mode;
+  at: number;
+  until: number;
+}
+
+export interface WalletView {
+  balance: number;
+  stakes: Stake[];
+  canRelief: boolean;
+  writesLeft: number;
+  caps: Record<string, { net: number; cap: number }>;
+  fresh: boolean;
+}
+
+export type WalletReply =
+  | { ok: true; wallet: WalletView; credited?: number; capped?: number; dup?: true; statsIgnored?: StatsProblem }
+  | { ok: false; error: string; wallet?: WalletView };
+
+export type StatsProblem = 'too_big' | 'bad_stats';
+
+export interface FakeEnv {
+  FAKE_BANK: DurableObjectNamespace<FakeBank>;
+}
+
+interface State {
+  balance: number;
+  /** 桌上的筹码，key 是 `游戏:ref` */
+  stakes: Record<string, Stake>;
+  reliefDay: string;
+  /** client 模式当天每个游戏的带入、结回（算净赢）和带入过的最高档 */
+  day: string;
+  cin: Record<string, number>;
+  cout: Record<string, number>;
+  top: Record<string, Tier>;
+  /** `游戏:op` → 第一次的结果 */
+  ops: Record<string, Done>;
+  /** 到期退回过的 `游戏:ref` */
+  expired: string[];
+  fresh: boolean;
+}
+
+type Done = { ok: true; credited?: number; capped?: number; statsIgnored?: StatsProblem };
+type Cmd = { t: 'buyin' | 'settle' | 'refund'; game: string; ref: string; tier?: Tier; amount?: number; until?: number; mode: Mode; op: string; stats?: unknown };
+
+const beijingDay = (now: number): string => new Date(now + 8 * 3_600_000).toISOString().slice(0, 10);
+const onTable = (s: State): number => Object.values(s.stakes).reduce((n, k) => n + k.amount, 0);
+
+export class FakeBank extends DurableObject {
+  /** 被调了几次、写了几次：测试数游戏调平台几次、平台写几行 */
+  calls = 0;
+  writes = 0;
+  /** 结回带上来的小结，按先后记在内存里；不合格的记 ignored */
+  stats: { game: string; ref: string; stats: unknown; ignored?: StatsProblem }[] = [];
+
+  private async load(now: number): Promise<State> {
+    const s =
+      (await this.ctx.storage.get<State>('w')) ??
+      ({ balance: NEW_BALANCE, stakes: {}, reliefDay: '', day: '', cin: {}, cout: {}, top: {}, ops: {}, expired: [], fresh: true } satisfies State);
+    const day = beijingDay(now);
+    if (s.day !== day) Object.assign(s, { day, cin: {}, cout: {}, top: {} });
+    // 到期的那一份原样退回，记下 `游戏:ref`（最近 16 个）
+    for (const [key, k] of Object.entries(s.stakes)) {
+      if (k.until > now) continue;
+      s.balance += k.amount;
+      if (k.mode === 'client') s.cin[k.game] = Math.max(0, (s.cin[k.game] ?? 0) - k.amount);
+      s.expired = [...s.expired, key].slice(-16);
+      delete s.stakes[key];
+    }
+    return s;
+  }
+
+  private async save(s: State): Promise<void> {
+    this.writes++;
+    // 操作 id 只留最近 32 个
+    const ops = Object.entries(s.ops);
+    if (ops.length > 32) s.ops = Object.fromEntries(ops.slice(-32));
+    await this.ctx.storage.put('w', { ...s, fresh: false });
+  }
+
+  private view(s: State): WalletView {
+    const caps: WalletView['caps'] = {};
+    for (const g of Object.keys(s.cin)) caps[g] = { net: (s.cout[g] ?? 0) - (s.cin[g] ?? 0), cap: WIN_UNITS * TIERS[s.top[g] ?? 'small'] };
+    return {
+      balance: s.balance,
+      stakes: Object.values(s.stakes),
+      canRelief: s.balance + onTable(s) < RELIEF_TO && s.reliefDay !== s.day,
+      writesLeft: 1_000,
+      caps,
+      fresh: s.fresh,
+    };
+  }
+
+  async look(now: number): Promise<WalletView> {
+    this.calls++;
+    return this.view(await this.load(now));
+  }
+
+  /** 只给测试用：直接把余额设成这个数（比如造一个只有 500 的人），不算调用和写入 */
+  async setBalance(balance: number, now: number): Promise<void> {
+    const s = await this.load(now);
+    s.balance = balance;
+    await this.ctx.storage.put('w', { ...s, fresh: false });
+  }
+
+  async run(c: Cmd, now: number): Promise<WalletReply> {
+    this.calls++;
+    const s = await this.load(now);
+    const key = `${c.game}:${c.op}`;
+    const before = s.ops[key];
+    if (before) return { ...before, wallet: this.view(s), dup: true };
+    const r = this.apply(s, c, now);
+    if (!r.ok) return { ...r, wallet: this.view(s) };
+    if (c.t === 'settle' && c.stats !== undefined) {
+      const ignored = statsProblem(c.stats);
+      this.stats.push({ game: c.game, ref: c.ref, stats: c.stats, ...(ignored ? { ignored } : {}) });
+      if (ignored) r.statsIgnored = ignored;
+    }
+    s.ops[key] = r;
+    await this.save(s);
+    return { ...r, wallet: this.view(s) };
+  }
+
+  private apply(s: State, c: Cmd, now: number): Done | { ok: false; error: string } {
+    const sk = `${c.game}:${c.ref}`;
+    const k = s.stakes[sk];
+    if (c.t === 'buyin') {
+      const tier = c.tier!;
+      const amount = c.amount!;
+      if (amount < 1 || amount > TIERS[tier]) return { ok: false, error: 'bad_amount' };
+      if (c.until! <= now) return { ok: false, error: 'bad_until' };
+      if (s.expired.includes(sk)) return { ok: false, error: 'expired' };
+      if (k && k.tier !== tier) return { ok: false, error: 'at_table' };
+      if (k && k.mode !== c.mode) return { ok: false, error: 'bad_mode' };
+      // 新开一份、补码都只要余额够这次的数（平台 0.10.2）
+      if (s.balance < amount) return { ok: false, error: 'no_funds' };
+      const until = Math.min(c.until!, now + DAY_MS);
+      if (k) {
+        k.amount += amount;
+        k.until = Math.max(k.until, until);
+      } else {
+        s.stakes[sk] = { game: c.game, ref: c.ref, tier, amount, mode: c.mode, at: now, until };
+      }
+      s.balance -= amount;
+      if (!s.top[c.game] || TIERS[tier] > TIERS[s.top[c.game]!]) s.top[c.game] = tier;
+      if (c.mode === 'client') s.cin[c.game] = (s.cin[c.game] ?? 0) + amount;
+      return { ok: true };
+    }
+    if (!k) return { ok: false, error: s.expired.includes(sk) ? 'expired' : 'no_stake' };
+    if (k.mode !== c.mode) return { ok: false, error: 'bad_mode' };
+    if (c.t === 'refund') {
+      delete s.stakes[sk];
+      s.balance += k.amount;
+      if (k.mode === 'client') s.cin[c.game] = Math.max(0, (s.cin[c.game] ?? 0) - k.amount);
+      return { ok: true, credited: k.amount };
+    }
+    const amount = c.amount!;
+    if (amount > k.amount + SETTLE_EXTRA_UNITS * TIERS[k.tier]) return { ok: false, error: 'bad_amount' };
+    delete s.stakes[sk];
+    let credited = amount;
+    if (k.mode === 'client') {
+      // 当天净赢最多 WIN_UNITS 份；带上桌的那一份总能拿回来
+      const room = WIN_UNITS * TIERS[s.top[c.game] ?? k.tier] - ((s.cout[c.game] ?? 0) - (s.cin[c.game] ?? 0));
+      credited = Math.min(amount, Math.max(room, Math.min(amount, k.amount)));
+      s.cout[c.game] = (s.cout[c.game] ?? 0) + credited;
+    }
+    s.balance += credited;
+    return credited < amount ? { ok: true, credited, capped: amount - credited } : { ok: true, credited };
+  }
+
+  /** 领补给（15.9）：余额加桌上的不到补给额、今天没领过，补到补给额（平台 0.10.2 起桌上有筹码也能领） */
+  async relief(now: number): Promise<{ status: number; body: { error?: string; wallet: WalletView } }> {
+    this.calls++;
+    const s = await this.load(now);
+    const total = s.balance + onTable(s);
+    if (total >= RELIEF_TO) return { status: 409, body: { error: 'relief_not_needed', wallet: this.view(s) } };
+    if (s.reliefDay === s.day) return { status: 409, body: { error: 'relief_used', wallet: this.view(s) } };
+    s.balance += RELIEF_TO - total;
+    s.reliefDay = s.day;
+    await this.save(s);
+    return { status: 200, body: { wallet: this.view({ ...s, fresh: false }) } };
+  }
+}
+
+const bank = (env: FakeEnv, userId: string) => env.FAKE_BANK.get(env.FAKE_BANK.idFromName(userId));
+
+/** 平台给游戏的 RPC（5.9）：绑定写 `entrypoint: "WalletService"`、`props: { game }` */
+export class WalletService extends WorkerEntrypoint<FakeEnv, { game?: string }> {
+  async view(userId: string): Promise<WalletReply> {
+    if (!this.bound()) return { ok: false, error: 'bad_game' };
+    return { ok: true, wallet: await bank(this.env, userId).look(Date.now()) };
+  }
+  buyin(req: unknown): Promise<WalletReply> {
+    return this.op('buyin', req);
+  }
+  settle(req: unknown): Promise<WalletReply> {
+    return this.op('settle', req);
+  }
+  refund(req: unknown): Promise<WalletReply> {
+    return this.op('refund', req);
+  }
+
+  private bound(): string | null {
+    const g = this.ctx.props?.game;
+    return typeof g === 'string' && g !== '' ? g : null;
+  }
+
+  private async op(t: Cmd['t'], req: unknown): Promise<WalletReply> {
+    const game = this.bound();
+    // 平台先查绑定和 game，参数不对也先回这个
+    if (!game || (req as { game?: unknown } | null)?.game !== game) return { ok: false, error: 'bad_game' };
+    const q = req as Record<string, unknown>;
+    const okId = (x: unknown) => typeof x === 'string' && ID.test(x);
+    const okNum = (x: unknown) => typeof x === 'number' && Number.isSafeInteger(x) && x >= 0;
+    if (typeof q.userId !== 'string' || q.userId === '' || !okId(q.ref) || !okId(q.op) || (q.mode !== 'server' && q.mode !== 'client')) return { ok: false, error: 'bad_request' };
+    if (t === 'buyin' && (!(typeof q.tier === 'string' && Object.hasOwn(TIERS, q.tier)) || !okNum(q.amount) || !okNum(q.until))) return { ok: false, error: 'bad_request' };
+    if (t === 'settle' && !okNum(q.amount)) return { ok: false, error: 'bad_request' };
+    const cmd: Cmd = { t, game, ref: q.ref as string, mode: q.mode as Mode, op: q.op as string };
+    if (t === 'buyin') Object.assign(cmd, { tier: q.tier as Tier, amount: q.amount as number, until: q.until as number });
+    if (t === 'settle') Object.assign(cmd, { amount: q.amount as number, ...(q.stats !== undefined ? { stats: q.stats } : {}) });
+    return bank(this.env, q.userId).run(cmd, Date.now());
+  }
+}
+
+/** 5.10 的检查：JSON 后 ≤ 256 字节；rounds、wins、best 非负整数；称号最多 5 个、格式；max + sum 最多 3 个 key、值是安全整数 */
+export function statsProblem(x: unknown): StatsProblem | undefined {
+  if (JSON.stringify(x).length > 256) return 'too_big';
+  const o = x as Record<string, unknown> | null;
+  const nat = (v: unknown) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+  if (!o || typeof o !== 'object' || !nat(o.rounds) || !nat(o.wins) || !nat(o.best)) return 'bad_stats';
+  const id = /^[a-z][a-z0-9_]{0,23}$/;
+  if (o.titles !== undefined && !(Array.isArray(o.titles) && o.titles.length <= 5 && o.titles.every((t) => typeof t === 'string' && id.test(t)))) return 'bad_stats';
+  let keys = 0;
+  for (const k of ['max', 'sum'] as const) {
+    const m = o[k];
+    if (m === undefined) continue;
+    if (!m || typeof m !== 'object') return 'bad_stats';
+    for (const [key, v] of Object.entries(m)) {
+      if (!/^[a-z][a-z0-9_]{0,15}$/.test(key) || typeof v !== 'number' || !Number.isSafeInteger(v)) return 'bad_stats';
+      keys++;
+    }
+  }
+  return keys > 3 ? 'bad_stats' : undefined;
+}
+
+/** 浏览器的钱包接口（15.9）：认平台的会话 cookie（值就当 userId）；不是这两条路回 null，调用方接着处理别的 */
+export async function walletHttp(request: Request, env: FakeEnv): Promise<Response | null> {
+  const url = new URL(request.url);
+  if (url.pathname !== '/api/wallet' && url.pathname !== '/api/wallet/relief') return null;
+  const sid = new RegExp(`${SESSION_COOKIE}=([^;]+)`).exec(request.headers.get('cookie') ?? '')?.[1];
+  if (!sid) return Response.json({ error: 'login' }, { status: 401 });
+  if (url.pathname === '/api/wallet') {
+    if (request.method !== 'GET') return Response.json({ error: 'method' }, { status: 405 });
+    return Response.json({ wallet: await bank(env, sid).look(Date.now()), tiers: TIERS, reliefTo: RELIEF_TO, winUnits: WIN_UNITS });
+  }
+  if (request.method !== 'POST') return Response.json({ error: 'method' }, { status: 405 });
+  if (request.headers.get('x-arcade') !== '1') return Response.json({ error: 'forbidden' }, { status: 403 });
+  const r = await bank(env, sid).relief(Date.now());
+  return Response.json(r.body, { status: r.status });
+}

package/src/worker.ts

@@ -0,0 +1,234 @@
+/**
+ * 游戏 Worker 里开房、进房的两个入口：校验房间码、查 Origin、经平台 /api/me 认人、再找房间，打包在一起。
+ * 游戏只要把路由接到这两个函数上，不用自己碰浏览器的原始请求，也就没有机会把它（连同浏览器自己带的头）原样转给房间。
+ *
+ * 进房被拒时不回 4xx：浏览器的 WebSocket 拿不到 HTTP 状态码，只会看到"连不上"，然后一直重连。
+ * 这里先接受升级、马上用关闭码关掉，客户端认得这些码：4401 没登录、4403 别的网站、4004 没有这个房间都不再重连
+ * （房间自己还会回 4503：今天联机额度快满了，不进新人）；
+ * 平台暂时不可用是 1013（稍后再试），客户端按退避重连。
+ * 独立模式（0.10.0，guest.ts）：没有 ARCADE 绑定、GATE 也不是 login 时认游客 cookie（开房时没有就现发一个），
+ * 浏览器可以在开房、进房的地址上带 ?name=<昵称>；有 ARCADE 绑定时和以前完全一样。
+ * 这是普通 Worker，不是房间，没有 ctx.acceptWebSocket，只能用 server.accept()；连接接受了马上关，不留着。
+ */
+import { identify, sameOrigin } from './auth.js';
+import { type GuestOptions, isStandalone, type ModeEnv } from './guest.js';
+import { CLOSE, type CreateError, ROOM_CODE_RE } from './protocol.js';
+import { identityHeader, type Identity, KIT_HOST, newRoomCode, roomStub } from './internal.js';
+import type { MeterEnv } from './meter.js';
+import type { CreateOutcome } from './room.js';
+
+/**
+ * 游戏 Worker 的绑定名固定：房间 ROOM，平台 ARCADE（登录闸门已经用这个名字），计量 METER、门槛 KIT_QUOTA（0.2.0，meter.ts）。
+ * METER 是房间自己用的（开房占名额、报写入），这里列出来是为了游戏的 Env 一眼看全
+ */
+export interface KitEnv extends MeterEnv {
+  ROOM: DurableObjectNamespace;
+  ARCADE?: Fetcher;
+  /** "login" 表示这次部署必须接平台（0.10.0）：没绑 ARCADE 时按平台不可用拒绝，不退成游客模式 */
+  GATE?: string;
+}
+
+export interface GateOptions {
+  /**
+   * Origin 只认这个站点（比如 https://<你的站点>）。不给就认请求自己的 origin（0.9.0）：浏览器从哪个站点打开页面、连的就是哪个站点，
+   * 别的网站的页面带来的 Origin 对不上。游戏可以把部署时注入的 SITE_ORIGIN 变量传进来，设了就按它
+   */
+  siteOrigin?: string;
+  /** 默认是请求所在站点的 /api/me */
+  meUrl?: string;
+  /** 独立模式的游客设置（cookie 名、游戏电脑人物的名字当保留昵称，0.10.0）；平台模式不看 */
+  guest?: GuestOptions;
+}
+
+/** 认人：按部署方式（identify），昵称取地址里的 ?name= */
+function who(request: Request, env: KitEnv, opts: GateOptions, mint: boolean) {
+  return identify(request, env, {
+    ...(opts.meUrl ? { meUrl: opts.meUrl } : {}),
+    ...(opts.guest ? { guest: opts.guest } : {}),
+    mint,
+    nickname: new URL(request.url).searchParams.get('name'),
+  });
+}
+
+export interface CreateOptions extends GateOptions {
+  /**
+   * 开房时就定下的开局选项（0.4.0，可选）：游戏 Worker 从开房请求里取出来原样传进来，房间用 RoomGame.options 校验，
+   * 不合格回 400 bad_options、不占名额也不建房间。定下以后不能再改：进房的人都看得到（RoomInfo.opts），开打时 start 带的 opts 不看。
+   * 不带就和以前一样，由房主开打时的 start 定
+   */
+  options?: unknown;
+}
+
+/**
+ * 开房：POST。成功 201 { code }；失败回 JSON { error, code? }（protocol.ts 的 CreateError）：
+ * 别的网站 403 forbidden；没登录 401 login；这个人已经有开着的房间 409 has_room（带那个房间的码）；今天开房次数用完 429 daily_limit；
+ * 今天联机的人太多 503 busy；开房选项不合格 400 bad_options（0.4.0）；平台或计量连不上、房间码连撞 5 次、房间出错 503 unavailable。
+ * 额度由房间开房时向计量（env.METER，meter.ts）去占；没绑计量就不限额。
+ * 独立模式下没有游客 cookie 就现发一个（任何结果的回话都带上这条 Set-Cookie）。
+ */
+export async function acceptCreate(request: Request, env: KitEnv, opts: CreateOptions = {}): Promise<Response> {
+  if (request.method !== 'POST') return new Response('method not allowed', { status: 405 });
+  if (!sameOrigin(request, opts.siteOrigin)) return fail(403, 'forbidden');
+  const w = await who(request, env, opts, true);
+  if ('error' in w) return w.error === 'anonymous' ? fail(401, 'login') : fail(503, 'unavailable');
+  const me = w.user;
+  // 平台模式不转 Set-Cookie（和以前一样）；独立模式现发的游客 cookie 要带回去，不然下次进房认不出这个人
+  const cookies = isStandalone(env) ? w.setCookie : [];
+  const res = await create(env, me, opts);
+  return cookies.length ? withCookies(res, cookies) : res;
+}
+
+async function create(env: KitEnv, me: Identity, opts: CreateOptions): Promise<Response> {
+  for (let i = 0; i < 5; i++) {
+    const code = newRoomCode();
+    // 走 RPC，不走 fetch：身份是参数，不在任何请求头里
+    const stub = roomStub(env.ROOM, code) as unknown as { kitCreate(code: string, host: Identity, opts?: unknown): Promise<CreateOutcome> };
+    const out = await stub.kitCreate(code, me, opts.options);
+    switch (out.r) {
+      case 'created':
+        return Response.json({ code }, { status: 201 });
+      case 'exists':
+        continue;
+      case 'has_room':
+        return fail(409, 'has_room', out.code);
+      case 'daily_limit':
+        return fail(429, 'daily_limit');
+      case 'bad_options':
+        return fail(400, 'bad_options');
+      case 'busy':
+        return fail(503, 'busy');
+      default:
+        return fail(503, 'unavailable');
+    }
+  }
+  return fail(503, 'unavailable');
+}
+
+function fail(status: number, error: CreateError, code?: string): Response {
+  return Response.json(code ? { error, code } : { error }, { status });
+}
+
+/**
+ * 进房：WebSocket 升级。认不出人、别的网站、码不对、平台不可用，都是"接受后马上用关闭码关掉"。
+ * 独立模式下进房不发游客 cookie（101 回话上的 Set-Cookie 浏览器不一定收）：没有就 4401，页面刷新一下首页（loginGate 会发）再来
+ */
+export async function acceptJoin(request: Request, env: KitEnv, code: string, opts: GateOptions = {}): Promise<Response> {
+  if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') return new Response('websocket only', { status: 426 });
+  if (!ROOM_CODE_RE.test(code)) return refuse(CLOSE.noRoom, 'no room');
+  if (!sameOrigin(request, opts.siteOrigin)) return refuse(CLOSE.forbidden, 'bad origin');
+  const w = await who(request, env, opts, false);
+  if ('error' in w) return w.error === 'anonymous' ? refuse(CLOSE.unauthorized, 'login first') : refuse(CLOSE.tryLater, 'try later');
+  const me = w.user;
+  // 新建请求，只带认好的身份和客户端版本；浏览器带来的 x-kit-user 之类的头一律不转
+  const cv = new URL(request.url).searchParams.get('cv') ?? '0';
+  return roomStub(env.ROOM, code).fetch(`https://${KIT_HOST}/ws?cv=${encodeURIComponent(cv)}`, {
+    headers: { upgrade: 'websocket', 'x-kit-user': identityHeader(me) },
+  });
+}
+
+function refuse(code: number, reason: string): Response {
+  const pair = new WebSocketPair();
+  pair[1].accept();
+  pair[1].close(code, reason);
+  return new Response(null, { status: 101, webSocket: pair[0] });
+}
+
+/**
+ * 登录闸门要的绑定：页面的静态资源 ASSETS、平台 ARCADE；GATE 写 "off" 时不拦（本地开发试页面用）。
+ * 没有 ARCADE、GATE 也不是 "login" 是独立模式（0.10.0）：不拦，补发游客 cookie
+ */
+export interface GateEnv {
+  ASSETS: Fetcher;
+  ARCADE?: Fetcher;
+  GATE?: string;
+}
+
+export interface LoginGateOptions {
+  /** 默认是请求所在站点的 /api/me */
+  meUrl?: string;
+  /** 平台连不上时回的整页 HTML（503）；默认一个不带游戏名的通用页，游戏可以换成自己的标题和配色 */
+  downPage?: string;
+  /** 独立模式的游客设置（0.10.0）：cookie 名要和开房、进房传的一样 */
+  guest?: GuestOptions;
+}
+
+/** 平台连不上时的默认页：不写游戏名，回大厅的链接指向平台首页 */
+export const DOWN_PAGE = `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>平台暂时连不上</title>
+<style>body{margin:0;min-height:100vh;min-height:100dvh;display:grid;place-items:center;background:#1b1f2a;color:#eef0f4;font:16px/1.6 system-ui,sans-serif;text-align:center}
+a{color:#f3c86b}</style></head>
+<body><main><h1>平台暂时连不上</h1><p>稍等一会儿再刷新试试。</p><p><a href="/">回大厅</a></p></main></body></html>`;
+
+/**
+ * 游戏首页的登录闸门（0.8.0，docs/platform-backend.md 5.8、15.8）：游戏 Worker 把首页（`/games/<id>/`、`index.html`）交给它。
+ * - 登录了：放行，回 ASSETS 的页面，带上平台续期的 Set-Cookie，不缓存；
+ * - 没登录：302 到 `/login?next=<原路径和查询参数>`（平台 0.10.1 的 next，登录完整页跳回来，好友房链接的 ?room= 原样带回），同样带上 Set-Cookie；
+ * - 平台不可用：503 整页（`downPage`），`Retry-After: 30`；
+ * - `GATE` 是 "off"：不问平台，直接回页面；
+ * - 独立模式（0.10.0，没有 ARCADE、GATE 不是 "login"）：不跳登录，回页面；没有游客 cookie 就补发一个（开房、进房靠它认人）。
+ */
+export async function loginGate(request: Request, env: GateEnv, opts: LoginGateOptions = {}): Promise<Response> {
+  if (isStandalone(env)) {
+    const g = await identify(request, env, { ...(opts.guest ? { guest: opts.guest } : {}), mint: true });
+    return withCookies(await env.ASSETS.fetch(request), 'user' in g ? g.setCookie : []);
+  }
+  if (env.GATE === 'off') return env.ASSETS.fetch(request);
+  const who = await identify(request, env, opts.meUrl ? { meUrl: opts.meUrl } : {});
+  if ('user' in who) return withCookies(await env.ASSETS.fetch(request), who.setCookie);
+  if (who.error === 'anonymous') {
+    const url = new URL(request.url);
+    const next = encodeURIComponent(url.pathname + url.search);
+    return withCookies(new Response(null, { status: 302, headers: { location: `/login?next=${next}` } }), who.setCookie);
+  }
+  return new Response(opts.downPage ?? DOWN_PAGE, {
+    status: 503,
+    headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'retry-after': '30' },
+  });
+}
+
+/**
+ * 独立部署时站点根上本该归平台的两个路径（0.10.0；`/api/me` 0.10.2）。只在独立模式下回话，其余回 null，游戏接着走自己的路由：
+ * - `/`：游戏挂在 `/games/<id>/`，单独部署到 workers.dev 时有人直接打开 `/`，302 到游戏首页（查询参数原样带上）；
+ * - `/api/me`：页面的 `detectPlatform` 开局问一次。回 200 `{ standalone: true }`（没有 `user`，认作没有平台），
+ *   不让它落到静态资源回 404：404 在浏览器控制台每次都是一条红的资源加载错误。
+ * 两个路径都要先过 Worker：把 "/"、"/api/me" 加进 wrangler.jsonc 的 `assets.run_worker_first`。
+ * 本站部署时它们由平台的路由接，到不了游戏 Worker；就算到了，有平台绑定时这里也回 null
+ */
+export function standaloneRoot(request: Request, env: ModeEnv, gameId: string): Response | null {
+  const url = new URL(request.url);
+  if (!isStandalone(env) || !/^[a-z0-9-]+$/.test(gameId)) return null;
+  if (url.pathname === '/api/me') return Response.json({ standalone: true }, { headers: { 'cache-control': 'no-store' } });
+  if (url.pathname !== '/') return null;
+  return new Response(null, { status: 302, headers: { location: `/games/${gameId}/${url.search}`, 'cache-control': 'no-store' } });
+}
+
+export { isStandalone };
+
+/** 带上平台的 Set-Cookie（whoIs 给的 setCookie）；按人回的内容一律不缓存 */
+export function withCookies(res: Response, setCookie: readonly string[]): Response {
+  const out = new Response(res.body, res);
+  out.headers.set('cache-control', 'private, no-store');
+  for (const c of setCookie) out.headers.append('set-cookie', c);
+  return out;
+}
+
+/** JSON 回话，带上 Set-Cookie、不缓存 */
+export function json(body: unknown, status: number, setCookie: readonly string[] = []): Response {
+  return withCookies(Response.json(body, { status }), setCookie);
+}
+
+/**
+ * 读 JSON 请求体，读不了回 null。游戏自己的接口读请求体往往在认人之前：必须带 content-length 且 1 到 maxBytes 字节才读
+ * （分块传的大请求体不带长度，没登录的人也能让这里解析一大段）。浏览器 fetch 发字符串请求体总带 content-length
+ */
+export async function readJson(request: Request, maxBytes: number): Promise<unknown> {
+  const len = request.headers.get('content-length');
+  const n = len === null ? NaN : Number(len);
+  if (!(n > 0 && n <= maxBytes)) return null;
+  try {
+    return await request.json();
+  } catch {
+    return null;
+  }
+}