ratelimiter

package module
v0.0.0-...-c96df02 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 16, 2024 License: MIT Imports: 6 Imported by: 0

README

Ratelimiter

Ratelimiter is a lightweight rate limiter for gin and orbit. It implements the token bucket algorithm and is designed to protect API endpoints.

Ratelimiter supports two modes:

  • IP-based: Each IP address has its own rate limit bucket.
  • Shared: All requests share the same rate limit bucket.

Ratelimiter is built using native Go packages and other powerful libraries:

It is designed to be safe for concurrent usage.

Installation

go get github.com/shengyanli1982/orbit-contrib/pkg/ratelimiter

Quick Start

Configuration

The Ratelimiter component has a configuration object that can be used to customize its behavior. The configuration object provides the following methods:

  • WithCallback: Sets the callback function. The default is &emptyCallback{}.
  • WithRate: Sets the rate. The default is float64(1).
  • WithBurst: Sets the burst. The default is 1.
  • WithMatchFunc: Sets the match function. The default is DefaultLimitMatchFunc.
  • WithIpWhitelist: Sets the IP whitelist. The default is DefaultIpWhitelist.
Components
1. Ratelimiter

The Ratelimiter component is the main component used for rate limiting requests.

Methods

  • GetLimiter: Retrieves the limiter.
  • SetRate: Sets the rate for the limiter in a thread-safe manner.
  • SetBurst: Sets the burst for the limiter in a thread-safe manner.
  • HandlerFunc: Returns a gin.HandlerFunc for orbit or gin.
  • Stop: Stops the limiter. This is an empty function and does not need to be called.

Example

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"

	"github.com/gin-gonic/gin"
	rl "github.com/shengyanli1982/orbit-contrib/pkg/ratelimiter"
)

var (
	// 测试URL
	// Test URL
	testUrl = "/test"
)

// testRequestFunc 是一个测试请求的函数
// testRequestFunc is a function to test the request
func testRequestFunc(idx int, router *gin.Engine, conf *rl.Config, url string) {
	// 创建一个新的请求
	// Create a new request
	req := httptest.NewRequest(http.MethodGet, url, nil)

	// 创建一个新的响应记录器
	// Create a new response recorder
	resp := httptest.NewRecorder()

	// 使用路由器处理HTTP请求
	// Use the router to handle the HTTP request
	router.ServeHTTP(resp, req)

	// 打印请求的信息
	// Print the information of the request
	fmt.Println("[Request]", idx, resp.Code, url)
}

func main() {
	// 创建一个新的配置，设置速率为2，突发数为5
	// Create a new configuration, set the rate to 2 and the burst to 5
	conf := rl.NewConfig().WithRate(2).WithBurst(5)

	// 创建一个新的速率限制器
	// Create a new rate limiter
	limiter := rl.NewRateLimiter(conf)

	// 在函数返回时停止速率限制器
	// Stop the rate limiter when the function returns
	defer limiter.Stop()

	// 创建一个新的路由器
	// Create a new router
	router := gin.New()

	// 使用速率限制器的处理函数
	// Use the handler function of the rate limiter
	router.Use(limiter.HandlerFunc())

	// 添加一个GET路由
	// Add a GET route
	router.GET(testUrl, func(c *gin.Context) {
		c.String(http.StatusOK, "OK")
	})

	// 测试 10 次请求
	// Test 10 requests
	for i := 0; i < 10; i++ {
		// 调用测试请求函数，传入索引、路由器、配置和测试URL
		// Call the test request function, passing in the index, router, configuration, and test URL
		testRequestFunc(i, router, conf, testUrl)
	}

	// 等待所有请求任务执行完毕
	// Wait for all request tasks to complete
	time.Sleep(time.Second)
}

Result

$ go run demo.go
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /test                     --> main.main.func1 (2 handlers)
[Request] 0 200 /test
[Request] 1 200 /test
[Request] 2 200 /test
[Request] 3 200 /test
[Request] 4 200 /test
[Request] 5 429 /test
[Request] 6 429 /test
[Request] 7 429 /test
[Request] 8 429 /test
[Request] 9 429 /test
2. Ip Ratelimiter

Methods

  • GetLimiter: Retrieves the limiter by key.
  • SetRate: Sets the rate for the limiter in a thread-safe manner.
  • SetBurst: Sets the burst for the limiter in a thread-safe manner.
  • HandlerFunc: Returns a gin.HandlerFunc for orbit or gin.
  • Stop: Stops the limiter and releases the associated resources.

Example

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"

	"github.com/gin-gonic/gin"
	rl "github.com/shengyanli1982/orbit-contrib/pkg/ratelimiter"
)

var (
	// 测试URL
	// Test URL
	testUrl = "/test"

	// 测试端口
	// Test port
	testPort = 13143

	// 测试IP地址1
	// Test IP address 1
	testIpAddress = "192.168.0.11"

	// 测试端点1
	// Test endpoint 1
	testEndpoint = fmt.Sprintf("%s:%d", testIpAddress, testPort)

	// 测试IP地址2
	// Test IP address 2
	testIpAddress2 = "192.168.0.12"

	// 测试端点2
	// Test endpoint 2
	testEndpoint2 = fmt.Sprintf("%s:%d", testIpAddress2, testPort)
)

