Documentation
¶
Overview ¶
board.go —— taskboard.Board 的 PostgreSQL 参考实现。
判据落库形态 ¶
- **认领是读-判-写不可分割**:一个事务里 SELECT … FOR UPDATE 锁任务行, 依次判(不存在 / 终态 / 依赖 / 被活持有),通过才写——两个进程同时认领 同一任务时,输家会在行锁上等到赢家提交,然后读到 claimed 状态 ⇒ ErrTaken。并发正确性由 taskboard.ConcurrentClaim 的共享套件判。
- **令牌与接管代次由存储铸造**:令牌用随机 128 位(跨进程不复用不重合, ABA 封死);代次 = 该任务已见最大值 + 1,与令牌同一次写落库(同源)。
- **释放 / 完成 / 续期只认令牌**:条件更新 WHERE token = $2,影响行数为 0 即 ErrLeaseLost(迟到持有者放不掉别人的闸)。
到期时刻由**存储自己的时钟**算(可注入):调用方的时钟与存储的时钟可能 对不上,跨进程时更不能假设一致。
cursor.go —— eventbus.Tailer 游标持久化(eventbus.CursorStore)的 PostgreSQL 参考实现(issue #264 的「崩溃点重启续读」)。
为什么需要它 ¶
eventbus.Tailer 的游标默认是 Run 的局部状态,停机即失;只有装配 CursorStore 才能从上次停点续随(eventbus.CursorStore 契约:Load 失败停摆、 Save 失败不停摆、未命中回退显式起点 / MaxID)。仓内此前只有测试替身 (eventbus 的 memCursorStore)满足这条接缝,生产宿主接 PostgreSQL 时没有 参考落点——本实现补上这一环。
语义 ¶
- 一行一个消费者(consumer key):同一键的游标只有一条,Load 未命中 = found=false(首次部署);读失败返回 error,Tailer 会停摆重试,绝不 静默回退 MaxID(回退即跳过停机窗口)。
- **游标单调不减**:SaveCursor 用 GREATEST 吸收回退写(陈旧副本的迟到 保存不会把游标拉回去);非法回退不报错、不落库。
- 保存是独立 UPSERT,不与事件发布同事务:游标不是业务状态,Tailer 在 投递之后保存——崩溃窗口只会造成重启后重读(订阅侧游标幂等吸收), 不会跳读。
- 同一 consumer key 只应由一个尾随者写(多副本各用各的键);同键并发写 的语义是「最后落库的最大值获胜」,不承诺无重复投递。
Package pgstore 副作用闸 / 任务认领面 / 进度快照 / 可靠事件面(Outbox 形态) 的 **PostgreSQL 参考实现**。
生命周期: Experimental(v0.33.0 定级)——参考实现,随契约套件与参考部署 演进,不承诺任何兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级 规则见 docs/api-compat.md。
它是什么、不是什么 ¶
这是 examples 里的**参考实现**,不是内核依赖:内核(sideeffect / taskboard / checkpoint)依旧只给契约与判据,不给存储。本包演示的是「把同样的判据落到 一个真实数据库的原子操作上」长什么样——宿主照抄它,比照着契约散文重写, 漂移的概率小一个量级。
它与 examples/reference-runtime(内存版参考实现)是一对:
- 内存版证明「判据本身是对的」(进程内互斥锁即可);
- 本包证明「判据在**跨进程**下依然成立」(判据归存储,不归进程)—— 用内核的共享契约套件(sidetest / boardtest / RunSinkContract)在 真实 PostgreSQL 上原样跑通,不为任何实现开后门。
三套契约各自的落库形态 ¶
- sideeffect.Store:Acquire 的「三判合一」(已完成 > 结果未知 > 执行中 > 资源被占 > 授予)在一个事务里完成——SELECT … FOR UPDATE 行锁把 「读状态 → 判 → 写」钉成跨进程原子;执行意图与授予(令牌 + 持有者身份, sideeffect.MintHolder 在同一事务里铸造)写在同一事务里。Complete / Renew / MarkUncertain / Abandon / Release 全部三项联查(令牌 + 持有者 + 资源一致),缺一即拒(ErrFenceStale / ErrNotHolder / ErrResourceMismatch)。
- sideeffect.FencedSink:一条带条件的 INSERT … ON CONFLICT DO UPDATE (WHERE seen_fence <= presented)先原子预占,写入体在同一事务里执行; 写入体报错 ⇒ 整个事务回滚 ⇒ 不得部分写。
- taskboard.Board:认领是一个事务里的读-判-写(行锁),令牌与接管代次 在同一次操作里铸造;释放 / 完成 / 续期只认令牌。
- checkpoint.StoreCAS:一条带条件的 upsert(WHERE 持久化序号 < 本次序号), 影响行数为 0 即判陈旧。
- eventbus 可靠事件面(Outbox 形态,issue #264):事件行与业务状态同 事务提交(PublishInTx——事件与业务写入同生共死),ID 由单行水位表 串行化铸造(铸造序 == 提交序,回滚不烧号 ⇒ 序列空洞结构性地不存在), 读侧以已提交水位线为上界(TailStore / WatermarkTailStore)。这是 eventbus.TailStore 契约点名的唯一被承诺支持的生产形态;自增直读 (BIGSERIAL + WHERE id > cursor)被该契约显式声明不支持。 尾随游标经 TailCursorStore(pgref_tail_cursor)持久化——实现 eventbus.CursorStore,崩溃/停机后从上次停点续读(#264)。
时钟 ¶
过期判定的时间源(v0.33.0 后修正):**缺省读数据库的 clock_timestamp** (事务内、取得行锁之后),经 UseClock 可注入(sidetest / boardtest 的 硬要求:注入值是系统时间的测试替身)。
为什么不再是进程本地的 time.Now:租约与执行意图是**跨节点共享的事实**, 各 worker 用自己的时钟写入/判定到期时刻时,±10s 的时钟漂移对 15s 的 TTL 意味着「A 写入的租约在 B 看来从一开始就是过期的」⇒ B 提前接管 A 仍在执行的资源。数据库只有一个时钟,判定读它,漂移就没有入口。 取时刻必须在**取得行锁之后**:CURRENT_TIMESTAMP 固定在事务开始时刻, 事务在锁上等了几秒的话,用它判过期会把等锁时长算进租约寿命。
数据库连接 ¶
构造函数直接收 *pgxpool.Pool 与 schema 名:本包不管理连接串与凭据, 那是宿主的接线责任。隔离方案是**每个实例一个 schema**(EnsureSchema 建 CREATE TABLE IF NOT EXISTS 一套表),契约套件每个子测试建一份全新实现 ——与「factory 每次构造全新实现」的套件约定对齐。
部署与验证入口 ¶
- 契约 + 故障恢复用例:GAK_PGREF_DSN=… go test ./examples/pgstore/… (见 examples/docker-compose.yml 与 Makefile 的 integration 目标);
- 冒烟部署:docker compose -f examples/docker-compose.yml up(pgsmoke 服务)。
effect.go —— sideeffect.Store 的 PostgreSQL 参考实现:类型、事务骨架与行读写。
三条判据在库里的落法(与内存版 effectStore 逐条对应) ¶
- **三项联查**:Complete / Release / Abandon / Renew / MarkUncertain 都在 同一个事务里校验「令牌仍是最新代 + 持有者身份一致 + 租约与动作的资源 一致」。校验与写入在同一事务 ⇒ 任何一步失败都发生在**任何状态被改之前** ——这正是 MarkUncertain「标记写失败必须保住执行意图」的落库形态。
- **执行意图**:Acquire 的授予(令牌 + 持有者身份)与意图登记写在 同一事务里;意图过期未裁决 ⇒ 同一 Key 转入未知态而非重新授予。
- **对账占用**:BeginReconcile 与裁决分表字段,占用过期可重入。
原子性来自哪里 ¶
每个方法 = 一个事务 = 若干条 `SELECT … FOR UPDATE` + 条件写。行锁把 「读状态 → 判 → 写」钉成跨进程原子:第二个进程在第一个提交前读到的 永远是旧状态,且会在行锁上等待。这与「一条带条件的 UPDATE」等价, 是契约点名认可的两种形态之一。
锁序恒为「资源行 → 动作行」:所有方法按同一顺序加锁,两个并发事务 不可能交叉持锁(交叉死锁在锁序一致时不存在)。
effect_acquire.go —— Acquire:三判合一的一个事务。
判定顺序是契约里最要紧的一行:**已完成 > 结果未知 > 执行中 > 资源被占 > 授予**。 顺序写反的代价是重复施加:把「结果未知」排到「资源被占」之后,调用方会拿到 contended(以为「晚点重试就行」),于是重试发生、重复施加随之发生。
为什么整段在一个事务里:三判合一的每一步都读同一份状态,行锁保证第二个 进程要么读到判定前的旧状态(然后在锁上等),要么读到判定后的新状态—— 不存在「两个进程同时读到没做过、资源空闲」的窗口。
effect_lease.go —— 凭据一族:Complete / Release / Abandon / Renew / MarkUncertain。
五个方法共用同一套纪律:
- 校验与写入在**同一个事务**里 ⇒ 校验失败即整体回滚,存储侧不剩半截状态;
- 资源行 → 动作行的固定锁序(见 effect.go);
- 三项联查不过即拒(ErrFenceStale / ErrNotHolder / ErrResourceMismatch), 拒绝时**不落任何一行**。
effect_reconcile.go —— 对账侧:ResolveUncertain 与 BeginReconcile。
裁决**不校验栅栏**(契约硬要求):它的依据是**下游事实**,不是持有权—— 原持有者可能已经死亡、租约早已过期,而对账恰恰要在这种情况下进行。 占用与裁决的关系:占用过期可重入(对账者死亡不永久占住);裁决成功即 清除占用(这次尝试已有结论)。
event.go —— eventbus 可靠事件面(Outbox 形态)的 PostgreSQL 参考实现。
形态声明(与 eventbus.TailStore 的契约文字一致,issue #264) ¶
eventbus 的尾随读侧契约把「无空洞推进」收口为:**被承诺支持的生产形态 只有 Outbox**。本实现就是那个形态的落库样板:
- **写侧(事件行与业务状态同事务)**:PublishInTx 在调用方事务内落 事件行;业务写入与它共用同一个事务——提交则同现,回滚则同灭。
- **分配串行化(水位行)**:ID 由单行水位表 pgref_event_watermark 铸造 ——UPDATE … RETURNING 拿号的同时持行锁到事务提交,下一个发布者在 锁上等待 ⇒ **铸造序 == 提交序**,乱序提交结构性地不存在(issue #264 实证的丢帧序列「小 ID 在途、大 ID 先提交」在此形态下无法发生)。
- **回滚不烧号**:拿号、插行、业务写入全在同一事务,回滚一并消失 ⇒ 序列空洞结构性地不存在(对比 BIGSERIAL:回滚烧号 ⇒ 永久空洞, 水位线读法将在那里永久停摆)。
- **读侧(已提交水位线读法)**:ListAfter 的返回段以水位线为上界 (id > cursor AND id ≤ 水位线)——水位线之上哪怕已可见也扣住不返 (fail-closed 方向是扣住,不是放行)。无空洞推进由机制保证,不靠 观测截断。
明确不支持:用 BIGSERIAL + WHERE id > cursor 直读实现本面——那是 eventbus.TailStore 契约点名的违约形态(哨兵响但帧已永久丢失;回滚烧号 造成永久停摆)。宿主接自己的自增表时,先读契约再决定,不要抄这个面 之外的捷径。
与 DurablePublisher 的分工 ¶
与业务状态无原子性要求的事件仍走 eventbus.DurablePublisher + 本实现的 Insert(独立事务形态,满足 eventbus.Store);要求「事件与业务状态同生 共死」的发布走 PublishInTx——宿主在自己的业务事务里调它,**提交之后** 再广播(广播在事务外,回滚后的幻影帧由此排除)。两入口落同一张表、同一 套水位线,读侧(Tailer)无差别。
串行化的代价(写明,不藏) ¶
全部事件发布在水位行锁上串行——与 DurablePublisher 持锁串行 Insert 同款 取舍(事件是人的可读留痕而非高频指标,不是高频指标的形态)。水位行锁持 有到事务提交:业务事务较长时把 PublishInTx 放在事务末段,别让「拿号」 挡住其他副本的发布。
schema.go —— 连接池构造与建表。
表结构与判据的对应关系(每张表管一件事,见 doc.go):
- pgref_effect_action Key 级状态(做过没有 / 结果未知 / 执行意图 / 对账占用)
- pgref_effect_resource 资源级状态(这个资源谁占着 / 发第几代令牌)
- pgref_downstream 下游资源(已见最大令牌 + 参考业务数据,FencedSink 的落点)
- pgref_board_task 任务认领面(taskboard.Board)
- pgref_snapshot 进度快照(checkpoint.StoreCAS)
- pgref_event_watermark 已提交水位线(单行;事件 ID 分配的串行化点,#264)
- pgref_event 事件行(与业务状态同事务提交的落点,#264)
- pgref_tail_cursor 尾随游标持久化(eventbus.CursorStore,#264 重启续读)
sink.go —— sideeffect.FencedSink 的 PostgreSQL 参考实现(下游栅栏适配)。
原子性要求(实现这条契约的唯一要点) ¶
「比较与写入必须在**同一次原子操作**里完成」——本实现把它落成两件事:
- **栅栏预占是一条带条件的 upsert**:INSERT … ON CONFLICT (resource) DO UPDATE SET seen_fence = EXCLUDED.seen_fence WHERE seen_fence <= presented。 影响行数为 0 ⇒ 令牌陈旧(ErrFenceStale),此刻**什么都没写**; 影响行数为 1 ⇒ 预占成功,且这行就是「比较 + 更新已见最大」本身。
- **写入体在同一事务里执行**:ctx 里带上了事务句柄(TxFromContext), 写入体的业务写入必须用 ExecWithin / QueryRowWithin 走这个事务。 写入体报错 ⇒ 整个事务回滚 ⇒ 预占与已写的业务数据一起消失—— **不得部分写**。
反面教材(为什么不能三步写) ¶
「先读已见最大 → 判断 → 再写入」三步各自独立提交时,两个持有者可以同时 读到同一个旧值、双双通过检查,然后先后写入——更旧的那次写入反而后落, 覆盖掉更新的。栅栏形同虚设。这条失败形态在 sideeffect 包内有确定性用例 (TestNonAtomicSinkIsCaught)与共享套件的并发场景双向钉住。
snapshot.go —— checkpoint.StoreCAS 的 PostgreSQL 参考实现。
契约只有两条,落库形态也是两条:
- SaveIfNewer:一条带条件的 upsert(WHERE 已持久化序号 < 本次序号), 影响行数为 0 ⇒ 判陈旧(ErrStaleSeq),**不写入**;Seq == 0 一律先拒 (它不是一次真实提交,放它落库等于给了它唯一能覆盖既有快照的写)。 并发提交同一 run 时,两个进程的条件更新在行锁上排队,只有序号更大的 那个落库——单调闸在存储侧成立,不在进程侧。
- Load:无记录返回 ErrNotFound(**不得**返回零值 + nil——那会被上游 误判成「这个运行从没跑过」从而全量重跑)。
Index ¶
- Variables
- func DropSchema(ctx context.Context, pool *pgxpool.Pool, schema string) error
- func EnsureSchema(ctx context.Context, pool *pgxpool.Pool, schema string) error
- func ExecWithin(ctx context.Context, sql string, args ...any) (int64, error)
- func NewSchema(ctx context.Context, pool *pgxpool.Pool) (string, error)
- func TxFromContext(ctx context.Context) (pgx.Tx, bool)
- func WithTx(ctx context.Context, tx pgx.Tx) context.Context
- type BoardStore
- func (b *BoardStore) Claim(ctx context.Context, id taskboard.TaskID, agent taskboard.AgentID, ...) (taskboard.Task, error)
- func (b *BoardStore) Complete(ctx context.Context, id taskboard.TaskID, token string) error
- func (b *BoardStore) List(ctx context.Context) ([]taskboard.Task, error)
- func (b *BoardStore) Release(ctx context.Context, id taskboard.TaskID, token string) error
- func (b *BoardStore) Renew(ctx context.Context, id taskboard.TaskID, token string, ...) (taskboard.Task, error)
- func (b *BoardStore) Seed(tasks ...taskboard.Task)
- func (b *BoardStore) UseClock(now func() time.Time)
- type Downstream
- func (d *Downstream) Marker(ctx context.Context, resource string) (string, error)
- func (d *Downstream) SeenFence(ctx context.Context, resource string) (sideeffect.Fence, error)
- func (d *Downstream) WriteFenced(ctx context.Context, resource string, presented sideeffect.Fence, ...) error
- func (d *Downstream) WriteMarker(ctx context.Context, resource string) error
- type EffectStore
- func (s *EffectStore) Abandon(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, _ string) error
- func (s *EffectStore) Acquire(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Outcome, sideeffect.Lease, sideeffect.Result, error)
- func (s *EffectStore) BeginReconcile(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Reconcile, error)
- func (s *EffectStore) Complete(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) (sideeffect.Result, error)
- func (s *EffectStore) MarkUncertain(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) error
- func (s *EffectStore) Release(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease) error
- func (s *EffectStore) Renew(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) (sideeffect.Lease, error)
- func (s *EffectStore) ResolveUncertain(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
- func (s *EffectStore) ResolveUncertainOwned(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution, ...) (sideeffect.Outcome, sideeffect.Result, error)
- func (s *EffectStore) UseClock(now func() time.Time)
- type EventStore
- func (s *EventStore) CommittedWatermark(ctx context.Context) (uint64, error)
- func (s *EventStore) Insert(ctx context.Context, ev eventbus.Event) (uint64, error)
- func (s *EventStore) ListAfter(ctx context.Context, cursor uint64, limit int) ([]eventbus.Event, error)
- func (s *EventStore) MaxID(ctx context.Context) (uint64, error)
- func (s *EventStore) PublishInTx(ctx context.Context, tx pgx.Tx, ev eventbus.Event) (uint64, error)
- type SnapStore
- type TailCursorStore
Constants ¶
This section is empty.
Variables ¶
var ErrIntentIncomplete = errors.New("pgstore: 执行意图列部分填充,拒绝判定")
ErrIntentIncomplete 动作行的执行意图四列**部分填充**(半写行)。
这是存储侧数据损坏 / 仓外写入方只写部分列的形态,不是本包写入路径能 产生的状态(本包只写「四列全有」或「四列全空」)。判定遇到它必须 **fail-closed**:逐列解引用会 panic(库层 panic 直接杀宿主进程), 按「无意图」放行会重新授予执行权(重复施加的入口重新打开)。
Functions ¶
func DropSchema ¶
DropSchema 删除一个 schema(含其中的表)。
func EnsureSchema ¶
EnsureSchema 在 schema 里建好全部参考表(幂等,可重复执行)。
schema 由调用方先建好(或用 NewSchema 一并创建);本函数只建表。 search_path 用 SET LOCAL 在本事务内指定——否则 DDL 落到调用方连接的 缺省 schema(public)里,读侧的 search_path 指到的却是一套空 schema。
func NewSchema ¶
NewSchema 建一个随机命名的 schema,返回名字。
契约套件的 factory 每个子测试调一次,构造一份**全新**实现——在共享的 数据库里,「全新」的落法是独立 schema:表状态互不可见,t.Cleanup 时整块删除。
func TxFromContext ¶
TxFromContext 返回写入体所在的事务句柄。
写入体**必须**通过它(或 ExecWithin / QueryRowWithin)执行业务写入—— 绕开事务自己开连接写入的数据不受栅栏保护,也无法在失败时一起回滚。
Types ¶
type BoardStore ¶
type BoardStore struct {
// contains filtered or unexported fields
}
BoardStore taskboard.Board(含 RenewingBoard)的 PostgreSQL 参考实现。
func (*BoardStore) Claim ¶
func (b *BoardStore) Claim(ctx context.Context, id taskboard.TaskID, agent taskboard.AgentID, req taskboard.ClaimRequest) (taskboard.Task, error)
Claim 认领一个任务(读-判-写不可分割:一个事务完成)。
func (*BoardStore) Renew ¶
func (b *BoardStore) Renew(ctx context.Context, id taskboard.TaskID, token string, req taskboard.ClaimRequest) (taskboard.Task, error)
Renew 续期并确认持有资格(taskboard.RenewingBoard)。
校验(令牌是当前租约的 + 租约未过期)与延长在**同一个事务**里——原子; TTL 语义与 Claim 一致;续期不换令牌、不递增代次(续期不是接管)。
func (*BoardStore) Seed ¶
func (b *BoardStore) Seed(tasks ...taskboard.Task)
Seed 摆初始任务(契约里没有「创建」入口:任务拓扑是宿主的资产)。
签名与套件要求的形态一致(boardtest 经 interface{ Seed(tasks ...Task) } 取用,没有 error 返回位)。落库失败时**panic**:这是装载入口,静默失败 会让套件在一张空表上跑出误导性的结论——摆不进去就当场响。
幂等:同 id 重摆覆盖内容并清租约(套件每个子测试从全新 schema 起步, 生产宿主通常只在装载拓扑时调用它)。
func (*BoardStore) UseClock ¶
func (b *BoardStore) UseClock(now func() time.Time)
UseClock 注入时钟(boardtest 契约套件用)。
type Downstream ¶
type Downstream struct {
// contains filtered or unexported fields
}
Downstream FencedSink 的 PostgreSQL 参考实现。
func NewDownstream ¶
func NewDownstream(pool *pgxpool.Pool) *Downstream
NewDownstream 构造下游栅栏(pool 归调用方管理)。
func (*Downstream) SeenFence ¶
func (d *Downstream) SeenFence(ctx context.Context, resource string) (sideeffect.Fence, error)
SeenFence 读资源已见过的最大令牌(无记录返回 0)。
func (*Downstream) WriteFenced ¶
func (d *Downstream) WriteFenced(ctx context.Context, resource string, presented sideeffect.Fence, write func(ctx context.Context) error) error
WriteFenced 在资源上执行一次带栅栏令牌的写入。
语义(契约逐条对应):
- presented 小于已见最大 → 不执行写入,返回 ErrFenceStale(此刻零写入);
- 否则执行写入体,并把已见最大更新为 presented(**等于**也放行—— 同一代持有者的多次写入合法,如分批提交);
- 第 1 条的判定与第 2 条的写入(含令牌更新)在同一个事务里。
func (*Downstream) WriteMarker ¶
func (d *Downstream) WriteMarker(ctx context.Context, resource string) error
WriteMarker 在写入体里写一个参考业务标记(值追加 'm')。
它是参考实现的「业务写入」占位:宿主的真实业务写入走同一条路 (ExecWithin,同一事务)。供共享套件判「不得部分写」。
type EffectStore ¶
type EffectStore struct {
// contains filtered or unexported fields
}
EffectStore sideeffect.Store 的 PostgreSQL 参考实现。
一个实例绑定一个 schema(全部表在其中);并发安全。
func NewEffectStore ¶
func NewEffectStore(pool *pgxpool.Pool) *EffectStore
NewEffectStore 构造副作用闸存储。pool 归调用方管理(Close 由它负责)。
schema 必须已建好表(EnsureSchema);search_path 已被连接池指到该 schema (见 NewEffectStores),故本包的 SQL 不写 schema 前缀。
func (*EffectStore) Abandon ¶
func (s *EffectStore) Abandon(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, _ string) error
Abandon 显式放弃本次尝试:撤销执行意图,并释放(仍是自己的)资源持有。
资源闸只在仍是自己的时才放——易主了就不碰(那是新持有者的闸)。
func (*EffectStore) Acquire ¶
func (s *EffectStore) Acquire(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Outcome, sideeffect.Lease, sideeffect.Result, error)
Acquire 一次原子判定(契约语义逐条对照 sideeffect.Store 的文档)。
授予时在同一事务里做三件事:令牌 = 资源已见最大值 + 1;持有者身份由 sideeffect.MintHolder() 在**同一事务**里铸造;执行意图(本次令牌 + 到期 时刻)随授予一并落库。三者分开写就等于没写:中间死掉 ⇒ 意图悬空或没写, 重复施加的入口重新打开。
func (*EffectStore) BeginReconcile ¶
func (s *EffectStore) BeginReconcile(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Reconcile, error)
BeginReconcile 认领对账权:同一 Key 同一时刻至多一个对账者。
仅当该 Key 处于未知态时接受认领;占用未过期时拒绝(ErrReconcileTaken); 占用过期可重新认领(可重入)——对账者死亡不永久占住这个 Key。
func (*EffectStore) Complete ¶
func (s *EffectStore) Complete(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, res sideeffect.Result) (sideeffect.Result, error)
Complete 标记该键的动作已完成并留存结果。**先到者为准**。
幂等:同一 Key 重复 Complete 不报错,返回首次记录的结果(后到者不覆盖)。
func (*EffectStore) MarkUncertain ¶
func (s *EffectStore) MarkUncertain(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, reason string) error
MarkUncertain 把该键标记为「结果未知」(按键,与资源租约无关)。
标记写失败必须保住执行意图(契约硬要求第 5 条) ¶
本实现「校验 → 改状态」在一个事务里完成:任何一步失败都发生在**任何状态 被改之前**,整体回滚 ⇒ 意图原样留在存储里,后续 Acquire 被意图挡住。 这不是实现自由:落到数据库上时,标记与撤销意图**不得**「先撤意图、再标 未知」分两步提交——第二步失败,存储侧就什么都不剩,另一个 worker 直接重放。
标记成功后意图一并撤销(这次尝试已有结论:未知),但**闸不自动释放** ——调用方还要显式调 Release 只放资源。
func (*EffectStore) Release ¶
func (s *EffectStore) Release(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease) error
Release 释放**资源持有**,**不动**该键的执行意图。
意图没被裁决之前,这个键不得再被执行——否则「施加成功但进程死在记账 之前」会被下一次 Acquire 变成重复施加。两条出口(Abandon / Release) 不可互相替代,见 Store.Release 的契约注释。
func (*EffectStore) Renew ¶
func (s *EffectStore) Renew(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ttl time.Duration) (sideeffect.Lease, error)
Renew 续期并**同时确认持有资格**:闸已易主、尝试已失效**或租约已过期** 则拒绝续期(假续期是重复施加的入口)。
func (*EffectStore) ResolveUncertain ¶
func (s *EffectStore) ResolveUncertain(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
ResolveUncertain 裁决「结果未知」的键。**先到者为准**(简化入口, 不校验对账凭据——短对账无须认领,见 OwnedResolveStore)。
RetrySafetyUnsafe 的动作:未生效的裁决不解除阻塞(ErrUnsafeNotRetryable), 必须 Resolution.ForceRetryable 的显式决策才放行——「不可重试」是判据, 不是注释。
func (*EffectStore) ResolveUncertainOwned ¶ added in v0.35.0
func (s *EffectStore) ResolveUncertainOwned(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution, holder string) (sideeffect.Outcome, sideeffect.Result, error)
ResolveUncertainOwned 带对账占用凭据的裁决(OwnedResolveStore): holder 不是**当前有效**对账认领的持有者 → ErrReconcileLost,不改状态。
校验与裁决同一事务:占用状态被并发接管时,行锁让校验读到的就是裁决 要落的那份状态——「校验时还有效、裁决前已被接管」的窗口不存在。
func (*EffectStore) UseClock ¶
func (s *EffectStore) UseClock(now func() time.Time)
UseClock 注入时钟(sidetest 契约套件用)。
过期判定必须读它,否则过期场景恒不触发(套件的硬要求)。 注入值代表**系统时间**的测试替身(整个判定链的唯一时间源),不是 「某个 worker 的本地时钟」——修复后的实现里 worker 根本不提供时间, 这正是「租约统一数据库时钟」要达成的状态。
type EventStore ¶ added in v0.42.0
type EventStore struct {
// contains filtered or unexported fields
}
EventStore eventbus 可靠事件面(Outbox 形态)的 PostgreSQL 参考实现: 写侧 PublishInTx / Insert(eventbus.Store),读侧 MaxID / ListAfter (eventbus.TailStore)与 CommittedWatermark(eventbus.WatermarkTailStore)。
一个实例绑定一个 schema(表由 EnsureSchema 建,水位行由建表语句种子化); 并发安全(发布在水位行锁上串行,见文件头「串行化的代价」)。
func NewEventStore ¶ added in v0.42.0
func NewEventStore(pool *pgxpool.Pool) *EventStore
NewEventStore 构造事件面存储。pool 归调用方管理(Close 由它负责)。
func (*EventStore) CommittedWatermark ¶ added in v0.42.0
func (s *EventStore) CommittedWatermark(ctx context.Context) (uint64, error)
CommittedWatermark 已提交水位线读法(eventbus.WatermarkTailStore,#264 的实现声明面):实现本方法 = 声明本存储是 Outbox 形态,可机判口径见 eventbus 包的接口文档。
func (*EventStore) Insert ¶ added in v0.42.0
Insert eventbus.Store 的独立事务形态(与业务状态无原子性要求的事件): 内部自开事务,失败整体回滚。DurablePublisher 可直接接本方法。
func (*EventStore) ListAfter ¶ added in v0.42.0
func (s *EventStore) ListAfter(ctx context.Context, cursor uint64, limit int) ([]eventbus.Event, error)
ListAfter 列出 id > cursor 的事件(eventbus.TailStore,升序,limit 为单拍 上限;limit 由 Tailer 保证为正——DefaultTailLimit / WithTailBatchLimit)。
返回段被已提交水位线封顶:水位线之上的行哪怕已提交可见(宿主绕过写入 协议落的行)也扣住不返,下一拍水位线推进后再读——fail-closed 方向是扣住 (#264 可机判口径第二条)。水位线机制保证 (cursor, 水位线] 内连续无洞: 水位线只在「对应事件行提交」的那笔事务里推进(同生共死),故对任何可见 快照,≤ 水位线的行全部已提交。读失败不得返回部分结果(契约第四条): 行扫描中途出错即整体作废。
func (*EventStore) MaxID ¶ added in v0.42.0
func (s *EventStore) MaxID(ctx context.Context) (uint64, error)
MaxID 当前权威游标空间的**无空洞边界**(eventbus.TailStore,空表 = 0)。
不回裸 max(id):水位线之上的行(宿主绕过写入协议落的行)不得把初始化 游标推过无空洞边界——否则初始化本身就把在途小 ID 跳过(#264)。Outbox 形态下无空洞边界就是已提交水位线(与 CommittedWatermark 同值同源)。
func (*EventStore) PublishInTx ¶ added in v0.42.0
PublishInTx 在调用方事务内发布一条事件(Outbox 形态的写侧入口,#264)。
事件行与调用方在同一事务里的业务写入**同生共死**:提交则同现、回滚则 同灭(水位线推进一并回退,ID 不烧号——下一次发布复用同一 ID)。返回的 权威游标 ID 供提交后的广播携带(提交之后再广播,广播在事务外)。
输入事件的 ev.ID 一律忽略(游标由水位行铸造);Level / Payload 的零值 归一与 DurablePublisher 同口径(见 normalizeEvent);OccurredAt 零值由 数据库时钟补齐(本包时间源纪律,见 doc.go「时钟」段)。
type SnapStore ¶
type SnapStore struct {
// contains filtered or unexported fields
}
SnapStore checkpoint.StoreCAS 的 PostgreSQL 参考实现。
func (*SnapStore) SaveIfNewer ¶
SaveIfNewer 仅当已持久化的序号**严格小于**本次序号时才写入。
type TailCursorStore ¶ added in v0.42.0
type TailCursorStore struct {
// contains filtered or unexported fields
}
TailCursorStore eventbus.CursorStore 的 PostgreSQL 实现:绑定一个 consumer key(如「副本名 / 消费组名」),游标落在 pgref_tail_cursor。
func NewTailCursorStore ¶ added in v0.42.0
func NewTailCursorStore(pool *pgxpool.Pool, consumer string) *TailCursorStore
NewTailCursorStore 构造游标存储。pool 不得为 nil,consumer 不得为空—— 两者都是装配期编程错误,fail fast 在构造点(与 eventbus.NewTailer 同口径)。
func (*TailCursorStore) LoadCursor ¶ added in v0.42.0
LoadCursor 读上次保存的游标(0, false, nil = 从未存过;error = 读失败, Tailer 会停摆重试,不得静默回退 MaxID)。
func (*TailCursorStore) SaveCursor ¶ added in v0.42.0
func (s *TailCursorStore) SaveCursor(ctx context.Context, cursor uint64) error
SaveCursor 保存游标(UPSERT;单调不减:回退写被 GREATEST 吸收,不落库)。
失败返回 error,调用方(Tailer)只 warn 不停摆——游标落后只会导致重启后 重读(订阅侧幂等吸收),方向安全。