httprate

https://pkg.go.dev/github.com/go-chi/httprate
Admin
httprate is an HTTP request rate limiter for Go's net/http based on the Sliding Window Counter...
Tokens:3,862
Snippets:34
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Get Rate Limit Status

Source: https://pkg.go.dev/github.com/go-chi/httprate

Returns the current status for a given key, including whether the limit is reached and the current count.

```go
func (l *RateLimiter) Status(key string) (bool, float64, error)
```

--------------------------------

### Core Types and Interfaces

Source: https://pkg.go.dev/github.com/go-chi/httprate

Definitions for key functions, limit counters, and configuration options.

```go
type KeyFunc func(r *http.Request) (string, error)
```

```go
type LimitCounter interface {
	Config(requestLimit int, windowLength time.Duration)
	Increment(key string, currentWindow time.Time) error
	IncrementBy(key string, currentWindow time.Time, amount int) error
	Get(key string, currentWindow, previousWindow time.Time) (int, int, error)
}
```

```go
type Option func(rl *RateLimiter)
```

```go
type RateLimiter struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### Configuration Options

Source: https://pkg.go.dev/github.com/go-chi/httprate

Functional options for configuring the RateLimiter.

```go
func WithErrorHandler(h func(http.ResponseWriter, *http.Request, error)) Option
```

```go
func WithKeyByIP() Option
```

```go
func WithKeyByRealIP() Option
```

```go
func WithKeyFuncs(keyFuncs ...KeyFunc) Option
```

```go
func WithLimitCounter(c LimitCounter) Option
```

```go
func WithLimitHandler(h http.HandlerFunc) Option
```

```go
func WithNoop() Option
```

```go
func WithResponseHeaders(headers ResponseHeaders) Option
```

--------------------------------

### Initialize RateLimiter

Source: https://pkg.go.dev/github.com/go-chi/httprate

Creates a new RateLimiter instance with a specified request limit and window duration.

```go
func NewRateLimiter(requestLimit int, windowLength time.Duration, options ...Option) *RateLimiter
```

--------------------------------

### Implement basic IP-based rate limiting

Source: https://pkg.go.dev/github.com/go-chi/httprate

Use the LimitByIP middleware to restrict requests based on the client's IP address.

```go
package main

import (
	"net/http"
	"time"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"
	"github.com/go-chi/httprate"
)

func main() {
	r := chi.NewRouter()
	r.Use(middleware.Logger)

	// Enable httprate request limiter of 100 requests per minute.
	//
	// In the code example below, rate-limiting is bound to the request IP address
	// via the LimitByIP middleware handler.
	//
	// To have a single rate-limiter for all requests, use httprate.LimitAll(..).
	//
	// Please see _example/main.go for other more, or read the library code.
	r.Use(httprate.LimitByIP(100, time.Minute))

	r.Get("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("."))
	})

	http.ListenAndServe(":3333", r)
}
```

--------------------------------

### Counter and Context Utilities

Source: https://pkg.go.dev/github.com/go-chi/httprate

Utility functions for managing rate limit counters and request context.

```go
func LimitCounterKey(key string, window time.Time) uint64
```

```go
func NewLocalLimitCounter(windowLength time.Duration) *localCounter
```

```go
func WithIncrement(ctx context.Context, value int) context.Context
```

```go
func WithRequestLimit(ctx context.Context, value int) context.Context
```

--------------------------------

### Configure Response Headers

Source: https://pkg.go.dev/github.com/go-chi/httprate

Defines custom header names for rate limit information in HTTP responses.

```go
type ResponseHeaders struct {
	Limit      string // Default: X-RateLimit-Limit
	Remaining  string // Default: X-RateLimit-Remaining
	Increment  string // Default: X-RateLimit-Increment
	Reset      string // Default: X-RateLimit-Reset
	RetryAfter string // Default: Retry-After
}
```

--------------------------------

### Configure custom response headers

Source: https://pkg.go.dev/github.com/go-chi/httprate

Map rate limit status information to specific custom HTTP response headers.

```go
r.Use(httprate.Limit(
	1000,
	time.Minute,
	httprate.WithResponseHeaders(httprate.ResponseHeaders{
		Limit:      "X-RateLimit-Limit",
		Remaining:  "X-RateLimit-Remaining",
		Reset:      "X-RateLimit-Reset",
		RetryAfter: "Retry-After",
		Increment:  "", // omit
	}),
))
```

--------------------------------

### Check Rate Limit and Respond

Source: https://pkg.go.dev/github.com/go-chi/httprate

Checks the rate limit for a key and automatically sends an HTTP response if the limit is reached.

```go
func (l *RateLimiter) RespondOnLimit(w http.ResponseWriter, r *http.Request, key string) bool
```

--------------------------------

### Rate Limiter Configuration and Usage

Source: https://pkg.go.dev/github.com/go-chi/httprate

This section covers the core functions for creating and configuring a rate limiter, including options for custom key functions, error handling, and response headers.

```APIDOC
## Rate Limiter API

