DEV Community: Mustafa Veysi Soyvural

Consistent Hashing in Go: From the Math to Production-Grade Code

Mustafa Veysi Soyvural — Thu, 02 Apr 2026 21:54:56 +0000

When you scale a cache cluster from 5 to 6 servers using modulo hashing, 83% of your keys remap to different servers. All at once. Every one of those remapped keys hits your database simultaneously — the thundering herd problem that has taken down production systems at every scale.

Before:  hash("user:1001") % 5 = 3  → Server C
After:   hash("user:1001") % 6 = 1  → Server A  ← cache miss

Consistent hashing solves this. It's the algorithm behind DynamoDB's partitioning, Cassandra's token ring, Discord's chat server routing, and Netflix's CDN distribution. This post walks through how it works, why it works, and the implementation details that separate a textbook explanation from production-ready code — backed by benchmarks and chaos testing.

The full implementation is available on GitHub: ~800 lines of Go, zero external dependencies.

The Algorithm

Consistent hashing was introduced by Karger et al. in 1997 to solve cache distribution for the early web. The original paper defined four formal properties that any consistent hash function must satisfy:

Balance — Keys distribute evenly across all nodes. No single node should be disproportionately loaded.
Monotonicity — When a new node joins, keys only move to the new node. Keys never reshuffle between existing nodes.
Spread — Across different client views of the cluster, a key maps to a small number of distinct nodes.
Load — No node receives more than its fair share of keys, regardless of which subset of nodes a client sees.

These aren't aspirational goals — they're the mathematical contract. If your implementation violates any of them, you don't have consistent hashing; you have a hash ring with bugs.

How the Ring Works

Instead of hash(key) % N, both nodes and keys are placed on a circular ring of size 2^32. To find which node owns a key:

Hash the key to a position on the ring
Walk clockwise until you hit a node
That node owns the key

The critical property: adding or removing a node only affects the keys in the arc between the changed node and its predecessor. Everything else stays put.

Strategy          │ Keys Remapped (5→6 nodes, 100K keys)
──────────────────┼─────────────────────────────────────
Modulo (hash%N)   │  83,803  (83.8%)
Consistent Hash   │  15,723  (15.7%)  ← ~K/N theoretical bound

That's monotonicity in action. The theoretical bound is K/N (20,000 for 100K keys across 5 nodes). The measured 15,723 falls within expected variance.

Virtual Nodes: From Theory to Practice

The raw ring algorithm satisfies monotonicity but fails badly on balance. With one position per physical node on a 5-node ring:

Node A:  32,014 keys
Node B:  27,412 keys
Node C:  18,805 keys
Node D:  19,914 keys
Node E:   1,855 keys  ← 17x less than Node A

A 17:1 imbalance. In production, Node E sits idle while Node A melts.

The fix is virtual nodes: each physical node gets multiple positions on the ring. Node-A#0 through Node-A#149 are each hashed independently to different ring positions. A lookup that lands on any of Node A's virtual nodes routes to the physical Node A.

Here's how balance improves as you add virtual nodes (measured across 100K keys, 5 physical nodes):

Virtual Nodes	Std Deviation	Worst Node Ratio
1	11,353	3.20x average
50	4,601	1.83x average
150	2,824	1.47x average
500	976	1.17x average

Diminishing returns kick in hard after 150. Going from 1 to 150 vnodes cuts standard deviation by 75%. Going from 150 to 500 cuts it by another 65%, but at the cost of 3.3x more ring entries, more memory, and slower binary searches. 150 is the sweet spot for most deployments — and it's what production systems like Cassandra converge on.

Proving Correctness Under Chaos

Benchmarks show the happy path. Chaos testing proves the guarantees hold when things break.

Failure Isolation

When a node dies, only its keys are affected. This is a direct consequence of monotonicity — surviving nodes' arc boundaries don't change.

Testing with 10,000 keys across five Redis nodes:

redis-1     2,197 keys
redis-2     1,731 keys
redis-3     1,559 keys  ← killed
redis-4     1,730 keys
redis-5     2,783 keys

After redis-3 failure:
  Cache hit rate:  84.4%
  Cache misses:    1,559  ← exactly redis-3's key count
  Keys remapped from surviving nodes: 0

Zero remapping for surviving nodes. The blast radius is perfectly contained.

Catastrophic Scenarios

Five tests verified the formal properties under extreme conditions:

