ratelimit

ratelimit

Package ratelimit is a rules-based rate limiter backed by Redis fixed-window counters. It maintains a counter per (limiter, rule, characteristics) tuple and decides whether each request is within the configured limit.

It implements the cross-SDK rate-limit contract pinned by the labkit-spec conformance suite: every LabKit SDK uses the same Redis key shape and the same Lua scripts, so services in any language can enforce shared limits against the same Redis, and all emit the same gitlab_labkit_rate_limiter_* Prometheus metrics.

Usage

A Limiter is the unit of configuration for one call site (e.g. "rack requests", "graphql mutations"). Construct it once at boot and reuse it:

limiter, err := ratelimit.NewWithConfig(&ratelimit.Config{
	Name:  "api_request",
	Store: redisstore.New(redisClient.Redis()), // labkit redis client, or any goredis.UniversalClient
	Rules: []ratelimit.Rule{
		{
			Name:            "api_user",
			Limit:           600,
			Period:          time.Minute,
			Characteristics: []string{"user"},
			Match:           map[string]ratelimit.Matcher{"endpoint": ratelimit.Re(`^/api/`)},
		},
		{
			Name:            "unauthenticated",
			Limit:           60,
			Period:          time.Minute,
			Characteristics: []string{"ip"},
			Match:           map[string]ratelimit.Matcher{"user": ratelimit.Eq("")},
		},
	},
	Registerer: app.Metrics().Registerer(),
	Logger:     logger,
})

Every request calls Check:

result := limiter.Check(ctx, ratelimit.Identifier{
	"user":     userID,
	"ip":       clientIP,
	"endpoint": r.URL.Path,
})

if result.Blocked() {
	for k, v := range result.ResponseHeaders() {
		w.Header().Set(k, v)
	}
	http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
	return
}

The endpoint identifier key is treated specially: its query string is stripped, so URLs that vary only by query parameter share the same counter. A missing identifier key reads as "", which is how Eq("") matches unauthenticated traffic.

NewWithConfig validates the limiter name and every rule and returns an error instead of constructing a limiter that would misbehave at request time.

Rule

Matchers

Actions

The rule's action describes what the rule does. The result describes the outcome, which is only ever allow or block.

A rule carrying a ban reports banned instead of block/log while the ban holds.

Evaluation flow

Check walks the rule list in order and evaluates every rule that matches: each one increments its own counter. Only two things terminate the walk: a matched skip rule, and an ActionLimit rule over its limit (rules declared after it are neither counted nor evaluated).

The returned Result collects one Evaluation per counted rule, and its readers (Rule, Info, Exceeded, ResponseHeaders) report the most constraining one: a blocking evaluation first, then exceeded ones, then the fewest remaining, ties broken by declaration order.

Dynamic configuration

LimitFunc, PeriodFunc, and BanForFunc resolve on every check. Pass per-request context with WithRuleContext. The concrete type is a contract between the rule's func and the call site:

result := limiter.Check(ctx, id, ratelimit.WithRuleContext(namespaceSettings))

WithCost supports cost-mode counters such as resource-usage limits. WithCost(0) charges nothing but still opens the fixed window on a fresh key, so a later charged request inherits it. Use Peek to read without writing.

Peek and Clear

Peek returns the same Result shape as Check without mutating Redis or extending any TTL - useful when one code path should account for the request and another should only gate on whether the caller is already over-limit.

Clear deletes this limiter's counters and bans for one identifier and returns the number of keys removed. It exists for call sites where a later success should wipe earlier failures, such as an authentication ban cleared by a valid login.

Redis keys

labkit:rl:{<limiter>:<rule>:<char>:<value>[:<char>:<value>...]}       counter
labkit:rl:{<limiter>:<rule>:<char>:<value>[:<char>:<value>...]}:ban   ban

The braces are a Redis Cluster hash tag: a rule's counter and ban share a slot (the ban script touches both in one call) while different rules spread across nodes. Characteristic values longer than 200 characters are replaced with a SHA-256 hexdigest. The TTL is set on the first write of each window and not extended afterwards, so the window is a true fixed window starting at the first request.

Each check is a single EVALSHA running the increment, SADD, or ban script. The whole read-modify-write runs atomically inside Lua, so no key can be left without a TTL and no concurrent check can miss a ban threshold crossing.

Fail-open

Check and Peek never return an error. Any failure - unreachable Redis, an unresolvable dynamic value - is logged at WARN with error_type: "rate_limit_error", counted with error="true" on checks_total or peeks_total, and returned as an allowed Result with Failed() == true. A request is never blocked on a partial evaluation.

The package does not bound the Redis call itself. A hung Redis costs each check the client's read timeout (3s by default in go-redis) before it fails open, so set timeouts on the client passed to redisstore.New.

A matched CountDistinct rule whose identifier is missing the distinct key fails open per-rule: the rule is skipped, the check completes, and the result reports Degraded() == true.

Metrics

sum by (rate_limiter) (rate(gitlab_labkit_rate_limiter_checks_total[5m])) is the request rate through a limiter.

Storage

The limiter talks to Redis through the Store interface, two methods in plain Go types: Eval for the Lua scripts and Del for Clear. redisstore.New adapts any go-redis UniversalClient, including the labkit redis package's Client.Redis(). The adapter is the only place go-redis appears, so a consumer with another client, or a test double, implements Store and never imports go-redis.

Testing

Use testing/redistest (miniredis) for the Redis dependency and testing/metricstest for metric assertions:

srv := redistest.New(t)
client := goredis.NewClient(&goredis.Options{Addr: srv.Addr()})
limiter, err := ratelimit.NewWithConfig(&ratelimit.Config{Name: "test", Rules: rules, Store: redisstore.New(client)})

srv.Miniredis().FastForward(d) advances the fake clock to test window expiry and bans.