redis

go-redis 🧰

🧷 Resilient Redis wiring for Go in one call — sensible pool, timeouts, and retries by default, with sentinel failover, cluster, and a health check built in, plus an optional toolkit for the patterns every service rebuilds.

go-redis wraps redis/go-redis/v9 so a service stops re-deriving the same pool sizes, timeouts, and retry policy in every codebase. Connect returns a client that has already Pinged the server, so a successful call means you are ready to serve.

✨ Highlights

• 🛟 Resilient by default — pool, timeouts, retries with backoff, sentinel failover and cluster from one Connect.
• ⚡ Fails fast when you ask — FastFail() gives health probes and fail-open paths a view that gives up in milliseconds while Redis is down.
• 🧰 A toolkit on top — Lua scripts, caching, streams, pub/sub, locks, idempotency keys and rate limiting, each in its own package.
• 🪶 Pay for what you import — the core has no logging or telemetry dependency; the toolkit and otel live in subpackages.
• 🔇 Quiet unless asked — every tool takes a go-log logger for generous diagnostics and discards everything by default.
• 🧪 Tested against real Redis — unit tests on miniredis, integration tests on redis:7 in CI.

📦 Install

go get github.com/Bugs5382/go-redis

🚀 Usage

Connect applies resilient defaults, dials, and verifies readiness with a Ping. Redis() hands you the full go-redis command API.

client, err := redis.Connect(ctx, redis.WithAddr("localhost:6379"))
if err != nil {
	log.Fatal(err)
}
defer client.Close()

rdb := client.Redis()
rdb.Set(ctx, "session:123", "alice", time.Minute)
name, _ := rdb.Get(ctx, "session:123").Result()

🧩 Depend on go-redis only

Nil, Cmdable, and UniversalClient re-export the handful of go-redis names a caller needs in order to name the value Redis() returns, so a wrapper library can depend on go-redis alone and never import github.com/redis/go-redis/v9 directly:

var cmd redis.Cmdable = client.Redis() // or redis.UniversalClient

_, err := cmd.Get(ctx, "session:missing").Result()
if errors.Is(err, redis.Nil) {
	// cache miss
}

Transactions, pipelines and streams get the same treatment. TxFailedErr, Tx, Pipeliner, Cmder, StringCmd, XAddArgs, XMessage and XMessageSliceCmd are aliases of the go-redis names, so an optimistic WATCH loop needs nothing else:

err := client.Redis().Watch(ctx, func(tx *redis.Tx) error {
	n, err := tx.Get(ctx, "audit:head").Result()
	if err != nil && !errors.Is(err, redis.Nil) {
		return err
	}
	_, err = tx.TxPipelined(ctx, func(p redis.Pipeliner) error {
		p.XAdd(ctx, &redis.XAddArgs{Stream: "audit", ID: "*", Values: map[string]any{"prev": n}})
		p.Set(ctx, "audit:head", "next", 0)
		return nil
	})
	return err
}, "audit:head")
if errors.Is(err, redis.TxFailedErr) {
	// another writer got there first: retry
}

🛟 High availability

Point at Redis Sentinel for automatic failover — the client discovers the current master through the sentinels and re-resolves it after a switchover. Redis Cluster is one option away.

// Sentinel-managed failover master.
client, _ := redis.Connect(ctx,
	redis.WithSentinel("mymaster", "localhost:26379", "localhost:26380"),
)

// Redis Cluster.
client, _ := redis.Connect(ctx,
	redis.WithCluster("localhost:7000", "localhost:7001", "localhost:7002"),
)

🎛 Options

Every knob is a functional option, and every one has a resilient default.

client, _ := redis.Connect(ctx,
	redis.WithAddr("localhost:6379"),
	redis.WithUsername("orders-svc"), // an ACL user; leave unset for the default user
	redis.WithPassword("s3cret"),
	redis.WithDB(0),
	redis.WithTLS(&tls.Config{}),
	redis.WithPool(50),
	redis.WithTimeouts(5*time.Second, 3*time.Second, 3*time.Second),
	redis.WithRetry(3, 8*time.Millisecond, 512*time.Millisecond),
	redis.WithDialRetry(5, 100*time.Millisecond),
	redis.WithFastFail(200*time.Millisecond),
)

The retry defaults favour riding out a blip over failing quickly. Each new connection is dialed up to 5 times with 100ms between tries (the go-redis dial loop, made explicit by WithDialRetry), and each command is retried up to 3 times on top of that. While the server is down, one call through the default client can take well over a second to fail (about 1.7s against a refused port in the tests). That is the right trade for work that needs Redis, and the wrong one for work that can do without it; see Failing open for the per-call answer instead of lowering the defaults for everyone.

🔐 ACL users

On Redis 6+ or Valkey, give each service its own ACL user with only the keys and commands it needs, and connect as it. WithUsername sends the user with the WithPassword password on every connection: standalone, cluster, the sentinel-managed master and replicas, and the FastFail view. The sentinels themselves are not authenticated.

