--- kind: CONCEPT slug: fenced-lease title: fenced lease — 만료 시각만으로는 부족한 이유 topic: owner-safe-state-machines project: clean-architecture-backend-template status: 게시 전 sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916 basisVersion: PostgreSQL 16 · Flyway 11.14.1 · 리비전 21234e38 rootTreeNode: concept:fenced-lease evidenceCapturedOn: 2026-09-01 assets: - key: fenced-lease file: ../../../final/evidence/rendered/fenced-lease.svg evidence: - ../../../final/evidence/raw/fenced-lease.txt source: - 원본 분석 절은 final/document.md#4-1, #4-3 · final/document.md#a05 §10 · final/document.md#a19 §7.3 이다. --- # fenced lease — 만료 시각만으로는 부족한 이유 리스에 만료 시각만 기록하면 언제 끝나는지는 알아도 누가 들고 있는지는 모른다. 소유자와 증가하는 토큰을 함께 기록하면 만료된 작업자의 쓰기가 아무 행에도 맞지 않게 된다. ## 관계 - **lease가 만료 시각만 기록하고 소유자를 기록하지 않아 terminal state가 되돌려졌다** 이 개념이 필요해진 사례다. - **CAS 튜플을 where 절에 전부 반복하고 update count를 답으로 쓴다** 펜싱 토큰을 실제로 강제하는 방법이다. - **만료된 claim과 만료된 실행은 다르게 다뤄야 한다** 리스가 만료됐을 때의 처리를 갈라야 하는 이유다. ## 본문 lease가 "언제 끝나는가"만 기록하고 "누가 들고 있는가"를 기록하지 않으면 만료를 지난 worker가 여전히 쓸 수 있다. V2 마이그레이션 헤더가 그 시나리오를 3단계로 적는다 — relay A가 claim하고 브로커를 부름 / lease 만료, relay B가 재claim하고 발행하고 PUBLISHED 기록 / relay A가 타임아웃 후 그 위에 AMBIGUOUS를 씀. ## V2 헤더가 적은 3단계 시나리오 :::evidence key="fenced-lease" alt="분석 문서 final/document.md 에서 이 기록의 근거 절을 그대로 잘라낸 18줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="final/document.md 발췌 — 18줄" zoom="true" ::: ## lease를 늘리는 것이 해법이 아닌 이유 "**Making the lease longer than the publish timeout lowers the odds; it does not turn a GC pause, a scheduler stall**..." ## 해법과 그 반복 소유자와 fencing token을 행에 기록하고 terminal write가 그 튜플로 매칭하는 것이다. 같은 결함이 이 저장소에서 최소 세 곳(messaging outbox·fileserver cleanup·notification dispatcher)에 나타났다. :::note 없음 — 마이그레이션과 claim SQL을 코드로 확인했다 ::: ## 만료 시각만 있을 때 일어나는 일 메시징 outbox 의 V1 스키마는 리스 만료 시각만 기록했다. 릴레이의 최종 상태 쓰기는 메시지 식별자만으로 행을 찾았다. 마이그레이션 헤더가 그 결과를 순서대로 적는다. ```text relay A claims the row and calls the broker the lease expires; relay B reclaims it, publishes, and records PUBLISHED relay A finally times out and records AMBIGUOUS over the top ``` 세 줄이 끝나면 행은 다시 청구 가능한 상태가 되고 메시지는 두 번째로 발행된다. ## 리스를 늘리는 것은 해법이 아니다 ```text Making the lease longer than the publish timeout lowers the odds; it does not turn a GC pause, a scheduler stall or a slow broker into a data constraint. ``` 확률을 낮추는 것과 불변식을 만드는 것은 다르다. GC 정지나 스케줄러 지연이나 느린 브로커는 시간 여유로 없앨 수 있는 것이 아니다. ## 토큰이 하는 일 ```text A token does: every terminal write names the acquisition it belongs to, and a superseded worker's write matches nothing. ``` 모든 최종 쓰기가 자기가 속한 획득을 지목한다. 밀려난 작업자의 쓰기는 어떤 행에도 맞지 않는다. 실패가 아니라 갱신 건수 0 이 되고, 그것이 답이 된다. ## 스키마가 담는 것 ```sql ALTER TABLE messaging_outbox ADD COLUMN lease_owner VARCHAR(160), ADD COLUMN lease_token BIGINT NOT NULL DEFAULT 0, ADD COLUMN next_attempt_at TIMESTAMPTZ; ALTER TABLE messaging_outbox ADD CONSTRAINT ck_messaging_outbox_lease_token CHECK (lease_token >= 0); ``` 백필이 정확성에 필요하지 않다는 것도 헤더가 적는다. 기본값이 0 이고 첫 청구가 그것을 올린다. 제약은 코드가 의존하는 불변식을 문장으로 남기기 위한 것이다. ## 같은 마이그레이션이 함께 고친 것 ```sql -- EXHAUSTED is a new terminal state: the attempt budget ran out without any confirmation, which is -- not the same as the broker rejecting the message. V1's CHECK listed five states, so writing the -- sixth failed at the constraint rather than at review. ``` :::note 상태 목록을 CHECK 제약으로 닫아 두면, 새 상태를 추가하는 변경이 리뷰가 아니라 제약에서 실패한다. 그것이 의도된 동작이다 — 상태 어휘의 확장이 조용히 일어나지 않는다. ::: ## 같은 형태가 다른 곳에도 있다 파일서버 리프의 V3 마이그레이션이 같은 문제를 같은 방식으로 푼다. 리스 소유자와 펜스를 함께 기록한다.