음성 이중 과금 결함을 찾아낸 것은 사용량 로그가 아니라 독립 리뷰어의 HIGH 심각도 지적이었다. 이 파이프라인은 statements·branches·functions·lines 4개 지표 모두 100% 커버리지 게이트를 유지했는데도 그 결함을 통과시켰다. 외부 AI 프로바이더 호출에 재시도를 붙이면서 중복 과금이 걱정되는 백엔드 개발자라면, 통과한 테스트 수치보다 먼저 재호출을 허용할 근거와 이미 끝난 작업의 저장 경계를 살펴야 한다. 실제 이중 청구가 발생했다는 과금 기록은 없으며, 여기서 다루는 것은 리뷰 단계에서 발견된 코드 결함이다.

실패 응답을 받았다고 해서 외부 서버의 작업까지 실패했다고 단정할 수는 없다. 호출은 처리됐지만 응답을 받지 못했거나, 파일은 저장됐지만 그 파일을 가리키는 데이터베이스 행이 만들어지지 않은 상태를 구분해야 한다. 이 구분 없이 다시 호출하면 원래 실패에 중복 작업을 더할 수 있다.

이 글은 Cloudflare Workers 기반 AI 영상 생성 파이프라인의 작업 기록을 바탕으로 재시도 판정과 저장 순서, 버전 라우팅을 설명한다. 추론은 외부 프로바이더 SDK가 담당하며, 구현은 에이전트가 맡고 별도 모델이 독립 리뷰한 작업이다. 경쟁 상태·부분 실패·멱등성의 개념은 동시성 기초에서 이어 볼 수 있다. 여기서 데드레터큐(DLQ)는 신버전 바인딩이 없는 작업을 설정 오류로 종결시키는 경로를 뜻한다.

멱등성 계약이 없으면 재시도는 진행이 아니라 차단이다

재시도를 넣기 전에 먼저 확인할 것은 멱등성 계약이다. 멱등성(idempotency)은 같은 요청을 반복해도 결과가 중복 반영되지 않는 성질을 말한다. 외부 호출에서는 키 이름의 존재만으로 판단하지 말고, 중복 제거가 보장되는 조건을 재시도 정책에 반영해야 한다.

작업 기록에는 프로바이더와 모달리티를 묶은 16개 조합의 재시도·복구 정책 매트릭스가 남아 있다. 모달리티는 텍스트·이미지·음성·영상 같은 데이터 유형을 뜻한다. 당시 판정은 작동하는 멱등성 키를 문서화한 프로바이더가 없다는 것이었고, 안전한 자동 재시도로 분류된 조합도 없었다. 특정 SDK의 멱등성 헤더가 사실상 무효였다는 결론도 기록돼 있지만, 같은 요청을 두 번 보내 확인했다는 실행 절차는 남아 있지 않다.

따라서 이 결과는 당시 조사 대상과 정책 판정의 범위로 읽어야 한다. 모든 프로바이더의 현재 동작을 일반화하거나 각 조합을 실제 호출해 재현한 결과로 확대할 수는 없다. 독립 리뷰에서 매트릭스에 빠진 이미지 생성 조합이 발견돼 보완된 기록도 있다.

정책은 자동 재시도, 기존 작업 조회, 수동 복구를 구분하도록 정해졌다. 외부 작업 ID로 조회할 수 있는 비동기 영상 작업과 예측 작업은 새로 호출하지 않고 기존 작업을 조회하는 대상으로 분류됐다. 나머지 동기 호출은 성공 여부가 애매한 실패로 두고 자동 재시도를 막으며 수동 복구를 요구한다. 안전한 자동 재시도 후보가 없다는 결론은 이 매트릭스의 판정이며, 조회 복구의 성공 횟수를 뜻하지 않는다.

결과를 모르는 호출에는 재시도 권한을 먼저 주지 않는다. 조회할 수 있으면 기존 작업을 확인하고, 확인할 수 없으면 수동 복구 대상으로 남긴다.

