README.md

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.