ClaimMarker Pattern (PostgreSQL Idempotency)¶
概念概覽
ClaimMarker 核心語義¶
核心知識¶
ClaimMarker 核心語義¶
ClaimMarker 的正確實作順序：
1. INSERT INTO claim_markers ... ON CONFLICT DO NOTHING RETURNING id
2. 依據是否有回傳列（returned row）決定是否執行 grant
關鍵點：PostgreSQL 的 INSERT ... ON CONFLICT DO NOTHING 在衝突時會**阻塞**其他 transaction，直到原始 transaction commit 或 rollback，這提供了正確的並發保護語義。這不是「先查後寫」（TOCTOU 漏洞），而是原子性的「claim-first」flow。
適用條件¶
- 需要有外層 session-level guard（如 dungeon session lock）保護等待成本
- ClaimMarker 引入額外 DB write，但換取的是正確的並發語義（非 double-grant 保證）
AuditRepositorymock 必須更新以反映 claim-first flow，否則 unit test 驗不到正確行為
經驗教訓¶
-
PostgreSQL INSERT...ON CONFLICT DO NOTHING RETURNING 的阻塞語義是 ClaimMarker 能消除 TOCTOU 的根本原因，不是 application-level 的 check-then-act
-
ClaimMarker migration 後 distributor_test.go 的 AuditRepository mock 必須同步更新，否則測試驗證的是舊 flow
常見陷阱¶
-
誤用「先查後寫」（SELECT 檢查 + 條件 INSERT）無法解決 TOCTOU，兩個並發請求都可能通過 SELECT 檢查
-
只有 INSERT...ON CONFLICT DO NOTHING RETURNING 才有正確的 row-level blocking 語義
最佳實踐¶
-
ClaimMarker 必須搭配外層 session-level guard，降低 blocking 等待成本
-
Claim-first flow 的 unit test 必須驗證「有 RETURNING 列」與「無 RETURNING 列」兩條 code path
相關概念¶
- Activity Framework Settlement Idempotency
- Config Sync Advisory Lock Pattern
- 設計文件四塊同步原則
- Dungeon Reward Dual-Path Contract
- Hero Unlock Idempotency
- Immutable Settlement Contract
- MutationPlan Grant Pipeline Architecture
- PostgreSQL JSONB Hot Predicate Anti-pattern
- PostgreSQL Varchar Overflow Three-Layer Defense
- Reward Claims Architecture
- reward-pipeline-consolidation----dangling-------dangling---
- RPC Idempotency for Gacha / Random Pack Opening
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-22 | 4d2cd4bd-d412-452e-8787-2ed0d493c165 | 明確定義 ClaimMarker 的 PostgreSQL 並發語義：利用 row-level blocking 消除 TOCTOU race condition |