rails_soft_lock 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28c11572b431bdc87a2f4771c63b6aef7665f619761c84949d0265b73f2976d1
-  data.tar.gz: a81700f090a280d04f43d96dbac00603dc64fbd7912a7e22f69a76321792a57d
+  metadata.gz: 340ed740ba96e987fda3b66518a71a8693a3e1a99c5df1b9f0093acc89e5c36f
+  data.tar.gz: bdb1f86ad797cabf1468be9e9cf20bb1e89b7887ae420006b98fc436a2c0f51e
 SHA512:
-  metadata.gz: 824828fb615e0e17866a4ebf266f493f3283876e6e83fb485afdfde89beae8a748ba9ab6e7afec273344572385b0853b2707943fc4f64692961174a8baae6c4e
-  data.tar.gz: 1dcea30302c83b22c3782aeabf7307a3c931a7c6355b39f62726dd277630a472eb441200369426fa64a55dc04d124b65f18033a3a8524f24ebaf5ba5b65439e6
+  metadata.gz: b5741cf3a3aebd0219abeb477f855b63a58d86c25936efbcb2bb02efde3382af75f21523e516c303dbb0fe4033bcbea2f3c7f7dfc2ec1e2f2ad3099305272124
+  data.tar.gz: 10c6814dfa262802d16df2095cfa11c5cdbb55ecf66f8eec8bc26b1468e798fc68e89227d4acb4179deebfdb852863ba81091a920820661740005c6755db5e71

data/README.md

@@ -4,7 +4,7 @@
 
 The RailsSoftLock gem provides group-level locking for Rails ApplicationRecord objects based on a shared attribute. Instead of individually locking each database record (which can be expensive and complex), it creates and manages a single in-memory lock for the entire group via the attribute. This reduces database contention while maintaining thread safety.
 
-### Key Features
+## Key Features
 
     Lightweight Group Locking:
 
@@ -24,6 +24,16 @@ The RailsSoftLock gem provides group-level locking for Rails ApplicationRecord o
 
         Useful for batch operations or state management (e.g., "processing", "archived").
 
+    Lock Expiration (TTL) ⚠️ see "Lock TTL" section below — requires Redis >= 7.4:
+
+        Lock keys automatically expire after a configurable TTL, protecting against stuck/abandoned locks (e.g., a crashed process that never released one).
+
+        Default TTL is 12 hours (43200 seconds).
+
+        Configurable via the RAILS_SOFT_LOCK_TTL environment variable (in seconds), via config/redis.yml (ttl key), or per lock instance.
+
+        Set TTL to 0 to disable expiration entirely.
+
 ### Current Status
 
     Active Development: New features and optimizations in progress.
@@ -142,6 +152,36 @@ Key Points:
 
 In this case, the lock remains unchanged (no new lock is set).
 
+## Lock TTL
+
+**Attention!** This feature requires Redis/Valkey ~> 7.4 (uses `HEXPIRE`/`HTTL` under the hood, which set expiration on individual hash fields rather than the whole key).
+
+By default, lock records expire automatically after 12 hours, protecting against
+stuck/abandoned locks (e.g., a process crashing before releasing one). The TTL
+applies **per lock field**, not to the whole group key — other locks sharing the
+same group (`object_name`) are unaffected when one of them expires.
+
+Override the default globally via the `RAILS_SOFT_LOCK_TTL` environment variable
+(in seconds):
+
+```bash
+RAILS_SOFT_LOCK_TTL=3600 # 1 hour
+```
+
+or via `config/redis.yml`:
+
+```yaml
+default: &default
+  url: redis://localhost:6379/0
+  ttl: 3600
+```
+
+Set `RAILS_SOFT_LOCK_TTL=0` (or `ttl: 0` in `config/redis.yml`) to disable expiration
+entirely — locks will never expire automatically.
+
+If your Redis/Valkey server is older than 7.4, `HEXPIRE` will raise an error. Either
+upgrade the server, or set TTL to `0` to disable this feature until you do.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/rails_soft_lock/lock_object.rb

@@ -30,10 +30,11 @@ module RailsSoftLock
 
     attr_reader :object_name, :object_key, :object_value
 
-    def initialize(object_name:, object_key: nil, object_value: nil)
+    def initialize(object_name:, object_key: nil, object_value: nil, ttl: RailsSoftLock::RedisConfig.default_ttl)
       @object_name = object_name
       @object_key = object_key
       @object_value = object_value.presence&.to_s # Convert to string for consistency
+      @ttl = ttl
     end
 
     # Returns the ID of the locker who locked the object

data/lib/rails_soft_lock/redis_adapter.rb

@@ -25,16 +25,27 @@ module RailsSoftLock
 
     # Creates a new key-value pair if the key does not exist
     # @return [Boolean] true if the key was created, false if it already existed
+    # Note: field creation and TTL application are two separate Redis calls
+    # (not a single atomic operation). In the rare case a process crashes
+    # between them, the lock field would persist without a TTL. This is an
+    # accepted trade-off: TTL here is a best-effort cleanup convenience, not
+    # a strict consistency guarantee — a Redis restart/redeploy will clear
+    # stale locks regardless. If atomicity becomes a hard requirement, see
+    # HSETEX (Redis >= 8.0) or wrap creation+TTL in a Lua script (EVAL).
+
     def create
-      result = redis_client.multi do |transaction|
-        transaction.hsetnx(@object_name, @object_key, @object_value)
-        transaction.hget(@object_name, @object_key)
-      end
-      result.first # true on creation, false otherwise
+      created = create_field
+      apply_ttl if created
+      created # true on creation, false otherwise
     end
 
     # Updates the value for an existing key or creates a new key-value pair
     # @return [Boolean] true if the key was updated, false if it was created
