hanikamu-operation 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 565d28c9c7d700db3b5bdb2be0ddd960951d07bf027a16b946cc8c527ad45ae6
-  data.tar.gz: 2c241ea17940bc687881d746361fa94fe85dfc3149d410c4b665c44d0367491b
+  metadata.gz: 30ca0f88ea8223a13a4b23eda4d6cefb6d010a5affedbc93e6a2d69614ba486b
+  data.tar.gz: 0601bee8022568f95a8a33163bb823bfe3fb09036c32d62ab2c7b2482819a06b
 SHA512:
-  metadata.gz: da40b97d680e9f4f99b9819283c5d9441335b5a2e05b77143ee33b04635db03c6a3e00896f4b98f9481950d2b52721080c48b958eef8e3ba0133dda020da221d
-  data.tar.gz: 6bf7537f8d8b3351f122c4e3a9c0de036c736a97907dcdf460fa9bd932600051f2807f39aaefaf28ee79b5f48264d7db0a9dc0132470f475cc45c4392701d8f4
+  metadata.gz: d097cc17ab86c0c5e29eace1bedac6fbcb89b55a85da19a035d1a012e6c0e55d06a4aefa9212605576f25303e521cbf7f090a27a6d6e7fc1381245789b6750cb
+  data.tar.gz: adb979d5f17ae5c50285041e38051db0b8aabf7d4c10ef5529980b2b193db2461d6bdb236f5fcc46227f60142a08a4e69605130b4783f971ee242958ad8c225c

data/CHANGELOG.md

@@ -22,6 +22,17 @@
   Passing both `:if` and `:unless`, or a non-callable condition, raises `ArgumentError` at class
   definition time.
 
