checkpoint

README

Checkpoint

Installation

go get -u github.com/aidenfine/checkpoint

Quick Start

You can use checkpoint in two methods.

No config setup

import (
    checkpoint "github.com/aidenfine/checkpoint"
)
func main() {
    rateLimiterMiddleware := checkpoint.LimitByIp(25, 1, 1)
    httpHandler := rateLimiterMiddleware(http.DefaultServeMux)

    http.ListenAndServe(":8080", httpHandler)

}

Or with a config for people who require a little more customization.

import (
    checkpoint "github.com/aidenfine/checkpoint"
)
func main() {

	config := checkpoint.Config{
		IgnorePaths:     []string{"/logs"},
		MaxTokens:       25,
		RefillRate:      1,
		TokensPerRefill: 1,
		LimitMethod:     checkpoint.LimitByIp,
	}

    rateLimiterMiddleware := checkpoint.WithConfig(config)
    httpHandler := rateLimiterMiddleware(http.DefaultServeMux)

    http.ListenAndServe(":8080", httpHandler)

}

Performance

General Load:

• Target Rate: 25,000 req/s
• Duration: 30 seconds
• Total Requests: 750,000

General Summary:

Metric	Value
Request Rate	25,000 req/s
Actual Throughput	13,667 req/s (54.67% allowed)
Total Requests	750,000
Successful (200)	410,000 (54.67%)
Rate Limited (429)	340,000 (45.33%)

Latency:

Percentile	Latency
Mean	53.4 µs
p50	48.2 µs
p95	73.9 µs
p99	182.9 µs
Max	5.1 ms

Normal Load:

• Target Rate: 10,000 req/s
• Duration: 30 seconds
• Total Requests: 300,000

General Summary:

Metric	Value
Request Rate	10,000 req/s
Actual Throughput	10,000 req/s
Total Requests	30,000
Successful (200)	30,000 (100%)

Latency:

Percentile	Latency
Mean	45.4 µs
p50	40.4 µs
p95	63.2 µs
p99	144.7 µs
Max	3.0 ms

Documentation

Index

• func Limit(maxTokens, refillRate, tokensPerRefill int, config Config) func(next http.Handler) http.Handler
• func LimitByIp(maxTokens, refillRate, tokensPerRefill int, config Config) func(next http.Handler) http.Handler
• func LimitIpByEndpoint(maxTokens, refillRate, tokensPerRefill int, config Config) func(next http.Handler) http.Handler
• func MatchPathPattern(pattern, path string) bool
• func WithConfig(config Config) func(next http.Handler) http.Handler
• type ClientRequestData
• type Config
• type TokenBucket
  • func NewTokenBucket(maxTokens, refillRate int, tokensPerRefill int, config Config) *TokenBucket
  • func (tb *TokenBucket) Allow(ip string) (bool, int)
  • func (tb *TokenBucket) Handler(next http.Handler) http.Handler
  • func (tb *TokenBucket) SetClientForTest(ip string, tokens int, lastRequest time.Time)

Functions

func Limit

func Limit(maxTokens, refillRate, tokensPerRefill int, config Config) func(next http.Handler) http.Handler

func LimitByIp

func LimitByIp(maxTokens, refillRate, tokensPerRefill int, config Config) func(next http.Handler) http.Handler

func LimitIpByEndpoint

func LimitIpByEndpoint(maxTokens, refillRate, tokensPerRefill int, config Config) func(next http.Handler) http.Handler

func MatchPathPattern

func MatchPathPattern(pattern, path string) bool

func WithConfig

func WithConfig(config Config) func(next http.Handler) http.Handler

Types

type ClientRequestData

type ClientRequestData struct {
	LastRequest time.Time
	Tokens      int
}

type Config

type Config struct {
	IgnorePaths     []string `json:"ignorePaths" yaml:"ignorePaths"`
	MaxTokens       int      `json:"maxTokens" yaml:"maxTokens"`
	RefillRate      int      `json:"refillRate" yaml:"refillRate"`
	TokensPerRefill int      `json:"tokensPerRefill" yaml:"tokensPerRefill"`
	LimitMethod     func(maxTokens, refillRate, tokensPerRefill int, config Config) func(next http.Handler) http.Handler
}

type TokenBucket

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

func NewTokenBucket

func NewTokenBucket(maxTokens, refillRate int, tokensPerRefill int, config Config) *TokenBucket

func (*TokenBucket) Allow

func (tb *TokenBucket) Allow(ip string) (bool, int)

func (*TokenBucket) Handler

func (tb *TokenBucket) Handler(next http.Handler) http.Handler

func (*TokenBucket) SetClientForTest

func (tb *TokenBucket) SetClientForTest(ip string, tokens int, lastRequest time.Time)