《移动游戏产品的架构·网络、资源与热更新》2.2 请求响应、推送与超时语义

// file: src/net/request-tracker.ts
// tier: L1
// verify: node --test test/net/request-tracker.test.ts

export type RequestState =
  | "pending"
  | "retrying"
  | "settled"
  | "timed-out"
  | "abandoned";

export type PushKind = "snapshot" | "notice" | "heartbeat";

export interface TrackerOptions {
  readonly defaultTimeoutMs: number;
  readonly maxAttempts: number;
}

export interface RequestRecord {
  readonly id: string;
  state: RequestState;
  attempts: number;
  readonly startedAtMs: number;
  readonly timeoutMs: number;
  deadlineMs: number;
  latencyMs?: number;
}

export interface AckResult {
  readonly outcome: "settled" | "duplicate" | "unknown";
  readonly latencyMs?: number;
}

export interface ExpireResult {
  readonly id: string;
  readonly attempt: number;
  readonly state: "retrying" | "timed-out";
  readonly deadlineMs: number;
}

export interface TrackerSnapshot {
  readonly started: number;
  readonly settled: number;
  readonly timedOut: number;
  readonly retried: number;
  readonly abandoned: number;
  readonly pushes: number;
  readonly inFlight: number;
}

const PUSH_KINDS: readonly PushKind[] = ["snapshot", "notice", "heartbeat"];

function isPushKind(value: string): value is PushKind {
  return (PUSH_KINDS as readonly string[]).includes(value);
}

function isOpen(state: RequestState): boolean {
  return state === "pending" || state === "retrying";
}

export class RequestTracker {
  #records = new Map<string, RequestRecord>();
  #timeoutMs: number;
  #maxAttempts: number;
  #started = 0;
  #settled = 0;
  #timedOut = 0;
  #retried = 0;
  #abandoned = 0;
  #pushes = 0;

  constructor(options: Partial<TrackerOptions> = {}) {
    const timeout = options.defaultTimeoutMs ?? 1_000;
    const attempts = options.maxAttempts ?? 2;
    if (!Number.isInteger(timeout) || timeout <= 0) {
      throw new Error(`defaultTimeoutMs must be a positive integer: ${timeout}`);
    }
    if (!Number.isInteger(attempts) || attempts < 1) {
      throw new Error(`maxAttempts must be a positive integer: ${attempts}`);
    }
    this.#timeoutMs = timeout;
    this.#maxAttempts = attempts;
  }

  start(id: string, nowMs: number, timeoutMs = this.#timeoutMs): void {
    if (id.length === 0) {
      throw new Error("request id must not be empty");
    }
    if (this.#records.has(id)) {
      throw new Error(`duplicate request id: ${id}`);
    }
    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
      throw new Error(`timeout must be a positive integer: ${timeoutMs}`);
    }
    this.#records.set(id, {
      id,
      state: "pending",
      attempts: 1,
      startedAtMs: nowMs,
      timeoutMs,
      deadlineMs: nowMs + timeoutMs,
    });
    this.#started += 1;
  }

  ack(id: string, nowMs: number): AckResult {
    const record = this.#records.get(id);
    if (record === undefined) {
      return { outcome: "unknown" };
    }
    if (!isOpen(record.state)) {
      return { outcome: "duplicate" };
    }
    const latencyMs = Math.max(0, nowMs - record.startedAtMs);
    record.state = "settled";
    record.latencyMs = latencyMs;
    this.#settled += 1;
    return { outcome: "settled", latencyMs };
  }

  expire(nowMs: number): readonly ExpireResult[] {
    const expired: ExpireResult[] = [];
    for (const record of this.#records.values()) {
      if (!isOpen(record.state) || record.deadlineMs > nowMs) {
        continue;
      }
      if (record.attempts >= this.#maxAttempts) {
        record.state = "timed-out";
        this.#timedOut += 1;
        expired.push({
          id: record.id,
          attempt: record.attempts,
          state: "timed-out",
          deadlineMs: record.deadlineMs,
        });
        continue;
      }
      record.attempts += 1;
      record.state = "retrying";
      record.deadlineMs = nowMs + record.timeoutMs;
      this.#retried += 1;
      expired.push({
        id: record.id,
        attempt: record.attempts,
        state: "retrying",
        deadlineMs: record.deadlineMs,
      });
    }
    return expired;
  }

  recordPush(kind: string): boolean {
    if (!isPushKind(kind)) {
      return false;
    }
    this.#pushes += 1;
    return true;
  }

  cancel(id: string): boolean {
    const record = this.#records.get(id);
    if (record === undefined || !isOpen(record.state)) {
      return false;
    }
    record.state = "abandoned";
    this.#abandoned += 1;
    return true;
  }

  snapshot(): TrackerSnapshot {
    let inFlight = 0;
    for (const record of this.#records.values()) {
      if (isOpen(record.state)) {
        inFlight += 1;
      }
    }
    return {
      started: this.#started,
      settled: this.#settled,
      timedOut: this.#timedOut,
      retried: this.#retried,
      abandoned: this.#abandoned,
      pushes: this.#pushes,
      inFlight,
    };
  }

  record(id: string): RequestRecord | undefined {
    return this.#records.get(id);
  }
}

export function describeTracker(snapshot: TrackerSnapshot): string {
  return `tracker started=${snapshot.started} settled=${snapshot.settled} retried=${snapshot.retried} timedOut=${snapshot.timedOut} abandoned=${snapshot.abandoned} pushes=${snapshot.pushes} inFlight=${snapshot.inFlight}`;
}

export function describeAck(id: string, result: AckResult): string {
  if (result.outcome === "settled") {
    return `ack ${id}: settled in ${result.latencyMs ?? 0}ms`;
  }
  return `ack ${id}: ${result.outcome}`;
}

export function createTracker(options: Partial<TrackerOptions> = {}): RequestTracker {
  return new RequestTracker(options);
}

tracker started=2 settled=1 retried=0 timedOut=1 abandoned=0 pushes=1 inFlight=0