Documentation
¶
Overview ¶
Package finalize 收尾漏斗:一轮编排中止时「该落哪个终态 / 该不落终态」的 唯一收口——Cause→终态四分路由 + 多起点条件迁移 + detached 写纪律 + 零行回读补发「不谎报」(issue #167,移植自宿主 FinalizeTaskError 路由表 与 queue 的双起点收敛段)。
生命周期: Experimental(v0.38.0 定级)——本包仍会随首个宿主接入打磨 (报告文案 / needs_review / 排队结算等宿主回调的接缝形状),不承诺兼容; 定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
为什么是编排内核级 ¶
contract 已下发 Status 词表(created / running / waiting_approval / succeeded / failed / cancelled / timed_out)——**词表在内核,「怎么安全地 迁过去」的算法也该在内核**。路由决策(Cause→目标态)与并发裁决 (CAS 零行=他路已接手 / detached 写 / 0 行回读补发不谎报)不依赖任何 领域字段,是 contract 词表的消费算法,宿主无关性由 contract 的存在 本身证明。gorm/model 不下沉:条件迁移、回读现终态、发事件全走 Store 注入接口,本包只含路由与并发裁决算法。
三条并发纪律(包级不变量,不是调用方自觉) ¶
- **终态写必须走脱离 ctx**(Detached):编排 ctx 已取消时存储直查会 直接中止 ⇒ 终态写不进去、会话滞留 running 而事件谎报 succeeded。 Converge 内部一律派生脱离 ctx;宿主自己的收尾写同样要走 Detached。
- **条件迁移零行 = 他路已接手**:不再写任何状态(不覆盖他路的终态)。 零行处置二选一见 ZeroRow:静默(他路已发事件)或回读补发(不谎报)。
- **多起点收敛 + 0 行回读补发**:超时可能打在编排段(running),也可能 打在等待审批段(waiting_approval)——只认 running 起点的终态写零行 ⇒ 会话永不入终态。故 Spec.From 收全部起点、由存储一次原子条件迁移; 零行时回读库内现终态补发事件(Raced=true),**按库内事实报,不按 意图报**。
划界(与既有同域包互指、不重复) ¶
- vs contract:契约面(词表与接缝),不含算法——本包是它的消费算法。
- vs statemachine:纯谓词只回答「这次迁移合不合法」,不回答「该迁去哪」 ——本包是路由(该迁去哪)+ 并发写纪律。
- vs commitgate:环节(step)级并发终态**独占**提交闸(防两条分支都 提交);本包是会话级 **cause 路由**与多起点收敛(防「写不进去却谎报」)。
- vs checkpoint:崩溃续跑(定案不接);本包是运行期收尾,方向不交叉。
- vs drain:drain 只管停机臂的在途轮收敛且明写「不写终态」——「停机 不落终态」这条 case 的归属地正是本路由表(drain 收敛完 in-flight 后, 把「接下来落不落」交给本包)。
- vs steer:**接管臂(ErrSteered)的载荷与续跑语义在 steer**(摘要构建、 回 created、队列续跑、空队列失败收敛),本包只管路由到那一臂。 依赖方向 **finalize → steer**(消费 steer.ErrSteered),单向不许环; 两边包头互指:finalize 管「往哪收」,steer 管「怎么收与怎么续」。
留宿主的回调 ¶
报告文案、needs_review 标记、排队结算、事件载荷的组装留宿主:本包只给 Route(往哪收)+ Converge(怎么安全收)+ AdjudicateRetry(失败臂排队 裁决)。
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrSessionDeadline = errors.New("会话超过会话级时限")
ErrSessionDeadline 会话级墙钟超时的 Cause(WithTimeoutCause 携带): 收尾按 timed_out 终态强制收敛,且判定**必须先于停机分支**(停机不落 终态,而超时恰恰要落终态——次序反了该收敛的会话会被留给恢复循环)。
裸 deadline(未带本 Cause)归停机臂:宿主设置会话超时必须写 context.WithTimeoutCause(parent, d, ErrSessionDeadline),否则超时会被 误判成停机、会话滞留 running。
var ErrUserCancelled = errors.New("会话被用户取消")
ErrUserCancelled 用户经取消 API 触发的取消 Cause(WithCancelCause 携带): 与进程停机的裸 ctx 取消**可区分**——取消落 cancelled 终态,停机不落终态 留给恢复循环。
Functions ¶
Types ¶
type Action ¶
type Action int
Action 路由结论(Route 的输出 = 该收去哪条臂)。
const ( // ActionFailed 其余臂:落 failed 终态 + 排队重试裁决(AdjudicateRetry)。 // 零值即此——「没有特殊 Cause」的缺省结局是失败。 ActionFailed Action = iota // ActionTakeover 接管臂:**不落终态回 created**——载荷(环节摘要、 // 回迁、队列续跑、空队列失败收敛)由 steer.Run 承接,本包只路由到这一臂。 ActionTakeover // ActionCancelled 用户取消:落 cancelled 终态。 ActionCancelled // ActionTimedOut 会话超时:落 timed_out 终态(**先于停机分支**判定)。 ActionTimedOut // ActionShutdown 进程停机:**不落终态**——running / waiting_approval // 留给恢复循环按搁浅语义收敛;也不写失败报告(写了就是谎报)。 ActionShutdown )
func Route ¶
Route Cause→终态四分路由(纯函数;移植自宿主 FinalizeTaskError 的路由表):
接管(不落终态回 created)/ 用户取消(cancelled 终态)/ 会话超时 (timed_out 终态,**先于**停机分支)/ 进程停机(不落终态留给恢复循环)/ 其余 failed。
判定走 errors.Is(可判包装链);Cause 由宿主经 WithCancelCause 注入 (可注入哨兵形态——contract 未下发 Cause 哨兵,故用户取消/超时的哨兵 在本包、接管哨兵在 steer,本包消费)。
接管臂只判 Cause 不判队列:「有排队条目才回 created、否则按失败收敛」 是 steer.Decide 的队列感知(归接管臂载荷,见包头划界)。
type Notice ¶
type Notice struct {
// Status 事件携带的状态:命中 = 目标态;补发 = 库内现状态。
Status string
// Raced true = 条件迁移零行、他路已接手后的补发。
Raced bool
// Extra 宿主附加载荷(error、诊断字段等)。
Extra map[string]any
}
Notice 收尾事件(宿主映射到自己的事件总线 / 通知面)。
type Outcome ¶
type Outcome struct {
// Status 终局状态:命中 = 目标态;零行回读 = 库内现状态;静默 = 空。
Status string
// Hit 条件迁移命中(false = 他路已接手)。
Hit bool
}
Outcome 收敛结果。
type RetryDecision ¶
type RetryDecision int
RetryDecision 失败臂裁决结论。
const ( // RetryAbandon 落 failed + 排队明示结算(不悬挂)——零值缺省。 RetryAbandon RetryDecision = iota // RetryRequeue 回 created 自动以排队输入重开一轮(条件迁移由宿主执行, // 零行回落到放弃——迁移零行 = 他路已接手,不得再开轮)。 RetryRequeue // RetryBudgetExhausted 预算尽:按预算收敛(报告与 needs_review 载荷 // 留宿主回调)。 RetryBudgetExhausted )
func AdjudicateRetry ¶
func AdjudicateRetry(f RetryFacts) RetryDecision
AdjudicateRetry 失败路径排队重试裁决:
RetryEnabled 且队列非空才进预算判定——预算未尽回 created 续跑、 预算尽按预算收敛;其余(缺省关 / 无排队)落 failed 并明示结算排队。
缺省关是保守取向:排队明示结算(queue_abandoned 事件)不悬挂, 坏场景不因自动续跑无限重跑。
type RetryFacts ¶
type RetryFacts struct {
// RetryEnabled 失败路径排队重试开关(缺省关 = 保守取向:排队明示结算,
// 不让坏场景无限重跑)。
RetryEnabled bool
// HasQueue 是否仍有排队条目。
HasQueue bool
// BudgetOK 排队预算未尽(续跑预算闸的判定结果,判据在宿主)。
BudgetOK bool
}
RetryFacts 失败臂裁决的注入事实(宿主给出,本包不读库)。
type Spec ¶
type Spec struct {
// From 起点状态全集(如 running、waiting_approval——双起点缺一即搁浅,
// 见包头纪律 ③)。
From []string
// To 目标态(contract 词表)。
To string
// Report 终报文本;空 = 不写(折叠 / 追加策略留宿主 SetReport)。
Report string
// ZeroRow 零行处置(缺省回读补发)。
ZeroRow ZeroRow
}
Spec 一次收敛的意图。
type Store ¶
type Store interface {
// Migrate 一次原子条件迁移:现状态 ∈ from 时迁移到 to;ok=false = 0 行。
//
// 多起点(from 多值)必须在**一次原子操作**里判(等价
// `UPDATE … WHERE status IN (from…)`):分多次逐点试会让两次尝试之间
// 落地的他路写入漏判,且多出的往返都在脱离 ctx 预算内。原子性由宿主
// 存储保证,本包只判结果。
Migrate(ctx context.Context, from []string, to string) (ok bool, err error)
// SetReport 覆写终报(折叠 / 追加策略留宿主;本包只传文本)。
SetReport(ctx context.Context, text string) error
// ReadStatus 回读库内现状态(零行补发「不谎报」的依据)。
ReadStatus(ctx context.Context) (string, error)
// Publish 发布收尾事件:Raced=true 表示条件迁移零行后的回读补发,
// 此时 Status 必须取库内现状态——按意图报目标态就是谎报。
Publish(ctx context.Context, n Notice)
}
Store 收尾存储面(宿主实现——gorm/model 不下沉)。
四个方法就是并发裁决算法的全部输入:条件迁移、报告覆写、回读现终态、 发事件——本包不碰任何存储客户端。