// ACL SETUSER orders-svc on >s3cret ~orders:* +@all -@dangerous
client, err := redis.Connect(ctx,
	redis.WithAddr("cache.example.org:6379"),
	redis.WithUsername("orders-svc"),
	redis.WithPassword("s3cret"),
)

Without a username the password authenticates the server's default user, as before. A wrong user or password fails Connect with WRONGPASS, which WaitFor returns at once instead of retrying.

💓 Health

Healthy is a Ping. On the client from Connect it carries the normal retries, so while the server is down it can take a second or more to answer false. For a readiness probe, ask the fail-fast view, which answers within its budget:

if !client.FastFail().Healthy(ctx) {
	// fail the probe
}

⚡ Failing open

Some calls should skip Redis when it is down rather than wait for it: a cache read that can go to the source, a rate-limit check that can let the request through, a feature flag with a safe default. FastFail() returns a view of the same server with no command retries, a single dial try, and a short budget (200ms by default, set with WithFastFail) on its dial, read, write and pool-wait timeouts. While the server refuses connections, a call through the view fails in well under a millisecond.

ff := client.FastFail()

v, err := ff.Redis().Get(ctx, "flags:new-checkout").Result()
switch {
case err == nil:
	return v == "on"
case errors.Is(err, redis.Nil):
	return false // not set
default:
	logger.Warn("flag store unavailable, using the default", "err", err)
	return false // fail open
}

The view is a *redis.Client, so the toolkit takes it as is:

users := cache.New[User](client.FastFail()) // a down Redis falls through to the loader at once
limiter := ratelimit.New(client.FastFail())  // decide what a limiter error means: allow or deny

A few things to know:

• 🔁 One view per client — the view has its own connection pool, built on the first FastFail() call and opened only when used. Calling it again returns the same view.
• 🧹 The parent owns it — Close on the view does nothing; closing the client closes both.
• 🎯 Pick the budget above your normal latency — a slow but healthy server that needs longer than the budget fails on the view too, and the caller takes its fallback.
• 🚫 Not for writes that must land — keep those on the retrying client, where a blip is ridden out instead of reported.
• 🔍 Telling down from broken — Transient(err) is true for the errors that mean the server is unreachable, if a fallback should only cover those.

⏳ Waiting for the server at startup

Connect pings once, so a service that starts before Redis or Valkey answers (after a reboot, say) gets an error. WaitFor retries while the error is Transient (network failures, and the LOADING, MASTERDOWN, TRYAGAIN and CLUSTERDOWN replies), with capped exponential backoff and jitter. Anything else, such as WRONGPASS, is returned at once.

var client *redis.Client
err := redis.WaitFor(ctx, func(ctx context.Context) error {
	c, err := redis.Connect(ctx, redis.WithAddr("cache.example.org:6379"))
	client = c
	return err
}, redis.WithRetryHook(func(attempt int, err error, delay time.Duration) {
	logger.Warn("redis not reachable yet, retrying", "attempt", attempt, "in", delay, "err", err)
}))

WithWaitBackoff(base, max) tunes the waits (default 500ms doubling to 15s).

🔌 Logging & metrics

A minimal Logger (dial diagnostics) and Observer (per-command and per-dial signals) are pluggable and default to no-ops, so the core drags in no logging or telemetry dependency.

client, _ := redis.Connect(ctx,
	redis.WithAddr("localhost:6379"),
	redis.WithObserver(myObserver),
)

📊 OpenTelemetry

The optional otel subpackage turns on tracing and metrics in one call against the global providers, keeping the dependency out of the core.

import redisotel "github.com/Bugs5382/go-redis/otel"

client, _ := redis.Connect(ctx, redis.WithAddr("localhost:6379"))
redisotel.Instrument(client) // spans + metrics per command

🧰 Toolkit

Each tool is optional, builds only on *redis.Client, and lives in its own package, so importing one pulls in nothing else. They all take a context.Context, log through a go-log Logger passed with WithLogger (keys and IDs only, never values; silent by default), and return plain wrapped errors you match with errors.Is.

📜 Lua scripts

script.New hashes the source once; Run sends EVALSHA and, when the server answers NOSCRIPT (first use, after a failover or SCRIPT FLUSH), falls back to EVAL, which caches it again. The lock, idempotency and rate-limit tools are built on it.

import "github.com/Bugs5382/go-redis/script"

incr := script.New(`return redis.call('INCRBY', KEYS[1], ARGV[1])`)
n, err := incr.Run(ctx, client, []string{"counter"}, 5).Int64()

Pass every key the script touches in keys. On a cluster client, keys that hash to different slots fail with ErrCrossSlot before anything is sent, so use a hash tag such as {order:7}:items to keep related keys together.

🗄️ Cache

A typed Cache[T] with Get, Set, GetOrSet and Delete. A miss is ErrMiss, never confused with a failure.

import "github.com/Bugs5382/go-redis/cache"

