⚡ 서비스 워커 캐싱 전략 마스터 가이드

[브라우저 메인 스레드 (UI / DOM)]
               │
       (1) Fetch 요청 발생
               ▼
[서비스 워커 (Service Worker Thread)] ──(2) 캐시 확인──▶ [캐시 스토리지 (Cache Storage)]
               │                                                │
       (3) 캐시 미스 발생 시                                    │ (2-A) 캐시 히트 시 즉시 반환
               ▼                                                ▼
     [실제 네트워크 (인터넷)] ◀───────────────────────── [브라우저 화면 표출]

// sw.js - 정밀하게 설계된 Cache-First 전략
const STATIC_CACHE_NAME = 'static-assets-v2';
const FALLBACK_IMAGE_URL = '/images/fallback-placeholder.png';

// 설치(install) 단계에서 핵심 자산 및 폴백 이미지 사전 캐싱 (Precaching)
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(STATIC_CACHE_NAME).then((cache) => {
      console.log('[Service Worker] 필수 정적 에셋 프리캐싱 진행 중...');
      return cache.addAll([
        '/',
        '/index.html',
        '/css/main.css',
        '/js/app.js',
        FALLBACK_IMAGE_URL
      ]);
    }).then(() => self.skipWaiting())
  );
});

self.addEventListener('fetch', (event) => {
  const requestUrl = new URL(event.request.url);

  // GET 요청 및 정적 자산(이미지, 폰트, 스타일 등)에 대해서만 Cache-First 적용
  if (event.request.method === 'GET' && 
      (event.request.destination === 'image' || 
       event.request.destination === 'font' || 
       requestUrl.pathname.startsWith('/static/'))) {
    
    event.respondWith(
      caches.open(STATIC_CACHE_NAME).then((cache) => {
        return cache.match(event.request).then((cachedResponse) => {
          if (cachedResponse) {
            // 캐시 히트: 로컬에서 즉시 반환 (성능 최적화의 핵심)
            return cachedResponse;
          }

          // 캐시 미스: 네트워크에서 가져온 후 유효성 검증을 거쳐 캐시에 기록
          return fetch(event.request).then((networkResponse) => {
            // 응답이 유효하지 않은 경우(에러 페이지, 불완전 응답 등) 캐싱하지 않고 그대로 반환
            if (!networkResponse || networkResponse.status !== 200 || networkResponse.type !== 'basic') {
              return networkResponse;
            }

            // 응답 스트림은 단 한 번만 읽을 수 있으므로 복제(Clone)하여 보관
            cache.put(event.request, networkResponse.clone());
            return networkResponse;
          }).catch((err) => {
            console.error('[Service Worker] 네트워크 요청 실패. 폴백 처리 진행.', err);
            // 만약 이미지 요청이 실패한 경우, 사전에 준비한 폴백 대체 이미지 반환
            if (event.request.destination === 'image') {
              return cache.match(FALLBACK_IMAGE_URL);
            }
            throw err;
          });
        });
      })
    );
  }
});

[요청 발생] ──▶ (1) 네트워크 호출 시도 ──▶ [성공] ──▶ 캐시 업데이트 후 응답 반환
                    │
                 [실패 / 타임아웃]
                    ▼
          (2) 캐시 스토리지 조회 ──▶ [성공] ──▶ 이전 캐시 데이터 반환 (오프라인 폴백)
                    │
                 [실패]
                    ▼
          (3) 최후의 에러 핸들러 작동 (예: "네트워크 연결이 끊겼습니다" 안내)

// sw.js - 네트워크 타임아웃이 결합된 Network-First 전략
const DYNAMIC_CACHE_NAME = 'dynamic-api-v2';
const NETWORK_TIMEOUT_MS = 3000; // 3초 타임아웃 지정

// 지정된 시간 이후 강제로 reject하는 타이머 프로미스 생성 헬퍼
function timeout(ms) {
  return new Promise((_, reject) => {
    setTimeout(() => reject(new Error('Network request timed out')), ms);
  });
}

