@yyyu-star/arcade-kit 0.13.0 → 0.13.1

package/src/client.ts

@@ -16,7 +16,7 @@
  *
  * 浏览器里的计时器（重连、心跳）可以用 setTimeout，"只用一个闹钟"是房间（Durable Object）那边的规矩。
  */
-import { CLOSE, CLOSE_REASON, type CreateError, type DownMsg, type EmotedMsg, isFinalClose, PING, PONG, PROTOCOL_VERSION, type UpMsg } from './protocol.js';
+import { CLOSE, CLOSE_REASON, type CreateError, type DownMsg, type EmotedMsg, isFinalClose, PING, PONG, PROTOCOL_VERSION, type RoomInfo, type UpMsg } from './protocol.js';
 
 export type ClientStatus = 'connecting' | 'open' | 'reconnecting' | 'closed' | 'failed';
 
@@ -73,6 +73,13 @@ const HEARTBEAT_MS = 25_000;
 export const PONG_WAIT_MS = 8_000;
 /** 建连最多等多久（0.11.1）：卡在 CONNECTING 的按一次失败算，重连 */
 export const CONNECT_MS = 10_000;
+/**
+ * 看门狗（0.13.1）：房间说的出手时限（或停顿的结束时间）过了 STALL_GRACE_MS 再加最多 STALL_JITTER_MS 的随机抖动，还没有新状态，
+ * 就当房间的闹钟没设上（存储出错、没人发消息时房间不会自己醒），重连一次把房间叫醒：进房是房间的一个入口，它会按 getAlarm() 重排闹钟、
+ * 把过期的那一手照常处理。同一个 seq 只踢一次；抖动让一桌人里先到的那个去踢，别人收到新状态就不踢了
+ */
+export const STALL_GRACE_MS = 20_000;
+export const STALL_JITTER_MS = 10_000;
 /** 快捷短语太快时最多排几个（多的丢最早的） */
 const EMOTE_QUEUE = 2;
 
@@ -97,6 +104,9 @@ export class RoomClient<A = unknown, V = unknown> {
   private probing = false;
   private probeTimer: unknown = null;
   private connectTimer: unknown = null;
+  /** 看门狗（0.13.1）：到点还停在 watchSeq 就重连一次；kickedSeq 是踢过的，不再踢 */
+  private watchTimer: unknown = null;
+  private kickedSeq = -1;
   /** 没收到 ack 的操作：重连后按原 moveId 重发 */
   private pending = new Map<string, UpMsg<A>>();
   private moveCounter = 0;
@@ -254,11 +264,13 @@ export class RoomClient<A = unknown, V = unknown> {
         this.welcomed = true;
         this.attempt = 0;
         this.failures = 0;
+        this.watch(ws, msg);
       } else if (msg.t === 'state') {
         const mine = msg.ack !== undefined && this.pending.delete(msg.ack);
         // 旧的、重复的丢掉（ack 已经处理过了）。例外：别人看不出来的一步（0.7.1，quiet），房间只回给我、seq 不加，第一次收到要交给页面
         if (msg.seq < this.lastSeq || (msg.seq === this.lastSeq && !(mine && msg.quiet === true))) return;
         this.lastSeq = msg.seq;
+        this.watch(ws, msg);
       } else if (msg.t === 'error' && msg.moveId) {
         // 被拒的操作不再重发
         this.pending.delete(msg.moveId);
@@ -316,6 +328,25 @@ export class RoomClient<A = unknown, V = unknown> {
     }, PONG_WAIT_MS);
   }
 
