controlplane

package
v0.44.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

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;具体界面归宿主。本包给四样:

  1. Plane 契约(宿主包着自己的 taskboard.Board / sideeffect Runner / 运行状态存储实现它);
  2. 宿主自有类型的窄契约族(HostPlane / AuthorizerOf——泛型 ID 与宿主 快照/租户类型,纯接口零实现,见 hostiface.go;issue #238);
  3. 存储中立实现:Store 契约(任务/运行/效果键的一致快照 + 带版本锚的 原子提交,留痕与状态同事务)+ StorePlane(查询/介入的唯一一份判定 逻辑,多副本共享同一 Store 即跨实例可见);进程内参考实现见 MemStore / MemPlane / MemAuditor(判据怎么落的演示体,也是测试与 演练的最小运行时面);
  4. 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)。

介入端点全部是 POST + JSON body,而浏览器的跨站「简单请求」(表单的 urlencoded、fetch 的 text/plain)不触发 CORS 预检,可以直接打进来—— force-release / terminate / adjudicate 又都是不可幂等的介入。防线两层, 都在本包写死:

  1. Content-Type 闸(见 decode):介入请求只收 application/json,缺省与 其它类型一律 415——两种跨站简单请求形态都挡在 JSON 解码之前(Go 的 JSON 解码器本不看 Content-Type,不设闸它们会被当合法请求处理);
  2. 鉴权只认 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

Constants

This section is empty.

Variables

View Source
var (
	// ErrAuthorityMismatch 控制面存储与任务权威面不是同一份(装配期拒绝)。
	ErrAuthorityMismatch = errors.New("controlplane: 控制面存储与任务权威面不同源(装配期拒绝)")
	// ErrNoEffectAuthority 权威控制面未装配副作用权威面:裁决无处落地(fail-closed)。
	ErrNoEffectAuthority = errors.New("controlplane: 未装配副作用权威面(裁决必须落到副作用闸的同一份状态)")
)

装配/裁决面的失败哨兵。

View Source
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,不要各造一套)。

View Source
var (
	// ErrNoStore 未装配 Store 就要构造 / 使用持久化 Plane。
	// 修声明:装配 Store;不得静默退化成进程内状态(多副本下两份真相)。
	ErrNoStore = errors.New("controlplane: 状态存储未装配")
	// ErrStoreConflict 版本锚不匹配:快照之后目标被另一个副本改过。
	// **重试**:重读快照、重判后再提交;这不是「介入失败」,而是一次
	// 乐观并发冲突(StorePlane 内部已自动重试,穷尽后才会把它交给调用方)。
	ErrStoreConflict = errors.New("controlplane: 状态版本冲突(快照已过期)")
)

控制面存储的装配/提交错误哨兵。

View Source
var ErrAlreadyExists = errors.New("controlplane: 目标已存在")

ErrAlreadyExists 目标已存在(Seed* 的重复登记;介入类动作不会报它—— 介入对已存在目标的语义是执行,不是登记)。

View Source
var ErrAuditorPanic = errors.New("controlplane: 留痕实现 panic(已隔离,状态未变)")

ErrAuditorPanic 留痕实现 panic 被内核隔离(issue #327):状态一字不动, 错误上抛给介入方。宿主留痕面(DB 落盘/审计服务)的异常不得把一次 「尚未提交」的介入变成进程级事故,也不得留下半条状态。

View Source
var ErrInvalidAudit = errors.New("controlplane: 留痕不完整——谁/动作/目标/依据缺一不可,动作须在介入词表内")

ErrInvalidAudit 留痕不完整,或动作不在介入词表内(谁 / 动作 / 目标 / 依据 缺一不可;查询动作与词表外动作同样拒收)。 MemAuditor 对不完整/词表外的留痕拒收;宿主实现应复用同一判据 (IsKnownInterventionAction)。

Functions

func IsKnownInterventionAction added in v0.43.0

func IsKnownInterventionAction(a Action) bool

IsKnownInterventionAction 报告动作是否在介入词表内。

与 MemAuditor.Append 的接受集逐字一致;宿主实现留痕面时复用本判据即可。 查询动作 ActionQuery 与任何词表外动作都返回 false。

Types

type Action

type Action string

Action 介入/查询动作种类(留痕的 Action 字段;httpapi 鉴权钩子的判定对象)。

const (
	// ActionQuery 查询(运行状态视图 / 不变量视图)。
	ActionQuery Action = "query"
	// ActionForceRelease 强制释放。
	ActionForceRelease Action = "force_release"
	// ActionAdjudicate 裁决未知结果。
	ActionAdjudicate Action = "adjudicate"
	// ActionTerminate 终止运行。
	ActionTerminate Action = "terminate"
)

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(不覆盖先到的结论)。

func (Adjudication) Validate

func (r Adjudication) Validate() error

Validate 介入请求的留痕完整性 + 结论词表判定。

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 头注:控制面不开无鉴权的口子)。

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP 实现 http.Handler。

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

func AllowAnonymousRead(v bool) MemOption

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

func NewMemPlane(aud Auditor, opts ...MemOption) *MemPlane

NewMemPlane 构造参考实现。aud 可为 nil——留痕面缺位时介入一律拒绝 (ErrNoAuditor),这正是契约要演示的 fail-closed 形态。 opts 可变参装配选项(见 MemOption;缺省全部 fail-closed)。

func (*MemPlane) Claim

