다운로드 엔진 아키텍처

┌─────────────────────────────────────────────────┐
│                   다운로드 엔진                    │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ 세그먼트   │→│ 세그먼트   │→│ 파일 쓰기      │  │
│  │ 다운로드  │  │ 처리     │  │ 모듈          │  │
│  │ 모듈     │  │ 모듈     │  │               │  │
│  │          │  │          │  │               │  │
│  │ · 동시   │  │ · 복호화  │  │ · FSA 스트림  │  │
│  │ · 재시도  │  │ · 연결   │  │ · StreamSaver │  │
│  │ · 속도 제한│  │ · 리무싱 │  │ · Blob 최후   │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │              메모리 안전 관리자                │ │
│  │  · 크기 예측  · 임계값 검사  · 전략 선택       │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

사용자 다운로드 클릭
    │
    ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 1. 플레이리스트 │ ──→ │ 2. 세그먼트   │ ──→ │ 3. 세그먼트   │
│ 파싱         │     │ 다운로드     │     │ 처리         │
│              │     │              │     │              │
│ · M3U8 다운로드│     │ · Worker Pool│     │ · AES 복호화  │
│ · 세그먼트 리스트│     │ · 동시 제어   │     │ · TS 연결    │
│ 파싱         │     │ · 지수 백오프 │     │ · FFmpeg 리무 │
│ · 키 추출   │     │ · 진행률 보고 │     │ · 오디오/비디오│
│ · 크기 예측  │     │              │     │   병합        │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                                  ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 6. 완료 알림   │ ←── │ 5. 정리 회수   │ ←── │ 4. 파일 쓰기   │
│              │     │              │     │              │
│ · 데스크톱 알림│     │ · 메모리 해제 │     │ · FSA 스트림  │
│ · 경로 복사   │     │ · 임시 파일   │     │ · StreamSaver│
│ · 큐 진행    │     │   정리       │     │ · Blob 최후  │
│              │     │ · 상태 리셋   │     │              │
└──────────────┘     └──────────────┘     └──────────────┘

  [유휴]
    │ 사용자 다운로드 트리거
    ▼
  [초기화] ──── WASM 로딩, API 가용성 확인, 쓰기 전략 선택
    │
    ▼
  [플레이리스트 파싱] ── M3U8/MPD 다운로드 및 파싱, 세그먼트 리스트와 키 추출
    │
    ▼
  [세그먼트 다운로드] ── Worker Pool 동시 다운로드, 실시간 진행률 보고
    │
    ▼
  [세그먼트 처리] ── 복호화 → 연결/리무싱 → 디스크 쓰기
    │
    ├── 성공 → [정리] → [완료] → [유휴]
    │
    ├── 취소 → [정리] → [유휴]
    │
    └── 실패 → [정리] → [에러] → [유휴]

const downloadSegmentsConcurrently = async (
  segments: SegmentInfo[],
  onSegmentDownloaded: (buffer: ArrayBuffer, index: number) => void
) => {
  const concurrency = Math.min(config.concurrency, 8)
  let nextIndex = 0

  const worker = async () => {
    while (nextIndex < segments.length) {
      const index = nextIndex++
      const buffer = await downloadWithRetry(segments[index]!)
      onSegmentDownloaded(buffer, index)
    }
  }

  const workers = Array.from(
    { length: Math.min(concurrency, segments.length) },
    () => worker()
  )
  await Promise.all(workers)
}

미리 분할(비권장):
Worker 1: [세그먼트 0-49]   ← 이 세그먼트들이 크면 Worker 1이 병목이 됨
Worker 2: [세그먼트 50-99]  ← 조기 완료 후 유휴 대기

공유 카운터(FlowPick 채택):
Worker 1: 세그먼트 0 → 세그먼트 3 → 세그먼트 5 → ...
Worker 2: 세그먼트 1 → 세그먼트 4 → 세그먼트 7 → ...
Worker 3: 세그먼트 2 → 세그먼트 6 → 세그먼트 8 → ...

async function* segmentGenerator(
  segments: SegmentInfo[],
  signal?: AbortSignal
): AsyncGenerator<ArrayBuffer> {
  for (const segment of segments) {
    if (signal?.aborted) break
    const buffer = await downloadWithRetry(segment)
    yield buffer
  }
}