// testRequestFunc 是一个测试请求的函数
// testRequestFunc is a function to test the request
func testRequestFunc(idx int, router *gin.Engine, conf *rl.Config, ep, url string) {
	// 创建一个新的请求
	// Create a new request
	req := httptest.NewRequest(http.MethodGet, url, nil)

	// 设置请求的远程地址
	// Set the remote address of the request
	req.RemoteAddr = ep

	// 创建一个新的响应记录器
	// Create a new response recorder
	resp := httptest.NewRecorder()

	// 使用路由器处理HTTP请求
	// Use the router to handle the HTTP request
	router.ServeHTTP(resp, req)

	// 打印请求的信息
	// Print the information of the request
	fmt.Println("[Request]", idx, resp.Code, ep, url)
}

func main() {
	// 创建一个新的配置，设置速率为2，突发数为5
	// Create a new configuration, set the rate to 2 and the burst to 5
	conf := rl.NewConfig().WithRate(2).WithBurst(5)

	// 创建一个新的IP速率限制器
	// Create a new IP rate limiter
	limiter := rl.NewIpRateLimiter(conf)

	// 在函数返回时停止速率限制器
	// Stop the rate limiter when the function returns
	defer limiter.Stop()

	// 创建一个新的路由器
	// Create a new router
	router := gin.New()

	// 使用速率限制器的处理函数
	// Use the handler function of the rate limiter
	router.Use(limiter.HandlerFunc())

	// 添加一个GET路由
	// Add a GET route
	router.GET(testUrl, func(c *gin.Context) {
		c.String(http.StatusOK, "OK")
	})

	// 测试 10 次请求
	// Test 10 requests
	for i := 0; i < 10; i++ {
		// 调用测试请求函数，传入索引、路由器、配置、端点和测试URL
		// Call the test request function, passing in the index, router, configuration, endpoint, and test URL
		testRequestFunc(i, router, conf, testEndpoint, testUrl)
	}

	// 测试 10 次请求
	// Test 10 requests
	for i := 0; i < 10; i++ {
		// 调用测试请求函数，传入索引、路由器、配置、端点和测试URL
		// Call the test request function, passing in the index, router, configuration, endpoint, and test URL
		testRequestFunc(i, router, conf, testEndpoint2, testUrl)
	}

	// 等待所有请求任务执行完毕
	// Wait for all request tasks to complete
	time.Sleep(time.Second)
}

Result

$ go run demo.go
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /test                     --> main.main.func1 (2 handlers)
[Request] 0 200 192.168.0.11:13143 /test
[Request] 1 200 192.168.0.11:13143 /test
[Request] 2 200 192.168.0.11:13143 /test
[Request] 3 200 192.168.0.11:13143 /test
[Request] 4 200 192.168.0.11:13143 /test
[Request] 5 429 192.168.0.11:13143 /test
[Request] 6 429 192.168.0.11:13143 /test
[Request] 7 429 192.168.0.11:13143 /test
[Request] 8 429 192.168.0.11:13143 /test
[Request] 9 429 192.168.0.11:13143 /test
[Request] 0 200 192.168.0.12:13143 /test
[Request] 1 200 192.168.0.12:13143 /test
[Request] 2 200 192.168.0.12:13143 /test
[Request] 3 200 192.168.0.12:13143 /test
[Request] 4 200 192.168.0.12:13143 /test
[Request] 5 429 192.168.0.12:13143 /test
[Request] 6 429 192.168.0.12:13143 /test
[Request] 7 429 192.168.0.12:13143 /test
[Request] 8 429 192.168.0.12:13143 /test
[Request] 9 429 192.168.0.12:13143 /test

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultLimitBurst = 1

DefaultLimitBurst 是默认的限制突发 DefaultLimitBurst is the default limit burst

View Source 
var DefaultLimitRatePerSecond = float64(1)

DefaultLimitRatePerSecond 是默认的每秒限制速率 DefaultLimitRatePerSecond is the default limit rate per second

Functions

This section is empty.

Types

type Callback 

type Callback interface {
	// OnLimited 是一个方法，当请求被限流时被调用，接收一个 http.Request 指针作为参数
	// OnLimited is a method that is called when a request is rate limited, it takes a pointer to http.Request as a parameter
	OnLimited(header *http.Request)
}

Callback 是一个限流回调接口，用于处理被限流的请求 Callback is a rate limiting callback interface for handling requests that are rate limited

type Config 

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

Config 是配置结构体，包含速率、突发、IP白名单、匹配函数和回调 Config is the configuration structure, including rate, burst, IP whitelist, match function and callback

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig 是一个函数，返回一个新的默认配置 DefaultConfig is a function that returns a new default configuration

func NewConfig 

func NewConfig() *Config

