idempotency_lock 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa9a2abc50beeef3b17f4b11c444373735a0c04f5cb451f7c1f17cf4592e63f8
-  data.tar.gz: 7eb8ff38a775b71eef1c607da5542b11f62c95b5a1146ff92c468da1b370d590
+  metadata.gz: '0952806b286b015b244bbf5b11a3f1382007d202ba6195b16b0df7d7126fc8e4'
+  data.tar.gz: 67fe502a6e14b2c0e54090d2127e2e823b466dda34be01e0275826e9b8365414
 SHA512:
-  metadata.gz: feea7d88474b9fbda1412b901c157b6634764e5a6933f297141159476198926a96005d251b8735ccad8604baa4e7accd90116cc2378dcc194d54271937396785
-  data.tar.gz: a8a13eeed8e4ec35ffca2af0b571295da250539d060198f00ae14d6d0c67c885a1d1d71cc78b9b30e1b74109aa490efeb6be91ea39e1f30ef4f5e9abb1137bd0
+  metadata.gz: cba6fda111af891eaad41c400060d7b9f613ac7e3b2d0a3c685a708294986e79f6617b71d6542598fc0c20a79ab7c82907acb1b614a010dfa851448c26f59879
+  data.tar.gz: 4ac42ca1a5a69e0856345eae7cb4cc8e7b06a15f69d48fe573db69e0616de3c4691ad2f8818a48300275a617185a76add5e8dbbb130640588dce3ca39c3bcedd

data/CHANGELOG.md

@@ -1,6 +1,72 @@
 ## [Unreleased]
 
