ginbump

README

ginbump

Example Speedbump middleware for Gin

Usage:

Somewhere in your Gin engine setup code:

// Create a Redis client
client := redis.NewClient(&redis.Options{
    Addr:     "localhost:6379",
    Password: "",
    DB:       0,
})

// Limit the engine's or group's requests to a maximum of 100 requests per
// client per minute.
engineOrGroup.Use(ginbump.RateLimit(client, speedbump.PerMinuteHasher{}, 100))

after that, if clients stay within the limit, they won't notice anything. If they do go over the limit, the will get an HTTP 429 error (Too Many Requests) with the following content:

{
    "messages":["Rate limit exceeded. Try again in 1 minute from now"],
    "status":"error"
}

Documentation

Overview

Package ginbump provides an example Speedbump middleware for the Gin framework.

Index

• func GetRequesterAddress(r *http.Request) string
• func IsPublicIP(ip net.IP) bool
• func ParseForwarded(ipList string) string
• func RateLimit(client *redis.Client, hasher speedbump.RateHasher, max int64) gin.HandlerFunc
• func RateLimitLB(client *redis.Client, hasher speedbump.RateHasher, max int64) gin.HandlerFunc

Examples

• RateLimit

Functions

func GetRequesterAddress

func GetRequesterAddress(r *http.Request) string

GetRequesterAddress does a best effort lookup for the real IP address of the requester. Many load balancers (such as AWS's ELB) set a X-Forwarded-For header which can be used to determine the IP address of the client when the server is behind a load balancer.

It is possible however for the client to spoof this header if the load balancer is not configured to remove it from the request or if the server is accessed directly.

For uses such as rate limitting, only use this function if you can trust that the load balancer will strip the header from the client and that the server will not be directly accessible by the public (only though the load balancer).

func IsPublicIP

func IsPublicIP(ip net.IP) bool

IsPublicIP returns true if the given IP can be routed on the Internet

func ParseForwarded

func ParseForwarded(ipList string) string

ParseForwarded parses the value of the X-Forwarded-For Header and returns the IP address.

func RateLimit

func RateLimit(client *redis.Client, hasher speedbump.RateHasher, max int64) gin.HandlerFunc

RateLimit is a Gin middleware for rate limitting incoming requests based on the client's IP address.

The resulting middleware will use the client to talk to the Redis server. The hasher is used to keep track of counters and to provide an estimate of when the client should be able to do requests again. The limit per period is defined by the max.

Response format

Once a client reaches the imposed limit, they will receive a JSON response similar to the following:

{
  "messages":["Rate limit exceeded. Try again in 1 minute from now"],
  "status":"error"
}

Example

The following example shows how to set up a rate limitting middleware in Gin that allows 100 requests per client per minute.

// Create a Gin engine
router := gin.Default()

// Add a route
router.GET("/", func(c *gin.Context) {
	c.String(http.StatusOK, "hello world")
})

// Create a Redis client
client := redis.NewClient(&redis.Options{
	Addr:     "localhost:6379",
	Password: "",
	DB:       0,
})

// Limit the engine's requests to a maximum of 100 requests per client per
// minute.
router.Use(RateLimit(client, speedbump.PerMinuteHasher{}, 100))

// Start listening
router.Run(":8080")

func RateLimitLB

func RateLimitLB(client *redis.Client, hasher speedbump.RateHasher, max int64) gin.HandlerFunc

RateLimitLB is very similar to RateLimit but it takes the X-Forwarded-For header in cosideration when trying to figure the IP address of the client. This is useful for when running a server behind a load balancer or proxy.

However, this header can be spoofed by the client, so in some cases it could provide a way of getting around the rate limiter.

When using this middleware, make sure the load balancer will strip any X-Forwarded-For headers set by the client, and that the server will not be publicly accessible by the public, just the load balancer.