《移动游戏产品的架构·客户端与移动运行时》3.2 桥接层设计：消息、线程与生命周期

// file: src/platform/host-mock.ts
// tier: L2
// verify: node --test test/platform/host-mock.test.ts

import { SystemClock, type Clock } from "../core/clock.ts";
import type { Host, PermissionKind, PermissionState, Platform } from "./host.ts";
import { shellKindFor } from "./host.ts";

export const PROTOCOL_VERSION = 2;

export type ThreadId = "main" | "render" | "worker";

export interface BridgeMessage {
  readonly id: string;
  readonly name: string;
  readonly version: number;
  readonly thread: ThreadId;
  readonly payload: unknown;
}

export interface BridgeEvent {
  readonly name: string;
  readonly version: number;
  readonly thread: ThreadId;
  readonly payload: unknown;
}

export type BridgeErrorCode =
  | "timeout"
  | "cancelled"
  | "version-mismatch"
  | "unsupported"
  | "host-error";

export type BridgeResult<T> =
  | { readonly ok: true; readonly value: T }
  | { readonly ok: false; readonly code: BridgeErrorCode; readonly message: string };

export interface BridgeCall<T> {
  readonly id: string;
  readonly result: Promise<BridgeResult<T>>;
}

export type BridgeHandler = (payload: unknown) => BridgeResult<unknown>;

export class BridgeHost {
  #version: number;
  #handlers = new Map<string, BridgeHandler>();

  constructor(version: number = PROTOCOL_VERSION) {
    this.#version = version;
  }

  get version(): number {
    return this.#version;
  }

  on(name: string, handler: BridgeHandler): void {
    this.#handlers.set(name, handler);
  }

  handle(message: BridgeMessage): BridgeResult<unknown> {
    if (message.version !== this.#version) {
      return {
        ok: false,
        code: "version-mismatch",
        message: `expected ${this.#version}, got ${message.version}`,
      };
    }
    const handler = this.#handlers.get(message.name);
    if (!handler) {
      return { ok: false, code: "unsupported", message: `no handler for ${message.name}` };
    }
    try {
      return handler(message.payload);
    } catch (error) {
      return { ok: false, code: "host-error", message: String(error) };
    }
  }
}

type Pending = {
  readonly message: BridgeMessage;
  readonly timeoutMs: number;
  readonly deadlineMs: number;
  readonly settle: (result: BridgeResult<unknown>) => void;
};

export interface BridgeOptions {
  readonly clock?: Clock;
  readonly host?: BridgeHost;
  readonly timeoutMs?: number;
}

export class Bridge {
  #clock: Clock;
  #host: BridgeHost;
  #defaultTimeoutMs: number;
  #seq = 0;
  #pending = new Map<string, Pending>();
  #outbox: BridgeMessage[] = [];
  #inbox: BridgeEvent[] = [];
  #listeners = new Map<string, Set<(payload: unknown) => void>>();

  constructor(options: BridgeOptions = {}) {
    this.#clock = options.clock ?? new SystemClock();
    this.#host = options.host ?? new BridgeHost();
    this.#defaultTimeoutMs = options.timeoutMs ?? 5_000;
  }

  get pendingCount(): number {
    return this.#pending.size;
  }

