Gin

distlimit menyediakan adapter middleware native untuk aplikasi Gin melalui package github.com/balramadan/distlimit/middleware/gin.

---

Instalasi

Instal Gin dan distlimit menggunakan Go Modules:

go get github.com/gin-gonic/gin
go get github.com/balramadan/distlimit

---

Setup Dasar

Pasangkan middleware distlimit secara global atau per-route group pada router Gin Anda:

package main

import (
  "time"

  "github.com/balramadan/distlimit"
  "github.com/balramadan/distlimit/algorithm/tokenbucket"
  "github.com/balramadan/distlimit/driver/memory"
  distlimitgin "github.com/balramadan/distlimit/middleware/gin"
  "github.com/gin-gonic/gin"
)

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()),
  )

  r := gin.Default()

  // 2. Registrasi Middleware distlimit
  r.Use(distlimitgin.New(limiter))

  r.GET("/api/ping", func(c *gin.Context) {
    c.JSON(200, gin.H{"message": "pong"})
  })

  r.Run(":8080")
}

---

Opsi Konfigurasi

Konfigurasikan perilaku middleware dengan meneruskan opsi ke distlimitgin.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 *gin.Context) string	Fungsi kustom untuk mengekstrak key rate limit dari context Gin.
WithRouteLabeling(enable)	bool	Mengaktifkan pengiriman full route path Gin (c.FullPath()) 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:

r.Use(distlimitgin.New(
  limiter,
  distlimitgin.WithKeyFunc(func(c *gin.Context) string {
    if apiKey := c.GetHeader("X-API-Key"); apiKey != "" {
      return "api_key:" + apiKey
    }
    // Fallback ke alamat IP client
    return distlimitgin.ExtractClientIP(c, nil)
  }),
))

---

Response Header & Perilaku Error

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

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, Gin akan menghentikan eksekusi handler dan mengembalikan status HTTP 429 Too Many Requests.