폴백 응답에 immutable 캐시를 그대로 물려주면 안 되는 이유
커버 변형이 없을 때 원본으로 대신 응답한 폴백에 긴 immutable 캐시가 붙었던 문제를 정리했다. 캐시 수명 분리와 당시 코드 검증, 기존 응답의 별도 확인을 구분한다.

작업 기록에는 workers.dev URL의 응답 헤더에서 Cache-Control이 immutable인 것을 직접 확인했다고 남아 있다.
코드의 IMMUTABLE_CACHE_CONTROL 상수 값은 public, max-age=31536000, immutable이었다.
2026년 7월 29일 새 글 2편을 발행한 직후, 커버는 요청한 축소본 대신 원본으로 반환되고 있었다.
긴 이미지 캐시를 적용한 운영자에게 당황스러운 지점은 워커 로직 자체가 정상 동작하는데도 이런 응답이 남을 수 있다는 것이다.
이 사례의 수정은 정상 객체와 임시 폴백이 물려받는 캐시 수명을 분리하는 것이었다.
변형 이미지가 생성되기 전에 변형 URL이 요청됐고, 원본을 대신 보내는 폴백에 정상 응답과 같은 장기 캐시 정책이 붙었다. 다만 코드를 고치는 일과 이미 브라우저나 엣지에 저장된 응답을 처리하는 일은 별개다. 당시 작업 기록도 코드 수정·검증과 배포 후 캐시 확인을 구분해 남겼다.
같은 URL이 곧 축소본을 반환해야 한다면, 지금 대신 보내는 원본에는 정상 객체와 다른 캐시 수명이 필요하다.
축소본 대신 원본을 반환한 커버
이 블로그의 커버 srcset은 @640과 @1024 축소본을 이미지 후보로 사용한다.
예를 들어 cover@640.webp는 원본에서 만든 축소본의 이름이다.
하지만 변형 URL이 준비됐다고 R2 저장소에 실제 축소본 업로드까지 끝났다는 뜻은 아니다.
업로드 전에 해당 URL이 요청되면 워커는 원본으로 폴백할 수 있다.
폴백은 축소본이 없을 때 깨진 이미지 대신 원본을 보여주기 위한 경로였다. 이미지는 보이지만 요청한 축소본보다 큰 파일을 보낼 수 있다는 절충이 있다. 문제는 임시로 보낸 이 응답에도 정상 이미지와 같은 긴 캐시 수명을 부여했다는 점이다.
Cache-Control: public, max-age=31536000, immutable
기록에 남은 관찰은 원본이 반환된 증상과 라이브 URL의 응답 헤더다. 워커 로직 자체가 정상 동작하고 있었다는 확인도 함께 남아 있다. 최초 요청을 누가 보냈는지, 방문자의 브라우저 디스크 캐시에 무엇이 표시됐는지까지 확인한 로그는 없다.
immutable이 약속하는 기간
RFC 8246의 immutable 정의는 응답이 신선한 기간 동안 원본 내용이 바뀌지 않는다는 약속이다.
영구 저장을 뜻하지 않으며, 수명이 지난 응답에는 일반적인 캐시 규칙이 적용된다.
이 사례에서 주의할 값은 함께 지정된 max-age=31536000, 즉 1년이라는 신선도 수명이다.
그 기간에 캐시된 응답을 계속 사용하면 저장소에 나중에 올라온 축소본을 바로 확인하지 않을 수 있다. 폴백 URL은 지금 원본을 보내더라도 축소본이 준비된 뒤에는 다른 바이트를 보내야 한다. 따라서 HTTP 상태가 200이라는 이유만으로 정상 객체와 폴백에 같은 캐시 수명을 적용하기 어렵다.
이 사이트는 장기 immutable 캐시를 쓰는 이미지의 내용이 바뀌면 새 키로 올리고 본문 참조도 바꾸는 운영 규칙을 둔다. 이미 저장된 응답과 새 파일이 같은 URL을 두고 충돌하는 일을 피하기 위한 기준이다. 변형이 아직 없는 임시 상태에는 별도로 짧은 캐시 정책을 적용해야 한다.
정상 응답과 폴백이 만나는 지점
이미지 함수는 먼저 Workers Cache API에서 요청 URL의 응답을 찾는다. 캐시에 없으면 R2에서 요청한 키를 조회하고, 변형 키가 없으면 원본 키를 한 번 더 조회한다. 정상 객체를 찾은 경우와 원본으로 폴백한 경우는 이후의 헤더 작성 경로에서 만난다.
- 캐시에 요청 URL의 응답이 있으면 반환한다.
- 캐시가 없으면 R2에서 요청한 이미지 키를 찾는다.
- 변형 이미지가 없고 키가 변형 형식에 맞으면 원본을 한 번 조회한다.
- 객체가 없으면 404를 반환하고, 있으면 응답 헤더를 작성해 Cache API에 저장한다.
수정 전에는 정상 객체와 폴백 모두에 긴 immutable 헤더가 붙었다. 이후 같은 URL의 응답이 캐시에 있으면 함수는 R2 조회 전에 그 응답을 반환한다. 축소본이 나중에 생겨도 캐시에 남은 원본 응답이 먼저 선택될 수 있었던 이유다.
폴백의 캐시 수명을 분리한 수정
코드는 코딩 에이전트가 작성했으며, 작성자가 아닌 별도 검증 경로가 검토를 맡았다.
당시 수정은 servedVariantFallback으로 요청한 객체를 찾은 경우와 원본으로 대체한 경우를 구분했다.
정상 객체에는 기존 정책을 유지하고, 폴백에만 새 상수 FALLBACK_CACHE_CONTROL을 적용했다.
그 값인 public, max-age=300은 5분이며, 이 서비스가 선택한 임시 수명이다.
const IMMUTABLE_CACHE_CONTROL =
"public, max-age=31536000, immutable";
const FALLBACK_CACHE_CONTROL = "public, max-age=300";
headers.set(
"Cache-Control",
servedVariantFallback
? FALLBACK_CACHE_CONTROL
: IMMUTABLE_CACHE_CONTROL,
);
당시 기록은 Cloudflare의 Cache API 문서를 근거로 응답의 Cache-Control이 캐시 수명에 사용된다고 설명한다.
따라서 이 코드에서는 cache.put()에 전달하는 응답 헤더를 바꾸는 것으로 정책을 분리했다.
별도 TTL 옵션을 추가하지 않았으며, 변경 규모는 2개 파일에 +16 / −2줄이었다.
기록에 남은 검증 범위는 타입 검사와 정상·폴백 경로의 캐시 헤더 검사다. 수정에는 기존 이미지 테스트 각각에 정상 응답의 immutable 정책과 폴백의 짧은 정책을 확인하는 assertion이 추가됐다. 이 범위는 코드가 어떤 헤더를 내보내야 하는지 다루며, 배포 후 모든 캐시가 새 응답으로 교체됐다는 증거는 아니다.
| 응답 | 이 함수의 정책 | 적용 조건·한계 |
|---|---|---|
| 요청한 객체를 찾음 | 1년, immutable | 같은 키의 내용을 덮어쓰지 않는 발행 규칙이 전제 |
| 원본으로 폴백 | 300초, immutable 없음 | 임시 응답이므로 짧게 저장. 즉시 전환까지 보장하지 않음 |
| 객체를 찾지 못함 | 404 반환, 이 함수에서는 Cache API 저장 안 함 | 다른 프록시나 별도 캐시 규칙까지 설명하는 것은 아님 |
이미 저장된 응답은 별도로 확인한다
새 코드의 300초 정책이 기존에 저장된 1년짜리 응답의 헤더를 소급해서 바꾸지는 않는다. 당시 기록에는 배포와 기존 캐시 제거가 후속 확인으로 남아 있다. 기존 응답의 퍼지는 필요시 처리할 항목이었으며, 배포 후 캐시 확인까지 완료됐다는 기록은 없다.
2026-09-19에 조회한 Cloudflare Cache API 공식 문서에 따르면 캐시의 저장 내용은 원래 데이터센터 밖으로 자동 복제되지 않는다.
같은 문서에서 cache.delete()도 워커가 실행된 데이터센터의 캐시만 제거한다고 설명한다.
한 위치에서 새 이미지를 확인했다고 다른 위치의 캐시 상태까지 같다고 볼 수 없다.
엣지 캐시를 제거하더라도 방문자 브라우저에 저장된 복사본을 직접 지우는 것은 아니다.
후속 검증을 한다면 테스트용 새 이미지 키로 ‘변형 없음 → 원본 폴백 → 변형 업로드 → 변형 반환’ 순서를 확인한다. 각 응답의 헤더와 실제 이미지 바이트를 함께 비교하고, 필요하면 기존 키의 캐시 제거 또는 새 키 발행을 선택한다. 이는 이 글이 제안하는 검사 절차이며, 당시 모두 수행한 실험으로 기록된 것은 아니다.
재시도와 폴백을 다룰 때도 예외 경로의 상태를 정상 결과와 구분해야 한다. 이미지 캐시에서는 그 구분이 응답 수명으로 이어진다. 자신의 워커를 점검할 때는 정상 이미지에 붙인 헤더뿐 아니라, 변형을 찾지 못한 응답이 어떤 헤더를 물려받는지도 확인해야 한다.
아직 댓글이 없습니다.