kannuki 0.1.0

data/lib/kannuki/strategies/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module Strategies
+    class Base
+      attr_reader :adapter, :options
+
+      def initialize(adapter, options = {})
+        @adapter = adapter
+        @options = options
+      end
+
+      def execute(lock_key, &block)
+        raise NotImplementedError, 'Subclasses must implement #execute'
+      end
+
+      protected
+
+      def timeout
+        options.fetch(:timeout, Kannuki.configuration.default_timeout)
+      end
+
+      def shared?
+        options.fetch(:shared, false)
+      end
+
+      def transaction?
+        options.fetch(:transaction, false)
+      end
+
+      def on_conflict
+        options.fetch(:on_conflict, :wait)
+      end
+
+      def acquire_lock(lock_key)
+        adapter.acquire_lock(lock_key, timeout: timeout, shared: shared?, transaction: transaction?)
+      end
+
+      def release_lock(lock_key)
+        adapter.release_lock(lock_key, transaction: transaction?)
+      end
+
+      def track_lock(lock_key)
+        Thread.current[:kannuki_locks] ||= Set.new
+        Thread.current[:kannuki_locks] << lock_key.to_s
+      end
+
+      def untrack_lock(lock_key)
+        Thread.current[:kannuki_locks]&.delete(lock_key.to_s)
+      end
+
+      def execute_with_lock(lock_key)
+        start_time = Time.now
+        acquired = acquire_lock(lock_key)
+
+        if acquired
+          duration = Time.now - start_time
+          Instrumentation.acquired(lock_key, adapter: adapter.adapter_name, duration: duration)
+          track_lock(lock_key)
+
+          begin
+            result = yield
+            Result.new(lock_key: lock_key, acquired: true, value: result, duration: duration,
+                       adapter_name: adapter.adapter_name)
+          ensure
+            release_start = Time.now
+            release_lock(lock_key)
+            untrack_lock(lock_key)
+            Instrumentation.released(lock_key, adapter: adapter.adapter_name, duration: Time.now - release_start)
+          end
+        else
+          handle_lock_failure(lock_key)
+        end
+      end
+
+      def handle_lock_failure(lock_key)
+        Instrumentation.failed(lock_key, adapter: adapter.adapter_name, reason: :not_acquired, timeout: timeout)
+
+        case on_conflict
+        when :raise
+          raise LockNotAcquiredError.new(lock_key.to_s, timeout: timeout)
+        when :skip
+          Result.new(lock_key: lock_key, acquired: false)
+        else
+          Result.new(lock_key: lock_key, acquired: false)
+        end
+      end
+    end
+  end
+end

data/lib/kannuki/strategies/blocking.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module Strategies
+    class Blocking < Base
+      def execute(lock_key, &block)
+        Instrumentation.waiting(lock_key, adapter: adapter.adapter_name) if timeout.nil?
+        execute_with_lock(lock_key, &block)
+      end
+    end
+  end
+end

data/lib/kannuki/strategies/non_blocking.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module Strategies
+    class NonBlocking < Base
+      def execute(lock_key, &block)
+        execute_with_lock(lock_key, &block)
+      end
+
+      protected
+
+      def timeout
+        0
+      end
+    end
+  end
+end

data/lib/kannuki/strategies/retry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module Strategies
+    class Retry < Base
+      def execute(lock_key, &block)
+        attempts = 0
+        max_attempts = retry_attempts
+
+        loop do
+          attempts += 1
+          result = try_acquire_and_execute(lock_key, &block)
+          return result if result.acquired?
+          return result if attempts >= max_attempts
+
+          sleep(calculate_interval(attempts))
+        end
+      end
+
+      protected
+
+      def retry_attempts
+        options.fetch(:retry_attempts, Kannuki.configuration.retry_attempts)
+      end
+
+      def retry_interval
+        options.fetch(:retry_interval, Kannuki.configuration.retry_interval)
+      end
+
+      def retry_backoff
+        options.fetch(:retry_backoff, Kannuki.configuration.retry_backoff)
+      end
+
+      def calculate_interval(attempt)
+        case retry_backoff
+        when :exponential
+          retry_interval * (2**(attempt - 1))
+        when :linear
+          retry_interval * attempt
+        else
+          retry_interval
+        end
+      end
+
+      def try_acquire_and_execute(lock_key)
+        acquired = adapter.acquire_lock(lock_key, timeout: 0, shared: shared?, transaction: transaction?)
+
+        if acquired
+          start_time = Time.now
+          Instrumentation.acquired(lock_key, adapter: adapter.adapter_name, duration: 0)
+          track_lock(lock_key)
+
+          begin
+            result = yield
+            duration = Time.now - start_time
+            Result.new(lock_key: lock_key, acquired: true, value: result, duration: duration,
+                       adapter_name: adapter.adapter_name)
+          ensure
+            release_start = Time.now
+            release_lock(lock_key)
+            untrack_lock(lock_key)
+            Instrumentation.released(lock_key, adapter: adapter.adapter_name, duration: Time.now - release_start)
+          end
+        else
+          Result.new(lock_key: lock_key, acquired: false)
+        end
+      end
+    end
+  end
+end