  call<T>(
    name: string,
    payload: unknown,
    options: { thread?: ThreadId; timeoutMs?: number } = {},
  ): BridgeCall<T> {
    this.#seq += 1;
    const id = `m${this.#seq}`;
    const message: BridgeMessage = {
      id,
      name,
      version: PROTOCOL_VERSION,
      thread: options.thread ?? "main",
      payload,
    };
    const timeoutMs = options.timeoutMs ?? this.#defaultTimeoutMs;
    const result = new Promise<BridgeResult<T>>((resolve) => {
      this.#pending.set(id, {
        message,
        timeoutMs,
        deadlineMs: this.#clock.nowMs() + timeoutMs,
        settle: (outcome) => resolve(outcome as BridgeResult<T>),
      });
    });
    this.#outbox.push(message);
    return { id, result };
  }

  drain(thread: ThreadId): readonly BridgeMessage[] {
    const picked = this.#outbox.filter((message) => message.thread === thread);
    this.#outbox = this.#outbox.filter((message) => message.thread !== thread);
    return picked;
  }

  dispatch(message: BridgeMessage): BridgeResult<unknown> {
    const outcome = this.#host.handle(message);
    this.#settle(message.id, outcome);
    return outcome;
  }

  resolve<T>(id: string, value: T): boolean {
    return this.#settle(id, { ok: true, value });
  }

  reject(id: string, code: BridgeErrorCode, message: string): boolean {
    return this.#settle(id, { ok: false, code, message });
  }

  cancel(id: string): boolean {
    if (!this.#pending.has(id)) {
      return false;
    }
    this.#outbox = this.#outbox.filter((message) => message.id !== id);
    return this.#settle(id, { ok: false, code: "cancelled", message: "cancelled by engine" });
  }

  sweep(): readonly string[] {
    const now = this.#clock.nowMs();
    const expired = [...this.#pending.values()].filter((pending) => pending.deadlineMs <= now);
    const ids: string[] = [];
    for (const pending of expired) {
      const id = pending.message.id;
      this.#outbox = this.#outbox.filter((message) => message.id !== id);
      this.#settle(id, {
        ok: false,
        code: "timeout",
        message: `no response within ${pending.timeoutMs}ms`,
      });
      ids.push(id);
    }
    return ids;
  }

  on(name: string, listener: (payload: unknown) => void): () => void {
    let set = this.#listeners.get(name);
    if (!set) {
      set = new Set();
      this.#listeners.set(name, set);
    }
    set.add(listener);
    return () => set.delete(listener);
  }

  push(event: BridgeEvent): BridgeResult<null> {
    if (event.version !== PROTOCOL_VERSION) {
      return {
        ok: false,
        code: "version-mismatch",
        message: `expected ${PROTOCOL_VERSION}, got ${event.version}`,
      };
    }
    this.#inbox.push(event);
    return { ok: true, value: null };
  }

  pump(thread: ThreadId): number {
    const due = this.#inbox.filter((event) => event.thread === thread);
    this.#inbox = this.#inbox.filter((event) => event.thread !== thread);
    for (const event of due) {
      const set = this.#listeners.get(event.name);
      if (!set) {
        continue;
      }
      for (const listener of [...set]) {
        listener(event.payload);
      }
    }
    return due.length;
  }

  #settle(id: string, outcome: BridgeResult<unknown>): boolean {
    const pending = this.#pending.get(id);
    if (!pending) {
      return false;
    }
    this.#pending.delete(id);
    pending.settle(outcome);
    return true;
  }
}

export interface MockHostOptions {
  readonly platform?: Platform;
  readonly clock?: Clock;
  readonly permissions?: Partial<Record<PermissionKind, PermissionState>>;
}

export interface MockHost extends Host {
  setPermission(kind: PermissionKind, state: PermissionState): void;
}

export function createMockHost(options: MockHostOptions = {}): MockHost {
  const platform = options.platform ?? "android";
  const clock = options.clock ?? new SystemClock();
  const permissions = new Map<PermissionKind, PermissionState>(
    Object.entries(options.permissions ?? {}) as [PermissionKind, PermissionState][],
  );
  return {
    platform,
    shell: shellKindFor(platform),
    mainThread: "main",
    renderThread: "render",
    nowMs: () => clock.nowMs(),
    permissionState: (kind) => permissions.get(kind) ?? "not-determined",
    setPermission: (kind, state) => {
      permissions.set(kind, state);
    },
  };
}

export function createMockBridgeHost(host: MockHost): BridgeHost {
  const bridgeHost = new BridgeHost();
  bridgeHost.on("permission.state", (payload) => {
    const kind = (payload as { kind: PermissionKind }).kind;
    return { ok: true, value: host.permissionState(kind) };
  });
  bridgeHost.on("app.threads", () => ({
    ok: true,
    value: { main: host.mainThread, render: host.renderThread },
  }));
  bridgeHost.on("billing.buy", (payload) => {
    const productId = (payload as { productId?: string }).productId;
    if (!productId) {
      return { ok: false, code: "host-error", message: "missing productId" };
    }
    return { ok: true, value: { productId, state: "pending" } };
  });
  return bridgeHost;
}