Forem: Maksat Ramazan

I Made My Go Linter Talk to Claude ? Here's What I Learned About MCP

Maksat Ramazan — Fri, 15 May 2026 08:25:04 +0000

I built a fun side project ? a Go static analyzer that finds code smells. Then I made it work with Claude Code via MCP (Model Context Protocol). Now AI can roast your Go code automatically.

Repo: github.com/aqylsoft/godepvis

The Problem I Didn't Know I Had

You know that moment when you're reviewing a PR and you see a 200-line function? Or a method with 9 parameters? Or someone using context.Background() right next to a perfectly good ctx?

These things aren't bugs. They compile fine. Tests pass. But they make you go "hmm" and reach for the comment button.

I wanted a tool that catches these patterns automatically. Not to replace code review ? but to handle the boring "hey, this function is too long" comments so humans can focus on actual logic.

Golangci-lint is great, but configuring it to catch architectural smells requires yoga-level flexibility. I wanted something opinionated and simple.

So I built godepvis.

What godepvis Actually Detects

I call them "sins" because "code smells" sounds too polite. Here's what the tool catches:

The Heavy Hitters

huge_function ? Functions over 50 lines. Yes, 50 is arbitrary. No, I won't debate it.

// Sin detected at user_service.go:45
func (s *UserService) CreateUser(ctx context.Context, req CreateUserRequest) (*User, error) {
    // ... 87 lines of validation, database calls,
    // event publishing, logging, and existential dread
}

huge_main ? The classic "I'll refactor it later" main.go that somehow handles config, DI, server setup, graceful shutdown, and your emotional baggage.

too_many_params ? Functions with 6+ parameters. Usually a sign you need a struct.

// Sin: 8 parameters. Your function is not a phone number.
func processOrder(ctx context.Context, userID, orderID, productID string,
    quantity int, discount float64, notify bool, logger *slog.Logger) error

The Subtle Ones

context_misuse ? Using context.Background() when you already have ctx in scope. This one's sneaky because it works, but breaks cancellation and tracing.

func (h *Handler) Handle(ctx context.Context, event Event) error {
    // ...
    result, err := h.client.Call(context.Background()) // Sin! Use ctx
    // ...
}

no_tests ? Packages without _test.go files. Sometimes intentional, often forgotten.

todo_comments ? Those "I'll fix it tomorrow" comments from 2019.

The MCP Adventure

Here's where the weekend project became interesting.

What is MCP?

Model Context Protocol is Anthropic's way of letting AI assistants use external tools. Instead of the AI guessing or asking you to run commands, it can just... call your tool directly.

Think of it as giving Claude hands to use your CLI.

The Implementation

MCP is surprisingly simple. It's JSON-RPC over stdio. Your tool:

Receives a JSON request
Does the thing
Returns a JSON response

Here's the core of my MCP handler:

func (s *MCPServer) handleToolCall(name string, args map[string]any) (any, error) {
    switch name {
    case "analyze_code":
        path, _ := args["path"].(string)
        maxIssues, _ := args["max_issues"].(string)
        return s.analyzeCode(path, maxIssues)
    case "list_sin_types":
        return s.listSinTypes()
    default:
        return nil, fmt.Errorf("unknown tool: %s", name)
    }
}

The protocol handles capability negotiation, tool discovery, and error formatting. You just implement your logic.

What Claude Sees

When you add godepvis to Claude Code's MCP config, it gets two new tools:

analyze_code ? Run the analyzer on a path
list_sin_types ? Show what sins we can detect

Now conversations like this work:

User: analyze my Go code for smells

Claude: I'll run godepvis on your project.

*calls analyze_code tool*

Found 20 issues in 519 files:

? huge_main `cmd/consumer/main.go:42`
   main() is 164 lines ? consider extracting setup logic

? context_misuse `handler.go:120`
   Using context.Background() but ctx is available in scope

? too_many_params `main.go:157`
   runWorkerLoop has 8 parameters ? consider a config struct

Want me to help refactor any of these?

The AI doesn't just report problems ? it can actually suggest fixes because it knows the exact location and context.

Lessons Learned (The Hard Way)

1. Keep Responses Concise

My first version returned every detail about every sin. Claude's context window filled up fast on large codebases. Now I return summaries with file:line references.

2. Validate Inputs Religiously

AI will send weird stuff. Empty strings. Null values. Paths that don't exist. The number 42 as a string when you expected an int.

maxIssues := 20 // default
if v, ok := args["max_issues"].(string); ok && v != "" {
    if parsed, err := strconv.Atoi(v); err == nil {
        maxIssues = parsed
    }
}

3. Errors Should Be Helpful

When something fails, the AI will show your error to the user or try to fix it. Make errors actionable:

// Bad
return nil, errors.New("failed")