self.addEventListener('fetch', (event) => {
  const requestUrl = new URL(event.request.url);

  // 사용자 프로필 정보 및 대시보드 API 요청에 적용
  if (requestUrl.pathname.startsWith('/api/v2/user/') || requestUrl.pathname.includes('/dashboard')) {
    event.respondWith(
      caches.open(DYNAMIC_CACHE_NAME).then((cache) => {
        // Promise.race를 이용해 네트워크 요청과 타임아웃 타이머 중 먼저 완료되는 쪽을 실행
        return Promise.race([
          fetch(event.request).then((networkResponse) => {
            // 정상 응답 수신 시 캐시 갱신 후 반환
            if (networkResponse.status === 200) {
              cache.put(event.request, networkResponse.clone());
            }
            return networkResponse;
          }),
          timeout(NETWORK_TIMEOUT_MS)
        ]).catch((error) => {
          console.warn('[Service Worker] 네트워크 지연 또는 장애 발생. 로컬 캐시 조회 진행.', error);
          
          // 네트워크 실패 또는 타임아웃 시 캐시 스토리지에서 대체 데이터 탐색
          return cache.match(event.request).then((cachedResponse) => {
            if (cachedResponse) {
              return cachedResponse;
            }
            // 캐시에도 없다면 JSON 포맷의 오프라인 안내 객체 반환
            return new Response(
              JSON.stringify({ 
                error: 'offline', 
                message: '현재 네트워크에 연결되어 있지 않으며, 저장된 오프라인 데이터가 없습니다.' 
              }), 
              { headers: { 'Content-Type': 'application/json' } }
            );
          });
        });
      })
    );
  }
});

// sw.js - Stale-While-Revalidate 전략 구현 및 UI 동기화 기법
const REVALIDATE_CACHE_NAME = 'stale-assets-v2';

self.addEventListener('fetch', (event) => {
  const requestUrl = new URL(event.request.url);

  // 메인 스크립트 및 자주 변경되는 레이아웃 스타일 적용
  if (event.request.destination === 'script' || event.request.destination === 'style') {
    event.respondWith(
      caches.open(REVALIDATE_CACHE_NAME).then((cache) => {
        return cache.match(event.request).then((cachedResponse) => {
          
          // 백그라운드에서 네트워크 요청을 비동기로 조용히 수행
          const fetchPromise = fetch(event.request).then((networkResponse) => {
            if (networkResponse.status === 200) {
              // 캐시 데이터가 업데이트되었음을 감지하여 메인 스레드로 브로드캐스트 전송 가능 (옵션)
              cache.put(event.request, networkResponse.clone()).then(() => {
                // UI를 실시간으로 업데이트하기 위해 postMessage 활용 가능
                self.clients.matchAll().then((clients) => {
                  clients.forEach((client) => {
                    client.postMessage({
                      type: 'CACHE_UPDATED',
                      url: event.request.url
                    });
                  });
                });
              });
            }
            return networkResponse;
          }).catch((err) => console.log('[Service Worker] 백그라운드 갱신 실패 (오프라인 상태 등):', err));

          // 캐시 데이터가 존재하면 즉시 반환(성능 최적화), 없으면 백그라운드 fetch 완료 시까지 대기하여 반환
          return cachedResponse || fetchPromise;
        });
      })
    );
  }
});

// sw.js - Cache-Only 구현
const OFFLINE_STATIC_CACHE = 'offline-static-v1';

self.addEventListener('fetch', (event) => {
  const requestUrl = new URL(event.request.url);
  
  if (requestUrl.pathname.includes('/assets/static-logos/')) {
    event.respondWith(
      caches.match(event.request).then((cachedResponse) => {
        if (cachedResponse) {
          return cachedResponse;
        }
        // 캐시에 없을 경우 브라우저 레벨 에러 발생 방지를 위한 빈 픽셀 응답 처리
        return new Response('', { status: 404, statusText: 'Not Found in Cache' });
      })
    );
  }
});

// sw.js - Network-Only 구현 및 예외 경로 지정
self.addEventListener('fetch', (event) => {
  const requestUrl = new URL(event.request.url);

  // 결제 검증 및 실시간 메시지 발송 API는 원천적으로 캐시 처리 배제
  if (requestUrl.pathname.startsWith('/api/v2/payment/') || requestUrl.pathname.startsWith('/api/v2/chat/send')) {
    event.respondWith(
      fetch(event.request).catch((err) => {
        // 네트워크 연결 실패 시 에러 응답 직접 가공하여 반환
        return new Response(
          JSON.stringify({ 
            success: false, 
            error: 'NetworkRequired', 
            message: '보안 통신 경로로써 반드시 안정적인 인터넷 연결이 필요합니다.' 
          }), 
          { status: 503, headers: { 'Content-Type': 'application/json' } }
        );
      })
    );
  }
});

