@yyyu-star/arcade-kit 0.19.1 → 0.20.1

package/src/client.ts

@@ -17,7 +17,7 @@
  * 浏览器里的计时器（重连、心跳）可以用 setTimeout，"只用一个闹钟"是房间（Durable Object）那边的规矩。
  */
 import { type ChatSendResult, checkChat } from './chat.js';
-import { type ChattedMsg, CLOSE, CLOSE_REASON, type CreateError, type DownMsg, type EmotedMsg, isFinalClose, PING, PONG, PROTOCOL_VERSION, type RoomInfo, type UpMsg } from './protocol.js';
+import { type ChattedMsg, CLOSE, CLOSE_REASON, type CreateError, type DownMsg, type EmotedMsg, isFinalClose, type MatchDownMsg, type MatchSoloWhy, PING, PONG, PROTOCOL_VERSION, type RoomInfo, type UpMsg } from './protocol.js';
 
 export type ClientStatus = 'connecting' | 'open' | 'reconnecting' | 'closed' | 'failed';
 
@@ -547,6 +547,123 @@ export function closeText(code: number, reason?: string, overrides: RoomTexts =
   return overrides[key] ?? ROOM_TEXT[key];
 }
 
+// ---------- 快速匹配（0.20.0，docs/match.md） ----------
+
+export type { MatchSoloWhy };
+
+export interface MatchClientOptions {
+  /** 排队地址（游戏 Worker 接 acceptMatch 的那条路由，ws:// 或 wss://，带上档位） */
+  url: string;
+  /** 人数变了：n 是排着几个人（含自己），seats 一桌最多几个真人，leftMs 离"不等了"还剩多久（页面自己倒计时） */
+  onWaiting?(n: number, seats: number, leftMs: number): void;
+  /** 凑成一桌了：用 code 照常进房（RoomClient），这条排队连接已经关了 */
+  onMatched(code: string): void;
+  /** 不排了，转本机单机（同档位）；why 给页面挑一句话（MATCH_TEXT） */
+  onSolo(why: MatchSoloWhy): void;
+  /** 已经有一个开着的房间：带他回去（不给就当 onMatched） */
+  onHasRoom?(code: string): void;
+  /** 排队最多等多久（毫秒，和排队那边的 waitMs 一样，默认 15 秒）：没收到人数推送时，兜底计时按它算 */
+  waitMs?: number;
+  WebSocketImpl?: { new (url: string): WebSocketLike };
+}
+
+/**
+ * 兜底（安全审阅 0.20.0）：排队那边到点了还没给结果（平台、房间卡住，或者连接静默死掉），再多等这么久就自己转单机（unavailable），
+ * 不让页面一直停在"等待中"
+ */
+export const MATCH_GRACE_MS = 10_000;
+
+/** 转单机时给玩家看的话（游戏可以换掉个别措辞） */
+export const MATCH_TEXT: Record<MatchSoloWhy, string> = {
+  alone: '现在没人在排，先和电脑打',
+  daily_limit: '今天联机局数用完了，先和电脑打',
+  busy: '联机人多，先和电脑打',
+  unavailable: '暂时排不了，先和电脑打',
+  too_often: '排得太频繁了，先和电脑打一局',
+  replaced: '你在别的页面排上了，这里不排了',
+};
+
+/**
+ * 快速匹配的连接器：start() 连上就是在排，cancel() 关掉就是不排了。断线不重连：排队不值得重连，直接 onSolo('unavailable')。
+ * 结果只回一次（matched、solo、has_room 三选一），之后什么都不回调
+ */
+export class MatchClient {
+  private ws: WebSocketLike | null = null;
+  private done = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly opts: MatchClientOptions) {}
+
+  start(): void {
+    if (this.ws || this.done) return;
+    this.arm((this.opts.waitMs ?? 15_000) + MATCH_GRACE_MS);
+    const Impl = this.opts.WebSocketImpl ?? (globalThis.WebSocket as unknown as { new (url: string): WebSocketLike });
+    const ws = new Impl(this.opts.url);
+    this.ws = ws;
+    ws.onmessage = (ev) => {
+      if (typeof ev.data !== 'string' || ev.data === PONG) return;
+      let m: MatchDownMsg;
+      try {
+        m = JSON.parse(ev.data) as MatchDownMsg;
+      } catch {
+        return;
+      }
+      if (m.t === 'waiting') {
+        if (this.done) return;
+        this.arm(m.left + MATCH_GRACE_MS);
+        this.opts.onWaiting?.(m.n, m.seats, m.left);
+      } else if (m.t === 'matched') this.end(() => this.opts.onMatched(m.code));
+      else if (m.t === 'has_room') this.end(() => (this.opts.onHasRoom ?? this.opts.onMatched)(m.code));
+      else if (m.t === 'solo') this.end(() => this.opts.onSolo(m.why));
+    };
+    ws.onclose = (ev) => {
+      const why: MatchSoloWhy = ev.code === CLOSE.replaced ? 'replaced' : ev.code === CLOSE.tooManyJoins ? 'too_often' : ev.code === CLOSE.tryLater ? 'busy' : 'unavailable';
+      this.end(() => this.opts.onSolo(why));
+    };
+    ws.onerror = () => {};
+  }
+
+  /** 不排了（"取消"或"不等了，和电脑打"）：关掉连接，之后不再回调 */
+  cancel(): void {
+    this.done = true;
+    this.disarm();
+    const ws = this.ws;
+    this.ws = null;
+    try {
+      ws?.close(1000, 'cancel');
+    } catch {
+      // 已经关了
+    }
+  }
+
+  private end(fn: () => void): void {
+    if (this.done) return;
+    this.done = true;
+    this.disarm();
+    this.ws = null;
+    fn();
+  }
+
+  /** 到点还没有结果：关掉连接，自己转单机 */
+  private arm(ms: number): void {
+    this.disarm();
+    this.timer = setTimeout(() => {
+      const ws = this.ws;
+      this.end(() => this.opts.onSolo('unavailable'));
+      try {
+        ws?.close(1000, 'no answer');
+      } catch {
+        // 已经关了
+      }
+    }, Math.max(0, ms));
+  }
+
+  private disarm(): void {
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = null;
+  }
+}
+
 // ---------- 有没有平台（0.10.0，独立部署时页面降级用） ----------
 
 /**

package/src/fun-logic.ts

@@ -443,6 +443,19 @@ export function pickLane(freeAt: readonly number[], now: number): number {
  * 上面两个角从屏幕高度的 9% 往下：几个游戏的顶栏（回大厅、设置）都在那一条里，kit 不知道它们的位置
  */
 export function placeDock(view: { width: number; height: number }, w: number, h: number, avoid: readonly Box[] = [], margin = 12): { left: number; top: number } {
+  const { left, top } = dockSpot(view, w, h, avoid, margin);
+  return { left, top };
+}
+
+/**
+ * 四个角里有没有一个一点都不压禁区（0.20.0）：没有的话，玩家又没自己展开过，电脑版聊天框默认收成"聊天"小按钮。
+ * 掼蛋 1280×720 上四个角都放不下，压得最少的左上角正好盖住左家的头像，点不到他、也看不到剩几张
+ */
+export function dockFits(view: { width: number; height: number }, w: number, h: number, avoid: readonly Box[] = [], margin = 12): boolean {
+  return dockSpot(view, w, h, avoid, margin).cost === 0;
+}
+
+function dockSpot(view: { width: number; height: number }, w: number, h: number, avoid: readonly Box[], margin: number): { left: number; top: number; cost: number } {
   const l = margin;
   const r = Math.max(margin, view.width - margin - w);
   const t = Math.max(margin, Math.round(view.height * 0.09));
@@ -457,7 +470,7 @@ export function placeDock(view: { width: number; height: number }, w: number, h:
       if (cost === 0) break;
     }
   }
