document-haness/docs/clean-architecture-backend-template/tech-log-studio/owner-safe-state-machines/concept/concept-fenced-lease.md

kind, slug, title, topic, project, status, sourceRevision, basisVersion, rootTreeNode, evidenceCapturedOn, assets, evidence, source

kind	slug	title	topic	project	status	sourceRevision	basisVersion	rootTreeNode	evidenceCapturedOn	assets	evidence	source
CONCEPT	fenced-lease	fenced lease — 만료 시각만으로는 부족한 이유	owner-safe-state-machines	clean-architecture-backend-template	게시 전	21234e38cdb9a926cbc92bb97a2aee2e4a7d2916	PostgreSQL 16 · Flyway 11.14.1 · 리비전 21234e38	concept:fenced-lease	2026-09-01	key file fenced-lease ../../../final/evidence/rendered/fenced-lease.svg	../../../final/evidence/raw/fenced-lease.txt	원본 분석 절은 final/document.md#4-1,

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 스키마는 리스 만료 시각만 기록했다. 릴레이의 최종 상태 쓰기는 메시지 식별자만으로 행을 찾았다.

마이그레이션 헤더가 그 결과를 순서대로 적는다.

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

세 줄이 끝나면 행은 다시 청구 가능한 상태가 되고 메시지는 두 번째로 발행된다.

리스를 늘리는 것은 해법이 아니다

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 정지나 스케줄러 지연이나 느린 브로커는 시간 여유로 없앨 수 있는 것이 아니다.

토큰이 하는 일

A token does: every terminal write names the acquisition it belongs to, and a superseded worker's
write matches nothing.

모든 최종 쓰기가 자기가 속한 획득을 지목한다. 밀려난 작업자의 쓰기는 어떤 행에도 맞지 않는다. 실패가 아니라 갱신 건수 0 이 되고, 그것이 답이 된다.

스키마가 담는 것

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 이고 첫 청구가 그것을 올린다. 제약은 코드가 의존하는 불변식을 문장으로 남기기 위한 것이다.

같은 마이그레이션이 함께 고친 것

-- 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 마이그레이션이 같은 문제를 같은 방식으로 푼다. 리스 소유자와 펜스를 함께 기록한다.