idempotency_lock 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88b6cc80e37f3db005c446a96005520945b141ef45f1ff4d90863975de52ed45
-  data.tar.gz: 43adf42af7496edc68cf46590fc2d09d585214c44dcd57487d0c290161f4af72
+  metadata.gz: aa9a2abc50beeef3b17f4b11c444373735a0c04f5cb451f7c1f17cf4592e63f8
+  data.tar.gz: 7eb8ff38a775b71eef1c607da5542b11f62c95b5a1146ff92c468da1b370d590
 SHA512:
-  metadata.gz: 989d09faf1a493cf14ee9426c4ffa67275a761e5784072164a0b3e24f9f3202a0424308f9621cace94e2245707ae25d936b96349a8798dfd5bb2b38656529b7c
-  data.tar.gz: '084463272e767a8579dde4848d1a386645119404d65c608ee5d2960940963e877dbeaa3ed4c481679e6d5e14811cdeabeee2427a906571e2db9ea1366baf7344'
+  metadata.gz: feea7d88474b9fbda1412b901c157b6634764e5a6933f297141159476198926a96005d251b8735ccad8604baa4e7accd90116cc2378dcc194d54271937396785
+  data.tar.gz: a8a13eeed8e4ec35ffca2af0b571295da250539d060198f00ae14d6d0c67c885a1d1d71cc78b9b30e1b74109aa490efeb6be91ea39e1f30ef4f5e9abb1137bd0

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-01-24
+
+### Added
+
+- `IdempotencyLock.temporarily` - Execute a block with an ephemeral lock that is
+  automatically released when the block completes (success or error)
+- `wait:` parameter for `temporarily` - Poll for lock availability with configurable
+  timeout (e.g., `wait: 5.seconds`)
+
+## [0.1.3] - 2025-12-06
+
+### Changed
+
+- Use `updated_at` instead of `expires_at` for optimistic locking (more reliable
+  since it's system-managed and always moves forward)
+
 ## [0.1.2] - 2025-12-06
 
 ### Fixed

data/README.md

@@ -73,6 +73,49 @@ IdempotencyLock.once("periodic-task", ttl: 3600) do
 end
 ```
 
+### Temporary Locks (Auto-Release)
+
+Use `temporarily` when you want exclusive execution but don't need permanent idempotency. The lock is automatically released when the block completes (success or error):
+
+```ruby
+# Lock is held only while the block runs
+IdempotencyLock.temporarily("process-payment-#{payment.id}") do
+  PaymentProcessor.charge(payment)
+end
+# Lock is now released - another call can acquire it
+```
+
+This is useful for:
+- Preventing concurrent processing of the same resource
+- Mutex-style synchronization across processes/servers
+- Operations that should be exclusive but retriable
+
+#### Waiting for Lock Availability
+
+By default, `temporarily` returns immediately if the lock is held. Use `wait:` to poll until the lock becomes available:
+
+```ruby
+# Wait up to 5 seconds for lock, then skip if still unavailable
+result = IdempotencyLock.temporarily("exclusive-job", wait: 5.seconds) do
+  process_job
+end
+
+if result.skipped?
+  puts "Could not acquire lock within timeout"
+end
+```
+
+#### TTL for Crash Protection
+
+Combine with `ttl:` to ensure locks are released even if the process crashes:
+
+```ruby
+IdempotencyLock.temporarily("long-job", ttl: 10.minutes, wait: 30.seconds) do
+  # If process crashes, lock expires after 10 minutes
+  long_running_task
+end
+```
+
 ### Error Handling
 
 Control what happens when an error occurs inside the block:
@@ -172,6 +215,17 @@ class ImportantJob
 end
 ```
 
+### Exclusive Resource Processing
+
+```ruby
+# Ensure only one process handles a payment at a time
+def process_payment(payment_id)
+  IdempotencyLock.temporarily("payment-#{payment_id}", wait: 10.seconds) do
+    Payment.find(payment_id).process!
+  end
+end
+```
+
 ## Database Schema
 
 The gem creates an `idempotency_locks` table with:

data/lib/idempotency_lock/lock.rb

@@ -56,12 +56,12 @@ module IdempotencyLock
         return false if existing.nil?
         return false unless existing.expired?(now: now)
 
-        # Optimistic locking: use the observed expires_at in the WHERE clause.
+        # Optimistic locking: use the observed updated_at in the WHERE clause.
         # This prevents a race where two processes both see an expired lock and
         # both try to claim it. Only one UPDATE will match; the other returns 0.
-        # This is safer than `WHERE expires_at < now` which could allow a second
-        # process to steal a lock if the first used a short TTL.
-        updated = where(name: name, expires_at: existing.expires_at)
+        # We use updated_at rather than expires_at because it's system-managed
+        # and always moves forward, making it more reliable for concurrency control.
+        updated = where(name: name, updated_at: existing.updated_at)
                   .update_all(expires_at: expires_at, executed_at: now, updated_at: now)
 
         updated.positive?

data/lib/idempotency_lock/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IdempotencyLock
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/idempotency_lock.rb

@@ -27,6 +27,9 @@ module IdempotencyLock
   ON_ERROR_KEEP_LOCKED = :keep    # Keep lock in place (default)
   ON_ERROR_RAISE = :raise         # Re-raise after cleanup/logging
 
+  # Wait retry interval for temporarily with wait option
+  WAIT_RETRY_INTERVAL = 0.1 # 100ms between retry attempts
+
   class << self
     # Execute a block exactly once for the given operation name.
     #
@@ -54,6 +57,40 @@ module IdempotencyLock
     # Convenience alias for `once`
     alias wrap once
 
+    # Execute a block with a temporary lock that is automatically released
+    # when the block completes (success or error).
+    #
+    # Unlike `once`, this method always releases the lock after execution,
+    # making it suitable for mutex-style synchronization rather than idempotency.
+    #
+    # @param name [String] unique identifier for this lock
+    # @param ttl [ActiveSupport::Duration, Integer, nil] time-to-live for crash protection
+    # @param wait [ActiveSupport::Duration, Integer, nil] how long to wait for lock availability
+    # @yield The block to execute while holding the lock
+    # @return [Result] containing execution status and return value
+    def temporarily(name, ttl: nil, wait: nil)
+      raise ArgumentError, "Block required" unless block_given?
+
+      acquired = acquire_with_wait(name, ttl: ttl, wait: wait)
+
+      unless acquired
+        log_debug("Lock already held for '#{name}', skipping execution")
+        return Result.new(executed: false, skipped: true)
+      end
+
+      log_debug("Temporary lock acquired for '#{name}', executing block")
+      begin
+        value = yield
+        Result.new(executed: true, value: value)
+      rescue StandardError => e
+        log_error("Exception in temporary lock block '#{name}': #{e.class} - #{e.message}")
+        Result.new(executed: true, error: e)
+      ensure
+        Lock.release(name)
+        log_debug("Temporary lock released for '#{name}'")
+      end
+    end
+
     # Release a lock manually (useful for testing or manual intervention)
     #
     # @param name [String] the lock name to release
@@ -86,6 +123,29 @@ module IdempotencyLock
 
     private
 
+    def acquire_with_wait(name, ttl:, wait:)
+      now = Time.current
+      expires_at = calculate_expires_at(ttl, now)
+      acquired = Lock.acquire(name, expires_at: expires_at, now: now)
+
+      return true if acquired
+      return false if wait.nil?
+
+      # Calculate deadline for waiting
+      wait_seconds = wait.respond_to?(:to_f) ? wait.to_f : wait.to_i
+      deadline = Time.current + wait_seconds
+
+      while Time.current < deadline
+        sleep(WAIT_RETRY_INTERVAL)
+        now = Time.current
+        expires_at = calculate_expires_at(ttl, now)
+        acquired = Lock.acquire(name, expires_at: expires_at, now: now)
+        return true if acquired
+      end
+
+      false
+    end
+
     def calculate_expires_at(ttl, now)
       return nil if ttl.nil?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idempotency_lock
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - John Nagro