+## [0.3.1] - 2026-08-26
+
+- Fixed `RedisClient::NoScriptError: NOSCRIPT` raised on every `within_mutex` acquire when a host
+  application runs its test suite with `Redlock::Client.testing_mode = :bypass` against a Redis with
+  an empty script cache (typically a fresh CI container). 0.3.0 read the lease window with
+  `get_remaining_ttl_for_resource`, which evaluates a Lua script; `:bypass` also stubs out Redlock's
+  script loading, so the `EVALSHA` failed and Redlock's own recovery could not reload the script.
+  The lease window is now taken from the `:validity` that Redlock already returns when the lock is
+  acquired — no Lua script, and one fewer Redis round-trip per acquire. Lease-aware reentrancy
+  behaviour is unchanged.
+
 ## [0.3.0] - 2026-08-25
 
 - `within_mutex` is now reentrant within the same execution context (fiber-local, effectively

data/README.md

@@ -414,7 +414,7 @@ end
 - **Same execution context only**: reentrancy is keyed to the current fiber (via a fiber-local lease stack), which in the usual thread-per-request / thread-per-job model means the current thread. A synchronous callback cascade or nested call runs in that same context, so it is treated as the same holder.
 - **Cross-context is unchanged**: a different thread, process, or independently scheduled fiber (e.g. a separate background job or web request) still contends on Redis and still raises `Redlock::LockError` when the key is held elsewhere.
 - **No configuration, no opt-out**: a same-context re-acquire of a held key can only self-deadlock, so there is no valid non-reentrant use case. Reentrancy is always on.
-- **Lease-aware, not just lexical**: the inline bypass only happens while a lease this context actually holds on the key is still live. Each real acquire records a deadline derived from Redis's own remaining TTL (already clock-drift adjusted), so the bypass window never outlives the lease Redis granted. If an operation runs past its mutex TTL (so the lease could have lapsed and been taken over), a nested same-key call does **not** run inline — it performs a real acquire, which re-locks the key if it is free (its own lease frame, so deeper nested calls still bypass safely) or raises `Redlock::LockError` if another context now owns it. Reentrancy therefore never weakens mutual exclusion beyond what Redlock itself guarantees.
+- **Lease-aware, not just lexical**: the inline bypass only happens while a lease this context actually holds on the key is still live. Each real acquire records a deadline from the `:validity` Redlock returns at acquire time (the TTL minus acquisition time minus clock drift), so the bypass window never outlives the lease Redis granted — and no extra Redis round-trip or Lua script is needed, which keeps this working under `Redlock::Client.testing_mode = :bypass`. If an operation runs past its mutex TTL (so the lease could have lapsed and been taken over), a nested same-key call does **not** run inline — it performs a real acquire, which re-locks the key if it is free (its own lease frame, so deeper nested calls still bypass safely) or raises `Redlock::LockError` if another context now owns it. Reentrancy therefore never weakens mutual exclusion beyond what Redlock itself guarantees.
 - **TTL is not refreshed** by nested reentrant calls — the outermost acquire's expiry still applies.
 
 ### Database Transactions with `within_transaction`

data/docs/projects/20260825_hanikamu_reentrant_mutex.md

@@ -89,15 +89,24 @@ Add to the `private` section (see `lib/hanikamu/operation.rb` for the full set):
 # Real acquire: push this lease's deadline onto this context's per-key stack, run,
 # then pop. A nested call that finds the lease expired lands here again and takes a
 # fresh, independent lease (its own stack frame), so it never contends with itself.
+# Uses `lock` (not `lock!`) because only `lock` yields the lock_info carrying
+# Redlock's drift-adjusted `:validity`; `lock` returns `!!lock_info`, so the
+# operation's own result is captured and returned explicitly.
 def _acquire_and_run(lock_key, &)
-  Hanikamu::Operation.redis_lock.lock!(lock_key, self.class._mutex_expire_milliseconds) do
-    _push_lease(lock_key)
+  result = nil
+
+  Hanikamu::Operation.redis_lock.lock(lock_key, self.class._mutex_expire_milliseconds) do |lock_info|
+    raise Redlock::LockError, lock_key unless lock_info
+
+    _push_lease(lock_key, lock_info[:validity])
     begin
-      yield
+      result = yield
     ensure
       _pop_lease(lock_key)
     end
   end
+
+  result
 end
 
 def _stable_lock_key(key)
@@ -125,12 +134,11 @@ def _reentrant_lease_valid?(lock_key)
   _monotonic_ms < stack.last
 end
 
-# Anchor the deadline to Redis's authoritative remaining TTL (already clock-drift
-# adjusted by Redlock), captured right after acquisition, so the window never outlives
-# the lease Redis actually granted — even if acquisition retried/took time.
-def _push_lease(lock_key)
-  remaining = Hanikamu::Operation.redis_lock.get_remaining_ttl_for_resource(lock_key)
-  deadline = _monotonic_ms + (remaining || self.class._mutex_expire_milliseconds)
+# Anchor the deadline to the lease Redlock actually granted: `:validity` is the TTL
+# minus acquisition time minus Redlock's clock drift allowance, so the window never
+# outlives the real lease even when the acquire was slow or retried.
+def _push_lease(lock_key, validity_ms)
+  deadline = _monotonic_ms + (validity_ms || self.class._mutex_expire_milliseconds)
   (_lease_stacks[lock_key] ||= []) << deadline
 end
 
@@ -145,15 +153,19 @@ end
 
 ### Why this is correct / safe
 
-- **Return value preserved:** `redis_lock.lock!` returns the block's value; `_acquire_and_run`
-  returns the value of `yield` (the `ensure` around `_pop_lease` doesn't override it), and the bypass
-  path is a plain `yield`. Operation responses flow through unchanged.
-- **Exception-safe:** a lease is only pushed once we're inside the `lock!` block, and the `ensure`
-  always pops it. If `lock!` itself fails to acquire (real contention from another context), the
-  block never runs, so nothing is pushed and nothing leaks.
+- **Return value preserved:** `_acquire_and_run` captures the value of `yield` and returns it (the
+  `ensure` around `_pop_lease` doesn't override it, and `lock`'s own `!!lock_info` return is
+  discarded), and the bypass path is a plain `yield`. Operation responses flow through unchanged.
+- **Exception-safe:** a lease is only pushed once acquisition succeeded, and the `ensure` always pops
+  it. If the acquire fails (real contention from another context), `lock_info` is falsy, we raise
+  `Redlock::LockError` before pushing, so nothing leaks.
+- **No Lua script on the mutex path:** the lease window comes from the `:validity` Redlock returns at
+  acquire time, not from a follow-up TTL query. That avoids a second Redis round-trip and, crucially,
+  works under `Redlock::Client.testing_mode = :bypass`, which stubs out script loading — a
+  script-based TTL read raises `NOSCRIPT` there on a cold Redis (see 0.3.1 in the CHANGELOG).
 - **Lease-aware, not merely lexical:** the bypass is gated on a live lease — each real acquire pushes
-  a deadline derived from Redis's own remaining TTL (already clock-drift adjusted), captured right
-  after acquisition, so the window never outlives the lease Redis granted (even under a slow/retried
+  a deadline derived from Redlock's drift-adjusted `:validity` (TTL minus the time acquisition took),
+  so the window never outlives the lease Redis granted (even under a slow/retried
   acquire). If an operation outlives its mutex TTL, a nested same-key call re-acquires for real as
   its own stack frame instead of running inline — re-locking a free key (deeper nested calls then
   bypass *that* replacement lease, avoiding a fresh self-deadlock) or raising `Redlock::LockError` on
@@ -206,6 +218,9 @@ The suite already uses a **real Redis** (`described_class.redis_lock`). Cover:
    the live replacement lease, not the expired outer deadline.
 8. **Mutable key snapshot.** An op whose lock-key method returns a String that `execute` mutates
    still cleans up the stack (no leaked entry under the pre-mutation value).
+9. **Redlock `:bypass` on a cold Redis.** With `Redlock::Client.testing_mode = :bypass` and the
+   script cache flushed, a nested same-key run must complete without raising — proving the mutex
+   path evaluates no Lua script (regression guard for the 0.3.1 `NOSCRIPT` fix).
 
 ---
 

data/lib/hanikamu/operation.rb

@@ -231,15 +231,28 @@ module Hanikamu
     # key, run, then release. Nested reentrant calls ride on this lease without touching
     # Redis; a nested call that finds the lease expired lands here again and takes a
     # fresh, independent lease (its own stack frame), so it never contends with itself.
+    #
+    # Uses `lock` rather than `lock!` because only `lock` yields the lock_info, which
+    # carries Redlock's own drift-adjusted `:validity`. Reading the lease window from
+    # the acquire result costs no extra Redis round-trip and evaluates no Lua script —
+    # the latter matters because under `Redlock::Client.testing_mode = :bypass` the
+    # scripts are never loaded, so any EVALSHA raises NOSCRIPT on a cold Redis.
+    # `lock` returns `!!lock_info`, so the operation's own result is captured instead.
     def _acquire_and_run(lock_key, &)
-      Hanikamu::Operation.redis_lock.lock!(lock_key, self.class._mutex_expire_milliseconds) do
-        _push_lease(lock_key)
+      result = nil
+
+      Hanikamu::Operation.redis_lock.lock(lock_key, self.class._mutex_expire_milliseconds) do |lock_info|
+        raise Redlock::LockError, lock_key unless lock_info
+
+        _push_lease(lock_key, lock_info[:validity])
         begin
-          yield
+          result = yield
         ensure
           _pop_lease(lock_key)
         end
       end
+
+      result
     end
 
     # A key is documented as a String; freeze a copy so it is a stable, immutable
@@ -278,12 +291,11 @@ module Hanikamu
       _monotonic_ms < stack.last
     end
 
-    # Anchor the deadline to Redis's authoritative remaining TTL (already clock-drift
-    # adjusted by Redlock), captured right after acquisition, so the window never
-    # outlives the lease Redis actually granted — even if acquisition retried/took time.
-    def _push_lease(lock_key)
-      remaining = Hanikamu::Operation.redis_lock.get_remaining_ttl_for_resource(lock_key)
-      deadline = _monotonic_ms + (remaining || self.class._mutex_expire_milliseconds)
+    # Anchor the deadline to the lease Redlock actually granted: `:validity` is the TTL
+    # minus the time acquisition took minus Redlock's clock drift allowance, so the
+    # window never outlives the real lease even when the acquire was slow or retried.
+    def _push_lease(lock_key, validity_ms)
+      deadline = _monotonic_ms + (validity_ms || self.class._mutex_expire_milliseconds)
       (_lease_stacks[lock_key] ||= []) << deadline
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hanikamu-operation
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Nicolai Seerup