redislock

A fencing token is a strictly increasing value used to protect resources from clients that lose their lock (e.g., due to a long GC pause) but attempt to perform writes anyway.

To use them:

1. Set Options.FenceKey in locker.Obtain. This key is used to store the monotonic counter in Redis.
2. Retrieve the token using lock.FenceToken().
3. Include this token in every write operation to your protected resource.
4. The resource must atomically check that the incoming token is greater than or equal to the highest token it has already processed. If the token is older, the write must be rejected.

Important Notes:

• Redis Cluster Compatibility: The FenceKey must hash to the same slot as the lock key. Use Redis hash tags (e.g., lock key {job}:lock and fence key {job}:fence) to ensure they reside on the same node.
• Monotonicity: On a single Redis instance, the token is strictly monotonic. In a Sentinel or Cluster failover scenario, the token might regress if the INCR operation is lost during failover. For absolute cross-failover monotonicity, use a linearizable store.
• Persistence: The counter persists across lock releases and continues to increment.

// Obtain a lock with a fencing token.
lock, err := locker.Obtain(ctx, "my-key", time.Second, &redislock.Options{FenceKey: "my-key:fence"})
if err != nil {
	log.Fatalln(err)
}
defer lock.Release(ctx)

// FenceToken is 0 without a FenceKey. Stamp writes with the token; reject older ones.
if token := lock.FenceToken(); token != 0 {
	fmt.Printf("fenced write with token %d\n", token)
}

To use redislock, create a new locker using redislock.New(client) where client is a *redis.Client. Use locker.Obtain(ctx, key, ttl, options) to attempt to acquire a lock. If the lock cannot be acquired, it returns redislock.ErrNotObtained. Once obtained, you must ensure the lock is released by calling lock.Release(ctx), typically via defer. You can also check the remaining time on the lock using lock.TTL(ctx) and extend the lock duration using lock.Refresh(ctx, ttl, options).

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/bsm/redislock"
	"github.com/redis/go-redis/v9"
)

func main() {
	client := redis.NewClient(&redis.Options{
		Network: "tcp",
		Addr:    "127.0.0.1:6379",
	})
	defer client.Close()

	locker := redislock.New(client)
	ctx := context.Background()

	// Try to obtain lock.
	lock, err := locker.Obtain(ctx, "my-key", 100*time.Millisecond, nil)
	if err == redislock.ErrNotObtained {
		fmt.Println("Could not obtain lock!")
		return
	} else if err != nil {
		log.Fatalln(err)
		return
	}

	// Don't forget to defer Release.
	defer lock.Release(ctx)
	fmt.Println("I have a lock!")

	// Extend my lock.
	if err := lock.Refresh(ctx, 100*time.Millisecond, nil); err != nil {
		log.Fatalln(err)
	}
}

redislock does not provide an internal background goroutine for refreshing locks. If you need a lock to outlive its initial TTL, you must implement your own watchdog pattern.

Best Practices:

• Refresh Interval: Set the refresh interval to approximately ttl/3. This provides enough buffer to handle transient Redis connectivity issues before the lock actually expires.
• Error Handling: If lock.Refresh returns redislock.ErrNotObtained, it means the lock was lost or stolen. In this case, you should immediately cancel the context used for the protected work to prevent further operations with an invalid lock.
• Ownership: The caller remains responsible for calling Release.

// Obtain a lock with a 30s TTL.
const ttl = 30 * time.Second
lock, err := locker.Obtain(ctx, "my-key", ttl, nil)
if err != nil {
	log.Fatalln(err)
}
defer lock.Release(context.Background())

// Start a watchdog that refreshes the lock every ttl/3.
workCtx, cancel := context.WithCancel(ctx)
defer cancel()

go func() {
	t := time.NewTicker(ttl / 3)
	defer t.Stop()
	for {
		select {
		case <-workCtx.Done():
			return
		case <-t.C:
			if err := lock.Refresh(workCtx, ttl, nil); err != nil {
				log.Printf("lock refresh failed: %v", err)
				cancel() // Stop the work if refresh fails
				return
			}
		}
	}
}()

// ... do work using workCtx ...