NewConfig 创建一个新的配置，包含默认的速率、突发、匹配函数、IP白名单和回调 NewConfig creates a new configuration, including default rate, burst, match function, IP whitelist and callback

func (*Config) WithBurst 

func (c *Config) WithBurst(burst int) *Config

WithBurst 是一个方法，接收一个整数作为参数，设置配置的突发，并返回配置 WithBurst is a method that takes an integer as a parameter, sets the burst of the configuration, and returns the configuration

func (*Config) WithCallback 

func (c *Config) WithCallback(callback Callback) *Config

WithCallback 是一个方法，接收一个回调作为参数，设置配置的回调，并返回配置 WithCallback is a method that takes a callback as a parameter, sets the callback of the configuration, and returns the configuration

func (*Config) WithIpWhitelist 

func (c *Config) WithIpWhitelist(whitelist []string) *Config

WithIpWhitelist 是一个方法，接收一个字符串切片作为参数，设置配置的 IP 白名单，并返回配置 WithIpWhitelist is a method that takes a slice of strings as a parameter, sets the IP whitelist of the configuration, and returns the configuration

func (*Config) WithMatchFunc 

func (c *Config) WithMatchFunc(fn com.HttpRequestHeaderMatchFunc) *Config

WithMatchFunc 是一个方法，接收一个匹配函数作为参数，设置配置的匹配函数，并返回配置 WithMatchFunc is a method that takes a match function as a parameter, sets the match function of the configuration, and returns the configuration

func (*Config) WithRate 

func (c *Config) WithRate(rate float64) *Config

WithRate 是一个方法，接收一个浮点数作为参数，设置配置的速率，并返回配置 WithRate is a method that takes a float as a parameter, sets the rate of the configuration, and returns the configuration

type IpRateLimiter 

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

IpRateLimiter 是一个结构体，包含配置和限流器 IpRateLimiter is a struct that contains configuration and rate limiter

func NewIpRateLimiter 

func NewIpRateLimiter(config *Config) *IpRateLimiter

NewIpRateLimiter 是一个函数，接收一个 Config 结构体的指针作为参数，返回一个新的 IpRateLimiter 结构体的指针 NewIpRateLimiter is a function that takes a pointer to the Config struct as a parameter and returns a new pointer to the IpRateLimiter struct

func (*IpRateLimiter) GetLimiter 

func (rl *IpRateLimiter) GetLimiter(key string) *rate.Limiter

GetLimiter 方法用于根据键获取限流器 The GetLimiter method is used to get the rate limiter based on the key

func (*IpRateLimiter) HandlerFunc 

func (rl *IpRateLimiter) HandlerFunc() gin.HandlerFunc

HandlerFunc 返回一个 gin.HandlerFunc，用于处理请求 HandlerFunc returns a gin.HandlerFunc for processing requests

func (*IpRateLimiter) SetBurst 

func (rl *IpRateLimiter) SetBurst(burst int)

SetBurst 方法用于设置限流器的突发流量 The SetBurst method is used to set the burst traffic of the rate limiter

func (*IpRateLimiter) SetRate 

func (rl *IpRateLimiter) SetRate(rate float64)

SetRate 方法用于设置限流器的速率 The SetRate method is used to set the rate of the rate limiter

func (*IpRateLimiter) Stop 

func (rl *IpRateLimiter) Stop()

Stop 方法用于停止 IP 限流器 The Stop method is used to stop the IP rate limiter

type RateLimiter 

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

RateLimiter 是一个结构体，包含配置和限流器 RateLimiter is a struct that contains configuration and rate limiter

func NewRateLimiter 

func NewRateLimiter(config *Config) *RateLimiter

NewRateLimiter 是一个函数，接收一个 Config 结构体的指针作为参数，返回一个新的 RateLimiter 结构体的指针 NewRateLimiter is a function that takes a pointer to the Config struct as a parameter and returns a new pointer to the RateLimiter struct

func (*RateLimiter) GetLimiter 

func (rl *RateLimiter) GetLimiter() *rate.Limiter

GetLimiter 方法用于获取限流器 The GetLimiter method is used to get the rate limiter

func (*RateLimiter) HandlerFunc 

func (rl *RateLimiter) HandlerFunc() gin.HandlerFunc

HandlerFunc 返回一个 gin.HandlerFunc，用于处理请求 HandlerFunc returns a gin.HandlerFunc for processing requests

func (*RateLimiter) SetBurst 

func (rl *RateLimiter) SetBurst(burst int)

SetBurst 方法用于设置限流器的突发流量 The SetBurst method is used to set the burst traffic of the rate limiter

func (*RateLimiter) SetRate 

func (rl *RateLimiter) SetRate(rate float64)

SetRate 方法用于设置限流器的速率 The SetRate method is used to set the rate of the rate limiter

func (*RateLimiter) Stop 

func (rl *RateLimiter) Stop()

Stop 方法用于停止限流器，但在这里没有实现任何功能 The Stop method is used to stop the rate limiter, but it does not implement any functionality here

Source Files

View all Source files

Directories

Path Synopsis
example
ip_ratelimiter
ratelimiter

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.