// Good
return nil, fmt.Errorf("path %q does not exist or is not a Go module", path)

4. Test With Real AI Usage

Unit tests are great. But run your tool through Claude a few times. You'll find edge cases you never imagined.

The Architecture (Such As It Is)

godepvis/
??? cmd/godepvis/       # CLI entry point
??? internal/
?   ??? analyzer/       # The actual code analysis
?   ??? mcp/            # MCP server implementation
?   ??? sins/           # Sin definitions and detection
??? go.mod

The analyzer walks Go AST, the sins package defines what to look for, and the MCP server wraps it for AI consumption.

Nothing fancy. ~1500 lines of Go. The kind of codebase you can read in an afternoon.

Try It Yourself

CLI Mode

go install github.com/aqylsoft/godepvis@latest

# Analyze current directory
godepvis analyze ./...

# Analyze specific path
godepvis analyze /path/to/your/project

With Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "godepvis": {
      "command": "godepvis",
      "args": ["mcp"]
    }
  }
}

Restart Claude Code. Now you can ask it to analyze your Go code.

Is This Production Ready?

Let me be real: this is a weekend project.

The detections work. The MCP integration is solid. But I built this to learn, not to replace your existing tooling.

That said:

It found real issues in my work codebase
The MCP pattern is reusable for other tools
It's fun to watch AI roast your code

What's Next?

Ideas I might implement (PRs welcome):

Severity levels ? Not all sins are equal
Auto-fix suggestions ? Generate the refactored code
More sins ? Naked returns, error shadowing, import cycles
Ignore patterns ? Sometimes long functions are okay
VS Code extension ? Because why not

Wrapping Up

MCP is the real discovery here. The protocol is simple, the integration is smooth, and suddenly your CLI tools become AI capabilities.

godepvis is just one example. Imagine:

Database migration tools that AI can run
Infrastructure linters AI can invoke
Custom validators for your domain

The barrier between "tool I use" and "tool AI uses" just got a lot lower.

What code smells annoy you the most? I'm looking for new sins to detect. Drop ideas in the comments.

First time writing about AI tooling. First time publishing a Go analyzer. First time implementing MCP. Lots of firsts. Be gentle, but honest.

GitHub: aqylsoft/godepvis

Why Your Retry Logic Is Silently Charging Customers Twice

Maksat Ramazan — Tue, 12 May 2026 15:37:21 +0000

You've seen this bug. Maybe you've shipped it.

Client sends a payment request. Network hiccups. Client doesn't get a response, so it retries. Your handler runs twice. Two charges. One very angry customer.

This isn't a race condition. It's not a bug in your database layer. It's a missing contract between the client and the server: idempotency.

What idempotency actually means in HTTP

An HTTP endpoint is idempotent if calling it multiple times with the same input produces the same result — and more importantly, the same effect.

GET is idempotent by definition. DELETE usually is. POST /payments is not — unless you build it that way.

The pattern Stripe, Adyen, and most serious payment APIs use is the Idempotency-Key header: the client generates a unique key (usually a UUID) and sends it with every request. The server caches the response and returns it on any subsequent request with the same key, without re-executing the handler.

Simple idea. Surprisingly few Go libraries implement it correctly.

I built once because I wanted something that handles the edge cases right — per-key locking, double-check pattern, configurable caching — without pulling in a framework. If you already have a solution you're happy with, this article might still be useful for the reasoning behind the implementation. If you don't, here's one that works.

The problems that make this non-trivial

Before jumping to code, here's what makes a naive implementation break in production.

1. Thundering herd on the first request

Ten retries arrive simultaneously. The key doesn't exist in the store yet. All ten pass the cache check, all ten acquire the handler. You've now processed the request ten times.

The fix is a per-key lock: the first goroutine acquires it, executes the handler, stores the result. The other nine wait, then hit the cache. But locking introduces its own problem — you need a double-check after acquiring the lock, because another goroutine may have already written the result while you were waiting.

2. What to cache when the handler fails

If your handler returns a 500, do you cache that? If yes, retries get a cached error instead of a real retry. If no, the thundering herd problem is back for any request that fails.

The right answer: make it configurable. Cache only 200, 201, 204 by default. Let the caller decide what counts as a final response.

3. Same key, different body

Client sends key abc with amount=100. Something goes wrong client-side. It resends key abc with amount=200. If you just return the cached response, you've silently ignored a changed request.

Stripe returns 422 in this case. You should too — optionally, since the hash check has a cost.

4. Concurrent lock on the same key in progress

If a request is actively being processed (lock held), a duplicate arriving at that exact moment shouldn't wait — it should get 409 Conflict immediately, so the client knows to back off and retry later rather than pile up.

Building it as middleware

