redsync

Redsync provides a Redis-based distributed mutual exclusion lock for Go, implementing the Redlock algorithm described in Redis’s official distributed-locking proposal. Instead of relying on a single Redis instance as a single point of failure, Redsync acquires a lock across a quorum of independent Redis pools, only considering the lock held once a majority of nodes agree — reducing the risk of two processes believing they hold the same lock at once.

The library ships as a thin coordination layer over pluggable Redis drivers: it defines a small redis.Pool/redis.Conn interface and provides adapters for go-redis (v7, v8, v9), Redigo, Rueidis, and Valkey-go, so teams can adopt whichever Redis client they already use without vendoring a second one. Locking, unlocking, and extending are implemented with Lua scripts executed atomically on each node, and context-aware variants (LockContext, UnlockContext, ExtendContext) let callers integrate cancellation and timeouts cleanly into existing Go control flow.

What You Get

• A Redsync factory that wraps one or more Redis connection pools and produces named Mutex instances
• Quorum-based locking: a lock is only considered acquired once more than half of the configured Redis pools agree, tolerating individual node failure
• Blocking (Lock/LockContext) and non-blocking (TryLock/TryLockContext) acquisition, both with context.Context support for cancellation and deadlines
• Atomic unlock and extend operations implemented as Lua scripts so a lock can only be released or renewed by the process that holds its value token
• Driver adapters for go-redis v7/v8/v9, Redigo, Rueidis, and Valkey-go under redis/, so the library plugs into whichever client is already in use
• Tunable options (WithExpiry, WithTries, WithRetryDelay, WithDriftFactor, WithTimeoutFactor, WithShufflePools, WithFailFast, WithSetNXOnExtend) for adapting the algorithm’s timing behavior to a given deployment

Common Use Cases

• Ensuring a scheduled job or cron task runs on exactly one instance in a horizontally scaled fleet
• Guarding a critical section of code (e.g. a resource-intensive migration or cache rebuild) so only one replica executes it at a time
• Coordinating access to an external API with strict rate limits shared across multiple service instances
• Preventing duplicate processing of the same message or event when multiple consumers read from the same queue
• Building higher-level distributed coordination primitives (leader election, work queues) on top of a simple mutex

Under The Hood

Architecture The library centers on two core types: Redsync, a thin factory in redsync.go holding a slice of redis.Pool, and Mutex, in mutex.go, which holds retry/timing parameters plus that same pool slice. Locking flows through lockContext, which runs actOnPoolsAsync concurrently against every pool via acquire (a Redis SETNX), tallies successes against a quorum requirement (len(pools)/2 + 1), and computes lock validity from elapsed time minus a clock-drift factor; on quorum failure it immediately releases whatever partial locks it took via the Lua deleteScript. Unlock and Extend follow the same fan-out-then-quorum-check pattern. The Mutex is fully decoupled from any specific Redis client through the redis.Pool/redis.Conn interface defined in redis/redis.go, with driver-specific adapters for go-redis (v7/v8/v9), Redigo, Rueidis, and Valkey-go living in isolated subpackages that each implement just Get/Set/SetNX/Eval/ScriptLoad/PTTL/Close. Changing the core Redlock quorum/timeout math in lockContext would ripple through Lock, TryLock, and Extend simultaneously, while swapping a driver only touches its own adapter file.

Tech Stack A Go module with no required runtime dependencies for the core algorithm itself — go.mod lists several optional Redis driver dependencies (multiple go-redis major versions, Redigo, Rueidis, Valkey-go) that are only pulled in when their corresponding adapter package is imported, keeping the base library lean. Concurrency uses golang.org/x/sync inside actOnPoolsAsync to query every Redis pool in parallel, and both math/rand and crypto/rand are used for retry jitter and generating the mutex’s random value token. Build and CI tooling is a plain Makefile plus GitLab CI configuration alongside a legacy Travis config; there is no code generation and no bespoke build system.

Code Quality The repository includes a substantial suite of _test.go files covering Lock/Unlock/Extend/Valid behavior across driver combinations, spinning up ephemeral Redis instances via a forked tempredis dependency rather than mocking the Redis protocol, and every driver adapter carries its own dedicated test file. Errors are typed rather than swallowed — sentinel errors (ErrFailed, ErrExtendFailed, ErrLockAlreadyExpired) sit alongside structured error types (ErrTaken, ErrNodeTaken, RedisError) that implement Unwrap for compatibility with Go’s errors.Is/As. The public API consistently offers both context-aware and plain variants of every operation, and naming follows idiomatic Go conventions throughout.

What Makes It Unique Redsync’s contribution isn’t a novel algorithm — it’s a faithful, well-scoped Go implementation of Redis’s own published Redlock proposal, in the same lineage as ports for other languages. Its real differentiation is breadth of driver support, offering adapters for several separate Redis clients behind one common interface, plus tunable knobs like fail-fast quorum returns, pool shuffling, and SETNX-based extend semantics that address practical production edge cases — reducing tail latency and improving lock-renewal reliability during Redis restarts — rather than introducing new distributed-systems techniques.