Add optional fencing token minted atomically on Obtain

[nijatsdev]

Closes #93.

Adds an opt-in fencing token to Obtain: a strictly increasing value, incremented atomically inside obtain.lua on each new acquisition and returned by Lock.FenceToken. Callers stamp writes to the protected resource with the token and reject any write carrying an older one, fencing out a stale lock holder per Martin Kleppmann's How to do distributed locking.

API

lock, _ := locker.Obtain(ctx, "my-key", time.Second, &redislock.Options{FenceKey: "my-key:fence"})
if token := lock.FenceToken(); token != 0 {
    // stamp writes to the protected resource with `token`
}

• Options.FenceKey string — the key the fence counter lives at; non-empty opts in (default off).
• Lock.FenceToken() int64 — the token, or 0 when obtained without FenceKey. Tokens start at 1, so 0 is an unambiguous "unfenced" sentinel.

Behaviour

• The token is minted only on a genuinely new acquisition (the msetnx path). A re-entrant override by the current holder returns the existing token without incrementing, so refreshing-via-obtain does not inflate it.
• The fence key is caller-supplied rather than auto-derived, so you control its placement. It is passed in KEYS (the last entry when fencing is on, flagged via ARGV), so on Redis Cluster a fence key that does not share a slot with the lock key fails with CROSSSLOT up front rather than mid-execution.
• The counter persists across Release, so it keeps increasing.
• Backward compatible: without FenceKey, obtain.lua returns the original "OK" status and FenceToken returns 0. Existing tests pass unchanged.

Caveat (documented in the README)

The token is only as monotonic as the underlying Redis. On a single instance it is strict; on a Sentinel/Cluster failover that loses the INCR, it can regress. For strict cross-failover monotonicity, source the token from a linearizable store.

Tests

• TestObtain_fence — token minted, monotonic across terms, absent without FenceKey.
• TestObtain_fence_reentrant — re-entrant override does not advance the token.

[dim]

LGTM, only a minor comment, open to debate

[dim]

I would simplify this and always return 0 if not fenced. you can mention this in the method documentation, seems the better choice

[nijatsdev]

Good call — done. FenceToken now returns int64 with 0 meaning unfenced; since tokens start at 1 the sentinel is unambiguous, and I noted it on the method doc. Thanks!

[dim]

Sorry, one more thing I thought of

[dim]

one little concern left: I don't like the fact that we are automatically generating key names for the fence key, I always prefer to delegate this to the user as there are sometimes non-trivial implications, e.g. redis cluster or other redis implementations where key names matter. I would therefore suggest:

lock, err := locker.Obtain(ctx, "my-key", time.Second, &redislock.Options{FenceKey: "my-key:fence"})

what do you think?

[nijatsdev]

Agreed — auto-generating the key name hides exactly the kind of Cluster/key-placement footgun you're describing, so letting the caller own it is the right call. Done: Options.FenceKey is now caller-supplied.

I also took it one step further for Cluster safety — the fence key now goes in KEYS (not ARGV), as the last entry when fencing is on, with an ARGV flag telling the script to treat it specially. That way Redis validates the slot up front and a misplaced fence key fails with CROSSSLOT before the script runs, rather than mid-execution.

[dim]

Thanks!!