Documentation
¶
Overview ¶
Package boardtest @@Board@@ 的**共享契约测试套件**。
生命周期: Experimental(v0.33.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
宿主写完存储实现后跑一遍:违反哪条契约就红在哪一条,免得「各判一套、 漂移到没人发现为止」(与 @sidetest@ 同一范式)。
硬失败不静默跳过 ¶
显式接入套件 = 声明要满足契约。跳过等于把「没测过」伪装成「通过了」。 续期(@@taskboard.RenewingBoard@@)与种子(Seed)都是可选接口,但 **接入套件就必须实现**——套件对缺失硬失败,不降级、不跳过。
时钟 ¶
「租约过期可被接管」「续期把到期时刻推后」这些契约需要可控时钟,否则只能 靠 sleep(慢且 flaky)。套件提供 FakeClock;实现须通过 ClockedBoard 接口 暴露「用哪个时钟」,且**过期判定必须读这个时钟**(不是 time.Now)—— 否则套件的过期场景测的是真实时间,恒不触发,套件就成了一组空断言。 (与 @sidetest@ 的 ClockedStore 同一范式。)
并发规模(issue #97) ¶
「读-判-写不可分割」这条要求在 4 并发下几乎撞不出来。套件把并发认领的 规模做成可配置(Config.ClaimWorkers),缺省跑 **10 与 100** 两档—— 存储实现过 4 并发不算过套件。宿主按自己的生产量级调那一档。
renew.go —— 过期接管与租约续期的契约场景(issue #87)。
四条判据,两两成对:
- 过期接管后旧持有者提交被拒(迟到提交有判据可拒)↔ 长任务续期后可继续 持有(续期给出路);
- 接管代次严格递增(代次是真判据不是装饰)↔ 旧令牌续期被拒 (假续期延长的是别人的闸)。
每条场景的判据核心是返回 error 的 checkXxx——变异验证(见 boardtest_test.go) 直接调核心,摘掉判据必红。
tenant.go —— 租户作用域的契约场景(issue #195)。
它补的是哪一段 ¶
多租户此前只进了控制面的 fail-closed 判据:数据面的键空间与领取条件 没有任何租户维度,跨租户认领/覆盖在契约层不可判定。本文件的场景把 「租户进了存储键与领取条件」变成可跑断言:
- 跨租户任务**不可见、不可领**(List 里没有,Claim 报 ErrNotFound);
- 同 id 不同租户是两条互不相干的任务(互不覆盖);
- 跨租户并发认领互不干扰(各租户恰好一个赢家,他租户一个都领不到);
- 他租户令牌不能收场(Release/Complete/Renew 一律 ErrNotFound);
- 缺租户 fail-closed(与写路径 tenant.Require 同口径:ErrNoContext)。
接入方式 ¶
租户作用域是**显式声明**的能力:实现构造一个「所有操作从 ctx 取租户、 缺失即拒」的板,再用 RunTenant 跑本套件。单租户实现不接本套件不受影响 (默认路径零回归);声明支持却不隔离的实现会在下面每一条上红。
token.go —— 令牌铸造与「只认 token」的契约场景。
令牌由存储铸造(v0.33.0),释放/完成只认 token 不认内容。本文件的场景 钉四条:铸造、非持有者被拒、旧令牌重用被拒(ABA)、**跨任务与并发的 令牌复用被拒**(issue #97 新增的两条——各拿各的令牌的并发认领撞不出 「校验与写入分离」,必须让同一令牌的使用者正面相撞)。
Index ¶
Constants ¶
const DefaultClaimWorkers = 100
DefaultClaimWorkers 大规模并发认领档位的缺省 agent 数。
Variables ¶
This section is empty.
Functions ¶
func RunConfig ¶ added in v0.34.0
RunConfig 跑整套契约判据,并发规模可配置(issue #97)。
每个子测试独立调用 factory(各条例句互不污染)。
func RunTenant ¶ added in v0.39.0
func RunTenant(t *testing.T, factory TenantFactory)
RunTenant 跑租户隔离契约判据。
调用本函数 = 声明「本实现支持租户作用域」。套件对「声明了但不隔离」 硬失败,不降级、不跳过(与 Run 的纪律一致)。
Types ¶
type ClockedBoard ¶ added in v0.33.0
type ClockedBoard interface {
taskboard.Board
// UseClock 指定存储实现读时钟的方式(通常是注入一个 func() time.Time)。
//
// # 接缝契约(issue #369)
//
// @seam: no-reentry no-blocking panic-caller
//
// 实现方必须保证:注入的回调不在持有内部锁时被调用(不得重入);
// 回调必须立即返回(不得阻塞);panic 不由套件兜(panic-caller)。
UseClock(now func() time.Time)
}
ClockedBoard 实现须提供的能力:把时钟注入到存储实现里。
**为什么单独一个接口**:过期判定是存储实现内部的事(它自己知道 「租约还在不在」)。套件不能替它判,只能要求它**用可注入的时钟**。 没实现这个接口 → 套件硬失败(而不是跳过过期场景——跳过等于假绿)。
type Config ¶ added in v0.34.0
type Config struct {
// ClaimWorkers 大规模并发认领判据的 agent 数(零值 = DefaultClaimWorkers)。
//
// 套件固定另跑一档 10;本值是「生产量级」那一档,宿主按自己的并发量调
// ——存储只要过小规模并发就能过套件的时代结束了(issue #97)。
// 负值在套件启动时即报错:写错的配置要让人看到,不静默回落缺省。
ClaimWorkers int
}
Config 套件参数(零值 = 缺省档位)。
type Factory ¶ added in v0.33.0
type Factory func(t *testing.T, clock *FakeClock) ClockedBoard
Factory 构造被测存储实现。
factory 每个子测试调用一次,构造一份全新实现,并把套件的假时钟注入它。
type FakeClock ¶ added in v0.33.0
type FakeClock struct {
// contains filtered or unexported fields
}
FakeClock 套件提供的假时钟(并发安全;测试内手动推进)。
func NewFakeClock ¶ added in v0.33.0
func NewFakeClock() *FakeClock
NewFakeClock 创建起点为 2026-01-01T00:00:00Z 的假时钟。
type TenantFactory ¶ added in v0.39.0
type TenantFactory func(t *testing.T, clock *FakeClock) ClockedBoard
TenantFactory 构造**租户作用域**的被测实现。
与 Factory 同形:每个子测试一份全新实现 + 套件假时钟。区别是构造出的 板必须从 ctx 取租户(tenant.Context),缺失时对所有方法 fail-closed。