ratelimit

README

RateLimit - Powerful Rate Limiter, support In-Memory and Redis-Based.

Installation

To install the package, run:

go get github.com/go-zoox/ratelimit

Getting Started

import (
  "testing"
  "github.com/go-zoox/ratelimit"
)

func main() {
	limiter := ratelimit.NewMemory("example", 10*time.Second, 2)

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		ip := strings.Split(r.RemoteAddr, ":")[0]
		limiter.Inc(ip)

		if limiter.IsExceeded(ip) {
			http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
			return
		}

		w.Header().Set("X-RateLimit-Remaing", fmt.Sprintf("%d", limiter.Remaining(ip)))
		w.Header().Set("X-RateLimit-Reset-After", fmt.Sprintf("%d", limiter.ResetAfter(ip)))
		w.Header().Set("X-RateLimit-Total", fmt.Sprintf("%d", limiter.Total(ip)))

		w.Write([]byte("Hello World!"))
	})

	fmt.Println("server start at http://127.0.0.1:8080")
	http.ListenAndServe(":8080", nil)
}

// 1. curl -I http://127.0.0.1:8080
// HTTP/1.1 200 OK
// X-Ratelimit-Remaing: 1
// X-Ratelimit-Reset-After: 10000
// X-Ratelimit-Total: 2
// Date: Sat, 04 Jun 2022 05:04:25 GMT
// Content-Length: 12
// Content-Type: text/plain; charset=utf-8

// 1. curl -I http://127.0.0.1:8080
// HTTP/1.1 200 OK
// X-Ratelimit-Remaing: 0
// X-Ratelimit-Reset-After: 8867
// X-Ratelimit-Total: 2
// Date: Sat, 04 Jun 2022 05:08:07 GMT
// Content-Length: 12
// Content-Type: text/plain; charset=utf-8

// 3. curl -I http://127.0.0.1:8080
// HTTP/1.1 429 Too Many Requests
// Content-Type: text/plain; charset=utf-8
// X-Content-Type-Options: nosniff
// Date: Sat, 04 Jun 2022 05:03:19 GMT
// Content-Length: 20

Inspired By

• abo/rerate - redis-based rate counter and rate limiter.
• go-zoox/counter - Simple Counter, used to count requests or other events, expecially RateLimit.

License

GoZoox is released under the MIT License.

Documentation

Index

• Variables
• type RateLimit
  • func New(bucket bucket.Bucket, namespace string, maxAge time.Duration, maxCount int64) *RateLimit
  • func NewMemory(namespace string, maxAge time.Duration, maxCount int64) *RateLimit
  • func NewRedis(namespace string, maxAge time.Duration, maxCount int64, ...) (*RateLimit, error)
  • func (r *RateLimit) IsExceeded(id string) bool
  • func (r *RateLimit) Remaining(id string) int64
  • func (r *RateLimit) ResetAfter(id string) int64
  • func (r *RateLimit) ResetAt(id string) int64
  • func (r *RateLimit) Status(id string) (*Status, error)
  • func (r *RateLimit) Total(id string) int64
• type Status

Variables

var Version = "1.2.1"

Version is the current version of the package.

Types

type RateLimit

type RateLimit struct {
	counter.Counter
	// contains filtered or unexported fields
}

RateLimit is a rate limiter, support custom bucket (memory, redis, other databases).

func New

func New(bucket bucket.Bucket, namespace string, maxAge time.Duration, maxCount int64) *RateLimit

New creates a new rate limiter.

func NewMemory

func NewMemory(namespace string, maxAge time.Duration, maxCount int64) *RateLimit

NewMemory creates a in-memory ratelimit.

func NewRedis

func NewRedis(namespace string, maxAge time.Duration, maxCount int64, cfg *bucket.RedisConfig) (*RateLimit, error)

NewRedis creates a redis-baed ratelimit.

func (*RateLimit) IsExceeded

func (r *RateLimit) IsExceeded(id string) bool

IsExceeded is the rate limit is exceeded.

func (*RateLimit) Remaining

func (r *RateLimit) Remaining(id string) int64

Remaining is the number of occurrences remaining during a period.

func (*RateLimit) ResetAfter

func (r *RateLimit) ResetAfter(id string) int64

ResetAfter is the time when the rate limit will be reset.

func (*RateLimit) ResetAt

func (r *RateLimit) ResetAt(id string) int64

ResetAt is the time when the rate limit will be reset.

func (*RateLimit) Status

func (r *RateLimit) Status(id string) (*Status, error)

Status is the status of the rate limit.

func (*RateLimit) Total

func (r *RateLimit) Total(id string) int64

Total is the total number of occurrences during a period.

type Status

type Status struct {
	Total     int64
	Remaining int64
	// the time when the rate limit will be reset, unit: milliseconds
	ResetAfter  int64
	IsExeceeded bool
}

Status is the status of the rate limit.