-## [0.2.0] - 2025-01-24
+## [0.3.0] - 2026-11-07
+
+### Upgrading
+
+- **Run the upgrade migration before deploying:** `rails generate idempotency_lock:upgrade && rails db:migrate`
+  (adds the `owner_token` column).
+- Minimum supported ActiveRecord / ActiveSupport is now **7.1** (7.0 is end-of-life).
+- Invalid arguments now raise `ArgumentError` instead of being silently accepted
+  (see "Fixed" below).
+
+### Fixed
+
+- **A process could release a lock it no longer held.** If a lock's TTL lapsed
+  mid-block and another process claimed it, the original holder's release
+  (`temporarily`'s auto-release, or `once` with `:unlock` / `:raise` / a callable)
+  deleted the new holder's lock, allowing concurrent execution. Locks now carry
+  a random owner token and releases only delete the caller's own lock.
+- Invalid lock names (`nil`, blank, non-String/Symbol, or over 255 characters)
+  were reported as `skipped?` without running the block. They now raise
+  `ArgumentError`.
+- An unknown `on_error` value (e.g. a typo like `:unlok`) silently kept the lock.
+  It now raises `ArgumentError`. Invalid `ttl:` and `wait:` values also raise.
+- Non-`StandardError` exceptions (`Interrupt`, `SignalException`,
+  `Sidekiq::Shutdown`, ...) bypassed `on_error`, leaving the lock held even with
+  `:unlock`. The lock is now released for every strategy except `:keep`.
+- A lock conflict that reached the database (two callers racing on a new name)
+  inside a caller's transaction aborted that transaction on PostgreSQL
+  (`PG::InFailedSqlTransaction`). Acquisition now runs in a savepoint.
+- `IdempotencyLock.logger = nil` was ignored in Rails apps (it fell back to
+  `Rails.logger`), and the lookup crashed when `Rails` was defined without a
+  `logger` method.
+- Fractional `ttl:` values were truncated to whole seconds.
+
+### Changed
+
+- Requiring the gem no longer loads `ActiveRecord::Base` eagerly; the model is
+  autoloaded on first use, so host-app ActiveRecord configuration is respected.
+  The gem now requires `active_record` / `active_support` itself.
+- Expired-lock claims use the owner token (instead of `updated_at`) as the
+  optimistic-lock version, avoiding timestamp-precision edge cases.
+- `Lock.acquire` returns the owner token (or `nil`) instead of `true`/`false`;
+  `Lock.release` accepts an optional `owner_token:`. Truthiness is unchanged.
+- Dropped the `uniqueness` validation on `Lock#name`; the unique index already
+  enforces it, saving a `SELECT` per acquisition.
+- `Result#inspect` shows the class of the value rather than its contents, to
+  avoid leaking sensitive data into logs and error trackers.
+- `temporarily` wait loop uses a monotonic clock.
+- The Railtie no longer overwrites a configured logger.
+
+### Added
+
+- `on_error:` for `temporarily` (`:raise` or a callable).
+- `rails generate idempotency_lock:upgrade` generator.
+- `on_error:` accepts any object responding to `call`, not only Procs.
+- RBS signatures for the public API.
+- CI: Ruby 3.2–3.4 × ActiveRecord 7.1–8.1, plus PostgreSQL and MySQL jobs;
+  read-only token permissions and SHA-pinned actions.
+
+### Documentation
+
+- Clarified that `once` is *at most once*, not exactly once, and documented
+  error-swallowing, interrupt, transaction, and clock-skew behavior.
+- Fixed the Sidekiq example (it used `:unlock`, which swallows the error so
+  Sidekiq never retries) and the webhook example (now verifies the signature
+  before taking a lock). Added a Security Considerations section.
+
+## [0.2.0] - 2026-01-24
 
 ### Added
 

data/README.md

@@ -1,6 +1,6 @@
 # IdempotencyLock
 
-A simple, robust idempotency solution for Ruby on Rails applications. Ensures operations run exactly once using database-backed locks with support for TTL expiration, multiple error handling strategies, and clean return value handling.
+A simple, robust idempotency solution for Ruby on Rails applications. Guarantees an operation runs **at most once** per lock name (or once per TTL window) across processes and machines, using database-backed locks with support for TTL expiration, multiple error handling strategies, and clean return value handling.
 
 ## Installation
 
@@ -23,6 +23,17 @@ rails generate idempotency_lock:install
 rails db:migrate
 ```
 
+Requires Ruby 3.2+ and Rails / ActiveRecord 7.1+. Tested on SQLite, PostgreSQL, and MySQL.
+
+### Upgrading from 0.2.x or earlier
+
+Version 0.3.0 adds an `owner_token` column. Generate and run the upgrade migration **before** deploying 0.3.0:
+
+```bash
+rails generate idempotency_lock:upgrade
+rails db:migrate
+```
+
 ## Usage
 
 ### Basic Usage
@@ -52,6 +63,15 @@ result.value      # the return value of the block
 result.error      # the exception if one was raised
 ```
 
+### At-most-once semantics
+
+The lock is taken **before** the block runs. That makes `once` *at most once*, not *exactly once*:
+
+- If the block raises, `on_error` decides whether the lock is kept (no retry) or released (retry allowed). See [Error Handling](#error-handling).
+- If the process dies mid-block (crash, `kill -9`, OOM), the lock stays in place and the operation will not run again until the lock expires (`ttl:`) or is released manually. Use a `ttl:` if you would rather risk a second run than never finishing.
+
+Lock names must be non-blank Strings or Symbols of at most 255 characters; anything else raises `ArgumentError`.
+
 ### TTL / Expiration
 
 Sometimes you want "run once per hour" instead of "run once forever":
@@ -67,19 +87,20 @@ IdempotencyLock.once("hourly-cleanup", ttl: 1.hour) do
   TempFile.cleanup_old
 end
 
-# TTL also accepts integer seconds
+# TTL also accepts seconds
 IdempotencyLock.once("periodic-task", ttl: 3600) do
   some_periodic_work
 end
 ```
 
+Expiry is checked against the clock of the server doing the check, so keep server clocks synchronized (NTP). Clock skew can shorten or lengthen a TTL window: a server whose clock runs ahead can see a lock as expired, and take it over, while the previous holder is still running. Pick TTLs with a margin well above your expected clock drift. (When several callers race to claim the *same* expired lock, the owner-token check still guarantees only one succeeds.)
+
 ### 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):
+Use `temporarily` when you want exclusive execution but don't need permanent idempotency. The lock is released when the block finishes, whether it succeeds, raises, or exits early:
 
 ```ruby
-# Lock is held only while the block runs
-IdempotencyLock.temporarily("process-payment-#{payment.id}") do
+IdempotencyLock.temporarily("process-payment-#{payment.id}", ttl: 5.minutes) do
   PaymentProcessor.charge(payment)
 end
 # Lock is now released - another call can acquire it
@@ -90,13 +111,19 @@ This is useful for:
 - Mutex-style synchronization across processes/servers
 - Operations that should be exclusive but retriable
 
+#### Always set a TTL
+
+> **Without `ttl:`, a lock held by a process that is killed (SIGKILL, OOM, host failure) is never released**, and every later call is skipped until you run `IdempotencyLock.release(name)`.
+
+Set `ttl:` comfortably longer than the block's worst-case runtime. If the block outlives its TTL, another process may acquire the lock and run concurrently. The original holder will not release the new holder's lock when it finishes.
+
 #### 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
+result = IdempotencyLock.temporarily("exclusive-job", ttl: 10.minutes, wait: 5.seconds) do
   process_job
 end
 
@@ -105,56 +132,86 @@ if result.skipped?
 end
 ```
 
-#### TTL for Crash Protection
+#### Errors in temporary locks
 
-Combine with `ttl:` to ensure locks are released even if the process crashes:
+By default an exception raised in the block is captured in the `Result` (`result.error?`) and **not re-raised**. Pass `on_error: :raise` to re-raise it after the lock is released, or a callable to be notified:
 
 ```ruby
-IdempotencyLock.temporarily("long-job", ttl: 10.minutes, wait: 30.seconds) do
-  # If process crashes, lock expires after 10 minutes
-  long_running_task
+IdempotencyLock.temporarily("sync-account-#{id}", ttl: 1.minute, on_error: :raise) do
+  AccountSync.run(id)
 end
 ```
 
 ### Error Handling
 
-Control what happens when an error occurs inside the block:
+Control what happens when the block raises a `StandardError`:
 
 ```ruby
-# :keep (default) - Keep the lock, don't allow retry
+# :keep (default) - Keep the lock: the operation will NOT be retried
 IdempotencyLock.once("risky-op", on_error: :keep) do
   might_fail
 end
 
-# :unlock - Release the lock so another process can retry
+# :unlock - Release the lock so a later call can retry
 IdempotencyLock.once("retriable-op", on_error: :unlock) do
   external_api_call
 end
 
-# :raise - Re-raise the exception after releasing the lock
+# :raise - Release the lock, then re-raise the exception
 IdempotencyLock.once("critical-op", on_error: :raise) do
   must_succeed_or_alert
 end
 
-# Custom handler with a Proc
+# Any callable - Release the lock, then call it with the exception
 IdempotencyLock.once("custom-error", on_error: ->(e) { Bugsnag.notify(e) }) do
   something_important
 end
 ```
 
+Things to know:
+
+- **Errors are swallowed unless you use `:raise`.** With `:keep`, `:unlock`, or a callable, `once` returns a `Result` with `error?` set and does not raise. In a background job, that means the job framework sees success and **will not retry**. Use `on_error: :raise` when you rely on job retries.
+- **The default (`:keep`) means a transient failure permanently suppresses the operation** (or until the TTL expires). Choose `:unlock` / `:raise` if retrying is safe.
+- **Interrupts and other non-`StandardError` exceptions** (e.g. `Interrupt`, `SignalException`, `Sidekiq::Shutdown` during a deploy) are always re-raised. The lock is kept for `:keep` and released for every other strategy; callables are not invoked for them.
+- **An early `return`/`break`/`next` out of the block counts as success.** The lock is kept.
+- An unknown `on_error` value raises `ArgumentError` before anything runs.
+
+### Database Transactions
+
+The lock row is written through the current database connection, so if you call `once` inside a transaction:
+
+- The lock is not visible to other processes until your transaction commits. A concurrent caller blocks on the unique index until then, then skips.
+- **If your transaction rolls back, the lock is rolled back too**, even though any side effects (emails sent, APIs called) already happened. Prefer to call `once` outside transactions, or wrap only database work that should roll back together with the lock.
+
+Acquisition uses a savepoint, so a lock conflict never aborts your surrounding transaction (relevant on PostgreSQL).
+
 ### Manual Lock Management
 
 ```ruby
 # Check if an operation is locked
 IdempotencyLock.locked?("my-operation")  # => true/false
 
-# Release a lock manually (useful for testing or manual intervention)
+# Force-release a lock regardless of who holds it
+# (useful for testing or manual intervention)
 IdempotencyLock.release("my-operation")
 
 # Clean up all expired locks (good for a periodic job)
 IdempotencyLock.cleanup_expired
 ```
 
+Locks without a TTL are never removed by `cleanup_expired`.
+
+### Logging
+
+Logs go to `Rails.logger` by default. To use a different logger, or disable logging:
+
+```ruby
+IdempotencyLock.logger = Logger.new($stdout)
+IdempotencyLock.logger = nil # disable
+```
+
+Lock names and exception messages are logged, so avoid putting secrets or personal data in lock names.
+
 ### Alias
 
 The `wrap` method is available as an alias for `once`:
@@ -167,16 +224,26 @@ IdempotencyLock.wrap("operation-name") { do_something }
 
 ### Preventing Duplicate Webhook Processing
 
+Verify the webhook signature **before** taking a lock. Otherwise anyone can send forged requests that claim lock names (and grow the table) for events that never happened.
+
 ```ruby
 class WebhooksController < ApplicationController
   def stripe
-    event_id = params[:id]
-    
-    result = IdempotencyLock.once("stripe-webhook-#{event_id}") do
-      StripeWebhookProcessor.process(params)
+    event = Stripe::Webhook.construct_event(
+      request.body.read,
+      request.headers["Stripe-Signature"],
+      Rails.application.credentials.stripe_webhook_secret
+    )
+
+    # Namespace the key; expire it after Stripe's retry window.
+    # on_error: :raise releases the lock and returns a 500, so Stripe retries.
+    IdempotencyLock.once("stripe-webhook:#{event.id}", ttl: 7.days, on_error: :raise) do
+      StripeWebhookProcessor.process(event)
     end
-    
+
     head :ok
+  rescue JSON::ParserError, Stripe::SignatureVerificationError
+    head :bad_request
   end
 end
 ```
@@ -207,8 +274,9 @@ class ImportantJob
   include Sidekiq::Job
 
   def perform(record_id)
-    IdempotencyLock.once("important-job-#{record_id}", on_error: :unlock) do
-      # If this fails, another job can retry
+    # :raise releases the lock and re-raises, so Sidekiq's retry runs it again.
+    # (With :unlock the error would be swallowed and Sidekiq would never retry.)
+    IdempotencyLock.once("important-job-#{record_id}", on_error: :raise) do
       ImportantService.process(record_id)
     end
   end
@@ -220,12 +288,18 @@ end
 ```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
+  IdempotencyLock.temporarily("payment-#{payment_id}", ttl: 5.minutes, wait: 10.seconds) do
     Payment.find(payment_id).process!
   end
 end
 ```
 
+## Security Considerations
+
+- **Lock names derived from user input:** if an attacker can choose lock names, they can claim names in advance to block legitimate operations, or create rows without limit. Authenticate/verify input first (e.g. webhook signatures), namespace names (`"stripe-webhook:#{id}"`), and use a `ttl:` plus a periodic `cleanup_expired` so the table stays bounded.
+- **`Result#inspect`** shows only the class of the block's return value, not its contents, so inspecting a result in logs or error trackers does not leak data. `result.value` still holds the real value.
+- All queries use bound parameters.
+
 ## Database Schema
 
 The gem creates an `idempotency_locks` table with:
@@ -233,8 +307,9 @@ The gem creates an `idempotency_locks` table with:
 | Column | Type | Description |
 |--------|------|-------------|
 | `name` | string (max 255) | Unique identifier for the lock |
+| `owner_token` | string (36) | Random token identifying the current holder |
 | `expires_at` | datetime | When the lock expires (null = never) |
-| `executed_at` | datetime | When the operation was executed |
+| `executed_at` | datetime | When the lock was acquired (i.e. when the block started) |
 | `created_at` | datetime | Standard Rails timestamp |
 | `updated_at` | datetime | Standard Rails timestamp |
 
@@ -242,30 +317,49 @@ Indexes:
 - Unique index on `name` (provides atomicity)
 - Index on `expires_at` (partial index on PostgreSQL/SQLite, regular index on MySQL)
 
-**Note on name length:** Lock names are limited to 255 characters to ensure compatibility with database unique index limits. MySQL users with `utf8mb4` encoding may need to reduce this to 191 characters by modifying the migration before running it.
+**Note on name length:** modern MySQL (InnoDB with the default DYNAMIC row format) can index 255 `utf8mb4` characters. Very old MySQL setups limited to 767-byte index keys need the column reduced to 191 characters in the migration. If you do that, keep your lock names within that length too.
 
 ## How It Works
 
-1. **Lock Acquisition**: Attempts to create a record with the given name. The unique index ensures only one process succeeds.
+1. **Lock Acquisition**: Inserts a row with the given name and a fresh random owner token. The unique index ensures only one process succeeds. The insert runs in a savepoint so a conflict never breaks a surrounding transaction.
 
-2. **TTL Support**: If a TTL is provided, the lock includes an `expires_at` timestamp. Expired locks can be claimed by new operations via an atomic UPDATE.
+2. **TTL Support**: If a TTL is provided, the lock includes an `expires_at` timestamp. An expired lock is claimed with a conditional `UPDATE ... WHERE owner_token = <observed token>`, so if several processes race to claim the same expired lock, exactly one wins. Whether a lock counts as expired depends on the claiming server's clock (see [TTL / Expiration](#ttl--expiration)).
 
-3. **Error Handling**: Different strategies control whether the lock is released on error, allowing for retry semantics.
+3. **Owner-Safe Release**: Releases delete the row only if it still carries the releasing process's owner token. A process whose lock expired and was taken over cannot delete the new holder's lock.
 
-4. **Return Values**: The block's return value is captured and returned in the `Result` object.
+4. **Error Handling**: Strategies control whether the lock is released on error, allowing for retry semantics.
 
-## Thread Safety
+5. **Return Values**: The block's return value is captured and returned in the `Result` object.
+
+## Concurrency
 
 The gem relies on database-level uniqueness constraints for atomicity. This means:
 
-- ✅ Safe across multiple processes (web servers, job workers)
-- ✅ Safe across multiple machines
-- ✅ Safe in multi-threaded environments
+- ✅ Safe across multiple processes (web servers, job workers) and machines
+- ✅ Safe across threads (each thread uses its own database connection)
 - ✅ Survives application restarts
+- ⚠️ Mutual exclusion from `temporarily` holds only while the TTL has not expired (as judged by each server's clock), so pick a TTL longer than the block's runtime plus expected clock drift
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+After checking out the repo, run `bin/setup` to install dependencies. Then run `rake` to run the tests and RuboCop.
+
+The suite uses SQLite by default. To run it against PostgreSQL or MySQL:
+
+```bash
+BUNDLE_WITH=postgres bundle install
+BUNDLE_WITH=postgres DATABASE_URL=postgres://user:pass@localhost/idempotency_lock_test bundle exec rake test
+
+BUNDLE_WITH=mysql bundle install
+BUNDLE_WITH=mysql DATABASE_URL=mysql2://user:pass@127.0.0.1/idempotency_lock_test bundle exec rake test
+```
+
+To test a specific ActiveRecord version, use the gemfiles in `gemfiles/`:
+
+```bash
+BUNDLE_GEMFILE=gemfiles/activerecord_7.1.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/activerecord_7.1.gemfile bundle exec rake test
+```
 
 ## Contributing
 

data/lib/generators/idempotency_lock/install_generator.rb

@@ -1,16 +1,13 @@
 # frozen_string_literal: true
 
-require "rails/generators"
-require "rails/generators/active_record"
+require_relative "migration_generator_helpers"
 
 module IdempotencyLock
   module Generators
     # Generator to create the idempotency_locks table migration.
     # Run with: rails generate idempotency_lock:install
     class InstallGenerator < Rails::Generators::Base
-      include ActiveRecord::Generators::Migration
-
-      source_root File.expand_path("templates", __dir__)
+      include MigrationGeneratorHelpers
 
       desc "Creates the idempotency_locks table migration"
 
@@ -20,10 +17,6 @@ module IdempotencyLock
           "db/migrate/create_idempotency_locks.rb"
         )
       end
-
-      def migration_version
-        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
-      end
     end
   end
 end

data/lib/generators/idempotency_lock/migration_generator_helpers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module IdempotencyLock
+  module Generators
+    # Shared setup for the gem's migration generators.
+    module MigrationGeneratorHelpers
+      def self.included(base)
+        base.include ActiveRecord::Generators::Migration
+        base.source_root File.expand_path("templates", __dir__)
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/idempotency_lock/templates/add_owner_token_to_idempotency_locks.rb.erb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddOwnerTokenToIdempotencyLocks < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Random token identifying the current lock holder, so a process can only
+    # release a lock it still owns. Required by idempotency_lock >= 0.3.0.
+    add_column :idempotency_locks, :owner_token, :string, limit: 36
+  end
+end

data/lib/generators/idempotency_lock/templates/create_idempotency_locks.rb.erb

@@ -3,10 +3,15 @@
 class CreateIdempotencyLocks < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :idempotency_locks do |t|
-      # Limit ensures compatibility with unique index on most databases.
-      # MySQL with utf8mb4 supports max 191 chars; adjust if needed.
+      # Must match IdempotencyLock::MAX_NAME_LENGTH (255). Modern MySQL
+      # (InnoDB, DYNAMIC row format) can index 255 utf8mb4 characters; very old
+      # MySQL setups limited to 767-byte index keys need 191 here instead.
       t.string :name, null: false, limit: 255
+      # Random token identifying the current lock holder, so a process can only
+      # release a lock it still owns.
+      t.string :owner_token, limit: 36
       t.datetime :expires_at
+      # When the lock was acquired (i.e. when the block started running).
       t.datetime :executed_at
 
       t.timestamps
@@ -16,11 +21,10 @@ class CreateIdempotencyLocks < ActiveRecord::Migration<%= migration_version %>
 
     # Partial indexes are more efficient but not supported by MySQL.
     # Use a regular index for MySQL, partial index for PostgreSQL/SQLite.
-    if ActiveRecord::Base.connection.adapter_name.downcase.include?("mysql")
+    if connection.adapter_name.downcase.include?("mysql")
       add_index :idempotency_locks, :expires_at
     else
       add_index :idempotency_locks, :expires_at, where: "expires_at IS NOT NULL"
     end
   end
 end
-

data/lib/generators/idempotency_lock/upgrade_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "migration_generator_helpers"
+
+module IdempotencyLock
+  module Generators
+    # Generator for existing installs upgrading to 0.3.0+: adds the
+    # owner_token column used to make lock release owner-safe.
+    # Run with: rails generate idempotency_lock:upgrade
+    class UpgradeGenerator < Rails::Generators::Base
+      include MigrationGeneratorHelpers
+
+      desc "Adds the owner_token column required by idempotency_lock >= 0.3.0"
+
+      def create_migration_file
+        migration_template(
+          "add_owner_token_to_idempotency_locks.rb.erb",
+          "db/migrate/add_owner_token_to_idempotency_locks.rb"
+        )
+      end
+    end
+  end
+end

data/lib/idempotency_lock/arguments.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module IdempotencyLock
+  # Validation for the public API's arguments. Invalid input raises
+  # ArgumentError up front instead of being mistaken for "lock already held".
+  # @api private
+  module Arguments
+    module_function
+
+    # @return [String] the name as a String
+    def normalize_name!(name)
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise ArgumentError, "Lock name must be a String or Symbol, got #{name.class}"
+      end
+
+      name = name.to_s
+      # blank? (not strip.empty?) so Unicode whitespace such as U+00A0 is
+      # rejected here, matching the model's presence validation.
+      raise ArgumentError, "Lock name must not be blank" if name.blank?
+      if name.length > MAX_NAME_LENGTH
+        raise ArgumentError, "Lock name is too long (#{name.length} > #{MAX_NAME_LENGTH} characters)"
+      end
+
+      name
+    end
+
+    # ActiveSupport::Duration reports is_a?(Numeric) as true, so this accepts
+    # both plain seconds and durations like 5.minutes. NaN and Infinity are
+    # rejected: they can't be added to a Time.
+    def validate_ttl!(ttl)
+      return if ttl.nil? || (finite_number?(ttl) && ttl.positive?)
+
+      raise ArgumentError, "ttl must be a positive number of seconds or a Duration, got #{ttl.inspect}"
+    end
+
+    # @return [Float, nil] the wait in seconds
+    # NaN and Infinity are rejected: NaN would silently skip without waiting,
+    # and Infinity would poll forever.
+    def normalize_wait!(wait)
+      return nil if wait.nil?
+      return wait.to_f if finite_number?(wait) && !wait.negative?
+
+      raise ArgumentError, "wait must be a non-negative number of seconds or a Duration, got #{wait.inspect}"
+    end
+
+    def finite_number?(value)
+      value.is_a?(Numeric) && value.to_f.finite?
+    end
+
+    def validate_on_error!(on_error, strategies)
+      return if strategies.include?(on_error) || on_error.respond_to?(:call)
+
+      allowed = strategies.map(&:inspect).join(", ")
+      raise ArgumentError, "on_error must be one of #{allowed} or a callable, got #{on_error.inspect}"
+    end
+  end
+end

data/lib/idempotency_lock/lock.rb

@@ -1,26 +1,31 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module IdempotencyLock
   # ActiveRecord model for storing idempotency locks.
   #
   # This model expects a database table with the following schema:
   #   - name: string (unique, indexed, max 255 chars)
+  #   - owner_token: string (random token identifying the current holder)
   #   - expires_at: datetime (nullable, indexed)
-  #   - executed_at: datetime
+  #   - executed_at: datetime (when the lock was acquired / the block started)
   #   - created_at: datetime
   #   - updated_at: datetime
   #
-  # Use the provided generator to create the migration:
-  #   rails generate idempotency_lock:install
+  # Use the provided generators to create the migration:
+  #   rails generate idempotency_lock:install   # new installs
+  #   rails generate idempotency_lock:upgrade   # upgrading from < 0.3.0
   #
   class Lock < ActiveRecord::Base
     self.table_name = "idempotency_locks"
 
-    # Maximum length for lock names. Ensures compatibility with database
-    # unique index limits (MySQL utf8mb4 = 191, most others = 255+).
-    MAX_NAME_LENGTH = 255
+    MAX_NAME_LENGTH = IdempotencyLock::MAX_NAME_LENGTH
 
-    validates :name, presence: true, uniqueness: true, length: { maximum: MAX_NAME_LENGTH }
+    # Uniqueness is enforced by the unique index on `name`, not by a
+    # validation, so acquiring a lock is a single INSERT rather than a
+    # SELECT followed by an INSERT.
+    validates :name, presence: true, length: { maximum: MAX_NAME_LENGTH }
 
     # Check if this lock has expired
     # @return [Boolean]
@@ -36,62 +41,79 @@ module IdempotencyLock
 
     class << self
       # Attempt to acquire a lock for the given name.
-      # Returns true if the lock was acquired, false otherwise.
       #
       # @param name [String] unique identifier for the operation
       # @param expires_at [Time, nil] when the lock should expire (nil = never)
       # @param now [Time] current time reference (injectable for testing)
-      # @return [Boolean] true if lock was acquired
+      # @return [String, nil] an owner token if the lock was acquired, nil otherwise.
+      #   Pass the token to {release} so only the holder can release the lock.
       def acquire(name, expires_at: nil, now: Time.current)
-        # Try to insert first (most common case for new keys)
-        begin
-          create!(name: name, expires_at: expires_at, executed_at: now)
-          return true
-        rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid
-          # Lock exists, check if it's expired
-        end
+        token = SecureRandom.uuid
+        return token if insert_lock(name, token, expires_at, now)
 
-        # Check if an existing lock is expired and can be claimed
-        existing = find_by(name: name)
-        return false if existing.nil?
-        return false unless existing.expired?(now: now)
-
-        # 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.
-        # 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?
+        claim_expired(name, token, expires_at, now) ? token : nil
       end
 
-      # Release a lock by name (removes the record entirely)
+      # Release a lock by name.
+      #
+      # When `owner_token` is given, the lock is only removed if it is still
+      # held by that owner. This prevents a holder whose lock expired (and was
+      # claimed by someone else) from deleting the new holder's lock.
       #
       # @param name [String] unique identifier for the operation
+      # @param owner_token [String, nil] token returned by {acquire}; nil forces release
       # @return [Boolean] true if a lock was removed
-      def release(name)
-        deleted = where(name: name).delete_all
-        deleted.positive?
+      def release(name, owner_token: nil)
+        scope = where(name: name)
+        scope = scope.where(owner_token: owner_token) if owner_token
+        scope.delete_all.positive?
       end
 
       # Check if a valid (non-expired) lock exists for the given name
       #
       # @param name [String] unique identifier for the operation
       # @return [Boolean]
-      def locked?(name)
+      def locked?(name, now: Time.current)
         lock = find_by(name: name)
         return false if lock.nil?
 
-        lock.valid_lock?
+        lock.valid_lock?(now: now)
       end
 
       # Clean up expired locks
       #
       # @return [Integer] number of locks removed
-      def cleanup_expired
-        where("expires_at IS NOT NULL AND expires_at < ?", Time.current).delete_all
+      def cleanup_expired(now: Time.current)
+        where("expires_at IS NOT NULL AND expires_at < ?", now).delete_all
+      end
+
+      private
+
+      # Insert a new lock row. Runs inside a savepoint so that a unique
+      # violation does not abort an enclosing transaction (PostgreSQL marks the
+      # whole transaction as failed after any error otherwise).
+      def insert_lock(name, token, expires_at, now)
+        transaction(requires_new: true) do
+          create!(name: name, owner_token: token, expires_at: expires_at, executed_at: now)
+        end
+        true
+      rescue ActiveRecord::RecordNotUnique
+        false
+      end
+
+      # Claim an existing lock if it has expired.
+      #
+      # Uses the observed owner_token as an optimistic-lock version: if two
+      # processes both see the same expired lock, only one UPDATE matches and
+      # the other affects 0 rows. Every acquisition writes a fresh random
+      # token, so the version always changes (no timestamp precision issues).
+      def claim_expired(name, token, expires_at, now)
+        existing = find_by(name: name)
+        return false if existing.nil? || !existing.expired?(now: now)
+
+        where(name: name, owner_token: existing.owner_token)
+          .update_all(owner_token: token, expires_at: expires_at, executed_at: now, updated_at: now)
+          .positive?
       end
     end
   end

data/lib/idempotency_lock/railtie.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module IdempotencyLock
-  # Rails integration for IdempotencyLock.
-  # Automatically configures the logger and loads generators.
+  # Rails integration for IdempotencyLock: registers the generators.
+  #
+  # Logging defaults to Rails.logger (see IdempotencyLock.logger), so no
+  # initializer is needed and an explicitly configured logger, including nil,
+  # is never overwritten.
   class Railtie < Rails::Railtie
     generators do
       require_relative "../generators/idempotency_lock/install_generator"
-    end
-
-    initializer "idempotency_lock.configure" do
-      IdempotencyLock.logger = Rails.logger
+      require_relative "../generators/idempotency_lock/upgrade_generator"
     end
   end
 end

data/lib/idempotency_lock/result.rb

@@ -41,11 +41,15 @@ module IdempotencyLock
       @executed && !error?
     end
 
-    # @return [String] human-readable representation for debugging
+    # Human-readable representation for debugging. Shows only the class of the
+    # value, not its contents, so inspecting a Result (in logs or error
+    # trackers) does not leak sensitive return values.
+    #
+    # @return [String]
     def inspect
       parts = ["executed=#{@executed}"]
       parts << "skipped=#{@skipped}" if @skipped
-      parts << "value=#{@value.inspect}" if @value
+      parts << "value=#{@value.class}" unless @value.nil?
       parts << "error=#{@error.class}" if @error
       "#<IdempotencyLock::Result #{parts.join(" ")}>"
     end

data/lib/idempotency_lock/version.rb

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

data/lib/idempotency_lock.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
+require "active_record"
+require "active_support/time"
+
 require_relative "idempotency_lock/version"
 require_relative "idempotency_lock/result"
-require_relative "idempotency_lock/lock"
+require_relative "idempotency_lock/arguments"
 
 # Database-backed idempotency locks for Ruby on Rails.
 #
-# Ensures operations run exactly once using database-backed locks with support
-# for TTL expiration, multiple error handling strategies, and clean return
-# value handling.
+# Guarantees an operation runs *at most once* per lock name (or once per TTL
+# window) across processes and machines, using a unique database index for
+# atomicity. Supports TTL expiration, multiple error handling strategies, and
+# clean return value handling.
 #
 # @example Basic usage
 #   result = IdempotencyLock.once("send-welcome-email-user-123") do
@@ -22,89 +26,108 @@ require_relative "idempotency_lock/lock"
 module IdempotencyLock
   class Error < StandardError; end
 
-  # Error handling strategies
+  # Error handling strategies for `once`
   ON_ERROR_UNLOCK = :unlock       # Remove lock so operation can be retried
   ON_ERROR_KEEP_LOCKED = :keep    # Keep lock in place (default)
-  ON_ERROR_RAISE = :raise         # Re-raise after cleanup/logging
+  ON_ERROR_RAISE = :raise         # Release lock, then re-raise
+  ON_ERROR_STRATEGIES = [ON_ERROR_KEEP_LOCKED, ON_ERROR_UNLOCK, ON_ERROR_RAISE].freeze
+
+  # Error handling strategies for `temporarily` (the lock is always released)
+  TEMPORARY_ON_ERROR_STRATEGIES = [nil, ON_ERROR_RAISE].freeze
+
+  # Maximum length for lock names. Matches the column limit in the generated
+  # migration and stays within unique index limits on common databases.
+  MAX_NAME_LENGTH = 255
 
-  # Wait retry interval for temporarily with wait option
-  WAIT_RETRY_INTERVAL = 0.1 # 100ms between retry attempts
+  # Interval between attempts when `temporarily` is called with `wait:`
+  WAIT_RETRY_INTERVAL = 0.1 # 100ms
+
+  # Loaded on first use so that requiring the gem does not force
+  # ActiveRecord::Base to load before the host application is configured.
+  autoload :Lock, File.expand_path("idempotency_lock/lock", __dir__)
 
   class << self
-    # Execute a block exactly once for the given operation name.
+    # Execute a block at most once for the given operation name.
+    #
+    # The lock is taken *before* the block runs. If the block raises, `on_error`
+    # decides whether the lock is kept (no retry) or released (retry allowed).
     #
-    # @param name [String] unique identifier for this operation
-    # @param ttl [ActiveSupport::Duration, Integer, nil] time-to-live for the lock
-    # @param on_error [Symbol, Proc] error handling strategy (:keep, :unlock, :raise, or Proc)
-    # @yield The block to execute (exactly once per lock name)
+    # @param name [String, Symbol] unique identifier for this operation
+    # @param ttl [ActiveSupport::Duration, Numeric, nil] time-to-live for the lock
+    # @param on_error [Symbol, #call] :keep (default), :unlock, :raise, or a callable
+    # @yield The block to execute (at most once per lock name / TTL window)
     # @return [Result] containing execution status and return value
-    def once(name, ttl: nil, on_error: ON_ERROR_KEEP_LOCKED, &)
-      raise ArgumentError, "Block required" unless block_given?
+    # @raise [ArgumentError] for a missing block, invalid name, ttl, or on_error
+    def once(name, ttl: nil, on_error: ON_ERROR_KEEP_LOCKED, &block)
+      raise ArgumentError, "Block required" unless block
 
-      now = Time.current
-      expires_at = calculate_expires_at(ttl, now)
-      acquired = Lock.acquire(name, expires_at: expires_at, now: now)
+      name = Arguments.normalize_name!(name)
+      Arguments.validate_ttl!(ttl)
+      Arguments.validate_on_error!(on_error, ON_ERROR_STRATEGIES)
 
-      unless acquired
+      token = acquire_lock(name, ttl)
+      unless token
         log_debug("Lock already exists for '#{name}', skipping execution")
         return Result.new(executed: false, skipped: true)
       end
 
       log_debug("Lock acquired for '#{name}', executing block")
-      execute_with_lock(name, on_error, &)
+      run_once(name, token, on_error, &block)
     end
 
     # 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).
+    # Execute a block while holding a lock that is always released when the
+    # block finishes (success, error, or non-local exit).
+    #
+    # Unlike `once`, this is mutex-style exclusion, not idempotency.
     #
-    # Unlike `once`, this method always releases the lock after execution,
-    # making it suitable for mutex-style synchronization rather than idempotency.
+    # Without a `ttl:`, a lock held by a process that is killed (e.g. SIGKILL,
+    # OOM, host failure) is never released. Pass a `ttl:` longer than the
+    # block's worst-case runtime for crash protection.
     #
-    # @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
+    # @param name [String, Symbol] unique identifier for this lock
+    # @param ttl [ActiveSupport::Duration, Numeric, nil] time-to-live for crash protection
+    # @param wait [ActiveSupport::Duration, Numeric, nil] how long to wait for the lock
+    # @param on_error [nil, Symbol, #call] nil (default) captures the error in the
+    #   Result; :raise re-raises it; a callable is invoked with it
     # @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?
+    # @raise [ArgumentError] for a missing block, invalid name, ttl, wait, or on_error
+    def temporarily(name, ttl: nil, wait: nil, on_error: nil, &block)
+      raise ArgumentError, "Block required" unless block
 
-      acquired = acquire_with_wait(name, ttl: ttl, wait: wait)
+      name = Arguments.normalize_name!(name)
+      Arguments.validate_ttl!(ttl)
+      Arguments.validate_on_error!(on_error, TEMPORARY_ON_ERROR_STRATEGIES)
+      wait_seconds = Arguments.normalize_wait!(wait)
 
-      unless acquired
+      token = acquire_with_wait(name, ttl, wait_seconds)
+      unless token
         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
+      run_temporarily(name, token, on_error, &block)
     end
 
-    # Release a lock manually (useful for testing or manual intervention)
+    # Force-release a lock regardless of who holds it (useful for testing or
+    # manual intervention).
     #
-    # @param name [String] the lock name to release
+    # @param name [String, Symbol] the lock name to release
     # @return [Boolean] true if a lock was released
     def release(name)
-      Lock.release(name)
+      Lock.release(Arguments.normalize_name!(name))
     end
 
     # Check if an operation is currently locked
     #
-    # @param name [String] the lock name to check
+    # @param name [String, Symbol] the lock name to check
     # @return [Boolean] true if locked and not expired
     def locked?(name)
-      Lock.locked?(name)
+      Lock.locked?(Arguments.normalize_name!(name))
     end
 
     # Clean up all expired locks
@@ -114,90 +137,100 @@ module IdempotencyLock
       Lock.cleanup_expired
     end
 
-    # Configure the logger (uses Rails.logger by default if available)
+    # Set the logger. Set to nil to disable logging.
     attr_writer :logger
 
+    # The configured logger, or Rails.logger if none has been set.
     def logger
-      @logger ||= defined?(Rails) ? Rails.logger : nil
+      return @logger if defined?(@logger)
+
+      Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
     end
 
     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
+    def run_once(name, token, on_error)
+      value = yield
+      Result.new(executed: true, value: value)
+    rescue StandardError => e
+      handle_error(name, token, e, on_error)
+    rescue Exception # rubocop:disable Lint/RescueException
+      # Interrupt, SignalException, Sidekiq::Shutdown, etc. The block did not
+      # finish, so apply the release policy before propagating.
+      release_after_abort(name, token, on_error)
+      raise
+    end
+
+    def run_temporarily(name, token, on_error)
+      begin
+        value = yield
+      rescue StandardError => e
+        error = e
+      ensure
+        Lock.release(name, owner_token: token)
+        log_debug("Temporary lock released for '#{name}'")
       end
+      return Result.new(executed: true, value: value) unless error
 
-      false
+      log_error("Exception in temporary lock block '#{name}': #{error.class} - #{error.message}")
+      raise error if on_error == ON_ERROR_RAISE
+
+      on_error&.call(error)
+      Result.new(executed: true, error: error)
     end
 
-    def calculate_expires_at(ttl, now)
-      return nil if ttl.nil?
+    def acquire_lock(name, ttl)
+      now = Time.current
+      Lock.acquire(name, expires_at: ttl && (now + ttl), now: now)
+    end
 
-      if ttl.respond_to?(:from_now)
-        # ActiveSupport::Duration
-        now + ttl
-      else
-        # Assume seconds
-        now + ttl.to_i
+    def acquire_with_wait(name, ttl, wait_seconds)
+      token = acquire_lock(name, ttl)
+      return token if token || wait_seconds.nil?
+
+      deadline = monotonic_now + wait_seconds
+      loop do
+        remaining = deadline - monotonic_now
+        return nil unless remaining.positive?
+
+        sleep([WAIT_RETRY_INTERVAL, remaining].min)
+        token = acquire_lock(name, ttl)
+        return token if token
       end
     end
 
-    def execute_with_lock(name, on_error)
-      value = yield
-      Result.new(executed: true, value: value)
-    rescue StandardError => e
-      handle_error(name, e, on_error)
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
-    def handle_error(name, exception, on_error)
+    def handle_error(name, token, exception, on_error)
       log_error("Exception in idempotent block '#{name}': #{exception.class} - #{exception.message}")
 
       case on_error
-      when :unlock then handle_unlock_error(name, exception)
-      when :raise then handle_raise_error(name, exception)
-      when :keep, ON_ERROR_KEEP_LOCKED then handle_keep_error(name, exception)
-      when Proc then handle_proc_error(name, exception, on_error)
-      else Result.new(executed: true, error: exception)
+      when ON_ERROR_KEEP_LOCKED
+        log_debug("Lock kept for '#{name}' despite error (on_error: :keep)")
+      when ON_ERROR_UNLOCK
+        release_owned(name, token, "due to error (on_error: :unlock)")
+      when ON_ERROR_RAISE
+        release_owned(name, token, "re-raising error (on_error: :raise)")
+        raise exception
+      else
+        release_owned(name, token, "calling error handler")
+        on_error.call(exception)
       end
-    end
 
-    def handle_unlock_error(name, exception)
-      Lock.release(name)
-      log_debug("Lock released for '#{name}' due to error (on_error: :unlock)")
       Result.new(executed: true, error: exception)
     end
 
-    def handle_raise_error(name, exception)
-      Lock.release(name)
-      log_debug("Lock released for '#{name}', re-raising error (on_error: :raise)")
-      raise exception
-    end
+    def release_after_abort(name, token, on_error)
+      return if on_error == ON_ERROR_KEEP_LOCKED
 
-    def handle_keep_error(name, exception)
-      log_debug("Lock kept for '#{name}' despite error (on_error: :keep)")
-      Result.new(executed: true, error: exception)
+      release_owned(name, token, "after the block was aborted")
     end
 
-    def handle_proc_error(name, exception, handler)
-      Lock.release(name)
-      handler.call(exception)
-      Result.new(executed: true, error: exception)
+    def release_owned(name, token, reason)
+      Lock.release(name, owner_token: token)
+      log_debug("Lock released for '#{name}' #{reason}")
     end
 
     def log_debug(message)

data/sig/idempotency_lock.rbs

@@ -1,4 +1,56 @@
 module IdempotencyLock
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+  end
+
+  ON_ERROR_UNLOCK: :unlock
+  ON_ERROR_KEEP_LOCKED: :keep
+  ON_ERROR_RAISE: :raise
+  ON_ERROR_STRATEGIES: Array[Symbol]
+  TEMPORARY_ON_ERROR_STRATEGIES: Array[Symbol?]
+  MAX_NAME_LENGTH: Integer
+  WAIT_RETRY_INTERVAL: Float
+
+  interface _ErrorHandler
+    def call: (StandardError) -> untyped
+  end
+
+  type lock_name = String | Symbol
+  type duration = Numeric
+  type on_error = :keep | :unlock | :raise | _ErrorHandler
+  type temporary_on_error = :raise | _ErrorHandler | nil
+
+  def self.once: [T] (lock_name name, ?ttl: duration?, ?on_error: on_error) { () -> T } -> Result[T]
+  def self.wrap: [T] (lock_name name, ?ttl: duration?, ?on_error: on_error) { () -> T } -> Result[T]
+  def self.temporarily: [T] (lock_name name, ?ttl: duration?, ?wait: duration?, ?on_error: temporary_on_error) { () -> T } -> Result[T]
+  def self.release: (lock_name name) -> bool
+  def self.locked?: (lock_name name) -> bool
+  def self.cleanup_expired: () -> Integer
+  def self.logger: () -> untyped
+  def self.logger=: (untyped logger) -> untyped
+
+  class Result[T]
+    attr_reader value: T?
+    attr_reader error: StandardError?
+
+    def initialize: (executed: bool, ?value: T?, ?skipped: bool, ?error: StandardError?) -> void
+    def executed?: () -> bool
+    def skipped?: () -> bool
+    def error?: () -> bool
+    def success?: () -> bool
+    def inspect: () -> String
+  end
+
+  class Lock
+    MAX_NAME_LENGTH: Integer
+
+    def self.acquire: (String name, ?expires_at: Time?, ?now: Time) -> String?
+    def self.release: (String name, ?owner_token: String?) -> bool
+    def self.locked?: (String name, ?now: Time) -> bool
+    def self.cleanup_expired: (?now: Time) -> Integer
+
+    def expired?: (?now: Time) -> bool
+    def valid_lock?: (?now: Time) -> bool
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idempotency_lock
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - John Nagro
@@ -15,32 +15,33 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 description: |
-  A simple, robust idempotency solution for Rails applications. Ensures operations
-  run exactly once using database-backed locks with support for TTL expiration,
-  multiple error handling strategies, and clean return value handling.
+  A simple, robust idempotency solution for Rails applications. Guarantees an
+  operation runs at most once per key (or per TTL window) across processes using
+  database-backed locks, with TTL expiration, owner-safe release, multiple error
+  handling strategies, and clean return value handling.
 email:
 - john@noreastergroup.com
 executables: []
@@ -53,8 +54,12 @@ files:
 - README.md
 - Rakefile
 - lib/generators/idempotency_lock/install_generator.rb
+- lib/generators/idempotency_lock/migration_generator_helpers.rb
+- lib/generators/idempotency_lock/templates/add_owner_token_to_idempotency_locks.rb.erb
 - lib/generators/idempotency_lock/templates/create_idempotency_locks.rb.erb
+- lib/generators/idempotency_lock/upgrade_generator.rb
 - lib/idempotency_lock.rb
+- lib/idempotency_lock/arguments.rb
 - lib/idempotency_lock/lock.rb
 - lib/idempotency_lock/railtie.rb
 - lib/idempotency_lock/result.rb