worker

package
v0.46.1 Latest Latest
Warning

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

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

Documentation

Overview

execute.go —— 单个在途任务的执行与收场(串行路径与并发池共用)。

从 loop.go 拆出的理由与 lease.go 同款(结构阈值按判据的一侧切): 领取/心跳是「怎么找到活」,本文件是「一条活怎么跑完、怎么落库」。

heartbeat.go —— 注册心跳与在途租约续期(issue #179/#196/#266 共用的循环)。

两个心跳、互不阻断

注册心跳走独立节拍(HeartbeatInterval);任务租约续期按**每条任务自己的 到期时刻**调度,两者互不阻断:身份的可用性不是任务正确性的前置条件 (issue #179 的触发序列)。

续期调度(issue #266)

旧实现每拍逐条串行 Renew 全量在途任务:200 个任务 × 100ms 一轮 = 20s, TTL 15s 时后段任务在轮到它之前就已过期。现在:

  • **按到期时刻调度**:每条 claimed 有 nextRenew(本地时钟)= 上次成功 续期 + (TTL − RenewMargin)。心跳只续「到点」的任务,并用定时器等到 最近一个到期点;新增在途经 inflight.wake 立即重排;
  • **批量优先**:任务板实现 taskboard.BatchRenewingBoard 时,一次往返 续一批(每批至多 renewBatchLimit 条);
  • **有界并发**:没有批量面时按 RenewConcurrency 并发逐条续期,单条慢 不拖住同拍其它任务;
  • **单条超时**:每条/每批续期有独立的 RenewTimeout;超时只算该任务 一次失败,且与普通失败**分开计数**(renewTimeouts / renewFails);
  • 连续失败(含超时)达到 RenewFailMax ⇒ 停止领取并封口该任务 (ErrLeaseUnconfirmed 的既有语义)。

锁纪律(issue #326)

续期判定与计数在 claimed.mu 内(与本任务的收场互斥);所有宿主可见动作 ——OnLeaseLost 通知、取消在途 ctx、停止领取——都在锁外、由心跳协程顺序 执行。宿主回调回查本包不会二次抢锁死锁,回调 panic 也不会掀翻心跳。

panic 隔离(issue #368)

同一宿主接缝(任务板续期)的两条路径必须同口径:并发路径每条 async.GoSafe(逐条隔离),批量路径经 renewBatchCall recover + async.ReportPanic(整批隔离)。宿主 RenewBatch/Renew 的 panic 都不得 逃出心跳协程——逃出一次就是全部在途租约失保、他副本接管、非幂等 副作用双份。

计数住在 claimed 上、只由心跳协程(及其派生的续期 goroutine)在 mu 下 读写;在途集合本身由 inflight.mu 护住。

inflight.go —— 在途认领集合、续期判定与调度时刻(issue #196/#266/#326)。

从 loop.go 拆出(结构阈值按判据的一侧切):驱动生命周期(注册→领取→ 执行→排水→注销)与「一条认领怎么续期、怎么与收场互斥」是两段可读的 判据,分开后两边都能在单文件内看完。

lease.go —— 在途租约资格的**可观测面**(issue #179):三条失去资格的 路径各给一个可判别的信号,宿主据此计数/留痕/告警。从 loop.go 拆出 (结构阈值按判据的一侧切):驱动循环与它的租约事件词表分开,两边各自 可读。

为什么这三条不许静默

「闸已易主、本次结果作废」是事实不是成功路径。静默吞掉它们,下游的 非幂等副作用就可能双份——租约易主 ⇒ 旧执行体本该被封口,而它是否 真被封口、收场有没有被拒,宿主必须有信号可看(@@Config.OnLeaseLost@@)。

loop.go —— 六段生命周期的驱动:注册 → 领取 → 执行 → 心跳/续期 → 排水 → 注销。

驱动不吞失败

每一段的失败都有**明确的处置**,不静默吞:

  • 注册失败 → 直接返回(没身份就别开工);
  • 心跳失败(@@ErrNotRegistered@@)→ 身份没了:停止领取,收刀退出; **非身份类**心跳失败(存储抖动)→ 只影响身份本身,**不得吞掉同一拍 的任务租约续期**(issue #179:身份的可用性不是任务正确性的前置条件 ——两个故障域互不阻断);
  • 任务租约续期失败(@@taskboard.ErrLeaseLost@@)→ 资格没了:**取消在途 执行的 ctx**,本次任务按失败收场——资格检查失败后的继续执行就是 与新持有者重复施加(危险窗口在施加之前封口);
  • 任务租约续期**连续失败**跨过一个 TTL(@@ErrLeaseUnconfirmed@@)→ 无法确认持有资格:取消在途 ctx + 停止领取收刀——续不上又继续开工, 与新持有者重复施加的是同一种危险,只是这次连「谁在持」都答不出来;
  • handler 失败 → 任务 Release 回任务板(failed/open 都可被重做, 一次失败不把子任务钉死——taskboard 的状态语义);
  • 收场动作被 @@taskboard.ErrLeaseLost@@ 拒(任务已归新持有者)→ 如实接受但**经 @@Config.OnLeaseLost@@ 留痕**——「闸已易主、本次结果 作废」是事实不是成功路径,静默吞掉它宿主就永远不知道丢了什么。

优雅退出 = 停止领取 + 在途收敛 + 注销

外层 ctx 取消后:不再领取新任务,**当前在途任务收场**(收场动作走 WithoutCancel——排水期间的 Complete/Release 不能因 ctx 已取消而失败), 然后注销注册。在途何时收敛由 handler 对 ctx 的响应决定:handler 无视 取消就等于无限期排水——ctx 已把「该收手了」送到它手里,剩下的不是 本驱动能替它决定的。

managed.go —— 受管任务执行器:Claim → SideEffect.Execute → Checkpoint → Complete 的标准编排。

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

@@Loop@@ 的语义是「认领 → 调 Handler → 成功 Complete / 失败 Release」—— 失败即回板,可被重做。这条默认语义作用在**不可幂等**动作上就是重复施加: 下单、发信、改远程状态这类动作重跑一次,副作用就双份。

本执行器把「执行意图与对账」强制接进任务生命周期,四步不能重排、不能漏:

  1. **Claim**:拿租约与令牌(令牌由任务板铸造——任务归属的唯一凭据), 认领即开**租约会话**(@@LeaseSession@@:执行期间续期、关键步之前 确认所有权、易主封口在途执行);
  2. **SideEffect.Execute**:走 @@sideeffect.Runner@@ 的既有契约—— Acquire 原子登记执行意图 + 栅栏令牌,施加前做持有资格检查, 失败按 @@RetrySafety@@ 分流出「可重试」与「结果未知」;
  3. **Checkpoint**:副作用记账成功后单调提交进度快照(不覆盖更高版本); 进度面支持栅栏判据时带接管代次条件提交(存储侧拒绝陈旧代次的 迟到写入,见 @@LeasedProgress@@ / checkpoint.FencedStoreCAS);
  4. **Complete**:凭第 1 步的令牌收口。

不发明第二套状态机

本执行器**只做编排**:每个判定都调用既有原语,不复制任何状态。

  • 「这次能不能做」归 @@sideeffect.Store.Acquire@@(已完成 / 结果未知 / 执行中 / 资源被占 / 授予);
  • 「这次失败能不能重试」归 @@sideeffect.RetrySafety@@ 与 Runner 的四条 失败出口(Abandon / MarkUncertain + Release);
  • 「进度回退」归 @@checkpoint.Committer@@(SaveIfNewer + 进程内闸);
  • 「任务归谁」归 @@taskboard.Board@@(令牌 + 代次,Complete 校验令牌)。

本文件出现 if/else 的地方都是**处置分流**(这个既有结论该触发哪个 既有动作),不是第四份判据。

UNCERTAIN 在任务板上的落法

taskboard 没有(也不该有)UNCERTAIN 状态:结果未知是 @@sideeffect@@ 的 一等结论,任务板只回答「谁负责这个子任务」。本执行器的处置是:

  • **不 Complete**(没做成的不能记成做成了);
  • **释放任务板租约**(不占着一把谁都不敢动的锁);
  • 该副作用 Key 由 sideeffect 闸继续挡着——任何 worker 重新认领后, Runner.Acquire 返回 OutcomeUncertain ⇒ 不执行、再次释放。于是 「任务可被重新认领」与「动作不会被重跑」同时成立,阻塞点在唯一 该在的地方(副作用闸),而不是在任务板上再长一个状态。

对账入口是 @@ManagedExecutor.Resolve@@(转发 Runner.Reconcile,不另造裁决)。

与 worker.Loop 的取舍

  • 任务动作**不可幂等**(或宿主不确定)→ 用本执行器。它保证失败/不确定 不会被「回板重做」变成重复施加;
  • 动作可安全重做、或根本不对接外部副作用 → 用 @@worker.Loop@@ 更省 (它已经处理注册、心跳、续期、优雅退出)。

两者不要叠着用:本执行器自己 Claim、自己 Complete,再套 Loop 的 Handler 会对同一任务二次收口(第二次必然 ErrLeaseLost)。

任务选择不在本执行器里

Execute 收的是**一个任务 id**(调用方选定)。优先级 / 公平 / 配额等挑选 判据归 @@scheduling@@——本执行器不内嵌第二份,否则同一件事会有两个答案, 而漂移的形态是「调度说该做 A、执行器挑了 B」且两边都显示正常。

managed_lease.go —— 受管租约会话(issue #265)。

它补的是哪一段

受管执行器的四步编排(Claim → 施加 → Checkpoint → Complete)此前全程 没有续期:ClaimTTL 被迫覆盖「整个任务做完」,长任务(LLM 推理、工具 调用、远端阻塞都可能超过 TTL)必然撞上「执行到一半租约过期 ⇒ 被接管 ⇒ 旧持有者还在写」的错位。本文件把「认领之后、收场之前」这段的持有 资格收成一个**会话**:执行期间续期、关键步之前确认所有权、易主即刻 封口在途执行。

会话不是第二份租约状态

会话持有的唯一凭据(Token / Fence)出自任务板认领那次原子操作—— 与 @@taskboard.Board@@ 的「令牌由存储铸造」同源,本包不铸造、不缓存 第二份真相。续期走 @@RenewingBoard.Renew@@(资格校验 + 推后到期, 存储侧原子),确认所有权走同一个原语:会话只是把「什么时候调、调完 怎么处置」固化下来,不复制任何判定。

续期节拍(#266 的门)

续期按固定节拍跑在独立协程上(默认 TTL/3):一拍失败不致命——节拍 远短于 TTL,下一拍仍有出路;撑满 TTL 仍失败 ⇒ 任务可被接管,接管后 的下一拍必然 @@ErrLeaseLost@@ ⇒ 会话封口。调度策略(按到期时刻动态 安排、抖动、退避)是 #266 的车道:本会话提供的是「会话存续期间持有 资格有人管」的机制面,节拍经 @@LeaseSessionConfig.RenewInterval@@ 显式可换。

易主即封口

任一续期被 @@ErrLeaseLost@@ 拒(或 @@AssertOwned@@ 资格确认失败): 会话记下失因、取消 @@Context@@——在途的施加段随之取消(施加之前封口, 与 worker.Loop 在途取消同一纪律)。之后的一切资格确认快速失败, 不再碰一条已经死了的租约。

managed_resolve.go —— 受管执行器的对账与释放面。

Resolve 是宿主对「结果未知」副作用做人工/自动裁决的入口(转交 sideeffect.Runner.Reconcile);release / withRelease 是任务板租约的 收场面——ErrLeaseLost 不算故障(租约已易主,不该动新持有者的闸), 释放失败与主错误链式合并,两个信息都不丢。

memory.go —— Registry 的进程内参考实现(记忆版,**单进程演示用**)。

边界刻在类型上

MemRegistry 的原子性来自**进程内互斥锁**:Register 的「顶替 + 铸令牌」、 Heartbeat 的「资格校验 + 推后有效期」都在同一把锁内完成,但那只对同一 进程成立。多副本(多进程)共享注册表时,宿主要把同一套判据落到自己的 跨进程存储上(Redis SET NX PX / PostgreSQL 条件 UPDATE / etcd txn)—— 拿 MemRegistry 当多副本注册表,两个进程各持一把各自的锁, 「同 ID 顶替」「旧令牌心跳被拒」这些判据会显示为绿,而身份页实际上 已经不再一致(AGENTS.md「参考实现是可被误用的资产」那条纪律的原话场景)。

它在本仓的用途只有两个:①给 Loop 的契约用例当**测试保底**; ②给宿主当**形态示范**——照它的四个方法写跨进程版本(契约见 Registry)。

语义逐条

  • Register:同 ID 顶替并铸新令牌(崩溃重启是正常路径,先到者从此 被 ErrNotRegistered 拒在门外——它由此得知自己已被顶替,而不是靠 幽灵状态猜);
  • Heartbeat:令牌不匹配、记录不在、或有效期已过 ⇒ ErrNotRegistered (**不静默成功**);TTL <= 0 ⇒ ErrInvalidConfig;
  • Deregister:凭令牌;令牌不匹配 ⇒ ErrNotRegistered。过期的注册仍可 凭原令牌注销(收尾路径不该因为「刚好过期」而失败);
  • List:Alive 用**注册表自己的时钟**判(判据归存储侧,不归调用方); 过期记录保留在原地并显式 Alive=false——与 Registry.Status 的契约 一致(实现也可以清理,清理与否不是契约条款)。

pool.go —— 有界并发池(issue #196,Config.Concurrency > 1 的路径)。

形态:领取环单点、执行体有界并行

领取仍然只有一处(claimNext → Claim):并发认领会互相竞争同一个候选, 把「谁先领」变成随机重试;单点领取 + 并行执行拿到同样的吞吐,且 Pick 钩子不需要是并发安全的(既有契约不变)。

slots 是并发上限:领取前先占槽,认领到任务后把执行投给 async.GoSafe; 没有候选就立刻还槽并按 PollInterval 再试。因此慢任务只占执行槽, **不占领取环**。

排水(Drain)

停机 = 停止领取 + 等全部在途收场:

  • 外层 ctx 取消 ⇒ 主循环退出,执行体经派生 ctx 收到取消信号; 收场动作(Complete/Release)在 executeOne 里走 WithoutCancel, 落库不受停机影响;
  • 收场何时完成由 handler 对 ctx 的响应决定:handler 无视取消等于 无限期排水——这是既有 Loop 契约,不是并发池新增的语义。

失败处置

  • 执行体 panic → invokeHandler 收编为一次失败(Release),只影响该任务;
  • 收场(Complete/Release)返回基础设施错误 → 与串行路径同义:停止领取、 取消其它在途(它们按失败收场)、排水后把第一个错误交给 Run;
  • claimNext 的基础设施错误 → 同上(不再领取,等在途收场后返回)。

recover.go —— 任务恢复:接管前任留下的过期认领。

判资格不判时钟

「这个租约过期了吗」由**任务板自己的时钟与资格判定**回答(Board.Claim 对过期租约授予接管、对活租约报 ErrTaken——issue #87 之后的既有语义)。 Recover 不自建第二套时钟判据:它对每个认领态的任务直接尝试 Claim, 存储侧的结论就是结论。这与「判据归存储,不归进程」同一条纪律—— 恢复方拿本地时钟比对 Until,跨进程时钟对不上时会把活任务抢过来, 两个执行者做同一件事。

Package worker Worker Runtime 的**生命周期契约与驱动**:注册 → 心跳 → 领取 → 执行 → 续期/恢复 → 优雅退出。

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

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

@delegate@ 是委托的契约面(能不能交 / 交给谁 / 回来算不算完成), @taskboard@ 是认领的契约面(谁负责哪个子任务、怎么把认领还回去)—— 但「执行这些子任务的 worker 自己怎么活」此前没有机制面:各宿主自己写 注册、心跳、领取循环、退出清理,各写一套必然各漏一样(漏心跳 ⇒ 别人 以为它死了;漏续期 ⇒ 长任务必被接管;漏注销 ⇒ 注册表里全是幽灵)。

本包把生命周期收成两样:

  1. @@Registry@@:worker 注册/心跳/注销的**存储中立契约**(与 taskboard.Board 同一范式:语义归本包,落库归宿主);
  2. @@Loop@@:把六段生命周期串起来的**驱动**——领取走 taskboard.Board, 续期走 taskboard.RenewingBoard(issue #87 的能力,心跳不是摆设: 它续的就是那条契约的租约),退出走排水语义。

心跳与续期是两个心跳(都接上了既有契约)

  • **worker 心跳**(@@Registry.Heartbeat@@):「这个 worker 还活着」—— 注册表按它判离线,是资格检查不是纯计时(令牌不匹配即拒绝);
  • **任务租约续期**(@@taskboard.RenewingBoard.Renew@@):「这次认领 还有资格」——它是 issue #87 定的语义:校验令牌仍是最新代 + 推后 到期时刻,**同一次原子操作**。租约易主(@@ErrLeaseLost@@)时驱动 **取消在途执行的 ctx**:资格没了,施加副作用前必须收手——这正是 sideeffect「危险窗口要在施加之前封口」的同一条纪律在 worker 侧的落法。

并发池(issue #196)

Config.Concurrency 缺省 1 = 串行驱动(领一个、跑完、再领下一个),既有 宿主的语义逐字不变。显式 >1 时领取与执行解耦:领取环单点认领,执行体在 有界池里并行,每任务独立 token / cancel / 连续续期失败计数;慢任务不再 占住整个副本的领取能力。停机仍是「停止领取 + 在途逐个收场(WithoutCancel 落库)」,排水上界由 handler 对 ctx 取消的响应决定(与串行同一条契约)。

恢复(Recover)判资格不判时钟

崩溃恢复 = 接管前任留下的过期任务。@@Recover@@ 对每个在认领态的任务 直接尝试 @@Claim@@:租约仍活的被 @@ErrTaken@@ 拒(跳过),已过期的被 存储侧判过资格、授予新代——**过期判定归存储侧**(与 taskboard 的 判据归存储同一条纪律),本包不自建第二套时钟判据。

边界(契约 + 进程内参考实现;跨进程落库归宿主)

本包含契约、驱动与一份**进程内参考实现**(MemRegistry,memory.go): 后者的原子性来自进程内互斥锁,只给契约用例与宿主当形态示范——多副本 共享注册表的跨进程实现(Redis/PG/etcd)归宿主,本仓零数据库依赖。 端到端演示仍在 examples/worker-runtime(Worker 生命周期要靠真实的任务板 与注册表才能验证)。

Index

Constants

View Source
const DefaultPollInterval = 200 * time.Millisecond

DefaultPollInterval 领取轮询的缺省间隔。

View Source
const DefaultRenewConcurrency = 8

DefaultRenewConcurrency 续期并发的缺省上限(issue #266)。

200 个在途任务、单次续期 100ms 时:8 并发一轮约 2.5s,远小于常见 TTL; 串行实现是 20s(TTL 15s 时后段任务在轮到它之前就已过期)。

Variables

View Source
var ErrInvalidConfig = errors.New("worker: 配置非法")

ErrInvalidConfig Loop/Spec 的配置非法(空 ID、非正 TTL、心跳间隔不短于 注册有效期等)。

装配期就红:心跳间隔长于有效期 = 注册必然周期性过期,症状是 「同事 sees 幽灵/失踪交替」,而配置里每个数字看起来都合法。

View Source
var ErrLeaseUnconfirmed = errors.New("worker: 任务租约无法确认持有资格(连续续期失败跨过 TTL)")

ErrLeaseUnconfirmed 在途任务的租约连续续期失败跨过一个 TTL:驱动无法 确认自己仍是持有者,已取消在途执行并停止领取收刀(issue #179)。

与 @@ErrNotRegistered@@ 分列:那是身份没了,这是任务资格答不出来—— 两者对宿主的处置不同(前者查注册表/顶替,后者查任务板/存储健康)。 驱动报它即已收刀:续不上还继续开工,施加的每个副作用都可能是 与新持有者的双份。

View Source
var ErrNotRegistered = errors.New("worker: 注册已失效(令牌不匹配或有效期已过)")

ErrNotRegistered 注册已失效:令牌不匹配、注册被顶替、或有效期已过。

心跳拿到它 = 这个 worker 的身份已经没了(凭据由注册表铸造,丢了就是 丢了)。驱动收到它即停止领取新任务、收刀退出——身份没了还继续领任务, 账都记不到它头上。

Functions

func Recover

func Recover(ctx context.Context, board taskboard.Board, agent taskboard.AgentID, ttl time.Duration) ([]taskboard.TaskID, error)

Recover 接管任务板上「认领已过期」的任务(崩溃恢复入口)。

语义:

  • 认领态且租约已过期 → Claim 成功(接管,新令牌新代次),计入返回;
  • 认领态且租约仍活 → @@ErrTaken@@(前任还活着),跳过——**不抢活**;
  • 其余状态(open/failed/done)→ 不属于「恢复」的范畴,跳过 (open 任务本来就能被正常领取循环拿走);
  • 竞争性失败(ErrTaken/ErrBlocked/ErrTerminal/ErrNotFound)都是 「这次没轮上」的正常结论,不构成 error;非竞争类错误(任务板 不可用等)原样上抛。

返回本次成功接管的任务 id(调用方据此留痕:哪些任务换了主人)。 agent 是接管者标识;ttl 是接管后新租约的有效期(>0)。

Types

type Config

type Config struct {
	// Agent 任务认领者标识(taskboard.AgentID;注册 Spec.ID 也取它)。
	Agent taskboard.AgentID
	// TTL 认领租约与注册共用的有效期(>0)。共用一个刻度只是本驱动的
	// 缺省口径——要分开调的宿主自己组装即可(机制面不焊死策略)。
	TTL time.Duration
	// PollInterval 领取轮询间隔(0 = DefaultPollInterval)。
	PollInterval time.Duration
	// HeartbeatInterval 心跳/续期周期(0 = TTL/3)。必须短于 TTL,
	// 否则注册周期性过期(装配期拦下,不静默运行)。
	HeartbeatInterval time.Duration
	// Concurrency 同时在途执行的任务上限(0/1 = 串行,既有行为逐字不变;
	// 负值非法,装配期拦下)。>1 时领取与执行解耦:领取环只做认领并投递,
	// 执行体在有界池里并行——单个慢任务不再占住整个副本的领取能力。
	//
	// 租约契约与串行路径相同,只是**按任务独立**:每个在途任务有自己的
	// token / cancel / 连续续期失败计数;ErrLeaseLost 只取消它自己;
	// 连续续期失败跨过阈值(ErrLeaseUnconfirmed)仍按既有契约停止领取
	// 并收刀。停机时停止领取、等待全部在途收场(handler 无视 ctx 取消
	// 时排水同样无上界——既有语义)。
	Concurrency int
	// Pick 可选的挑选钩子:从候选任务里挑一个认领。缺省按 ID 序取第一个
	// 可认领的(确定性——不依赖任务板返回顺序)。优先级/公平性等挑选策略
	// 由宿主在此接线(判据面见 scheduling 包;本驱动不内嵌第二份)。
	Pick func(candidates []taskboard.Task) (taskboard.TaskID, bool)
	// RenewFailMax 在途租约的连续续期失败阈值:连续失败达到它(且外层
	// ctx 未取消)= 无法确认持有资格,驱动取消在途执行的 ctx 并停止
	// 领取收刀(@@ErrLeaseUnconfirmed@@)。0 = 缺省
	// ceil(TTL/HeartbeatInterval)——连续失败跨过一个 TTL 还没续上,租约
	// 按已到期对待(期间接管者随时可能就位);负值非法(装配期拦下)。
	RenewFailMax int
	// RenewMargin 提前续期的安全余量(issue #266):租约到期前 margin 就发起
	// 下一次续期,而不是等到最后一拍。0 = TTL/3;必须 >0 且 < TTL。
	//
	// 续期调度按**本进程时钟**推算「距上次成功续期已过去多久」,不与存储的
	// 绝对 Until 比较——调用方与存储的时钟可能对不上(TTL 才是共同刻度)。
	RenewMargin time.Duration
	// RenewConcurrency 同一拍内逐条续期的并发上限(issue #266)。0 = 8;
	// 负值非法。批量续期接口存在时本值不参与(一次往返续一批)。
	RenewConcurrency int
	// RenewTimeout 单条/单批续期的超时(issue #266)。超时只算该任务一次
	// 续期失败(与其它错误分开计数),不阻断同拍其它任务。0 = TTL/4。
	RenewTimeout time.Duration
	// OnLeaseLost 在途租约失去资格时的可观测钩子(nil = 不回调)。
	//
	// 三个触发点(见 @@LeaseLostCause@@):续期报 @@taskboard.ErrLeaseLost@@
	// (租约已易主);连续续期失败到阈值(无法确认持有资格);收场动作
	// (Complete/Release)被 @@taskboard.ErrLeaseLost@@ 拒(结果作废)。
	// 三个都是「本次执行的结果已作废」的事实,不是成功路径——宿主据此
	// 计数/留痕/告警,静默吞掉它们下游的非幂等副作用就可能双份(issue
	// #179 的触发序列)。
	//
	// 回调在心跳协程/收场路径上同步调用,但**不在 claimed.mu 内**(issue
	// #326):续期判定与收场互斥,通知一律在锁外——宿主回调回查本包的
	// 任务板/注册表不会二次抢锁死锁。回调 panic 被隔离(与 invokeHandler
	// 同款):留痕钩子的异常不得掀翻心跳面,否则全部在途租约停止续期。
	// 仍然要求快返回,别在里面做重活。
	OnLeaseLost func(task taskboard.TaskID, cause LeaseLostCause)
}

Config 驱动配置(零值不可用;NewLoop 做装配期校验)。

type EffectRunner added in v0.39.0

type EffectRunner interface {
	// ExecuteWith 抢闸 → 准备 → 持有资格检查 → 施加 → 记账(语义见
	// sideeffect.Runner.ExecuteWith)。
	ExecuteWith(ctx context.Context, act sideeffect.Action, eff sideeffect.Effect) (sideeffect.Outcome, sideeffect.Result, error)
	// Reconcile 对账裁决结果未知的 Key(语义见 sideeffect.Runner.Reconcile)。
	Reconcile(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
}

EffectRunner 受管执行器依赖的副作用编排面(*sideeffect.Runner 满足)。

收成接口而不是直接收 *sideeffect.Runner:执行器的用例要能精确构造 「Applied / Replayed / Contended / Uncertain」四种结论,而这两种结论的 真实构造需要完整的存储替身;接口让编排判据与存储实现解耦(生产构造 仍只接受 *sideeffect.Runner 的实现,见 NewManagedExecutor)。

type Handler

type Handler interface {
	Execute(ctx context.Context, task taskboard.Task) error
}

Handler 一个任务的执行体(宿主实现;本包不认识任务内容)。

Execute 收到的 ctx 在「租约易主」「外层停机」时被取消:**施加副作用之前** 应检查它。返回 nil ⇒ 驱动 Complete 任务;返回 err ⇒ 驱动 Release 任务 (任务可被重做)。

type HandlerFunc

type HandlerFunc func(ctx context.Context, task taskboard.Task) error

HandlerFunc 函数适配器。

func (HandlerFunc) Execute

func (f HandlerFunc) Execute(ctx context.Context, task taskboard.Task) error

Execute 实现 Handler。

type LeaseLostCause added in v0.39.0

type LeaseLostCause int

LeaseLostCause 在途租约失去资格的原因(@@Config.OnLeaseLost@@ 的判别面)。

const (
	// LeaseLostTakenOver 续期报 @@taskboard.ErrLeaseLost@@:租约已易主
	//(新持有者在位),在途执行的 ctx 随之取消。
	LeaseLostTakenOver LeaseLostCause = iota
	// LeaseLostUnconfirmed 连续续期失败跨过阈值:无法确认持有资格——
	// 取消在途 ctx 并停止领取(施加之前封口;本次连「谁在持」都答不出)。
	LeaseLostUnconfirmed
	// LeaseLostOnFinalize 收场动作(Complete/Release)被
	// @@taskboard.ErrLeaseLost@@ 拒:任务已归新持有者,本次结果作废。
	LeaseLostOnFinalize
)

func (LeaseLostCause) String added in v0.39.0

func (c LeaseLostCause) String() string

type LeaseSession added in v0.42.0

type LeaseSession interface {
	// Context 会话作用域的 ctx:租约易主或 Close 后取消。
	Context() context.Context
	// Token 本次认领的租约令牌(Complete / Release 的唯一凭据)。
	Token() string
	// Fence 本次认领的接管代次(下游栅栏判据的出示值)。
	Fence() uint64
	// AssertOwned 确认持有资格并推后到期(Renew)。失格后恒返回
	// ErrLeaseLost 链(快速失败,不重试已死的租约)。
	AssertOwned(ctx context.Context) error
	// Close 停止续期协程并取消会话 ctx(幂等;不归还租约)。
	Close(ctx context.Context) error
}

LeaseSession 一次任务认领的租约会话(issue #265)。

生命周期:认领成功后由 @@NewLeaseSession@@ 开启;调用方**必须**在收场 后 @@Close@@(释放续期协程,不释放租约——租约归还/收口是编排面的处置, 见 ManagedExecutor)。Context 在会话关闭或租约易主时取消。

契约

  • Token / Fence 是认领那次原子操作铸造的凭据(只读投影,不另铸);
  • Context() 返回的 ctx 在租约易主或 Close 后取消——长动作应拿它执行, 易主时施加段被取消(封口);
  • AssertOwned 是**资格确认 + 续期**(不是心跳):存储侧校验令牌仍是 最新代并推后到期;被 @@taskboard.ErrLeaseLost@@ 拒即失格(此后恒败);
  • Close 停止续期并等待协程退出;**不**归还租约(归还归编排面—— 收口与释放的处置各不相同,会话不替调用方选)。

func NewLeaseSession added in v0.42.0

func NewLeaseSession(ctx context.Context, board taskboard.RenewingBoard, task taskboard.Task, cfg LeaseSessionConfig) (LeaseSession, error)

NewLeaseSession 为一次认领开启租约会话:立刻起续期协程,直到 Close。

会话 ctx 派生自传入的 ctx:外层取消(停机)时在途执行随之封口—— 与租约易主的封口同一通道(Context),两个失格源不设第二套机制。

task 必须携带认领铸造的租约(Lease.Token 为空 ⇒ ErrInvalidConfig—— 没有凭据的会话是摆设,静默开启等于假装持有)。

type LeaseSessionConfig added in v0.42.0

type LeaseSessionConfig struct {
	// TTL 每次续期申请的租约有效期(必填,>0)——与认领时同一口径,
	// 由存储按自己的时钟推算。
	TTL time.Duration
	// RenewInterval 续期节拍(零值 = TTL/3)。
	//
	// 必须短于 TTL:节拍是「资格容忍窗」里的巡逻频率,等于或超过 TTL
	// 意味着两次巡逻之间租约必然过期——那不是续期,是补票。显式给了
	// 非正值以外的配置时按装配期错误拒绝(ErrInvalidConfig)。
	//
	// 调度策略的正式化(按到期时刻动态安排、抖动、退避)是 #266 的车道;
	// 本字段是换装点,不是最终形态。
	RenewInterval time.Duration
}

LeaseSessionConfig 会话配置。

type LeasedProgress added in v0.42.0

type LeasedProgress interface {
	// CommitFenced 带接管代次的条件提交(语义见 checkpoint.FencedStoreCAS)。
	CommitFenced(ctx context.Context, s checkpoint.Snapshot, fence uint64) error
}

LeasedProgress 带**持有凭据**的进度提交面(*checkpoint.Committer 满足, 经 CommitFenced)。

进度实现了它时,执行器把本次认领的接管代次(@@LeaseSession.Fence@@) 一并交给存储:陈旧代次的迟到提交由**存储侧**拒绝(check-then-act 的 窗口靠这个关,调用前的资格确认关不住它,见 checkpoint.FencedStoreCAS)。 未实现时退回普通 Commit——资格确认仍在(提交前 AssertOwned),但 「确认通过之后、写入落地之前」的窗口只剩 TTL 量级的兜底,宿主要严格 一致的状态提交必须装配支持栅栏判据的存储。

type Loop

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

Loop 六段生命周期的驱动。Run 之外的可见状态一律经任务板与注册表读取 ——派生状态只有一个真相(板里是什么状态,外面看到的就是什么状态)。

func NewLoop

func NewLoop(board taskboard.RenewingBoard, registry Registry, handler Handler, cfg Config) (*Loop, error)

NewLoop 校验配置并构造驱动。

func (*Loop) Run

func (l *Loop) Run(ctx context.Context) error

Run 跑完整生命周期(阻塞到外层 ctx 取消或身份丢失)。

返回 nil = 优雅退出(在途已收场、注册已注销); 返回 ErrNotRegistered = 身份在途丢失(已尽力注销); 其余错误 = 装配或基础设施故障。

type ManagedConfig added in v0.39.0

type ManagedConfig struct {
	// Agent 任务认领者标识(必填)。
	Agent taskboard.AgentID
	// ClaimTTL 认领租约有效期(必填,>0)。
	//
	// # ClaimTTL 覆盖什么、不覆盖什么(issue #265)
	//
	// **覆盖**:两次续期之间的资格容忍窗。本执行器为每次 Execute 开
	// 租约会话(见 @@LeaseSession@@),执行期间按 RenewInterval 节拍续期
	// ——TTL 不再是「整个任务必须做完」的截止线,长任务不会只因超时
	// 就被接管。
	//
	// **不覆盖**:
	//   - **续期断档**:节拍短于 TTL 是资格的前提(节拍 ≥ TTL 会被装配
	//     期拒绝)。存储抖动或进程暂停跨满 TTL ⇒ 任务可被接管;接管后
	//     旧持有者的迟到提交由存储端条件提交(@@LeasedProgress@@)与
	//     Complete 的令牌校验拒绝——TTL 是资格的容忍窗,不是免死金牌;
	//   - **副作用闸的租约**(sideeffect.Runner 的 TTL 另配)与**下游
	//     栅栏**(sideeffect.FencedSink)——两份独立判据面,本执行器的
	//     续期不替它们续;
	//   - **进度归属**:租约只答「任务归谁」。谁有权写这个 run 的恢复点,
	//     由进度存储的代次判定答(checkpoint.FencedStoreCAS)。
	ClaimTTL time.Duration
	// RenewInterval 租约续期节拍(可选;零值 = ClaimTTL/3)。
	//
	// 必须短于 ClaimTTL(装配期拒绝)。调度策略的正式化(按到期时刻动态
	// 安排、抖动、退避)是 #266 的车道;本字段是换装点。
	RenewInterval time.Duration
	// Progress 进度提交面(可选;nil = 本执行器不提交进度)。
	//
	// 实现 @@LeasedProgress@@(如 *checkpoint.Committer,其存储实现
	// checkpoint.FencedStoreCAS 时)即获得存储端的迟到提交拒绝;
	// 只有 Commit 时提交前仍有资格确认,但 check-then-act 窗口没有
	// 存储侧判据兜底。
	Progress Progress
}

ManagedConfig 执行器配置(零值不可用;NewManagedExecutor 做装配期校验)。

type ManagedExecutor added in v0.39.0

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

ManagedExecutor 受管任务执行器(可组合组件;无共享可变状态)。

func NewManagedExecutor added in v0.39.0

func NewManagedExecutor(board taskboard.RenewingBoard, effects EffectRunner, cfg ManagedConfig) (*ManagedExecutor, error)

NewManagedExecutor 装配执行器。

func (*ManagedExecutor) Execute added in v0.39.0

Execute 受管执行一个任务(阻塞到本次收场)。

认领成功即开租约会话(@@LeaseSession@@):执行期间按节拍续期,施加段 跑在会话 ctx 上(租约易主 ⇒ 在途取消),进度与收口前各做一次资格确认。

返回的 Outcome 是**副作用闸的结论**(Applied / Replayed / Contended / Uncertain)——调用方据此区分「我做完了」「别人做过了」「没轮上我」 「上次结果未知」。error 只表示本次调用没能完整走完编排(认领失败、 副作用失败、进度失败、资格被拒、收口被拒);Contended 不带 error (正常判据)。

各结论的处置:

  • Applied / Replayed → 资格确认 → 快照提交(若装配)→ 资格确认 → Complete;
  • Contended → 释放任务板租约(让别的 worker 试),不 Complete;
  • Uncertain → **不 Complete**、释放租约;副作用闸继续挡着重试;
  • 资格确认或 Complete 被 ErrLeaseLost 拒 → 如实返回(任务已归新 持有者),**不重试、不覆盖**——本次副作用已记账,重试会与真正 持有者重复;进度提交被 ErrStaleFence 拒同理(本 run 已归新代)。

func (*ManagedExecutor) Resolve added in v0.39.0

type ManagedWork added in v0.39.0

type ManagedWork struct {
	// Action 副作用动作。Key / Resource 留空时由任务 id 派生(默认键的
	// 作用域口径见 Scope):零作用域时 key = "task:" + id、resource = id
	// (旧口径逐字不变);有作用域时按 @@sideeffect.ActionKeyBuilder@@
	// 全段转义拼接。同一次任务的重试因此天然共用同一个幂等键;宿主需要
	// 更细的粒度时显式给(拼装走 ActionKeyBuilder,不要各自拼字符串——
	// 拼法分散就是口径漂移的开始)。
	Action sideeffect.Action
	// Scope 动作身份的**作用域段**(可选;宿主词汇——运行 id、环境名、
	// 任务板未覆盖的命名空间维度……本仓不解释段的内容,见
	// sideeffect.ActionKeyBuilder 的词汇归属说明)。
	//
	// 默认键的作用域段自动并入两项:
	//   - 任务板的租户(@@Task.Tenant@@ 非空时)——与任务板的作用域口径
	//     对齐:coord 的任务板分租户,副作用闸不分就会跨租户互相重放
	//     (issue #261);
	//   - 本字段给的段(按给出顺序拼接)。
	//
	// 稳定性:同一逻辑动作的所有重试必须给同一组段——Attempt / 重试
	// 计数 / 时间戳不得入段(入段即每次重试一个新动作,幂等闸形同虚设)。
	Scope []string
	// Effect 执行体(Prepare / Apply;Apply 必填)。
	Effect sideeffect.Effect
	// Snapshot 成功后构造进度快照(可选;nil = 不记录进度)。
	//
	// 返回 false 表示「这次任务没有进度可记」(不是错误,也不阻塞 Complete)。
	// 配置了 Snapshot 但没有装配 Progress ⇒ 装配期之外的显式错误,不会
	// 静默跳过(静默跳过会让宿主以为进度落了库)。
	Snapshot func(task taskboard.Task, res sideeffect.Result) (checkpoint.Snapshot, bool, error)
}

ManagedWork 一个受管任务要做的动作(由宿主按任务给出)。

type MemRegistry added in v0.39.0

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

MemRegistry Registry 的进程内参考实现。经 NewMemRegistry 构造; 零值可用(内部状态惰性初始化)。并发安全。

func NewMemRegistry added in v0.39.0

func NewMemRegistry(opts ...RegistryOption) *MemRegistry

NewMemRegistry 构造参考实现。opts 见 RegistryOption。

func (*MemRegistry) Deregister added in v0.39.0

func (m *MemRegistry) Deregister(_ context.Context, id, token string) error

Deregister 注销(凭令牌;过期的注册仍可凭原令牌收尾)。

func (*MemRegistry) Heartbeat added in v0.39.0

func (m *MemRegistry) Heartbeat(_ context.Context, id, token string, ttl time.Duration) (time.Time, error)

Heartbeat 心跳 = 资格检查 + 延长有效期(同一把锁内完成——原子)。

func (*MemRegistry) List added in v0.39.0

func (m *MemRegistry) List(_ context.Context) ([]Status, error)

List 全量快照(Alive 用注册表自己的时钟判——判据归存储侧)。 过期记录保留并显式 Alive=false(契约允许实现自行清理;这里选择让 幽灵可见:运维看到「有一条过期注册」比「它凭空消失」更容易解释)。

func (*MemRegistry) Register added in v0.39.0

func (m *MemRegistry) Register(_ context.Context, spec Spec) (Registration, error)

Register 注册一个 worker(同 ID 顶替旧注册并铸新令牌)。

type Progress added in v0.39.0

type Progress interface {
	Commit(ctx context.Context, s checkpoint.Snapshot) error
}

Progress 进度快照的提交面(*checkpoint.Committer 满足)。

只收 Commit 一个方法:单调判定(SaveIfNewer + 进程内闸)在 Committer / StoreCAS 里,本执行器不重写。

type Registration

type Registration struct {
	// ID worker 标识。
	ID string
	// Token 注册表铸造的凭据。
	Token string
	// ExpiresAt 当前有效期终点(存储时钟口径;心跳成功后前移)。
	ExpiresAt time.Time
}

Registration 一次注册的凭证(由注册表铸造;心跳与注销的唯一凭据)。

与 taskboard「令牌由存储铸造」同一条纪律:调用方自带的凭据不是凭据 ——凭据铸造在注册表的原子操作里,调用方拿到的只是它。

type Registry

type Registry interface {
	// Register 注册一个 worker(同 ID 顶替旧注册并铸新令牌)。
	Register(ctx context.Context, spec Spec) (Registration, error)
	// Heartbeat 心跳 = 资格检查 + 延长有效期(凭 Token;TTL 语义与
	// Register 一致:正数按存储时钟推算,<=0 报错——「不设限的注册」
	// 会让幽灵永远在线)。
	Heartbeat(ctx context.Context, id, token string, ttl time.Duration) (time.Time, error)
	// Deregister 注销(凭 Token;优雅退出收尾)。
	Deregister(ctx context.Context, id, token string) error
	// List 全量快照(判据归存储侧:Alive 用存储时钟判)。
	List(ctx context.Context) ([]Status, error)
}

Registry worker 注册表的存储中立契约。

实现方必须保证:

  • Register / Heartbeat / Deregister 的**资格校验与写入**是一次原子操作 (心跳推后有效期与校验令牌不可分——拆两步就是「假心跳」: 顶替者已在位,原持有者的心跳延长的却是别人的注册);
  • 心跳凭 Token 认人,不匹配报 @@ErrNotRegistered@@(不静默成功);
  • ExpiresAt 由**存储自己的时钟**推算(调用方时钟与存储时钟不可假设一致)。

type RegistryOption added in v0.39.0

type RegistryOption func(*registryConfig)

RegistryOption MemRegistry 的装配选项。

func WithRegistryClock added in v0.39.0

func WithRegistryClock(now func() time.Time) RegistryOption

WithRegistryClock 注入注册表读时钟的方式(测试与演练用)。

生产装配不必注入:到期判定走注册表自己的时钟是契约要求, 多副本下这个「自己的时钟」应当是存储侧时钟(见 Registry 的说明)。

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

接缝契约(issue #369)

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

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

type Spec

type Spec struct {
	// ID worker 标识(宿主词表;空串非法)。允许重复注册:后到者顶替
	// 先到者并铸新令牌(崩溃重启是正常路径,先到者的心跳从此被拒
	// ——它由此得知自己已被顶替,而不是靠幽灵状态猜)。
	ID string
	// Labels 原样携带的标签(能力声明、分组等;语义由宿主解释)。
	Labels map[string]string
	// TTL 注册有效期(>0 必填):两次心跳之间隔多久算离线。
	// 这与任务的租约 TTL 是两回事——worker 活着不等于某个任务还在做。
	TTL time.Duration
}

Spec 注册声明:worker 是谁、要多久的心跳周期。

func (Spec) Validate

func (s Spec) Validate() error

Validate 装配期自检(违者报 ErrInvalidConfig)。

type Status

type Status struct {
	// ID worker 标识。
	ID string
	// Labels 注册时声明的标签(快照)。
	Labels map[string]string
	// ExpiresAt 有效期终点(存储时钟口径)。
	ExpiresAt time.Time
	// Alive 注册表判定:有效期未过(在线)。已过期的记录是否被清除
	// 由实现决定(清了就不在 List 里;不清则 Alive=false 显式可见)。
	Alive bool
}

Status 注册表里一条 worker 记录的快照(List 的产出)。

Alive 由**注册表用自己的时钟**判(判据归存储侧,不归调用方—— 跨进程时钟对不上,调用方拿 time.Now 比对 ExpiresAt 是自建第二套判据)。

Jump to

Keyboard shortcuts

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