capacitor

Capacitor

A leaky-bucket rate limiter for Go, backed by Valkey. Atomic bucket logic runs server-side via a Lua script, making it safe for distributed deployments. Ships with drop-in net/http middleware.

Features

• Atomic leaky-bucket algorithm executed in a single Valkey round-trip
• Standard func(http.Handler) http.Handler middleware — works with http.ServeMux, chi, gorilla/mux, and any http.Handler-based router
• Configurable key extraction (IP, header, custom function)
• IETF RateLimit header fields on every response
• Fallback strategy when Valkey is unreachable (fail-open or fail-closed)
• Optional structured logging (log/slog) and metrics collection

Installation

go get codeberg.org/matthew/capacitor

Requires Go 1.22+ and a running Valkey (or Redis 7+) instance.

Quick Start

package main

import (
	"log"
	"net/http"
	"time"

	"github.com/valkey-io/valkey-go"
	"codeberg.org/matthew/capacitor"
)

func main() {
	client, err := valkey.NewClient(valkey.ClientOption{
		InitAddress: []string{"localhost:6379"},
	})
	if err != nil {
		log.Fatal(err)
	}

	limiter := capacitor.New(client, capacitor.Config{
		KeyPrefix: "rl",
		Capacity:  10,
		LeakRate:  1.0, // 1 token per second
		Timeout:   500 * time.Millisecond,
	})
	defer limiter.Close()

	mux := http.NewServeMux()
	mux.HandleFunc("GET /hello", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello, world!\n"))
	})

	rl := capacitor.NewMiddleware(limiter)

	log.Println("listening on :8080")
	http.ListenAndServe(":8080", rl(mux))
}

Configuration

Middleware Options

WithKeyFunc

Controls how the rate-limit key is derived from each request. Defaults to KeyFromRemoteIP.

// Rate-limit by API key header.
rl := capacitor.NewMiddleware(limiter,
	capacitor.WithKeyFunc(capacitor.KeyFromHeader("X-API-Key")),
)

Built-in key functions:

You can provide any func(*http.Request) string. Return an empty string to skip rate limiting for that request.

WithDenyHandler

Replaces the default plain-text 429 response.

rl := capacitor.NewMiddleware(limiter,
	capacitor.WithDenyHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusTooManyRequests)
		w.Write([]byte(`{"error":"rate limited"}`))
	})),
)

Limiter Options

Pass these to capacitor.New:

Response Headers

Every response includes standard rate-limit headers:

Direct Usage (Without Middleware)

You can call the limiter directly for non-HTTP use cases such as background workers or gRPC interceptors:

result, err := limiter.Attempt(ctx, "user:42")
if err != nil {
	// Valkey unreachable — result contains the fallback decision.
	log.Println("fallback used:", err)
}

if !result.Allowed {
	log.Printf("denied, retry after %s\n", result.RetryAfter)
}

Health Check

if err := limiter.HealthCheck(ctx); err != nil {
	log.Fatal("valkey unreachable:", err)
}

License

EUPL-1.2