rails_soft_lock 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c32f27ad65f09cec7133fd1c1f9224ce95b3d64318be08296ac77bfb5c1f16c
-  data.tar.gz: a4fe29cc7cc3c461f6b22bc5d4d3ff012303021ac7fbcccaa16efd11c593b2c5
+  metadata.gz: 9f6443555d20169a04a8c16dbe970b56fca4f3befe6a840bea0f1385e6783524
+  data.tar.gz: '08382ac46d6a3fe067e4899721da2b217ccd74065bf76061886509694ab6c85a'
 SHA512:
-  metadata.gz: 7d42129a9a4a00d10ff3f2fb55ef9600b51f1582aec62bc57a83a0ed3935326e4ca26a7433673f754985c09162d8c57e300da1bded27c8132ad66ee04f3a1749
-  data.tar.gz: a7b631bc817bfd3b1994c6a21b1cb1c775caace2f12c1a850c2b3b781f527792099a91de1a5255ebb8f05fcbfdfc08121c2c0682af83604e18997e2498cbdccd
+  metadata.gz: a1bd7a8346ccfc3e17b12f632847627bd313ae27bb2cc641e437524f932d708cd93f2edcf9e7694a8e5b9df81efab8b1c76006d67fb7508fe5ad5e8df48797d6
+  data.tar.gz: 892296a9f41bf10c6c61eca479b42bd6f79892cb2dfbe9762f978080b634630b34f97178759259f0efa20db7bbed25ac059403a83e44cf3febcc3175932f6fd6

data/README.md

@@ -1,21 +1,49 @@
-# RailsSoftLock
+# RailsSoftLock – Group Locking for ApplicationRecord by Attribute
 
-This gem implements the ability to lock Rails Active Records using adapters for in-memory databases, such as redis, nats, etc.
-Locks can be done by using the active record attribute.
-it is possible to define the uniqueness scope of the attribute.
-The gem is under active development.
-Currently, an adapter to redis-compatible databases, such as redis, walkey, etc., has been implemented.
+## Overview
+
+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
+
+    Lightweight Group Locking:
+
+        Locks records sharing the same attribute value via an in-memory database (e.g., Redis, NATS).
+
+        Avoids expensive row-level locks in your primary database.
+
+    ActiveRecord Integration:
+
+        Extends Rails’ built-in locking mechanisms with adapters for in-memory stores.
+
+        Supports scoped uniqueness (e.g., lock groups by account_id + category).
+
+    Beyond Locking:
+
+        Can also mark/tag groups of records (e.g., flag all records with project_id=123 as "favorites").
+
+        Useful for batch operations or state management (e.g., "processing", "archived").
+
+### Current Status
+
+    Active Development: New features and optimizations in progress.
+
+    Available Adapters: Redis and Redis-compatible databases (e.g., Valkey).
 
 ## Installation
 
 Install the gem and add to the application's Gemfile:
 
 ```bash
+# Stable version
+gem "rails_soft_lock"
+# Last version
 gem "rails_soft_lock", git: "https://github.com/sergey-arkhipov/rails_soft_lock.git"
 
 ```
 
-After run
+When using Redis as an adapter and having REDIS_URL in config/redis.yml it is not necessary to install the initializer.
+Only when need to replace some standard settings, User model, for example, or adapter.
 
 ```bash
 bundle install
@@ -57,6 +85,19 @@ Gem use ConnectionPool inside for safety connect to Redis adapter (now inplement
 
 Gem assumes that the User model is used to determine the user who sets the lock.
 
+Another model for setting the attribute of the blocking user can be specified in the configuration.
+The model ID is used for blocking.
+
+```ruby
+RailsSoftLock.configure do |config|
+...
+  # (Optional) Model class for locked_by lookups
+  config.locked_by_class = "User"
+
+
+end
+```
+
 Model < ApplicationRecord should include `RailsSoftLock::ModelExtensions`
 and `acts_as_locked_by` with `acts_as_locked_scope` should be set, for example
 
@@ -64,26 +105,42 @@ and `acts_as_locked_by` with `acts_as_locked_scope` should be set, for example
 class Article < ApplicationRecord
   include RailsSoftLock::ModelExtensions
 
-  acts_as_locked_by(:attribyte)
-  acts_as_locked_scope(proc { :scoped_attribute || "none" })
+  acts_as_locked_by: attribyte, scope: -> { 'scope_result'}
+
 
 ```
 
 See `spec/rails_soft_lock/model_extensions_spec.rb for implemented methods`
 
