graph LR
    A[发送端] -->|信令交换| B[信令服务器]
    B -->|SDP/ICE Candidate| C[接收端]
    A -.->|P2P DataChannel| C
    A -->|可选 中转| D[TURN 服务器]
    C -->|可选 中转| D

class SenderController {
  constructor(channel, file, options = {}) {
    this.channel = channel;
    this.file = file;
    this.chunkSize = options.chunkSize || 32 * 1024; // 32 KB
    this.windowSize = options.windowSize || 50;       // 滑动窗口
    this.pendingAck = new Map();                      // index -> {data, timer}
    this.nextIndex = 0;
    this.ackedIndex = -1;
  }

  // 核心发送循环
  async pump() {
    while (this.nextIndex - this.ackedIndex < this.windowSize) {
      const chunk = await this.readChunk(this.nextIndex);
      if (!chunk) break; // 文件读完
      this.sendFrame(chunk);
      this.nextIndex++;
    }
  }

  // 处理接收端 ACK
  onAck(ackIndex) {
    this.pendingAck.delete(ackIndex);
    this.ackedIndex = Math.max(this.ackedIndex, ackIndex);
    this.pump(); // 窗口滑动
  }
}

{
  "fileId": "uuid-v4",
  "fileName": "example.zip",
  "fileSize": 1073741824,
  "chunkSize": 32768,
  "totalChunks": 32768,
  "hashAlgorithm": "SHA-256",
  "hashValue": "hex-string...",
  "createdAt": 1715000000000
}

// 发送端 -> 接收端
{ "action": "RESUME_QUERY", "fileId": "..." }

// 接收端 -> 发送端
{ "action": "RESUME_ACK", "fileId": "...", "receivedIndexes": [0,1,2, 100,101...] }

// 简易 BDP 估算与通道数自适应
function estimateOptimalChannels(rttMs, bandwidthMbps) {
  const bdpBytes = (bandwidthMbps * 1e6 / 8) * (rttMs / 1000);
  const chunkBytes = 32 * 1024;
  const minChannels = Math.ceil(bdpBytes / chunkBytes / 50); // 窗口50
  return Math.min(Math.max(minChannels, 2), 8); // 夹逼在 2-8
}

webrtc-file-transfer/
├── src/
│   ├── core/
│   │   ├── protocol.js        # 帧编解码、CRC32、分片器
│   │   ├── sender.js          # 发送端状态机、流控、续传逻辑
│   │   ├── receiver.js        # 接收端重组、ACK/NACK、落盘
│   │   └── signaling.js       # 信令封装（WebSocket / WebRTC DataChannel 信令复用）
│   ├── workers/
│   │   ├── hasher.worker.js   # SHA-256 / CRC32 计算
│   │   └── crypto.worker.js   # 可选：应用层额外加密
│   ├── ui/
│   │   ├── transfer-list.vue  # 传输列表、进度、断点续传按钮
│   │   └── settings.vue       # 分片大小、并发数、TURN 配置
│   └── main.js                # 入口、权限申请、全局错误兜底
├── public/
│   └── sw.js                  # Service Worker 离线缓存核心逻辑
├── package.json
└── README.md

graph TB
    subgraph Client Layer
        A[Web SDK] -->|WS/WSS| B(LVS / Cloud LB)
    end
    subgraph Signaling Cluster
        B --> C[Signaling Node 1]
        B --> D[Signaling Node 2]
        B --> E[Signaling Node N]
    end
    subgraph State Store
        C --> F[(Redis ClusternSession Mapping)]
        D --> F
        E --> F
        C --> G[(KafkanEvent Bus)]
        D --> G
        E --> G
    end

// 前台保活
let wakeLock = null;
async function acquireWakeLock() {
  try {
    wakeLock = await navigator.wakeLock.request('screen');
    wakeLock.addEventListener('release', () => console.log('Wake Lock released'));
  } catch (e) { console.warn('Wake Lock unavailable', e); }
}

// 后台心跳（Service Worker + Push API）
// sw.js
self.addEventListener('push', e => {
  const data = e.data.json();
  if (data.type === 'SIGNALING_RECONNECT') {
    clients.matchAll({type: 'window'}).then(windows => {
      if (windows.length) windows[0].focus();
      else clients.openWindow('/transfer?resume=' + data.fileId);
    });
  }
});

// 信令下发 TURN 凭证（短效，TTL 24h）
{
  "action": "TURN_CREDENTIALS",
  "payload": {
    "urls": ["turn:turn1.example.com:3478?transport=udp", "turns:turn1.example.com:443?transport=tcp"],
    "username": "1715000000:user123", // timestamp:userid
    "credential": "hmac-sha256(secret, username)",
    "ttl": 86400,
    "region": "cn-east-1" // 客户端就近选择
  }
}

