ratelimit

func Middleware ¶

func Middleware(c *cache.Cache, configure ...BuilderFunc) router.Middleware

Middleware returns middleware that limits each key to the configured number of requests in any sliding window, counting in c.

The limiter is a sliding-window counter. Time is divided into fixed windows of settings.Window aligned to the Unix epoch, and each key keeps one counter per window index, joined to the configured namespace and client with a TTL of twice the window. A request increments the current window's counter and reads the previous window's counter, then estimates the requests in the last window as

previous * (1 - elapsed/Window) + current

where elapsed is the time since the current window began. The request is denied when the estimate exceeds Limit. Unlike a fixed window this cannot admit twice the limit across a window boundary: the previous window's requests keep counting, with linearly decaying weight. The estimate assumes requests were evenly spread over the previous window, so it is approximate, but it needs only atomic increments. Instances must have reasonably synchronized clocks.

Denied requests do not count. A denied request's increment is undone with a decrement, so a client that keeps retrying while limited does not extend its own block: the counters would otherwise carry into later windows and a client sending many times the limit could stay blocked for many windows. Concurrent requests may briefly be denied because another in-flight request's increment is visible, which errs towards the limit.

After successful counter operations, responses carry RateLimit-Limit, RateLimit-Remaining (the estimated requests still available, rounded down), and RateLimit-Reset. Reset is the whole seconds, rounded up and at least one, until the estimate would decay to zero if the client stopped sending, which is the moment the full Limit is available again. A denial also carries Retry-After, independently of the configured problem's status, equal to its Reset: the whole seconds, rounded up and at least one, until the estimate leaves room for one more request. Both are computed from the same window arithmetic as the decision and never fall early. Counts and recovery intervals use integer ratios with upward rounding, so large limits and nanosecond boundaries do not lose precision through floats.

Counters are kept with cache.Cache.IncrementWithTTL, which increments and sets the expiry atomically, so a counter can never outlive its window. A driver that cannot do this returns cache.ErrUnsupported and the limiter cannot be used with it.

With Builder.Events, the first denied request of a key in each fixed window normally publishes Exceeded. Finding the first costs one cache Add per denied request, only when events are enabled. Deduplication is best-effort: failure to add the marker still publishes, so repeated denials can produce duplicate events. Counter failures instead fail the request; they never bypass the limit.

A nil cache, negative Limit, invalid Namespace, or Window outside (0, time.Duration(math.MaxInt64/2)] panics after all callbacks. Zero Limit and Window retain their defaults of 60 and one minute. Cache errors, including a nonpositive counter returned after increment, fail the request without calling the protected handler.

Example:

routes.Use(ratelimit.Middleware(store, func(limiter *ratelimit.Builder) {
	limiter.Namespace(cache.NewNamespace[int64]("app.rate"))
}))

func TrustedProxyKey ¶

func TrustedProxyKey(trusted ...netip.Prefix) func(*http.Request) string

TrustedProxyKey returns a key function for use with Builder.KeyFunc that identifies clients behind reverse proxies or load balancers. When the request's RemoteAddr lies within trusted, the X-Forwarded-For header lines are walked from right to left and the first address outside trusted is the client. When RemoteAddr is not trusted the header is client-controlled and ignored. If an entry cannot be parsed, or every address is trusted, the nearest trusted hop that reported it is the key, so attacker-chosen strings never become keys. Addresses are reduced as in the default key function.

Example:

routes.Use(ratelimit.Middleware(store, func(limiter *ratelimit.Builder) {
	limiter.KeyFunc(ratelimit.TrustedProxyKey(netip.MustParsePrefix("10.0.0.0/8")))
}))