ratelimit

package
v1.24.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package ratelimit 提供可热调、可影子运行(dry-run)的令牌桶限流原语。

与 octo-lib `pkg/wkhttp` 的三个限流中间件的分工:

  • lib 的中间件在**构造时**固定 rps/burst(middleware 只创建一次), 因此改配额必须重启进程。全局 per-IP 桶就是这个形状。
  • 本包把 rps/burst/开关做成**每次判定时读取**的 ParamsFunc, 于是配额可经 system_setting 运行时热调,无需重启。

为什么需要热调(这不是锦上添花):2026-08-05 的生产事故里,止血手段是把全局 per-IP 配额从 500 调到 1500,而该值只能靠滚动重启生效;滚动的 93 秒窗口内新旧 副本共用同一个 Redis 桶却各传各的参数,限流行为抖动,一个 bot 恰在此窗口被踢 下线且无法自愈。任何新增的桶若仍然只能靠重启调整,等于把这个故障模式复制一份。

与 repo rule `rate-limit` 的关系:该 rule 要求 authenticated route 挂 `SharedUIDRateLimiter`,但那是**进程级单例**(octo-server pkg/wkhttp ratelimit_helper.go 的 uidRateLimitReady 守卫),bot 与登录用户共用同一套 rps/burst。本包服务的场景需要「独立配额值 + 运行时热调」,共享单例在结构上 表达不了——这与 modules/incomingwebhook 的 per-webhook 桶同构,落在该 rule 已写明的 Exception(按业务身份的独立配额)之内,不是绕过。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SanitizeBurst

func SanitizeBurst(v, fallback int) int

SanitizeBurst 同 SanitizeRPS。burst <= 0 会让桶永远填不进 1 个 token → 100% 拒绝。

func SanitizeRPS

func SanitizeRPS(v, fallback float64) float64

SanitizeRPS 是**读侧防御**:配置值再怎么校验,也可能被直接改库、或被 env 绕过 写侧校验(`ParseRPSFromEnv` 底层是 strconv.ParseFloat,会原样接受 "NaN"/"+Inf")。

非法值必须回退到一个**合法且仍然限流**的值,绝不能退化成「放行」:

  • rps <= 0 会让上面的 Lua 走 `rate <= 0` 分支 → 100% 拒绝(不是放行,但等于 把整条路由打死);
  • **NaN 尤其危险**:octo-lib 的 `newKeyedLimiter` 只检查 `rps <= 0`,而 `NaN <= 0` 为 false,所以 NaN 会穿过它的启动期 panic 校验直达 Lua。 导出本函数正是为了让走 lib 中间件的调用方也能补上这道消毒;
  • NaN 会让 Lua 的算术全部变 NaN,比较失败,行为不可预测。

两者都不可接受,故一律回退到 fallback(由调用方给出代码默认值)。

Types

type Limiter

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

Limiter 是一条可热调、可影子运行的限流通道。

一个 Limiter 对应一个 class(业务分类,如 business/heartbeat/register), 拥有独立的 Redis keyspace 与独立的配置来源。

func New

func New(client *rd.Client, keyPrefix, class string, params ParamsFunc, obs Observer, fallback Params) *Limiter

New 构造一条限流通道。

  • keyPrefix 决定 Redis keyspace,必须以 ':' 结尾,且各 class 之间不得共用, 否则不同语义的流量会互相消耗对方的令牌。
  • fallback 提供**代码内的安全默认值**,仅在配置给出非法值(NaN/±Inf/≤0)时 顶上。它自身必须合法,否则读侧防御就没有底。

func (*Limiter) Check

func (l *Limiter) Check(key string) Result

Check 对 key 执行一次限流判定。key 为空时直接旁路——拿不到身份就限不了流, 此时**fail-open** 而不是归入某个共享桶:本包服务的都是已鉴权路径, 身份缺失属于挂载顺序错误(应当由测试守卫拦住),不应在生产上表现为 "所有无身份请求共享一个桶"这种更难排查的形态。

但两种旁路要**分别上报**:`enabled=false` 是预期状态(OutcomeBypassed), 而"开着却取不到身份"是配置/挂载错误(OutcomeNoKey)。见 OutcomeNoKey 的注释。

type Observer

type Observer interface {
	Observe(class string, key string, outcome Outcome)
}

Observer 接收每次判定的结果。实现必须是**非阻塞**的:它跑在请求路径上。

key 是限流维度的业务标识(本任务里是 robotID)。它**只允许**流向低基数的 聚合结构(如 Redis 的 top-N ZSet),**不得**作为 Prometheus label——生产实测 活跃 bot 2903 个且随业务增长无上界。

type OffenderRecorder

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

OffenderRecorder 把「谁被拒了」记进一个**有界**的 Redis ZSet,用于事故时定位到 具体 bot。它与 Prometheus 指标是互补的两层:

Prometheus  —— 无身份、低基数,回答「整体拒了多少、趋势如何」
OffenderZSet —— 有身份、有界,回答「具体是哪几个」

之所以不把身份塞进 Prometheus:生产实测活跃 bot 2903 个(Redis bot:heartbeat:*, TTL 60s)且随业务增长无上界,作为 label 会产生数万条随时间 churn 的 series。

func NewOffenderRecorder

func NewOffenderRecorder(client *rd.Client, prefix string) *OffenderRecorder

NewOffenderRecorder 构造记录器。prefix 必须以 ':' 结尾。

func (*OffenderRecorder) Record

func (r *OffenderRecorder) Record(class, key string)

Record 只应在**拒绝或影子拒绝**时调用,绝不能每请求调用——那会让观测本身 成为一条与业务流量同阶的 Redis 写路径。