-### Attention
+### Understanding the lock_or_find Method
+
+The lock_or_find method returns a hash with the following structure:
+ruby
+
+{ has_locked: false, locked_by: user.id }
+
+Key Points:
+
+    has_locked: false indicates that the object was not locked prior to this operation.
+
+        Note: This does not refer to the success/failure of the lock attempt itself.
+
+    How locking works:
+
+        Since this is an in-memory database designed for fast access, the method:
+
+            Sets the lock (if no lock existed).
+
+            Reports (has_locked: false) that no prior lock was present.
+
+            Returns the ID of the user who now holds the lock.
 
-Pay attention how method `locak_or_find` work
+        If the object was already locked, it returns:
+        ruby
 
-Method return hash
-`has_locked: false, locked_by: user.id`
+{ has_locked: true, locked_by: <existing_lock_user_id> }
 
-`has_lock`: false implies that there was no lock on the passed object before this point.
-Not to be confused with the result of executing the lock itself.
-Since this is an in-memory base and the goal is quick and easy access, the method sets the lock,
-reports that there was no lock before, and returns the user of the lock.
-If there was a lock, true is returned and the user of this current lock.
-The lock itself is not changed.
+In this case, the lock remains unchanged (no new lock is set).
 
 ## Development
 

data/lib/rails_soft_lock/configuration.rb

@@ -7,21 +7,31 @@ module RailsSoftLock
     # List of supported adapters.
     VALID_ADAPTERS = %i[redis nats memcached].freeze
     attr_reader :adapter
-    attr_accessor :adapter_options, :acts_as_locked_by, :acts_as_locked_scope
+    # :reek:Attribute
+    attr_accessor :adapter_options
+    # :reek:Attribute
+    attr_writer :locked_by_class
 
     def initialize
       @adapter = :redis # Default adapter
-      @adapter_options = adapter_options || {} # Default adapter options
-      @acts_as_locked_by = :none
-      @acts_as_locked_scope = -> { "default" }
+      @adapter_options ||= RedisConfig.default_adapter_options # Default adapter options
+      @locked_by_class = locked_by_class || "User"
     end
 
-    def [](key)
-      send(key)
+    def acts_as_locked_by(attribute = :lock_attribute, scope: -> { "none" })
+      @acts_as_locked_options = { by: attribute, scope: scope }
     end
 
-    def []=(key, value)
-      send("#{key}=", value)
+    def acts_as_locked_attribute
+      @acts_as_locked_options&.[](:by) || :lock_attribute
+    end
+
+    def acts_as_locked_scope
+      @acts_as_locked_options&.[](:scope)&.call || "none"
+    end
+
+    def locked_by_class
+      @locked_by_class.is_a?(String) ? @locked_by_class.constantize : @locked_by_class
     end
 
     # Sets the adapter and validates it.
@@ -33,30 +43,4 @@ module RailsSoftLock
       @adapter = value
     end
   end
-
-  class << self
-    # Configures the RailsSoftLock gem with a block.
-    # @yield [config] Yields the configuration object to the block.
-    # @return [void]
-    def configure
-      @configuration ||= Configuration.new
-      if block_given?
-        yield(@configuration)
-      else
-        warn "[RailsSoftLock] No configuration block provided in `configure`"
-      end
-    end
-
-    # Returns the current configuration instance.
-    # @return [Configuration] The configuration object.
-    def configuration
-      @configuration ||= Configuration.new
-    end
-
-    # Resets the configuration (useful for testing).
-    # @return [void]
-    def reset_configuration
-      @configuration = nil
-    end
-  end
 end

data/lib/rails_soft_lock/lock_object.rb

@@ -9,7 +9,7 @@ module RailsSoftLock
   #   - object_key: The identifier of the lock instance, typically a unique database record ID
   #   - object_value: The identifier of the locker that locked the record
   class LockObject
-    # Подключаем адаптер на основе конфигурации
+    # Attach adapter based on config
     def self.adapter
       case RailsSoftLock.configuration.adapter
       when :redis