I wanted something that drops into any net/http stack without dependencies, with a pluggable store interface — the same approach I used for circuitbreaker.

The core interface:

type Store interface {
    Get(ctx context.Context, key string) (*Response, bool)
    Set(ctx context.Context, key string, resp *Response, ttl time.Duration) error
    Lock(ctx context.Context, key string) (unlock func(), err error)
}

The middleware logic, simplified:

func New(store Store, opts ...Option) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            key := r.Header.Get(cfg.header)

            // No key: pass through or reject, depending on config
            if key == "" {
                if cfg.requireKey {
                    http.Error(w, "Idempotency-Key header is required", http.StatusBadRequest)
                    return
                }
                next.ServeHTTP(w, r)
                return
            }

            // Cache hit: return stored response
            if cached, found := store.Get(ctx, key); found {
                cached.writeTo(w)
                return
            }

            // Acquire per-key lock
            unlock, err := store.Lock(ctx, key)
            if err == ErrLocked {
                http.Error(w, "Request in progress", http.StatusConflict)
                return
            }
            defer unlock()

            // Double-check after lock (another goroutine may have written it)
            if cached, found := store.Get(ctx, key); found {
                cached.writeTo(w)
                return
            }

            // Execute handler, capture response
            rw := newResponseWriter(w)
            next.ServeHTTP(rw, r)

            // Store only if status is considered final
            if cfg.cacheableStatus[rw.statusCode] {
                store.Set(ctx, key, rw.toResponse(requestHash), cfg.ttl)
            }
        })
    }
}

The double-check after acquiring the lock is what separates a correct implementation from one that looks correct in testing and fails at 3am.

Response capture

To cache what the handler wrote, you need to intercept writes to http.ResponseWriter. The standard approach — wrap it:

type responseWriter struct {
    http.ResponseWriter
    statusCode int
    body       []byte
}

func (rw *responseWriter) WriteHeader(code int) {
    rw.statusCode = code
    rw.ResponseWriter.WriteHeader(code)
}

func (rw *responseWriter) Write(b []byte) (int, int) {
    rw.body = append(rw.body, b...)
    return rw.ResponseWriter.Write(b)
}

This captures both the status code and body, so you can store a complete response and replay it exactly on cache hits.

Usage

store := once.NewMemoryStore()
defer store.Stop()

middleware := once.New(store,
    once.WithTTL(24*time.Hour),
    once.WithRequireKey(true),
    once.WithRequestHashCheck(true),
)

http.Handle("/payments", middleware(paymentHandler))

Client side:

POST /payments HTTP/1.1
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{"amount": 100, "currency": "USD"}

First request: handler executes, response cached, X-Idempotent-Replayed: false.

Any repeat with the same key: cached response returned, X-Idempotent-Replayed: true, handler never touched.

HTTP semantics

Status	Meaning
`200`	Cached response replayed
`400`	Key required but missing
`409`	Same key currently in flight
`422`	Key exists but request body differs

Request body validation

When WithRequestHashCheck(true) is set, the middleware computes a SHA-256 of the request body and stores it alongside the response. On subsequent requests with the same key, it compares hashes — if they differ, it returns 422 instead of the cached result.

func hashRequestBody(r *http.Request) string {
    body, _ := io.ReadAll(r.Body)
    r.Body = io.NopCloser(bytes.NewReader(body)) // restore for handler
    h := sha256.Sum256(body)
    return hex.EncodeToString(h[:])
}

One detail: after reading the body for hashing, you must restore r.Body — otherwise the handler sees an empty body. Easy to miss, painful to debug.

Benchmarks

Measured on Intel Core i7-1355U:

Scenario	ns/op
Cache hit	2,834
Cache hit (parallel)	3,427
Cache miss (first write)	4,429
Passthrough (no key)	2,716
With body hash check	4,632
Thundering herd (100 goroutines)	618,231 total / 6,182 per goroutine

Cache hits are cheap. The thundering herd test launches 100 concurrent goroutines for the same key — only one executes the handler, the rest wait and read from cache. The total time looks large; the per-goroutine cost is reasonable.

C shared library

There's a cgo subpackage that compiles once into a shared library (libonce.so) with a C API:

void once_init(void);
int  once_check(char* key, char* response, int responseLen);
int  once_store(char* key, int statusCode, char* body, int bodyLen, int ttlSeconds);
int  once_lock(char* key);
void once_unlock(int lockId);

This lets you use the same idempotency logic from PHP, Python, or any language with FFI — useful if you have a mixed-stack service where you want consistent behavior without reimplementing the semantics.

What this doesn't cover

In-memory store means the cache doesn't survive restarts and isn't shared across instances. For multi-instance deployments, you need a Redis-backed store. The Store interface is designed for that — a Redis implementation is a thin wrapper around SET NX PX for locking and regular GET/SET for caching.