错误被吞掉:观测失败不应影响业务判定。degraded 的信号由 Prometheus 那一层 (OutcomeDegraded)承担,此处再记一次只会在故障期放大日志。

func (*OffenderRecorder) Top

func (r *OffenderRecorder) Top(class string, n int) ([]rd.Z, error)

Top 返回该 class 当前的 offender 排行(score 降序),供排查使用。

**目前没有生产调用方**,这是刻意的:brief 明确决定不为它建管理端点(多一个鉴权面、 而事故期直接 `redis-cli ZREVRANGE ratelimit:bot:offenders:<class> 0 -1 WITHSCORES` 就够)。保留这个方法的理由是它把 key 拼接与降序语义收在包内一处——将来若要接 管理端点或诊断命令,是唯一该走的读路径,不必在调用方重新拼 key。

上界用 highWater 而非 topN:高水位裁剪允许集合暂时长到 2*topN,若这里仍夹到 topN, 排查时就会看不到水位区间内那些**最新出现**的 offender——而那恰恰是最需要看的。

type Outcome

type Outcome int

Outcome 是一次 Check 的判定结果。

WouldDeny 与 Denied 必须是**两个不同的值**:影子期(dry-run)与执行期的数据 若混在一起,就无法回答「关掉 dry-run 之后会多拒多少」——而那正是影子模式存在 的唯一理由。

const (
	// OutcomeBypassed 表示该层未启用(enabled=false),完全旁路:
	// 没有查过 Redis,也不应设置任何 X-RateLimit-* 头。
	OutcomeBypassed Outcome = iota
	// OutcomeAllowed 表示桶判定放行。
	OutcomeAllowed
	// OutcomeWouldDeny 表示桶判定拒绝,但因 dry-run 而**未**拦截。
	OutcomeWouldDeny
	// OutcomeDenied 表示桶判定拒绝且已拦截。
	OutcomeDenied
	// OutcomeDegraded 表示 Redis 故障,fail-open 放行。
	OutcomeDegraded
	// OutcomeNoKey 表示该层**已启用**,但取不到限流维度(key 为空),因此旁路放行。
	//
	// 与 OutcomeBypassed 分开是刻意的(code review 补入):两者外部行为相同(都放行、
	// 都不设头),但**成因完全相反**——Bypassed 是运维主动关掉了开关,属预期状态;
	// NoKey 意味着身份提取失败,而对已鉴权通道来说那只可能是**中间件挂载顺序错了**
	// (限流挂在了 authBot / botActorUID 之前),也就是本设计明文最怕的失败形态。
	//
	// 混在同一个 label 里的后果很具体:影子期看到 outcome="bypassed" 时,无法区分
	// 「通道还没开」和「开了但每条请求都取不到身份」——后者会让整层静默失效,
	// 而观测的全部意义就是发现这种「装上了但没生效」。
	OutcomeNoKey
)

func (Outcome) String

func (o Outcome) String() string

String 供指标 label 与日志使用。取值是**固定枚举**,这是 Prometheus label 基数有界的前提之一。

type Params

type Params struct {
	// Enabled=false 时完全旁路:不查 Redis、不设响应头、不改变任何可观察行为。
	// 这是 kill switch,误伤时用它止损比回滚发版快一个数量级。
	Enabled bool
	// DryRun=true 时执行完整判定(含 Redis 往返,成本要真实暴露)并上报观测,
	// 但**不拦截**、**不设 X-RateLimit-* 头**。
	//
	// 「不设头」是硬要求而非洁癖:影子期若下发限流头,客户端可能据此自行降频,
	// 于是观测到的不再是真实流量,定值也就失去意义。
	DryRun bool
	RPS    float64
	Burst  int
}

Params 是一次判定所用的运行时配置。由 ParamsFunc 在**每次判定时**返回, 因此改 system_setting 后最多一个配置快照周期(60s)即生效,无需重启。

type ParamsFunc

type ParamsFunc func() Params

ParamsFunc 每次判定时被调用一次。实现方负责读配置并做读侧防御。

type Result

type Result struct {
	Outcome    Outcome
	Remaining  int
	RetryAfter int
	// Burst 回传当次判定实际使用的桶容量,供调用方写 X-RateLimit-Limit。
	// 不能让调用方自己再读一次配置——两次读之间配置可能已经变了。
	Burst int
	// DryRun 标记本次判定处于影子模式。
	//
	// 必须单独带出来,而不能从 Outcome 反推:影子模式下**放行**的请求 outcome 仍是
	// OutcomeAllowed(判定结果就是放行,这不是影子特有的),若只看 outcome 就会给它
	// 下发 X-RateLimit-* 头——于是影子期客户端照样看到 Remaining 递减并自行降频,
	// 观测到的不再是真实流量。集成测试
	// TestRateLimitDryRunDoesNotAffectClients 钉住这条。
	DryRun bool
}

Result 是 Check 返回给调用方的判定结论。是否拒绝、如何拒绝由调用方决定, 本包不依赖任何 HTTP 框架。

func (Result) ShouldReject

func (r Result) ShouldReject() bool

ShouldReject 表示调用方应当拒绝该请求。 注意 OutcomeWouldDeny 返回 false:影子模式下"判定为拒绝"但"不拦截"。

func (Result) ShouldSetHeaders

func (r Result) ShouldSetHeaders() bool

ShouldSetHeaders 表示调用方应当下发 X-RateLimit-* 头。

影子模式一律不下发——**包括判定放行的那些请求**,理由见 Result.DryRun。 旁路同理:关闭状态下的响应必须与未挂 limiter 逐字节一致。

Jump to

Keyboard shortcuts

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