-  return best;
+  return { ...best, cost: bestCost };
 }
 
 /**

package/src/game.ts

@@ -209,3 +209,43 @@ export function snapshotBytes<S, A, V, O, E extends RoomEffect>(game: RoomGame<S
   }
   return max;
 }
+
+/**
+ * 快速匹配的配置对不对得上房间（0.20.0，安全审阅）：每个开放的档位，排队那边的 tableSize（一桌几个真人）和 roomOptions（开桌带的选项）
+ * 要过得了这张桌的 RoomGame。对不上的话房间每桌都回 bad / bad_options、排到的人都转单机，线上只看得到日志。
+ * 游戏在自己的测试里调：`expect(matchConfigErrors(game, tiers, (t) => queue.tableSize(t), (t) => queue.roomOptions(t))).toEqual([])`。
+ * 返回每个问题一句话，没问题是空数组。纯函数，不碰运行时（普通 Node 测试能用）
+ */
+export function matchConfigErrors<S, A, V, O, E extends RoomEffect>(
+  game: RoomGame<S, A, V, O, E>,
+  tiers: readonly string[],
+  tableSize: (tier: string) => number,
+  roomOptions: (tier: string) => unknown = () => undefined,
+): string[] {
+  const out: string[] = [];
+  for (const tier of tiers) {
+    const raw = roomOptions(tier);
+    let opts: O | undefined;
+    if (raw !== undefined) {
+      if (!game.options) {
+        out.push(`${tier}: roomOptions given but the game has no options()`);
+        continue;
+      }
+      const o = game.options(raw);
+      if (o === null) {
+        out.push(`${tier}: roomOptions rejected by game.options()`);
+        continue;
+      }
+      opts = o;
+    } else if (game.options && game.options(undefined) === null) {
+      out.push(`${tier}: game.options() needs roomOptions for this tier`);
+      continue;
+    }
+    const count = game.seatCount ? game.seatCount(opts) : game.seats;
+    const size = tableSize(tier);
+    if (!Number.isInteger(size) || size < 2) out.push(`${tier}: tableSize ${size} must be an integer ≥ 2`);
+    else if (size > count) out.push(`${tier}: tableSize ${size} is more than the ${count} seats this table plays`);
+    else if (size > 9) out.push(`${tier}: tableSize ${size} is more than 9 (blockedAmong limit)`);
+  }
+  return out;
+}

