ticket

package
v0.47.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: 5 Imported by: 0

Documentation

Overview

backend.go —— 票据状态存储接缝(issue #145 多副本部署)。

为什么要把状态抽出来

原实现把判定与状态焊在一起(mu + map):签发/消费的判定语义正确, 但状态只活在本进程里——多副本宿主在副本 A 签发的票据,副本 B 消费时 找不到,一次性短时授权的防重放语义跨副本失效。抽成 Backend 之后: **判定逻辑(TTL、单次消费、容量策略的调用时机)留在 Store,跨进程状态 由宿主接 DB / 协调后端**——与 sideeffect.Acquire「判定归包内、原子性归 存储」同一条分工。

跨进程实现的硬要求(原子性契约)

  • **Take 必须原子**:多副本并发 Take 同一 id,恰好一个返回 ok=true。 DB 形态 = `DELETE ... RETURNING`(或等价事务);Redis 形态 = Lua。 判定「过期则失败」也在同一次取出里完成——先查后删的两步形态会把 「两个副本同时消费」的窗口重新打开,正是本包要防的那件事。
  • **Put 写入即可见**,同 id 覆盖(与进程内语义一致;id 是 192 bit 随机,碰撞不在现实里)。
  • GC / Len 是清理与观测面,一致性要求弱于 Take。

时间的真相只有存储一个(issue #186)

**节点时钟不得参与过期判定。** 多副本部署下各节点时钟必然有偏移: 快 30s 的副本会把未过期票据判成过期(旧实现先删后判——这次误判同时 删掉了票,真正持有者随后消费失败且不可恢复);慢的副本则让过期票据 仍可重放。这不是「略有偏差」,是把「票据是否过期」的语义交给了一台 随时会漂的机器。

故时间权威在 **Backend**:

  • `Put(id, binding, ttl)` 按**存储时钟**落 expires_at,并返回该时刻 (Issue 原样返回给宿主,库里记的与宿主看到的是同一个时刻);
  • `Take(id)` / `GC()` 不带任何时间参数,过期比较**只能**用存储时钟。 接口层面根本没有接收节点时钟的入口——不是靠实现自觉忽略它。

实现形态:PostgreSQL → 事务内 `clock_timestamp()`(或 `now() + ttl` 在同一语句里落库并 RETURNING);Redis → Lua 脚本内 `TIME`; 进程内参考实现 → 构造时注入的时钟(`NewMemoryBackendWithClock`, 它就是单进程的「存储时钟」,也是过期语义可确定性测试的接缝)。 `examples/pgstore` 的「到期由存储时钟算」(#140/#194)是同一口径。

进程内参考实现

NewMemoryBackend:单进程成立,**不得上生产**(跨进程原子性它给不了)。 它的职责是把判定逻辑垫在契约之下,让契约可测——与 coord 的内存后端、 examples/pgstore 对 taskboard 的分工同口径(内核证契约,宿主接生产)。

Package ticket 一次性短时授权票据(机制面)。

生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。

这件事为什么要有个原语

宿主要把控制台、IM、长连接这类「先给个凭据、稍后凭凭据进来」的面暴露出去时, 绕不开三件事:**凭据短命**、**只能用一次**、**只能用于某一个用途**。 各宿主各写一套,于是每次都重犯同一种错:把**长期令牌塞进 query**—— 令牌会落进访问日志、代理日志、浏览器历史、Referer 头,于是「短时凭据」 名义上短时,实际是长期有效且到处留痕。

本包把机制面收成一处:**签发(Issue)/ 消费(Consume)/ 过期(TTL)/ 用途绑定**。

三条纪律

  1. **单次消费**:票据消费即作废(用过即焚)。同一 id 第二次消费**必然失败**—— 不是「尽量不重复」,是结构上不可能重复。

  2. **过期即失效**:消费时刻晚于过期时刻 ⇒ 失败。过期判定与消费判定**同一次 原子操作**(Backend.Take 内部;不要两处各判一次,两处判就会有一处漂)。 **时间真相只有存储一个**(issue #186):Put 按存储时钟落 expires_at, Take/GC 用存储时钟比较——节点时钟不得参与过期判定(多副本时钟偏移 会把「票据是否过期」变成「这台机器几点了」)。

  3. **机制与策略分离**:本包**不决定**谁能签、票据能干什么、过期多久—— 那是宿主的治理决策。本包只提供机制:宿主拿到 id 与过期时刻,自己决定 拿它做什么。绑定载荷(Binding)里的字段语义也归宿主解释。

边界

状态在 Backend 接缝之后(issue #145):缺省是进程内存储(重启即失效)—— 对「只活几十秒的票据」这是**正确**的默认,宁可让用户重取一次,也不要把 凭据持久化到磁盘(落盘即多一份要擦的痕迹)。多副本宿主实现 Backend 经 NewWithBackend 注入:判定逻辑(TTL 语义 / 单次消费 / 容量调用时机)留在 本包,跨进程原子性与**时间权威**归存储——原子性契约与「节点时钟不得参与 过期判定」见 backend.go 文件头(issue #186)。本包**不提供**分布式实现, 也不做任何集群语义(复制、选主、租约一概不认识)。

Index

Constants

View Source
const DefaultMaxEntries = 1024

DefaultMaxEntries 默认容量上限:票据空间有界,超出即**拒发**(报错)。

⭐ 为什么要有上限:票据是「发了就占一份内存」的凭据,若宿主无限制签发, 一次误用的批量签发就能把进程内存吃干。本包的立场是**满了就说满**, 而不是默默淘汰(默默淘汰会让宿主以为票据还在,实际已失效 ⇒ 表现为 「偶发地连不上」,极难查)。

⭐ 容量按**未过期张数**计(issue #208):签发路径在容量判定前回收过期 票据——被签发但从未被消费的票不再永久占容量,长期运行进程不会因累计 过期票而签发永久失败。未过期的票满了照样显式拒发(上面的立场不变)。

Variables

This section is empty.

Functions

This section is empty.

Types

type Backend added in v0.35.0

type Backend interface {
	// Put 写入一张未消费票据,expires_at 由**存储时钟** + ttl 落下,
	// 并返回该时刻(Issue 原样返回给宿主)。
	//
	// 容量策略由实现自判(内存参考实现满了报错,与旧实现「票据空间已满」
	// 同一拒发口径)。
	//
	// 签发路径(Store.Issue)在 Put 前先经 GC 回收过期票据(issue #208):
	// 实现看到的容量压力以未过期票据为主——实现自身的容量判据不必分辨
	// 过期与否(它拿到的 ttl 与存储时钟足以在落库时判,但容量口径归实现)。
	Put(id string, binding Binding, ttl time.Duration) (expiresAt time.Time, err error)
	// Take 原子取出并删除:不存在或已过期(**存储时钟**)⇒ ok=false。
	//
	// ⚠️ 过期票据**也已被删除**——与进程内旧实现「消费尝试顺手清过期」
	// 逐字一致(先删后判的顺序是语义的一部分,不是实现巧合)。时钟权威
	// 归存储之后,这一条不再有「误删尚未过期的票」的窗口。
	Take(id string) (Binding, bool, error)
	// GC 删除已过期票据(**存储时钟**),返回清理张数。
	GC() (int, error)
	// Len 返回现存票据数(含过期未清理的——它们只是不可消费,仍占空间)。
	Len() (int, error)
}

Backend 票据状态存储(并发安全;原子性契约见文件头)。

实现可以是进程内的(MemoryBackend)、SQL 的、Redis 的——本包只依赖 这四个操作的语义,不依赖它们怎么达成。**过期判定的时间权威在实现侧** (存储时钟,见文件头「时间的真相只有存储一个」):接口不接收调用方时间, 节点时钟因此没有进入判定面的路径。

func NewMemoryBackend added in v0.35.0

func NewMemoryBackend(maxSize int) Backend

NewMemoryBackend 构造进程内参考实现(maxSize <= 0 ⇒ DefaultMaxEntries)。

存储时钟取 time.Now;需要确定性过期语义(测试)用 NewMemoryBackendWithClock 注入时钟。

这是 Store 缺省构造(New)背后的实现;宿主的跨进程 Backend 由宿主 自己实现并经 NewWithBackend 注入。

func NewMemoryBackendWithClock added in v0.39.0

func NewMemoryBackendWithClock(maxSize int, now func() time.Time) Backend

NewMemoryBackendWithClock 构造进程内参考实现并注入**存储时钟**。

⭐ 为什么时钟在 Backend 而不是 Store:过期判定必须只有一个时间真相。 旧实现让调用方把 now 传进 Take/GC,多副本下「谁的时钟说了算」取决于 这次调用是谁发的——快时钟误杀、慢时钟放行重放。时钟注入到存储侧之后, 进程内参考实现与跨进程 DB 遵守同一条语义(DB 用存储时钟),测试也能 确定性地推进过期(不靠 sleep)。

**本实现不会在持有内部锁时调用该回调**(issue #317):now 在进入临界区 之前取值,回调里重入本包的 Put/Take/GC/Len 不会撞上不可重入的互斥锁。 宿主可以放心在时钟闭包里读票据数或其他本包接口。

接缝契约(issue #369)

@seam: no-reentry no-blocking panic-caller

  • **不得重入**:回调内不得再次触发会读取后端时钟的写路径(会递归); 只读回查是安全的(时钟在 b.mu 之外被调用,issue #317)。
  • **不得阻塞**:回调在每次过期判定前被调用,必须立即返回。
  • **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。

maxSize <= 0 ⇒ DefaultMaxEntries;now 为 nil ⇒ time.Now。

type Binding

type Binding struct {
	// Subject 主体标识(宿主自解释,例如某个身份)。
	Subject string
	// Purpose 用途标识(宿主自解释,例如某个端点或某个能力)。
	Purpose string
	// Target 目标标识(宿主自解释,例如某个会话或某个对象的引用)。
	Target string
}

Binding 票据携带的**用途绑定**(字段语义由宿主解释)。

本包只负责**原样携带与原样取回**,不解释、不校验、不推断。

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store 票据机制面:判定逻辑 + 状态接缝(Backend;进程内参考实现见 backend.go)。

零值不可用,用 New 构造。Store **没有时钟**(issue #186):过期判定的 时间真相在 Backend(存储时钟),节点侧没有任何时钟参与语义——不是 「传了但忽略」,是接口上没有这个入口。

func New

func New() *Store

New 构造票据存储(进程内参考实现,容量上限取 DefaultMaxEntries)。

func NewWithBackend added in v0.35.0

func NewWithBackend(b Backend) *Store

NewWithBackend 构造票据存储:判定逻辑在本包,状态在注入的 Backend。

多副本宿主用它接自己的跨进程存储(DB / 协调后端);Backend 的原子性契约 与时间权威见 backend.go 文件头(Take 必须原子——多副本并发消费同一张票 恰好一个赢;**过期判定只读存储时钟**)。 b 为 nil ⇒ 退化为进程内参考实现(DefaultMaxEntries)。

func NewWithClock

func NewWithClock(maxSize int, now func() time.Time) *Store

NewWithClock 构造**进程内**票据存储并注入**存储时钟**(缺省后端的时钟)。

⭐ 为什么要注入时钟:过期判定是本包的核心语义之一,若测试只能靠 sleep 等过期, 一则慢、二则把「等到了」当成了「判对了」——真把判定写反了,测试照样绿 (只是慢一点)。注入时钟 ⇒ 过期语义可以被**确定性**地测。

注入点在**后端**而不是 Store(issue #186):跨进程实现由宿主注入的 Backend 自带存储时钟,`now` 只影响本函数构造的进程内参考后端。

接缝契约(issue #369)

@seam: no-reentry no-blocking panic-caller

  • **不得重入**:回调内不得再次触发会读取后端时钟的写路径(会递归); 只读回查是安全的(时钟在参考后端的内部锁外被调用,issue #317)。
  • **不得阻塞**:回调在每次过期判定前被调用,必须立即返回。
  • **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。

maxSize <= 0 ⇒ 取 DefaultMaxEntries;now 为 nil ⇒ time.Now。

func (*Store) Consume

func (s *Store) Consume(id string) (Binding, bool)

Consume 消费一张票据:取出绑定载荷并**立即作废**。

⭐ 语义:未知 id ⇒ 失败;已过期 ⇒ 失败;已被消费过 ⇒ 失败(同一路径, 因为消费即删除,第二次根本找不到)。成功 ⇒ 返回绑定载荷。

过期与未知**不区分**(都返回 false):区分开等于给「枚举 id」开了一扇 能区分「存在但过期」的窗,而票据 id 是 192 bit 随机,枚举本来就不可能—— 但没必要的差别就不留。

过期判定由 Backend.Take 用**存储时钟**在同一次原子取出里完成(issue #186): 调用方不提供时间,节点时钟无法改写「这张票是否过期」。

Backend 故障 ⇒ 按消费失败处理(fail-closed:票没被取走,宿主侧表现为 「这次没通过」,重试即可;绝不放行一张没验成的票)。本包入口没有 ctx 可传,跨进程实现的超时/截止由实现内部管理。

func (*Store) GC

func (s *Store) GC() int

GC 清掉过期票据,返回清理张数(过期判定用 Backend 的存储时钟,issue #186)。

过期票据**已不可消费**(Consume 判过期即失败),但仍占着空间 ⇒ 需要有人 定期收。宿主可挂定时器调它;签发路径(Issue)签发前也会顺手调一次 (issue #208)——即使宿主从不主动 GC,过期票也不再永久占容量。 Backend 故障 ⇒ 返回 0(本轮没清成,下轮再试;清理是尽力面不是判定面)。

func (*Store) Issue

func (s *Store) Issue(b Binding, ttl time.Duration) (string, time.Time, error)

Issue 签发一张票据:返回**票据 id** 与**过期时刻**。

⭐ 过期时刻由**签发方给的 TTL** 决定(机制面不替宿主定策略),具体时刻 由**存储时钟**算(Backend.Put;issue #186)——返回值就是库里那个 expires_at,不是节点时钟算出的另一个版本。多副本下宿主拿到它做展示/ 传递时,与真正判定过期用的是同一个时刻。 随机源失败 ⇒ 显式报错(不降级成「可预测的 id」——票据 id 一旦可预测, 单次消费语义就没有意义了)。

容量已满 ⇒ 显式报错(见 DefaultMaxEntries 的说明)。

签发前**顺手回收过期票据**(issue #208):被签发但从未被消费的票(链接 没人点开)等不到 Consume/Take 来删它,若无人回收,累计满容量后 Put 恒报 「票据空间已满」⇒ 此后所有签发永久失败。回收走 Backend.GC(多副本宿主 注入的 Backend 同样生效);判定与 Take 同一把尺(存储时钟晚于过期时刻)。 回收是**尽力面**:GC 故障不拦签发,容量判定仍归 Backend(满了照样显式 拒发)——回收成功与否只决定「过期票还占不占地方」,不改变放行语义。

⚠️ 绑定载荷**零校验**(含零值 Binding{}——机制面不解释字段语义)。 零绑定票据消费成功后返回全空 Binding,消费方拿到「授权成立」却答不出 「授权给谁、干什么、对什么对象」,审计面同样无从追溯。多数宿主应改用 IssueStrict(签发前校验绑定完整性);确有「字段语义宿主自定义、允许留空」 的场景再用本函数。

func (*Store) IssueStrict

func (s *Store) IssueStrict(b Binding, ttl time.Duration) (string, time.Time, error)

IssueStrict 签发前校验**绑定完整性**:Binding 三字段(Subject/Purpose/ Target)任一为空 ⇒ 显式报错,不签发。

为什么默认建议走这里:空绑定不是策略,是**绑定不完整**——宿主策略无论 如何都没法在一张「无主体/无用途/无目标」的票据上做判定,而消费侧拿到的 是「授权成立 + 全空载荷」的假安全感(转用/误签发无从追溯)。与包内既有 防线同哲学:随机源失败显式报错、容量满显式拒发,语义层面的非法值同样 不静默放行。字段语义仍归宿主解释,本函数只校验「非空」这一完整性底线。

func (*Store) Len

func (s *Store) Len() int

Len 当前未消费票据数(过期未清理的也算——它们只是不可消费,仍占空间)。 Backend 故障 ⇒ 返回 0(观测面;容量判定在 Backend 内部,不依赖这里)。

Jump to

Keyboard shortcuts

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