목차
Cloudflare Workflows의 step 곁에 둔 saga 롤백 (2026-06)
원문 정보
- 원문: How we built saga rollbacks for Cloudflare Workflows
- 매체 · 게시일: The Cloudflare Blog · 2026-06-25
- 저자: Vaishnav Kavitha, Mia Malden, André Venceslau
- 원문 내용을 바탕으로 재구성한 요약입니다.
출금 뒤에 멈춘 은행 간 송금
은행 간 송금 워크플로를 떠올려 보겠습니다. A 은행에서 출금하고, B 은행에 입금하고, 두 계좌 소유자에게 확인 메일을 보내는 흐름입니다. 여기서 B 은행 입금이 실패해도 A 은행의 출금은 이미 확정된 뒤입니다. 돈은 그 시스템을 떠났습니다.
송금을 조율하는 워크플로가 A 은행의 연산을 단순히 취소할 수는 없습니다. A 계좌에 다시 입금하는 새 연산을 실행해야 합니다. 처음 한 일을 의미상 반대로 돌리는 보상 로직을 원래 연산과 짝짓는 방식이 saga 패턴입니다.
Cloudflare Workflows는 step마다 외부 시스템을 호출하고, 실패를 재시도하며, 재시작 뒤에도 상태를 유지하는 다단계 애플리케이션용 서비스입니다. 이런 내구성이 있어도 중간에 실패하면 앞선 작업은 불완전한 상태로 남을 수 있습니다. 그동안 개발자는 step 정의 바깥에서 무엇이 성공했는지 추적하고, 실패 뒤의 보상 순서와 보상 중 오류 처리를 직접 작성해야 했습니다. saga 롤백은 그 보상 로직을 각 step 곁에 두고, 보상 실행에도 Workflows의 내구성을 적용합니다.
step.do()의 시작 시점을 지키는 옵션
Cloudflare가 선택한 API는 step.do(..., { rollback })입니다. 마지막 인자로 넘기는 옵션 객체에 보상 함수를 넣습니다. step은 이전과 같은 시점에 시작하고, 반환하는 Promise는 여전히 그 step의 출력을 나타냅니다. 기존 호출과 동시성 실행 모델을 유지하면서 보상 동작을 추가한 형태입니다.
처음 검토한 step.do(...).rollback(...)은 더 간결해 보였습니다. 순방향 작업과 보상이 나란히 놓이고, 익숙한 JavaScript 체이닝으로 읽힙니다. 하지만 Workers RPC에서 이런 문법은 다른 의미로 받아들여질 여지가 있었습니다.
Workers RPC는 Cap’n Proto 같은 시스템에서 이어받은 promise pipelining을 지원합니다. 호출자는 authenticate()의 결과가 돌아오기 전에 아직 도착하지 않은 세션에 whoami()를 요청할 수 있습니다. 원격 쪽에서는 인증으로 세션이 만들어지면 그 요청을 실행하므로 왕복 한 번을 아낍니다. 이 맥락에서 .rollback()을 붙이면 step의 반환값에 메서드를 호출하는 것처럼 보입니다. 보상 함수는 step이 시작되기 전에 등록해야 하는 옵션인데도 말입니다.
시작 시점도 문제였습니다. 지금은 first를 step.do()로 시작해 두고 second를 기다린 뒤 first를 await해도, 시작 순서는 first, second입니다. fluent API에서는 .rollback()이 붙는지 기다려야 전체 step 정의를 알 수 있습니다. 그러면 first가 await first에 이르러서야 시작돼, 이미 second가 끝난 뒤로 밀릴 수도 있었습니다. 병렬 실행의 순서가 step.do()를 호출한 위치보다 반환된 Promise를 소비하는 시점에 좌우되는 셈입니다.
step.saga("charge").do(...).rollback(...).run() 같은 builder도 검토했습니다. Promise의 의미를 흐리지 않고, 앞으로 추가할 step 옵션을 둘 자리도 분명했습니다. 대가는 호출마다 붙여야 하는 .run()이었습니다. 빠뜨리기 쉽고 도구 없이는 발견하기 어려운 데다, 단순한 작업 하나도 긴 설정 체인이 됩니다. 새 step.saga()는 기존 step.<action> 패턴을 벗어나고 step.do()를 이전 방식처럼 보이게 만들기도 했습니다.
팀은 문법을 조금 더 명시적으로 쓰더라도 기존 step.do()를 확장하는 쪽을 택했습니다. 보상은 그 step의 메타데이터로 남습니다. 개발자는 새 builder나 특별한 Promise 대신 옵션 객체 하나를 더 익히면 됩니다.
결과를 저장하기 전에 실패한 step
롤백은 워크플로 자체가 최종 실패하기 직전에 시작됩니다. step 하나가 오류를 냈더라도 사용자 코드가 이를 잡고 계속 실행하면 보상은 시작되지 않습니다. 그렇게 오류를 처리한 뒤 워크플로가 다른 이유로 실패할 때는, 앞서 등록한 핸들러도 여전히 롤백 대상이 될 수 있습니다.
대상은 롤백 핸들러를 등록하고 시작한 step입니다. 완료된 step에만 한정되지 않습니다. 결제 제공자가 이미 결제를 처리했는데 step이 chargeId를 Workflows에 반환하기 전에 실패하는 경우를 생각해 볼 수 있습니다. step의 실패가 외부 시스템에서 아무 일도 일어나지 않았다는 뜻은 아닙니다.
그래서 보상 함수는 output === undefined도 처리해야 합니다. 핸들러가 받는 output은 순방향 step이 저장한 반환값입니다. 값을 저장하기 전에 실패했다면 undefined이며, 정상적으로 저장한 반환값 자체가 undefined일 수도 있습니다.
핸들러는 step 시작 순서의 역순으로 실행됩니다. 재고 예약, 카드 결제, 배송 생성으로 이어지는 예에서는 배송 생성이 실패하면 카드를 환불하고 재고를 해제합니다. 순차 실행에서는 자연스러운 순서입니다. 병렬 실행에서는 먼저 시작한 step이 더 늦게 끝날 수 있으므로, Workflows는 완료 순서 대신 저장된 시작 순서를 기준으로 삼습니다. Promise.all()로 실행한 step도 이 규칙을 따릅니다.
보상 함수 역시 일반 step처럼 멱등이어야 합니다. 환불에는 결제 제공자의 멱등 키를 쓰고, 재고 해제는 여러 번 호출해도 안전하게 작성해야 합니다. 송금 예제에서도 출금·입금과 각각의 롤백에 멱등 키를 사용해 재시도가 이체를 중복시키지 않도록 했습니다.
재시작 뒤에 복원하는 롤백 핸들러
Workflows는 보상 함수의 본문을 데이터로 저장하지 않습니다. 영속적으로 남기는 것은 step의 실행 기록입니다. 기존에도 시작 여부, 완료 여부, 반환값, 재개할 때 다시 실행하지 않고 건너뛸지를 기록했으며, 롤백을 위해 보상 로직의 등록 여부를 더했습니다.
함수를 호출할 방법은 별도로 유지합니다. Workers RPC에서는 다른 곳에서 실행되는 코드를 호출할 수 있는 참조를 stub이라고 부릅니다. stub은 호출이나 실행 컨텍스트가 끝나면 폐기될 수 있습니다. 더 오래 보관하려면 같은 대상을 가리키는 새 핸들을 만드는 dup()을 사용합니다. 롤백은 핸들러를 등록한 step.do() 호출보다 나중에 실행될 수 있으므로 Workflows도 보상 단계까지 유지할 자체 참조를 갖습니다.
일반적인 경우에는 같은 엔진 수명 안에서 롤백이 시작됩니다. 필요한 stub이 이미 있으므로, 저장된 기록에서 대상 step을 찾고 그 stub을 호출하면 됩니다. 엔진이 퇴출되거나 충돌하거나 재시작한 경우에는 사정이 달라집니다. 실행 기록은 남아 있어도 메모리의 stub은 사라졌을 수 있습니다.
이때 핸들러를 되찾는 방법이 replay입니다. 워크플로 코드를 다시 실행하되, 완료된 순방향 step의 본문은 반복하지 않는 복구 모드입니다. 완료된 step.do()를 만나면 저장된 결과를 읽고, 롤백 대상인 step의 옵션에서 호출 가능한 stub을 다시 등록합니다. 완료된 step의 외부 작업을 중복 실행하지 않고도 필요한 보상 함수를 복원하는 방식입니다.
Workflows는 저장된 기록으로 어떤 step이 시작됐고 끝났는지, 실패한 step 중 무엇이 보상 대상인지, 각 핸들러에 어떤 출력을 넘길지 판단합니다. 실행 순서도 같은 기록에서 얻습니다. 확보한 stub을 호출할 때는 롤백을 시작하게 한 원래 오류, step 컨텍스트, 저장된 출력을 함께 넘깁니다.
직접 작성한 catch 블록은 JavaScript의 해당 실행 지점에 메모리로 남아 있는 정보에 의존합니다. Workflows의 롤백은 영속적인 step 기록으로 이미 일어난 일을 판단하고, 메모리에서 잃어버린 호출 참조는 replay로 복구합니다. 보상 로직을 내구성 있는 작업 단위인 step.do()에 붙인 이유도 여기에 있습니다.
보상 실패까지 남기는 실행 기록
롤백 핸들러도 일반 step과 같은 실행 체계를 거칩니다. 보상에 재시도와 타임아웃을 적용하고, 라이프사이클 이벤트와 로그, 최종 결과를 남깁니다. 일반 step의 재시도·타임아웃을 WorkflowStepConfig로 지정하듯 보상에는 rollbackConfig를 둡니다. 핸들러와 그 실행 설정을 한곳에서 관리하는 방식입니다.
보상에도 실패의 끝이 있습니다. 설정한 재시도 뒤에도 핸들러가 계속 실패하면 Workflows는 롤백 결과를 실패로 기록하고, 남은 핸들러의 실행을 중단합니다. 워크플로 인스턴스는 최종적으로 Errored 상태가 됩니다. 앞선 보상이 계속 실패한 상태에서 나머지 보상을 끝까지 실행하는 동작은 아닙니다.
워크플로의 원래 실패와 롤백 결과는 별개로 유지됩니다. 롤백은 워크플로가 실패한 뒤 수행하는 작업이며, 처음 실패한 원인을 대체하지 않습니다. 라이프사이클 이벤트에서는 보상이 시작됐는지, 어느 핸들러가 실패했는지, 롤백이 성공적으로 끝났는지를 확인할 수 있습니다.
순차 롤백으로 출발한 첫 버전
첫 버전은 step.do()별 롤백 핸들러와 순차 보상 실행, 보상용 재시도·타임아웃 설정을 제공합니다. 병렬로 시작한 step을 보상하더라도 롤백 핸들러의 실행 자체는 순차 방식입니다.
Cloudflare가 다음으로 탐색하려는 범위는 waitForEvent의 롤백 지원, 병렬 롤백 실행, Python Workflows의 롤백 지원입니다. 현재 제공하는 기능과는 구분되는 확장 후보입니다.
롤백 실행 규칙과 설정 예시
| 항목 | 값 |
|---|---|
| 롤백 실행 순서 | step 시작 순서의 역순(완료 순서 아님) |
| 롤백 시작 조건 | 워크플로가 최종 실패하기 직전 |
| 롤백 대상 | 시작·완료된 step 중 핸들러 보유, 핸들러를 등록한 실패 step |
| 핸들러가 받는 값 | 원인 오류, step 컨텍스트, output(undefined 가능) |
| 롤백 핸들러가 계속 실패할 때 | 결과를 실패로 기록, 남은 핸들러 중단, 인스턴스는 Errored |
rollbackConfig 예시 | retries limit 10, delay 30 seconds, backoff exponential, timeout 2 minutes |
| 첫 버전 포함 | step별 핸들러, 순차 실행, 재시도·타임아웃 설정 |
| 탐색 중 | waitForEvent 롤백, 병렬 롤백, Python Workflows |