Request Rate Limiting Middleware for Iris

Overview

The rate middleware provides rate limiting capabilities for the Iris web framework. It allows developers to control the rate of requests to their applications, ensuring fair usage and preventing abuse. The middleware is based on the token bucket algorithm, which is a popular method for rate limiting.

Installation

To use the rate middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v12/middleware/rate"        

Usage

Basic Setup

To use the rate limiter, you need to create an Iris application and register the middleware. Below is an example of how to set up the rate limiter:

package main

import (
	"time"

	"github.com/kataras/iris/v12"
	"github.com/kataras/iris/v12/middleware/rate"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	limit := rate.Limit(1, 5, rate.PurgeEvery(time.Minute, 5*time.Minute))
	app.Use(limit)

	app.Get("/", index)
	app.Get("/other", other)

	app.Listen(":8080")
}

func index(ctx iris.Context) {
	ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
	ctx.HTML("<h1>Other Page</h1>")
}        

This example allows 1 request per second with a maximum burst size of 5. It also purges old entries every minute if they haven't been seen for 5 minutes.

Using rate.Every Helper

This example demonstrates how to use the rate.Every helper to set up a rate limiter:

package main

import (
	"time"

	"github.com/kataras/iris/v12"
	"github.com/kataras/iris/v12/middleware/rate"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	// Use rate.Every helper to set up the rate limiter.
	limit := rate.Limit(rate.Every(time.Minute), 5)
	app.Use(limit)

	app.Get("/", index)
	app.Get("/other", other)

	app.Listen(":8080")
}

func index(ctx iris.Context) {
	ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
	ctx.HTML("<h1>Other Page</h1>")
}        

Using API Key for Rate Limiting

This example demonstrates how to set up a rate limiter that uses an API key instead of the client's remote IP address:

package main

import (
	"time"

	"github.com/kataras/iris/v12"
	"github.com/kataras/iris/v12/middleware/rate"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	// Use API key for rate limiting.
	app.Use(useAPIKey)

	limit := rate.Limit(rate.Every(time.Minute), 300, rate.PurgeEvery(5*time.Minute, 15*time.Minute))
	app.Use(limit)

	app.Get("/list", list)

	app.Listen(":8080")
}

func useAPIKey(ctx iris.Context) {
	apiKey := ctx.Header("X-API-Key")
	if apiKey == "" {
		ctx.StopWithStatus(iris.StatusForbidden)
		return
	}

	rate.SetIdentifier(ctx, apiKey)
	ctx.Next()
}

func list(ctx iris.Context) {
	ctx.JSON(iris.Map{"key": "value"})
}        

Custom Exceed Handler

This example demonstrates how to set a custom handler to be executed when the rate limit is exceeded:

package main

import (
	"time"

	"github.com/kataras/iris/v12"
	"github.com/kataras/iris/v12/middleware/rate"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	// Set a custom exceed handler.
	limit := rate.Limit(1, 5, rate.ExceedHandler(func(ctx iris.Context) {
		ctx.StopWithStatus(429)
	}))
	app.Use(limit)

	app.Get("/", index)
	app.Get("/other", other)

	app.Listen(":8080")
}

func index(ctx iris.Context) {
	ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
	ctx.HTML("<h1>Other Page</h1>")
}        

Custom Client Data

This example demonstrates how to store custom data for each client:

package main

import (
	"time"

	"github.com/kataras/iris/v12"
	"github.com/kataras/iris/v12/middleware/rate"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	// Store custom data for each client.
	limit := rate.Limit(1, 5, rate.ClientData(func(ctx iris.Context) any {
		return ctx.RemoteAddr()
	}))
	app.Use(limit)

	app.Get("/", index)
	app.Get("/other", other)

	app.Listen(":8080")
}

func index(ctx iris.Context) {
	ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
	ctx.HTML("<h1>Other Page</h1>")
}        

Explanation

• Rate Limiting: The rate.Limit function is used to create a new rate limiter. It takes three parameters:
• Token Bucket Algorithm: This algorithm controls the rate of requests by maintaining a bucket of tokens. Each request consumes a token, and tokens are added to the bucket at a fixed rate. If the bucket is empty, the request is denied.

Token Bucket Algorithm

The token bucket algorithm is a simple and efficient way to control the rate of requests. It works as follows:

1. Initialization: A bucket is initialized with a certain number of tokens.
2. Token Addition: Tokens are added to the bucket at a fixed rate.
3. Request Handling: Each request consumes a token. If the bucket is empty, the request is denied.
4. Burst Handling: The bucket can hold a maximum number of tokens, allowing for bursts of traffic.

For more details, refer to the Wikipedia article on Token Bucket.

Conclusion

This middleware provides a robust and flexible way to implement rate limiting in your Iris applications. By using the token bucket algorithm, it ensures fair usage and prevents abuse, making your application more reliable and secure.

For more examples and detailed usage, refer to the official Iris documentation.