### Description
Provides middleware for rate limiting HTTP requests.

### Functions

#### `Limit(requestLimit int, windowLength time.Duration, options ...Option) func(next http.Handler) http.Handler`
Creates a rate limiter middleware.

#### `LimitAll(requestLimit int, windowLength time.Duration) func(next http.Handler) http.Handler`
Creates a rate limiter middleware that applies limits to all requests.

#### `LimitByIP(requestLimit int, windowLength time.Duration) func(next http.Handler) http.Handler`
Creates a rate limiter middleware that limits requests based on the client's IP address.

#### `LimitByRealIP(requestLimit int, windowLength time.Duration) func(next http.Handler) http.Handler`
Creates a rate limiter middleware that limits requests based on the client's real IP address (useful behind proxies).

### Options

#### `Option` type
Functions that modify the behavior of the `RateLimiter`.

#### `WithErrorHandler(h func(http.ResponseWriter, *http.Request, error)) Option`
Sets a custom error handler for when rate limits are exceeded.

#### `WithKeyByIP() Option`
Configures the rate limiter to use the client's IP address as the key.

#### `WithKeyByRealIP() Option`
Configures the rate limiter to use the client's real IP address as the key.

#### `WithKeyFuncs(keyFuncs ...KeyFunc) Option`
Allows specifying custom key functions for rate limiting.

#### `WithLimitCounter(c LimitCounter) Option`
Provides a custom `LimitCounter` implementation.

#### `WithLimitHandler(h http.HandlerFunc) Option`
Sets a custom handler to be executed when a rate limit is exceeded.

#### `WithNoop() Option`
Disables rate limiting.

#### `WithResponseHeaders(headers ResponseHeaders) Option`
Configures response headers to be added when rate limits are applied.

### Types

#### `RateLimiter` struct
Represents a rate limiter.

- `NewRateLimiter(requestLimit int, windowLength time.Duration, options ...Option) *RateLimiter`
  Constructor for `RateLimiter`.

- `Handler(next http.Handler) http.Handler`
  Returns the rate limiting middleware handler.

- `Status(key string) (bool, float64, error)`
  Checks the status of a given key.

#### `LimitCounter` interface
Interface for implementing custom limit counters.

- `Config(requestLimit int, windowLength time.Duration)`
- `Increment(key string, currentWindow time.Time) error`
- `IncrementBy(key string, currentWindow time.Time, amount int) error`
- `Get(key string, currentWindow, previousWindow time.Time) (int, int, error)`

#### `KeyFunc` type
Function type for extracting a key from an HTTP request.

- `Key(key string) func(r *http.Request) (string, error)`
- `KeyByEndpoint(r *http.Request) (string, error)`
- `KeyByIP(r *http.Request) (string, error)`
- `KeyByRealIP(r *http.Request) (string, error)`

