go-chi/httprate

httprate is an HTTP request rate limiter based on the Sliding Window Counter pattern (inspired by Cloudflare). This pattern provides accurate, smooth traffic shaping and allows for easy distribution of rate limits across a cluster of servers.

To coordinate rate limits across multiple microservices, you can implement the httprate.LimitCounter interface to support atomic increments and gets in a shared backend like Redis.

You can override the default behavior when a request is rate-limited or when an internal error occurs by providing options during NewRateLimiter initialization:

• Rate-limited response: Use an option to set onRateLimited. This is a http.HandlerFunc called when RespondOnLimit detects a limit breach.
• Error response: Use an option to set onError. This is a function func(http.ResponseWriter, *http.Request, error) called when the LimitCounter returns an error. By default, it returns a 426 Precondition Required status.

The Limit, LimitAll, LimitByIP, and LimitByRealIP functions are deprecated. You should migrate to LimitBy, which requires an explicit key function as a mandatory argument. This makes the rate-limiting strategy (e.g., global, per-IP, or per-user) much more explicit.

Replacement Pattern: LimitBy(requestLimit, windowLength, keyFn, options...)

• For a single global bucket: Use httprate.Key("*") as the keyFn.
• For per-IP limiting: Use a custom key function that retrieves the client IP from the request context (see the recommended pattern below).

// Instead of Limit(10, time.Minute)
// Use LimitBy with an explicit key function
httprate.LimitBy(10, time.Minute, httprate.Key("*"))

For scenarios like login endpoints, you can use httprate.NewRateLimiter to manually check limits within a handler based on a value extracted from the request body (e.g., a username).

// Rate-limiter for login endpoint.
loginRateLimiter := httprate.NewRateLimiter(5, time.Minute)

r.Post("/login", func(w http.ResponseWriter, r *http.Request) {
	var payload struct {
		Username string `json:"username"`
		Password string `json:"password"`
	}
	if err := json.NewDecoder(r.Body).Decode(&payload); err != nil || payload.Username == "" {
		w.WriteHeader(400)
		return
	}

	// Rate-limit login at 5 req/min.
	if loginRateLimiter.RespondOnLimit(w, r, payload.Username) {
		return
	}

	w.Write([]byte("login at 5 req/min\n"))
})

The KeyFunc signature func(r *http.Request) (string, error) allows you to rate limit by any value extracted from the request, such as a custom header, a user ID, or a tenant ID.

r.Use(httprate.LimitBy(
	100,
	time.Minute,
	// rate limiting by a custom header
	func(r *http.Request) (string, error) {
		return r.Header.Get("X-Access-Token"), nil
	},
))

You can combine multiple keys to create more granular limits, such as limiting a specific user to a certain number of requests per specific endpoint using httprate.JoinKeys.

// clientIPKey is the KeyFunc from the "Rate limit by client IP behind a proxy" section.
r.Use(httprate.LimitBy(
	10,             // requests
	10*time.Second, // per duration
	httprate.JoinKeys(clientIPKey, httprate.KeyByEndpoint),
))

If your KeyFunc or your LimitCounter (backend) returns an error, you can intercept it using httprate.WithErrorHandler to return a specific HTTP status and message.

r.Use(httprate.LimitBy(
	10,
	time.Minute,
	clientIPKey,
	httprate.WithErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
		http.Error(w, fmt.Sprintf(`{"error": %q}`, err), http.StatusPreconditionRequired)
	}),
	httprate.WithLimitCounter(customBackend),
))

By default, httprate returns HTTP 429 with a Too Many Requests body. Use httprate.WithLimitHandler to provide a custom response (e.g., JSON) when a limit is exceeded.

r.Use(httprate.LimitBy(
	10,
	time.Minute,
	clientIPKey,
	httprate.WithLimitHandler(func(w http.ResponseWriter, r *http.Request) {
		http.Error(w, `{"error": "Rate-limited. Please, slow down."}`, http.StatusTooManyRequests)
	}),
))

Use WithIncrement to attach a specific increment value to a context.Context. This allows you to control how much the rate limit counter increases for a specific request (e.g., if a request is more 'expensive' than a standard one, you can pass a value greater than 1).

ctx := httprate.WithIncrement(r.Context(), 5)
// Subsequent middleware using this context will increment the rate limit by 5 instead of 1