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） 直接调核心，摘掉判据必红。
token.go —— 令牌铸造与「只认 token」的契约场景。
令牌由存储铸造（v0.33.0），释放/完成只认 token 不认内容。本文件的场景 钉四条：铸造、非持有者被拒、旧令牌重用被拒（ABA）、**跨任务与并发的 令牌复用被拒**（issue #97 新增的两条——各拿各的令牌的并发认领撞不出 「校验与写入分离」，必须让同一令牌的使用者正面相撞）。
Index ¶
Constants ¶
const DefaultClaimWorkers = 100
DefaultClaimWorkers 大规模并发认领档位的缺省 agent 数。
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ClockedBoard ¶ added in v0.33.0
type ClockedBoard interface {
taskboard.Board
// UseClock 指定存储实现读时钟的方式（通常是注入一个 func() time.Time）。
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 的假时钟。
Source Files