Mass failure (50% node loss): Removed 5 of 10 nodes simultaneously. Zero keys remapped between surviving nodes. All misses traced to removed nodes only — monotonicity holds.
Rapid churn (20 add/remove cycles): Each operation remapped within 1.5x of the K/N theoretical bound. No cumulative drift — balance recovers after each operation.
Concurrent chaos: 2.4 million reads during simultaneous node additions and removals. Zero data races. 100% correctness on every read that targeted a live node.

These aren't unit tests — they're property-based proofs that the implementation satisfies Karger's guarantees under adversarial conditions.

Implementation Deep-Dive

Hash Function Selection

The implementation supports pluggable hash functions: FNV-1a, MD5, and CRC32. The choice matters more than you'd expect.

FNV-1a is the default, and for good reason. Consistent hashing doesn't need collision resistance — there's no adversary trying to forge hash collisions on your cache keys. What it needs is uniform distribution and speed. FNV-1a delivers both: non-cryptographic, fast, and well-distributed across the 32-bit space.

MD5 works but wastes cycles on cryptographic properties you don't need. You're paying for collision resistance that buys you nothing in a hash ring context. Use it only if you need compatibility with an existing system that already uses MD5 hashes.

CRC32 is the fastest option but has known distribution weaknesses with certain input patterns. Fine for benchmarking, risky for production.

If you need maximum throughput, consider xxHash — it's faster than FNV-1a with comparable distribution quality. The implementation's pluggable interface makes swapping trivial.

Collision Handling in Virtual Node Space

With 150 virtual nodes per physical node across 5 nodes, you're placing 750 points in a 2^32 space. Collisions are rare but inevitable. The birthday problem applies: at 750 points in 4 billion slots, collisions will occur in roughly 1 in 5,700 deployments.

The implementation detects and skips duplicate positions rather than overwriting. Overwriting silently transfers ownership of a key range from one node to another — a violation of the balance property that produces no error and no log entry. A silent data correctness bug that only manifests under load.

Concurrency: RWMutex, Not Mutex

The hash ring has a heavily skewed read/write ratio. Key lookups (reads) happen on every cache operation — potentially millions per second. Node additions and removals (writes) happen during deployments and failures — maybe a few times per day.

sync.RWMutex allows concurrent readers with exclusive writers. A plain sync.Mutex would serialize every lookup behind every other lookup, destroying throughput for no safety benefit.

Ring Lookup: Sorted Array + Binary Search

The ring is stored as a sorted array of virtual node positions. Key lookup uses sort.Search (binary search) to find the first node position clockwise from the key's hash — O(log n) where n is the total number of virtual nodes.

An alternative is a self-balancing BST (red-black tree, etc.), which gives O(log n) insertion and deletion without re-sorting. But Go's sort.Search on a slice is cache-friendly and fast in practice. Re-sorting 750 elements on the rare node change is negligible compared to the millions of lookups that benefit from contiguous memory layout.

Error Handling on Empty Rings

An empty ring — no nodes registered — must return an explicit error, not a zero value. A zero-value return silently routes all keys to... nothing. No crash, no log, no alert. Data just disappears.

if len(r.nodes) == 0 {
    return "", ErrEmptyRing
}

This is a system boundary. Fail loudly.

When NOT to Use Consistent Hashing

Consistent hashing is not universally optimal. Knowing when to reach for something else is as important as knowing the algorithm itself.

Jump Consistent Hash

Google's Jump Consistent Hash (Lamping & Veach, 2014) uses O(1) space and O(ln n) time with near-perfect balance — no virtual nodes needed. The catch: nodes must be identified by sequential integers (0, 1, 2, ...), not names or addresses. You can't remove node 3 without renumbering nodes 4+.

Use jump hash when: nodes are numbered slots (e.g., sharded database partitions) and you only add/remove from the tail. Use ring-based consistent hashing when: nodes have identities (IP addresses, hostnames) and any node can fail independently.

Bounded-Load Consistent Hashing

Google's bounded-load variant (Mirrokni et al., 2018) caps each node's load at ceil(average_load * (1 + epsilon)). When a node would exceed its cap, the algorithm continues clockwise to the next under-capacity node.

This solves the "celebrity problem" — when a small number of keys receive massively disproportionate traffic. Standard consistent hashing distributes keys evenly but not load if key popularity is skewed. A single viral cache key can overwhelm its assigned node while others idle.