Also: this middleware handles HTTP-level idempotency. If your handler does external calls (third-party payment APIs, email sends), those need their own idempotency handling. The middleware can't protect you from non-idempotent side effects outside your service.

The library

github.com/aqylsoft/once

go get github.com/aqylsoft/once

Zero external dependencies for the core package. MIT license.

If you're building anything that takes money, sends notifications, or mutates state in response to external events — you probably need this.

How a “Kind of Working” Payment Gateway Made Me Write This Circuit Breaker

Maksat Ramazan — Tue, 31 Mar 2026 11:58:11 +0000

I got bored and wrote a circuit breaker

A few years ago I was working at a fintech company. We had an integration with a payment gateway. Critical one — money literally depended on it.

One day it started behaving weird.

Not down. Not healthy. Just slow enough to destroy everything.

Requests were hanging. Threads piling up. Retries amplifying the problem. Other services started lagging. The gateway was still responding — just slowly enough to kill us.

We needed a circuit breaker. We didn't have one. So we hacked something together in production. Ugly, tightly coupled, impossible to test.

Fast forward to now — I built the circuit breaker I wish we had back then.

Show me the code

breaker, _ := circuitbreaker.New("stripe",
    cb.WithConsecutiveFailures(5),
    cb.WithOpenTimeout(30*time.Second),
)

err := breaker.Execute(ctx, func() error {
    return stripeClient.Charge(amount)
})

if errors.Is(err, cb.ErrCircuitOpen) {
    // fallback or fail fast
}

That's it. Wrap any unreliable call — payment gateways, external APIs, legacy services, that one dependency that "kinda works".

Why not just use timeouts?

Timeouts protect your goroutine.
Circuit breakers protect your system.

When a dependency becomes slow:

retries multiply the load
queues grow
latency spreads
healthy parts fail because of one sick dependency

Circuit breaker says: "nope, not calling this for a while". System breathes again.

What's inside

Two trip strategies:

// Trip after N consecutive failures
cb.WithConsecutiveFailures(5)

// Trip when error rate exceeds threshold in time window
cb.WithSlidingWindow(time.Minute, 0.5, 10) // 50% errors, min 10 requests

State machine:

Closed → Open → Half-Open → Closed
         ↑___________|  (probe fails)

Distributed support:

// Share state across instances via Redis
store := redisstore.New(redisClient)
breaker, _ := cb.New("stripe", cb.WithStore(store))

The numbers

BenchmarkExecute_Closed-8     89 ns/op    0 B/op    0 allocs/op
BenchmarkExecute_Open-8       15 ns/op    0 B/op    0 allocs/op
BenchmarkExecute_Parallel-8   45 ns/op    0 B/op    0 allocs/op

Zero allocations in the hot path. No background goroutines. No magic.

Design constraints

Rule	Why
No background workers	Predictable resource usage
No framework coupling	Drop into any codebase
Explicit configuration	No surprises in production
Simple state machine	Easy to reason about at 3 AM

~500 lines of code. One dependency (Redis client, optional).

Features

Consecutive failure counting
Sliding window with error rate threshold
Configurable half-open probes
Custom failure detection (WithIsFailure)
State change callbacks (WithOnStateChange)
Redis store for distributed systems
Thread-safe, race-free

Installation

go get github.com/aqylsoft/circuitbreaker
go get github.com/aqylsoft/circuitbreaker/redisstore # optional

The real reason this exists

I still remember staring at dashboards at 3 AM, watching everything slow down because of one broken dependency, and thinking: "we should have done this properly from day one".

This is me doing it properly. Years later.

GitHub: https://github.com/aqylsoft/circuitbreaker

PRs and issues welcome. If this is useful — a star would be nice.

Zero-Dependency HTTP Fingerprinting Library in Go: Bot Detection with JA3

Maksat Ramazan — Fri, 13 Mar 2026 12:56:53 +0000

Last month I was building an API for a fintech project. We had rate limiting in place (using kazrl, actually), but bots kept slipping through. They'd rotate IPs, spoof User-Agents, and our simple checks were useless.

I needed something smarter. Something that could identify clients by how they make requests, not just what they send.

That's when I went down the rabbit hole of HTTP fingerprinting. And after reading papers on JA3, TLS fingerprinting, and header analysis — I realized there was no simple Go library that did all of this without pulling in half the internet as dependencies.

So I built reqdna — a zero-dependency HTTP fingerprinting library for Go 1.26+.

What is HTTP Fingerprinting?

Every HTTP client leaves a unique "fingerprint" based on:

TLS handshake — cipher suites, extensions, curves offered
Header order — browsers send headers in specific sequences
Header presence — real browsers send Accept-Language, bots often don't
User-Agent patterns — obvious, but still useful in combination

