Durable Objects 배포 기본값 변경: 300초 지연과 실제 실행 버전 확인

진행 중인 작업을 유지하며 새 실행 환경으로 전환하는 과정을 표현한 생성형 개념 이미지다. 실제 Cloudflare 화면이 아니다.

배포는 성공했는데 일부 Durable Object가 이전 응답을 반환한다면, 먼저 코드 업데이트 전략을 확인해야 한다. 배포된 버전과 현재 객체가 실행하는 버전의 전환 시점이 다를 수 있다.

Cloudflare는 2026년 10월 30일 Durable Objects의 기본 코드 업데이트를 즉시 적용에서 지연 적용으로 바꿨다고 발표했다. 활성 객체는 기본 최대 300초 동안 기존 코드로 동작하며 hibernate할 기회를 얻는다. 진행 중인 작업의 중단을 줄이려는 변경이지만, 모든 작업의 완료를 보장하는 기능은 아니다. 공식 발표

배포 성공과 전환 완료를 따로 본다

100% 배포를 기준으로, 비활성 객체는 다음 요청에 새 버전으로 시작한다. 활성 객체는 대기 중 구버전으로 새 요청도 받는다. 먼저 hibernate하면 다음 요청에 전환하고, 기한까지 활성 상태라면 reset 후 새 코드를 적용한다.

따라서 배포 직후 한 요청이 성공했다는 사실만으로 모든 기존 세션의 전환을 판정하기 어렵다. 운영 점검에는 배포 ID와 함께 객체가 실제 보고하는 빌드 식별자를 남기는 편이 좋다. 이는 문서의 동작을 바탕으로 한 검증 설계 제안이다. 전환 동작

지연 시간을 설정으로 드러낸다

아래는 기존 Wrangler 설정의 해당 부분에 병합할 예시다. 전체 프로젝트 설정이나 신규 클래스 마이그레이션을 대신하지 않는다.

max_delay는 초 단위이며 0~86400을 허용한다. 생략하면 300초다. 전략은 해당 Worker가 export하는 모든 Durable Object 클래스에 적용된다. 공식 설정 문서

긴 연결이 있다고 무조건 최대값을 키우기보다, 정상 작업 시간과 수정 코드가 적용되어야 할 시간을 함께 정한다. 장애 수정의 긴급성과 연결 중단 비용이 다르기 때문이다.

긴급 배포는 명시적으로 선택한다

다음은 이미 업로드한 버전을 즉시 적용하는 문서 기반 명령 예시다. VERSION_ID를 실제 대상으로 바꿔야 하며, 실행하면 배포 상태를 변경한다. 이 글에서는 실행하지 않았다.

CLI 플래그는 설정된 전략 전체를 대체한다. 다음 배포가 전략을 생략하면 이전의 즉시 적용 선택이 이어지는 대신 기본값을 사용한다. 단일 배포 설정

배포 파이프라인에는 선택한 전략과 이유도 남긴다. 상세 문서는 전략 필드가 write-only라고 설명하므로, 배포 조회 응답만으로 설정을 역추적하는 방식에 의존하지 않는다. REST 설명

WebSocket 연결과 메모리 상태는 다르다

Hibernation API를 쓰는 WebSocket은 객체가 hibernate한 뒤 새 코드로 전환할 때 연결을 유지할 수 있다. 이를 모든 WebSocket의 무중단 보장으로 확대하면 안 된다. 일반 WebSocket API와 outbound 연결에는 같은 hibernation 조건이 적용되지 않는다.

또한 hibernation 중 메모리 상태는 초기화되고, 다음 이벤트에서 constructor가 다시 실행된다. 연결에 필요한 상태는 문서의 attachment 직렬화·복원 방식과 영속 저장소를 검토해야 한다. 연결이 남아 있어도 객체 메모리가 그대로 남는 것은 아니다. WebSocket과 hibernation

배포 검증을 두 종류의 객체로 나눈다

다음은 스테이징 환경에서 적용할 검증 제안이다. 실제 Cloudflare 계정에 배포하거나 연결 지속 시간을 측정한 결과는 아니다.

1. 새 객체와 이미 활성 상태인 객체를 각각 준비한다.

2. 응답 또는 내부 진단 로그에 코드의 빌드 식별자를 기록한다. 외부 공개 엔드포인트에 계정 정보나 비밀 값을 노출하지 않는다.

3. 배포 직후 두 객체의 버전을 비교하고, 활성 객체는 작업 중·휴면 후·재접속 후를 구분해 기록한다.

4. 지연 상한을 넘는 작업과 강제 reset도 검사한다. 완료되지 않은 작업을 다시 수행할 때 중복 처리가 생기는지 확인한다.

5. 클라이언트 재연결과 상태 복원 경로를 별도 검사한다. 배포 API 성공만으로 합격 처리하지 않는다.

지연은 best-effort이며 런타임 업데이트 같은 다른 재시작을 늦추지 않는다. 점진 배포에서도 구버전이 남을 수 있는 기간 전체에 호환성을 유지해야 한다. 제한과 점진 배포

이번 변경을 적용할 때 가장 먼저 고칠 것은 “배포 성공이면 모든 객체도 새 코드”라는 검증 가정이다. 지연 전략을 명시하고, 실제 실행 버전과 상태 복원을 함께 확인하면 배포 후의 혼동을 줄일 수 있다.

검증 범위

공식 발표와 문서의 기본값·설정 범위·CLI 문법을 대조했다. 위 JSON 조각은 로컬 파서로 문법만 확인했다. Wrangler 배포, 실제 객체 전환, WebSocket 유지 및 성능 측정은 수행하지 않았다.