data/lib/kannuki/strategies.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'strategies/base'
+require_relative 'strategies/blocking'
+require_relative 'strategies/non_blocking'
+require_relative 'strategies/retry'

data/lib/kannuki/testing.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Kannuki
+  module Testing
+    class << self
+      def enable!
+        Kannuki.configuration.test_mode = true
+        @held_locks = Set.new
+      end
+
+      def disable!
+        Kannuki.configuration.test_mode = false
+        @held_locks = nil
+      end
+
+      def clear!
+        @held_locks&.clear
+      end
+
+      def test_mode?
+        Kannuki.configuration.test_mode
+      end
+
+      def simulate_lock_held(name)
+        @held_locks ||= Set.new
+        @held_locks << normalize_key(name)
+      end
+
+      def release_simulated_lock(name)
+        @held_locks&.delete(normalize_key(name))
+      end
+
+      def lock_held?(name)
+        @held_locks&.include?(normalize_key(name)) || false
+      end
+
+      def held_locks
+        @held_locks.to_a
+      end
+
+      private
+
+      def normalize_key(name)
+        case name
+        when LockKey
+          name.normalized_key
+        else
+          name.to_s
+        end
+      end
+    end
+
+    module RSpecHelpers
+      def with_kannuki_test_mode
+        before { Kannuki::Testing.enable! }
+        after { Kannuki::Testing.clear! }
+      end
+    end
+
+    module Matchers
+      if defined?(RSpec::Matchers::DSL)
+        extend RSpec::Matchers::DSL
+
+        matcher :acquire_kannuki do |expected_name|
+          supports_block_expectations
+
+          match do |block|
+            acquired_locks = []
+
+            subscriber = Kannuki::Instrumentation.subscribe('acquired') do |_name, _start, _finish, _id, payload|
+              acquired_locks << payload[:lock_key].to_s
+            end
+
+            begin
+              block.call
+            ensure
+              Kannuki::Instrumentation.unsubscribe(subscriber)
+            end
+
+            acquired_locks.any? { |lock| lock.include?(expected_name.to_s) }
+          end
+
+          failure_message do
+            "expected block to acquire advisory lock matching '#{expected_name}'"
+          end
+
+          failure_message_when_negated do
+            "expected block not to acquire advisory lock matching '#{expected_name}'"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kannuki/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kannuki
+  VERSION = '0.1.0'
+end

data/lib/kannuki.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_support'
+require 'active_support/concern'
+
+require_relative 'kannuki/version'
+require_relative 'kannuki/errors'
+require_relative 'kannuki/configuration'
+require_relative 'kannuki/lock_key'
+require_relative 'kannuki/result'
+require_relative 'kannuki/instrumentation'
+require_relative 'kannuki/adapters'
+require_relative 'kannuki/strategies'
+require_relative 'kannuki/lock_manager'
+require_relative 'kannuki/model_extension'
+require_relative 'kannuki/active_job_extension'
+require_relative 'kannuki/testing'
+require_relative 'kannuki/railtie' if defined?(Rails::Railtie)
+
+module Kannuki
+  class << self
+    delegate :with_lock, :try_lock, :lock!, :locked?, :current_locks, :holding_lock?, to: LockManager
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: kannuki
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Kannuki provides database-agnostic advisory locking for ActiveRecord
+  with support for PostgreSQL and MySQL, offering blocking/non-blocking strategies,
+  instrumentation, and ActiveJob integration.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/guide.md
+- lib/generators/kannuki/install_generator.rb
+- lib/generators/kannuki/templates/kannuki.rb
+- lib/kannuki.rb
+- lib/kannuki/active_job_extension.rb
+- lib/kannuki/adapters.rb
+- lib/kannuki/adapters/base.rb
+- lib/kannuki/adapters/mysql.rb
+- lib/kannuki/adapters/null.rb
+- lib/kannuki/adapters/postgresql.rb
+- lib/kannuki/configuration.rb
+- lib/kannuki/errors.rb
+- lib/kannuki/instrumentation.rb
+- lib/kannuki/lock_key.rb
+- lib/kannuki/lock_manager.rb
+- lib/kannuki/model_extension.rb
+- lib/kannuki/railtie.rb
+- lib/kannuki/result.rb
+- lib/kannuki/strategies.rb
+- lib/kannuki/strategies/base.rb
+- lib/kannuki/strategies/blocking.rb
+- lib/kannuki/strategies/non_blocking.rb
+- lib/kannuki/strategies/retry.rb
+- lib/kannuki/testing.rb
+- lib/kannuki/version.rb
+homepage: https://github.com/ydah/kannuki
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ydah/kannuki
+  source_code_uri: https://github.com/ydah/kannuki
+  changelog_uri: https://github.com/ydah/kannuki/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Advisory locking for ActiveRecord with modern Rails conventions
+test_files: []