《移动游戏产品的架构·网络、资源与热更新》12.3 下载失败的降级与重试

1 - (1 - 0.975)^2 × (1 - 0.92)^2 = 1 - 0.000625 × 0.0064 ≈ 99.9996%

// file: src/cdn/fallback.ts
// tier: L1
// verify: node --test test/cdn/fallback.test.ts

export type FailureKind =
  | "http-404"
  | "http-403"
  | "http-5xx"
  | "timeout"
  | "checksum"
  | "no-space"
  | "user-cancel"
  | "range-unsupported";

export type FallbackAction =
  | "next-cdn"
  | "resume-chunk"
  | "refresh-signature"
  | "free-space"
  | "stop-publish"
  | "ask-user"
  | "single-stream";

export interface FailureAdvice {
  readonly kind: FailureKind;
  readonly retryable: boolean;
  readonly action: FallbackAction;
  readonly note: string;
}

export interface FallbackTier {
  readonly id: string;
  readonly successRate: number;
  readonly maxAttempts: number;
  readonly chunkScale: number;
}

export interface FallbackAssessment {
  readonly successRate: number;
  readonly expectedAttempts: number;
  readonly expectedBytes: number;
  readonly worstBytes: number;
  readonly tiers: number;
}

export interface PackGroup {
  readonly id: string;
  readonly bytes: number;
  readonly critical: boolean;
  readonly priority: number;
}

export interface DegradeResult {
  readonly feasible: boolean;
  readonly retainedBytes: number;
  readonly deferredBytes: number;
  readonly deferred: readonly string[];
  readonly overflowBytes: number;
}

const ADVICE: Record<FailureKind, Omit<FailureAdvice, "kind">> = {
  "http-404": {
    retryable: false,
    action: "stop-publish",
    note: "object missing from the release; retrying cannot create it",
  },
  "http-403": {
    retryable: true,
    action: "refresh-signature",
    note: "signed url expired; refresh once before retrying",
  },
  "http-5xx": {
    retryable: true,
    action: "next-cdn",
    note: "edge or origin error; move the request to the next vendor",
  },
  timeout: {
    retryable: true,
    action: "resume-chunk",
    note: "keep completed ranges and resume with a smaller chunk",
  },
  checksum: {
    retryable: true,
    action: "next-cdn",
    note: "resume cannot repair bad bytes; fetch the object elsewhere",
  },
  "no-space": {
    retryable: false,
    action: "free-space",
    note: "the device cannot store the file until space is freed",
  },
  "user-cancel": {
    retryable: false,
    action: "ask-user",
    note: "the player stopped the download; do not fight the user",
  },
  "range-unsupported": {
    retryable: true,
    action: "single-stream",
    note: "the edge ignores Range; fall back to one stream",
  },
};

export const DEFAULT_TIERS: readonly FallbackTier[] = [
  { id: "primary-cdn", successRate: 0.975, maxAttempts: 2, chunkScale: 1 },
  { id: "secondary-cdn", successRate: 0.92, maxAttempts: 2, chunkScale: 1 },
];

export function classifyFailure(kind: string): FailureAdvice {
  const advice = ADVICE[kind as FailureKind];
  if (advice === undefined) throw new Error(`unknown failure kind: ${kind}`);
  return { kind: kind as FailureKind, ...advice };
}

export function assessFallback(tiers: readonly FallbackTier[], bytes: number): FallbackAssessment {
  if (tiers.length === 0) throw new Error("at least one fallback tier is required");
  if (!Number.isInteger(bytes) || bytes < 0) throw new Error(`invalid object size: ${bytes}`);

  let reach = 1;
  let expectedAttempts = 0;
  let expectedBytes = 0;
  let worstBytes = 0;

  for (const tier of tiers) {
    if (tier.id.length === 0) throw new Error("tier id must not be empty");
    if (!Number.isFinite(tier.successRate) || tier.successRate <= 0 || tier.successRate > 1) {
      throw new Error(`invalid success rate for ${tier.id}: ${tier.successRate}`);
    }
    if (!Number.isInteger(tier.maxAttempts) || tier.maxAttempts < 1) {
      throw new Error(`invalid max attempts for ${tier.id}: ${tier.maxAttempts}`);
    }
    if (!Number.isFinite(tier.chunkScale) || tier.chunkScale <= 0) {
      throw new Error(`invalid chunk scale for ${tier.id}: ${tier.chunkScale}`);
    }

    const fail = 1 - tier.successRate;
    const attempts = (1 - fail ** tier.maxAttempts) / tier.successRate;
    expectedAttempts += reach * attempts;
    expectedBytes += reach * attempts * tier.chunkScale * bytes;
    worstBytes += tier.maxAttempts * tier.chunkScale * bytes;
    reach *= fail ** tier.maxAttempts;
  }

  return { successRate: 1 - reach, expectedAttempts, expectedBytes, worstBytes, tiers: tiers.length };
}

export function degradeToFit(groups: readonly PackGroup[], budgetBytes: number): DegradeResult {
  if (!Number.isInteger(budgetBytes) || budgetBytes < 0) {
    throw new Error(`invalid budget: ${budgetBytes}`);
  }

  const seen = new Set<string>();
  let criticalBytes = 0;
  for (const group of groups) {
    if (group.id.length === 0) throw new Error("group id must not be empty");
    if (seen.has(group.id)) throw new Error(`duplicate group: ${group.id}`);
    seen.add(group.id);
    if (!Number.isInteger(group.bytes) || group.bytes < 0) {
      throw new Error(`invalid bytes for ${group.id}: ${group.bytes}`);
    }
    if (group.critical) criticalBytes += group.bytes;
  }

  if (criticalBytes > budgetBytes) {
    return {
      feasible: false,
      retainedBytes: criticalBytes,
      deferredBytes: 0,
      deferred: [],
      overflowBytes: criticalBytes - budgetBytes,
    };
  }

  const optional = groups
    .filter((group) => !group.critical)
    .sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id));

  let retainedBytes = criticalBytes;
  let deferredBytes = 0;
  const deferred: string[] = [];

  for (const group of optional) {
    if (retainedBytes + group.bytes <= budgetBytes) {
      retainedBytes += group.bytes;
    } else {
      deferred.push(group.id);
      deferredBytes += group.bytes;
    }
  }

  return { feasible: true, retainedBytes, deferredBytes, deferred, overflowBytes: 0 };
}

export function formatFallbackReport(assessment: FallbackAssessment): string {
  return [
    `success=${(assessment.successRate * 100).toFixed(4)}%`,
    `attempts=${assessment.expectedAttempts.toFixed(3)}`,
    `bytes=${Math.round(assessment.expectedBytes)}B`,
    `worst=${assessment.worstBytes}B`,
    `tiers=${assessment.tiers}`,
  ].join(" ");
}

success=99.9996% attempts=1.026 bytes=1026B worst=4000B tiers=2