DEV Community: Maksat Ramazan

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