Use bounded-load when: key access patterns are highly skewed (social media feeds, trending content, celebrity profiles).

Rendezvous Hashing (Highest Random Weight)

Each key computes a weight for every node; the highest-weight node wins. O(n) per lookup, but n is typically small (tens of nodes, not thousands). No ring, no virtual nodes, no rebalancing logic. Elegant for small clusters.

Use rendezvous when: your node count is small (< 50) and you value simplicity over lookup speed.

Plain Modulo with Planned Migration

If you can tolerate a maintenance window, hash % N with a full data migration on resize is simpler, faster per-lookup, and has zero overhead. Don't reach for consistent hashing if your cluster never changes size in production or if downtime during resizing is acceptable.

Use modulo when: the cluster is static, or downtime during scaling is acceptable.

Where Consistent Hashing Runs in Production

Amazon DynamoDB — The 2007 Dynamo paper popularized consistent hashing for key-value partitioning. Each node owns a range of the ring; virtual nodes handle heterogeneous hardware.
Apache Cassandra — Token ring partitioning assigns each node a set of token ranges. Virtual nodes (vnodes) were added in Cassandra 1.2 for automatic rebalancing.
Discord — Routes users to chat servers using consistent hashing, ensuring session stickiness during server scaling events.
Netflix — CDN edge servers use consistent hashing to route content requests, minimizing cache misses during server pool changes.
Memcached clients — libmemcached and most client libraries use consistent hashing by default for key-to-server routing.

Code & Resources

The full implementation: github.com/soyvural/consistent-hashing

~800 lines of Go. Zero external dependencies. Pluggable hash functions (FNV-1a, MD5, CRC32). Includes the benchmarks and chaos tests described above.

git clone https://github.com/soyvural/consistent-hashing.git
cd consistent-hashing
go run cmd/demo/main.go

I Built a Read-Only kubectl So AI Agents Can't Break My Cluster

Mustafa Veysi Soyvural — Sun, 29 Mar 2026 14:22:37 +0000

Last month I gave Claude access to one of our staging clusters. Within minutes it tried to kubectl exec into a pod and ran kubectl get secret -o yaml. Nothing bad happened — but it made me think: what if it had been production?

So I built kubectl-ro.

What it does

It's a thin wrapper around kubectl that only allows read-only commands. You use it exactly like kubectl:

kubectl-ro get pods -n kube-system        # works
kubectl-ro logs deployment/my-app          # works
kubectl-ro delete pod nginx                # nope
# ✘ BLOCKED: 'delete' is a mutating command

That's it. If the command would change anything in your cluster, it gets blocked before kubectl ever sees it.

Why not just use RBAC?

You absolutely should use RBAC. But RBAC is server-side — it requires cluster admin setup, service accounts, role bindings. kubectl-ro is client-side. You install it, point your AI agent at it, and you're done. No cluster changes needed.

Think of it as a seatbelt, not a replacement for airbags.

It also protects secrets

This was the part that surprised me most. Even "read-only" kubectl can leak sensitive data:

kubectl get secret db-creds -o yaml    # prints base64-encoded passwords
kubectl describe secret db-creds       # same thing, different format

kubectl-ro blocks these. You can list secrets (names and types), but you can't extract values. In MCP mode, secret values are replaced with [REDACTED] automatically.

It works as an MCP server too

This is the part I'm most excited about. Run kubectl-ro serve and it becomes an MCP server with 20 read-only tools that any AI agent can use:

{
  "mcpServers": {
    "kubectl-ro": {
      "command": "kubectl-ro",
      "args": ["serve"]
    }
  }
}

Now your AI can list_pods, get_pod_logs, list_deployments, get_events — all the things you'd want it to see, nothing it shouldn't touch.

How the policy works

There's no config file. The policy is baked into the binary on purpose — you can't accidentally misconfigure it.

The logic is simple:

Mutating commands (delete, apply, create, exec, scale, drain...) → always blocked
Read commands (get, describe, logs, top, events...) → allowed, with secrets checks
Unknown commands → blocked by default (fail-safe)

It also rejects arguments with control characters, which prevents a class of prompt injection attacks where an LLM hallucinates weird bytes.

Every action is logged

Everything goes to ~/.kubectl-ro/audit.log:

{"timestamp":"2026-03-29T13:04:36Z","action":"get pods","result":"allowed"}
{"timestamp":"2026-03-29T13:04:36Z","action":"delete pod x","result":"blocked","reason":"'delete' is a mutating command"}