Claim 运行时侧认领(铸造令牌与接管代次)。

func (*MemPlane) Complete

func (m *MemPlane) Complete(ctx context.Context, id taskboard.TaskID, token string) error

Complete 凭 token 完成任务。

func (*MemPlane) Release

func (m *MemPlane) Release(ctx context.Context, id taskboard.TaskID, token string) error

Release 凭 token 归还认领。

func (*MemPlane) SeedEffect

func (m *MemPlane) SeedEffect(key string, unsafe bool) error

SeedEffect 登记一个处于「结果未知」态的副作用键。

func (*MemPlane) SeedRun

func (m *MemPlane) SeedRun(id RunID, status string, tasks []taskboard.Task) error

SeedRun 建一个运行及其任务。

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

func NewMemStore(aud Auditor) *MemStore

NewMemStore 构造参考实现。aud 可为 nil——留痕面缺位时 Commit 一律 拒绝(ErrNoAuditor),这正是契约要演示的 fail-closed 形态。

func (*MemStore) Claim added in v0.39.0

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

func (m *MemStore) Complete(_ context.Context, id taskboard.TaskID, token string) error

Complete 运行时侧:凭 token 完成(旧令牌 / 非认领态 → taskboard.ErrLeaseLost)。

func (*MemStore) List added in v0.43.0

func (m *MemStore) List(_ context.Context) ([]taskboard.Task, error)

List 运行时侧:全部任务的一致快照(按 ID 排序,确定性输出)。

它是 taskboard.Board 的读面:参考实现也要能被共享契约套件(boardtest) 直接跑,判据才不是「为参考实现单独写一套」。

func (*MemStore) Release added in v0.39.0

func (m *MemStore) Release(_ context.Context, id taskboard.TaskID, token string) error

Release 运行时侧:凭 token 归还认领(旧令牌 → taskboard.ErrLeaseLost)。

func (*MemStore) Renew added in v0.43.0

Renew 运行时侧:续期并确认持有资格(taskboard.RenewingBoard 的参考实现)。

契约与 taskboard.Renew 一致:令牌不匹配 / 租约已过期 ⇒ ErrLeaseLost, **不做任何修改**;续期不递增代次、不换令牌。

func (*MemStore) SeedEffect added in v0.39.0

func (m *MemStore) SeedEffect(key string, unsafe bool) error

SeedEffect 运行时侧:登记一个处于「结果未知」态的副作用键。 unsafe 对应 sideeffect 的 RetrySafetyUnsafe(未生效裁决不自动开门)。

func (*MemStore) SeedRun added in v0.39.0

func (m *MemStore) SeedRun(id RunID, status string, tasks []taskboard.Task) error

SeedRun 运行时侧:建一个运行及其任务(taskID 全局唯一)。 status 为空取 contract.StatusCreated。重复 run / 重复任务 → ErrAlreadyExists。 先整单校验再落账:部分落账的 run 是半成品状态,视图会把「建了一半」 当成「建成了」。

func (*MemStore) SnapshotEffect added in v0.39.0

func (m *MemStore) SnapshotEffect(_ context.Context, key string) (EffectSnapshot, error)

SnapshotEffect 效果键裁决账。

func (*MemStore) SnapshotRun added in v0.39.0

func (m *MemStore) SnapshotRun(_ context.Context, id RunID) (RunSnapshot, error)

SnapshotRun 运行 + 全部任务(同一把锁内取,快照一致)。

func (*MemStore) SnapshotTask added in v0.39.0

func (m *MemStore) SnapshotTask(_ context.Context, id taskboard.TaskID) (TaskSnapshot, error)

SnapshotTask 任务 + 所属 run 的全部任务(同一把锁内取,快照一致)。

func (*MemStore) UseClock added in v0.43.0

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

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 RunID

type RunID string

RunID 运行标识(一轮编排;宿主生成,与 contract.RunContext.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) RunView added in v0.39.0

func (p *StorePlane) RunView(ctx context.Context, id RunID) (RunView, error)

RunView 实现 Plane:运行视图(状态 / 代次 / 全部任务 / 全 run 不变量)。

func (*StorePlane) TaskView added in v0.39.0

func (p *StorePlane) TaskView(ctx context.Context, id taskboard.TaskID) (TaskView, error)

TaskView 实现 Plane:任务视图 + run 级不变量在该任务上的投影。

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,两级判据不混。

func (Termination) Validate

func (r Termination) Validate() error

Validate 介入请求的留痕完整性判定。

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 用宿主的类型)。

type Verdict

type Verdict string

Verdict 对「结果未知」副作用的裁决结论(与 sideeffect.Resolution 同口径)。

const (
	// VerdictApplied 已生效:Key 记为完成并留存结果,之后同一 Key 的执行
	// 拿回这份结果(重放)。
	VerdictApplied Verdict = "applied"
	// VerdictNotApplied 未生效:清除未知标记,该 Key 重新可被执行。
	VerdictNotApplied Verdict = "not_applied"
)

type Version added in v0.39.0

type Version uint64

Version 控制面记录的版本锚:每次成功提交推进(不复用、不回退)。

实现可以按记录维护,也可以维护一个全局修订号——只要满足 「快照之后目标被改过 ⇒ 版本不匹配」。参考实现用全局修订号(简单且 正确:多副本下同一时刻只有一个提交能落,假冲突由 StorePlane 重试消化)。

Jump to

Keyboard shortcuts

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