《移动游戏产品的架构·客户端与移动运行时》4.3 杀进程与异常退出的兜底

// file: src/runtime/recovery.ts
// tier: L1
// verify: node --test test/runtime/recovery.test.ts

import type { Clock } from "../core/clock.ts";

export interface FileHost {
  write(path: string, data: string, options: { readonly sync: boolean }): void;
  read(path: string): string | null;
  rename(from: string, to: string): void;
  remove(path: string): void;
  exists(path: string): boolean;
}

export interface RecoveryPaths {
  readonly primary: string;
  readonly temp: string;
  readonly dirty: string;
}

export function recoveryPaths(dir: string, name = "session"): RecoveryPaths {
  const base = dir.endsWith("/") ? dir.slice(0, -1) : dir;
  return {
    primary: `${base}/${name}.json`,
    temp: `${base}/${name}.json.tmp`,
    dirty: `${base}/${name}.dirty`,
  };
}

export interface RecordBody {
  readonly version: 1;
  readonly sessionId: string;
  readonly seq: number;
  readonly writtenAtMs: number;
  readonly payload: string;
}

export interface RecordEnvelope extends RecordBody {
  readonly checksum: string;
}

function canonicalBody(body: RecordBody): string {
  return JSON.stringify([
    body.version,
    body.sessionId,
    body.seq,
    body.writtenAtMs,
    body.payload,
  ]);
}

export function checksumOf(text: string): string {
  let hash = 0x811c9dc5;
  for (let index = 0; index < text.length; index += 1) {
    hash ^= text.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash.toString(16).padStart(8, "0");
}

export function sealRecord(body: RecordBody): RecordEnvelope {
  return { ...body, checksum: checksumOf(canonicalBody(body)) };
}

export function serializeRecord(envelope: RecordEnvelope): string {
  return `${JSON.stringify(envelope)}\n`;
}

export function parseRecord(text: string): RecordEnvelope | null {
  try {
    const parsed = JSON.parse(text) as Partial<RecordEnvelope>;
    if (
      parsed.version !== 1 ||
      typeof parsed.sessionId !== "string" ||
      typeof parsed.seq !== "number" ||
      typeof parsed.writtenAtMs !== "number" ||
      typeof parsed.payload !== "string" ||
      typeof parsed.checksum !== "string"
    ) {
      return null;
    }

    const body: RecordBody = {
      version: 1,
      sessionId: parsed.sessionId,
      seq: parsed.seq,
      writtenAtMs: parsed.writtenAtMs,
      payload: parsed.payload,
    };
    return checksumOf(canonicalBody(body)) === parsed.checksum
      ? { ...body, checksum: parsed.checksum }
      : null;
  } catch {
    return null;
  }
}

export type RecoveryProduct = "match3" | "ark";

export type RecoveryHint =
  | "resume-last-match"
  | "return-to-lobby"
  | "server-reconcile";

export interface RecoveryPolicy {
  readonly product: RecoveryProduct;
  readonly checkpointEveryMs: number;
  readonly autoResume: boolean;
  readonly hint: RecoveryHint;
}

export const MATCH3_RECOVERY: RecoveryPolicy = {
  product: "match3",
  checkpointEveryMs: 15_000,
  autoResume: true,
  hint: "resume-last-match",
};

export const ARK_RECOVERY: RecoveryPolicy = {
  product: "ark",
  checkpointEveryMs: 30_000,
  autoResume: false,
  hint: "server-reconcile",
};

export function promptFor(policy: RecoveryPolicy): string {
  if (policy.product === "match3") {
    return "检测到未正常退出的对局，可回到最近检查点继续。";
  }
  return "检测到未正常退出的战斗，请回到大厅并由服务端校验战斗令牌。";
}

export interface CleanDecision {
  readonly kind: "clean";
}

export interface RecoverDecision {
  readonly kind: "recover";
  readonly record: RecordEnvelope;
  readonly policy: RecoveryPolicy;
  readonly prompt: string;
}

export interface LostDecision {
  readonly kind: "lost";
  readonly reason: string;
}

export type RecoveryDecision = CleanDecision | RecoverDecision | LostDecision;

export class CrashRecoveryRecorder {
  #files: FileHost;
  #paths: RecoveryPaths;
  #clock: Clock;
  #policy: RecoveryPolicy;
  #sessionId: string | null = null;
  #lastCheckpointAtMs: number | null = null;

  constructor(
    files: FileHost,
    paths: RecoveryPaths,
    clock: Clock,
    policy: RecoveryPolicy,
  ) {
    this.#files = files;
    this.#paths = paths;
    this.#clock = clock;
    this.#policy = policy;
  }

  get sessionId(): string | null {
    return this.#sessionId;
  }

  get lastCheckpointAtMs(): number | null {
    return this.#lastCheckpointAtMs;
  }

  beginSession(sessionId: string): void {
    if (sessionId.length === 0) {
      throw new Error("session id must not be empty");
    }
    this.#files.write(this.#paths.dirty, sessionId, { sync: true });
    this.#sessionId = sessionId;
    this.#lastCheckpointAtMs = null;
  }

  checkpoint(seq: number, payload: string, force = false): RecordEnvelope | null {
    if (this.#sessionId === null) {
      throw new Error("beginSession must be called before checkpoint");
    }
    if (!Number.isInteger(seq) || seq < 0) {
      throw new RangeError(`checkpoint seq must be a non-negative integer: ${seq}`);
    }

    const now = this.#clock.nowMs();
    if (
      !force &&
      this.#lastCheckpointAtMs !== null &&
      now - this.#lastCheckpointAtMs < this.#policy.checkpointEveryMs
    ) {
      return null;
    }

    const envelope = sealRecord({
      version: 1,
      sessionId: this.#sessionId,
      seq,
      writtenAtMs: now,
      payload,
    });

    this.#files.write(this.#paths.temp, serializeRecord(envelope), { sync: true });
    this.#files.rename(this.#paths.temp, this.#paths.primary);
    this.#lastCheckpointAtMs = now;
    return envelope;
  }

  markCleanExit(): void {
    this.#files.remove(this.#paths.dirty);
    this.#sessionId = null;
    this.#lastCheckpointAtMs = null;
  }

  inspect(): RecoveryDecision {
    this.discardTemp();

    const dirty = this.#files.read(this.#paths.dirty);
    if (dirty === null) {
      return { kind: "clean" };
    }

    const raw = this.#files.read(this.#paths.primary);
    if (raw === null) {
      return { kind: "lost", reason: "dirty marker without checkpoint" };
    }

    const record = parseRecord(raw);
    if (record === null) {
      return { kind: "lost", reason: "checkpoint failed checksum validation" };
    }

    if (record.sessionId !== dirty) {
      return { kind: "lost", reason: "checkpoint belongs to another session" };
    }

    return {
      kind: "recover",
      record,
      policy: this.#policy,
      prompt: promptFor(this.#policy),
    };
  }

  discardTemp(): boolean {
    if (!this.#files.exists(this.#paths.temp)) {
      return false;
    }
    this.#files.remove(this.#paths.temp);
    return true;
  }

  discardRecord(): void {
    this.#files.remove(this.#paths.temp);
    this.#files.remove(this.#paths.primary);
    this.#files.remove(this.#paths.dirty);
    this.#sessionId = null;
    this.#lastCheckpointAtMs = null;
  }
}