limiter

README

gin- limiter

A simple gin middleware for IP limiter based on redis.

Installation

• Download

  Type the following command in your terminal.

  go get github.com/go-redis/redis/v8
  go get github.com/davidleitw/gin-limiter 
  

• Import

  import "github.com/go-redis/redis/v8"
  import limiter "github.com/davidleitw/gin-limiter"
  

---

Quickstart

• Create a limit middleware dispatcher object

  // Set redis client
  rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379", Password: "", DB: 0})
  
  dispatcher, err := limiter.LimitDispatcher("24-M", 100, rdb)
  
  if err != nil {
      log.Println(err)
  }
  
  

• Add a middleware to controlling each route.

  server := gin.Default()
  
  server.POST("/ExamplePost1", dispatcher.MiddleWare("4-M", 20), func(ctx *gin.Context) {
  	ctx.String(http.StatusOK, "Hello ExamplePost1")
  })
  
  server.GET("/ExampleGet1", dispatcher.MiddleWare("5-M", 10), func(ctx *gin.Context) {
  	ctx.String(http.StatusOK, "Hello ExampleGet1")
  })
  
  err = server.Run(":8080")
  if err != nil {
  	log.Println("gin server error = ", err)
  }
  

  See more examples HERE.

---

Response

• When the total of request times is within limit, we will write data to header.

  Return header:
  
  X-RateLimit-Limit-global     -> Request limit of a single ip can send request for the server. 
  X-RateLimit-Remaining-global -> Remaining times which single ip can send request for the server.
  X-RateLimit-Reset-global     -> Time to global limit reset. 
  
  X-RateLimit-Limit-single     -> Request limit of a single ip can send request for the single route.
  X-RateLimit-Remaining-single -> Remaining times which single ip can send request for the single route.
  X-RateLimit-Reset-single     -> Time to single route limit reset. 
  
  

• When global limit or single route limit is reached, a 429 HTTP status code is sent. and add the header with:

  Return header:
  
  If global remaining request time < 0
      return global limit reset time. 
  
  If single remaining request time < 0
      return this single route limit reset time.
  

---

Reference

• https://github.com/ulule/limiter
• https://github.com/jpillora/ipfilter
• https://github.com/KennyChenFight/dcard-simple-demo

---

If you want to know the updated progress, please check Ipfilter branch.

License

All source code is licensed under the MIT License.

Documentation

Index

• Constants
• Variables
• type Dispatcher
  • func LimitDispatcher(command string, limit int, rdb *redis.Client) (*Dispatcher, error)
  • func (dispatch *Dispatcher) GetDeadLine() int64
  • func (dispatch *Dispatcher) GetDeadLineWithString() string
  • func (dispathch *Dispatcher) GetLimit() int
  • func (dispatch *Dispatcher) GetSHAScript(index string) string
  • func (dispatch *Dispatcher) MiddleWare(command string, limit int) gin.HandlerFunc
  • func (dispatch *Dispatcher) ParseCommand(command string) (time.Duration, error)
  • func (dispatch *Dispatcher) UpdateDeadLine()

Constants

const ResetScript = `` /* 209-byte string literal not displayed */

const Script = `` /* 1745-byte string literal not displayed */

const TimeFormat = "2006-01-02 15:04:05"

for the deadline time format.

Variables

var (
	LimitError   = errors.New("Limit should > 0.")
	CommandError = errors.New("The command of first number should > 0.")
	FormatError  = errors.New("Please check the format with your input.")
	MethodError  = errors.New("Please check the method is one of http method.")
	ServerError  = errors.New("StatusInternalServerError, please wait a minute.")
)

self define error

Types

type Dispatcher

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

func LimitDispatcher

func LimitDispatcher(command string, limit int, rdb *redis.Client) (*Dispatcher, error)

create a limit dispatcher object with command and limit request number.

func (*Dispatcher) GetDeadLine

func (dispatch *Dispatcher) GetDeadLine() int64

get the deadline with unix time.

func (*Dispatcher) GetDeadLineWithString

func (dispatch *Dispatcher) GetDeadLineWithString() string

get the deadline with format 2006-01-02 15:04:05

func (*Dispatcher) GetLimit

func (dispathch *Dispatcher) GetLimit() int

get the limit

func (*Dispatcher) GetSHAScript

func (dispatch *Dispatcher) GetSHAScript(index string) string

func (*Dispatcher) MiddleWare

func (dispatch *Dispatcher) MiddleWare(command string, limit int) gin.HandlerFunc

func (*Dispatcher) ParseCommand

func (dispatch *Dispatcher) ParseCommand(command string) (time.Duration, error)

func (*Dispatcher) UpdateDeadLine

func (dispatch *Dispatcher) UpdateDeadLine()

update the deadline