const downloadWithRetry = async (
  segment: SegmentInfo,
  maxRetries = 3
): Promise<ArrayBuffer> => {
  let lastError: unknown
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await downloadAndDecryptSegment(segment)
    } catch (e) {
      lastError = e
      if (attempt < maxRetries - 1) {
        // 지수 백오프: 400ms, 800ms, 1600ms
        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 400))
      }
    }
  }
  throw lastError
}

class FetchError extends Error {
  constructor(
    message: string,
    public status: number,
    public url: string
  ) {
    super(message)
    this.name = 'FetchError'
  }
}

const decryptAES128 = async (
  encryptedData: ArrayBuffer,
  key: ArrayBuffer,
  iv?: Uint8Array
): Promise<ArrayBuffer> => {
  const keyBytes = await crypto.subtle.importKey(
    'raw', key,
    { name: 'AES-CBC' },
    false,
    ['decrypt']
  )

  const ivBuffer = iv ? new Uint8Array(iv) : new Uint8Array(16)

  const decrypted = await crypto.subtle.decrypt(
    { name: 'AES-CBC', iv: ivBuffer },
    keyBytes,
    encryptedData
  )

  return decrypted
}

// 의사 코드
const merged = new Uint8Array(totalSize)
let offset = 0
for (const segment of segments) {
  merged.set(new Uint8Array(segment), offset)
  offset += segment.byteLength
}

HLS 스트림 처리:
  세그먼트 0 → 세그먼트 1 → 세그먼트 2 → ... → 연결 → 출력

DASH 스트림 처리(오디오/비디오 분리):
  초기화 세그먼트 → 비디오 세그먼트 0 → 비디오 세그먼트 1 → ... ─┐
                                              ├→ FFmpeg 병합 → 출력
  초기화 세그먼트 → 오디오 세그먼트 0 → 오디오 세그먼트 1 → ... ─┘

async function createFSAStream(
  filename: string,
  dirHandle?: FileSystemDirectoryHandle | null
): Promise<WritableStream<Uint8Array>> {
  let handle: FileSystemFileHandle

  if (dirHandle) {
    // 이미 디렉토리 권한 있음, 바로 파일 생성
    handle = await dirHandle.getFileHandle(filename, { create: true })
  } else {
    // 팝업으로 사용자에게 저장 위치 선택 요청
    handle = await window.showSaveFilePicker!({
      suggestedName: filename,
      types: [{
        description: 'Video',
        accept: { 'video/mp4': ['.mp4'] }
      }]
    })
  }

  const writable = await handle.createWritable()

  return new WritableStream<Uint8Array>({
    async write(chunk) { await writable.write(chunk) },
    async close() { await writable.close() },
    async abort(reason) { await writable.abort(reason) }
  }, {
    highWaterMark: 16 * 1024 * 1024 // 16MB 버퍼
  })
}

async function createStreamSaverStream(
  filename: string,
  fileSize?: number
): Promise<WritableStream<Uint8Array>> {
  const ss = await getStreamSaver()
  const fileStream = ss.createWriteStream(filename, { size: fileSize })
  return fileStream
}

// 의사 코드
const blob = new Blob([mergedData], { type: 'video/mp4' })
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = filename
a.click()
URL.revokeObjectURL(url)

async function estimateSegmentsSize(
  segments: ArrayBuffer[] | AsyncGenerator<ArrayBuffer>,
  totalCount: number
): Promise<{ estimatedSize: number; isEstimate: boolean }> {
  // 샘플링 수량: min(5, max(1, totalCount * 0.1))
  const sampleCount = Math.min(5, Math.max(1, Math.floor(totalCount * 0.1)))

  // 처음 몇 세그먼트 다운로드 및 평균 크기 계산
  let sampledTotal = 0
  for (let i = 0; i < sampleCount; i++) {
    sampledTotal += sampleSegment.byteLength
  }

  const avgSample = sampledTotal / sampleCount
  return {
    estimatedSize: Math.round(avgSample * totalCount),
    isEstimate: true
  }
}

예상 크기 < 800MB  → 임의 전략 가능
예상 크기 800MB-1.5GB → 우선 스트리밍 쓰기, Blob 모드 경고 표시
예상 크기 > 1.5GB → 강제 스트리밍 쓰기, Blob 모드 거부

const MEMORY_CONFIG = {
  maxBlobSize: 1500 * 1024 * 1024,    // 1.5GB 하드 제한
  warnBlobSize: 800 * 1024 * 1024,    // 800MB 경고 임계값
}