package/src/internal.ts

@@ -73,3 +73,11 @@ export const LIMITED_HEADER = 'x-kit-limited';
 export function meterStub(ns: DurableObjectNamespace): DurableObjectStub {
   return ns.get(ns.idFromName(METER_NAME), { locationHint: 'apac' });
 }
+
+/** 快速匹配的排队（0.20.0）：每个档位一个实例，和房间一样放在亚太 */
+export function matchStub(ns: DurableObjectNamespace, tier: string): DurableObjectStub {
+  return ns.get(ns.idFromName(`kit-match:${tier}`), { locationHint: 'apac' });
+}
+
+/** 档位 key 的格式：游戏给的短字符串（如 real-2、fun-normal） */
+export const TIER_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;

package/src/match.ts

@@ -0,0 +1,371 @@
+/**
+ * 快速匹配的排队（0.20.0，设计 docs/match.md）：游戏 Worker 里的 Durable Object 继承它，填上一桌几个真人，就能按档位排队凑桌。
+ * 每个档位一个实例（matchStub 按档位取），浏览器经 worker.ts 的 acceptMatch 连进来，连接本身就是"排着"。
+ *
+ * 守的规矩（和房间同一套，docs/platform-backend.md 第 4 节）：
+ * - 0 行存储：排着的人就是 ctx.getWebSockets()，附件里只放 userId、昵称、开始排的时间；被驱逐后名单还在；
+ * - 只用一个闹钟：最早那个人等满 waitMs 的时刻，只往早了调（setAlarm 也算一行写入）；
+ * - 只用 ctx.acceptWebSocket，不用 setTimeout / setInterval；排队连接只收不发，浏览器发什么都 1008 断开；
+ * - 不碰牌局：不 import 规则、不读房间状态。电脑补位、公平底线全在房间里，和好友房一样；
+ * - 名额由房间开桌时向计量一次占齐（kitCreateMatch），排队本身不占。
+ */
+import { DurableObject } from 'cloudflare:workers';
+import { type Identity, KIT_HOST, newRoomCode, parseIdentity, roomStub } from './internal.js';
+import { CLOSE, type MatchDownMsg, type MatchSoloWhy } from './protocol.js';
+import type { MatchOutcome } from './room.js';
+
+export type { MatchDownMsg, MatchSoloWhy } from './protocol.js';
+
+/** 排队对象要的绑定：房间 ROOM（开桌），平台 ARCADE（可选，屏蔽名单；单独部署没有） */
+export interface MatchEnv {
+  ROOM: DurableObjectNamespace;
+  ARCADE?: Fetcher;
+}
+
+interface Waiter {
+  userId: string;
+  name: string;
+  /** 开始排的时间（毫秒） */
+  since: number;
+  /** 档位（一个实例只有一个档位；放在附件里，被驱逐后闹钟醒来还知道） */
+  tier: string;
+}
+
+/** 开桌时房间码撞了最多再换几次 */
+const CODE_TRIES = 5;
+/** 一次凑桌最多重来几轮（有人被计量挡掉、请出去以后接着凑） */
+const FORM_ROUNDS = 8;
+/** 平台屏蔽名单一次最多问几个人（平台 blockedAmong 的上限，德州 9 人桌） */
+const BLOCK_MAX = 9;
+/**
+ * 凑桌时找平台、找房间最多等多久（毫秒，安全审阅 0.20.0）：凑桌持着"正在凑"的锁，平台或房间卡住时整个档位都会一直"等待中"。
+ * 超时的屏蔽名单按空的算，建房按 unavailable（这一桌的人转单机）
+ */
+export const MATCH_CALL_MS = 3_000;
+
+export abstract class MatchQueue<Env extends MatchEnv = MatchEnv> extends DurableObject<Env> {
+  /** 一桌最多几个真人（凑满就开）。按档位不同的游戏覆盖 tableSize */
+  protected abstract readonly seats: number;
+  /** 最多等多久（毫秒）：到点 ≥ 2 人就开，只剩自己就转单机 */
+  protected readonly waitMs: number = 15_000;
+  /** 一个档位最多排几个人，满了 1013（挡刷连接） */
+  protected readonly maxQueue: number = 200;
+  /** 每人每小时最多排几次，超了 4029（内存里记，被驱逐就清零，接受） */
+  protected readonly perHour: number = 30;
+  /** 凑桌时找平台、找房间最多等多久（毫秒，见 MATCH_CALL_MS） */
+  protected readonly callMs: number = MATCH_CALL_MS;
+
+  /** 这个档位一桌最多几个真人；默认 seats */
+  protected tableSize(_tier: string): number {
+    return this.seats;
+  }
+
+  /** 这个档位开桌带的开局选项（交给房间的 RoomGame.options 校验）；默认不带 */
+  protected roomOptions(_tier: string): unknown {
+    return undefined;
+  }
+
+  /**
+   * 这几个人之间谁屏蔽了谁（平台 0.25.0 的 ARCADE.blockedAmong，最多 9 人，只读）。没有平台（单独部署）、出错都当没有，回 []。
+   * 测试覆盖它换成假名单
+   */
+  protected async blockedAmong(userIds: string[]): Promise<[string, string][]> {
+    const arcade = this.env.ARCADE as unknown as { blockedAmong?: (ids: unknown) => Promise<unknown> } | undefined;
+    if (!arcade || userIds.length < 2) return [];
+    try {
+      const out = await arcade.blockedAmong!(userIds.slice(0, BLOCK_MAX));
+      return Array.isArray(out) ? out.filter((p): p is [string, string] => Array.isArray(p) && typeof p[0] === 'string' && typeof p[1] === 'string') : [];
+    } catch (e) {
+      console.error('blockedAmong failed, matching without it', e instanceof Error ? e.message : e);
+      return [];
+    }
+  }
+
+  /** 开一张匹配桌（房间的 kitCreateMatch）。游戏不用覆盖；kit 的测试用它模拟房间卡住 */
+  protected createMatchRoom(code: string, players: Identity[], opts: unknown): Promise<MatchOutcome> {
+    const stub = roomStub(this.env.ROOM, code) as unknown as { kitCreateMatch(code: string, players: Identity[], opts?: unknown): Promise<MatchOutcome> };
+    return stub.kitCreateMatch(code, players, opts);
+  }
+
+  /** 现在设着的闹钟；undefined 是还不知道，用前 getAlarm() 读 */
+  private alarmAt: number | null | undefined;
+  /** 正在凑桌（中间 await 了平台和房间）：这时进来的人、到点的闹钟只记一笔，凑完再来一轮 */
+  private forming = false;
+  private again = false;
+  /** 凑桌途中已经选中的人：别的一轮不再选他们 */
+  private readonly taken = new Set<string>();
+  /** 每人这一小时排了几次 */
+  private readonly hourly = new Map<string, number[]>();
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair('ping', 'pong'));
+  }
+
+  /** 入队：只认 kit 自己拼的内部地址（worker.ts 的 acceptMatch），身份在 x-kit-user 头里。 */
+  override async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.hostname !== KIT_HOST || url.pathname !== '/match' || request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
+      return new Response('not a kit request', { status: 400 });
+    }
+    const me = parseIdentity(request.headers.get('x-kit-user'));
+    const tier = url.searchParams.get('tier');
+    if (!me || !tier) return new Response('no identity', { status: 401 });
+    const pair = new WebSocketPair();
+    const [client, server] = [pair[0], pair[1]];
+    this.ctx.acceptWebSocket(server);
+    const done = new Response(null, { status: 101, webSocket: client });
+    const now = Date.now();
+    // 只数还排着的（附件还在）：已经出队、正在关的连接不占队长
+    const others = this.waiting().filter((o) => o !== server);
+    const mine = others.filter((o) => waiterOf(o)?.userId === me.userId);
+    if (others.length - mine.length >= this.maxQueue) {
+      server.close(CLOSE.tryLater, 'queue full');
+      return done;
+    }
+    // 一小时前的旧条目顺手清掉（排过一次就走的人不能让这张表一直涨）
+    for (const [u, ts] of this.hourly) if (now - ts[ts.length - 1]! >= 3_600_000) this.hourly.delete(u);
+    const times = (this.hourly.get(me.userId) ?? []).filter((t) => now - t < 3_600_000);
+    if (times.length >= this.perHour) {
+      this.hourly.set(me.userId, times);
+      server.close(CLOSE.tooManyJoins, 'too often');
+      return done;
+    }
+    times.push(now);
+    this.hourly.set(me.userId, times);
+    // 同一个人只排一次：旧的那条让位
+    for (const o of mine) this.drop(o, CLOSE.replaced, 'replaced');
+    server.serializeAttachment({ userId: me.userId, name: me.name, since: now, tier } satisfies Waiter);
+    // 先回 101 再凑桌：凑桌要找平台、房间，不能让新来的人连连接都拿不到
+    this.ctx.waitUntil(this.form());
+    return done;
+  }
+
+  /** 排队连接只收不发：发什么都断开（不让它变成能刷的入口） */
+  override async webSocketMessage(ws: WebSocket): Promise<void> {
+    this.drop(ws, CLOSE.policy, 'queue is receive-only');
+    this.pushWaiting();
+  }
+
+  override async webSocketClose(ws: WebSocket, code: number): Promise<void> {
+    try {
+      ws.close(code === 1005 || code === 1006 ? 1000 : code, 'bye');
+    } catch {
+      // 已经关了
+    }
+    ws.serializeAttachment(null);
+    this.pushWaiting();
+  }
+
+  override async webSocketError(ws: WebSocket): Promise<void> {
+    ws.serializeAttachment(null);
+    this.pushWaiting();
+  }
+
+  override async alarm(): Promise<void> {
+    this.alarmAt = null;
+    try {
+      await this.form();
+    } catch (e) {
+      // 闹钟里不往外抛（会自动重试、每次计费）
+      console.error('match alarm failed', e instanceof Error ? e.message : e);
+    }
+  }
+
+  // ---------- 凑桌 ----------
+
+  /**
+   * 凑一轮：凑满一桌立刻开；最早的人等够了：≥ 2 人就开，只剩自己转单机。凑完还有人就把闹钟对到下一个人。
+   * 凑桌中间要 await（平台、房间），这时别的入口进来只记 again，凑完再来一轮
+   */
+  private async form(): Promise<void> {
+    if (this.forming) {
+      this.again = true;
+      return;
+    }
+    this.forming = true;
+    try {
+      let rounds = 0;
+      do {
+        this.again = false;
+        while (rounds++ < FORM_ROUNDS && (await this.formOnce()));
+      } while (this.again && rounds < FORM_ROUNDS);
+    } finally {
+      this.forming = false;
+      this.taken.clear();
+    }
+    this.pushWaiting();
+    await this.planAlarm();
+  }
+
+  /** 凑一桌；凑出了（或者有人被请出去了）回 true，接着凑下一桌 */
+  private async formOnce(): Promise<boolean> {
+    const list = this.queue().filter((w) => !this.taken.has(w.me.userId));
+    if (!list.length) return false;
+    const tier = list[0]!.me.tier;
+    const size = Math.max(1, Math.min(this.tableSize(tier), BLOCK_MAX));
+    const due = Date.now() >= list[0]!.me.since + this.waitMs;
+    if (list.length < size && !due) return false;
+    const blocks = await withTimeout(this.blockedAmong(list.slice(0, BLOCK_MAX).map((w) => w.me.userId)), this.callMs).catch((e: unknown) => {
+      console.error('blockedAmong timed out, matching without it', e instanceof Error ? e.message : e);
+      return [] as [string, string][];
+    });
+    const chosen: typeof list = [];
+    for (const w of list.slice(0, BLOCK_MAX)) {
+      if (chosen.length >= size) break;
+      if (chosen.some((c) => blocks.some(([a, b]) => (a === c.me.userId && b === w.me.userId) || (a === w.me.userId && b === c.me.userId)))) continue;
+      chosen.push(w);
+    }
+    if (chosen.length < size && !due) return false;
+    if (chosen.length < 2) {
+      // 等够了却只有自己（或者在的人都和他互相屏蔽）：转单机
+      this.solo(chosen[0]!.ws, 'alone');
+      return true;
+    }
+    for (const c of chosen) this.taken.add(c.me.userId);
+    const players: Identity[] = chosen.map((c) => ({ userId: c.me.userId, name: c.me.name }));
+    let out: MatchOutcome = { r: 'unavailable' };
+    let code = '';
+    for (let i = 0; i < CODE_TRIES; i++) {
+      code = newRoomCode();
+      try {
+        out = await withTimeout(this.createMatchRoom(code, players, this.roomOptions(tier)), this.callMs);
+      } catch (e) {
+        console.error('kitCreateMatch failed', e instanceof Error ? e.message : e);
+        out = { r: 'unavailable' };
+      }
+      if (out.r !== 'exists') break;
+    }
+    for (const c of chosen) this.taken.delete(c.me.userId);
+    // 等的这一会儿可能有人走了、换了页面：按 userId 找他现在的连接
+    const sockOf = (userId: string) => this.waiting().find((ws) => waiterOf(ws)?.userId === userId);
+    if (out.r === 'created') {
+      for (const c of chosen) {
+        const ws = sockOf(c.me.userId);
+        if (ws) this.finish(ws, { t: 'matched', code });
+      }
+      return true;
+    }
+    if (out.r === 'refused') {
+      if (out.userId === null) {
+        // 全站忙：这一轮的人都转单机，其他人留着（到点还会被同样挡掉）
+        for (const c of chosen) {
+          const ws = sockOf(c.me.userId);
+          if (ws) this.solo(ws, 'busy');
+        }
+        return true;
+      }
+      const ws = sockOf(out.userId);
+      if (ws) {
+        if (out.why === 'has_room') this.finish(ws, { t: 'has_room', code: out.code });
+        else this.solo(ws, 'daily_limit');
+        return true;
+      }
+      return true;
+    }
+    // 房间那边出错、超时、选项不对：这一轮的人转单机，不让他们一直等。
+    // bad / bad_options 是游戏配错了（tableSize 比这一局的座位多、roomOptions 过不了 RoomGame.options），每桌都会这样：
+    // 大声记日志；游戏在自己的测试里用 game.ts 的 matchConfigErrors 先查
+    if (out.r === 'bad' || out.r === 'bad_options') console.error(`MatchQueue misconfigured for tier ${tier}: room said ${out.r} (check tableSize / roomOptions with matchConfigErrors)`);
+    else console.error('match room not created', out.r);
+    for (const c of chosen) {
+      const ws = sockOf(c.me.userId);
+      if (ws) this.solo(ws, 'unavailable');
+    }
+    // 房间那边不好（超时、出错）：这一次不接着凑，剩下的人等下一次闹钟，不让锁一直被连着的超时占着
+    this.again = false;
+    return false;
+  }
+
+  /** 只往早了调闹钟：最早那个人等够的时刻 */
+  private async planAlarm(): Promise<void> {
+    const list = this.queue();
+    if (!list.length) return;
+    const next = list[0]!.me.since + this.waitMs;
+    if (this.alarmAt === undefined) this.alarmAt = await this.ctx.storage.getAlarm();
+    if (this.alarmAt !== null && this.alarmAt <= next && this.alarmAt > Date.now() - 1_000) return;
+    this.alarmAt = next;
+    try {
+      await this.ctx.storage.setAlarm(next);
+    } catch (e) {
+      console.error('match setAlarm failed', e instanceof Error ? e.message : e);
+      this.alarmAt = undefined;
+    }
+  }
+
+  // ---------- 连接 ----------
+
+  private sockets(): WebSocket[] {
+    return this.ctx.getWebSockets();
+  }
+
+  private waiting(): WebSocket[] {
+    return this.sockets().filter((ws) => waiterOf(ws) !== null);
+  }
+
+  /** 排着的人，按开始排的先后；同一个人只算最新的那条 */
+  private queue(): { ws: WebSocket; me: Waiter }[] {
+    const by = new Map<string, { ws: WebSocket; me: Waiter }>();
+    for (const ws of this.waiting()) {
+      const me = waiterOf(ws)!;
+      const had = by.get(me.userId);
+      if (!had || had.me.since <= me.since) by.set(me.userId, { ws, me });
+    }
+    return [...by.values()].sort((a, b) => a.me.since - b.me.since);
+  }
+
+  /** 人数变了就推一次（不每秒推，页面自己倒计时） */
+  private pushWaiting(): void {
+    const list = this.queue();
+    if (!list.length) return;
+    // 倒计时按最早的那个人算：他到点时大家一起凑，后来的人等不满 waitMs
+    const left = Math.max(0, list[0]!.me.since + this.waitMs - Date.now());
+    const msg: MatchDownMsg = { t: 'waiting', n: list.length, seats: this.tableSize(list[0]!.me.tier), left };
+    for (const { ws } of list) send(ws, msg);
+  }
+
+  private solo(ws: WebSocket, why: MatchSoloWhy): void {
+    this.finish(ws, { t: 'solo', why });
+  }
+
+  /** 发最后一条，出队、关掉 */
+  private finish(ws: WebSocket, msg: MatchDownMsg): void {
+    send(ws, msg);
+    this.drop(ws, 1000, msg.t);
+  }
+
+  private drop(ws: WebSocket, code: number, reason: string): void {
+    ws.serializeAttachment(null);
+    try {
+      ws.close(code, reason);
+    } catch {
+      // 已经关了
+    }
+  }
+}
+
+function waiterOf(ws: WebSocket): Waiter | null {
+  const a = ws.deserializeAttachment() as Waiter | null | undefined;
+  return a && typeof a.userId === 'string' ? a : null;
+}
+
+function send(ws: WebSocket, msg: MatchDownMsg): void {
+  try {
+    ws.send(JSON.stringify(msg));
+  } catch {
+    // 连接正在关
+  }
+}
+
+/**
+ * 等一个外部调用最多 ms 毫秒，超时抛错（调用方按失败处理）。只在凑桌这一次请求里等，不是房间的状态计时，
+ * 所以用运行时的 scheduler.wait（不是 setTimeout、也不占那一个闹钟）
+ */
+async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+  // 超时以后原来的调用照样可能失败：先接住它的错，免得变成没人处理的 rejection
+  const settled = p.then((v) => ({ ok: true as const, v }), (e: unknown) => ({ ok: false as const, e }));
+  const out = await Promise.race([settled, scheduler.wait(ms).then(() => null)]);
+  if (out === null) throw new Error(`timed out after ${ms} ms`);
+  if (!out.ok) throw out.e;
+  return out.v;
+}