Echo v4 & v5

distlimit provides native middleware adapters for both Echo v4 (middleware/echo) and Echo v5 (middleware/echov5).

---

Installation

Install Echo and distlimit using Go Modules:

# For Echo v4 applications
go get github.com/labstack/echo/v4

# For Echo v5 applications
go get github.com/labstack/echo/v5

go get github.com/balramadan/distlimit

---

Basic Setup

Attach distlimit middleware to your Echo router instance:

package main

import (
  "time"

  "github.com/balramadan/distlimit"
  "github.com/balramadan/distlimit/algorithm/tokenbucket"
  "github.com/balramadan/distlimit/driver/memory"
  distlimitecho "github.com/balramadan/distlimit/middleware/echo"
  "github.com/labstack/echo/v4"
)

func main() {
  // 1. Initialize Driver & Limiter (100 requests / minute)
  memDriver := memory.New(5 * time.Minute)
  limiter, _ := distlimit.New(
    memDriver,
    distlimit.WithLimit(100),
    distlimit.WithWindow(1*time.Minute),
    distlimit.WithAlgorithm(tokenbucket.New()),
  )

  e := echo.New()

  // 2. Register distlimit Middleware
  e.Use(distlimitecho.New(limiter))

  e.GET("/api/ping", func(c echo.Context) error {
    return c.String(200, "pong")
  })

  e.Logger.Fatal(e.Start(":8080"))
}

---

Configuration Options

Configure the middleware behavior by passing options into distlimitecho.New(limiter, opts...) (or distlimitechov5.New(limiter, opts...)):

Option	Type	Description
WithTrustedProxies(proxies)	[]string	CIDR blocks or IPs of trusted reverse proxies for secure IP parsing.
WithKeyFunc(fn)	func(c echo.Context) string	Custom function to extract rate limit key from Echo context.
WithRouteLabeling(enable)	bool	Enables passing Echo route path (c.Path()) into metric labels.

---

Custom Key Extraction Example

By default, distlimit rate limits requests based on client IP addresses. You can extract custom identifiers like API Keys or Bearer Tokens using WithKeyFunc:

e.Use(distlimitecho.New(
  limiter,
  distlimitecho.WithKeyFunc(func(c echo.Context) string {
    if apiKey := c.Request().Header.Get("X-API-Key"); apiKey != "" {
      return "api_key:" + apiKey
    }
    // Fallback to client IP address
    return distlimitecho.ExtractClientIP(c, nil)
  }),
))

---

Response Headers & Error Behavior

When rate limiting is enforced, distlimit automatically injects standard RFC 6585 and legacy rate-limit headers into every Echo HTTP response:

Header	Description	Example
RateLimit-Limit	Configured maximum request quota in current window	100
RateLimit-Remaining	Remaining allowed requests in current window	99
RateLimit-Reset	Time in seconds until request quota resets	45
X-RateLimit-Limit	Legacy header for maximum request limit	100
X-RateLimit-Remaining	Legacy header for remaining request quota	99
X-RateLimit-Reset	Legacy header for reset duration in seconds	45

When a client exceeds the allowed quota, Echo halts execution and returns HTTP status 429 Too Many Requests.