So if something weird happens, you can see exactly what was attempted.

Try it

go install github.com/soyvural/kubectl-ro@latest

Or grab a binary from the releases page.

You can test the policy without running anything:

kubectl-ro --check get pods           # prints: OK
kubectl-ro --check delete pod nginx   # prints: BLOCKED

Put it on your PATH and it works as a kubectl plugin too: kubectl ro get pods.

The repo is at github.com/soyvural/kubectl-ro. It's MIT licensed, written in Go, and has zero external runtime dependencies.

If you're giving AI agents access to your clusters, I'd love to hear how you're handling the safety side. What's your approach?

I Benchmarked fasthttp vs net/http — The Results Surprised Me

Mustafa Veysi Soyvural — Fri, 27 Mar 2026 12:25:26 +0000

I kept hearing that fasthttp was faster than Go's standard net/http. So I decided to stop guessing and just measure it.

The result? 5.6x faster. Zero heap allocations. And the benchmark is only two files.

Keeping It Fair

The trick to an honest benchmark: remove everything except what you're testing.

Both servers use the same in-memory listener — no TCP, no network noise. Same endpoints, same response bodies. The only difference is the HTTP stack.

// net/http
func SimpleHandler(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Hello, World!"))
}

// fasthttp
func SimpleFastHandler(ctx *fasthttp.RequestCtx) {
    ctx.Write([]byte("Hello, World!"))
}

Same job. Very different performance.

The Numbers

Apple M2 Pro, Go 1.23.4

Benchmark	net/http	fasthttp	Speedup
Simple	14,449 ns/op, 63 allocs	2,563 ns/op, 0 allocs	5.6x
JSON	15,561 ns/op, 72 allocs	3,136 ns/op, 6 allocs	5.0x
Parallel	3,541 ns/op, 63 allocs	1,437 ns/op, 0 allocs	2.5x

Zero allocations on simple requests. That's not a typo.

The parallel gap is smaller (2.5x) because net/http already handles concurrency well. But even there — 63 allocations vs. 0.

What Makes fasthttp So Fast?

It comes down to one idea: don't allocate, reuse.

net/http creates fresh Request and ResponseWriter objects for every single request. fasthttp pools them with sync.Pool and resets them between requests. That's why you see 63 allocs drop to 0.

It also skips things most apps don't need — header map cloning, chunked encoding by default, HTTP/2. Less work per request = less time per request.

So Should You Switch?

Use fasthttp when:

You're building a proxy, gateway, or high-throughput service
Allocation pressure and GC pauses are a real problem
You need every microsecond on hot paths

Stick with net/http when:

You need HTTP/2
You rely on the Go middleware ecosystem
context.Context propagation matters to you

For most apps, net/http is the right choice. But when performance is the priority, fasthttp earns its name.

Run It Yourself

git clone https://github.com/soyvural/fasthttp-vs-nethttp.git
cd fasthttp-vs-nethttp
go test -bench=. -benchmem -count=3

Two files. No dependencies beyond fasthttp. Clone it, run it, see your own numbers.

Full source: soyvural/fasthttp-vs-nethttp

Got different results on your machine? I'd love to see them in the comments.

From OpenAPI Spec to MCP Tools — Automatically

Mustafa Veysi Soyvural — Fri, 27 Mar 2026 01:35:37 +0000

Hey folks 👋

I've been deep in the AI tooling world lately, and I kept running into the same annoying problem: connecting LLMs to existing APIs is way harder than it should be.

Every time I wanted an LLM to call a REST API, I had to write a custom MCP server from scratch. Define the tools. Map the parameters. Handle auth. Wire up the HTTP calls. Over and over again.

So I built something to fix that.

Meet mcp-server-openapi

