Echo v4 & v5

distlimit menyediakan adapter middleware native untuk Echo v4 (middleware/echo) dan Echo v5 (middleware/echov5).

---

Instalasi

Instal Echo dan distlimit menggunakan Go Modules:

# Untuk aplikasi Echo v4
go get github.com/labstack/echo/v4

# Untuk aplikasi Echo v5
go get github.com/labstack/echo/v5

go get github.com/balramadan/distlimit

---

Setup Dasar

Pasangkan middleware distlimit pada instance router Echo Anda:

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. Inisialisasi Driver & Limiter (100 request / menit)
  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. Registrasi Middleware distlimit
  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"))
}

---

Opsi Konfigurasi

Konfigurasikan perilaku middleware dengan meneruskan opsi ke distlimitecho.New(limiter, opts...):

Opsi	Tipe	Deskripsi
WithTrustedProxies(proxies)	[]string	Blok CIDR atau IP reverse proxy terpercaya untuk parsing IP yang aman.
WithKeyFunc(fn)	func(c echo.Context) string	Fungsi kustom untuk mengekstrak key rate limit dari context Echo.
WithRouteLabeling(enable)	bool	Mengaktifkan pengiriman path route Echo (c.Path()) ke label metrik.

---

Contoh Ekstraksi Key Kustom

Secara default, distlimit membatasi request berdasarkan alamat IP client. Anda dapat mengekstrak pengenal kustom seperti API Key atau Bearer Token menggunakan 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 ke alamat IP client
    return distlimitecho.ExtractClientIP(c, nil)
  }),
))

---

Response Header & Perilaku Error

Saat rate limiting aktif, distlimit secara otomatis menyisipkan header standar RFC 6585 ke dalam setiap response HTTP Echo:

Header	Deskripsi	Contoh
RateLimit-Limit	Kuota request maksimum dalam window aktif	100
RateLimit-Remaining	Sisa kuota request yang diizinkan dalam window aktif	99
RateLimit-Reset	Waktu dalam detik hingga kuota di-reset	45
X-RateLimit-Limit	Header legacy untuk kuota limit maksimum	100
X-RateLimit-Remaining	Header legacy untuk sisa kuota request	99
X-RateLimit-Reset	Header legacy untuk durasi reset dalam detik	45

Saat client melampaui kuota yang diizinkan, Echo akan menghentikan eksekusi dan mengembalikan status HTTP 429 Too Many Requests.