ratelimiter

README

rate-limiter

This package provides a rate limiter in Go (Golang) with a middleware adaptable for Gin web servers.

Installation

• Download

  Type the following command in your terminal.

  go get github.com/go-redis/redis
  go get github.com/codeNino/ratelimiter
  

• Import

  import "github.com/go-redis/redis"
  import limiter "github.com/codeNino/ratelimiter"
  import "time"
  

---

Quickstart

• Create a limiter object

  // Set redis client
  rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379", Password: "", DB: 0})
  
  // set up rate limiter object
  cop := &limiter.RateLimiter{
      TotalLimit : 100, BurstLimit : 10,
      MaxTime :  time.Hour * 24,   BurstPeriod : time.Hour * 2
      Client : rdb,  TotalLimitPrefix : "TotalLimitPrefixForRandomService"
      BurstLimitPrefix : "BurstLimitPrefixForRandomService"
  }
  
  

• Add different rate limiter type middleware to controlling each route.

  server := gin.Default()
  
  // create middleware for 
  
  server.POST("/ExamplePost1", limiter.IPLimiter(cop), func(ctx *gin.Context) {
  	ctx.String(http.StatusOK, "Hello ExamplePost1")
  })
  
  server.GET("/ExampleGet1", limiter.UserLimiter(cop, "sample_user_id"), func(ctx *gin.Context) {
  	ctx.String(http.StatusOK, "Hello ExampleGet1")
  })
  
  err = server.Run(":8080")
  if err != nil {
  	log.Println("gin server error = ", err)
  }
  

---

Response

• When the consecutive requests and total request times is within limit, the request is allowed to continue.

• When limit is reached, the request is aborted and a 429 HTTP status code is sent.

---

---

License

All source code is licensed under the MIT License.

Documentation

Index

• func GetIPAddress(c *gin.Context) (string, error)
• func IPLimiter(limiter RateLimiter) gin.HandlerFunc
• func IPUserLimiter(limiter RateLimiter, user_id string) gin.HandlerFunc
• func UserLimiter(limiter RateLimiter, user_id string) gin.HandlerFunc
• type RateLimiter
  • func (limiter *RateLimiter) AllowConsecutiveRequest(user_params ...string) bool
  • func (limiter *RateLimiter) AllowRequest(user_params ...string) bool
  • func (limiter *RateLimiter) AllowWithinTotalRequests(user_params ...string) bool
  • func (limiter *RateLimiter) UpdateConsecutiveRequests(user_params ...string)
  • func (limiter *RateLimiter) UpdateRequest(user_params ...string)
  • func (limiter *RateLimiter) UpdateTotalRequests(user_params ...string)

Functions

func GetIPAddress

func GetIPAddress(c *gin.Context) (string, error)

func IPLimiter

func IPLimiter(limiter RateLimiter) gin.HandlerFunc

enforce rate limit based on ip address of client making the request

func IPUserLimiter

func IPUserLimiter(limiter RateLimiter, user_id string) gin.HandlerFunc

enforce rate limit based on ip address of client and user making the request

func UserLimiter

func UserLimiter(limiter RateLimiter, user_id string) gin.HandlerFunc

enforce rate limit based on the user making the request

Types

type RateLimiter

type RateLimiter struct {
	TotalLimit       int           // maximum allowed requests over all
	BurstLimit       int           // maximum allowed consecutive requests in a short burst
	MaxTime          time.Duration // period for maximum allowed requests
	BurstPeriod      time.Duration // period for short bursts
	Client           *redis.Client
	TotalLimitPrefix string // prefix for total limit key in memory cache
	BurstLimitPrefix string // prefix for bursts limit key in memory cache
}

RateLimiter is the limiter instance

func (*RateLimiter) AllowConsecutiveRequest

func (limiter *RateLimiter) AllowConsecutiveRequest(user_params ...string) bool

check if consecutive requests made within specified limit before accepting new user request

func (*RateLimiter) AllowRequest

func (limiter *RateLimiter) AllowRequest(user_params ...string) bool

check if consecutive and total requests made within specified limit before accepting new user request

func (*RateLimiter) AllowWithinTotalRequests

func (limiter *RateLimiter) AllowWithinTotalRequests(user_params ...string) bool

check if total requests made within specified limit before accepting new user request

func (*RateLimiter) UpdateConsecutiveRequests

func (limiter *RateLimiter) UpdateConsecutiveRequests(user_params ...string)

note consecutive requests in short bursts made with user parameters and update per new request made

func (*RateLimiter) UpdateRequest

func (limiter *RateLimiter) UpdateRequest(user_params ...string)

note consecutive and total requests in made with user parameters and update each as per new request made

func (*RateLimiter) UpdateTotalRequests

func (limiter *RateLimiter) UpdateTotalRequests(user_params ...string)

note total requests made with user parameters and update per new request made