+    # @note TTL is intentionally NOT (re)applied here. This method is currently
+    #   part of the adapter's generic interface but is not exposed through
+    #   LockObject's public API (see LockObject#lock_or_find/#unlock/#all_locks).
+    #   If it becomes user-facing, TTL handling should mirror #create — see the
+    #   TTL trade-off note there before wiring it in.
     def update # rubocop:disable Naming/PredicateMethod
       result = redis_client.hset(@object_name, @object_key, @object_value)
       result.zero?
@@ -52,5 +63,26 @@ module RailsSoftLock
     def all
       redis_client.hgetall(@object_name)
     end
+
+    private
+
+    def create_field
+      redis_client.multi do |transaction|
+        transaction.hsetnx(@object_name, @object_key, @object_value)
+        transaction.hget(@object_name, @object_key)
+      end.first
+    end
+
+    # Sets TTL on this specific hash field only, not on the whole group hash,
+    # since @object_name can hold multiple unrelated locks as separate fields
+    def apply_ttl
+      return unless @ttl.to_i.positive?
+
+      # HEXPIRE <key> <seconds> FIELDS <numfields> <field...>
+      # Sets TTL on a single hash field (not the whole hash key), so that
+      # unrelated locks sharing the same @object_name hash aren't affected.
+      # Requires Redis/Valkey >= 7.4.
+      redis_client.call("HEXPIRE", @object_name, @ttl.to_s, "FIELDS", "1", @object_key)
+    end
   end
 end

data/lib/rails_soft_lock/redis_config.rb

@@ -10,6 +10,10 @@ module RailsSoftLock
   module RedisConfig
     module_function
 
+    # Add possibility to set TTL for lock objects
+    # Set to 0 (via ENV or Rails config) to disable TTL entirely
+    DEFAULT_TTL = 43_200 # seconds, 12 hours
+
     # Returns the complete Redis adapter options hash
     # @return [Hash] Options hash with :redis key containing configuration
     # @example
@@ -25,12 +29,22 @@ module RailsSoftLock
       { url: "redis://localhost:6379/0", timeout: 5 }
     end
 
+    # TTL (in seconds) applied to lock keys as a safety net against stuck locks
+    # Priority: ENV var > Rails config/redis.yml (:ttl key) > DEFAULT_TTL
+    # A value of 0 means "no TTL" (locks never expire automatically)
+    # @return [Integer]
+    def default_ttl
+      rails_ttl = rails_available? ? rails_config[:ttl] : nil
+      Integer(ENV["RAILS_SOFT_LOCK_TTL"] || rails_ttl || DEFAULT_TTL)
+    end
+
     # Merges default settings with any Rails-specific configuration
     # @return [Hash] Complete Redis configuration
     # @note Will return just defaults if Rails isn't available
     def config_with_defaults
       base_config = rails_available? ? rails_config : {}
-      default_settings.merge(base_config)
+      # :ttl is a separate concept, not a Redis connection option, so exclude it here
+      default_settings.merge(base_config.except(:ttl))
     end
 
     # Checks if Rails environment is available and properly configured

data/lib/rails_soft_lock/version.rb

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

data/lib/tasks/rails_soft_lock.rake

@@ -11,31 +11,39 @@ namespace :rails_soft_lock do
       puts "RailsSoftLock configuration file already exists at #{initializer_path}"
     else
       File.write(initializer_path, <<~RUBY)
-              # frozen_string_literal: true
-
-              # Configuration for RailsSoftLock gem
-              # This file sets up the adapter and options for soft locking Active Record models
-
-              RailsSoftLock.configure do |config|
-                # Specify the adapter for storing locks
-                config.adapter = :redis
-
-        # configuration for the redis adapter
-        config.adapter_options = {
-          redis: Rails.application.config_for(:redis).merge(
-            timeout: 5
-          )
-        }
-
-                # (Optional) Attribute used for locking
-                # config.acts_as_locked_by = :lock_attribute
-
-                # (Optional) Scope for separating locks
-                # config.acts_as_locked_scope = -> { "default_scope" }
-
-                # (Optional) Model class for locked_by lookups
-                # config.locked_by_class = "User"
-              end
+        # frozen_string_literal: true
+
+        # Configuration for RailsSoftLock gem
+        # This file sets up the adapter and options for soft locking Active Record models
+
+        RailsSoftLock.configure do |config|
+          # Specify the adapter for storing locks
+          config.adapter = :redis
+
+          # Configuration for the redis adapter
+          # Note: :ttl is excluded here on purpose — it's not a Redis connection
+          # option and would break RedisClient.new if passed through. Lock TTL is
+          # configured separately, see the note below.
+          config.adapter_options = {
+            redis: Rails.application.config_for(:redis).to_h.except(:ttl).merge(
+              timeout: 5
+            )
+          }
+
+          # (Optional) Attribute used for locking
+          # config.acts_as_locked_by = :lock_attribute
+
+          # (Optional) Scope for separating locks
+          # config.acts_as_locked_scope = -> { "default_scope" }
+
+          # (Optional) Model class for locked_by lookups
+          # config.locked_by_class = "User"
+
+        end
+        # (Optional) TTL (in seconds) for lock keys, protecting against stuck locks.
+        # Default is 12 hours. Set to 0 to disable expiration.
+        # Configure via the RAILS_SOFT_LOCK_TTL environment variable, or via the
+        # `ttl:` key in config/redis.yml — NOT via config.adapter_options.
       RUBY
       puts "Created RailsSoftLock configuration file at #{initializer_path}"
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_soft_lock
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Sergey Arkhipov
@@ -31,14 +31,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
 description: Using In-Memory Databases to Work with Rails Active Record Locks
 email:
 - sergey-arkhipov@ya.ru
@@ -84,7 +84,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="