《移动游戏产品的架构·网络、资源与热更新》12.1 下载器设计：分片、并发与断点续传

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

export type NetworkClass = "wifi" | "four-g" | "weak";

export interface DownloadProfile {
  readonly network: NetworkClass;
  readonly chunkBytes: number;
  readonly concurrency: number;
  readonly maxAttempts: number;
}

export const DEFAULT_PROFILES: Record<NetworkClass, DownloadProfile> = {
  wifi: { network: "wifi", chunkBytes: 8 * 1024 * 1024, concurrency: 6, maxAttempts: 3 },
  "four-g": { network: "four-g", chunkBytes: 4 * 1024 * 1024, concurrency: 4, maxAttempts: 3 },
  weak: { network: "weak", chunkBytes: 1024 * 1024, concurrency: 2, maxAttempts: 5 },
};

export interface FileSpec {
  readonly id: string;
  readonly bytes: number;
}

export interface Chunk {
  readonly id: string;
  readonly fileId: string;
  readonly index: number;
  readonly offset: number;
  readonly bytes: number;
}

export interface ChunkProgress {
  readonly attempts: number;
  readonly done: boolean;
  readonly failed: boolean;
}

export interface DownloadState {
  readonly profile: DownloadProfile;
  readonly chunks: readonly Chunk[];
  readonly progress: ReadonlyMap<string, ChunkProgress>;
  readonly totalBytes: number;
  readonly completedBytes: number;
  readonly wastedBytes: number;
}

export interface ChunkOutcome {
  readonly ok: boolean;
  readonly transferredBytes: number;
}

export function chooseProfile(network: NetworkClass, lowEnd = false): DownloadProfile {
  const base = DEFAULT_PROFILES[network];
  if (base === undefined) throw new Error(`unknown network class: ${String(network)}`);
  if (!lowEnd || network === "weak") return base;
  return {
    ...base,
    chunkBytes: Math.min(base.chunkBytes, 4 * 1024 * 1024),
    concurrency: Math.min(base.concurrency, 3),
  };
}

export function planChunks(fileId: string, bytes: number, chunkBytes: number): readonly Chunk[] {
  if (fileId.length === 0) throw new Error("file id must not be empty");
  if (!Number.isInteger(bytes) || bytes < 0) throw new Error(`invalid file size: ${bytes}`);
  if (!Number.isInteger(chunkBytes) || chunkBytes < 1) throw new Error(`invalid chunk size: ${chunkBytes}`);

  const chunks: Chunk[] = [];
  for (let offset = 0, index = 0; offset < bytes; offset += chunkBytes, index += 1) {
    chunks.push({
      id: `${fileId}#${index}`,
      fileId,
      index,
      offset,
      bytes: Math.min(chunkBytes, bytes - offset),
    });
  }
  return chunks;
}

export function createDownloadState(files: readonly FileSpec[], profile: DownloadProfile): DownloadState {
  if (!Number.isInteger(profile.chunkBytes) || profile.chunkBytes < 1) {
    throw new Error(`invalid chunk size: ${profile.chunkBytes}`);
  }
  if (!Number.isInteger(profile.concurrency) || profile.concurrency < 1) {
    throw new Error(`invalid concurrency: ${profile.concurrency}`);
  }
  if (!Number.isInteger(profile.maxAttempts) || profile.maxAttempts < 1) {
    throw new Error(`invalid max attempts: ${profile.maxAttempts}`);
  }

  const seen = new Set<string>();
  const chunks: Chunk[] = [];
  const progress = new Map<string, ChunkProgress>();
  let totalBytes = 0;

  for (const file of files) {
    if (seen.has(file.id)) throw new Error(`duplicate file id: ${file.id}`);
    seen.add(file.id);
    for (const chunk of planChunks(file.id, file.bytes, profile.chunkBytes)) {
      chunks.push(chunk);
      progress.set(chunk.id, { attempts: 0, done: false, failed: false });
    }
    totalBytes += file.bytes;
  }

  return { profile, chunks, progress, totalBytes, completedBytes: 0, wastedBytes: 0 };
}

export function applyChunkResult(
  state: DownloadState,
  chunkId: string,
  outcome: ChunkOutcome,
): DownloadState {
  const current = state.progress.get(chunkId);
  if (current === undefined) throw new Error(`unknown chunk: ${chunkId}`);
  if (current.done) throw new Error(`chunk already completed: ${chunkId}`);
  if (current.failed) throw new Error(`chunk already failed: ${chunkId}`);
  if (!Number.isInteger(outcome.transferredBytes) || outcome.transferredBytes < 0) {
    throw new Error(`invalid transferred bytes: ${outcome.transferredBytes}`);
  }

  const chunk = state.chunks.find((item) => item.id === chunkId);
  if (chunk === undefined) throw new Error(`chunk not found in plan: ${chunkId}`);
  if (outcome.transferredBytes > chunk.bytes) {
    throw new Error(`transferred more than chunk size: ${chunkId}`);
  }

  const attempts = current.attempts + 1;
  const next = new Map(state.progress);

  if (outcome.ok) {
    next.set(chunkId, { attempts, done: true, failed: false });
    return { ...state, progress: next, completedBytes: state.completedBytes + chunk.bytes };
  }

  const failed = attempts >= state.profile.maxAttempts;
  next.set(chunkId, { attempts, done: false, failed });
  return { ...state, progress: next, wastedBytes: state.wastedBytes + outcome.transferredBytes };
}

export function nextBatch(state: DownloadState, limit: number = state.profile.concurrency): readonly string[] {
  if (!Number.isInteger(limit) || limit < 1) throw new Error(`invalid batch size: ${limit}`);
  const ids: string[] = [];
  for (const chunk of state.chunks) {
    const item = state.progress.get(chunk.id);
    if (item !== undefined && !item.done && !item.failed) {
      ids.push(chunk.id);
      if (ids.length === limit) break;
    }
  }
  return ids;
}

export function formatDownloadProgress(state: DownloadState): string {
  let chunks = 0;
  let done = 0;
  let failed = 0;
  let retrying = 0;

  for (const item of state.progress.values()) {
    chunks += 1;
    if (item.done) done += 1;
    else if (item.failed) failed += 1;
    else if (item.attempts > 0) retrying += 1;
  }

  return [
    `downloaded=${state.completedBytes}/${state.totalBytes}B`,
    `chunks=${done}/${chunks}`,
    `pending=${chunks - done - failed}`,
    `retrying=${retrying}`,
    `failed=${failed}`,
    `wasted=${state.wastedBytes}B`,
  ].join(" ");
}

downloaded=5/15B chunks=1/3 pending=2 retrying=1 failed=0 wasted=2B