users := cache.New[User](client,
	cache.WithPrefix("users:"),
	cache.WithJitter(0.1),              // spread expiries
	cache.WithNegativeTTL(time.Minute), // remember "not found"
)
u, err := users.GetOrSet(ctx, id, 5*time.Minute, func(ctx context.Context) (User, error) {
	return db.LoadUser(ctx, id) // return cache.ErrNotFound when there is no such user
})

Concurrent GetOrSet calls for one key share a single load, within one process. If Redis is down, GetOrSet logs a warning and serves from the loader. Values are JSON unless you pass another Codec.

🌊 Streams

streams.Consume runs one consumer in a consumer group: it creates the group, reads with XREADGROUP, acks what the handler accepts, reclaims entries stuck with dead consumers (XAUTOCLAIM), and moves messages that keep failing to a dead-letter stream.

import "github.com/Bugs5382/go-redis/streams"

_, _ = streams.Publish(ctx, client, "orders", map[string]any{"order_id": "A-1"}, streams.WithMaxLen(100000))

err := streams.Consume(ctx, client, streams.Config{
	Stream:        "orders",
	Group:         "billing",
	Consumer:      podName,
	MaxDeliveries: 5, // then to "orders:dead"
}, func(ctx context.Context, msg streams.Message) error {
	return bill(ctx, msg.Values["order_id"]) // an error retries after ClaimMinIdle
})

Delivery is at least once: a message is handled again if its ack is lost, so handlers must be idempotent (the idempotency tool below pairs well). Redis errors back off and retry, and cancelling the context drains in-flight handlers before Consume returns.

📣 Pub/sub

pubsub.Subscribe returns once every channel and pattern is confirmed, then re-subscribes after a dropped connection or failover. Healthy backs a readiness probe.

import "github.com/Bugs5382/go-redis/pubsub"

sub, err := pubsub.Subscribe(ctx, client, pubsub.Topics{
	Channels: []string{"config.reload"},
	Patterns: []string{"orders.*"},
}, func(ctx context.Context, msg pubsub.Message) {
	route(ctx, msg.Channel, msg.Payload)
})
if err != nil {
	return err
}
defer sub.Close()

Redis pub/sub is at most once: messages published while the subscriber is disconnected are lost. Use streams when every message must arrive. The handler runs one message at a time, so hand slow work to your own goroutines.

🔒 Lock

lock.Acquire stores a random token with SET NX PX; Release and Extend only act while the key still holds that token, so an expired holder can never free the next holder's lock.

import "github.com/Bugs5382/go-redis/lock"

l, err := lock.Acquire(ctx, client, "jobs:nightly-report", 30*time.Second,
	lock.WithWait(5*time.Second),        // retry with backoff instead of failing fast
	lock.WithAutoExtend(10*time.Second), // keep it alive while the job runs
)
if errors.Is(err, lock.ErrNotAcquired) {
	return nil // another worker has it
}
defer l.Release(ctx)
// stop work if <-l.Lost() fires

This is a single-instance lock, not Redlock. Redis replicates asynchronously, so a failover can hand the same lock to a second client, and a long pause can outlive the TTL. Use it freely to avoid duplicate work; when overlapping holders would corrupt data, add a fencing token or make the downstream idempotent.

🔁 Idempotency

Store[T].Do runs a function at most once per key within a TTL and replays the stored result to duplicates, which is what a retried request or a redelivered message needs.

import "github.com/Bugs5382/go-redis/idempotency"

payments := idempotency.New[Receipt](client, idempotency.WithLease(30*time.Second))
r, err := payments.Do(ctx, requestID, 24*time.Hour, func(ctx context.Context) (Receipt, error) {
	return charge(ctx, order)
})
// a duplicate while charge runs gets idempotency.ErrInProgress (or waits, with WithWait)

On failure the key is released for a retry by default; KeepOnError stores the failure instead. The lease frees keys left by a caller that crashed mid-run, so keep it above the function's longest run. Like the lock, the guarantee is as strong as the Redis primary holding the key.

🚦 Rate limiting

ratelimit decides each request with one atomic Lua script per key, timed by the Redis server clock, so every app server agrees. It works on cluster.

import "github.com/Bugs5382/go-redis/ratelimit"

limiter := ratelimit.New(client) // token bucket; ratelimit.WithStrategy(ratelimit.SlidingWindow) for an exact window
r, err := limiter.Allow(ctx, "api:"+userID, ratelimit.Limit{Rate: 100, Period: time.Minute, Burst: 20})
if err != nil {
	return err
}
if !r.Allowed {
	return tooManyRequests(r.RetryAfter)
}

The token bucket allows bursts up to Burst and refills at Rate per Period; the sliding window never admits more than Rate in any Period. It needs Redis 5 or newer (the scripts call TIME).

🛠 Develop

task build    # go build ./...
task test     # go test ./...
task ci       # build + vet + race tests + linters
task license  # verify MIT headers (golic)

Integration tests run against a live server and are excluded from the default build:

REDIS_ADDR=localhost:6379 task test-integration

⚖️ License

MIT © 2026 Shane