idempotency_lock 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4920afd8d5429063037ecb787cf54915a0837d01dcc0e347143117c92aa1e842
-  data.tar.gz: fb92062859dc7f2dad7ecc897c6f327ddf486376b1177f2adbee01b595853429
+  metadata.gz: aa9a2abc50beeef3b17f4b11c444373735a0c04f5cb451f7c1f17cf4592e63f8
+  data.tar.gz: 7eb8ff38a775b71eef1c607da5542b11f62c95b5a1146ff92c468da1b370d590
 SHA512:
-  metadata.gz: e81784700e7745eb981190b9aa53268c79f47ee1897ff20ea04669254e684abd1e012247d35de67b6af499539e4034651a9a28486e9c3494137e7749af22a80d
-  data.tar.gz: 32838477ada126fce6e6ff26f5a07e6b363d34a846314e46808917e90a934cb283a62d21bb0312c3a451cf2f3cff67e20dd31a5cd8f77f67a7df536fb2f92e5c
+  metadata.gz: feea7d88474b9fbda1412b901c157b6634764e5a6933f297141159476198926a96005d251b8735ccad8604baa4e7accd90116cc2378dcc194d54271937396785
+  data.tar.gz: a8a13eeed8e4ec35ffca2af0b571295da250539d060198f00ae14d6d0c67c885a1d1d71cc78b9b30e1b74109aa490efeb6be91ea39e1f30ef4f5e9abb1137bd0

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [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

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IdempotencyLock
-  VERSION = "0.1.3"
+  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.3
+  version: 0.2.0
 platform: ruby
 authors:
 - John Nagro