handoff

package
v0.46.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

contention.go —— 领取的并发正确性**判据**(判据,不是测试风格)。

与 taskboard.ConcurrentClaim 同一形态:让 N 个接收方在同一个起跑线上 同时 Take 同一单,赢家必须恰好 1 个。判据长在包里,宿主的存储实现 被它跑一遍就算验过契约。

desk.go —— 语义面的**可持久化实现**:Desk 只依赖 Ledger,不持有进程内状态。

两个 Desk 共用一个 Ledger 就是「两个进程客户端」的形状:Offer / Take / Reply / Cancel 全部走「Load → 判 → Save(条件写)」,并发冲突靠 Revision 重试而不是进程内互斥。LocalDesk 是 Desk + MemoryLedger 的薄包装,行为与 旧版逐条一致(默认路径零回归)。

构造器按部署形态分流(issue #270):NewDesk 是单机/测试语义(允许进程 本地时钟回退);NewDistributedDesk 要求 Ledger 实现 ClockedLedger,缺 存储时钟即装配期失败——跨副本判定不得用「本进程以为的现在」。

Package handoff 跨进程任务交接的**契约面**:交接点在哪、交接是否原子、 幂等键是什么、回执回到谁手里、交接超时怎么办。

生命周期: Experimental(v0.35.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。

它补的是哪一段(issue #110)

@@delegate@@ 回答「能不能交给别的运行时」,@@taskboard@@ 回答「同一张 板子上的认领」——但两者的认领/负责关系都**局限在同一个存储里**。跨进程 交接(进程 A 的一步工作移交给进程 B 续做)此前没有任何机制面:交接点 在哪、交接是否原子、幂等键是什么、回执回到谁手里、交接超时怎么办, 各宿主自己拿一个队列或一张表兜着,于是「双方都以为对方负责」与 「谁都不负责」这两种错在报告里读起来完全正常。

本仓给什么、不给什么

与 taskboard 的分工同构:**给**契约(Ticket / Receipt / Store)与判据 (Validate / Check / ConcurrentTake,纯函数);**不给**跨进程存储实现—— 表结构、事务边界、持久化形态是宿主资产(进程内参考实现见 local.go, 它只证契约可满足,不做跨进程承诺)。

交接的四问(每问一条契约条款)

  1. **交接点在哪**:交接点是 @@Store@@——它持有交接单,交接单(@@Ticket@@) 携带幂等键、双方身份、载荷、回执地址与时限。交接单是数据不是消息: 「交接」不是把任务推过一条管道,而是把**负责人字段**改写一次。
  2. **交接是否原子**:负责人从 From 变为 To 发生在 @@Take@@ 成功的那一次 原子操作里(由存储实现保证,本包判结果——@@ConcurrentTake@@)。此前 From 负责(可 @@Cancel@@ 收回),此后 To 负责(可 @@Reply@@ 交回执), 不存在「双方都以为自己在负责」的中间态。
  3. **幂等键是什么**:@@Ticket.Key@@ 由调用方按业务给(本包只做集合判定, 不造键)。同一 Key 的重复 @@Offer@@ 是**重放**(返回原单,不开新单) ——与 sideeffect 的 apply-once 同一条纪律;超时/收回后的重新交接是 **新一代**(@@Generation@@ 同 Key 严格递增,与 taskboard 的 Fence 同源——迟到者的动作凭代次与令牌拒收)。
  4. **回执回到谁手里**:@@Ticket.ReplyTo@@ 在挂出时**必填**——回执送到 「源方显式声明的地址」,不假设「谁交的回给谁」(跨进程时源方可能 崩溃重启,重启后的身份不一定还是交接时的身份)。领取只允许 To 本人 (@@ErrNotAddressee@@),回执凭存储铸造的令牌提交(@@ErrLeaseLost@@ ——凭令牌认人,不凭内容,commitgate / taskboard 的同源教训)。
  5. **交接超时怎么办**:@@Ticket.TTL@@ 是**一条时限线**,覆盖领取与回执 两段(截止时刻由存储按**自己的**时钟推算——跨进程不假设时钟一致)。 到点未领取或已领取未回执,单落 @@StateExpired@@:迟到的领取与回执 一律拒收(fail-closed),源方重新交接即新一代。**无时限的交接单 是契约禁止的**(Validate 拒绝 TTL<=0)——没有截止时刻的跨进程交接 只会留下一把谁都不敢动的锁。

与既有纪律的对齐(同一条纪律,不另造一套)

  • 原子性判结果不判过程:@@ConcurrentTake@@ 跑一遍,赢家必须恰好 1 个 (taskboard.ConcurrentClaim 的同源判据);
  • 令牌由存储铸造、动作凭令牌不凭内容(taskboard 的 v0.33.0 教训);
  • 回执状态三值 completed / failed / refused,completed 类结论必填、不得带 失败原因(与 delegate.Status 同一份词表:ReceiptStatus 是它的类型别名, issue #358);
  • 重新交接 = 新一代(generation 单调,sideeffect.Fence 的同源口径)。

judge.go —— 交接契约的**判据面**:自洽性判定与快照不变量(纯函数)。

判据长在包里而不是只在测试里(taskboard.Check 的同一理由):宿主的存储 实现随时可以拿当前快照跑一遍 @@Check@@,「这一单自不自洽」不必等人肉 review 发现。

ledger.go —— 交接单的**持久化 Store 面**(Save / Load / Delete)。

内存参考实现在 memory.go;语义实现在 desk.go。

为什么要把「语义」与「持久化」分成两层

语义的 @@Store@@(Offer / Take / Reply / Cancel / Snapshot)回答「交接怎么走」; 本文件的 @@Ledger@@ 回答「记录落在哪」。两者分开的理由与 taskboard 的分工 同构:跨进程落库形态是宿主资产(表结构、事务边界、时钟域),内核不能替它 选;但交接的原子性、幂等键、回执寻址与代次又必须只有一份判据。故本包给

  • Ledger:**持久化契约**——Save 的条件写、Load、Delete 与回执索引;
  • MemoryLedger:进程内参考实现,只证契约可满足,不对跨进程做承诺;
  • @@Desk@@:**语义实现**,只依赖 Ledger——两个 Desk 共用一个 Ledger 就是两个进程客户端的形状(用例以此模拟跨实例交接)。

Ownership Epoch:代次防 ABA

每个 Key 有一条**所有权代次水位**(Record.Epoch)。它在同一 Key 上严格递增, 且**跨终态与 Delete 都不复用**:Delete 只删当前记录,水位留在 Ledger 里。 于是「删掉重来」不会让一个旧代持有者重新变成合法持有者(ABA),迟到的 Save / TakeAt / Reply 凭代次或令牌被拒。

代次是**存储侧铸造**的:Record.Epoch 为零值的 Save 由 Ledger 取 「水位 + 1」;调用方自带的更大代次不被接受(否则客户端可以把代次跳到 未来,让后面所有合法代次都变成「旧代」)。

Receipt addressing:回执按地址留存

回执送达的是 Ticket.ReplyTo 声明的地址,不是「谁交的回给谁」。Ledger 在 Save 一条已收口记录时把回执按地址索引下来(Receipts(addr)),记录被 Delete 后回执仍在——源方崩溃重启后仍能按自己的地址取回执。

条件写(CAS)与并发

Record.Revision 是记录版本,由 Ledger 铸造。更新一条**已存在**记录时, 调用方必须带回 Load 时看到的 Revision;版本不一致 ⇒ @@ErrConflict@@ (并发写者已经改过,调用方重新 Load 后再判一次)。这不是可「盲重试」的 错误:Desk 必须重读并重新执行语义判定(例如输家要在新状态下读到 accepted 才能返回 @@ErrTaken@@,而不是把一切冲突都当输家)。

local.go —— 进程内交接台:Desk + MemoryLedger 的薄包装。

边界与 desk.go 的注释同源:LocalDesk 只证契约可满足,对跨进程不做承诺。 需要跨实例/持久化形态时用 NewDesk(ledger):两个 Desk 共用一个 Ledger 就是两个客户端的形状;真实落库由宿主实现 Ledger(接口见 ledger.go)。

默认行为与旧版逐条一致(现有用例是判据):重放、终态开新代、懒式过期、 回执凭令牌、收回只归源方、快照按 Key 升序。

memory.go —— Ledger 的进程内参考实现(从 ledger.go 拆出:结构阈值按判据 的一侧切——契约面与参考实现分开,各自可读)。

Index

Constants

View Source
const (
	// ReceiptCompleted 交接的工作已完成(= delegate.StatusCompleted,"completed")。
	ReceiptCompleted = delegate.StatusCompleted
	// ReceiptDone 历史名称;值已统一为 completed,与 ReceiptCompleted 是同一个常量。
	//
	// Deprecated: 请改用 ReceiptCompleted(名称与词表取值一致,避免误读)。
	ReceiptDone = ReceiptCompleted
	// ReceiptFailed 交接的工作失败(接收方做过尝试)。
	ReceiptFailed = delegate.StatusFailed
	// ReceiptRefused 拒绝接收(接收方没有尝试)。
	ReceiptRefused = delegate.StatusRefused
)
View Source
const (
	CodeEmptyKey        = "empty_key"
	CodeDuplicateKey    = "duplicate_key"
	CodeUnknownState    = "unknown_state"
	CodeNoDeadline      = "no_deadline"
	CodeHolderMismatch  = "holder_mismatch"
	CodeMissingFence    = "missing_generation"
	CodeReceiptUntimely = "receipt_without_close"
	CodeOverdueHolder   = "overdue_holder"
	CodeOverdueReply    = "overdue_reply"
	CodeTTLNonPositive  = "ttl_non_positive"
)

不变量类别(Problem.Code,机器可判)。

Variables

View Source
var (
	// ErrUnknownKey 交接单不存在。
	ErrUnknownKey = errors.New("handoff: 交接单不存在")
	// ErrTaken 已被领取(Cancel 时撞上,或并发 Take 的输家)。
	ErrTaken = errors.New("handoff: 交接单已被领取")
	// ErrExpired 交接单已超时限(迟到的领取与回执一律拒收)。
	ErrExpired = errors.New("handoff: 交接单已超时限")
	// ErrNotAddressee 领取者不是指定接收方(回执寻址的领取半边)。
	ErrNotAddressee = errors.New("handoff: 领取者不是指定接收方")
	// ErrNotSource 收回者不是源方。
	ErrNotSource = errors.New("handoff: 收回者不是交接发起方")
	// ErrLeaseLost 领取令牌不匹配(回执凭令牌认人,不凭内容)。
	ErrLeaseLost = errors.New("handoff: 领取令牌不匹配")
	// ErrAlreadySettled 交接单已是终态。
	ErrAlreadySettled = errors.New("handoff: 交接单已是终态")
	// ErrUnknownState 交接单状态不在内核词表内(读不懂 ⇒ 写路径拒绝)。
	//
	// 与 Check 的 CodeUnknownState 同一事实、同一方向:体检说「这状态非法」,
	// 领取 / 回执 / 收回 / 落库也必须拒绝——否则一条脏状态行会让写路径照常
	// 铸造令牌、改写状态,事后无法区分「本来就是词表外状态」与「正常领取」。
	ErrUnknownState = errors.New("handoff: 交接单状态不在词表内")
)

错误哨兵(宿主实现必须复用,不要各造一套:判定方按 errors.Is 认人)。

View Source
var (
	// ErrConflict 记录已被并发写者修改(Revision 不匹配)。
	//
	// 处置是**重新 Load 并按最新状态重新判定**,不是盲目重试同一次写入——
	// 并发 Take 的输家必须在最新状态下读到 accepted 才能返回 ErrTaken。
	ErrConflict = errors.New("handoff: 交接单已被并发修改(重新读取后再判)")
	// ErrStaleEpoch 所有权代次陈旧:旧代不得覆盖/领取新代。
	//
	// 它是防 ABA 的判据:Delete 之后重新挂出必须开更大的代次;迟到的旧代
	// 写入与旧代领取一律用本哨兵拒收。
	ErrStaleEpoch = errors.New("handoff: 所有权代次已陈旧(旧代不得覆盖新代)")
)

持久化面的错误哨兵。

View Source
var ErrNoStoreClock = errors.New("handoff: 分布式交接台需要存储时钟(Ledger 必须实现 ClockedLedger)")

ErrNoStoreClock 分布式交接台缺存储时钟(Ledger 未实现 ClockedLedger)。

装配期错误而不是运行期失真:缺存储时钟时 Desk 只能退回进程本地时间, 多副本的截止/过期判定各按各的钟走——先过期的一方回收、后过期的一方 还在执行。fail-closed 在构造点(issue #270)。

Functions

func ConcurrentTake

func ConcurrentTake(ctx context.Context, s Store, key Key, tos []Agent, ttl time.Duration) (int, error)

ConcurrentTake 让多个接收方同时领取同一交接单,返回成功者数量。

判定(与 taskboard.ConcurrentClaim 同源):

  • 成功者必须**恰好 1 个**(0 = 谁都领不了;>1 = 存储没做到原子转移);
  • 输家的错误必须是 ErrTaken(不能是 ErrExpired / ErrNotAddressee 之类 ——那说明这些领取者压根没走到争用那一步,这次判定没测到想测的东西);
  • 任何**其它**错误都是基础设施故障,显式报出——把「数据库连不上」算成 输家,判据会在存储坏掉时变绿(测到的是「没人赢」而不是「只有一个 赢家」)。

ttl 用于给判定留一个整体时限(避免存储实现挂死拖垮调用方)。

Types

type AddressedReceipt added in v0.39.0

type AddressedReceipt struct {
	// Key 交接单的幂等键。
	Key Key
	// Generation 回执所属代次(= 收口时刻的 Ownership Epoch)。
	Generation uint64
	// Address 回执地址(Ticket.ReplyTo 的原样值)。
	Address string
	// From 交接发起方。
	From Agent
	// To 实际领取方。
	To Agent
	// Receipt 回执内容。
	Receipt Receipt
	// ClosedAt 收口时刻(存储时钟口径)。
	ClosedAt time.Time
}

AddressedReceipt 一条已投递到回执地址的回执。

地址取 Ticket.ReplyTo 的**原样值**:本包不解析地址,只按相等索引。

type Agent

type Agent string

Agent 交接一方的进程/执行体标识。

type ClockedLedger added in v0.39.0

type ClockedLedger interface {
	Ledger
	Now(ctx context.Context) (time.Time, error)
}

ClockedLedger 可选能力:持久化实现能报**自己的**当前时刻。

截止时刻与过期判定必须按存储的时钟推算(跨进程不假设时钟一致)——Desk 在装配到这种 Ledger 上时读它;没有该能力时退回 Desk 的注入时钟(单进程 参考实现即满足,跨进程宿主应实现它)。

type Desk added in v0.39.0

type Desk struct {
	// contains filtered or unexported fields
}

Desk 交接台:语义 Store 的持久化实现(每个方法经 Ledger 的条件写完成)。

零值不可用,请用 NewDesk。Desk 自身无共享可变状态,可并发使用; 多个 Desk 实例共用一个 Ledger 即模拟多个进程客户端。

func NewDesk added in v0.39.0

func NewDesk(ledger Ledger, opts ...DeskOption) *Desk

NewDesk 构造持久化交接台,语义是**单机/本地**:Ledger 未实现 ClockedLedger 时回退到进程本地时钟(time.Now 或 WithClock)。

这个回退只在单进程内成立。跨进程/跨副本部署必须用 NewDistributedDesk: 它要求存储时钟(ClockedLedger),缺失即装配期失败——两个副本的时钟偏差 会直接变成「谁以为交接过期了」的差异(issue #270)。ledger 为 nil 时 各方法显式报错,不静默成功。

func NewDistributedDesk added in v0.43.0

func NewDistributedDesk(ledger Ledger, opts ...DeskOption) (*Desk, error)

NewDistributedDesk 构造跨进程/跨副本交接台:**强制要求** Ledger 实现 ClockedLedger(存储侧时钟)。缺失 ⇒ 构造失败,不留到运行期用进程本地 时钟静默失真。WithClock 仍可用于确定性测试(同时转写 MemoryLedger 的 存储时钟),但它不能替代 ClockedLedger 这条装配判据。

func (*Desk) Cancel added in v0.39.0

func (d *Desk) Cancel(ctx context.Context, key Key, by Agent) error

Cancel 源方收回(仅 StateOffered;语义见 Store.Cancel)。

func (*Desk) Deliveries added in v0.39.0

func (d *Desk) Deliveries(ctx context.Context, addr string) ([]AddressedReceipt, error)

Deliveries 取回发往 addr 的回执(回执寻址的取件半边)。

addr 是挂出时写的 Ticket.ReplyTo 原样值;不解析、不做前缀匹配。回执在 交接单被 Delete 后仍然留存(源方崩溃重启后仍能取回)。

func (*Desk) Offer added in v0.39.0

func (d *Desk) Offer(ctx context.Context, t Ticket) (Ticket, error)

Offer 挂出交接单(原子 + 幂等;语义见 Store.Offer)。

同一 Key 未终态 ⇒ 原样返回(重放);终态 ⇒ 开新一代(代次由 Ledger 铸, 跨 Delete 不复用);否则首代。Deadline 按存储时钟从 TTL 推算。

func (*Desk) Reply added in v0.39.0

func (d *Desk) Reply(ctx context.Context, key Key, token string, r Receipt) error

Reply 交回执(凭领取令牌;迟到与令牌不匹配都拒收;语义见 Store.Reply)。

func (*Desk) Snapshot added in v0.39.0

func (d *Desk) Snapshot(ctx context.Context) ([]Ticket, error)

Snapshot 当前代的全部交接单(按 Key 升序,确定性;语义见 Store.Snapshot)。

func (*Desk) Take added in v0.39.0

func (d *Desk) Take(ctx context.Context, key Key, to Agent) (Handle, error)

Take 领取交接单(语义见 Store.Take)。

func (*Desk) TakeAt added in v0.39.0

func (d *Desk) TakeAt(ctx context.Context, key Key, to Agent, expected Epoch) (Handle, error)

TakeAt 领取并校验所有权代次:expected 与当前记录不一致 ⇒ ErrStaleEpoch。

这是「Take 侧校验代次单调」的入口:一个拿着旧代交接单的客户端(源方 重交接之后、或 Delete 重建之后)不能凭旧代领取新一单的工作。 expected 为 0 一律拒绝——0 不是一次真实挂出的代次。

type DeskOption

type DeskOption func(*Desk)

DeskOption 交接台的装配项。

func WithClock

func WithClock(clock func() time.Time) DeskOption

WithClock 注入时钟(缺省读 Ledger 自己的时钟,见 ClockedLedger)。

注意:跨进程部署时**不要**用进程本地时钟代替存储时钟——截止时刻是 存储侧的事实。注入只用于确定性测试;生产路径应实现 ClockedLedger。

接缝契约(issue #369)

@seam: no-reentry no-blocking panic-caller

  • **不得重入**:回调内不得再次触发会读取本台时钟的判定路径(会递归); 只读回查是安全的(Desk 自身无锁,回调在判定路径上调)。
  • **不得阻塞**:回调在每次截止时刻推算前被调用,必须立即返回。
  • **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。

type Epoch added in v0.39.0

type Epoch uint64

Epoch 所有权代次(同一 Key 上严格递增;跨终态与删除不复用)。

它是防 ABA 的**单一真相**:@@Ticket.Generation@@ 是这个代次在交接单上的 投影,@Handle.Fence@ 是它在领取凭证上的投影——不是第二个计数器。

type Handle

type Handle struct {
	// Token 存储铸造的领取令牌(回执的唯一凭据)。
	Token string
	// Fence 接管代次:与 Token 同一次原子操作铸造,等于领取时刻的
	// Ticket.Generation。
	Fence uint64
	// Until 责任期截止(= 交接单的 Deadline)。
	Until time.Time
}

Handle 一次领取的凭证(与 taskboard.Lease 同形:令牌 + 代次 + 截止)。

type Key

type Key string

Key 交接单的幂等键(宿主按业务给;同一键的重复挂出是重放不是新单)。

type Ledger added in v0.39.0

type Ledger interface {
	// Save 写入一条记录并返回**存储定型后**的记录(代次 / 版本 / 令牌可能被铸造)。
	//
	// 形态一:新建(无当前记录)。Record.Epoch 必须为 0(由 Ledger 铸
	// 「水位 + 1」),Revision 必须为 0,Ticket.State 必须是 offered。
	//
	// 形态二:同代更新。Record.Epoch 等于当前记录的 Epoch,Record.Revision
	// 等于当前记录的 Revision;不匹配 ⇒ ErrConflict(并发写者已改)。
	//
	// 形态三:终态之上开新代。Record.Epoch 等于当前 Epoch + 1,Revision 为 0,
	// 当前记录必须是终态,新单必须是 offered。
	//
	// 其余形态(旧代、跨代跳跃、对非终态开新代、Revision 不匹配)分别报
	// ErrStaleEpoch / ErrConflict,**都不得写入**。Ticket.State 不在词表内
	// (offered / accepted / closed / expired / withdrawn)⇒ ErrUnknownState,
	// 不得落库(与写路径同向,issue #359)。
	Save(ctx context.Context, rec Record) (Record, error)
	// Load 读取当前记录;无记录返回 ErrUnknownKey。
	Load(ctx context.Context, key Key) (Record, error)
	// Delete 删除当前记录(保留代次与版本水位,防 ABA)。
	//
	// 这是保留/清理入口,不是交接动作:删除不会让旧代重新合法。
	Delete(ctx context.Context, key Key) error
	// List 返回全部当前记录的一致快照(顺序不要求,Desk 会排序)。
	List(ctx context.Context) ([]Record, error)
	// Receipts 返回发往 addr 的全部回执(按 Key、代次升序,确定性)。
	Receipts(ctx context.Context, addr string) ([]AddressedReceipt, error)
	// Epoch 返回该 Key 的当前代次水位(从未出现过的 Key 返回 0)。
	//
	// 它让调用方在记录被 Delete 之后仍能知道「下一代从几开始」;
	// 新建记录时传 Epoch=0 也可让 Ledger 自行铸造。
	Epoch(ctx context.Context, key Key) (Epoch, error)
}

Ledger 交接单的持久化 Store 面。

实现方必须保证:

  • @@Save@@ 是**一次原子操作**:版本比对、代次水位推进、令牌铸造与 回执索引不可分割(拆开就有「两位写者各写一半」的窗口);
  • @@Save@@ 只接受「同代更新」或「终态之上开新代」两种形态,旧代一律 @@ErrStaleEpoch@@(不以「看起来更小」为由静默接受);
  • @@Save@@ 拒绝**词表外状态**(@@ErrUnknownState@@):落库面是最后一道 防线,内核读不懂的记录不得入库(issue #359);
  • @@Load@@ 无记录返回 @@ErrUnknownKey@@,不得返回 (零值, nil);
  • @@Delete@@ 只删当前记录,**保留代次与版本水位**(否则 ABA 封不住);
  • @@Receipts@@ 只返回发给该地址的回执(回执寻址的取件半边)。

type LedgerOption added in v0.39.0

type LedgerOption func(*MemoryLedger)

LedgerOption MemoryLedger 的装配项。

func WithLedgerClock added in v0.39.0

func WithLedgerClock(clock func() time.Time) LedgerOption

WithLedgerClock 注入 Ledger 自己的时钟(存储侧时钟语义见 ClockedLedger)。

注入的回调**不会在持有 MemoryLedger 内部锁时被调用**(issue #317):回调里 重入本包的 Load/Epoch/List 等接口不会与不可重入的互斥锁相撞。

接缝契约(issue #369)

@seam: no-reentry no-blocking panic-caller

  • **不得重入**:回调内不得再次触发会读取本账本时钟的写路径(会递归); 只读回查是安全的(时钟在 m.mu 之外被调用)。
  • **不得阻塞**:回调在每次截止时刻推算前被调用,必须立即返回。
  • **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。

type LocalDesk

type LocalDesk struct {
	// contains filtered or unexported fields
}

LocalDesk 进程内交接台(Store 的进程内参考实现)。

func NewLocalDesk

func NewLocalDesk(opts ...DeskOption) *LocalDesk

NewLocalDesk 构造进程内交接台(缺省行为:进程内互斥 + time.Now)。

func (*LocalDesk) Cancel

func (d *LocalDesk) Cancel(ctx context.Context, key Key, by Agent) error

Cancel 源方收回(仅 StateOffered;凭身份不凭内容)。

func (*LocalDesk) Deliveries added in v0.39.0

func (d *LocalDesk) Deliveries(ctx context.Context, addr string) ([]AddressedReceipt, error)

Deliveries 取回发往 addr 的回执(回执寻址的取件半边)。

func (*LocalDesk) Offer

func (d *LocalDesk) Offer(ctx context.Context, t Ticket) (Ticket, error)

Offer 挂出交接单(原子 + 幂等)。

func (*LocalDesk) Reply

func (d *LocalDesk) Reply(ctx context.Context, key Key, token string, r Receipt) error

Reply 交回执(凭领取令牌;迟到与令牌不匹配都拒收)。

func (*LocalDesk) Snapshot

func (d *LocalDesk) Snapshot(ctx context.Context) ([]Ticket, error)

Snapshot 当前代的全部交接单(按 Key 升序,确定性)。

func (*LocalDesk) Take

func (d *LocalDesk) Take(ctx context.Context, key Key, to Agent) (Handle, error)

Take 领取交接单:负责人在一次条件写里完成转移。

func (*LocalDesk) TakeAt added in v0.39.0

func (d *LocalDesk) TakeAt(ctx context.Context, key Key, to Agent, expected Epoch) (Handle, error)

TakeAt 领取并校验所有权代次(旧代 → ErrStaleEpoch)。

type MemoryLedger added in v0.39.0

type MemoryLedger struct {
	// contains filtered or unexported fields
}

MemoryLedger Ledger 的进程内参考实现。

边界与 LocalDesk 的注释同源:它证明契约**可满足**,不承诺跨进程原子性。 跨进程落库形态由宿主实现(表结构、事务与时钟域归宿主;参考 examples/pgstore 对 taskboard / sideeffect 的分工)。

func NewMemoryLedger added in v0.39.0

func NewMemoryLedger(opts ...LedgerOption) *MemoryLedger

NewMemoryLedger 构造内存参考实现。

func (*MemoryLedger) Delete added in v0.39.0

func (m *MemoryLedger) Delete(_ context.Context, key Key) error

Delete 删除当前记录(代次与版本水位保留)。

func (*MemoryLedger) Epoch added in v0.39.0

func (m *MemoryLedger) Epoch(_ context.Context, key Key) (Epoch, error)

Epoch 返回代次水位(未知 Key → 0)。

func (*MemoryLedger) List added in v0.39.0

func (m *MemoryLedger) List(_ context.Context) ([]Record, error)

List 全部当前记录(按 Key 升序,确定性)。

func (*MemoryLedger) Load added in v0.39.0

func (m *MemoryLedger) Load(_ context.Context, key Key) (Record, error)

Load 读当前记录(无记录 → ErrUnknownKey)。

func (*MemoryLedger) Now added in v0.39.0

Now 存储侧当前时刻(ClockedLedger 的实现;Desk 用它推算截止时刻与过期)。

为什么先取回调、解锁后再调(issue #317)

clock 是宿主注入的装配接缝,回调里重入本包是自然写法;持锁调用它意味着 宿主只要在回调里读一次记录就会永久死锁(不是错误返回,没有超时兜底)。 锁只保护「取哪个回调」(UseClock 可并发替换),**调用**发生在锁外。

func (*MemoryLedger) Receipts added in v0.39.0

func (m *MemoryLedger) Receipts(_ context.Context, addr string) ([]AddressedReceipt, error)

Receipts 按地址取回执(按 Key、代次升序)。

func (*MemoryLedger) Save added in v0.39.0

func (m *MemoryLedger) Save(_ context.Context, rec Record) (Record, error)

Save 条件写入(语义见 Ledger.Save 的三形态)。

func (*MemoryLedger) UseClock added in v0.39.0

func (m *MemoryLedger) UseClock(clock func() time.Time)

UseClock 注入时钟(与 LocalDesk 的 WithClock 同一形态:过期场景可确定性测)。

接缝契约(issue #369)

@seam: no-reentry no-blocking panic-caller

  • **不得重入**:回调内不得再次触发会读取本账本时钟的写路径(会递归); 只读回查是安全的(时钟在 m.mu 之外被调用)。
  • **不得阻塞**:回调在每次截止时刻推算前被调用,必须立即返回。
  • **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。

type Problem

type Problem struct {
	// Key 相关交接单(空 = 不针对单条)。
	Key Key
	// Code 机器可判的类别。
	Code string
	// Text 人读的说明。
	Text string
}

Problem 一条快照不变量违反。

func Check

func Check(tickets []Ticket, now time.Time) []Problem

Check 判一份快照的**不变量**,按 (Key, Code) 排序返回(确定性)。

now 由调用方注入:过期判定必须能被确定性测(boardtest.FakeClock 的同一 理由——靠 time.Now 的判定只能靠 sleep 测)。

本函数判**状态自身是否自相矛盾**,不判策略对错:

  • 键唯一、状态在词表内;
  • Deadline 必须有值(无界交接是契约禁止的),TTL 必须为正;
  • 状态与负责人/代次必须同进退:accepted 必有 Holder 与代次; 非 accepted 不得残留 Holder;
  • closed 必有结算时刻;未收口不得带结算时刻;
  • 过期判定(懒式):now 已过 Deadline 的 offered 单本应被标 Expired、 已过 Deadline 的 accepted 单本应被对账——发现残留即报 (实现方可以懒式落库,但快照要让「逾期没人管」显形)。

type Receipt

type Receipt struct {
	// Status 状态。
	Status ReceiptStatus
	// Summary 一句话结论(completed 时必填)。
	Summary string
	// Failure 失败/拒绝原因(failed 与 refused 时必填)。
	Failure string
	// Artifacts 产出物引用(路径或标识,原样携带)。
	Artifacts []string
}

Receipt 一次交接的回执。

func (Receipt) Validate

func (r Receipt) Validate() error

Validate 判回执是否自洽(与 delegate.Receipt.Validate 同一条纪律)。

  • 状态在词表内(词表单源在 delegate.Status,issue #358);
  • completed 必须有 Summary,且**不得**带 Failure(带了说明双方对「完成」 的理解不一致,而源方会按「完成」处理);
  • failed / refused 必须有 Failure(没有原因就无法决定重交接还是改方案)。

type ReceiptStatus

type ReceiptStatus = delegate.Status

ReceiptStatus 回执状态(三值,issue #358)。

与 delegate.Status 是**同一个类型**(别名,不是第二份定义):回执的 「完成 / 做过尝试的失败 / 没尝试的拒绝」三值语义只有一份词表,合法值集合 与 delegate 逐条相等。历史取值 done 已统一为 completed——宿主跨包聚合 (委托回执 + 交接回执)时两列值域不再不同而语义相同。

type Record added in v0.39.0

type Record struct {
	// Ticket 当前代的交接单。
	Ticket Ticket
	// Epoch 所有权代次(持久化真相;Ticket.Generation 是它的投影)。
	Epoch Epoch
	// Revision 记录版本(CAS;由 Ledger 铸造,调用方不自行递增)。
	Revision uint64
	// Token 领取令牌(accepted 时由 Ledger 铸造;非 accepted 必须为空)。
	Token string
	// Receipt 本次收口的回执(closed 时有值;Ledger 按 Address 索引留存)。
	Receipt *AddressedReceipt
}

Record 一条交接单的持久记录。

这是 Ledger 的存储单元,不是语义面:宿主实现 Ledger 时照它落库/序列化; 语义面仍只看 @@Ticket@@ / @@Receipt@@。

type State

type State string

State 交接单状态。

const (
	// StateOffered 已挂出、待领取:负责人仍是 From。
	StateOffered State = "offered"
	// StateAccepted 已交接:负责人是 To(领取的那一次原子操作完成转移)。
	StateAccepted State = "accepted"
	// StateClosed 已收口:回执已结算(结论在 Receipt.Status)。
	StateClosed State = "closed"
	// StateExpired 超时:到点未领取,或已领取未回执(一条时限线的两种落点)。
	StateExpired State = "expired"
	// StateWithdrawn 源方收回(终态;重新交接 = 新一代)。
	StateWithdrawn State = "withdrawn"
)

func (State) Terminal

func (s State) Terminal() bool

Terminal 报告该状态是否终态。

expired 与 withdrawn 都是终态但**不封闭 Key**:重新交接开新一代。 closed 也是终态——同一个业务动作做第二次是新的幂等键的事。

func (State) Valid added in v0.43.0

func (s State) Valid() bool

Valid 报告状态是否在词表内。

为什么必须导出(issue #359)

体检面(Check)对词表外状态报 CodeUnknownState,但写路径此前只判 `== StateAccepted` 与 Terminal()——未知状态两条都不命中,于是被当作 「待领取」,Take 照常铸造令牌并把状态改写成 accepted。内核在一条自己 读不懂的记录上发放了执行权。

判据必须能被写路径(Take / Reply / Cancel)与落库面(Ledger.Save)直接 消费;私有谓词逼实现靠 Terminal() 反推,而 Terminal() 对未知状态返回 false(不能把「读不懂」说成「终态」),反推必然漏。

type Store

type Store interface {
	// Offer 挂出交接单。
	//
	// 同一 Key 已有未终态单 ⇒ 原样返回该单(重放,Generation 不变);
	// 已终态 ⇒ 开新一代(Generation 递增)。Deadline 由存储按自己的
	// 时钟从 TTL 推算。不合法的交接单(Validate 不过)必须报错。
	Offer(ctx context.Context, t Ticket) (Ticket, error)
	// Take 领取交接单:负责人在这一次原子操作里从 From 变为 to。
	//
	// 非指定接收方(ErrNotAddressee)/ 已超时(ErrExpired)/ 已被领取或
	// 终态(ErrTaken / ErrAlreadySettled)/ 状态不在词表内(ErrUnknownState)
	// 必须报错——词表外一律不得铸造令牌、不得改写状态。令牌与代次由存储
	// 同一次原子操作铸造。
	Take(ctx context.Context, key Key, to Agent) (Handle, error)
	// Reply 交回执(凭领取令牌)。
	//
	// 令牌不匹配 → ErrLeaseLost;已超时 → ErrExpired(迟到回执被拒,
	// 责任期已过);状态不在词表内 → ErrUnknownState;回执不自洽 → 报错且
	// 状态不动。成功 ⇒ 单落 StateClosed。
	Reply(ctx context.Context, key Key, token string, r Receipt) error
	// Cancel 源方收回(仅 StateOffered)。
	//
	// 非 From(ErrNotSource)/ 已被领取(ErrTaken)/ 已终态
	// (ErrAlreadySettled)/ 状态不在词表内(ErrUnknownState)必须报错。
	// 成功 ⇒ 单落 StateWithdrawn。
	Cancel(ctx context.Context, key Key, by Agent) error
	// Snapshot 当前代的全部交接单(一致快照)。
	Snapshot(ctx context.Context) ([]Ticket, error)
}

Store 跨进程交接的存储中立契约。

实现形态有两类:进程内的 @@LocalDesk@@(参考实现)与基于 @@Ledger@@ 的 @@Desk@@(可持久化:两个 Desk 共用一个 Ledger 即两个客户端)。 持久化面的 Save/Load/Delete、条件写与代次水位见 ledger.go。

实现方必须保证(与 taskboard.Board 的实现义务同构):

  • @@Offer@@ **原子 + 幂等**:同一 Key 的判定与写入在一次操作里完成 (重放返回原单 / 终态开新一代,两个分支都必须在这一次操作里定型);
  • @@Take@@ **原子**:负责人转移不可分割(并发领取同一单只能有一个赢家);
  • @@Reply@@ / @@Cancel@@ **只认身份凭据**(令牌 / 源方身份),不匹配时报 哨兵,不静默成功;
  • @@Snapshot@@ 返回**一致快照**(不是边改边读的流)。

type Ticket

type Ticket struct {
	// Key 幂等键。
	Key Key
	// From 交接发起方(负责人在领取前是它;收回权也只在它手里)。
	From Agent
	// To 指定接收方(只有它能领取——回执寻址的领取半边)。
	To Agent
	// Payload 载荷(原样携带;语义由双方约定,本包不解释)。
	Payload []byte
	// ReplyTo 回执地址(必填):回执送到源方显式声明的地址,不假设
	// 「谁交的回给谁」。
	ReplyTo string
	// TTL 交接时限(必填,>0):领取与回执共用一条时限线。
	//
	// 给「多长」不给「到什么时候」:截止时刻归存储按**自己的**时钟推算
	// (跨进程不假设时钟一致——taskboard.ClaimRequest 的同源纪律)。
	TTL time.Duration
	// Generation 代次(同 Key 严格递增,由存储铸造)。重新交接 = 新一代;
	// 迟到者凭代次即可被判为旧持有者。
	//
	// 它是 @@Epoch@@(所有权代次)在交接单上的**投影**:Ledger 的
	// Record.Epoch 是持久化真相,跨终态与 Delete 都不复用(防 ABA);
	// 本字段只是把它带在交接单上,不是第二个计数器。
	Generation uint64
	// Deadline 截止时刻(存储按自己的时钟推算;零值 = 无界,契约禁止)。
	Deadline time.Time
	// State 当前状态。
	State State
	// Holder 当前负责人(仅 StateAccepted 时有值)。
	Holder Agent
	// ReceiptAt 回执结算时刻(仅 StateClosed 时有值)。
	ReceiptAt time.Time
}

Ticket 交接单(当前代)。

func (Ticket) Validate

func (t Ticket) Validate() error

Validate 判交接单是否自洽(不满足即报错,不静默补全)。

三条必填各有出处:

  • Key:没有幂等键的交接无法回答「做过没有」,重放语义无从谈起;
  • From / To / ReplyTo:回执寻址是契约硬面——没有回执地址的交接等于 寄丢;指定接收方让领取有判定对象(不是「谁先看到谁领」);
  • TTL > 0:交接必须有界(四问之四的契约化)——无时限的跨进程交接 只会留下一把谁都不敢动的锁。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL