ratelimit

Documentation

Overview

Package ratelimit provides HTTP rate limiting for generated or user-owned request-time handlers.

Index

• Constants
• func Addon() gowdk.Addon
• func DefaultErrorHandler(writer http.ResponseWriter, _ *http.Request, err error)
• func DefaultLimitHandler(writer http.ResponseWriter, _ *http.Request, _ Result)
• func KeyByRemoteAddr(request *http.Request) string
• func WriteHeaders(writer http.ResponseWriter, result Result)
• type ErrorHandler
• type InMemoryOptions
• type InMemoryStore
  • func NewInMemoryStore(options InMemoryOptions) *InMemoryStore
  • func (store *InMemoryStore) Take(ctx context.Context, key string, limit int, window time.Duration, ...) (Result, error)
• type KeyFunc
• type LimitHandler
• type Limiter
  • func New(options Options) (*Limiter, error)
  • func (limiter *Limiter) AllowRequest(request *http.Request) (Result, error)
  • func (limiter *Limiter) Middleware(next http.Handler) http.Handler
• type Options
• type RedisClient
• type RedisOptions
• type RedisStore
  • func NewRedisStore(options RedisOptions) (*RedisStore, error)
  • func (store *RedisStore) Take(ctx context.Context, key string, limit int, window time.Duration, ...) (Result, error)
• type Result
• type Store

Constants

const (
	// ImportPath is the canonical Go import path for the rate-limit addon.
	ImportPath = "github.com/cssbruno/gowdk/addons/ratelimit"

	// HeaderLimit reports the configured request limit for the current window.
	HeaderLimit = "X-RateLimit-Limit"
	// HeaderRemaining reports how many requests remain in the current window.
	HeaderRemaining = "X-RateLimit-Remaining"
	// HeaderReset reports the Unix timestamp when the current window resets.
	HeaderReset = "X-RateLimit-Reset"
)

Functions

func Addon

func Addon() gowdk.Addon

Addon enables request-time rate limiting support.

func DefaultErrorHandler

func DefaultErrorHandler(writer http.ResponseWriter, _ *http.Request, err error)

DefaultErrorHandler writes HTTP 500 for limiter failures.

func DefaultLimitHandler

func DefaultLimitHandler(writer http.ResponseWriter, _ *http.Request, _ Result)

DefaultLimitHandler writes HTTP 429 for blocked requests.

func KeyByRemoteAddr

func KeyByRemoteAddr(request *http.Request) string

KeyByRemoteAddr returns the request RemoteAddr host. It intentionally ignores forwarded headers because those are only safe behind trusted proxy handling.

func WriteHeaders

func WriteHeaders(writer http.ResponseWriter, result Result)

WriteHeaders writes rate-limit metadata response headers.

Types

type ErrorHandler

type ErrorHandler func(http.ResponseWriter, *http.Request, error)

ErrorHandler writes the response for rate-limit store or configuration failures.

type InMemoryOptions

type InMemoryOptions struct {
	CleanupInterval time.Duration
}

InMemoryOptions configures the in-memory store.

type InMemoryStore

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

InMemoryStore stores fixed-window counters in the current process.

func NewInMemoryStore

func NewInMemoryStore(options InMemoryOptions) *InMemoryStore

NewInMemoryStore creates a concurrency-safe process-local store.

func (*InMemoryStore) Take

func (store *InMemoryStore) Take(ctx context.Context, key string, limit int, window time.Duration, now time.Time) (Result, error)

Take records one hit against a fixed window.

type KeyFunc

type KeyFunc func(*http.Request) string

KeyFunc returns the storage key for a request.

type LimitHandler

type LimitHandler func(http.ResponseWriter, *http.Request, Result)

LimitHandler writes the response for blocked requests.

type Limiter

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

Limiter applies fixed-window rate limits to HTTP requests.

func New

func New(options Options) (*Limiter, error)

New creates a fixed-window limiter.

func (*Limiter) AllowRequest

func (limiter *Limiter) AllowRequest(request *http.Request) (Result, error)

AllowRequest records a request and returns the rate-limit decision.

func (*Limiter) Middleware

func (limiter *Limiter) Middleware(next http.Handler) http.Handler

Middleware wraps an HTTP handler with rate limiting.

type Options

type Options struct {
	Limit        int
	Window       time.Duration
	Store        Store
	KeyFunc      KeyFunc
	LimitHandler LimitHandler
	ErrorHandler ErrorHandler
	Now          func() time.Time
}

Options configures a Limiter.

type RedisClient

type RedisClient interface {
	EvalInt64s(ctx context.Context, script string, keys []string, args ...string) ([]int64, error)
}

RedisClient adapts a Redis client to the rate limiter's fixed-window script. Implementations should run script atomically and return the Lua integer array.

type RedisOptions

type RedisOptions struct {
	Client    RedisClient
	KeyPrefix string
}

RedisOptions configures a Redis-backed store.

type RedisStore

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

RedisStore stores fixed-window counters in Redis.

func NewRedisStore

func NewRedisStore(options RedisOptions) (*RedisStore, error)

NewRedisStore creates a Redis-backed store without depending on a concrete Redis client package.

func (*RedisStore) Take

func (store *RedisStore) Take(ctx context.Context, key string, limit int, window time.Duration, now time.Time) (Result, error)

Take records one hit against a fixed window using one Redis Lua evaluation.

type Result

type Result struct {
	Key        string
	Limit      int
	Remaining  int
	Reset      time.Time
	RetryAfter time.Duration
	Allowed    bool
}

Result describes one rate-limit decision.

type Store

type Store interface {
	Take(ctx context.Context, key string, limit int, window time.Duration, now time.Time) (Result, error)
}

Store records fixed-window request hits. Redis-backed implementations should make Take atomic for one key.