《互联网产品的客户端架构·内容、社交与实时互动》6.3 降级路径：实时不可用时产品还能做什么

// file: src/realtime/degrade.ts
// tier: L1
// verify: node --test test/realtime/degrade.test.ts
import type { ConnectionState } from "./connection.ts";

export const CAPABILITIES = ["badge", "autoInsert", "typing", "composer", "presence"] as const;

export type Capability = (typeof CAPABILITIES)[number];

export type CapabilityMode =
  | "live"
  | "manual"
  | "paused"
  | "queued"
  | "disabled"
  | "unknown"
  | "offline";

export type Banner = "none" | "connecting" | "reconnecting" | "offline" | "failed";

export type DegradeAction = "refresh" | "retry" | "cancel";

export interface DegradeOptions {
  canQueueWrites?: boolean;
  hasCachedContent?: boolean;
}

export interface DegradePlan {
  state: ConnectionState;
  banner: Banner;
  capabilities: Record<Capability, CapabilityMode>;
  actions: DegradeAction[];
  queuedWrites: boolean;
  render: {
    canRenderContent: boolean;
    source: "live" | "cache" | "empty";
    hint: string;
  };
}

export interface RecoveryPlan {
  refresh: boolean;
  flushQueue: boolean;
  resetBanner: boolean;
  reason: "connected" | "degraded" | "steady";
}

interface BasePlan {
  banner: Banner;
  modes: Record<Capability, CapabilityMode>;
  actions: DegradeAction[];
}

const STATES: ConnectionState[] = ["idle", "connecting", "open", "reconnecting", "closed", "failed"];

const BASE: Record<ConnectionState, BasePlan> = {
  idle: {
    banner: "none",
    modes: {
      badge: "paused",
      autoInsert: "paused",
      typing: "disabled",
      composer: "disabled",
      presence: "unknown",
    },
    actions: [],
  },
  connecting: {
    banner: "connecting",
    modes: {
      badge: "paused",
      autoInsert: "paused",
      typing: "disabled",
      composer: "disabled",
      presence: "unknown",
    },
    actions: ["cancel"],
  },
  open: {
    banner: "none",
    modes: {
      badge: "live",
      autoInsert: "live",
      typing: "live",
      composer: "live",
      presence: "live",
    },
    actions: [],
  },
  reconnecting: {
    banner: "reconnecting",
    modes: {
      badge: "paused",
      autoInsert: "paused",
      typing: "disabled",
      composer: "queued",
      presence: "unknown",
    },
    actions: ["refresh"],
  },
  closed: {
    banner: "offline",
    modes: {
      badge: "manual",
      autoInsert: "manual",
      typing: "disabled",
      composer: "queued",
      presence: "offline",
    },
    actions: ["refresh"],
  },
  failed: {
    banner: "failed",
    modes: {
      badge: "manual",
      autoInsert: "manual",
      typing: "disabled",
      composer: "disabled",
      presence: "offline",
    },
    actions: ["refresh", "retry"],
  },
};

export function planDegrade(state: ConnectionState, options: DegradeOptions = {}): DegradePlan {
  if (!STATES.includes(state)) throw new Error(`未知的连接状态：${String(state)}`);
  const base = BASE[state];
  const canQueueWrites = options.canQueueWrites ?? true;
  const hasCachedContent = options.hasCachedContent ?? true;
  const capabilities = { ...base.modes };
  if (capabilities.composer === "queued" && !canQueueWrites) {
    capabilities.composer = "disabled";
  }
  const source = state === "open" ? "live" : hasCachedContent ? "cache" : "empty";
  const hint =
    state === "open"
      ? "实时更新中，新内容会自动出现"
      : hasCachedContent
        ? "当前显示缓存内容，可手动刷新；输入不会丢失已写草稿"
        : "暂无缓存内容，显示空状态与刷新入口，不阻塞页面渲染";
  return {
    state,
    banner: base.banner,
    capabilities,
    actions: [...base.actions],
    queuedWrites: capabilities.composer === "queued",
    render: {
      canRenderContent: true,
      source,
      hint,
    },
  };
}

export function acceptsWrites(plan: DegradePlan): boolean {
  return plan.capabilities.composer === "live" || plan.capabilities.composer === "queued";
}

export function planRecovery(
  previous: ConnectionState,
  next: ConnectionState,
  options: { queuedWrites?: boolean } = {},
): RecoveryPlan {
  if (!STATES.includes(previous) || !STATES.includes(next)) {
    throw new Error("planRecovery 收到未知的连接状态");
  }
  if (previous === next) {
    return { refresh: false, flushQueue: false, resetBanner: false, reason: "steady" };
  }
  if (next === "open") {
    return {
      refresh: previous !== "idle",
      flushQueue: options.queuedWrites === true,
      resetBanner: true,
      reason: "connected",
    };
  }
  if (previous === "open") {
    return { refresh: false, flushQueue: false, resetBanner: false, reason: "degraded" };
  }
  return { refresh: false, flushQueue: false, resetBanner: false, reason: "steady" };
}

$ node --test test/realtime/degrade.test.ts
✔ open 状态下所有能力实时可用，页面不显示提示条 (0.847584ms)
✔ connecting 时暂停实时插入与角标，但缓存内容仍然渲染 (0.0835ms)
✔ reconnecting 默认允许输入排队，恢复后统一发送 (0.068292ms)
✔ 关闭排队策略后，reconnecting 的输入改为禁用 (0.421041ms)
✔ closed 时角标改为手动刷新，presence 明确标为离线 (0.0995ms)
✔ failed 时保留刷新与重试入口，但不接受新的写入 (0.068417ms)
✔ 没有缓存时显示空状态，仍然不把渲染挂到连接状态上 (0.258625ms)
✔ 恢复计划区分补拉、冲刷队列与稳态 (0.111542ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 170.012417