```

--------------------------------

### Context Utilities

Source: https://pkg.go.dev/github.com/go-chi/httprate

Functions for managing rate limiting context within requests.

```APIDOC
## Context Utilities

### Description
Utilities for working with rate limiting context.

### Functions

#### `WithIncrement(ctx context.Context, value int) context.Context`
Adds a value to the request context for incrementing the limit.

#### `WithRequestLimit(ctx context.Context, value int) context.Context`
Sets a specific request limit within the context.

```

--------------------------------

### Check Rate Limit

Source: https://pkg.go.dev/github.com/go-chi/httprate

Checks the rate limit for a key and updates headers. Returns true if the limit is reached; the caller must handle the response.

```go
func (l *RateLimiter) OnLimit(w http.ResponseWriter, r *http.Request, key string) bool
```

--------------------------------

### Omit response headers

Source: https://pkg.go.dev/github.com/go-chi/httprate

Disable the inclusion of rate limit headers in the response by passing an empty configuration.

```go
r.Use(httprate.Limit(
	1000,
	time.Minute,
	httprate.WithResponseHeaders(httprate.ResponseHeaders{}),
))
```

--------------------------------

### Customize rate limit response

Source: https://pkg.go.dev/github.com/go-chi/httprate

Override the default HTTP 429 response by providing a custom limit handler.

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

--------------------------------

### RateLimiter Functions

Source: https://pkg.go.dev/github.com/go-chi/httprate

This section details the core functions of the RateLimiter type, including initialization, handling requests, and checking status.

```APIDOC
## NewRateLimiter

### Description
Initializes a new RateLimiter with a specified request limit, window length, and optional configuration options.

### Signature
```go
func NewRateLimiter(requestLimit int, windowLength time.Duration, options ...Option) *RateLimiter
```

## RateLimiter.Counter

### Description
Returns the underlying LimitCounter used by the RateLimiter. Added in v0.13.1.

### Signature
```go
func (l *RateLimiter) Counter() LimitCounter
```

## RateLimiter.Handler

### Description
Returns an http.Handler that wraps the provided next http.Handler, applying rate limiting middleware. Added in v0.13.1.

### Signature
```go
func (l *RateLimiter) Handler(next http.Handler) http.Handler
```

## RateLimiter.OnLimit

### Description
Checks the rate limit for a given key. If the limit is reached, it returns true; otherwise, it increments the request count and returns false. This method does not send an HTTP response; the caller must handle the response. Added in v0.13.1.

### Signature
```go
func (l *RateLimiter) OnLimit(w http.ResponseWriter, r *http.Request, key string) bool
```

## RateLimiter.RespondOnLimit

### Description
Checks the rate limit for a given key. If the limit is reached, it automatically sends an HTTP response and returns true. Otherwise, it increments the request count and returns false. Added in v0.14.0.

### Signature
```go
func (l *RateLimiter) RespondOnLimit(w http.ResponseWriter, r *http.Request, key string) bool
```

## RateLimiter.Status

### Description
Returns the rate limit status for a given key, including whether the limit is exceeded, the remaining requests, and any potential error. Added in v0.13.1.

