《移动游戏产品的架构·客户端与移动运行时》4.1 冷启动、热启动与后台挂起

// file: src/runtime/lifecycle.ts
// tier: L2
// verify: node --test test/runtime/lifecycle.test.ts

import type { Clock } from "../core/clock.ts";
import { fail, ok, type Result } from "../core/result.ts";

export const LIFECYCLE_STATES = [
  "created",
  "foregrounded",
  "backgrounded",
  "suspended",
  "resumed",
  "destroyed",
] as const;

export type LifecycleState = (typeof LIFECYCLE_STATES)[number];
export type Visibility = "active" | "inactive" | "hidden";
export type Platform = "android" | "ios";

export type LifecycleEvent =
  | "launch"
  | "activate"
  | "deactivate"
  | "enter-background"
  | "return-foreground"
  | "resume-complete"
  | "suspend"
  | "destroy";

export interface PlatformBinding {
  readonly platform: Platform;
  readonly signal: string;
  readonly event: LifecycleEvent;
  readonly note: string;
}

export const PLATFORM_BINDINGS: readonly PlatformBinding[] = [
  { platform: "android", signal: "onCreate", event: "launch", note: "进程与 Activity 首次创建" },
  { platform: "android", signal: "onStart", event: "return-foreground", note: "界面开始可见，冷启动时也会触发" },
  { platform: "android", signal: "onResume", event: "resume-complete", note: "界面可交互，恢复流程完成" },
  { platform: "android", signal: "onPause", event: "deactivate", note: "仍可能可见，被对话框、分屏或来电遮挡" },
  { platform: "android", signal: "onStop", event: "enter-background", note: "完全不可见，进程仍可能存活" },
  { platform: "android", signal: "onDestroy", event: "destroy", note: "Activity 销毁，不保证进程退出" },
  { platform: "ios", signal: "didFinishLaunching", event: "launch", note: "启动完成，界面尚未可交互" },
  { platform: "ios", signal: "willEnterForeground", event: "return-foreground", note: "即将回到前台，恢复流程开始" },
  { platform: "ios", signal: "didBecomeActive", event: "resume-complete", note: "获得焦点并开始接收输入" },
  { platform: "ios", signal: "willResignActive", event: "deactivate", note: "失去焦点，仍可能可见" },
  { platform: "ios", signal: "didEnterBackground", event: "enter-background", note: "进入后台，系统可能随时回收进程" },
  { platform: "ios", signal: "willTerminate", event: "destroy", note: "仅在被主动终止且未被挂起时可靠" },
];

export function eventForSignal(platform: Platform, signal: string): LifecycleEvent | null {
  const binding = PLATFORM_BINDINGS.find(
    (item) => item.platform === platform && item.signal === signal,
  );
  return binding?.event ?? null;
}

export interface LifecyclePolicy {
  readonly suspendAfterMs: number;
  readonly evictAfterMs: number;
}

export const DEFAULT_LIFECYCLE_POLICY: LifecyclePolicy = {
  suspendAfterMs: 300_000,
  evictAfterMs: 1_800_000,
};

export type StartupKind = "cold" | "hot";

export interface Transition {
  readonly from: LifecycleState;
  readonly to: LifecycleState;
  readonly event: LifecycleEvent;
  readonly atMs: number;
}

export type TransitionError = "destroyed-terminal" | "illegal-transition" | "unknown-signal";

interface Rule {
  readonly from: readonly LifecycleState[];
  readonly to: LifecycleState;
  readonly visibility: Visibility;
}

const RULES: Record<LifecycleEvent, Rule> = {
  launch: { from: ["created"], to: "resumed", visibility: "hidden" },
  activate: { from: ["created", "resumed"], to: "foregrounded", visibility: "active" },
  deactivate: { from: ["foregrounded"], to: "foregrounded", visibility: "inactive" },
  "enter-background": { from: ["foregrounded", "resumed"], to: "backgrounded", visibility: "hidden" },
  "return-foreground": { from: ["backgrounded", "suspended", "resumed"], to: "resumed", visibility: "inactive" },
  "resume-complete": { from: ["resumed"], to: "foregrounded", visibility: "active" },
  suspend: { from: ["backgrounded"], to: "suspended", visibility: "hidden" },
  destroy: {
    from: ["created", "foregrounded", "backgrounded", "suspended", "resumed"],
    to: "destroyed",
    visibility: "hidden",
  },
};

export class LifecycleMachine {
  #clock: Clock;
  #policy: LifecyclePolicy;
  #state: LifecycleState = "created";
  #visibility: Visibility = "hidden";
  #startupKind: StartupKind = "cold";
  #backgroundedAtMs: number | null = null;
  #lastBackgroundAgeMs: number | null = null;
  #transitions: Transition[] = [];

  constructor(clock: Clock, policy: LifecyclePolicy = DEFAULT_LIFECYCLE_POLICY) {
    this.#clock = clock;
    this.#policy = policy;
  }

  get state(): LifecycleState {
    return this.#state;
  }

  get visibility(): Visibility {
    return this.#visibility;
  }

  get startupKind(): StartupKind {
    return this.#startupKind;
  }

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

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

  get transitions(): readonly Transition[] {
    return [...this.#transitions];
  }

  backgroundAgeMs(): number | null {
    if (this.#backgroundedAtMs === null) {
      return null;
    }
    return this.#clock.nowMs() - this.#backgroundedAtMs;
  }

  signal(platform: Platform, signal: string): Result<Transition, TransitionError> {
    const event = eventForSignal(platform, signal);
    if (event === null) {
      return fail("unknown-signal", `${platform}:${signal}`);
    }
    return this.dispatch(event);
  }

  dispatch(event: LifecycleEvent): Result<Transition, TransitionError> {
    if (this.#state === "destroyed") {
      return fail("destroyed-terminal", event);
    }

    const rule = RULES[event];
    if (!rule.from.includes(this.#state)) {
      return fail("illegal-transition", `${this.#state} -> ${event}`);
    }

    const now = this.#clock.nowMs();
    const from = this.#state;

    if (event === "return-foreground") {
      const age = this.backgroundAgeMs();
      if (age !== null) {
        this.#lastBackgroundAgeMs = age;
        this.#startupKind = age >= this.#policy.evictAfterMs ? "cold" : "hot";
      }
      this.#backgroundedAtMs = null;
    }

    if (event === "launch") {
      this.#startupKind = "cold";
    }

    if (event === "enter-background") {
      this.#backgroundedAtMs = now;
      this.#lastBackgroundAgeMs = null;
    }

    if (event === "destroy") {
      this.#backgroundedAtMs = null;
    }

    this.#state = rule.to;
    this.#visibility = rule.visibility;

    const transition: Transition = { from, to: rule.to, event, atMs: now };
    this.#transitions.push(transition);
    return ok(transition);
  }

  suspendIfIdle(): Result<Transition, TransitionError> | null {
    if (this.#state !== "backgrounded") {
      return null;
    }
    const age = this.backgroundAgeMs();
    if (age === null || age < this.#policy.suspendAfterMs) {
      return null;
    }
    return this.dispatch("suspend");
  }
}