📥 Background Fetch API 완벽 가이드: 탭을 닫아도 계속되는 백그라운드 대용량 파일 다운로드·업로드

// main.js - 메인 스레드
async function startBackgroundDownload() {
  // 1. 서비스 워커 등록 확인
  const registration = await navigator.serviceWorker.ready;
  
  if (!('backgroundFetch' in registration)) {
    console.warn('Background Fetch API를 지원하지 않는 브라우저입니다.');
    return;
  }

  // 2. 백그라운드 패치 요청 등록
  try {
    const bgFetch = await registration.backgroundFetch.fetch(
      'download-game-assets-v1', // 고유 작업 ID (Tag ID)
      [
        '/assets/models/character.glb',
        '/assets/textures/terrain.png',
        '/assets/audio/background.mp3'
      ], // 단일 URL 또는 URL 배열/Request 객체 배열
      {
        title: '대용량 게임 리소스 다운로드',
        icons: [
          { src: '/images/icon-192.png', sizes: '192x192', type: 'image/png' }
        ],
        downloadTotal: 150 * 1024 * 1024 // 총 예상 다운로드 크기 (150MB, 진행률 표시용)
      }
    );

    console.log('Background Fetch 등록 성공:', bgFetch.id);
  } catch (error) {
    console.error('Background Fetch 등록 실패:', error);
  }
}

// main.js
async function trackProgress(bgFetchId) {
  const registration = await navigator.serviceWorker.ready;
  const bgFetch = await registration.backgroundFetch.get(bgFetchId);

  if (!bgFetch) return;

  bgFetch.addEventListener('progress', () => {
    // bgFetch.downloaded: 지금까지 다운로드된 바이트 수
    // bgFetch.downloadTotal: 전체 바이트 수 (등록 시 지정한 값)
    const percent = Math.round((bgFetch.downloaded / bgFetch.downloadTotal) * 100);
    
    console.log(`현재 진행률: ${percent}% (${bgFetch.downloaded} / ${bgFetch.downloadTotal} bytes)`);
    
    // DOM 진행률 바 업데이트
    const progressBar = document.getElementById('my-progress-bar');
    if (progressBar) {
      progressBar.value = percent;
    }
  });
}

// sw.js - 서비스 워커 스레드

// 1. 모든 파일 다운로드가 성공적으로 완료된 경우
self.addEventListener('backgroundfetchsuccess', (event) => {
  const bgFetch = event.registration;

  event.waitUntil((
    async () => {
      // Cache Storage 열기
      const cache = await caches.open('offline-game-assets-v1');
      
      // 백그라운드 패치로 전달받은 모든 요청/응답 쌍 가져오기
      const records = await bgFetch.matchAll();
      
      const recordPromises = records.map(async (record) => {
        const response = await record.responseReady;
        // Cache Storage에 저장
        await cache.put(record.request, response);
      });

      await Promise.all(recordPromises);
      
      // 성공 상태 알림 표시
      await event.updateUI({ title: '모든 게임 자산 다운로드 완료!' });
    }
  )());
});

// 2. 다운로드가 실패했거나 취소된 경우
self.addEventListener('backgroundfetchfail', (event) => {
  console.error('Background fetch 실패:', event.registration.id);
  // 실패한 리소스 정리 작업 수행 가능
});

// 3. 사용자가 브라우저 OS 알림창 UI를 클릭했을 때
self.addEventListener('backgroundfetchclick', (event) => {
  const bgFetch = event.registration;

  event.waitUntil((
    async () => {
      // 이미 열려 있는 탭이 있다면 포커스, 없으면 새 창 열기
      const windowClients = await self.clients.matchAll({ type: 'window' });
      for (const client of windowClients) {
        if (client.url.includes('/download-page') && 'focus' in client) {
          return client.focus();
        }
      }
      if (self.clients.openWindow) {
        return self.clients.openWindow('/download-page');
      }
    }
  )());
});

// sw.js - Background Fetch + OPFS 연동
self.addEventListener('backgroundfetchsuccess', (event) => {
  const bgFetch = event.registration;

  event.waitUntil((
    async () => {
      // OPFS 루터 디렉토리 확보
      const root = await navigator.storage.getDirectory();
      const mediaFolder = await root.getDirectoryHandle('downloaded_videos', { create: true });

      const records = await bgFetch.matchAll();

      for (const record of records) {
        const response = await record.responseReady;
        const blob = await response.blob();
        
        // URL 패턴 기반 파일명 추출
        const url = new URL(record.request.url);
        const fileName = url.pathname.split('/').pop() || 'file.bin';
        
        // OPFS 파일 핸들 생성 및 작성
        const fileHandle = await mediaFolder.getFileHandle(fileName, { create: true });
        const accessHandle = await fileHandle.createWritable();
        await blob.stream().pipeTo(accessHandle);
      }

      await event.updateUI({ title: 'OPFS 저장 완료!' });
    }
  )());
});