mcp-server-openapi is an open-source Go CLI that automatically converts your OpenAPI spec into MCP tools. If your API has an OpenAPI doc (and let's be honest, most do), you can expose it to any MCP client — Claude Desktop, Cursor, VS Code, you name it — in about 30 seconds.

No boilerplate. No hand-wiring. Just point it at your spec and go.

mcp-server-openapi --spec ./your-api.yaml

That's it. Your API endpoints are now tools that any MCP client can call.

Wait, What's MCP?

If you're new to this — Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and data sources. Think of it as a USB-C port for AI: one standard connection that works everywhere.

MCP servers expose "tools" (basically functions) that an MCP client can discover and call. The problem is, building these servers by hand gets tedious fast — especially when your API already describes itself perfectly through OpenAPI.

That's the gap mcp-server-openapi fills.

The Processing Pipeline

  OpenAPI Spec        mcp-server-openapi           MCP Client
  ------------    --------------------------    ---------------

  +---------+     +-----+  +------+  +-----+   +-----------+
  |  YAML/  |---->|Parse|->|Filter|->|Schema|-->| Discovers |
  |  JSON   |     |     |  |      |  | Gen  |   |   Tools   |
  +---------+     +-----+  +------+  +-----+   +-----+-----+
                                                      |
                  +--------------------------+         |
                  |  When tool is called:    |<--------+
                  |                          |
                  |  1. Map args -> HTTP req |
                  |  2. Inject auth headers  |
                  |  3. Execute request      |---> Your API
                  |  4. Return response      |<--- Response
                  +--------------------------+

How It Works Step by Step

Parses your spec using kin-openapi — the gold standard for OpenAPI parsing in Go. Full $ref resolution, oneOf/anyOf/allOf — the works.
Filters operations — only endpoints tagged with mcp get exposed (you choose what gets visible)
Generates JSON Schema for each tool's input — path params, query params, headers, and body are all mapped automatically
Serves tools via stdio or Streamable HTTP using the mcp-go SDK
Executes HTTP requests when an MCP client calls a tool, mapping responses back cleanly

The key insight: your OpenAPI spec already has everything needed to generate MCP tools — parameter types, descriptions, required fields, request bodies. Why write it twice?

Quick Start (5 Minutes)

1. Install

go install github.com/soyvural/mcp-server-openapi/cmd/mcp-server-openapi@latest

2. Tag Your Endpoints

Add the mcp tag to any operation you want to expose:

paths:
  /v1/forecast:
    get:
      tags:
        - mcp              # <-- This is the magic switch
      operationId: getForecast
      summary: Get weather forecast
      parameters:
        - name: latitude
          in: query
          required: true
          schema:
            type: number
        - name: longitude
          in: query
          required: true
          schema:
            type: number

3. Configure Your MCP Client

Add this to your MCP client config (works with any MCP-compatible app — Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "my-api": {
      "command": "mcp-server-openapi",
      "args": ["--spec", "/path/to/your/openapi.yaml"]
    }
  }
}

Restart your MCP client, and your API tools show up automatically. Done. 🎉

Try It With a Real API — Zero Config

The repo includes a ready-to-use Open-Meteo weather example. No API key needed — it just works:

go install github.com/soyvural/mcp-server-openapi/cmd/mcp-server-openapi@latest
mcp-server-openapi --spec examples/weather/weather.yaml

Ask your MCP client things like:

"What's the weather in Berlin right now?"
"Give me a 5-day forecast for New York in Fahrenheit"
"What's the elevation of Denver, Colorado?"

The x-mcp Extensions (My Favorite Part)

You can fine-tune how your API appears to the MCP client using OpenAPI vendor extensions:

/users/{id}:
  get:
    tags: [mcp]
    operationId: getUserById
    x-mcp-tool-name: get_user            # Friendlier name
    x-mcp-description: |                 # AI-optimized description
      Fetch detailed user info including
      profile, settings, and activity.

/internal/health:
  get:
    tags: [mcp]
    x-mcp-hidden: true                   # Hide from AI

/debug/stats:
  get:
    tags: [internal]                     # No mcp tag, but...
    x-mcp-hidden: false                  # Force visible anyway

Here's what each extension does:

+-------------------+----------+--------------------------------+
| Extension         | Type     | What It Does                   |
+-------------------+----------+--------------------------------+
| x-mcp-tool-name   | string   | Override the generated name    |
| x-mcp-description | string   | Write AI-friendly description  |
| x-mcp-hidden      | boolean  | Show/hide regardless of tags   |
+-------------------+----------+--------------------------------+

Think of x-mcp-description as writing instructions specifically for the AI. Your OpenAPI summary might say "Get user by ID" (fine for docs), but the MCP description can add context that helps the LLM make smarter decisions about when and how to use the tool.

Authentication Built In

Most real APIs need auth. We've got you covered:

Bearer token:

export GITHUB_TOKEN="ghp_..."
mcp-server-openapi \\
  --spec ./github-api.yaml \\
  --auth-type bearer \\
  --auth-token-env GITHUB_TOKEN