const checkMemoryPressure = (): 'normal' | 'warning' | 'critical' => {
  // 현재 할당된 세그먼트 버퍼 총 크기 확인
  const allocatedMB = allocatedBuffers.reduce((sum, buf) => sum + buf.byteLength, 0) / 1048576

  if (allocatedMB > 1200) return 'critical'
  if (allocatedMB > 600) return 'warning'
  return 'normal'
}

총 진행률 = (파싱 단계 % × 파싱 가중치) 
          + (다운로드 단계 % × 다운로드 가중치) 
          + (처리 단계 % × 처리 가중치) 
          + (쓰기 단계 % × 쓰기 가중치)

class SpeedEstimator {
  private samples: Array<{ timestamp: number; bytes: number }> = []
  private windowSize = 10000 // 10초 윈도우

  addSample(bytes: number): void {
    const now = Date.now()
    this.samples.push({ timestamp: now, bytes })

    // 윈도우 외 샘플 제거
    while (this.samples.length > 0 && now - this.samples[0]!.timestamp > this.windowSize) {
      this.samples.shift()
    }
  }

  getSpeed(): number {
    if (this.samples.length < 2) return 0

    const oldest = this.samples[0]!
    const newest = this.samples[this.samples.length - 1]!
    const timeDiff = newest.timestamp - oldest.timestamp
    const totalBytes = newest.bytes - oldest.bytes

    return (totalBytes / timeDiff) * 1000 // bytes/sec
  }
}

ETA = (총 바이트 - 다운로드된 바이트) / 현재 속도

function updateProgressUI(progress: ProgressData): void {
  requestAnimationFrame(() => {
    progressBar.value = progress.percentage
    speedEl.textContent = formatSpeed(progress.speed)
    etaEl.textContent = formatTime(progress.eta)
  })
}

async function cancelDownload(abortController: AbortController): Promise<void> {
  // 1. AbortSignal 발신
  abortController.abort()

  // 2. 진행 중인 fetch 요청 취소
  // (AbortSignal이 fetch에 전달되어 있음)

  // 3. Worker Pool 중지
  // (다음 세그먼트 획득 시 aborted 체크)

  // 4. 임시 파일 정리
  await cleanupTempFiles()

  // 5. 메모리 해제
  releaseBuffers()
}

// 같은 도메인의 세그먼트는 자동으로 연결 공유
// (브라우저 fetch API 내장 최적화)

const throttleDownload = async (
  url: string,
  maxBytesPerSec: number
): Promise<ArrayBuffer> => {
  const response = await fetch(url)
  const reader = response.body!.getReader()

  const chunks: Uint8Array[] = []
  let totalBytes = 0
  const startTime = Date.now()

  while (true) {
    const { done, value } = await reader.read()
    if (done) break

    chunks.push(value!)
    totalBytes += value!.length

    // 속도 초과 시 대기
    const elapsed = Date.now() - startTime
    const expected = (totalBytes / maxBytesPerSec) * 1000
    if (elapsed < expected) {
      await sleep(expected - elapsed)
    }
  }

  return concatenate(chunks)
}

다운로드 → [버퍼] → 복호화 → [버퍼] → 디스크 쓰기 → 버퍼 해제

// FFmpeg 입력용 원시 버퍼 직접 사용
// (불필요한 복사 방지)
const ffmpeg = createFFmpeg({ log: true })

// TS → MP4 변환 시:
// 1. 세그먼트를 FFmpeg의 virtual filesystem에 쓰기
// 2. FFmpeg 실행
// 3. 출력 파일 읽기
// 4. virtual filesystem 정리

// 좋음: 비차단
async function startDownload() {
  updateUI('downloading')
  await engine.download()
  updateUI('complete')
}

// 나쁨: 차단
function startDownload() {
  updateUI('downloading')
  engine.download() // 메인 스레드 차단!
  updateUI('complete')
}

// FlowPick DevTools 확장(있는 경우)
window.__FLOWPICK_ENGINE__.getStatus()
// => { state: 'downloading', progress: 45, speed: '2.3 MB/s' }

// 또는 Console 직접 로그 확인
// [FlowPick] [INFO] Download started: video.m3u8
// [FlowPick] [WARN] Segment #42 retry 1/3
// [FlowPick] [ERROR] Segment #42 failed after 3 retries