+  /**
+   * 看门狗：按房间给的时间（now）算出手时限还剩多久，过了宽限还停在这个 seq，就扔掉连接重连一次（见 STALL_GRACE_MS）。
+   * 没在打、没有时限、旧房间不带 now 的不看；同一个 seq 踢过一次就不再踢（房间还是不动，就等真人出手或下一次进出）
+   */
+  private watch(ws: WebSocketLike, msg: { seq: number; room: RoomInfo; now?: number }): void {
+    if (this.watchTimer !== null) this.opts.clearTimer(this.watchTimer);
+    this.watchTimer = null;
+    const until = msg.room.turn?.deadline ?? msg.room.pause?.until;
+    if (msg.room.status !== 'playing' || until == null || typeof msg.now !== 'number' || msg.seq === this.kickedSeq) return;
+    const seq = msg.seq;
+    const wait = Math.max(0, until - msg.now) + STALL_GRACE_MS + Math.round(this.opts.random() * STALL_JITTER_MS);
+    this.watchTimer = this.opts.setTimer(() => {
+      this.watchTimer = null;
+      if (this.ws !== ws || this.lastSeq !== seq || ws.readyState !== OPEN) return;
+      this.kickedSeq = seq;
+      this.abandon(ws);
+    }, wait);
+  }
+
   /** 带上这次的关闭码：游戏据此区分"网络断了"（1006）和"平台有点忙"（1013）。 */
   private scheduleRetry(code: number): void {
     this.setStatus('reconnecting', code);
@@ -365,8 +396,8 @@ export class RoomClient<A = unknown, V = unknown> {
   }
 
   private clearTimers(): void {
-    for (const t of [this.retryTimer, this.emoteTimer, this.beatTimer, this.probeTimer, this.connectTimer]) if (t !== null) this.opts.clearTimer(t);
-    this.retryTimer = this.emoteTimer = this.beatTimer = this.probeTimer = this.connectTimer = null;
+    for (const t of [this.retryTimer, this.emoteTimer, this.beatTimer, this.probeTimer, this.connectTimer, this.watchTimer]) if (t !== null) this.opts.clearTimer(t);
+    this.retryTimer = this.emoteTimer = this.beatTimer = this.probeTimer = this.connectTimer = this.watchTimer = null;
     this.probing = false;
   }
 

package/src/protocol.ts

@@ -185,6 +185,11 @@ export interface WelcomeMsg<V = unknown> {
   you: You;
   room: RoomInfo;
   view: V | null;
+  /**
+   * 房间发这条消息时的时间（毫秒，0.13.1）：RoomClient 拿它和 room.turn.deadline 算"还剩多久"，不用浏览器自己的钟（可能差几分钟）。
+   * 用来发现房间的闹钟没设上、到点了却没人推进（见 RoomClient 的看门狗）。旧房间不带
+   */
+  now?: number;
   /**
    * 快捷短语的节奏（0.7.0，游戏有短语时才带）：每 ms 毫秒补 1 个令牌、最多攒 burst 个。RoomClient 按它在本地排队发，
    * 用户感觉不到限速；运维在 KIT_QUOTA 里改，不用发版
@@ -201,6 +206,8 @@ export interface StateMsg<V = unknown> {
   /** 至少一帧；最后一帧就是当前状态 */
   frames: Frame<V>[];
   ack?: string;
+  /** 同 WelcomeMsg.now（0.13.1） */
+  now?: number;
   /**
    * 别人看不出来的一步（0.7.1）：不轮流的操作没改任何别人能看到的东西（比如声明窗口里真人答"碰"），房间只回给出手的人、seq 不加（和上一条一样）。
    * 只和 ack 一起出现；RoomClient 0.7.1 起认它（seq 一样也交给页面），旧的 RoomClient 当重复丢掉

package/src/room.ts

@@ -119,6 +119,8 @@ export const DEFAULT_LIMITS: RoomLimits = {
 
 /** 闹钟里出错时，过这么久再醒来重试（不用"马上"，免得每次都出错时连着计费）。 */
 const ALARM_RETRY_MS = 60_000;
+/** setAlarm 一次最多试几回（0.13.1）：存储一时出错当场再试一次，不等下一个入口 */
+const SET_ALARM_TRIES = 2;
 /** 每个座位记住最近几个做成的 moveId（0.11.1）：客户端断线时攒着没确认的操作，重连后原样补发 */
 const RECENT_MOVES = 8;
 
@@ -461,26 +463,56 @@ export abstract class GameRoom<S, A, V, Env = unknown, O = unknown, E extends Ro
     this.totalWrites += this.writes;
     this.unmetered += this.writes;
     this.maxStepWrites = Math.max(this.maxStepWrites, this.writes);
-    if (at !== null && !(await this.setAlarmSafely(at))) this.lastStepFailed = true;
+    if (at !== null && !(await this.setAlarmSafely(at))) {
+      this.lastStepFailed = true;
+      await this.recoverAlarm();
+    }
     await this.afterStep();
     return out;
   }
 
   /**
-   * 设闹钟；失败了不往外抛（0.11.1）。planAlarm 已经把 alarmAt 改成了新时间，失败时它就是错的：
-   * 留着的话以后 planAlarm 看"已经设了更早的"一直不重设，房间就没人收场。改回"不知道"，下一个入口按 getAlarm() 重新读、照常重排
+   * 这一步要设的闹钟两次都没设上（0.13.1，第三轮审计）：按 getAlarm() 核对存储里还有没有闹钟（以前设的更早的那个可能还在）；
+   * 有就以它为准，没有而房间还在，就补一个 ALARM_RETRY_MS 后的，醒来时 onAlarm 按状态重新算（到点的照常处理）。
+   * 以前只靠下一个入口重排：全是电脑、大家都在等时限的房间没人发消息，就一直停着，不关房、结回也不重试。
+   * 补设也失败（存储一直坏着）就只剩浏览器的看门狗（RoomClient）重连来叫醒。读不了存储时不抛（入口里不往外抛）
    */
-  private async setAlarmSafely(at: number): Promise<boolean> {
+  private async recoverAlarm(): Promise<void> {
     try {
-      await this.ctx.storage.setAlarm(at);
-      return true;
+      if (!this.load()) return;
+      const cur = await this.ctx.storage.getAlarm();
+      if (cur !== null) {
+        this.alarmAt = cur;
+        return;
+      }
+      // 不另记一行：这一步的那次 setAlarm 已经记过了，它没写成，补设的这次顶替它
+      this.alarmAt = Date.now() + ALARM_RETRY_MS;
+      await this.setAlarmSafely(this.alarmAt);
     } catch (e) {
-      console.error('room setAlarm failed', e instanceof Error ? e.message : e);
+      console.error('room alarm recovery failed', e instanceof Error ? e.message : e);
       this.alarmAt = undefined;
-      return false;
     }
   }
 
+  /**
+   * 设闹钟；失败了不往外抛（0.11.1）。存储一时出错大多下一次就好，所以当场再试一次（0.13.1）；还不行：
+   * planAlarm 已经把 alarmAt 改成了新时间，失败时它就是错的，留着的话以后 planAlarm 看"已经设了更早的"一直不重设，房间就没人收场。
+   * 改回"不知道"，下一个入口（任何消息、进房、闹钟）按 getAlarm() 重新读、照常重排。
+   * 一直没人发消息（全是电脑在打、大家都在等时限）时，下一个入口由浏览器的看门狗给（RoomClient：时限过了很久还没有新状态就重连一次）
+   */
+  private async setAlarmSafely(at: number): Promise<boolean> {
+    for (let i = 0; i < SET_ALARM_TRIES; i++) {
+      try {
+        await this.ctx.storage.setAlarm(at);
+        return true;
+      } catch (e) {
+        console.error('room setAlarm failed', i + 1, e instanceof Error ? e.message : e);
+      }
+    }
+    this.alarmAt = undefined;
+    return false;
+  }
+
   // ---------- 计量（0.2.0） ----------
 
   /**
@@ -1584,6 +1616,7 @@ export abstract class GameRoom<S, A, V, Env = unknown, O = unknown, E extends Ro
       you: { seat, bound },
       room: this.roomInfo(),
       view: st.game === null ? null : this.game.view(st.game, seat),
+      now: Date.now(),
       // 有短语的游戏告诉页面限速的节奏（0.7.0），RoomClient 按它排队，用户感觉不到限速
       ...(hasEmotes(this.game.emotes) ? { emote: this.emoteRate() } : {}),
     };
@@ -1592,7 +1625,7 @@ export abstract class GameRoom<S, A, V, Env = unknown, O = unknown, E extends Ro
   private stateMsg(seat: number | null, bound: number | null, frames: { state: S | null; delay: number }[], ack?: string, quiet = false): DownMsg<V> {
     const st = this.st!;
     const out: Frame<V>[] = frames.map((f) => ({ view: (f.state === null ? null : this.game.view(f.state, seat)) as V, delay: f.delay }));
-    return { t: 'state', seq: st.seq, you: { seat, bound }, room: this.roomInfo(), frames: out, ...(ack ? { ack } : {}), ...(quiet ? { quiet: true as const } : {}) };
+    return { t: 'state', seq: st.seq, you: { seat, bound }, room: this.roomInfo(), frames: out, now: Date.now(), ...(ack ? { ack } : {}), ...(quiet ? { quiet: true as const } : {}) };
   }
 
   /** 按座位过滤后广播：同一个座位（加上绑定的座位，没入座的人各自不同）的消息只算一次。只发给已经收到快照（有 attachment）的连接。 */

package/src/table-fun.ts

@@ -49,8 +49,20 @@ export interface FunSeat {
   temper?: FunTemper;
 }
 
+/**
+ * storageKey 的检查（0.13.1）：它就是游戏 id，kit 拿它拼 `<id>.hint.fun`、`<id>.fun.blocked`。同站的几个游戏和平台只靠 `<id>.` 前缀分开存储，
+ * 所以只认游戏 id 的写法（小写字母、数字、连字符，字母或数字开头，最多 32 位）；带点（"guandan." 会拼出 "guandan..fun"）、大写、空串、
+ * 平台自己的前缀 arcade 都不行。不合格直接抛错：同一个字符串每次都一样，开发时第一次打开牌桌就看得到，不会带到线上
+ */
+export function checkStorageKey(key: unknown): string {
+  if (typeof key !== 'string' || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(key) || key === 'arcade') {
+    throw new Error(`arcade-kit/table-fun: storageKey 要写游戏 id（比如 "mygame"，存成 "mygame.hint.fun"），收到 ${JSON.stringify(key)}`);
+  }
+  return key;
+}
+
 export interface TableFunOptions {
-  /** 游戏 id：首次提示、屏蔽名单的存储 key 前缀（`<id>.hint.fun`、`<id>.fun.blocked`） */
+  /** 游戏 id：首次提示、屏蔽名单的存储 key 前缀（`<id>.hint.fun`、`<id>.fun.blocked`）；不是游戏 id 的写法构造时就抛错（checkStorageKey） */
   storageKey: string;
   /** 本游戏的短语表（编号 0..P-1，见 fun-logic 的 funItem） */
   phrases: readonly string[];
@@ -165,6 +177,8 @@ export class TableFun {
   private readonly onResize = (): void => this.refresh();
 
   constructor(opts: TableFunOptions) {
+    // 先查 key 再碰 DOM：不合格的不留下半个界面
+    checkStorageKey(opts.storageKey);
     this.o = opts;
     this.P = opts.phrases.length;
     this.doc = document;