API key (header or query):

export MY_KEY="sk_..."
mcp-server-openapi \\
  --spec ./api.yaml \\
  --auth-type api-key \\
  --auth-key-env MY_KEY \\
  --auth-key-name X-API-Key \\
  --auth-key-in header

Credentials stay in environment variables — never in config files or CLI args. 🔒

Error Handling That Makes Sense

When things go wrong (and they will), error mapping is clear:

+----------------+---------------------------------------------+
| What Happened  | What the MCP Client Sees                    |
+----------------+---------------------------------------------+
| 2xx response   | The actual response body (success!)         |
| 400-499 error  | Error with status code + response body      |
| 500-599 error  | "Upstream server error" + status code       |
| Timeout        | "Request timed out"                         |
| Can't connect  | "Failed to connect to upstream"             |
+----------------+---------------------------------------------+

All errors include enough context for the AI to understand what went wrong and communicate it to the user. No mysterious failures.

Docker Support

If you prefer containers:

docker run --rm -i \\
  -v $(pwd)/specs:/specs \\
  mcp-server-openapi --spec /specs/my-api.yaml

Works great for teams who want a standardized MCP setup across environments.

Why I Built This

Honestly? Laziness. The good kind.

I was working on a project where I needed my AI tools to interact with about a dozen internal APIs. Writing a custom MCP server for each one felt insane. The specs were already there. The parameter types were already documented. The auth was already defined.

I just needed something to connect the dots.

Now, adding a new API to my MCP setup takes me less than a minute: tag the endpoints, point the server at the spec, done.

What's Coming Next

The project is MIT-licensed and open for contributions. Here's what's on the roadmap:

🔐 OAuth2 client credentials flow
📄 Config file support (YAML)
🔄 SSE transport
⚠️ x-mcp-confirm extension for destructive operations
🔥 Spec hot-reload
⏱️ Rate limiting and retry policies

If any of that sounds interesting, PRs are welcome!

Try It Out

go install github.com/soyvural/mcp-server-openapi/cmd/mcp-server-openapi@latest
mcp-server-openapi --spec examples/weather/weather.yaml

⭐ GitHub Repo

I'd love to hear what APIs you connect with this. Drop a comment or open an issue — always happy to chat.

Happy building! 🚀

connpool: A Zero-Alloc TCP Connection Pool for Go

Mustafa Veysi Soyvural — Thu, 26 Mar 2026 17:11:11 +0000

The Story

Years ago, when I first needed TCP connection pooling in Go, I found fatih/pool. It was elegant, simple, and it taught me a lot about channel-based pooling design. It was a real inspiration.

But as I worked on high-throughput systems at scale, I kept running into gaps: no health checks, no idle eviction, no lifetime management, no metrics. I'd bolt these on as wrappers, and eventually realized I was maintaining a full pool implementation anyway.

So I built connpool — taking the channel-based foundation that fatih/pool popularized and adding the features that production systems actually need.

Introducing connpool

github.com/soyvural/connpool — a production-grade TCP connection pool for Go.

go get github.com/soyvural/connpool@v1.0.0

Zero dependencies. ~370 lines of code. Zero-alloc fast path.

Quick Example

cfg := connpool.Config{
    MinSize:     5,
    MaxSize:     20,
    Increment:   2,
    IdleTimeout: 30 * time.Second,
    MaxLifetime: 5 * time.Minute,
    Ping: func(c net.Conn) error {
        c.SetReadDeadline(time.Now().Add(time.Millisecond))
        buf := make([]byte, 1)
        if _, err := c.Read(buf); err != nil {
            if netErr, ok := err.(net.Error); ok && netErr.Timeout() {
                c.SetReadDeadline(time.Time{})
                return nil // timeout = alive
            }
            return err // dead
        }
        c.SetReadDeadline(time.Time{})
        return nil
    },
}

pool, _ := connpool.New(cfg, func() (net.Conn, error) {
    return net.DialTimeout("tcp", "localhost:6379", 5*time.Second)
}, connpool.WithName("redis-pool"))
defer pool.Stop()

conn, _ := pool.Get(ctx)
defer conn.Close() // returns to pool

// If the connection is broken:
pool.MarkUnusable(conn)
conn.Close() // destroys instead of returning

What Makes It Different

1. Health Check on Get()

Every Get() call validates the connection before returning it. The check order is optimized — cheapest first:

Lifetime check (time comparison) → Idle check (time comparison) → Ping (network I/O)

Time comparisons cost nanoseconds. The expensive network ping only runs if the connection passes the time-based checks. If a connection fails health check, it's discarded and the pool retries (up to 3 times) before growing.

2. Max Lifetime with Jitter

Connections have a maximum lifetime, but here's the trick: each connection gets a 10% random jitter on its expiration.

Why? Without jitter, if you create 20 connections at startup, they all expire at the exact same moment — causing a thundering herd of reconnections. Jitter spreads the expiration across time.

func (c *Config) maxLifetimeWithJitter() time.Duration {
    if c.MaxLifetime <= 0 {
        return 0
    }
    jitter := time.Duration(rand.Int64N(int64(c.MaxLifetime) / 10))
    return c.MaxLifetime + jitter
}

This is the same pattern used by pgx and Vitess.

3. Background Evictor

Without a background evictor, stale connections only get cleaned up when someone calls Get(). If the pool is idle (no traffic), dead connections accumulate silently.

The evictor runs every 30 seconds (configurable), drains the channel, health-checks each connection, discards the stale ones, and replenishes to MinSize.

4. Zero-Alloc Fast Path

The pool uses a channel internally (inspired by fatih/pool's original design), not a mutex+slice. This gives us:

Natural blocking semantics (when pool is at max, Get() blocks on channel receive)
Non-blocking fast path via select/default
Zero heap allocations on the hot path

BenchmarkGetPut_Sequential    8,556,068    139.9 ns/op    0 B/op    0 allocs/op
BenchmarkGetPut_Parallel      5,075,728    245.1 ns/op    0 B/op    0 allocs/op

5. Context-Aware Get()

Get() respects context deadlines and cancellation. If the pool is exhausted and a connection doesn't become available before the deadline, you get context.DeadlineExceeded — not a hang.

6. Comprehensive Metrics

stats := pool.Stats()
fmt.Printf("size=%d active=%d available=%d\n",
    stats.Size(), stats.Active(), stats.Available())
fmt.Printf("idle_closed=%d lifetime_closed=%d ping_failed=%d\n",
    stats.IdleClosed(), stats.LifetimeClosed(), stats.PingFailed())
fmt.Printf("wait_count=%d wait_time=%v\n",
    stats.WaitCount(), stats.WaitTime())

Every metric you need for alerting and debugging — without pulling in a metrics library.

Benchmarks

goos: darwin
goarch: arm64
cpu: Apple M2 Pro
BenchmarkGetPut_Sequential    8,556,068    139.9 ns/op    0 B/op    0 allocs/op
BenchmarkGetPut_Parallel      5,075,728    245.1 ns/op    0 B/op    0 allocs/op
BenchmarkGetPut_WithPing        216,386   5571   ns/op   81 B/op    2 allocs/op
BenchmarkGetPut_Contended     2,405,068    478.7 ns/op    0 B/op    0 allocs/op

The fast path (sequential, no ping) runs at 139ns with zero allocations. Even under heavy contention (8 workers fighting over 2 connections), it stays under 500ns.

Design Decisions

Decision	Why
Channel over mutex+slice	Natural blocking, zero-alloc `select`/`default` fast path
Lifetime jitter	Prevents thundering herd reconnection storms
Health check ordering	Cheapest checks first (time → time → network)
Background evictor	Don't wait for `Get()` to clean dead connections
`conn.Close()` returns to pool	Familiar `net.Conn` interface — no new API to learn

Inspired By the Best

This pool draws ideas from several production-grade systems:

Feature	Where I Learned It
Channel-based pool	fatih/pool
Idle timeout + max lifetime	pgx, Vitess
Health check on borrow	go-redis, Apache Commons Pool
Background evictor	pgx, Apache Commons Pool, Vitess
Context-aware Get	Vitess, pgx
MarkUnusable	fatih/pool

Get Started

go get github.com/soyvural/connpool@v1.0.0

The repo includes three working examples:

tcp-echo — basic pool usage
redis-proxy — pooling with health checks against Redis
load-balancer — round-robin across multiple backend pools

GitHub: soyvural/connpool

If you're working with TCP connections in Go and need something more robust than a basic pool, give connpool a try. Star the repo if you find it useful — it helps others discover it.

I'd love feedback on the API design, especially if you have use cases I haven't considered. Drop a comment or open an issue!