message FileNode {
  string name = 1;
  uint64 size = 2;          // 文件大小，目录为 0
  string hash = 3;          // SHA-256，目录为空
  repeated FileNode children = 4;
  uint32 mode = 5;          // POSIX 权限位
  int64 mtime = 6;          // 修改时间戳
}

# 1. 模拟 5% 丢包、100ms 延迟、10% 乱序
tc qdisc add dev eth0 root netem loss 5% delay 100ms 20ms reorder 10%

# 2. 模拟 NAT 映射超时（突发断开 30s）
iptables -A INPUT -p udp --dport 3478 -m statistic --mode random --probability 0.01 -j DROP
sleep 30
iptables -D INPUT -p udp --dport 3478 -m statistic --mode random --probability 0.01 -j DROP

# 3. 模拟 TURN 服务器证书过期/轮换
# 启动测试用 coturn 实例，配置短效证书 (TTL 60s)，观察客户端自动刷新凭证重连

# locustfile.py 核心逻辑
class WebRTCUser(User):
    wait_time = between(1, 3)
    
    @task(10)
    def upload_100mb(self):
        self.client.webrtc_transfer("test_100mb.bin", chunk_size=32*1024)
    
    @task(1)
    def upload_10gb(self):
        self.client.webrtc_transfer("test_10gb.bin", chunk_size=64*1024, parallel_channels=4)

# 容量规划公式
# 单节点最大并发 ≈ (CPU核心数 * 0.7) / (单连接CPU占用)
# 单连接CPU占用 ≈ 0.5% (纯转发) ~ 2% (含加密/校验)
# 建议：8C16G 节点支撑 200-300 并发 100Mbps 传输

graph TD
    A[WebRTC DataChannelnUDP/SCTP] -->|失败/不可用| B[WebTransportnHTTP/3 QUIC]
    B -->|失败/不可用| C[WebSocket + BinaryType=arraybuffernTCP/TLS]
    C -->|失败/不可用| D[HTTP/2 + ReadableStreamn分片上传/下载]
    D -->|最终兜底| E[HTTP/1.1 FormDatan断点续传 via Range/Content-Range]

async function selectTransport() {
  if (await probeWebRTC()) return new WebRTCTransport();      // 首选：P2P、低延迟
  if (await probeWebTransport()) return new WebTransportTransport(); // 次选：HTTP/3 多路复用
  if (await probeWebSocket()) return new WSTransport();       // 兜底：广泛兼容
  return new HTTPTransport();                                 // 终极兜底
}

// 探测函数示例：WebRTC
async function probeWebRTC() {
  try {
    const pc = new RTCPeerConnection({iceServers: [{urls: 'stun:stun.l.google.com:19302'}]});
    const dc = pc.createDataChannel('probe', {negotiated: true, id: 0});
    await new Promise((resolve, reject) => {
      dc.onopen = resolve;
      dc.onerror = reject;
      setTimeout(() => reject(new Error('timeout')), 3000);
    });
    dc.close(); pc.close();
    return true;
  } catch { return false; }
}

// types/protocol.ts
export const FrameType = {
  METADATA: 0x01,
  CHUNK: 0x02,
  ACK: 0x03,
  CONTROL: 0x04,
  DIRECTORY: 0x05,
} as const;

export type FrameType = typeof FrameType[keyof typeof FrameType];

export interface BaseFrame {
  magic: 0x5752; // 'WR'
  version: 1;
  type: FrameType;
  fileId: UUID;
}

export interface ChunkFrame extends BaseFrame {
  type: typeof FrameType.CHUNK;
  index: number;           // uint32
  offset: bigint;          // uint64, 支持 > 4GB
  length: number;          // uint32
  crc32: number;           // uint32
  payload: ArrayBuffer;    // zero-copy transferable
}

// 判别联合，编译期保证 switch 穷尽
export type InboundFrame = 
  | (BaseFrame & { type: typeof FrameType.METADATA; payload: FileMetadata })
  | (BaseFrame & { type: typeof FrameType.CHUNK; payload: ArrayBuffer })
  | (BaseFrame & { type: typeof FrameType.ACK; payload: AckPayload })
  | (BaseFrame & { type: typeof FrameType.CONTROL; payload: ControlPayload })
  | (BaseFrame & { type: typeof FrameType.DIRECTORY; payload: DirectoryTree });

// 统一异常类
export class TransferError extends Error {
  constructor(
    public readonly code: number,
    message: string,
    public readonly recoverable: boolean,
    public readonly context?: Record<string, unknown>
  ) {
    super(message);
    this.name = 'TransferError';
  }
  
  static fromUnknown(e: unknown, defaultCode = 5000): TransferError {
    if (e instanceof TransferError) return e;
    return new TransferError(defaultCode, String(e), false, { original: e });
  }
}