Documentation
¶
Overview ¶
audit.go —— 介入留痕契约与进程内参考实现。
留痕是介入的硬前提,不是事后增强:没有留痕的介入无法回答「谁在什么时候 依据什么改了运行状态」,出问题时与「存储被绕过直接改」无法区分。 故契约层面 Auditor 缺位 ⇒ 介入一律拒绝(ErrNoAuditor),实现层面 MemAuditor 对不完整的留痕拒收——两层各挡一个方向。
authority.go —— 控制面与运行时/副作用闸的**权威写入面**(issue #268)。
它补的是哪一段 ¶
旧形态里控制面的强制释放走 controlplane.Store.CommitTask,Worker 走 taskboard.Board——两个接口不强制共享同一条权威任务记录。宿主各接一份 存储时,运维「强制释放」只改了一个投影:任务板仍认为旧令牌有效,旧 Worker 继续执行、继续提交;两份状态各显示正常。
本文件给两条**权威面**,由宿主在装配期注入:
- TaskAuthority:必须就是 Worker 使用的 taskboard.Board(或其同一事务 后端/同一张表的包装)。ForceRelease 直接调用它凭令牌释放,令牌/代次 在同一处判定——旧 Worker 的 Renew/Complete 由同一份任务板拒收。 authoritative 模式**不再**调用 Store.CommitTask:结构上不存在第二份 可写任务状态;
- EffectAuthority:必须落到副作用闸(sideeffect.Store.ResolveUncertain) 读取的同一份状态,而不是控制面自己维护的效果投影。裁决之后闸看到的 就是这份结论。
装配期同源校验 ¶
内核不能靠类型猜「两份存储是不是同一张表」。宿主可选实现 TaskSource, 让 Store 与 TaskAuthority 各报一个来源标识;两者都实现且不一致 ⇒ ErrAuthorityMismatch(装配期拒绝)。不实现则跳过这项校验——校验是宿主 显式声明的前提,不是内核替它假设。
Package controlplane 控制平面的**最小契约 + 进程内参考实现 + HTTP 适配面**。
生命周期: Experimental(v0.35.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
它补的是哪一段(issue #115) ¶
本仓此前最接近控制面的是 taskboard.Check——判一份快照的不变量,宿主随时 可跑。但它不回答「现在跑到哪了」(运行状态查询),更不提供任何**人工介入** 动作:强制释放、裁决未知结果、终止运行。缺这一面的代价是:线上出问题时 宿主只能自己拼命令去查、自己去改存储——这些动作**绕过了运行时的判据**, 改完可能与运行中的持有者打架。
契约给什么 ¶
- **查询**:任务 / 运行的状态视图 + 不变量视图(taskboard.Check 的 投影,TaskView / RunView);
- **介入**:强制释放(ForceRelease)、裁决未知结果(Adjudicate)、 终止运行(Terminate);
- **权限边界**:介入动作必须走**与运行时同一套判据**,不绕闸—— 强制释放是「经闸换持有者」(旧令牌当场作废,迟到提交凭 taskboard.ErrLeaseLost 被拒;下一次认领铸造的代次严格大于被释放的 那一代,下游栅栏据此拒收被释放者的迟到写入);裁决走 sideeffect 的 对账语义(凭下游事实不凭持有权,先到者为准);终止凭**运行代次** (ExpectedGen 不匹配即 ErrStaleRun——「改完与运行中的持有者打架」 正是这条要拦的形态)。租户上下文经 tenant.Require fail-closed: 介入是写路径,必须可归责到租户与主体(issue #114 判据面的落点);
- **留痕**:每次介入必须产生一条 AuditEntry(谁、什么时候、依据什么 结论),留痕面缺位 ⇒ 介入一律拒绝(ErrNoAuditor)——没有留痕的 介入无法回答「谁在什么时候依据什么改了运行状态」。
边界 ¶
控制平面是**接口面**,不是 UI;具体界面归宿主。本包给四样:
- Plane 契约(宿主包着自己的 taskboard.Board / sideeffect Runner / 运行状态存储实现它);
- 宿主自有类型的窄契约族(HostPlane / AuthorizerOf——泛型 ID 与宿主 快照/租户类型,纯接口零实现,见 hostiface.go;issue #238);
- 存储中立实现:Store 契约(任务/运行/效果键的一致快照 + 带版本锚的 原子提交,留痕与状态同事务)+ StorePlane(查询/介入的唯一一份判定 逻辑,多副本共享同一 Store 即跨实例可见);进程内参考实现见 MemStore / MemPlane / MemAuditor(判据怎么落的演示体,也是测试与 演练的最小运行时面);
- net/http JSON 适配面(httpapi.go——鉴权钩子由宿主注入,内核不鉴权)。
hostiface.go —— 宿主自有类型接入的窄契约族(issue #238)。
Plane 是 taskboard 原生的便利契约:任务 ID 是 taskboard.TaskID、视图里是 taskboard.Task / taskboard.Problem、租户上下文是 tenant.Context。宿主若已有 自己的任务 ID / 运行 ID / 快照 / 租户类型,不该为了接入控制面先造一份 taskboard 副本——本文件给出与 taskboard **解耦**的窄契约:
- ID 用类型参数表达(任何 comparable 类型,string / 整型 / 自定义结构体均可);
- 任务快照与不变量条目的类型由宿主决定(TaskViewOf[T, P] / RunViewOf);
- 租户上下文不进方法签名(它经 context.Context 传递,载体由宿主决定)。
零实现纪律 ¶
本文件**只有声明**,不提供任何适配器或默认实现:接入由宿主完成。 参考实现 MemPlane 仍实现 taskboard 原生的 Plane,供演练与测试使用。 窄契约与原生契约是并列的两条接缝,不是「旧接口的包装层」——包一层 适配器会重新引入它本想拆掉的那份类型耦合。
与原生契约的分工 ¶
宿主已有 taskboard.Board / tenant.Context → 实现 Plane(任务板与租户面已就位) 宿主自有任务模型 / 租户体系 → 实现 HostPlane + AuthorizerOf
两条契约的**判定纪律相同**(介入走运行时同一套令牌 / 代次 / 栅栏,留痕 缺位即拒绝,介入者与依据必填);窄契约只换类型,不换判据。
httpapi.go —— 控制面的 net/http JSON 适配面。
鉴权边界:内核不鉴权 ¶
scope 词表、租户体系、会话形态全是宿主资产。Handler 持有 Authorizer 钩子 (宿主实现):它从请求解析主体与租户、判定该动作是否可执行,返回的 tenant.Context 被注入 request context 传给 Plane——Plane 侧的 tenant.Require(读与写共用的 fail-closed 判据,issue #197)据此有据可判。 这是「HTTP 面 ↔ 机制面」的唯一接缝:宿主在钩子里做完自己的判定, 机制面拿到的已经是判定过的上下文。
两层 fail-closed,缺一即 401:钩子缺位 ⇒ 全部请求 401;钩子在但对任何 请求返回零值 tenant.Context + nil ⇒ 全部请求(**含两个只读端点**) 仍被 Plane 的 tenant.Require 拒成 401——读路径不做第二道闸的话, 「同样的鉴权钩子、同样的错误,只有读放行」就是口子(issue #197)。
CSRF 边界(issue #198):Authorization 头形态,Cookie 会话不在此面 ¶
介入端点全部是 POST + JSON body,而浏览器的跨站「简单请求」(表单的 urlencoded、fetch 的 text/plain)不触发 CORS 预检,可以直接打进来—— force-release / terminate / adjudicate 又都是不可幂等的介入。防线两层, 都在本包写死:
- Content-Type 闸(见 decode):介入请求只收 application/json,缺省与 其它类型一律 415——两种跨站简单请求形态都挡在 JSON 解码之前(Go 的 JSON 解码器本不看 Content-Type,不设闸它们会被当合法请求处理);
- 鉴权只认 Authorization 头:宿主钩子(Authorizer)从请求头解析凭据, 本面**禁止 Cookie 会话**——跨站请求带不上 Authorization 头,无凭据 即 401/403。宿主若坚持 Cookie 形态,CSRF 防线(同源校验 / SameSite=Strict / 双提交令牌)归宿主,内核不背书。
路由(Go 1.22+ 模式路由) ¶
GET /tasks/{id} → TaskView
GET /runs/{id} → RunView
POST /tasks/{id}/force-release body: ForceRelease
POST /effects/{key}/adjudicate body: Adjudication
POST /runs/{id}/terminate body: Termination
路径参数是介入目标的**唯一来源**:请求体里同名字段被忽略——同一个目标 不允许两条来源(一个真相)。
memplane.go —— 控制面的进程内参考实现。
MemPlane 同时是两面 ¶
- **控制面**:实现 Plane 契约(查询 + 三类介入)。判定逻辑由 StorePlane 提供(与持久化 Plane **同一份**状态机);MemPlane 只是把 Store 固定 成进程内的 MemStore——单进程演示与测试的最小运行时面;
- **最小运行时面**:SeedRun / SeedEffect / Claim / Complete / Release 驱动场景(runtime.go)——控制面的介入判据必须对着真实的租约与代次 演示(强释之后旧令牌提交被拒、下一次认领代次严格递增)。
多副本共享控制面时用 NewStorePlane + 宿主的持久化 Store;MemStore 的 互斥锁只在单进程内成立(边界见 memstore.go)。
参考实现用单调计数器铸令牌(可读、可断言),**不承诺随机性**:宿主 实现存储时按 taskboard 的契约自行铸造(不可预测性是宿主的安全需求, 参考实现只演示判据)。
memstore.go —— Store 的进程内参考实现(issue #189)。
边界 ¶
MemStore 的原子性来自**进程内互斥锁**:快照一致、版本锚、留痕与状态 同事务都只在单进程内成立。多副本(多进程)共享控制面状态时,宿主必须 把同一份 Store 契约落到自己的持久化存储上(状态行 + 审计行同一事务); 拿 MemStore 当多副本存储,两个进程各持一份状态,介入可见性会显示为绿, 而 A 的强释在 B 的视图里从未发生(AGENTS.md「参考实现是可被误用的 资产」的原话场景)。
它在本仓的用途只有两个:①给 StorePlane 的契约用例当**测试保底** (两个 StorePlane 共享同一 MemStore 即「两个副本共享同一存储」的替身); ②给宿主当**形态示范**——照三个 Snapshot/三个 Commit 写持久化版本。
保留 MemPlane 的运行时面 ¶
SeedRun / SeedEffect / Claim / Complete / Release 仍是参考运行时的最小 面(runtime.go):控制面的介入判据必须对着真实的租约与代次演示。 这些方法不属于 Store 契约——宿主的真实运行时是自己的 taskboard.Board / sideeffect Runner。
runtime.go —— MemStore 的**最小运行时面**(建场景与认领/提交/归还)。
控制面的介入判据必须对着运行时的租约与代次演示(强释之后旧令牌提交 被拒、下一次认领代次严格递增),没有运行时面就没有可演示的「同一套 判据」。这些方法不是 Store / Plane 契约的一部分——它们是「运行时那一侧」 的参考实现:宿主的真实运行时是自己的 taskboard.Board / sideeffect Runner / 状态存储。
Seed* 先整单校验再落账:部分落账的 run 是半成品状态,视图会把 「建了一半」当成「建成了」。
store.go —— 控制面状态的**存储中立契约**(issue #189)。
它补的是哪一段 ¶
Plane 此前只有 MemPlane 一份进程内实现:两个副本各持一份状态,A 的介入 (强释 / 裁决 / 终止)在 B 的视图里不可见,B 的旧视图还能通过 CAS—— 「人工介入」在多副本下退化成「只在一个进程里算数」。
Store 把 Plane 需要的状态拆成三类记录(任务 / 运行 / 效果键)与两个 原语(一致快照读、带版本锚的原子提交),落库仍归宿主:表结构、事务 边界、编码形态都是宿主资产。内核只给契约与判据(StorePlane 是唯一 一份判定逻辑;MemStore 是进程内参考实现)。
三条硬契约 ¶
- **快照一致**:SnapshotTask / SnapshotRun 返回的任务集合与运行状态 来自同一瞬间(不是边改边读的流);TaskView 的 run 级不变量判据 依赖这一点。
- **提交原子且带版本锚**:Commit* 的 expect 必须等于对应快照的 Version;不一致 ⇒ ErrStoreConflict 且**什么都不写**(调用方重读重判)。 版本由存储推进:要么全局修订号、要么记录行版本,两种实现都满足; 契约只要求「快照之后目标被改过 ⇒ 提交必失败」。
- **留痕与状态同事务**:Commit* 同时追加一条 AuditEntry 并写状态; 留痕失败 ⇒ 状态一字不动(ErrNoAuditor / 留痕后端错误原样传出)。 这是 issue #180「一次失败的介入不得改变可观测状态」在存储契约上的 落点——没有「先改后补痕迹」的窗口。
为什么版本锚不取「值相等」 ¶
值相等断言在 ABA 场景(改走又改回)会误判「没动过」;版本随每次成功 提交推进,锚的是**变更次数**而不是变更后的内容——与 coord.Backend 的 Version 断言、commitgate「凭令牌认占用」同一条纪律。
storeplane.go —— Plane 的**存储中立实现**(Store 后端;issue #189)。
判定逻辑只有这一份 ¶
查询与三类介入的判据全部在本文件:快照读 → 判定 → 带版本锚的原子提交 (状态 + 留痕同事务)。MemPlane 只是把 Store 固定成 MemStore 的薄壳 (memplane.go)——参考实现与持久化实现走**同一份状态机**,「语义逐条 一致」不是靠两份代码互相校对,而是结构上只有一份。
并发介入:乐观并发 + 重试 ¶
两个副本拿着同一份快照同时介入:先提交者推进版本,后到者的提交 因 ErrStoreConflict 被拒——StorePlane 在内部重读快照、重判(此时通常 会看到「已经不在认领态 / 代次已前进」),而不是把旧视图的结论硬写下去。 这正是 MemPlane 的互斥锁在存储中立形态下的对偶:锁换成了版本锚。
留痕失败即整体失败 ¶
成功路径的留痕由 Store.Commit* 与状态写在同一次原子操作里:留痕失败 ⇒ 状态一字不动(issue #180)。被拒路径(目标不存在 / 代次过期 / 已裁决)没有状态变更,留痕直接追加;追加失败同样向上传播——「介入 返回 error ⇒ 可观测状态未变」这条对成功与失败路径都成立。
Index ¶
- Variables
- func IsKnownInterventionAction(a Action) bool
- type Action
- type Adjudication
- type Adjudicator
- type AuditEntry
- type Auditor
- type Authorizer
- type AuthorizerOf
- type EffectAuthority
- type EffectResolver
- type EffectSnapshot
- type EffectState
- type ForceRelease
- type ForceReleaseOf
- type Handler
- type HostPlane
- type MemAuditor
- type MemOption
- type MemPlane
- func (m *MemPlane) Claim(ctx context.Context, id taskboard.TaskID, agent taskboard.AgentID, ...) (taskboard.Task, error)
- func (m *MemPlane) Complete(ctx context.Context, id taskboard.TaskID, token string) error
- func (m *MemPlane) Release(ctx context.Context, id taskboard.TaskID, token string) error
- func (m *MemPlane) SeedEffect(key string, unsafe bool) error
- func (m *MemPlane) SeedRun(id RunID, status string, tasks []taskboard.Task) error
- type MemStore
- func (m *MemStore) Claim(_ context.Context, id taskboard.TaskID, agent taskboard.AgentID, ...) (taskboard.Task, error)
- func (m *MemStore) CommitEffect(ctx context.Context, expect Version, key string, next EffectState, ...) error
- func (m *MemStore) CommitRun(ctx context.Context, expect Version, id RunID, next RunState, entry AuditEntry) error
- func (m *MemStore) CommitTask(ctx context.Context, expect Version, next taskboard.Task, entry AuditEntry) error
- func (m *MemStore) Complete(_ context.Context, id taskboard.TaskID, token string) error
- func (m *MemStore) List(_ context.Context) ([]taskboard.Task, error)
- func (m *MemStore) Release(_ context.Context, id taskboard.TaskID, token string) error
- func (m *MemStore) Renew(_ context.Context, id taskboard.TaskID, token string, ...) (taskboard.Task, error)
- func (m *MemStore) SeedEffect(key string, unsafe bool) error
- func (m *MemStore) SeedRun(id RunID, status string, tasks []taskboard.Task) error
- func (m *MemStore) SnapshotEffect(_ context.Context, key string) (EffectSnapshot, error)
- func (m *MemStore) SnapshotRun(_ context.Context, id RunID) (RunSnapshot, error)
- func (m *MemStore) SnapshotTask(_ context.Context, id taskboard.TaskID) (TaskSnapshot, error)
- func (m *MemStore) UseClock(clock func() time.Time)
- type Plane
- type Releaser
- type RunID
- type RunQuerier
- type RunSnapshot
- type RunState
- type RunView
- type RunViewOf
- type SideEffectAuthority
- type Store
- type StorePlane
- func (p *StorePlane) Adjudicate(ctx context.Context, req Adjudication) error
- func (p *StorePlane) ForceRelease(ctx context.Context, req ForceRelease) error
- func (p *StorePlane) RunView(ctx context.Context, id RunID) (RunView, error)
- func (p *StorePlane) TaskView(ctx context.Context, id taskboard.TaskID) (TaskView, error)
- func (p *StorePlane) Terminate(ctx context.Context, req Termination) error
- type TaskAuthority
- type TaskQuerier
- type TaskSnapshot
- type TaskSource
- type TaskView
- type TaskViewOf
- type Termination
- type TerminationOf
- type Terminator
- type Verdict
- type Version
Constants ¶
This section is empty.
Variables ¶
var ( // ErrAuthorityMismatch 控制面存储与任务权威面不是同一份(装配期拒绝)。 ErrAuthorityMismatch = errors.New("controlplane: 控制面存储与任务权威面不同源(装配期拒绝)") // ErrNoEffectAuthority 权威控制面未装配副作用权威面:裁决无处落地(fail-closed)。 ErrNoEffectAuthority = errors.New("controlplane: 未装配副作用权威面(裁决必须落到副作用闸的同一份状态)") )
装配/裁决面的失败哨兵。
var ( // ErrNotFound 查询目标不存在(任务 / 运行)。 ErrNotFound = errors.New("controlplane: 目标不存在") // ErrInvalidRequest 介入请求不完整(Operator / Basis / 结论词表不合格)。 // 无归责不介入。 ErrInvalidRequest = errors.New("controlplane: 介入请求不完整——无归责不介入") // ErrNoAuditor 留痕面未装配。留痕是介入的硬前提:没有留痕的介入 // 无法回答「谁在什么时候依据什么改了运行状态」,一律拒绝(fail-closed)。 ErrNoAuditor = errors.New("controlplane: 留痕面未装配,拒绝介入") // ErrStaleRun 运行代次已前进:介入基于过期视图(Terminate 的乐观并发闸)。 ErrStaleRun = errors.New("controlplane: 运行代次已前进,介入基于过期视图") // ErrTerminalRun 运行已是终态:无需也无法终止(介入重试撞上它说明 // 第一次介入已生效)。 ErrTerminalRun = errors.New("controlplane: 运行已是终态,无需终止") // ErrUnknownRunStatus 运行状态不在已知词表内:无法判定是否终态(issue #334)。 // // 词表外状态可能是宿主自定义终态(如 "aborted")。按「非终态」放行会把 // 已终结的运行静默改写成 cancelled(fail-open)——与 checkpoint 的三态 // 判据方向相反。此类状态拒绝终止并回本哨兵,由宿主显式决定。 ErrUnknownRunStatus = errors.New("controlplane: 运行状态不在已知词表内,无法判定是否终态") )
错误哨兵(宿主判定走 errors.Is,不要各造一套)。
var ( // ErrNoStore 未装配 Store 就要构造 / 使用持久化 Plane。 // 修声明:装配 Store;不得静默退化成进程内状态(多副本下两份真相)。 ErrNoStore = errors.New("controlplane: 状态存储未装配") // ErrStoreConflict 版本锚不匹配:快照之后目标被另一个副本改过。 // **重试**:重读快照、重判后再提交;这不是「介入失败」,而是一次 // 乐观并发冲突(StorePlane 内部已自动重试,穷尽后才会把它交给调用方)。 ErrStoreConflict = errors.New("controlplane: 状态版本冲突(快照已过期)") )
控制面存储的装配/提交错误哨兵。
var ErrAlreadyExists = errors.New("controlplane: 目标已存在")
ErrAlreadyExists 目标已存在(Seed* 的重复登记;介入类动作不会报它—— 介入对已存在目标的语义是执行,不是登记)。
var ErrAuditorPanic = errors.New("controlplane: 留痕实现 panic(已隔离,状态未变)")
ErrAuditorPanic 留痕实现 panic 被内核隔离(issue #327):状态一字不动, 错误上抛给介入方。宿主留痕面(DB 落盘/审计服务)的异常不得把一次 「尚未提交」的介入变成进程级事故,也不得留下半条状态。
var ErrInvalidAudit = errors.New("controlplane: 留痕不完整——谁/动作/目标/依据缺一不可,动作须在介入词表内")
ErrInvalidAudit 留痕不完整,或动作不在介入词表内(谁 / 动作 / 目标 / 依据 缺一不可;查询动作与词表外动作同样拒收)。 MemAuditor 对不完整/词表外的留痕拒收;宿主实现应复用同一判据 (IsKnownInterventionAction)。
Functions ¶
func IsKnownInterventionAction ¶ added in v0.43.0
IsKnownInterventionAction 报告动作是否在介入词表内。
与 MemAuditor.Append 的接受集逐字一致;宿主实现留痕面时复用本判据即可。 查询动作 ActionQuery 与任何词表外动作都返回 false。
Types ¶
type Action ¶
type Action string
Action 介入/查询动作种类(留痕的 Action 字段;httpapi 鉴权钩子的判定对象)。
func AllInterventionActions ¶ added in v0.43.0
func AllInterventionActions() []Action
AllInterventionActions 返回全部介入动作(排序后的副本)。
这是**留痕面**的词表,不是 Action* 常量的全集:ActionQuery(查询)不在 其中——查询不改变运行状态,不是一次介入。宿主实现 Auditor 时应以本函数 为准,不要手抄 Action* 常量(那份含 query,比留痕面宽)。
type Adjudication ¶
type Adjudication struct {
// EffectKey 副作用幂等键(sideeffect.Action.Key;宿主映射)。
EffectKey string
// Verdict 裁决结论(词表见 Verdict)。
Verdict Verdict
// ForceRetryable 与 sideeffect.Resolution.ForceRetryable 同口径:
// 不可重试(Unsafe)的动作凭「未生效」的裁决不自动开门——重新打开
// 施加的门必须是显式决策,不能是「对账流程跑完了」的自然结果。
ForceRetryable bool
// Operator 谁在介入(留痕必填)。
Operator string
// Basis 依据什么结论(留痕必填:通常是「查了下游的什么、看到什么」)。
Basis string
}
Adjudication 裁决未知结果(sideeffect.Reconcile 同口径)。
契约:裁决凭下游事实,不凭持有权 ¶
裁决**不校验栅栏 / 令牌**:它的依据是宿主查到的下游事实——原持有者可能 已经死亡、租约早已过期,而对账恰恰要在这种情况下进行(sideeffect 同一条契约)。同一 Key 的多次裁决**先到者为准**:结论已定后再来裁决 → sideeffect.ErrNotUncertain(不覆盖先到的结论)。
type Adjudicator ¶ added in v0.39.0
type Adjudicator interface {
Adjudicate(ctx context.Context, req Adjudication) error
}
Adjudicator 裁决未知结果的窄契约(效果键是 sideeffect 的字符串契约, 与任务 / 租户类型无关,故可直接复用原生 Adjudication)。
type AuditEntry ¶
type AuditEntry struct {
// At 留痕时刻。由**留痕实现侧**补(实现收到零值时取自己的当前时刻)——
// 介入方的时钟不可信,留痕时刻以实现侧为准。
At time.Time
// Operator 谁在介入(必填)。
Operator string
// Action 动作种类(必填)。留痕面只接受 AllInterventionActions() 内的
// 介入动作;查询动作 ActionQuery 不经留痕(它不是一次介入),传给
// MemAuditor 会被 ErrInvalidAudit 拒绝。
Action Action
// Target 目标(任务 id / 效果键 / run id,必填)。
Target string
// Basis 依据什么结论(必填)。
Basis string
// Detail 结果摘要(可空:成功 / 被拒原因)。
Detail string
}
AuditEntry 一条人工介入留痕:谁、什么时候、做了什么、对谁、依据什么、结果如何。
type Auditor ¶
type Auditor interface {
// Append 追加一条介入留痕。
Append(ctx context.Context, e AuditEntry) error
// Entries 按目标取留痕(查询面)。target 为空取全部;按追加序返回。
Entries(ctx context.Context, target string) ([]AuditEntry, error)
}
Auditor 留痕契约:**只增不改**(append-only)。
实现方必须保证:
- Append 成功后条目永不修改、永不删除(留痕可被追加,不可被改写—— 可改写的留痕不是留痕);
- 收到零值 At 时补实现侧当前时刻;
- 对缺 Operator / Action / Target / Basis 的条目拒绝(ErrInvalidAudit), 不静默补空;**词表外动作同样拒绝**——宿主用 IsKnownInterventionAction 复用与内核参考实现逐字相同的接受集,不要 自己手抄一份。
调用面(issue #327) ¶
Append 在**状态锁之外**被调用:MemStore 在 commitMu(写者串行)下、m.mu 外 调用;StorePlane 的拒绝路径本来就无锁。宿主实现因此可以安全回查 MemStore 的 Snapshot*(查询面不经 commitMu),但有两条硬约束:
- **不得回调 Commit***:会重入 commitMu(同 goroutine 死锁);
- **不得阻塞**:提交序列串行等待它(查询面不受影响,但写者会排队)。
实现 panic 由内核隔离为上抛的 ErrAuditorPanic,状态一字不动。
持久化形态归宿主(表 / 文件 / 只读副本皆可);MemAuditor 是进程内参考实现。
type Authorizer ¶
type Authorizer interface {
Authorize(r *http.Request, act Action, target string) (tenant.Context, error)
}
Authorizer 鉴权钩子(宿主实现):解析请求 → 判定动作是否可执行 → 返回注入 request context 的租户/权限上下文。返回错误 ⇒ 403,不触达 Plane。
type AuthorizerOf ¶ added in v0.39.0
type AuthorizerOf[C any] interface { Authorize(r *http.Request, act Action, target string) (C, error) }
AuthorizerOf 鉴权钩子的宿主类型版本:宿主返回自己的租户 / 权限上下文 C, 如何把它注入请求 context 由宿主的装配层决定(controlplane 不解释 C)。
使用本包 Handler 的宿主实现 Authorizer(返回 tenant.Context); 租户体系不是 tenant 的宿主、或自建 HTTP 适配面的宿主实现本接口。
type EffectAuthority ¶ added in v0.43.0
type EffectAuthority interface {
// ResolveUncertain 裁决一个「结果未知」的副作用键。
//
// applied=true ⇒ 记为已完成;false ⇒ 确认未生效(Unsafe 动作仍受
// ForceRetryable 约束)。不处于未知态 ⇒ sideeffect.ErrNotUncertain;
// Unsafe 且未显式放行 ⇒ sideeffect.ErrUnsafeNotRetryable。
ResolveUncertain(ctx context.Context, key string, applied, forceRetryable bool, reason string) error
}
EffectAuthority 副作用裁决的权威面(issue #268)。
实现必须把结论落到**副作用闸读取的同一份状态**(sideeffect.Store. ResolveUncertain);控制面据此观察「同一份」而不是再写一个投影。
type EffectResolver ¶ added in v0.43.0
type EffectResolver interface {
ResolveUncertain(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
}
EffectResolver sideeffect.Store 的裁决子集(structural:完整 Store 自动满足)。
type EffectSnapshot ¶ added in v0.39.0
type EffectSnapshot struct {
// Version 快照版本(CommitEffect 的 expect)。
Version Version
// Key 效果幂等键。
Key string
// Effect 当前裁决账。
Effect EffectState
}
EffectSnapshot 效果键快照(Adjudicate 的存储输入)。
type EffectState ¶ added in v0.39.0
type EffectState struct {
// Uncertain 结果是否仍未知(true = 尚未裁决)。
Uncertain bool
// Unsafe 动作是否声明为不可重试(未生效裁决不自动开门)。
Unsafe bool
// Resolved 已裁决的结论(Uncertain=false 时有效)。
Resolved Verdict
}
EffectState 效果键的裁决账。
type ForceRelease ¶
type ForceRelease struct {
// TaskID 要释放的任务。
TaskID taskboard.TaskID
// Operator 谁在介入(留痕必填)。
Operator string
// Basis 依据什么结论(留痕必填:证据 / 判据 / 单号,宿主词表)。
Basis string
}
ForceRelease 强制释放任务认领。
契约:不是绕过闸,是经闸换持有者 ¶
实现必须按「接管」处理:被释放任务的旧令牌**当场作废**,任务回到可认领 态。于是旧持有者(崩溃的进程、失联的 worker)迟到的 Complete / Renew 一切动作都凭 taskboard.ErrLeaseLost 被拒;下一次认领铸造的接管代次 (taskboard.Fence)严格大于被释放的那一代——宿主的下游资源凭代次比较 拒收被释放者的迟到写入(与 taskboard / sideeffect 的栅栏同一纪律)。
危险实现(契约禁止):只改状态不清租约——旧令牌仍然匹配,幽灵持有者的 迟到提交会照常落账。
对不在认领态的任务强释 → 包装 taskboard.ErrLeaseLost 的错误(该任务 的租约已经不在了;介入重试撞上它说明第一次介入已生效)。
func (ForceRelease) Validate ¶
func (r ForceRelease) Validate() error
Validate 介入请求的留痕完整性判定(Operator 与 Basis 必填——无归责不介入)。
type ForceReleaseOf ¶ added in v0.39.0
type ForceReleaseOf[ID comparable] struct { // TaskID 要释放的任务(宿主类型)。 TaskID ID // Operator 谁在介入(留痕必填)。 Operator string // Basis 依据什么结论(留痕必填,宿主词表)。 Basis string }
ForceReleaseOf 强制释放任务认领(目标 ID 用宿主的类型)。
契约与 ForceRelease 相同:不是绕过闸,是经闸换持有者(旧令牌当场作废、 下一次认领铸造严格更大的代次)。
func (ForceReleaseOf[ID]) Validate ¶ added in v0.39.0
func (r ForceReleaseOf[ID]) Validate() error
Validate 留痕完整性判定(目标按宿主 ID 类型的零值判空)。
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler 控制面的 JSON 适配面。经 NewHandler 构造,直接挂到任意 http.Server。
func NewHandler ¶
func NewHandler(p Plane, a Authorizer) *Handler
NewHandler 构造适配面。auth 可为 nil——此时全部请求 401(见包内 httpapi 头注:控制面不开无鉴权的口子)。
type HostPlane ¶ added in v0.39.0
type HostPlane[TID comparable, RID comparable, T any, P any] interface { TaskQuerier[TID, T, P] RunQuerier[RID, T, P] Releaser[TID] Adjudicator Terminator[RID] }
HostPlane 控制面的宿主类型契约:查询 + 三类介入,类型全部由宿主决定。
类型参数:TID 任务标识 / RID 运行标识(comparable),T 任务快照, P 不变量条目。
租户上下文不在签名里:机制间经 context.Context 传递(tenant.WithContext 是内核的参考载体)。宿主自有租户类型在自己的实现里从 ctx 取用并判定; 鉴权钩子的宿主类型版本见 AuthorizerOf。
type MemAuditor ¶
type MemAuditor struct {
// contains filtered or unexported fields
}
MemAuditor 进程内参考留痕面。零值可用,并发安全。
func (*MemAuditor) Append ¶
func (a *MemAuditor) Append(_ context.Context, e AuditEntry) error
Append 追加留痕(先判完整性与动作词表,再补时刻,再落账)。
func (*MemAuditor) Entries ¶
func (a *MemAuditor) Entries(_ context.Context, target string) ([]AuditEntry, error)
Entries 按目标取留痕(target 空 = 全部;按追加序)。 返回的是拷贝:调用方改写条目不影响留痕面(只增不改的可观测面同样只读)。
type MemOption ¶ added in v0.39.0
type MemOption func(*memConfig)
MemOption MemPlane / StorePlane 的装配选项。
func AllowAnonymousRead ¶ added in v0.39.0
AllowAnonymousRead 显式放开读路径的匿名访问(TaskView/RunView 不再做 tenant.Require)。**缺省不放行**——控制面读路径与写路径共用同一道 fail-closed 闸(issue #197):宿主 Authorizer 实现有 bug(对任何请求 返回零值 tenant.Context + nil)时,写路径被 tenant.Require 拦下、 读路径若不设闸就成了「同样的鉴权钩子、同样的错误,只有读放行」的口子。
这是给「健康检查式只读」场景的**显式**出口:装配时写明,装配期可见, 不许静默缺省开。开了它之后读路径的可归责性由宿主的 Authorizer 独自 承担——内核不再有第二道闸。
type MemPlane ¶
type MemPlane struct {
*StorePlane
// contains filtered or unexported fields
}
MemPlane 进程内参考实现。经 NewMemPlane 构造;并发安全。
判定逻辑来自 StorePlane(与持久化 Plane 同一份),状态在 MemStore。
func NewMemPlane ¶
NewMemPlane 构造参考实现。aud 可为 nil——留痕面缺位时介入一律拒绝 (ErrNoAuditor),这正是契约要演示的 fail-closed 形态。 opts 可变参装配选项(见 MemOption;缺省全部 fail-closed)。
func (*MemPlane) Claim ¶
func (m *MemPlane) Claim(ctx context.Context, id taskboard.TaskID, agent taskboard.AgentID, ttl time.Duration) (taskboard.Task, error)
Claim 运行时侧认领(铸造令牌与接管代次)。
func (*MemPlane) SeedEffect ¶
SeedEffect 登记一个处于「结果未知」态的副作用键。
type MemStore ¶ added in v0.39.0
type MemStore struct {
// contains filtered or unexported fields
}
MemStore Store 的进程内参考实现。经 NewMemStore 构造;零值可用; 并发安全。aud 为 nil 时所有 Commit 返回 ErrNoAuditor(留痕面缺位 ⇒ 介入一律拒绝——与 MemPlane 的 fail-closed 口径一致)。
func NewMemStore ¶ added in v0.39.0
NewMemStore 构造参考实现。aud 可为 nil——留痕面缺位时 Commit 一律 拒绝(ErrNoAuditor),这正是契约要演示的 fail-closed 形态。
func (*MemStore) Claim ¶ added in v0.39.0
func (m *MemStore) Claim(_ context.Context, id taskboard.TaskID, agent taskboard.AgentID, ttl time.Duration) (taskboard.Task, error)
Claim 运行时侧:认领(铸造令牌与接管代次,语义对齐 taskboard.Board.Claim ——被**活着**持有 ErrTaken / 终态 ErrTerminal / 依赖未完成 ErrBlocked / 状态不在词表内 ErrUnknownState)。
「仍被持有」必须同时看状态与租约存活(taskboard.LeaseHeld,issue #335): 只看 State == claimed 会让持有者崩溃后的任务永久不可接管——与 Board.Claim 的「被别人活着持有」契约及三个参考实现方向相反。
func (*MemStore) CommitEffect ¶ added in v0.39.0
func (m *MemStore) CommitEffect(ctx context.Context, expect Version, key string, next EffectState, entry AuditEntry) error
CommitEffect 原子提交裁决账 + 留痕。
func (*MemStore) CommitRun ¶ added in v0.39.0
func (m *MemStore) CommitRun(ctx context.Context, expect Version, id RunID, next RunState, entry AuditEntry) error
CommitRun 原子提交运行状态/代次 + 留痕。
func (*MemStore) CommitTask ¶ added in v0.39.0
func (m *MemStore) CommitTask(ctx context.Context, expect Version, next taskboard.Task, entry AuditEntry) error
CommitTask 原子提交任务状态 + 留痕。
func (*MemStore) Complete ¶ added in v0.39.0
Complete 运行时侧:凭 token 完成(旧令牌 / 非认领态 → taskboard.ErrLeaseLost)。
func (*MemStore) List ¶ added in v0.43.0
List 运行时侧:全部任务的一致快照(按 ID 排序,确定性输出)。
它是 taskboard.Board 的读面:参考实现也要能被共享契约套件(boardtest) 直接跑,判据才不是「为参考实现单独写一套」。
func (*MemStore) Release ¶ added in v0.39.0
Release 运行时侧:凭 token 归还认领(旧令牌 → taskboard.ErrLeaseLost)。
func (*MemStore) Renew ¶ added in v0.43.0
func (m *MemStore) Renew(_ context.Context, id taskboard.TaskID, token string, req taskboard.ClaimRequest) (taskboard.Task, error)
Renew 运行时侧:续期并确认持有资格(taskboard.RenewingBoard 的参考实现)。
契约与 taskboard.Renew 一致:令牌不匹配 / 租约已过期 ⇒ ErrLeaseLost, **不做任何修改**;续期不递增代次、不换令牌。
func (*MemStore) SeedEffect ¶ added in v0.39.0
SeedEffect 运行时侧:登记一个处于「结果未知」态的副作用键。 unsafe 对应 sideeffect 的 RetrySafetyUnsafe(未生效裁决不自动开门)。
func (*MemStore) SeedRun ¶ added in v0.39.0
SeedRun 运行时侧:建一个运行及其任务(taskID 全局唯一)。 status 为空取 contract.StatusCreated。重复 run / 重复任务 → ErrAlreadyExists。 先整单校验再落账:部分落账的 run 是半成品状态,视图会把「建了一半」 当成「建成了」。
func (*MemStore) SnapshotEffect ¶ added in v0.39.0
SnapshotEffect 效果键裁决账。
func (*MemStore) SnapshotRun ¶ added in v0.39.0
SnapshotRun 运行 + 全部任务(同一把锁内取,快照一致)。
func (*MemStore) SnapshotTask ¶ added in v0.39.0
SnapshotTask 任务 + 所属 run 的全部任务(同一把锁内取,快照一致)。
func (*MemStore) UseClock ¶ added in v0.43.0
UseClock 注入存储时钟(租约到期与 Until 推算都按它;nil 忽略)。
与 taskboard 的「TTL 由存储自己的时钟推算」同口径:跨进程时调用方的 时钟不可信,参考实现也必须能演示「到期由存储判定」。
接缝契约(issue #369) ¶
@seam: no-reentry no-blocking panic-caller
- **不得重入**:回调内不得再调用 Claim / Renew 等会读取存储时钟的写路径 (会在回调里递归调用自己)。只读回查(SnapshotTask 等)是安全的: 实现保证时钟在 m.mu + commitMu **之外**被调用(issue #367)。
- **不得阻塞**:回调必须立即返回;它位于认领/续期路径的入口,阻塞会拖住 整条写路径。
- **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。 时钟失读是装配/编程错误,应当响亮失败;需要隔离的宿主应在回调内 recover。
type Plane ¶
type Plane interface {
// TaskView 任务的运行状态视图(快照 + 该任务身上的不变量违反)。
// 上下文未注入租户信息 → tenant.ErrNoContext(fail-closed,除非实现
// 显式声明匿名只读);不存在 → ErrNotFound。
TaskView(ctx context.Context, id taskboard.TaskID) (TaskView, error)
// RunView 运行的状态视图(状态、代次、全部任务、全 run 不变量视图)。
// 租户 fail-closed 判据与 TaskView 相同;不存在 → ErrNotFound。
RunView(ctx context.Context, id RunID) (RunView, error)
// ForceRelease 强制释放任务认领(契约见 ForceRelease)。
ForceRelease(ctx context.Context, req ForceRelease) error
// Adjudicate 裁决未知结果(契约见 Adjudication)。
Adjudicate(ctx context.Context, req Adjudication) error
// Terminate 终止运行(契约见 Termination)。
Terminate(ctx context.Context, req Termination) error
}
Plane 控制面契约:查询 + 介入。存储中立——实现方是宿主。
本接口是 **taskboard 原生**的便利契约(任务 ID / 快照 / 不变量条目都直接用 taskboard 的类型)。宿主自有任务模型或租户体系时实现 HostPlane / AuthorizerOf(hostiface.go)——两条契约并列,判定纪律相同,只是类型解耦。
实现方必须保证(三条硬契约,缺一即破):
- 介入**走运行时的同一套判据**(令牌 / 代次 / 栅栏),不绕闸;
- 介入**留痕**:Auditor 缺位时一律拒绝(ErrNoAuditor),不允许 「先介入、留痕以后补」——补的留痕无法证明发生在动作之前;
- 介入请求**可归责**:Operator 与 Basis 必填(各请求的 Validate 判)。
查询面与介入面共用同一道租户 fail-closed 闸(issue #197):TaskView / RunView 对未注入租户上下文的请求同样返回 tenant.ErrNoContext——写路径 靠 tenant.Require 兜住了宿主 Authorizer 的 bug(对任何请求返回零值 Context + nil),读路径若不设闸,「同样的鉴权钩子、同样的错误,只有读 放行」就是控制面自己开的口子。确需匿名只读(健康检查式读取)的宿主在 实现里**显式**放开(参考实现经 AllowAnonymousRead)并在装配期记录, 不许缺省放行。
type Releaser ¶ added in v0.39.0
type Releaser[ID comparable] interface { ForceRelease(ctx context.Context, req ForceReleaseOf[ID]) error }
Releaser 强制释放的窄契约(目标 ID 用宿主的类型)。
type RunQuerier ¶ added in v0.39.0
type RunQuerier[RID comparable, T any, P any] interface { RunView(ctx context.Context, id RID) (RunViewOf[RID, T, P], error) }
RunQuerier 运行视图查询的窄契约。
type RunSnapshot ¶ added in v0.39.0
type RunSnapshot struct {
// Version 快照版本(CommitRun 的 expect)。
Version Version
// RunID 运行标识。
RunID RunID
// Status 运行状态。
Status string
// Gen 运行代次。
Gen uint64
// Tasks 该 run 的全部任务(按任务 id 排序)。
Tasks []taskboard.Task
}
RunSnapshot 运行快照(RunView 的存储输入)。
type RunState ¶ added in v0.39.0
type RunState struct {
// Status 新状态。
Status string
// Gen 新代次。
Gen uint64
// TaskIDs 运行的任务集合(nil = 保持原集合不变)。
TaskIDs []taskboard.TaskID
}
RunState 运行记录的变更形态(CommitRun 的写入面)。
type RunView ¶
type RunView struct {
// RunID 运行标识。
RunID RunID
// Status 运行状态。取值建议用 contract 的状态常量(内核不解释词表;
// 终态词表与 contract 保持一致,宿主自定义状态自行登记)。
Status string
// Gen 运行代次:运行级介入的乐观并发判据。Terminate 携带的
// ExpectedGen 必须等于它,不等即 ErrStaleRun——介入方先查视图再介入,
// 两次介入之间状态若已前进,旧视图上的动作必须重查。
Gen uint64
// Tasks 该 run 的全部任务快照(按任务 id 排序,确定性输出)。
Tasks []taskboard.Task
// Problems 全 run 的不变量视图(taskboard.Check)。
Problems []taskboard.Problem
}
RunView 运行的状态视图。
type RunViewOf ¶ added in v0.39.0
type RunViewOf[RID comparable, T any, P any] struct { // RunID 运行标识(宿主的类型)。 RunID RID // Status 运行状态(词表归宿主;与 contract 对齐与否由宿主决定)。 Status string // Gen 运行代次:Terminate 的乐观并发判据(ExpectedGen 必须等于它)。 Gen uint64 // Tasks 该 run 的全部任务快照(实现应按任务 id 排序,确定性输出)。 Tasks []T // Problems 全 run 的不变量视图(宿主自己的判据产出)。 Problems []P }
RunViewOf 运行视图的宿主类型版本。
type SideEffectAuthority ¶ added in v0.43.0
type SideEffectAuthority struct {
Store EffectResolver
ActionOf func(key string) (sideeffect.Action, bool)
}
SideEffectAuthority 用 sideeffect.Store 实现 EffectAuthority 的参考适配器。
ActionOf 由宿主提供:把控制面的 EffectKey 映射成 sideeffect.Action (Resource / Payload / RetrySafety 是宿主词表,内核不解释)。
func (*SideEffectAuthority) ResolveUncertain ¶ added in v0.43.0
func (a *SideEffectAuthority) ResolveUncertain(ctx context.Context, key string, applied, forceRetryable bool, reason string) error
ResolveUncertain 实现 EffectAuthority。
type Store ¶ added in v0.39.0
type Store interface {
// SnapshotTask 读任务及其所属 run 的全部任务(一致快照)。
SnapshotTask(ctx context.Context, id taskboard.TaskID) (TaskSnapshot, error)
// SnapshotRun 读运行及其全部任务(一致快照)。
SnapshotRun(ctx context.Context, id RunID) (RunSnapshot, error)
// SnapshotEffect 读效果键裁决账。
SnapshotEffect(ctx context.Context, key string) (EffectSnapshot, error)
// CommitTask 原子提交任务状态 + 留痕(expect 见类型级契约)。
CommitTask(ctx context.Context, expect Version, next taskboard.Task, entry AuditEntry) error
// CommitRun 原子提交运行状态/代次 + 留痕。
CommitRun(ctx context.Context, expect Version, id RunID, next RunState, entry AuditEntry) error
// CommitEffect 原子提交裁决账 + 留痕。
CommitEffect(ctx context.Context, expect Version, key string, next EffectState, entry AuditEntry) error
}
Store 控制面状态的存储中立契约。
实现方必须保证(三条硬契约见文件头):
- 三个 Snapshot* 返回**一致快照**;目标不存在 ⇒ ErrNotFound;
- 三个 Commit* 在 expect 与当前版本不符时返回 ErrStoreConflict 且 不写任何状态(**不**追加留痕——失败的 CAS 不是一次介入);
- Commit* 把留痕与状态写在**同一次原子操作**里:留痕面缺位 ⇒ ErrNoAuditor;留痕写入失败 ⇒ 状态不变、错误原样传出;
- 并发安全:多个 StorePlane 实例共享同一 Store 时,介入必须按版本 锚串行化(后到者取新快照重判)。
参考实现 MemStore 见 memstore.go;跨进程实现把三个 Commit 落到数据库 事务(状态行 + 审计行同一事务)或 etcd/Redis 的条件事务上即可。
type StorePlane ¶ added in v0.39.0
type StorePlane struct {
// contains filtered or unexported fields
}
StorePlane 基于 Store 的 Plane 实现:查询 + 三类介入。
两个构造器对应两种装配形态:
- NewStorePlane:任务/运行/效果键全部走 Store(单进程参考实现或与 运行时同源的持久化 Store;同源与否由宿主保证);
- NewAuthoritativeStorePlane:强制释放走运行时的 taskboard.Board、 裁决走副作用闸(sideeffect.Store)的同一份状态——结构上不构造第二份 可写任务/效果状态(issue #268)。
多个 StorePlane 实例共享同一个 Store 即多副本部署的替身(跨实例可见、 代次单调、冲突串行化);并发安全与否取决于 Store 实现的并发契约。
func NewAuthoritativeStorePlane ¶ added in v0.43.0
func NewAuthoritativeStorePlane(store Store, aud Auditor, tasks TaskAuthority, effects EffectAuthority, opts ...MemOption) (*StorePlane, error)
NewAuthoritativeStorePlane 构造任务/副作用权威统一的控制面(issue #268)。
tasks 必填且必须与运行时同一份 taskboard.Board;effects 缺失时裁决 fail-closed(ErrNoEffectAuthority)。store 只提供运行状态(SnapshotRun/ CommitRun 等)——本实现**不调用** store 的任务/效果提交面,结构上不存在 第二份可写任务状态或效果投影。
func NewStorePlane ¶ added in v0.39.0
func NewStorePlane(store Store, aud Auditor, opts ...MemOption) (*StorePlane, error)
NewStorePlane 构造持久化控制面。
store 为 nil ⇒ ErrNoStore(显式失败,不静默退化成进程内状态); aud 为 nil ⇒ 介入一律 ErrNoAuditor(查询面仍可用)。
aud 必须与 Store 的留痕落点是**同一本账**:成功路径的留痕由 Store.Commit* 与状态同事务写入,被拒路径(目标不存在 / 代次过期 / 已裁决)由 StorePlane 直接 Append——两个账会让「谁在什么时候依据什么 介入过」在成功与失败两类记录之间分裂。
func (*StorePlane) Adjudicate ¶ added in v0.39.0
func (p *StorePlane) Adjudicate(ctx context.Context, req Adjudication) error
Adjudicate 实现 Plane:裁决未知结果(契约见 Adjudication 请求类型)。
func (*StorePlane) ForceRelease ¶ added in v0.39.0
func (p *StorePlane) ForceRelease(ctx context.Context, req ForceRelease) error
ForceRelease 实现 Plane:经闸换持有者(契约见 ForceRelease 请求类型)。
func (*StorePlane) Terminate ¶ added in v0.39.0
func (p *StorePlane) Terminate(ctx context.Context, req Termination) error
Terminate 实现 Plane:凭运行代次终止(契约见 Termination 请求类型)。
type TaskAuthority ¶ added in v0.43.0
type TaskAuthority interface {
// List 权威任务快照(与运行时同一份)。
List(ctx context.Context) ([]taskboard.Task, error)
// Release 凭令牌把认领态原子迁移回 open(等同 taskboard.Board.Release)。
// 令牌不匹配/已被释放 ⇒ taskboard.ErrLeaseLost。
Release(ctx context.Context, id taskboard.TaskID, token string) error
}
TaskAuthority 任务状态的唯一权威写入面(issue #268)。
生产实现必须是运行时同一个 taskboard.Board:强制释放与 Worker 的 Renew/Complete 在同一处判定令牌与代次。taskboard.Board 本身满足本接口。
type TaskQuerier ¶ added in v0.39.0
type TaskQuerier[ID comparable, T any, P any] interface { TaskView(ctx context.Context, id ID) (TaskViewOf[T, P], error) }
TaskQuerier 任务视图查询的窄契约:宿主自有任务 ID 与快照 / 问题类型。
type TaskSnapshot ¶ added in v0.39.0
type TaskSnapshot struct {
// Version 快照版本(CommitTask 的 expect)。
Version Version
// RunID 任务所属运行。
RunID RunID
// Task 目标任务当前状态。
Task taskboard.Task
// RunTasks 所属 run 的全部任务(按任务 id 排序)。
//
// 不变量是 run 级判据(依赖与环要看全集),TaskView 只投影到目标任务;
// 只取一个任务会让「依赖未完成却被认领」这类问题在视图里隐身。
RunTasks []taskboard.Task
}
TaskSnapshot 任务快照(TaskView 的存储输入)。
type TaskSource ¶ added in v0.43.0
type TaskSource interface {
TaskSourceID() string
}
TaskSource 可选的装配期同源声明(issue #268)。
同一份任务表/同一个任务板必须返回相同的非空来源标识。Store 与 TaskAuthority 都实现它时,NewAuthoritativeStorePlane 要求两者相等。
type TaskView ¶
type TaskView struct {
// Task 任务快照(状态 / owner / 租约 / 代次——与运行时读到的同一份)。
Task taskboard.Task
// Problems 该任务身上的不变量违反(run 级 taskboard.Check 的投影;
// 空 = 干净)。控制面不止报状态,还报「这份状态是否自相矛盾」——
// 人工介入的结论(Basis)往往正是一条 Problem。
Problems []taskboard.Problem
}
TaskView 任务的运行状态视图。
type TaskViewOf ¶ added in v0.39.0
type TaskViewOf[T any, P any] struct { // Task 任务快照(与运行时读到的同一份)。 Task T // Problems 该任务身上的不变量违反(空 = 干净)。 Problems []P }
TaskViewOf 任务视图的宿主类型版本:任务快照 T 与不变量条目 P 由宿主决定。
type Termination ¶
type Termination struct {
// RunID 要终止的运行。
RunID RunID
// ExpectedGen 介入方视图里的运行代次(来自 RunView.Gen)。
ExpectedGen uint64
// Operator 谁在介入(留痕必填)。
Operator string
// Basis 依据什么结论(留痕必填)。
Basis string
}
Termination 终止运行。
契约:终止凭运行代次(乐观并发) ¶
ExpectedGen 必须等于当前 RunView.Gen:不等即 ErrStaleRun。终止本身就是 一次代次前进——两个介入者拿着同一份旧视图并发终止,先到者生效,后到者 凭代次被拒,不会出现「两次终止都以为自己终了这次运行」。终止是运行级 动作:任务租约的清理走 ForceRelease,两级判据不混。
type TerminationOf ¶ added in v0.39.0
type TerminationOf[RID comparable] struct { // RunID 要终止的运行(宿主类型)。 RunID RID // ExpectedGen 介入方视图里的运行代次(来自 RunViewOf.Gen)。 ExpectedGen uint64 // Operator 谁在介入(留痕必填)。 Operator string // Basis 依据什么结论(留痕必填)。 Basis string }
TerminationOf 终止运行(运行 ID 用宿主的类型)。
契约与 Termination 相同:终止凭运行代次(ExpectedGen 必须等于当前 RunView.Gen),终止本身是一次代次前进。
func (TerminationOf[RID]) Validate ¶ added in v0.39.0
func (r TerminationOf[RID]) Validate() error
Validate 留痕完整性判定(目标按宿主 ID 类型的零值判空)。
type Terminator ¶ added in v0.39.0
type Terminator[RID comparable] interface { Terminate(ctx context.Context, req TerminationOf[RID]) error }
Terminator 终止运行的窄契约(运行 ID 用宿主的类型)。