data/lib/rails_soft_lock/model_extensions.rb

@@ -3,25 +3,13 @@
 # lib/rails_soft_lock/model_extensions.rb
 
 module RailsSoftLock
-  # Определяет настройки блокировки модели
+  # Extend model and give methods from gem
   module ModelExtensions
     extend ActiveSupport::Concern
-
     class_methods do
-      def acts_as_locked_by(attribute = :none)
-        RailsSoftLock.configuration[:acts_as_locked_by] = attribute
-      end
-
-      def current_locked_attribute
-        RailsSoftLock.configuration[:acts_as_locked_by]
-      end
-
-      def acts_as_locked_scope(attribute = nil)
-        RailsSoftLock.configuration[:acts_as_locked_scope] = attribute || -> { "default" }
-      end
-
-      def current_locked_scope
-        RailsSoftLock.configuration[:acts_as_locked_scope]
+      # :reek:UtilityFunction
+      def acts_as_locked_by(attribute = :lock_attribute, scope: -> { "none" })
+        RailsSoftLock.configuration.acts_as_locked_by(attribute, scope: scope)
       end
 
       def all_locks
@@ -33,8 +21,8 @@ module RailsSoftLock
       end
 
       def object_name
-        scope = current_locked_scope&.call || "default"
-        "#{name}-#{scope}"
+        scope = RailsSoftLock.configuration.acts_as_locked_scope
+        "#{name}::#{scope}"
       end
     end
 
@@ -55,11 +43,11 @@ module RailsSoftLock
 
       def locked_by
         user_id = base_lock_object.locked_by&.to_i
-        user_id ? User.find_by(id: user_id) : nil
+        user_id ? RailsSoftLock.configuration.locked_by_class.find_by(id: user_id) : nil
       end
 
       def object_key
-        attribute = RailsSoftLock.configuration[:acts_as_locked_by]
+        attribute = RailsSoftLock.configuration.acts_as_locked_attribute
         raise ArgumentError, "No locked attribute defined" if attribute == :none
 
         send(attribute)

data/lib/rails_soft_lock/redis_config.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# lib/rails_soft_lock/redis_config.rb
+module RailsSoftLock
+  # Provides Redis configuration management for RailsSoftLock gem
+  # Handles:
+  # - Default Redis settings
+  # - Rails-specific configuration lookup
+  # - Safe fallbacks when Rails isn't available
+  module RedisConfig
+    module_function
+
+    # Returns the complete Redis adapter options hash
+    # @return [Hash] Options hash with :redis key containing configuration
+    # @example
+    #   { redis: { host: 'localhost', port: 6379, db: 0, timeout: 5 } }
+    def default_adapter_options
+      { redis: config_with_defaults }
+    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)
+    end
+
+    # Checks if Rails environment is available and properly configured
+    # @return [Boolean]
+    def rails_available?
+      if defined?(Rails) &&
+         Rails.respond_to?(:application) &&
+         Rails.application
+        true
+      else
+        false
+      end
+    end
+
+    # Attempts to load Redis config from Rails application
+    # @return [Hash] Redis configuration from Rails or empty hash if unavailable
+    # @note Safely handles cases where config_for isn't available
+    def rails_config
+      return {} unless rails_config_available?
+
+      config = Rails.application.config_for(:redis)
+
+      config.is_a?(Hash) ? config.symbolize_keys : {}
+    rescue RuntimeError, ArgumentError
+      {}
+    end
+
+    # Checks if Rails provides config_for functionality
+    # @return [Boolean]
+    # @api private
+    def rails_config_available?
+      Rails.application.respond_to?(:config_for)
+    end
+
+    # The default Redis connection settings
+    # @return [Hash]
+    # @api private
+    def default_settings
+      { url: "redis://localhost:6379/0", timeout: 5 }
+    end
+  end
+end

data/lib/rails_soft_lock/version.rb

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

data/lib/rails_soft_lock.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
+# lib/rails_soft_lock.rb
+
 require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
-loader.setup
 
 # RailsSoftLock - module for soft lock ApplicationRecord by attribyte
 module RailsSoftLock
@@ -30,6 +30,35 @@ module RailsSoftLock
     lock_manager(object_name: object_name, object_key: object_key, object_value: object_value).lock_or_find
   end
 