호출 상황 판정 처리
작동하는 멱등성 키의 문서화된 계약을 확인할 수 없음 자동 재시도의 안전 근거 없음 키 이름만으로 자동 재시도를 허용하지 않음
동기 호출의 성공 여부가 불명확함 애매한 실패 자동 재시도 금지, 수동 복구
외부 작업 ID로 조회 가능한 비동기 작업 조회 가능 기존 작업의 상태 조회를 통한 복구 대상으로 분류
재시도·조회 가능 여부를 판정하지 못함 재시도 안전 후보로 인정하지 않음 fail-closed, 자동 재시도 차단

새 프로바이더를 검토할 때도 이 표의 질문을 사용할 수 있다. 멱등성 계약과 기존 작업 조회 수단을 확인하고, 확인되지 않은 호출은 자동 재시도 대상에서 제외하는 설계 원칙이다. 이 표를 먼저 작성하도록 도입 절차가 바뀌었다거나, 차단 뒤 사람에게 자동 알림이 전달됐다는 운영 기록은 없다.

R2가 성공해야 D1 행이 생긴다

저장 경계에서는 파일의 존재와 데이터베이스의 참조를 구분해야 한다. R2는 생성 파일을 저장하고, D1 자산 행은 그 파일을 가리킨다. 자산 행을 먼저 만들면 저장에 실패한 파일을 완료된 자산처럼 참조할 수 있다.

최종 렌더는 워커 메모리에 전체 버퍼로 올리지 않고 R2로 직접 스트리밍된다. R2 저장이 성공해야 비로소 D1 자산 행이 만들어지고 이 행이 저장된 파일을 가리킨다. R2 저장 뒤 D1 기록이 실패하면 참조되지 않는 고아 객체를 정리하고, 재시도에서는 결정론적 키를 다시 사용한다.
파일 저장 성공을 완료의 기준으로 삼고 그 뒤에 참조를 만들어야 실패한 파일을 완료된 자산처럼 가리키지 않는다.

작업 기록에 따르면 최종 렌더는 워커 메모리에 전체 버퍼로 적재하지 않고 R2로 직접 스트리밍하도록 바뀌었다. D1 자산 행은 R2 저장이 성공한 뒤에만 생성된다. 이 순서에서 완료의 기준은 파일 저장 성공이며, 스트리밍만으로 두 저장소의 상태가 함께 확정되는 것은 아니다.

R2 저장 뒤 D1 기록이 실패하는 반대 방향의 부분 실패도 처리 대상이다. 기록에는 이때 참조되지 않는 고아 객체를 정리하고, 재시도에는 결정론적 키를 재사용한다고 적혀 있다. 확인된 저장 순서는 R2 저장 성공 → D1 자산 행 생성까지이며, 삭제의 세부 동시성 조건은 이 기록만으로 설명할 수 없다.

결정론적 키는 같은 대상에 정해진 키를 다시 사용하는 방식이다. 이 파이프라인에서는 장면 영상과 최종 렌더에 적용되며, 모든 자산에 일괄 적용되는 규칙은 아니다. 장면 이미지는 재생성마다 다른 키를 사용한다. 최종 렌더 역시 키가 존재한다는 이유만으로 재사용하지 않고, 완료 상태와 유효한 메타데이터를 가진 비어 있지 않은 객체만 재사용하도록 돼 있다.

버전이 안 갈리면 폴백이 아니라 데드레터큐로 보낸다

구버전(V1)과 신버전(V2)을 함께 두는 설계에서는 재시도할 작업의 버전을 유지해야 한다. 매 실행 시점의 롤아웃 비율로 버전을 다시 고르면, 같은 작업이 처음과 다른 처리 규칙을 적용받을 수 있다. 이 파이프라인은 작업 생성 시 선택한 버전을 이후에도 유지하도록 구성됐다.

