redis_rate

README

Rate limiting for go-redis

package main

import (
    "fmt"
    "log"
    "net/http"
    "strconv"
    "time"

    "golang.org/x/time/rate"
    "github.com/molotovtv/redis_rate/v11"
    "github.com/redis/go-redis/v9"
)

func handler(w http.ResponseWriter, r *http.Request, rateLimiter *redis_rate.Limiter) {
    userID := "user-12345"
    limit := int64(5)

    count, delay, allowed := rateLimiter.AllowMinute(r.Context(), userID, limit)
    if !allowed {
        h := w.Header()
        h.Set("X-RateLimit-Limit", strconv.FormatInt(limit, 10))
        h.Set("X-RateLimit-Remaining", strconv.FormatInt(limit-count, 10))
        delaySec := int64(delay/time.Second)
        h.Set("X-RateLimit-Delay", strconv.FormatInt(delaySec, 10))
        http.Error(w, "API rate limit exceeded.", 429)
        return
    }

    fmt.Fprintf(w, "Hello world!\n")
    fmt.Fprint(w, "Rate limit remaining: ", strconv.FormatInt(limit-rate, 10))
}

func statusHandler(w http.ResponseWriter, r *http.Request, rateLimiter *redis_rate.Limiter) {
    userID := "user-12345"
    limit := int64(5)

    // With n=0 we just retrieve the current limit.
    count, delay, allowed := rateLimiter.AllowN(r.Context(), userID, limit, time.Minute, 0)
    fmt.Fprintf(w, "Current rate: %d", count)
    fmt.Fprintf(w, "Delay: %s", delay)
    fmt.Fprintf(w, "Allowed: %v", allowed)
}

func main() {
    ring := redis.NewRing(&redis.RingOptions{
        Addrs: map[string]string{
            "server1": "localhost:6379",
        },
    })
    limiter := redis_rate.NewLimiter(ring)
    // Optional.
    limiter.Fallback = rate.NewLimiter(rate.Every(time.Second), 100)

    http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
        handler(w, req, limiter)
    })

    http.HandleFunc("/status", func(w http.ResponseWriter, req *http.Request) {
        statusHandler(w, req, limiter)
    })

    http.HandleFunc("/favicon.ico", http.NotFound)
    log.Println("listening on localhost:8888...")
    log.Println(http.ListenAndServe("localhost:8888", nil))
}

Documentation

Index

• type Limiter
  • func NewLimiter(redis rediser) *Limiter
  • func (l *Limiter) Allow(ctx context.Context, name string, maxn int64, period time.Duration) (count int64, delay time.Duration, allow bool)
  • func (l *Limiter) AllowHour(ctx context.Context, name string, maxn int64) (count int64, delay time.Duration, allow bool)
  • func (l *Limiter) AllowMinute(ctx context.Context, name string, maxn int64) (count int64, delay time.Duration, allow bool)
  • func (l *Limiter) AllowN(ctx context.Context, name string, maxn int64, period time.Duration, n int64) (count int64, delay time.Duration, allow bool)
  • func (l *Limiter) AllowRate(ctx context.Context, name string, rateLimit rate.Limit) (delay time.Duration, allow bool)
  • func (l *Limiter) Reset(ctx context.Context, name string, period time.Duration) error
  • func (l *Limiter) ResetRate(ctx context.Context, name string, rateLimit rate.Limit) error

Types

type Limiter

type Limiter struct {

	// Optional fallback limiter used when Redis is unavailable.
	Fallback *rate.Limiter
	// contains filtered or unexported fields
}

Limiter controls how frequently events are allowed to happen.

func NewLimiter

func NewLimiter(redis rediser) *Limiter

func (*Limiter) Allow

func (l *Limiter) Allow(ctx context.Context, name string, maxn int64, period time.Duration) (count int64, delay time.Duration, allow bool)

Allow is shorthand for AllowN(name, max, period, 1).

func (*Limiter) AllowHour

func (l *Limiter) AllowHour(ctx context.Context, name string, maxn int64) (count int64, delay time.Duration, allow bool)

AllowHour is shorthand for Allow(name, maxn, time.Hour).

func (*Limiter) AllowMinute

func (l *Limiter) AllowMinute(ctx context.Context, name string, maxn int64) (count int64, delay time.Duration, allow bool)

AllowMinute is shorthand for Allow(name, maxn, time.Minute).

func (*Limiter) AllowN

func (l *Limiter) AllowN(
	ctx context.Context, name string, maxn int64, period time.Duration, n int64,
) (count int64, delay time.Duration, allow bool)

AllowN reports whether an event with given name may happen at time now. It allows up to maxn events within period, with each interaction incrementing the limit by n.

func (*Limiter) AllowRate

func (l *Limiter) AllowRate(ctx context.Context, name string, rateLimit rate.Limit) (delay time.Duration, allow bool)

AllowRate reports whether an event may happen at time now. It allows up to rateLimit events each second.

func (*Limiter) Reset

func (l *Limiter) Reset(ctx context.Context, name string, period time.Duration) error

Reset resets the rate limit for the name in the given rate limit period.

func (*Limiter) ResetRate

func (l *Limiter) ResetRate(ctx context.Context, name string, rateLimit rate.Limit) error

ResetRate resets the rate limit for the name and limit.