// sw.js - 프로덕션 수준의 구형 캐시 버전 스위칭 및 소거 기법
const CACHE_VERSION = 'v3';
const CURRENT_CACHES = {
  static: `static-cache-${CACHE_VERSION}`,
  dynamic: `dynamic-cache-${CACHE_VERSION}`
};

self.addEventListener('activate', (event) => {
  const expectedCacheNames = Object.values(CURRENT_CACHES);

  event.waitUntil(
    caches.keys().then((cacheNames) => {
      return Promise.all(
        cacheNames.map((cacheName) => {
          // 현재 활성화된 캐시 버전 목록에 포함되어 있지 않은 구형 캐시는 전부 삭제
          if (!expectedCacheNames.includes(cacheName)) {
            console.warn('[Service Worker] 구형 캐시 발견 및 자동 청소 중:', cacheName);
            return caches.delete(cacheName);
          }
        })
      );
    }).then(() => {
      // 새로운 서비스 워커가 활성화되자마자 대기 중인 클라이언트들을 강제로 제어(Claim)
      return self.clients.claim();
    })
  );
});

// sw.js - 캐시 보관 개수 제한 헬퍼 구현
function trimCache(cacheName, maxItems) {
  caches.open(cacheName).then((cache) => {
    cache.keys().then((keys) => {
      if (keys.length > maxItems) {
        // 가장 오래된 첫 번째 캐시 아이템부터 삭제 조치 (FIFO 변형)
        cache.delete(keys[0]).then(() => {
          trimCache(cacheName, maxItems); // 재귀 호출로 한계치 도달 시까지 반복
        });
      }
    });
  });
}

// 사용 예시: 동적 캐싱이 일어날 때마다 호출
// trimCache(CURRENT_CACHES.dynamic, 50); // 최대 50개 유지

// sw.js - Range Request 감지 시 서비스 워커 가로채기 바이패스 처리
self.addEventListener('fetch', (event) => {
  const requestHeaders = event.request.headers;
  
  // 요청 헤더에 range 속성이 포함되어 있는지 명확히 감지
  if (requestHeaders.has('range')) {
    event.respondWith(
      // Range 요청은 단순 캐시 조작이 불가하므로, 서비스 워커 개입을 차단하고 
      // 네트워크로 직접 연결(Bypass)하여 브라우저 네이티브 스트리밍 모듈에 제어권을 위임합니다.
      fetch(event.request)
        .catch((err) => {
          console.error('[Service Worker] Range 요청을 네트워크로 바이패스하는 도중 실패:', err);
          // 오프라인 상태일 경우 적절한 대체 미디어 반환 불가 시 에러 처리
          return new Response('Offline Media Unavailable', { status: 503 });
        })
    );
  }
});

// sw.js - 보안 및 정합성 보존을 위한 강력한 블랙리스트 패턴 필터링 예제
const BLACKLIST_PATTERNS = [
  /\/api\/v[0-9]\/auth\//,         // 사용자 로그인/MFA 인증 토큰 API
  /\/api\/v[0-9]\/payment\//,      // 결제, 환불, 카드 승인 트랜잭션 API
  /\/api\/v[0-9]\/admin\//,        // 관리자 백오피스 제어 API
  /service-worker\.js$/,           // 서비스 워커 자체 파일 (캐싱 시 영원히 업데이트 불가)
  /index\.html$/                   // 메인 HTML (자산 변경 추적이 복잡한 정적 세팅의 경우)
];

function isBlacklisted(url) {
  return BLACKLIST_PATTERNS.some((pattern) => pattern.test(url));
}

self.addEventListener('fetch', (event) => {
  const requestUrl = event.request.url;

  if (isBlacklisted(requestUrl)) {
    // 블랙리스트 매칭 시 캐시 스토리지를 아예 거치지 않고 Network-Only로 직접 패스스루 처리
    event.respondWith(fetch(event.request));
    return;
  }
});

[Application 탭] ➡️ [Service Workers]
┌────────────────────────────────────────────────────────┐
│ ⬜ Offline      ☑️ Update on reload     ⬜ Bypass for network │
└────────────────────────────────────────────────────────┘