+  class << self
+    # Configures the RailsSoftLock gem with a block.
+    # @yield [config] Yields the configuration object to the block.
+    # @return [void]
+    def configure
+      @configuration ||= Configuration.new
+      if block_given?
+        yield(@configuration)
+      else
+        warn "[RailsSoftLock] No configuration block provided in `configure`"
+      end
+    end
+
+    # Returns the current configuration instance.
+    # @return [Configuration] The configuration object.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Resets the configuration (useful for testing).
+    # @return [void]
+    def reset_configuration
+      @configuration = nil
+    end
+  end
+
   # Load rake task if Rails
   require "rails_soft_lock/railtie" if defined?(Rails)
 end
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup

data/lib/tasks/rails_soft_lock.rake

@@ -22,7 +22,7 @@ namespace :rails_soft_lock do
 
         # configuration for the redis adapter
         config.adapter_options = {
-          redis: rails.application.config_for(:redis).merge(
+          redis: Rails.application.config_for(:redis).merge(
             timeout: 5
           )
         }
@@ -34,7 +34,7 @@ namespace :rails_soft_lock do
                 # config.acts_as_locked_scope = -> { "default_scope" }
 
                 # (Optional) Model class for locked_by lookups
-                # config.locked_by_class = User
+                # config.locked_by_class = "User"
               end
       RUBY
       puts "Created RailsSoftLock configuration file at #{initializer_path}"

data/sig/rails_soft_lock.rbs

@@ -2,6 +2,8 @@
 module RailsSoftLock
   self.@lock_manager: untyped
 
+  self.@configuration: untyped
+
   # Error class for gem
   class Error < StandardError
   end
@@ -14,4 +16,17 @@ module RailsSoftLock
   def self.create: (untyped object_name, untyped object_key, untyped object_value) -> untyped
 
   def self.update: (untyped object_name, untyped object_key, untyped object_value) -> untyped
+
+  # Configures the RailsSoftLock gem with a block.
+  # @yield [config] Yields the configuration object to the block.
+  # @return [void]
+  def self.configure: () ?{ (untyped) -> untyped } -> untyped
+
+  # Returns the current configuration instance.
+  # @return [Configuration] The configuration object.
+  def self.configuration: () -> untyped
+
+  # Resets the configuration (useful for testing).
+  # @return [void]
+  def self.reset_configuration: () -> untyped
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_soft_lock
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Sergey Arkhipov
 - Vladimir Peskov
 bindir: lib
 cert_chain: []
-date: 2025-04-26 00:00:00.000000000 Z
+date: 2025-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -40,7 +40,8 @@ dependencies:
         version: '2.7'
 description: Using In-Memory Databases to Work with Rails Active Record Locks
 email:
-- sergey-ARkhipov@ya.ru
+- sergey-arkhipov@ya.ru
+- v.peskov@mail.ru
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -59,15 +60,10 @@ files:
 - lib/rails_soft_lock/model_extensions.rb
 - lib/rails_soft_lock/railtie.rb
 - lib/rails_soft_lock/redis_adapter.rb
+- lib/rails_soft_lock/redis_config.rb
 - lib/rails_soft_lock/version.rb
 - lib/tasks/rails_soft_lock.rake
 - sig/rails_soft_lock.rbs
-- sig/rails_soft_lock/configuration.rbs
-- sig/rails_soft_lock/lock_object.rbs
-- sig/rails_soft_lock/model_extensions.rbs
-- sig/rails_soft_lock/railtie.rbs
-- sig/rails_soft_lock/redis_adapter.rbs
-- sig/rails_soft_lock/version.rbs
 homepage: https://github.com/sergey-arkhipov/rails_soft_lock
 licenses:
 - MIT

data/sig/rails_soft_lock/configuration.rbs

@@ -1,50 +0,0 @@
-# lib/rails_soft_lock/configuration.rb
-module RailsSoftLock
-  self.@configuration: untyped
-
-  # Configuration class for RailsSoftLock gem.
-  class Configuration
-    @adapter: untyped
-
-    @adapter_options: untyped
-
-    @acts_as_locked_by: untyped
-
-    @acts_as_locked_scope: untyped
-
-    # List of supported adapters.
-    VALID_ADAPTERS: ::Array[:redis | :nats | :memcached]
-
-    attr_reader adapter: untyped
-
-    attr_accessor adapter_options: untyped
-
-    attr_accessor acts_as_locked_by: untyped
-
-    attr_accessor acts_as_locked_scope: untyped
-
-    def initialize: () -> void
-
-    def []: (untyped key) -> untyped
-
-    def []=: (untyped key, untyped value) -> untyped
-
-    # Sets the adapter and validates it.
-    # @param value [Symbol] The adapter to use.
-    # @raise [ArgumentError] If the adapter is not supported.
-    def adapter=: (untyped value) -> untyped
-  end
-
-  # Configures the RailsSoftLock gem with a block.
-  # @yield [config] Yields the configuration object to the block.
-  # @return [void]
-  def self.configure: () ?{ (untyped) -> untyped } -> untyped
-
-  # Returns the current configuration instance.
-  # @return [Configuration] The configuration object.
-  def self.configuration: () -> untyped
-
-  # Resets the configuration (useful for testing).
-  # @return [void]
-  def self.reset_configuration: () -> untyped
-end

data/sig/rails_soft_lock/lock_object.rbs

@@ -1,41 +0,0 @@
-module RailsSoftLock
-  # Service for managing object locks
-  # A lock object contains the following parameters:
-  #   - object_name: The name of the lock storage, typically the model name with an optional scope
-  #   - object_key: The identifier of the lock instance, typically a unique database record ID
-  #   - object_value: The identifier of the locker that locked the record
-  class LockObject
-    @object_name: untyped
-
-    @object_key: untyped
-
-    @object_value: untyped
-
-    # Подключаем адаптер на основе конфигурации
-    def self.adapter: () -> untyped
-
-    attr_reader object_name: untyped
-
-    attr_reader object_key: untyped
-
-    attr_reader object_value: untyped
-
-    def initialize: (object_name: untyped, ?object_key: untyped?, ?object_value: untyped?) -> void
-
-    # Returns the ID of the locker who locked the object
-    # @return [String, nil] The locker's ID or nil if not locked
-    def locked_by: () -> untyped
-
-    # Attempts to lock the object or returns the existing lock
-    # @return [Hash] { has_locked: Boolean, locked_by: String or nil }
-    def lock_or_find: () -> { has_locked: untyped, locked_by: untyped }
-
-    # Unlocks the object
-    # @return [Boolean] True if the lock was removed, false otherwise
-    def unlock: () -> untyped
-
-    # Returns all locks in the storage
-    # @return [Hash] All key-value pairs in the storage
-    def all_locks: () -> untyped
-  end
-end

data/sig/rails_soft_lock/model_extensions.rbs

@@ -1,6 +0,0 @@
-module RailsSoftLock
-  # Определяет настройки блокировки модели
-  module ModelExtensions
-    extend ActiveSupport::Concern
-  end
-end

data/sig/rails_soft_lock/railtie.rbs

@@ -1,7 +0,0 @@
-module RailsSoftLock
-  # Load rails_soft_lock:install
-  # After load rails rails_soft_lock:install check config/initializers/rails_soft_lock.rb
-  # and create initializer if do not exists
-  class Railtie < Rails::Railtie
-  end
-end

data/sig/rails_soft_lock/redis_adapter.rbs

@@ -1,29 +0,0 @@
-module RailsSoftLock
-  # Adapter for store lock in redis
-  module RedisAdapter
-    @redis_client: untyped
-
-    # Initialize Redis client
-    def redis_client: () -> untyped
-
-    # Retrieves a value by key from the specified hash
-    # @return [String, nil] The value associated with the key
-    def get: () -> untyped
-
-    # 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
-    def create: () -> untyped
-
-    # 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
-    def update: () -> untyped
-
-    # Deletes a key from the specified hash
-    # @return [Boolean] true if the key was deleted, false if it did not exist
-    def delete: () -> untyped
-
-    # Retrieves all key-value pairs in the specified hash
-    # @return [Hash] The key-value pairs in the hash
-    def all: () -> untyped
-  end
-end

data/sig/rails_soft_lock/version.rbs

@@ -1,3 +0,0 @@
-module RailsSoftLock
-  VERSION: "0.1.0"
-end