authz

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 12 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrSessionNotFound = errors.New("authz: 会话不存在")

ErrSessionNotFound 表示会话不在登记表(未登记 / 已过期 / 已下线)。

Functions

func RevokeToken

func RevokeToken(ctx context.Context, r Revoker, token string, remaining time.Duration) error

RevokeToken 以原始令牌串登记撤销(Revoker.Revoke 的薄助手:内部经 TokenHash 落到键空间)。remaining 语义同 Revoker.Revoke。

func RevokedToken

func RevokedToken(ctx context.Context, r Revoker, token string) (bool, error)

RevokedToken 以原始令牌串判定撤销(Revoker.Revoked 的薄助手)。

func TokenHash

func TokenHash(token string) string

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

func (m *MemRevoker) Revoke(ctx context.Context, hash string, remaining time.Duration) error

Revoke 登记一条 token 级撤销(TTL=remaining)。

func (*MemRevoker) RevokeUser

func (m *MemRevoker) RevokeUser(ctx context.Context, userID string, at time.Time) error

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

func (m *MemRevoker) Revoked(ctx context.Context, hash string) (bool, error)

Revoked 判定 token 级撤销(过期条目视为不在)。读路径不回删(RWMutex 读锁;物理回收交给 Sweep)。

func (*MemRevoker) RevokedUser

func (m *MemRevoker) RevokedUser(ctx context.Context, userID string, iat time.Time) (bool, error)

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) Del added in v0.10.0

func (m *MemSessionStore) Del(ctx context.Context, key string) (bool, error)

Del 删除键(契约见 SessionStore;字符串键与集合键同一命名空间,均可删)。

func (*MemSessionStore) Expire added in v0.10.0

func (m *MemSessionStore) Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)

Expire 重设键过期时间(契约见 SessionStore)。

func (*MemSessionStore) Get added in v0.10.0

func (m *MemSessionStore) Get(ctx context.Context, key string) (string, bool, error)

Get 返回键值(契约见 SessionStore)。

func (*MemSessionStore) SAdd added in v0.10.0

func (m *MemSessionStore) SAdd(ctx context.Context, key, member string, ttl time.Duration) error

SAdd 加入集合并延长 TTL(契约见 SessionStore)。

func (*MemSessionStore) SMembers added in v0.10.0

func (m *MemSessionStore) SMembers(ctx context.Context, key string) ([]string, error)

SMembers 返回集合快照(契约见 SessionStore)。

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。

func (*MemSessionStore) TTL added in v0.10.0

TTL 返回剩余寿命(契约见 SessionStore)。

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

func (r *StoreRegistry) GetByRefreshHash(ctx context.Context, refreshHash string) (Session, error)

GetByRefreshHash 按 refresh 哈希查会话(契约见 SessionRegistry)。

func (*StoreRegistry) Kick added in v0.10.0

func (r *StoreRegistry) Kick(ctx context.Context, id string) (bool, error)

Kick 强踢单会话(契约见 SessionRegistry 的三态返回)。

时序(与旧 MemRegistry 的 #136 解锁-重锁窗口同构):

ID 锁内读快照(Session + 登记代次 + 剩余寿命)→ 释放锁
→ 锁外双 hash 拉黑(失败 ⇒ (false, err),登记保留可重试)
→ 重抢 ID 锁,按**代次**复核:代次已变/主键已不在 ⇒ 败方 (false, nil)
→ 删主键(下线生效点)→ 尽力清理 refresh/用户索引 → (true, nil)

func (*StoreRegistry) KickUser added in v0.10.0

func (r *StoreRegistry) KickUser(ctx context.Context, userID string) (int, error)

KickUser 强踢某用户全部在线会话(契约见 SessionRegistry)。

func (*StoreRegistry) ListByUser added in v0.10.0

func (r *StoreRegistry) ListByUser(ctx context.Context, userID string) ([]Session, error)

ListByUser 枚举某用户的在线会话(契约见 SessionRegistry)。

func (*StoreRegistry) Register added in v0.10.0

func (r *StoreRegistry) Register(ctx context.Context, s Session, ttl time.Duration) error

Register 登记会话(契约见 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——它只拿到已拼好的不透明键。

Directories

Path Synopsis
Package authztest 提供 authz.SessionStore 的契约测试套件(#196):下游把 自己的 Redis 等持久存储适配器塞进 Run,同一组用例验证「键值/集合原语语义 + kitx 编排层依赖的会话注册表行为」。
Package authztest 提供 authz.SessionStore 的契约测试套件(#196):下游把 自己的 Redis 等持久存储适配器塞进 Run,同一组用例验证「键值/集合原语语义 + kitx 编排层依赖的会话注册表行为」。

Jump to

Keyboard shortcuts

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