리소스 다운로드 HTTP Range 이어받기

마지막 업데이트 2026-07-22

1. 배경 — 왜 바꿨나

아동 수업에 필요한 리소스는 presigned URL을 통해 S3에서 내려받아 Cache API(디스크)에 캐싱된다. 모바일/저사양 회선에서 대용량 영상을 받다가 Wi-Fi가 잠깐 끊기면, 기존 fetch().then(res => res.blob()) 방식은 받던 데이터를 전부 버리고 처음부터 다시 받았다.

• 네트워크가 불안정할수록 재시도 비용이 누적 → 수업 시작 전 캐싱이 느려지거나 실패
• TypeError: Failed to fetch(연결 끊김)와 403(presigned URL 만료)이 구분 없이 똑같이 실패 처리됨
• 중간에 잘린(truncate) 응답을 정상 완료로 오인할 여지

2. 해결 — fetchResumable

chunks(받은 조각)와 received(받은 바이트 수)를 재시도 루프 바깥에 두는 것이 전부의 핵심이다. try 안에서 예외가 나도 누적분이 초기화되지 않고 다음 시도로 그대로 이어진다.

const chunks = [];     // ← 루프 밖. catch 후에도 보존
let received = 0;      // ← 루프 밖. 끊긴 지점 = Range 시작 오프셋
let total = 0;
let supportsRange = true;

for (let attempt = 0; attempt <= maxRetries; attempt++) {   // 최초 1 + 재시도 3 = 최대 4회
  try {
    const isResume = received > 0 && supportsRange;
    const headers = isResume ? { Range: `bytes=${received}-` } : {};
    const response = await fetch(url, { headers });
    ...
    const reader = response.body.getReader();
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      if (value) { chunks.push(value); received += value.length; }
    }
    if (total > 0 && received !== total) throw new Error("Incomplete download");
    return new Blob(chunks, { type: contentType });
  } catch (error) { ... }
}

3. 재시도 메커니즘

catch 블록은 두 갈래로 나뉜다.

① 즉시 중단 (재시도 없음)

• HTTP 상태 에러 — !response.ok && status !== 206이면 throw new Error("HTTP ..."). 메시지가 "HTTP "로 시작하면 break. 403 만료·404·5xx는 이어받기로 해결되지 않으므로 백오프 없이 즉시 실패.
• 마지막 시도 — attempt === maxRetries면 break 후 lastError throw.

② 지수 백오프 후 재시도

네트워크 오류(TypeError)나 미완료 다운로드만 재시도 대상. 대기 시간은 baseDelayMs × 2^attempt:

4. 엣지 케이스 처리

5. 적용 경로 — use-resource-cache

두 캐싱 경로 모두 캐시 미스일 때만 fetchResumable을 호출하고, 받은 blob을 Response로 감싸 버전 키(?v={updatedAt})로 Cache API에 저장한다.

6. 변경 파일

7. 전체 시나리오

대용량 영상 60% 받다가 Wi-Fi 끊김:

1. attempt=0 — 60%에서 reader.read() 끊김 → catch (chunks/received 보존) → 500ms 대기
2. attempt=1 — Range: bytes={60%}- 전송 → 서버 206 → 나머지 40% 이어받기 → received === total 통과 → blob 반환 ✅

presigned URL 만료:

1. attempt=0 — 서버 403 → throw "HTTP 403 Forbidden" → 재시도 없이 즉시 실패