The key insight: even if a bot spoofs the User-Agent, it can't easily fake the TLS handshake. That's where JA3 comes in.

JA3: The TLS Fingerprint

JA3 is a method developed by Salesforce to fingerprint TLS clients. It extracts data from the ClientHello message:

Format: SSLVersion,Ciphers,Extensions,EllipticCurves,ECPointFormats
Example: 771,4865-4866-4867-49196,0-23-65281-10-11,29-23-24,0
Hash: MD5 → ada70206e40642a3e4461f35503241d5

Every browser version has a unique JA3 hash. Chrome, Firefox, curl, Python requests — all different. And here's the kicker: it's extremely hard to spoof.

To fake a JA3 fingerprint, you'd need to modify the TLS library itself. Most bots don't bother.

Client	JA3 Hash
Chrome	`b32309a26951912be7dba376398abc3b`
Firefox	`839bbe3ed07fed922ded5aaf714d6842`
curl	`456523fc94726331a4d5a2e1d40b2cd7`
Python requests	`3b5074b1b5d032e5620f69f9f700ff0e`

Enter reqdna

Here's the simplest usage:

package main

import (
    "fmt"
    "net/http"
    "github.com/aqylsoft/reqdna"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fp := reqdna.FromRequest(r)

        fmt.Println("Fingerprint:", fp.Hash[:16])
        fmt.Println("Bot Score:", fp.BotScore)
        fmt.Println("Is Bot:", fp.IsBot())
        fmt.Println("Device:", fp.Device.Type, fp.Device.Browser)
    })

    http.ListenAndServe(":8080", nil)
}

That's it. 10 lines and you have:

Stable fingerprint hash
Bot probability score (0.0 - 1.0)
Device/browser detection
IP analysis (hashed for GDPR compliance)

The Fingerprint Structure

type Fingerprint struct {
    Hash        string      // Stable SHA256 fingerprint
    IP          IPInfo      // IP metadata (hashed by default)
    TLS         TLSInfo     // TLS fingerprint with JA3
    Headers     HeaderInfo  // Header analysis
    Device      DeviceInfo  // OS, browser, device type
    BotScore    float64     // 0.0 - 1.0 probability
    RequestedAt time.Time
}

The BotScore is calculated from multiple signals:

Missing standard headers (User-Agent, Accept, Accept-Language)
Low header count (bots send minimal headers)
Known bot patterns in User-Agent
Header entropy (too uniform = suspicious)
Outdated TLS versions
Device type detection

Full JA3 Fingerprinting

Here's where it gets interesting. Go's crypto/tls package exposes ClientHelloInfo through the GetConfigForClient callback. This contains everything we need for JA3:

SupportedVersions
CipherSuites
Extensions (added in Go 1.21!)
SupportedCurves
SupportedPoints

No external dependencies. No C bindings. Pure Go stdlib.

Here's how to enable full JA3:

package main

import (
    "crypto/tls"
    "fmt"
    "net/http"
    "github.com/aqylsoft/reqdna"
)

func main() {
    // 1. Create store to capture ClientHello
    store := reqdna.NewClientHelloStore()

    // 2. Wrap your TLS config
    tlsConfig := reqdna.WrapTLSConfig(&tls.Config{
        MinVersion: tls.VersionTLS12,
    }, store)

    // 3. Use JA3-aware middleware
    mux := http.NewServeMux()
    mux.HandleFunc("/", handler)

    wrapped := reqdna.MiddlewareWithJA3(mux, store)

    // 4. Start HTTPS server
    server := &http.Server{
        Addr:      ":443",
        Handler:   wrapped,
        TLSConfig: tlsConfig,
    }
    server.ListenAndServeTLS("cert.pem", "key.pem")
}

func handler(w http.ResponseWriter, r *http.Request) {
    fp, _ := reqdna.Get(r.Context())

    fmt.Fprintf(w, "Your fingerprint: %s\n", fp.Hash[:16])
    fmt.Fprintf(w, "Bot score: %.2f\n", fp.BotScore)

    if fp.TLS.JA3 != nil {
        fmt.Fprintf(w, "JA3 Hash: %s\n", fp.TLS.JA3.Hash)
        fmt.Fprintf(w, "JA3 String: %s\n", fp.TLS.JA3.String)
    }
}

The magic happens in WrapTLSConfig. It intercepts the TLS handshake, captures the ClientHello, and stores it keyed by remote address. The middleware then retrieves it and computes the full JA3.

How JA3 Computation Works