### Signature
```go
func (l *RateLimiter) Status(key string) (bool, float64, error)
```
```

--------------------------------

### Wrap HTTP Handler

Source: https://pkg.go.dev/github.com/go-chi/httprate

Returns an http.Handler that applies rate limiting to the provided next handler.

```go
func (l *RateLimiter) Handler(next http.Handler) http.Handler
```

--------------------------------

### Rate limit by IP and URL path

Source: https://pkg.go.dev/github.com/go-chi/httprate

Combine multiple key functions to restrict traffic based on both the client IP and the specific endpoint accessed.

```go
r.Use(httprate.Limit(
	10,             // requests
	10*time.Second, // per duration
	httprate.WithKeyFuncs(httprate.KeyByIP, httprate.KeyByEndpoint),
))
```

--------------------------------

### Rate limit by arbitrary keys

Source: https://pkg.go.dev/github.com/go-chi/httprate

Use custom key functions to extract identifiers from request headers or other request properties.

```go
r.Use(httprate.Limit(
	100,
	time.Minute,
	// an oversimplified example of rate limiting by a custom header
	httprate.WithKeyFuncs(func(r *http.Request) (string, error) {
		return r.Header.Get("X-Access-Token"), nil
	}),
))
```

--------------------------------

### Key Generation Functions

Source: https://pkg.go.dev/github.com/go-chi/httprate

Functions used to generate unique keys for rate limiting based on request properties.

```go
func Key(key string) func(r *http.Request) (string, error)
```

```go
func KeyByEndpoint(r *http.Request) (string, error)
```

```go
func KeyByIP(r *http.Request) (string, error)
```

```go
func KeyByRealIP(r *http.Request) (string, error)
```

--------------------------------

### Rate Limiting Middleware

Source: https://pkg.go.dev/github.com/go-chi/httprate

Middleware functions to apply rate limits to HTTP handlers.

```go
func Limit(requestLimit int, windowLength time.Duration, options ...Option) func(next http.Handler) http.Handler
```

```go
func LimitAll(requestLimit int, windowLength time.Duration) func(next http.Handler) http.Handler
```

```go
func LimitByIP(requestLimit int, windowLength time.Duration) func(next http.Handler) http.Handler
```

```go
func LimitByRealIP(requestLimit int, windowLength time.Duration) func(next http.Handler) http.Handler
```

--------------------------------

### Local Limit Counter

Source: https://pkg.go.dev/github.com/go-chi/httprate

Details on the in-memory implementation of the LimitCounter.

```APIDOC
## Local Limit Counter

### Description
An in-memory implementation of the `LimitCounter` interface.

### Functions

#### `NewLocalLimitCounter(windowLength time.Duration) *localCounter`
Creates a new instance of `localCounter`. All methods are guaranteed to always return `nil` error.

```

--------------------------------

### Handle rate limiting errors

Source: https://pkg.go.dev/github.com/go-chi/httprate

Define a custom error handler to manage errors returned by custom key functions or external backends.

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

--------------------------------

### Access RateLimiter Counter

Source: https://pkg.go.dev/github.com/go-chi/httprate

Retrieves the underlying LimitCounter for the rate limiter.

```go
func (l *RateLimiter) Counter() LimitCounter
```

--------------------------------

### Rate limit by request payload

Source: https://pkg.go.dev/github.com/go-chi/httprate

Manually trigger rate limiting logic within a handler based on parsed request body content.

```go
// 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"`
	}
	err := json.NewDecoder(r.Body).Decode(&payload)
	if err != nil || payload.Username == "" || payload.Password == "" {
		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"))
})
```

--------------------------------

### ResponseHeaders Type

Source: https://pkg.go.dev/github.com/go-chi/httprate

Defines custom response headers for rate limiting information.

```APIDOC
## ResponseHeaders Type

### Description
Allows customization of response headers used to convey rate limiting information. If a header field is empty, that specific header will be omitted from the response. Added in v0.11.0.

### Fields
- **Limit** (string) - The header name for the total request limit (Default: `X-RateLimit-Limit`).
- **Remaining** (string) - The header name for the remaining requests allowed (Default: `X-RateLimit-Remaining`).
- **Increment** (string) - The header name for the increment value (Default: `X-RateLimit-Increment`).
- **Reset** (string) - The header name for the time when the limit resets (Default: `X-RateLimit-Reset`).
- **RetryAfter** (string) - The header name for the time to wait before retrying (Default: `Retry-After`).

### Example Struct
```go
type ResponseHeaders struct {
	Limit      string
	Remaining  string
	Increment  string
	Reset      string
	RetryAfter string
}
```
```
Tokens:
Raw