limiter, _ := goratelimit.New("redis://localhost:6379", goratelimit.PerMinute(100))
r.Use(middleware.RateLimit(limiter, middleware.KeyByIP))

import goratelimit "github.com/krishna-kudari/ratelimit"

limiter, _ := goratelimit.NewInMemory(goratelimit.PerMinute(100))

result, _ := limiter.Allow(ctx, "user:123")
if !result.Allowed {
    // result.RetryAfter tells the client exactly when to try again
}

limiter, _ := goratelimit.New("redis://localhost:6379", goratelimit.PerMinute(100))

import "github.com/krishna-kudari/ratelimit/middleware"

mux.Handle("/api/", middleware.RateLimit(limiter, middleware.KeyByIP)(handler))

limiter, _ := goratelimit.NewFixedWindow(
    100,  // max requests
    60,   // per 60 seconds
)

limiter, _ := goratelimit.NewSlidingWindow(100, 60)

limiter, _ := goratelimit.NewSlidingWindowCounter(100, 60)

limiter, _ := goratelimit.NewTokenBucket(
    100,  // capacity (max burst)
    10,   // refill rate per second
)

// Policing — excess requests are dropped immediately (fast 429)
limiter, _ := goratelimit.NewLeakyBucket(100, 10, goratelimit.Policing)

// Shaping — excess requests are queued (smooth output, adds delay)
limiter, _ := goratelimit.NewLeakyBucket(100, 10, goratelimit.Shaping)

limiter, _ := goratelimit.NewGCRA(
    16,  // sustained rate (requests per second)
    32,  // burst allowance
)

limiter, _ := goratelimit.NewCMS(
    100,   // requests per window
    60,    // window seconds
    0.01,  // 1% error rate
    0.001, // 0.1% failure probability
)

fmt.Println(goratelimit.CMSMemoryBytes(0.01, 0.001)) // 30,464 bytes — fixed forever

// Fast local sketch — no network calls, no Redis load during attacks
cms, _ := goratelimit.NewCMS(100, 60, 0.01, 0.001)

// Precise distributed limiter for traffic that passes the sketch
gcra, _ := goratelimit.NewGCRA(16, 32, goratelimit.WithRedis(client))

// Chain them — CMS runs first, GCRA only sees what CMS lets through
limiter := goratelimit.NewPreFilter(cms, gcra)

import "github.com/krishna-kudari/ratelimit/middleware"

mux.Handle("/api/", middleware.RateLimit(limiter, middleware.KeyByIP)(handler))

import "github.com/krishna-kudari/ratelimit/middleware/ginmw"

r.Use(ginmw.RateLimit(limiter, ginmw.KeyByClientIP))

import "github.com/krishna-kudari/ratelimit/middleware/echomw"

e.Use(echomw.RateLimit(limiter, echomw.KeyByRealIP))

import "github.com/krishna-kudari/ratelimit/middleware/fibermw"

app.Use(fibermw.RateLimit(limiter, fibermw.KeyByIP))

import "github.com/krishna-kudari/ratelimit/middleware/grpcmw"

grpc.ChainUnaryInterceptor(grpcmw.UnaryServerInterceptor(limiter, grpcmw.KeyByPeer))
grpc.ChainStreamInterceptor(grpcmw.StreamServerInterceptor(limiter, grpcmw.StreamKeyByPeer))

middleware.KeyByIP          // client IP
middleware.KeyByRealIP      // X-Forwarded-For aware, for proxied traffic
middleware.KeyByAPIKey      // Authorization header

// Per-tenant + per-route limiting — most SaaS APIs need exactly this
middleware.RateLimit(limiter, func(r *http.Request) string {
    return r.Header.Get("X-Tenant-ID") + ":" + r.URL.Path
})

limiter, _ := goratelimit.NewFixedWindow(60, 60,
    goratelimit.WithLimitFunc(func(ctx context.Context, key string) int64 {
        switch getPlan(ctx, key) {
        case "pro":         return 1_000
        case "enterprise":  return 100_000
        default:            return 60    // free tier
        }
    }),
)

import "github.com/krishna-kudari/ratelimit/cache"

// Checks in-process cache first. Only hits Redis on a miss.
// L1 hit: ~100ns. L2 Redis hit: ~1ms.
cached := cache.New(limiter, cache.WithTTL(100*time.Millisecond))

import "github.com/krishna-kudari/ratelimit/metrics"

collector := metrics.NewCollector()
limiter = metrics.Wrap(limiter, metrics.GCRA, collector)

// Automatically exposes:
// ratelimit_requests_total{algorithm="gcra", result="allowed|denied"}
// ratelimit_request_duration_seconds{quantile="0.5|0.95|0.99"}

limiter, _ := goratelimit.NewGCRA(100, 20,
    goratelimit.WithRedis(clusterClient),
    goratelimit.WithHashTag(), // keys become {user:123} for correct slot routing
)

goratelimit.WithFailOpen(true)  // allow requests if Redis is down (default)
goratelimit.WithFailOpen(false) // deny requests if Redis is down

limiter, _ := goratelimit.NewBuilder().
    SlidingWindowCounter(100, 60*time.Second).
    Redis(client).
    HashTag().
    Build()

// Auto-selects in-memory or Redis based on URL
New(redisURL string, rate Rate, opts ...Option) (Limiter, error)
NewInMemory(rate Rate, opts ...Option) (Limiter, error)

// Algorithm-specific
NewFixedWindow(maxRequests, windowSeconds int64, opts ...Option) (Limiter, error)
NewSlidingWindow(maxRequests, windowSeconds int64, opts ...Option) (Limiter, error)
NewSlidingWindowCounter(maxRequests, windowSeconds int64, opts ...Option) (Limiter, error)
NewTokenBucket(capacity, refillRate int64, opts ...Option) (Limiter, error)
NewLeakyBucket(capacity, leakRate int64, mode LeakyBucketMode, opts ...Option) (Limiter, error)
NewGCRA(rate, burst int64, opts ...Option) (Limiter, error)
NewCMS(limit, windowSeconds int64, epsilon, delta float64, opts ...Option) (Limiter, error)
NewPreFilter(local, precise Limiter) Limiter

// Builder
NewBuilder() *Builder
CMSMemoryBytes(epsilon, delta float64) int

PerSecond(n int64) Rate
PerMinute(n int64) Rate
PerHour(n int64) Rate

type Limiter interface {
    Allow(ctx context.Context, key string) (*Result, error)
    AllowN(ctx context.Context, key string, n int) (*Result, error)
    Reset(ctx context.Context, key string) error
}

type Result struct {
    Allowed    bool
    Remaining  int64
    Limit      int64
    ResetAt    time.Time
    RetryAfter time.Duration  // how long to wait before retrying (only meaningful when !Allowed)
}