Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-api

golang-gin-api

Verified

Build REST APIs with Go Gin. Use when creating Go web servers, adding Gin routes, writing handlers, or asking about middleware, binding, error handling, or project structure.

FileKindSize
SKILL.mdskill md10.0 KB
metadata.jsonconfig482 B
references/background-jobs-goroutine-and-pool.mdmarkdown3.5 KB
references/background-jobs-queue-and-shutdown.mdmarkdown3.5 KB
references/defensive-handler-patterns.mdmarkdown3.7 KB
references/error-handling-apperror.mdmarkdown4.1 KB
references/error-handling-recovery.mdmarkdown1.8 KB
references/error-handling-validation.mdmarkdown3.0 KB
references/file-uploads-cloud.mdmarkdown2.4 KB
references/file-uploads-local.mdmarkdown4.0 KB
references/middleware-core.mdmarkdown4.2 KB
references/middleware-logging-and-recovery.mdmarkdown3.3 KB
references/middleware-timeout-and-custom.mdmarkdown3.2 KB
references/rate-limiting-algorithms.mdmarkdown3.5 KB
references/rate-limiting-fallback.mdmarkdown2.3 KB
references/rate-limiting-headers.mdmarkdown1.8 KB
references/rate-limiting-peruser.mdmarkdown2.4 KB
references/rate-limiting-redis-sliding.mdmarkdown2.2 KB
references/rate-limiting-redis.mdmarkdown2.9 KB
references/rate-limiting-sliding-window.mdmarkdown2.2 KB
references/rate-limiting-tiered.mdmarkdown3.0 KB
references/routing-groups-and-versioning.mdmarkdown3.8 KB
references/routing-params-and-wildcards.mdmarkdown3.4 KB
references/routing-validators-and-limits.mdmarkdown2.4 KB
references/safe-context-extraction.mdmarkdown4.3 KB
references/server-handlers-and-errors.mdmarkdown3.6 KB
references/server-setup-and-routes.mdmarkdown3.9 KB
references/websocket-auth-and-keepalive.mdmarkdown3.5 KB
references/websocket-chat-handler.mdmarkdown1.5 KB
references/websocket-hub-and-client.mdmarkdown3.9 KB
references/websocket-setup-and-echo.mdmarkdown3.4 KB
references/websocket-shutdown-and-messages.mdmarkdown3.8 KB
references/websocket-testing.mdmarkdown3.8 KB

references/rate-limiting-algorithms.md

View on GitHub
# Rate Limiting — Algorithm Overview & In-Memory Token Bucket

See also: `rate-limiting-redis.md`, `rate-limiting-peruser.md`, `rate-limiting-tiered.md`, `rate-limiting-headers.md`, `rate-limiting-fallback.md`

## Algorithm Overview

| Algorithm | Accuracy | Memory | Distributed | Best For |
|---|---|---|---|---|
| Fixed window | Low (boundary burst) | O(1) | Yes (INCR) | Simple global caps |
| Token bucket | High | O(clients) | Yes (Lua) | Smooth traffic shaping |
| Sliding window counter | Medium-high | O(1) | Yes (INCR×2) | Accurate without per-request storage |
| Sliding window log | Exact | O(requests) | Yes (ZADD) | High-value APIs, low traffic |

**Token bucket** (via `golang.org/x/time/rate`) is best for single-node deployments — it allows short bursts while enforcing a long-term rate. **Sliding window counter** blends two fixed-window buckets for near-exact counts without storing individual timestamps. **Redis Lua** scripts ensure atomic check-and-decrement across instances.

Use **in-memory** when: single binary, simplicity matters, losing counts on restart is acceptable.
Use **Redis** when: multiple instances, counts must survive restarts, per-user billing accuracy required.

---

## In-Memory Token Bucket

`golang.org/x/time/rate` wraps the token bucket algorithm. Accepts a configurable cleanup interval and a done channel for clean shutdown.

```go
// pkg/middleware/rate_limiter_memory.go
package middleware

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

	"github.com/gin-gonic/gin"
	"golang.org/x/time/rate"
)

type clientLimiter struct {
	limiter  *rate.Limiter
	lastSeen time.Time
}

// MemoryRateLimiterConfig configures the in-memory rate limiter.
type MemoryRateLimiterConfig struct {
	Rate            rate.Limit
	Burst           int
	CleanupInterval time.Duration
	TTL             time.Duration
}

// MemoryRateLimiter limits requests per client IP using a token bucket.
// NOT suitable for multi-instance deployments — use RedisRateLimiter instead.
func MemoryRateLimiter(cfg MemoryRateLimiterConfig, done <-chan struct{}) gin.HandlerFunc {
	if cfg.CleanupInterval == 0 {
		cfg.CleanupInterval = time.Minute
	}
	if cfg.TTL == 0 {
		cfg.TTL = 3 * time.Minute
	}

	var mu sync.Mutex
	limiters := make(map[string]*clientLimiter)

	go func() {
		ticker := time.NewTicker(cfg.CleanupInterval)
		defer ticker.Stop()
		for {
			select {
			case <-ticker.C:
				mu.Lock()
				for ip, cl := range limiters {
					if time.Since(cl.lastSeen) > cfg.TTL {
						delete(limiters, ip)
					}
				}
				mu.Unlock()
			case <-done:
				return
			}
		}
	}()

	getLimiter := func(ip string) *rate.Limiter {
		mu.Lock()
		defer mu.Unlock()
		cl, ok := limiters[ip]
		if !ok {
			cl = &clientLimiter{limiter: rate.NewLimiter(cfg.Rate, cfg.Burst)}
			limiters[ip] = cl
		}
		cl.lastSeen = time.Now()
		return cl.limiter
	}

	return func(c *gin.Context) {
		ip := c.ClientIP()
		lim := getLimiter(ip)
		if !lim.Allow() {
			slog.WarnContext(c.Request.Context(), "rate limit exceeded", "ip", ip)
			c.Header("Retry-After", "1")
			c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{
				"error": "rate limit exceeded",
			})
			return
		}
		c.Next()
	}
}
```

**Usage:**

```go
done := make(chan struct{})
defer close(done)

r.Use(middleware.MemoryRateLimiter(middleware.MemoryRateLimiterConfig{
    Rate:  10,
    Burst: 20,
}, done))
```

**Why `done` channel:** The goroutine would leak if the server restarts or the router is rebuilt in tests. Closing `done` stops the ticker cleanly.

See also: `rate-limiting-sliding-window.md` for the sliding window counter implementation.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall