Documentation
¶
Overview ¶
Package authz 提供双 token 的**状态面**原语(#119):撤销黑名单(token 级 / 用户级)与在线会话注册表(设备/会话维度登记、枚举、强踢),与 kitx/jwt 的 校验面(ParseTyped 等)组合消费——jwt 只管「令牌是不是我签的、过没过期」, 本包回答「这枚令牌还能不能用」「某用户在哪些设备在线」「如何把他踢下线」。
#119 的缺口:kitx/jwt pair.go 明文把撤销黑名单等有状态部分留在平台层,下游 (zeus 4 服务)只能手搓两份拷贝靠注释对齐哈希口径,漂移即强踢失效。本包把 「必须单点」的键空间/哈希约定收进库层:
- TokenHash 是键空间唯一产出口(sha256hex),黑名单/会话注册表的键全部 由此派生,跨服务不再各写一份;
- Revoker / SessionRegistry 接口化存储面(#119 建议形态):内存实现 MemRevoker / MemRegistry 随包交付(单实例进程内部署与测试替身双用), Redis 等持久实现由下游按同一契约落地。
#196 存储适配层:多实例下游不必再重写 400 行 Redis 会话索引——
- SessionStore 是编排层依赖的最小存储面(Get/SetNX/Del/SAdd/SRem/SMembers/ Expire/TTL,各方法语义与原子性/TTL 要求写在接口注释里);下游把 Redis 包成 10 来行适配器即可;
- StoreRegistry 是基于 SessionStore 的编排实现(注册冲突/refreshHash 唯一 挂载/Kick 三态/KickUser 聚合计数,键布局见类型注释),MemRegistry 自 #196 起也构建在它之上(MemSessionStore + StoreRegistry),不再维护第二套 索引实现;
- authz/authztest 是对外契约测试套件:下游把自己的 SessionStore 实现塞进 authztest.Run,即可覆盖原语语义与注册表行为(重复 ID、refreshHash 已挂载、 Kick 三态/拉黑命中、KickUser 聚合计数等)。kitx 自身用它回归 MemSessionStore。
撤销语义两层:
- token 级:Revoke(hash, remaining)——单枚令牌拉黑,条目 TTL=令牌剩余 寿命(过期自然出清,过期令牌本就被 exp 拒绝);
- 用户级:RevokeUser(userID, at)——截断点,at 之前签发的全部令牌判陈旧 (#121 改密陈旧吊销的落地口)。判定口径单点在 pwd.TokenStaleBefore (秒截断比较),本包复用之,两处比较不各写一份。
会话语义(SessionRegistry):Register 登记(TTL=refresh 剩余寿命)、 ListByUser 管理端枚举、Kick 单会话强踢(**双 hash 拉黑 + 删键**,原子认领 语义供 refresh 轮换防重放拍板)、KickUser 全会话强踢。编排层(kitx/auth) 在此之上交付签发尾段/轮换/登出/改密吊销的单点语义。
并发契约:MemRevoker / MemRegistry / MemSessionStore / StoreRegistry 全方法 并发安全。StoreRegistry 用 SetNX 操作锁串行同一会话 ID 的 Register 全程与 Kick 的读快照/代次复核删键临界区(拉黑调用在锁外;锁 TTL 30s,释放失败仅 记日志、TTL 自愈);内存实现不启动后台 goroutine——过期条目读判即视为不在, Sweep 可手动清扫。
Index ¶
- Variables
- func RevokeToken(ctx context.Context, r Revoker, token string, remaining time.Duration) error
- func RevokedToken(ctx context.Context, r Revoker, token string) (bool, error)
- func TokenHash(token string) string
- type MemRegistry
- type MemRegistryOption
- type MemRevoker
- func (m *MemRevoker) Revoke(ctx context.Context, hash string, remaining time.Duration) error
- func (m *MemRevoker) RevokeUser(ctx context.Context, userID string, at time.Time) error
- func (m *MemRevoker) Revoked(ctx context.Context, hash string) (bool, error)
- func (m *MemRevoker) RevokedUser(ctx context.Context, userID string, iat time.Time) (bool, error)
- func (m *MemRevoker) Sweep()
- type MemRevokerOption
- type MemSessionStore
- func (m *MemSessionStore) Del(ctx context.Context, key string) (bool, error)
- func (m *MemSessionStore) Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)
- func (m *MemSessionStore) Get(ctx context.Context, key string) (string, bool, error)
- func (m *MemSessionStore) SAdd(ctx context.Context, key, member string, ttl time.Duration) error
- func (m *MemSessionStore) SMembers(ctx context.Context, key string) ([]string, error)
- func (m *MemSessionStore) SRem(ctx context.Context, key, member string) error
- func (m *MemSessionStore) SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error)
- func (m *MemSessionStore) Sweep()
- func (m *MemSessionStore) TTL(ctx context.Context, key string) (time.Duration, bool, error)
- type MemSessionStoreOption
- type Revoker
- type Session
- type SessionRegistry
- type SessionStore
- type StoreRegistry
- func (r *StoreRegistry) GetByRefreshHash(ctx context.Context, refreshHash string) (Session, error)
- func (r *StoreRegistry) Kick(ctx context.Context, id string) (bool, error)
- func (r *StoreRegistry) KickUser(ctx context.Context, userID string) (int, error)
- func (r *StoreRegistry) ListByUser(ctx context.Context, userID string) ([]Session, error)
- func (r *StoreRegistry) Register(ctx context.Context, s Session, ttl time.Duration) error
- type StoreRegistryOption
Constants ¶
This section is empty.
Variables ¶
var ErrSessionNotFound = errors.New("authz: 会话不存在")
ErrSessionNotFound 表示会话不在登记表(未登记 / 已过期 / 已下线)。
Functions ¶
func RevokeToken ¶
RevokeToken 以原始令牌串登记撤销(Revoker.Revoke 的薄助手:内部经 TokenHash 落到键空间)。remaining 语义同 Revoker.Revoke。
func RevokedToken ¶
RevokedToken 以原始令牌串判定撤销(Revoker.Revoked 的薄助手)。
func TokenHash ¶
TokenHash 计算令牌哈希键:sha256(token) 的小写 hex(#119 建议形态)。
这是撤销黑名单/会话注册表键空间的**唯一产出口**:所有按令牌定位的键 (黑名单条目、会话 AccessHash/RefreshHash)都必须经本函数派生,下游不再 各写一份 sha256 口径(#119 下游实证:两份拷贝漂移即强踢失效)。 #208:哈希实现单源收编 pkg/encoding.Sha256Hex(逐行等价)——此前手写的 sha256.Sum256+hex.EncodeToString 正是「宣言靠注释对齐」的残留面;kitx 本就 依赖 pkg,单源落在 pkg,kitx 侧零 sha256 实现。 入参是完整令牌串而非 jti:绑定到具体令牌形态(同一 jti 的两个令牌串不同、 哈希不同,可分别吊销)。
Types ¶
type MemRegistry ¶
type MemRegistry struct {
*StoreRegistry
// contains filtered or unexported fields
}
MemRegistry 是 SessionRegistry 的内存实现:基于 MemSessionStore + StoreRegistry 编排层(#196 起不再维护第二套索引实现),与 MemRevoker 配对使用(Kick 的 双 hash 拉黑经构造注入的 Revoker 落地)。
定位与 MemRevoker 一致:单实例进程内形态 + 契约测试替身。不启动后台 goroutine——过期会话读判即视为不在,Sweep 可手动回收。
func NewMemRegistry ¶
func NewMemRegistry(rev Revoker, opts ...MemRegistryOption) *MemRegistry
NewMemRegistry 构造内存会话注册表。rev 是 Kick/KickUser 双 hash 拉黑的 落地口,必须非 nil——强踢无拉黑等于假强踢(#65 同款零值透传纪律,构造期 fail-fast panic)。
func (*MemRegistry) Sweep ¶
func (m *MemRegistry) Sweep()
Sweep 回收过期登记(读路径已把过期会话视为不在,Sweep 只影响内存占用)。
type MemRegistryOption ¶
type MemRegistryOption func(*MemRegistry)
MemRegistryOption 是 NewMemRegistry 的函数选项。
func WithRegistryClock ¶
func WithRegistryClock(f func() time.Time) MemRegistryOption
WithRegistryClock 注入 MemRegistry 时钟(f 为 nil 直接 panic,WithRevokerClock 同款纪律)。时钟同时用于内存 store 的 TTL 判定。
type MemRevoker ¶
type MemRevoker struct {
// contains filtered or unexported fields
}
MemRevoker 是 Revoker 的内存实现:并发安全(mutex 保护),零第三方依赖。
定位:单实例进程内部署的内存形态,兼作契约测试替身(#119 建议形态的 MapRevoker 角色)。持久形态(Redis 等)由下游按 Revoker 契约落地——键前缀 可配、条目 TTL 语义与本实现一致。
生命周期:不启动后台 goroutine(本仓禁止裸 go func)。token 级条目过期后 读判即视为不在;写路径不自动清扫,Sweep 可手动回收过期条目(pkg/cache NoBackgroundSweep 同款哲学:清扫时机交给部署形态)。TTL 骨架(键→失效 时刻 + 惰性过期 + Sweep + 时钟防呆)单源在包内 ttlmap(#209),hashes 表 的时钟与 m.now 同源(构造期注入,之后不可变)。
func NewMemRevoker ¶
func NewMemRevoker(opts ...MemRevokerOption) *MemRevoker
NewMemRevoker 构造内存撤销黑名单(缺省时钟 time.Now)。
func (*MemRevoker) RevokeUser ¶
RevokeUser 设置用户级截断点(单调不回退,取既有值与 at 的较大者——回退 会让已判陈旧的令牌复活)。
零值 fail-fast(#188):at.IsZero(DB NULL/零值扫描、或调用方误传 time.Time{} 想「吊销全部」)时直接报错,不登记——零值截断点存进去后 RevokedUser 的判定恒 false(任何真实 iat 都不 Before 零时刻),改密/强踢 静默零效果且接口返回 nil 表示「成功」,正是 Revoke 对非正 remaining 已经 fail-fast 的同款风险(#65 纪律)。确需「撤销一切历史」的语义请用 显式截断点(如 time.Now()),不要让零值承担含义。
func (*MemRevoker) RevokedUser ¶
RevokedUser 用户级判定:iat 早于截断点(秒截断)即陈旧。
比较口径单点委托 pwd.TokenStaleBefore(#121 改密陈旧判定的同一份实现—— 两处各写一份秒截断比较正是 #119/#121 要消灭的漂移形态)。
func (*MemRevoker) Sweep ¶
func (m *MemRevoker) Sweep()
Sweep 回收 token 级过期条目(用户级截断点不设 TTL,不回收)。 读路径本就把过期条目视为不在,Sweep 只影响内存占用,不影响判定语义。
type MemRevokerOption ¶
type MemRevokerOption func(*MemRevoker)
MemRevokerOption 是 NewMemRevoker 的函数选项。
func WithRevokerClock ¶
func WithRevokerClock(f func() time.Time) MemRevokerOption
WithRevokerClock 注入 MemRevoker 时钟(测试确定性 TTL 边界;f 为 nil 直接 panic——静默回落 time.Now() 会让时钟无声漂移,WithNow(#64)同款纪律)。
type MemSessionStore ¶ added in v0.10.0
type MemSessionStore struct {
// contains filtered or unexported fields
}
MemSessionStore 是 SessionStore 的内存参考实现:并发安全(mutex 保护), 零第三方依赖,可作 StoreRegistry 的单实例/multi-instance 测试替身。
过期语义:读路径惰性出清(过期键视作不存在),Sweep 可手动回收;不启动 后台 goroutine(本仓禁止裸 go func)。TTL 骨架(键→失效时刻 + 惰性过期 + Sweep + 时钟防呆)单源在包内 ttlmap(#209)——kv 与 sets 两张表共用一份 实现,时钟取构造注入的 m.now(与 ttlmap 内部判定同一时钟源,构造后不可变)。
func NewMemSessionStore ¶ added in v0.10.0
func NewMemSessionStore(opts ...MemSessionStoreOption) *MemSessionStore
NewMemSessionStore 构造内存 SessionStore(缺省时钟 time.Now)。
func (*MemSessionStore) SRem ¶ added in v0.10.0
func (m *MemSessionStore) SRem(ctx context.Context, key, member string) error
SRem 移除集合成员(契约见 SessionStore)。
func (*MemSessionStore) SetNX ¶ added in v0.10.0
func (m *MemSessionStore) SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error)
SetNX 原子写入(契约见 SessionStore)。
func (*MemSessionStore) Sweep ¶ added in v0.10.0
func (m *MemSessionStore) Sweep()
Sweep 回收过期键与集合(读路径本就把过期项视为不存在,Sweep 只影响内存占用)。 仅内存实现提供;持久 store 依赖后端原生 TTL。
type MemSessionStoreOption ¶ added in v0.10.0
type MemSessionStoreOption func(*MemSessionStore)
MemSessionStoreOption 是 NewMemSessionStore 的函数选项。
func WithSessionStoreClock ¶ added in v0.10.0
func WithSessionStoreClock(f func() time.Time) MemSessionStoreOption
WithSessionStoreClock 注入内存 store 时钟(测试确定性 TTL 边界;f 为 nil 直接 panic——静默回落 time.Now() 会让 TTL 无声漂移,WithRevokerClock 同款纪律)。
type Revoker ¶
type Revoker interface {
// Revoke 吊销单枚令牌:以 hash 记黑名单,条目 TTL=remaining。
// remaining 必须为正(已过期令牌无需登记,非正 TTL 是配置零值透传的
// 常见形态,#65 同款纪律)。
Revoke(ctx context.Context, hash string, remaining time.Duration) error
// Revoked 判定单枚令牌是否已吊销(token 级)。
Revoked(ctx context.Context, hash string) (bool, error)
// RevokeUser 用户级吊销:at 之前签发的该用户令牌全部判陈旧(截断点单调不回退)。
// at 不得为零值:零值截断点会让判定恒 false(一枚令牌都没吊销却返回 nil
// ——fail-open),非正/零值是配置零值透传的常见形态,实现出口必须
// fail-fast(与 Revoke 的 remaining 同款 #65 纪律,#188)。
RevokeUser(ctx context.Context, userID string, at time.Time) error
// RevokedUser 用户级判定:iat 早于截断点(秒截断,pwd.TokenStaleBefore
// 口径)即陈旧。无截断点 ⇒ false。
RevokedUser(ctx context.Context, userID string, iat time.Time) (bool, error)
}
Revoker 撤销黑名单存储面(#119):token 级 + 用户级两层,接口化存储。
键纪律:hash 参数必须出自 TokenHash(键空间唯一产出口),实现按「键即 TokenHash 产物」理解与建索引,不接受任意字符串键。原始令牌串入口见 RevokeToken / RevokedToken 助手。raw token 与 hash 的分型是有意为之: 会话注册表(Kick 双 hash 拉黑)只持有 hash,轮换/登出路径未必持有原始串, 签名收窄到 hash 级可杜绝「随手传非 TokenHash 键污染键空间」。
两层语义:
- token 级(Revoke/Revoked):单枚令牌拉黑。remaining 是该令牌的**剩余 寿命**(条目 TTL,过期自然出清——过期令牌本就被 exp 拒绝,条目无需 长生);已过期令牌不需要登记。
- 用户级(RevokeUser/RevokedUser):截断点。at 之前签发的全部令牌判陈旧 (#121 改密陈旧吊销的落地口)。截断点**单调不回退**(同用户重复设置取 时间较大者——回退会让已判陈旧的令牌复活,是 fail-open);不设 TTL(陈旧 判定随 iat 天然自限,条目随用户数线性)。
陈旧判定口径单点在 pwd.TokenStaleBefore(秒截断比较:iat 与截断点同秒不判 陈旧)——实现 RevokedUser 必须复用该口径,禁止另写一份比较。
存储故障契约:实现出错必须返回 error,**不得**把故障折叠成「未吊销」放行 (fail-open 是黑名单最危险的缺省)。消费侧(kitx/auth)把查询故障归 500: 既不放行、也不放大成 401 全站踢下线。
type Session ¶
type Session struct {
// ID 会话 ID(登记表主键,编排层生成;同一次登录一对令牌一枚会话 ID)。
ID string
// UserID 会话归属用户。
UserID string
// Device 设备标识(自由文本,管理端枚举/按设备辨识用;可空)。
Device string
// IP 登录来源 IP(审计留痕;可空)。
IP string
// UA 登录客户端 UA(审计留痕;可空)。
UA string
// RefreshJTI 会话对应的 refresh 令牌 jti(管理端展示与对账;可空)。
RefreshJTI string
// AccessHash access 令牌的 TokenHash(强踢拉黑口径;可空——空则 Kick 跳过该路)。
AccessHash string
// RefreshHash refresh 令牌的 TokenHash(轮换认领键;必填)。
RefreshHash string
// LoginAt 登录/换发时刻。
LoginAt time.Time
}
Session 是一条在线会话登记项(设备/会话维度,#119)。
登记表回答「某用户在哪些设备在线」(ListByUser → Device/IP/UA/LoginAt), 强踢回答「如何把他踢下线」(Kick/KickUser → 双 hash 拉黑 + 删键)。
哈希字段(AccessHash/RefreshHash)是 TokenHash 产出口:登记期由编排层 (kitx/auth)算好写入,拉黑期由注册表直接消费——原始令牌串不进登记表 (存储面不落明文凭据)。
type SessionRegistry ¶
type SessionRegistry interface {
// Register 登记会话(ttl=refresh 剩余寿命,必须为正)。
// ID 已被未过期会话占用、或 RefreshHash 已挂在另一会话上 ⇒ 报错
// (同一 refresh 不得挂两枚会话——登记面本身也是防重放面)。
Register(ctx context.Context, s Session, ttl time.Duration) error
// GetByRefreshHash 按 refresh 哈希查会话(refresh 轮换的认领前置)。
// 不在(未登记/已过期/已下线)⇒ ErrSessionNotFound。
GetByRefreshHash(ctx context.Context, refreshHash string) (Session, error)
// ListByUser 枚举某用户的在线会话(管理端;按 LoginAt、ID 稳定排序,
// 过期会话不出现)。返回值是快照副本,改写不影响登记表。
ListByUser(ctx context.Context, userID string) ([]Session, error)
// Kick 强踢单会话:双 hash 拉黑 + 删键,**原子认领**。三态契约:
// - (true, nil):完整下线(拉黑与删键都已落地);
// - (false, nil):登记不存在(幂等强踢的常态 / 轮换竞态的败方 / 同 ID
// 会话已重建的 ABA 败方,#136);
// - (false, err):拉黑或下线前置落地失败,登记**保留**(可重试)。
//
// 原子认领(claim)是 refresh 轮换防重放的拍板点:并发轮换/强踢竞争同一
// 会话时恰有一个调用拿到 true,其余按败方拒绝——「旧 refresh 二次使用被拒」
// 不靠时序运气。ABA 提示(#136):解锁-重锁窗口里同 ID 会话可能被「踢掉 +
// 重建」,实现必须按登记项**身份**复核(而非存在性),不得误删重建会话。
Kick(ctx context.Context, id string) (bool, error)
// KickUser 强踢某用户全部在线会话(#119 强踢全会话;改密吊销钩子的落地
// 一半)。返回完整下线的会话数;部分失败时已踢的不回滚,错误聚合上抛
// (errors.Join)。
KickUser(ctx context.Context, userID string) (int, error)
}
SessionRegistry 在线会话注册表存储面(#119):接口化存储。
生命周期契约:登记 TTL 是 refresh 令牌的**剩余寿命**(编排层以 ttlRefresh 登记)——会话过期即两令牌都已自然失效(编排层保证 ttlRefresh ≥ ttlAccess, 登记 TTL 是两令牌寿命的上界)。MemRegistry(进程内)与 StoreRegistry (SessionStore 编排,Redis 等持久形态,#196)都实现本契约。
强踢契约(Kick):**双 hash 拉黑 + 删键**一次落地——只删登记不拉黑等于假 强踢(令牌还活着),只拉黑不删键会让会话继续被枚举为在线。拉黑落地失败时 登记必须保留(可重试),见 Kick 的三态返回。
type SessionStore ¶ added in v0.10.0
type SessionStore interface {
// Get 返回 key 的当前值。key 不存在或已过期 ⇒ ("", false, nil);
// 存储故障 ⇒ ("", false, err)。
Get(ctx context.Context, key string) (string, bool, error)
// SetNX 仅当 key 不存在(或已过期)时原子写入 value 并设置 ttl,返回是否
// 写入成功。**原子性是多实例强踢/登记的拍板点**:并发 SetNX 同一 key 必须
// 恰有一个 true。ttl 必须为正(<=0 返回 error);已存在的 key 不得被覆盖、
// 不得刷新其 TTL。
SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error)
// Del 原子删除 key(字符串键或集合键),返回 key 是否存在并被删除
// (不存在/已过期 ⇒ false)。Del(missing) 不是错误(幂等清理)。
Del(ctx context.Context, key string) (bool, error)
// SAdd 原子把 member 加入集合 key,并把集合 TTL **延长到至少 ttl**:
// 集合不存在时创建并设置 ttl;已存在时 TTL 取「现有剩余寿命」与 ttl 的
// 较大者——**只延长、不缩短**(一个用户的会话寿命长短不一,短寿命会话
// 登记不得把长寿命会话从索引里提前抹掉)。ttl 必须为正。
SAdd(ctx context.Context, key, member string, ttl time.Duration) error
// SRem 从集合 key 移除 member(集合/成员不存在照常成功,幂等)。
SRem(ctx context.Context, key, member string) error
// SMembers 返回集合全部成员的快照(集合不存在 ⇒ 空切片,无错误)。
// 顺序不保证;调用方自行排序。
SMembers(ctx context.Context, key string) ([]string, error)
// Expire 把已存在 key 的过期时间重设为 ttl(不延长/不缩短的语义由调用方
// 判断),返回 key 是否存在。ttl 必须为正。
Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)
// TTL 返回 key 的剩余寿命。key 不存在/已过期 ⇒ (0, false, nil);
// key 存在且带过期时间 ⇒ (remaining, true, nil)。实现不得创建无过期键;
// 若探测到无过期键应返回 error(契约违约),不得以 0/false 静默放行。
TTL(ctx context.Context, key string) (time.Duration, bool, error)
}
SessionStore 是 SessionRegistry 编排层依赖的最小存储面(#196):键值 + 集合 + TTL 原语。kitx 只依赖这 8 个方法,下游把 Redis 等持久存储包成 10 来行适配器即可复用整套注册/轮换/强踢编排(StoreRegistry)。
键由编排层生成(含 WithStorePrefix 命名空间),对 store 实现是不透明字符串; 实现不得解析/改写键。所有方法必须并发安全且跨实例安全(同一键的并发 SetNX/Del 语义与单实例一致)。
生命周期硬约束:**实现创建的每个键都必须带过期时间**(SetNX/SAdd 的 ttl、 Expire 的 ttl 均必须为正)。无过期键会让会话索引永久驻留,也会让 Kick 无法 计算剩余寿命——TTL 探测失败时必须返回 error,不得回落成「永不过期」。
存储故障契约(与 Revoker 同口径):实现出错必须返回 error,不得把故障折叠 成「不存在/已删除」——强踢把存储故障误判成 not-found 就是假下线。
type StoreRegistry ¶ added in v0.10.0
type StoreRegistry struct {
// contains filtered or unexported fields
}
StoreRegistry 是基于 SessionStore 的会话注册表编排实现(#196):把注册冲突、 refreshHash 唯一挂载、Kick 三态(原子认领 + 双 hash 拉黑 + 删键)与 KickUser 聚合计数集中在本层,下游只需实现 SessionStore(Redis 等适配器约 10 行)即可替换 MemRegistry,kitx/auth.Flow 的登录/轮换/登出/强踢链路零改动。
键布局(prefix 由 WithStorePrefix 配置,缺省 authz:sess:):
<prefix>id:<sessionID> 主键(storedSession JSON:Session + 登记代次) <prefix>refresh:<refreshHash> refresh 反查/唯一挂载(refreshMount JSON) <prefix>user:<userID> 用户索引集合(成员=sessionID) <prefix>lock:id:<sessionID> 会话操作锁(SetNX + TTL) <prefix>lock:refresh:<hash> refresh 索引变更锁(SetNX + TTL)
并发拍板:Register 全程持 ID 锁(主键/refresh/用户索引一次落地);Kick 只在 「读取快照」与「代次复核 + 删主键 + 清索引」两个短临界区持 ID 锁,拉黑调用 在锁外执行(与旧 MemRegistry 的解锁-重锁窗口同形,#136)——并发 Kick 各自 幂等拉黑,重锁后只有代次仍匹配的一方删键成功并返回 true。refresh 索引的 挂载/摘除另抢 refresh 锁,靠代次比对避免 ABA 误删。
锁持有时间受 sessionOpLockTTL 约束,存储操作异常慢时锁会自然过期——实现应 保证 SessionStore 调用远快于 30s。锁释放失败只记日志(锁会在 TTL 后自愈), 不影响已落地结果的三态语义。
func NewStoreRegistry ¶ added in v0.10.0
func NewStoreRegistry(rev Revoker, store SessionStore, opts ...StoreRegistryOption) (*StoreRegistry, error)
NewStoreRegistry 构造基于 SessionStore 的会话注册表。构造期 fail-fast: rev/store 任一为 nil 直接报错(无拉黑的强踢是假强踢;无存储的注册表是空壳)。
func (*StoreRegistry) GetByRefreshHash ¶ added in v0.10.0
GetByRefreshHash 按 refresh 哈希查会话(契约见 SessionRegistry)。
func (*StoreRegistry) Kick ¶ added in v0.10.0
Kick 强踢单会话(契约见 SessionRegistry 的三态返回)。
时序(与旧 MemRegistry 的 #136 解锁-重锁窗口同构):
ID 锁内读快照(Session + 登记代次 + 剩余寿命)→ 释放锁 → 锁外双 hash 拉黑(失败 ⇒ (false, err),登记保留可重试) → 重抢 ID 锁,按**代次**复核:代次已变/主键已不在 ⇒ 败方 (false, nil) → 删主键(下线生效点)→ 尽力清理 refresh/用户索引 → (true, nil)
func (*StoreRegistry) ListByUser ¶ added in v0.10.0
ListByUser 枚举某用户的在线会话(契约见 SessionRegistry)。
type StoreRegistryOption ¶ added in v0.10.0
type StoreRegistryOption func(*StoreRegistry)
StoreRegistryOption 是 NewStoreRegistry 的函数选项。
func WithStorePrefix ¶ added in v0.10.0
func WithStorePrefix(prefix string) StoreRegistryOption
WithStorePrefix 配置键命名空间(多租户/多环境隔离)。空串显式回退缺省 "authz:sess:";非空且未以 ':' 结尾时自动补 ':',保证键为 prefix+"id:"+... 的可读形态。store 实现无需感知 prefix——它只拿到已拼好的不透明键。