controlplane

package
v0.39.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

audit.go —— 介入留痕契约与进程内参考实现。

留痕是介入的硬前提,不是事后增强:没有留痕的介入无法回答「谁在什么时候 依据什么改了运行状态」,出问题时与「存储被绕过直接改」无法区分。 故契约层面 Auditor 缺位 ⇒ 介入一律拒绝(ErrNoAuditor),实现层面 MemAuditor 对不完整的留痕拒收——两层各挡一个方向。

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 (
	// 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: 运行已是终态,无需终止")
)

错误哨兵(宿主判定走 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 ErrInvalidAudit = errors.New("controlplane: 留痕不完整——谁/动作/目标/依据缺一不可")

ErrInvalidAudit 留痕不完整(谁 / 动作 / 目标 / 依据缺一不可)。 MemAuditor 对不完整的留痕拒收;宿主实现应复用同一判据。

Functions

This section is empty.

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"
)

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 动作种类(必填,词表见 Action* 常量)。
	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), 不静默补空。

持久化形态归宿主(表 / 文件 / 只读副本皆可);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 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)。

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) Release added in v0.39.0

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

Release 运行时侧:凭 token 归还认领(旧令牌 → taskboard.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 的全部任务(同一把锁内取,快照一致)。

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 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 实现:查询 + 三类介入。

多个 StorePlane 实例共享同一个 Store 即多副本部署的替身(跨实例可见、 代次单调、冲突串行化)。经 NewStorePlane 构造;并发安全与否取决于 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 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 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