왼쪽은 실행 시점마다 롤아웃 비율로 버전을 다시 고르는 방식으로, 같은 작업이 처음과 다른 처리 규칙을 적용받을 수 있다. 오른쪽은 작업 생성 시 고른 버전을 인스턴스 ID 접두사로 남기고, 재시도와 큐 처리에서 그 접두사로 바인딩을 해석한다. V2 작업인데 V2 바인딩이 없으면 V1으로 폴백하지 않고 설정 오류로 DLQ에 보내 종결한다.
재시도 기준은 롤아웃 비율이 아니라 생성 시 인스턴스 ID에 남긴 버전이다.

워크플로 인스턴스 ID에는 선택된 버전을 나타내는 접두사가 붙는다. 이후 재시도와 큐 처리에서는 그 접두사로 해당 버전의 바인딩을 해석한다. 롤아웃 비율이 바뀌어도 이미 만들어진 작업은 다른 버전으로 다시 연결되지 않는다.

예외 처리도 선택된 버전을 기준으로 한다. V2 작업인데 V2 바인딩이 없으면 V1으로 폴백하지 않고 설정 오류로 DLQ에 라우팅해 종결한다. 이는 기록된 처리 규칙이며, 실제로 DLQ에 쌓인 건수나 그 뒤의 대응 결과는 기록돼 있지 않다.

R2 저장 성공 뒤의 D1 행 생성과 DLQ 종결 경로 위쪽 줄은 R2 저장이 성공한 다음에 D1 자산 행이 만들어지는 순서를, 아래쪽 줄은 V2 작업에 V2 바인딩이 없을 때 V1으로 폴백하지 않고 설정 오류로 DLQ에 보내는 경로를 흐르는 점선과 단계별 강조로 보여 준다. 저장 순서 R2 저장 성공 D1 자산 행 생성 버전 라우팅 V2 작업 V2 바인딩 없음 설정 오류로 DLQ V1으로 폴백하지 않음
저장 순서는 R2 성공이 먼저이고, 선택한 버전의 바인딩이 없으면 V1 폴백 대신 DLQ로 종결한다는 두 규칙을 한 장면으로 묶었다.

롤아웃 비율은 별도 설정 하나로 관리하고 기본값은 0이다. 신규 작업의 V2 선택은 이 비율과 바인딩 가용성에 따르며, 기존 작업은 저장된 버전을 유지한다. 비율을 올렸다가 되돌린 실행 기록은 없으므로 롤백의 속도나 편의성을 운영 성과로 평가할 수는 없다.

  • 작업 생성 시 선택한 버전이 인스턴스 ID에 남고, 재시도에서도 유지되는가.
  • V2 작업에 필요한 바인딩이 없으면 V1 폴백 대신 설정 오류로 DLQ에 보내는가.
  • 기본 롤아웃 비율 0과 기존 작업의 버전 유지 규칙을 구분하고 있는가.

단계 경계를 넘을 때는 await로 순서를 강제한다

작업 기록에는 진행 상황의 쓰기 순서 결함과 음성 재사용 결함이 각각 남아 있다. 두 결함이 함께 음성 이중 과금을 일으켰다는 인과는 기록돼 있지 않다. 진행 기록을 언제 확정하는지와 이미 합성한 결과를 어떻게 재사용하는지를 나누어 살펴야 한다.

진행 상황은 여러 변경을 모아 D1에 쓰는 플러시로 처리됐다. 그런데 단계 실행 결과를 await하지 않고 return하면서, finally의 플러시가 단계 완료보다 먼저 실행되는 버그가 있었다. 그 결과 마지막으로 모인 진행 기록이 유실됐고, 단계 완료를 기다린 뒤 플러시하도록 수정됐다. 에이전트가 작성한 초안 테스트가 이 버그를 항상 통과시키던 문제도 함께 발견돼 수정된 것으로 기록돼 있다.

음성 이중 과금 결함에는 장면별 재사용과 즉시 저장이 적용됐다. V2 워크플로는 준비·장면별 실행·결과 적용·마무리의 네 단계로 분리됐다. 이미 합성된 장면의 음성은 저장된 클립을 재사용하며, 결과 적용과 마무리 단계에서는 프로바이더를 다시 호출하지 않는다.