// Simplified from ja3.go
func ComputeJA3(hello *tls.ClientHelloInfo) *JA3Info {
    // Filter out GREASE values (RFC 8701)
    cipherSuites := filterGREASE(hello.CipherSuites)
    extensions := filterGREASE(hello.Extensions)
    curves := filterGREASE(hello.SupportedCurves)

    // Build JA3 string
    // Format: Version,Ciphers,Extensions,Curves,PointFormats
    ja3String := fmt.Sprintf("%d,%s,%s,%s,%s",
        hello.SupportedVersions[0],
        join(cipherSuites, "-"),
        join(extensions, "-"),
        join(curves, "-"),
        join(hello.SupportedPoints, "-"),
    )

    // MD5 hash for compatibility with original JA3
    hash := md5.Sum([]byte(ja3String))

    return &JA3Info{
        String: ja3String,
        Hash:   hex.EncodeToString(hash[:]),
    }
}

GREASE values (0x0a0a, 0x1a1a, etc.) are filtered per the JA3 spec — they're random values browsers insert to test server compatibility.

Bot Detection in Practice

Here's a real-world pattern for protecting an API:

func protectedHandler(w http.ResponseWriter, r *http.Request) {
    fp, ok := reqdna.Get(r.Context())
    if !ok {
        http.Error(w, "Internal error", 500)
        return
    }

    // Hard block obvious bots
    if fp.IsBot() { // BotScore >= 0.7
        http.Error(w, "Access denied", 403)
        return
    }

    // Flag suspicious requests for review
    if fp.IsSuspicious() { // BotScore >= 0.4
        logSuspiciousRequest(r, fp)
    }

    // Use fingerprint for smarter rate limiting
    // Instead of just IP, use fp.Hash
    if !rateLimiter.Allow(fp.Hash) {
        http.Error(w, "Too many requests", 429)
        return
    }

    // Proceed with normal handling
    handleRequest(w, r)
}

The key insight: fingerprint-based rate limiting is much harder to bypass than IP-based. Rotating IPs doesn't help when your TLS fingerprint stays the same.

Middleware Integration

Works with any router:

// Standard library
handler := reqdna.Middleware(mux)

// Chi
r := chi.NewRouter()
r.Use(reqdna.MiddlewareFunc())

// With JA3 (requires HTTPS)
r.Use(reqdna.MiddlewareFuncWithJA3(store))

Performance

BenchmarkComputeJA3-12       815370    1411 ns/op    792 B/op   28 allocs
BenchmarkFromRequest-12      298992    3972 ns/op   1016 B/op   26 allocs

~4μs per request. That's negligible compared to typical handler latency.

Privacy Considerations

By default, IP addresses are hashed with a salt before being included in the fingerprint. This means:

You can identify repeat visitors
You can't reverse the hash to get the original IP
GDPR-friendly by design

// Custom salt for your application
fp := reqdna.FromRequest(r,
    reqdna.WithHashSalt(os.Getenv("FINGERPRINT_SALT")),
)

Testing Your Code

The library provides test helpers and interfaces for easy mocking:

func TestBotBlocking(t *testing.T) {
    // Create a bot fingerprint for testing
    fp := reqdna.TestBotFingerprint()

    if !fp.IsBot() {
        t.Error("should detect as bot")
    }
}

// Or use interfaces for dependency injection
type mockExtractor struct {
    fp reqdna.Fingerprint
}

func (m *mockExtractor) Extract(r *http.Request) reqdna.Fingerprint {
    return m.fp
}

What's Next?

Some ideas I'm considering:

Known JA3 database — map hashes to known clients
Behavioral analysis — request timing patterns
WebSocket fingerprinting — extend to WS connections
Integration with kazrl — fingerprint-aware rate limiting out of the box

Conclusion

Bot detection is an arms race. Simple checks like User-Agent validation haven't been effective for years. But TLS fingerprinting with JA3 raises the bar significantly — bots now need to modify their TLS stack to evade detection.

reqdna gives you all of this with zero dependencies, ~4μs overhead, and a clean API. It's the "DNA" of HTTP requests.

Check it out: github.com/aqylsoft/reqdna

If you found this useful, I also wrote about building a zero-dependency rate limiter in Go. These two libraries work great together.

What fingerprinting techniques do you use for bot detection? Let me know in the comments!

Building a Zero-Dependency Rate Limiter in Go (Token Bucket, Leaky Bucket, Sliding Window)

Maksat Ramazan — Wed, 19 Nov 2025 14:49:26 +0000

Rate limiting is essential for protecting APIs from abuse, ensuring fair resource allocation, and maintaining system stability. While there are existing solutions, I wanted to build something lightweight, performant, and easy to integrate into any Go project.

Today, I'm sharing kazrl - a zero-dependency rate limiter library that implements three different algorithms and comes with ready-to-use middleware for popular Go web frameworks.

The Problem

Most rate limiting libraries either:

Come with heavy dependencies
Support only one algorithm
Require complex setup for per-client limiting
Lack middleware integration

I needed something that:

Has zero external dependencies
Supports multiple algorithms (Token Bucket, Leaky Bucket, Sliding Window)
Works with popular frameworks out of the box
Provides flexible per-client rate limiting

Installation

go get github.com/Makennsky/kazrl

That's it! No transitive dependencies to worry about.

Quick Start

Here's the simplest way to add rate limiting to your HTTP handler:

import (
    "net/http"
    "github.com/Makennsky/kazrl"
    "github.com/Makennsky/kazrl/middleware"
)

func main() {
    // Create a rate limiter: 100 requests per second, burst of 200
    limiter := kazrl.NewTokenBucket(100, 200)

    // Apply middleware
    rateLimitMiddleware := middleware.HTTP(limiter)

    handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })

    http.Handle("/api/", rateLimitMiddleware(handler))
    http.ListenAndServe(":8080", nil)
}

That's literally 10 lines of code to add rate limiting!

Three Algorithms, One Interface

Different use cases need different strategies. kazrl implements three battle-tested algorithms:

1. Token Bucket

Perfect for APIs that need to allow bursts while maintaining average rate limits.

limiter := kazrl.NewTokenBucket(10, 20)
// 10 requests per second, allows bursts up to 20

Use case: Public APIs, user-facing endpoints

2. Leaky Bucket

Smooths out traffic spikes by processing requests at a constant rate.

limiter := kazrl.NewLeakyBucket(10, 20)
// Processes 10 req/s, queues up to 20

Use case: Protecting downstream services, database queries

3. Sliding Window

Provides the most accurate rate limiting without fixed window edge cases.

limiter := kazrl.NewSlidingWindow(10, 20)
// 10 req/s with a sliding time window

Use case: Strict rate enforcement, billing APIs

All three implement the same interface, so switching is trivial:

type RateLimiter interface {
    Allow() bool
    AllowN(n int) bool
    Wait(ctx context.Context) error
    WaitN(ctx context.Context, n int) error
    Reserve() time.Duration
    ReserveN(n int) time.Duration
}

Per-Client Rate Limiting Made Easy

The real power comes with per-client limiting. Here's how to rate limit by IP address:

rateLimitMiddleware := middleware.HTTPWithKeyFunc(
    func() kazrl.RateLimiter {
        return kazrl.NewTokenBucket(10, 20) // 10 req/s per IP
    },
    middleware.KeyByIP, // Built-in IP extractor
)

http.Handle("/api/", rateLimitMiddleware(handler))

Each IP address automatically gets its own rate limiter instance. The library handles X-Forwarded-For and X-Real-IP headers correctly.

Rate Limit by API Key

rateLimitMiddleware := middleware.HTTPWithKeyFunc(
    func() kazrl.RateLimiter {
        return kazrl.NewTokenBucket(100, 200)
    },
    middleware.KeyByAPIKey, // Extracts from Authorization header
)

Custom Key Functions

Need something more complex? Write your own key extractor:

customKeyFunc := func(r *http.Request) string {
    // Rate limit by IP + endpoint combination
    return middleware.KeyByIP(r) + ":" + r.URL.Path
}

rateLimitMiddleware := middleware.HTTPWithKeyFunc(
    func() kazrl.RateLimiter {
        return kazrl.NewTokenBucket(5, 10)
    },
    customKeyFunc,
)

Framework Integration

kazrl provides native middleware for popular frameworks:

Gin

r := gin.Default()
limiter := kazrl.NewTokenBucket(100, 200)
r.Use(middleware.Gin(limiter))

Echo

e := echo.New()
limiter := kazrl.NewTokenBucket(100, 200)
e.Use(middleware.Echo(limiter))

Fiber

app := fiber.New()
limiter := kazrl.NewTokenBucket(100, 200)
app.Use(middleware.Fiber(limiter))

Chi

r := chi.NewRouter()
limiter := kazrl.NewTokenBucket(100, 200)
r.Use(middleware.Chi(limiter))

Multi-Layer Rate Limiting

For advanced scenarios, you can stack multiple rate limiters:

// Global limit: 1000 req/s for all clients
globalLimiter := kazrl.NewTokenBucket(1000, 2000)
globalMiddleware := middleware.HTTP(globalLimiter)

// Per-IP limit: 10 req/s per client
perIPMiddleware := middleware.HTTPWithKeyFunc(
    func() kazrl.RateLimiter {
        return kazrl.NewTokenBucket(10, 20)
    },
    middleware.KeyByIP,
)

// Stack them!
handler := globalMiddleware(perIPMiddleware(yourHandler))

This protects against both individual abuse and total system overload.

Performance

Benchmarks on a modern system (Intel i7-1355U):

