《移动游戏产品的架构·网络、资源与热更新》3.1 连接状态机：从连接到就绪

// file: src/net/connection-fsm.ts
// tier: L1
// verify: node --test test/net/connection-fsm.test.ts
/**
 * 连接生命周期状态机（mga-net-lab）。
 * 阶段预算与重试口径都是实验设定，不是案例数据。
 */

export type ConnectionPhase =
  | "idle"
  | "connecting"
  | "handshaking"
  | "syncing"
  | "ready"
  | "draining"
  | "failed"
  | "closed";

export type ConnectionEvent =
  | "socket-open"
  | "auth-ok"
  | "session-ok"
  | "state-synced"
  | "fail"
  | "timeout"
  | "drain"
  | "retry"
  | "close";

export interface PhaseBudget {
  readonly connectMs: number;
  readonly handshakeMs: number;
  readonly syncMs: number;
  readonly drainMs: number;
}

export const DEFAULT_BUDGET: PhaseBudget = {
  connectMs: 5000,
  handshakeMs: 3000,
  syncMs: 2000,
  drainMs: 1500,
};

export interface TraceEntry {
  readonly seq: number;
  readonly at: number;
  readonly from: ConnectionPhase;
  readonly to: ConnectionPhase;
  readonly event: ConnectionEvent | "start";
}

export interface ConnectionState {
  readonly phase: ConnectionPhase;
  readonly seq: number;
  readonly enteredAt: number;
  readonly deadlineAt: number | null;
  readonly lastError: string | null;
  readonly trace: readonly TraceEntry[];
}

export interface DispatchResult {
  readonly state: ConnectionState;
  readonly accepted: boolean;
  readonly reason: string;
}

const TABLE: Record<ConnectionPhase, Partial<Record<ConnectionEvent, ConnectionPhase>>> = {
  idle: { "socket-open": "connecting" },
  connecting: { "auth-ok": "handshaking", fail: "failed", timeout: "failed" },
  handshaking: { "session-ok": "syncing", fail: "failed", timeout: "failed" },
  syncing: { "state-synced": "ready", fail: "failed", timeout: "failed" },
  ready: { drain: "draining", fail: "failed", timeout: "failed", close: "closed" },
  draining: { close: "closed", fail: "closed", timeout: "closed" },
  failed: { retry: "connecting", close: "closed" },
  closed: {},
};

const LABELS: Record<ConnectionPhase, string> = {
  idle: "空闲",
  connecting: "建连中",
  handshaking: "握手中",
  syncing: "状态同步中",
  ready: "就绪",
  draining: "排空中",
  failed: "失败待重试",
  closed: "已关闭",
};

function budgetFor(phase: ConnectionPhase, budget: PhaseBudget): number | null {
  switch (phase) {
    case "connecting":
      return budget.connectMs;
    case "handshaking":
      return budget.handshakeMs;
    case "syncing":
      return budget.syncMs;
    case "draining":
      return budget.drainMs;
    default:
      return null;
  }
}

function reject(state: ConnectionState, reason: string): DispatchResult {
  return { state, accepted: false, reason };
}

export function createConnection(now = 0): ConnectionState {
  return {
    phase: "idle",
    seq: 0,
    enteredAt: now,
    deadlineAt: null,
    lastError: null,
    trace: [],
  };
}

export function dispatch(
  state: ConnectionState,
  event: ConnectionEvent,
  at: number,
  detail = "",
  budget: PhaseBudget = DEFAULT_BUDGET,
): DispatchResult {
  if (at < state.enteredAt) {
    return reject(state, "时钟回退：事件时间早于阶段进入时间");
  }
  const next = TABLE[state.phase][event];
  if (next === undefined) {
    return reject(state, `阶段 ${state.phase} 不接受事件 ${event}`);
  }
  if (
    event === "timeout" &&
    state.phase !== "ready" &&
    (state.deadlineAt === null || at < state.deadlineAt)
  ) {
    const left = state.deadlineAt === null ? 0 : state.deadlineAt - at;
    return reject(state, `未到阶段期限，剩余 ${left}ms`);
  }

  const seq = state.seq + 1;
  const budgetMs = budgetFor(next, budget);
  const deadlineAt = budgetMs === null ? null : at + budgetMs;
  const failed = event === "fail" || event === "timeout";
  const lastError = failed
    ? detail.length > 0
      ? detail
      : event
    : next === "ready" || event === "retry"
      ? null
      : state.lastError;
  const trace: TraceEntry = {
    seq,
    at,
    from: state.phase,
    to: next,
    event,
  };

  return {
    state: {
      phase: next,
      seq,
      enteredAt: at,
      deadlineAt,
      lastError,
      trace: [...state.trace, trace],
    },
    accepted: true,
    reason: `${state.phase} -> ${next}`,
  };
}

export function isReady(state: ConnectionState): boolean {
  return state.phase === "ready";
}

export function describeState(state: ConnectionState): string {
  const label = LABELS[state.phase];
  const budget = state.deadlineAt === null ? "无阶段期限" : `阶段期限 ${state.deadlineAt}ms`;
  const error = state.lastError === null ? "" : `，最近错误：${state.lastError}`;
  return `${label}（seq=${state.seq}，${budget}${error}）`;
}

export function formatTrace(state: ConnectionState): string {
  return state.trace
    .map((entry) => {
      const seq = String(entry.seq).padStart(2, "0");
      return `#${seq} ${entry.at}ms ${entry.from} -> ${entry.to} (${entry.event})`;
    })
    .join("\n");
}

#01 100ms idle -> connecting (socket-open)
#02 200ms connecting -> handshaking (auth-ok)