동시성 처리를 맡는 공통 함수의 에러 삼킴 버그도 함께 수정됐다. 수정된 동작은 실패가 생겨도 이미 시작한 작업들이 끝날 때까지 기다린 뒤 에러를 드러내는 것이다. 이는 승인된 음성 클립의 저장이 재시도 전에 끝나도록 하기 위한 경계다.

이 작업은 statements·branches·functions·lines 네 지표 모두 100% 커버리지 게이트를 유지했다. 그런데도 음성 이중 과금 결함은 독립 리뷰어의 HIGH 지적으로 발견됐다. 커버리지는 코드가 실행됐는지를 보여 주지만, 테스트가 잘못된 결과를 거부하는지까지 보장하지 않는다.

100% 커버리지와 불변식 검증은 같은 증거가 아니다. 테스트가 방어 조건의 실패를 실제로 구별하는지 별도로 확인해야 한다.

기록된 검증 구조는 구현 에이전트와 독립 리뷰어를 분리하고, 별도 컨트롤러가 핵심 불변식을 뮤테이션 테스트로 재검증하는 방식이었다. 뮤테이션 테스트는 코드를 일부러 바꾸어 방어 조건이 깨졌을 때 테스트가 실패하는지 확인하는 방법이다. 이 기록은 검증 방식의 근거이며, 이후 이중 과금이 발생하지 않았다는 운영 통계는 아니다.

최종 렌더 산출물 검증에는 미완료 경계가 남았다. 작업 당시 환경에 Docker가 없어 실제 MP4를 만들고 ffprobe로 확인하는 최종 렌더 승인 테스트는 실행되지 못했다. ffprobe는 미디어 파일의 스트림과 길이 정보를 읽는 도구다. 유닛 테스트 통과를 실제 렌더 파일의 검증 완료로 확대해서는 안 된다.

재시도 설계의 점검 기준은 세 가지로 정리할 수 있다. 멱등성 계약이 확인되지 않은 호출은 자동 재시도하지 않는다. D1 자산 행은 R2 저장 성공 뒤에 생성한다. 선택된 버전의 바인딩이 없으면 다른 버전으로 넘기지 않고 설정 오류로 처리한다.

이 기준은 재시도 정책과 저장 경계, 버전 선택을 리뷰할 때 사용할 수 있다. 실제 산출물 검증을 CI에서 반복할 수 있게 만드는 것도 후속 검토 항목으로 삼을 수 있다. 다만 기록으로 확인되는 미완료 항목은 Docker 기반 최종 렌더 승인 테스트이며, CI 이전이 완료됐다는 뜻은 아니다. 관련 프로그래밍 글에서도 구현 사실과 검증 범위를 구분해 읽는 것이 좋다.

자주 묻는 질문

문서에 idempotency key가 있으면 자동 재시도를 허용해도 되나요?

키 이름만으로는 부족하다. 중복 반영을 막는 계약과 적용 조건을 확인해야 한다. 이 파이프라인의 당시 기록에는 작동하는 멱등성 키를 문서화한 프로바이더가 없다고 남아 있으며, 안전한 자동 재시도 후보도 없었다.

R2 저장은 성공했지만 D1 기록이 실패하면 객체를 바로 지워도 되나요?

이 기록만으로 즉시 삭제가 안전하다고 판단할 수는 없다. 확인된 구현은 R2 저장 성공 후 D1 자산 행 생성, D1 실패 시 고아 객체 정리, 결정론적 키 재사용까지다. 삭제의 세부 동시성 조건은 기록돼 있지 않다.

V2 바인딩이 없을 때 V1으로 폴백하면 왜 안 되나요?

V2로 선택된 작업을 V1으로 보내면 작업 생성 시 정한 버전이 유지되지 않는다. 이 파이프라인은 인스턴스 ID의 버전 접두사로 경로를 고정하며, V2 바인딩이 없으면 설정 오류로 DLQ에 라우팅해 종결한다.