BenchmarkTokenBucketAllow-12        4,574,689 ops    255.6 ns/op    0 allocs/op
BenchmarkLeakyBucketAllow-12        5,218,902 ops    208.3 ns/op    0 allocs/op
BenchmarkSlidingWindowAllow-12      6,476,462 ops    198.6 ns/op    0 allocs/op

200-260 nanoseconds per operation with zero allocations. That's fast enough for the most demanding applications.

Production-Ready Features

Context Support

All blocking operations support context cancellation:

ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
defer cancel()

if err := limiter.Wait(ctx); err != nil {
    // Handle timeout or cancellation
}

Reservation API

For advanced use cases, you can reserve tokens and schedule work:

waitDuration := limiter.Reserve()
if waitDuration > 0 {
    // Schedule for later
    time.AfterFunc(waitDuration, processRequest)
} else {
    // Process immediately
    processRequest()
}

Thread-Safe

All operations are thread-safe. You can safely use the same limiter instance across multiple goroutines.

Algorithm Comparison

Algorithm	Burst Support	Smoothing	Memory	Best For
Token Bucket	Yes	No	Low	Public APIs, burst tolerance
Leaky Bucket	Queued	Yes	Medium	Downstream protection
Sliding Window	No	No	High	Strict enforcement

Implementation Insights

Why Zero Dependencies?

Dependencies are a security and maintenance burden. By keeping kazrl dependency-free:

No supply chain attacks via transitive dependencies
Faster installation and smaller binaries
No version conflicts with your other dependencies
Easy to audit (< 2000 lines of code)

Concurrency Design

Each algorithm uses sync.Mutex for thread-safety. While this might seem simple, it's actually the right choice here:

type tokenBucket struct {
    mu         sync.Mutex
    rate       float64
    burst      int
    tokens     float64
    lastUpdate time.Time
}

Lock contention is minimal because:

Operations are extremely fast (< 300ns)
The critical section is tiny (just token math)
Per-client limiting distributes the load

For most applications, you'll never see contention. If you're handling millions of requests per second per endpoint, you might need a distributed solution anyway.

Memory Management

The library is designed to minimize allocations:

// No allocations in the hot path
func (tb *tokenBucket) Allow() bool {
    tb.mu.Lock()
    defer tb.mu.Unlock()

    now := time.Now()
    tb.refillTokens(now) // Pure math, no allocations

    if tb.tokens >= 1.0 {
        tb.tokens -= 1.0
        return true
    }
    return false
}

The only allocations happen when creating new per-client limiters, which is infrequent.

Real-World Example

Here's a complete example of a production-ready API server:

package main

import (
    "encoding/json"
    "net/http"

    "github.com/Makennsky/kazrl"
    "github.com/Makennsky/kazrl/middleware"
)

func main() {
    // Global rate limit: 10,000 req/s
    globalLimiter := kazrl.NewTokenBucket(10000, 20000)
    globalMiddleware := middleware.HTTP(globalLimiter)

    // Per-IP rate limit: 100 req/s
    perIPMiddleware := middleware.HTTPWithKeyFunc(
        func() kazrl.RateLimiter {
            return kazrl.NewTokenBucket(100, 200)
        },
        middleware.KeyByIP,
    )

    // API handler
    apiHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        response := map[string]string{
            "status": "ok",
            "message": "Request processed",
        }
        json.NewEncoder(w).Encode(response)
    })

    // Stack middleware
    http.Handle("/api/", globalMiddleware(perIPMiddleware(apiHandler)))

    http.ListenAndServe(":8080", nil)
}

When to Use Each Algorithm

Token Bucket - Default choice

Public APIs
User-facing endpoints
Services that need burst capacity
Not suitable when strict rate enforcement is needed

Leaky Bucket - Traffic shaping

Protecting slow downstream services
Database query rate limiting
Smoothing traffic spikes
Not suitable when you need to allow bursts

Sliding Window - Strict enforcement

Billing/metered APIs
When accuracy is critical
Preventing gaming fixed windows
Not suitable when you need burst capacity

Future Plans

Ideas I'm considering:

Distributed rate limiting (Redis backend)
Prometheus metrics integration
Response header injection (X-RateLimit-*)
Dynamic rate adjustment based on system load
gRPC interceptors

What would you find useful? Let me know in the comments!

Resources

GitHub: https://github.com/Makennsky/kazrl
Documentation: Full examples in README
Benchmarks: Run go test -bench=. -benchmem

Try It Out

Give kazrl a try in your next project! It's production-ready, battle-tested, and takes 2 minutes to integrate.

go get github.com/Makennsky/kazrl

If you find it useful, please star the repo on GitHub!

What rate limiting challenges have you faced? Share your experiences in the comments below!

Built in Kazakhstan