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.Limitfunction is used to create a new rate limiter. It takes three parameters:-
limit: The maximum number of requests allowed per second. -
burst: The maximum burst size. -
options: Additional options such asPurgeEveryfor cleaning up old entries.
-
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:
- Initialization: A bucket is initialized with a certain number of tokens.
- Token Addition: Tokens are added to the bucket at a fixed rate.
- Request Handling: Each request consumes a token. If the bucket is empty, the request is denied.
- 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.
Top comments (0)