Michael JohnsonDurable Object 호출이 네트워크 오류로 끝나면, 이전에는 개발자가 다시 보낼지 판단해야 하는 경우가 많았습니다. 2026년 11월 5일부터는 Cloudflare 런타임이 이러한 재시도의 일부를 수행합니다. 런타임은 fetch() 호출과 stub을 통한 RPC 호출 중 일부 실패를 자동으로 재시도합니다. 이제 애플리케이션 코드에서 핵심 질문은 더 구체적입니다. 특정 메서드를 두 번째로 실행해도 안전한가?
답은 연결이 어디서 끊겼는지에 달려 있습니다. 런타임은 기본적으로 중복 실행 방지 기능을 유지하면서 일부 호출을 자동 재시도합니다. 전달 여부가 불확실하면 같은 요청 식별자를 사용하며, 객체가 첫 번째 시도를 이미 받았다면 재시도를 거부합니다. 명시적으로 retryable()로 표시한 메서드는 다르게 동작합니다. 첫 번째 시도가 객체에 도달했더라도 다시 실행될 수 있습니다. 따라서 이 표시는 상태와 부수 효과 모두에서 반복 실행이 안전한 작업에만 사용해야 합니다.
런타임이 재시도하는 범위
11월 5일 Cloudflare 발표에 따르면 재시도는 Worker나 다른 Durable Object가 수행한 Durable Object 대상 fetch() 호출과 RPC 호출에 적용됩니다. stub을 통한 호출에는 기본적으로 최초 시도와 최대 네 번의 재시도가 적용되며, 호출 시작 후 10초가 지나면 새로운 시도는 시작되지 않습니다.
재시도 조건은 .retryable 속성이 있는 오류입니다. 예를 들어 객체가 재시작 중이거나 이동 중이어서 요청에 도달하지 못했을 수 있습니다. 연결이 끊겨 객체가 요청을 받았는지 알 수 없는 경우에도 런타임은 재시도할 수 있습니다. 객체가 이미 요청을 받았다면 같은 식별자를 사용한 재시도는 거부됩니다. 런타임은 Durable Object 코드에서 발생한 오류, .overloaded 속성이 있는 오류, 500 같은 HTTP 응답은 재시도하지 않습니다. 이는 전달 오류가 아니라 핸들러의 응답이기 때문입니다.
전송 재시도는 작업 재실행과 다르다
요청을 다시 전송한다고 해서 메서드가 두 번 실행되는 것은 아닙니다. 결과가 불확실하면 런타임은 같은 식별자로 요청을 보내며, 객체가 원래 시도를 받았다면 재시도를 거부합니다. 이 방식은 일반적인 상황에서 네트워크 오류 하나로 인해 메서드가 다시 실행되는 일을 막습니다. 예를 들어 요금이 다시 청구되거나 레코드가 중복 생성되는 것을 방지합니다.
cloudflare:durable-objects의 retryable()로 메서드를 표시하면 경계가 달라집니다. 이 경우 첫 시도가 이미 시작되었을 가능성이 있어도 객체는 메서드를 다시 실행할 수 있습니다. Cloudflare는 두 가지 예를 듭니다. 상품 수량을 지정된 값으로 설정하는 것은 멱등적이지만, 수량을 1씩 늘리는 것은 그렇지 않습니다. 첫 번째 작업을 반복하면 같은 값이 설정되지만, 두 번째 작업을 반복하면 수량이 한 번 더 증가합니다.
저장소의 최종 상태뿐 아니라 메서드의 모든 효과를 점검해야 합니다. 재실행으로 결제가 하나 더 생성되거나 메시지가 전송되거나 외부 작업이 시작된다면, Durable Object 내부 상태가 같더라도 안전한 재시도라고 할 수 없습니다. 재실행해도 결과의 의미가 달라지지 않고 부수 효과도 중복되지 않는 경우에만 표시를 사용해야 합니다.
명시적 멱등성이 유용한 경우
값 설정, 상태 스냅샷 기록, 필드를 알려진 값으로 갱신하는 작업은 반복해도 대체로 같은 결과를 냅니다. 이런 메서드에 retryable()을 사용하면 처리가 시작된 뒤 연결이 끊기더라도 호출이 성공적으로 완료될 수 있습니다.
‘더하기’, ‘하나 더 만들기’, ‘차감하기’, ‘보내기’ 작업에는 보통 다른 보호 장치가 필요합니다. 재실행을 허용하기 전에 비즈니스 작업이 중복을 인식하는지, 또는 반복해도 효과가 두 번 발생하지 않도록 설계되었는지 확인하세요. 함수 이름만으로는 안전성을 보장할 수 없습니다. 메서드 안에서 발생하는 상태 변경과 외부 작업을 모두 점검해야 합니다.
retryable()의 역할은 제한적입니다. 첫 호출이 전달되었는지 확인할 수 없을 때 실행을 다시 허용합니다. 런타임이 대응하는 오류의 종류를 바꾸거나 시도 횟수를 늘리지는 않습니다. 이 플래그는 함수에 적용됩니다. 메서드를 재정의하거나 감싼 버전은 별도로 표시하지 않으면 자동으로 플래그를 상속하지 않습니다.
기존 프로젝트에서 점검할 사항
가장 먼저 살펴볼 곳은 Durable Objects 호출을 감싸는 자체 재시도 루프입니다. 이제 각 시도에 런타임 재시도가 추가될 수 있으므로, 전체 요청 횟수가 애플리케이션 설정만으로 예상한 것보다 많아질 수 있습니다. Cloudflare는 재시도를 애플리케이션 코드가 관리한다면 자체 시도 횟수를 줄이거나 stub에 maxRetries: 0을 설정할 것을 권장합니다.
특정 stub의 제한은 get() 또는 getByName() 호출 시 설정합니다. maxRetries는 최초 시도 이후 재시도 횟수를 0회에서 10회까지 지정합니다. timeoutMs는 새 시도가 시작되지 않는 시점까지의 간격을 지정하며, 범위는 500~60,000밀리초입니다. 이 설정은 해당 stub을 통한 호출에 적용됩니다. retryable()과 retry 객체를 사용하려면 Wrangler 4.158.0 이상이 필요합니다.
유용한 점검 방법은 각 호출에 대해 세 가지 질문을 하는 것입니다. 상태가 두 번 이상 변경될 수 있는가? 외부 부수 효과가 반복되는가? 애플리케이션 자체 재시도 정책이 있는가? 그런 다음 해당 stub에 기본값을 적용할지, 별도의 제한을 둘지 결정하세요. 멱등적 메서드에는 명시적 표시를 사용할지 따로 검토할 수 있습니다. 그 밖의 메서드는 보호 장치를 유지하고, 첫 시도의 결과를 알 수 없을 때 오류를 처리하는 방식을 점검하세요.
결과: 책임의 경계가 메서드로 이동한다
자동 재시도는 네트워크 관련 로직 일부를 애플리케이션 코드에서 덜어내지만, 실행을 다시 허용할지는 여전히 작업의 속성입니다. 런타임은 전송을 안전하게 재시도한 뒤 호출이 실행되었는지 모르면 멈출 수 있습니다. 개발자는 상태 변경이나 부수 효과가 중복되지 않는다고 명시적으로 확인해 메서드 재실행을 허용할 수 있습니다.
따라서 이번 업데이트는 전송 계층과 핸들러 사이의 계약이 바뀌는 것으로 이해해야 합니다. 먼저 자체 재시도 루프와 부수 효과의 반복 가능성을 점검한 뒤, 필요한 stub의 제한을 설정하세요. 그러면 짧은 장애에 대한 내장 복원력을 활용하면서도 두 번째 실행의 비용이 큰 작업은 직접 통제할 수 있습니다.
