go 47 lines · 7 steps

Rate limiting HTTP handlers with a token bucket

An http.Handler wrapper uses a token-bucket limiter to reserve, delay, or reject requests before passing them downstream.

Explained by highlit
Advanced rate-limiting token-bucket middleware concurrency context-cancellation
1package server
2 
3import (
4 "net/http"
5 "time"
6 
7 "golang.org/x/time/rate"
8)
9 
10type RateLimitedHandler struct {
11 next http.Handler
12 limiter *rate.Limiter
13}
14 
15func NewRateLimitedHandler(next http.Handler, rps float64, burst int) *RateLimitedHandler {
16 return &RateLimitedHandler{
17 next: next,
18 limiter: rate.NewLimiter(rate.Limit(rps), burst),
19 }
20}
21 
22func (h *RateLimitedHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
23 res := h.limiter.Reserve()
24 if !res.OK() {
25 http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
26 return
27 }
28 
29 if delay := res.Delay(); delay > 0 {
30 if delay > 2*time.Second {
31 res.Cancel()
32 w.Header().Set("Retry-After", delay.Round(time.Second).String())
33 http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
34 return
35 }
36 
37 select {
38 case <-time.After(delay):
39 case <-r.Context().Done():
40 res.Cancel()
41 http.Error(w, "request cancelled", http.StatusRequestTimeout)
42 return
43 }
44 }
45 
46 h.next.ServeHTTP(w, r)
47}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Wrapping an http.Handler lets you inject cross-cutting policy like rate limiting without touching downstream logic.
  2. 2Reserve gives you the wait time up front so you can choose to sleep, reject, or cancel instead of blocking blindly.
  3. 3Always honor request context cancellation and return reserved tokens when you bail out so capacity isn't wasted.

Related explainers

rust 
use axum::{
    extract::{FromRef, FromRequestParts},
    http::{header, request::Parts, StatusCode},
    RequestPartsExt,

How a JWT extractor works in Axum

jwt authentication extractors
Intermediate 8 steps
java 
public final class CircuitBreaker {
 
    private enum State { CLOSED, OPEN, HALF_OPEN }
 

How a circuit breaker guards failing calls

state-machine resilience concurrency
Advanced 7 steps
go 
package middleware
 
import (
	"fmt"

How a panic-recovery middleware works in Gin

middleware panic-recovery error-reporting
Intermediate 8 steps
php 
<?php
 
namespace App\Jobs;
 

Debouncing a Laravel shipping-rate job

queues debouncing atomic-locks
Advanced 9 steps
go 
func UploadDocument(c *gin.Context) {
	fileHeader, err := c.FormFile("file")
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "file is required"})

Handling multipart uploads in Gin

multipart-upload validation error-handling
Intermediate 9 steps
rust 
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
 
use axum::body::Body;

A maintenance-mode gate in Axum

middleware shared-state atomics
Intermediate 7 steps

Share this explainer

Here's the card — post it anywhere.

Rate limiting HTTP handlers with a token bucket — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code