kannuki 0.1.0

data/lib/kannuki/active_job_extension.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module ActiveJobExtension
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def with_lock(name, key: nil, **options)
+        @kannuki_config = { name: name, key: key, options: options }
+
+        around_perform do |job, block|
+          config = job.class.instance_variable_get(:@kannuki_config)
+          lock_key = LockKey.from_job(job, key: config[:key])
+          full_key = "#{config[:name]}/#{lock_key}"
+
+          result = LockManager.with_lock(full_key, **config[:options]) do
+            block.call
+          end
+
+          raise LockNotAcquiredError, full_key if result == false && config[:options][:on_conflict] != :skip
+        end
+      end
+
+      def unique_by_lock(on_conflict: :skip, timeout: 0, **options)
+        around_perform do |job, block|
+          lock_key = "unique/#{job.class.name}/#{job.arguments.map(&:to_s).join('-')}"
+
+          result = LockManager.with_lock(lock_key, timeout: timeout, on_conflict: on_conflict, **options) do
+            block.call
+          end
+
+          if result == false
+            case on_conflict
+            when :raise
+              raise LockNotAcquiredError, lock_key
+            when :skip
+              Kannuki.configuration.logger.info(
+                "[Kannuki] Skipping duplicate job: #{job.class.name} with args #{job.arguments}"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kannuki/adapters/base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module Adapters
+    class Base
+      attr_reader :connection
+
+      def initialize(connection)
+        @connection = connection
+      end
+
+      def acquire_lock(key, timeout:, shared:, transaction:)
+        raise NotImplementedError, 'Subclasses must implement #acquire_lock'
+      end
+
+      def release_lock(key, transaction:)
+        raise NotImplementedError, 'Subclasses must implement #release_lock'
+      end
+
+      def lock_exists?(key)
+        raise NotImplementedError, 'Subclasses must implement #lock_exists?'
+      end
+
+      def supports_shared_locks?
+        false
+      end
+
+      def supports_transaction_locks?
+        false
+      end
+
+      def adapter_name
+        self.class.name.split('::').last.downcase
+      end
+
+      private
+
+      def quote(value)
+        connection.quote(value)
+      end
+
+      def execute(sql)
+        connection.execute(sql)
+      end
+
+      def select_value(sql)
+        connection.select_value(sql)
+      end
+    end
+  end
+end

data/lib/kannuki/adapters/mysql.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module Adapters
+    class MySQL < Base
+      def acquire_lock(key, timeout:, shared:, transaction:)
+        raise NotSupportedError, 'MySQL does not support shared advisory locks' if shared
+
+        raise NotSupportedError, 'MySQL does not support transaction-scoped advisory locks' if transaction
+
+        string_key = key.is_a?(LockKey) ? key.normalized_key : LockKey.new(key).normalized_key
+        timeout_value = timeout || -1
+
+        result = select_value("SELECT GET_LOCK(#{quote(string_key)}, #{timeout_value})")
+
+        case result.to_i
+        when 1 then true
+        when 0 then false
+        else
+          raise LockNotAcquiredError.new(string_key), "GET_LOCK returned unexpected value: #{result}"
+        end
+      end
+
+      def release_lock(key, transaction:)
+        string_key = key.is_a?(LockKey) ? key.normalized_key : LockKey.new(key).normalized_key
+        result = select_value("SELECT RELEASE_LOCK(#{quote(string_key)})")
+        result.to_i == 1
+      end
+
+      def lock_exists?(key)
+        string_key = key.is_a?(LockKey) ? key.normalized_key : LockKey.new(key).normalized_key
+        result = select_value("SELECT IS_USED_LOCK(#{quote(string_key)})")
+        !result.nil?
+      end
+
+      def supports_shared_locks?
+        false
+      end
+
+      def supports_transaction_locks?
+        false
+      end
+    end
+  end
+end

data/lib/kannuki/adapters/null.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module Adapters
+    class Null < Base
+      def initialize(connection = nil)
+        @connection = connection
+        @locks = {}
+      end
+
+      def acquire_lock(key, timeout:, shared:, transaction:)
+        string_key = key.is_a?(LockKey) ? key.normalized_key : key.to_s
+
+        return false if Kannuki::Testing.test_mode? && Kannuki::Testing.lock_held?(string_key)
+
+        @locks[string_key] = { shared: shared, transaction: transaction }
+        true
+      end
+
+      def release_lock(key, transaction:)
+        string_key = key.is_a?(LockKey) ? key.normalized_key : key.to_s
+        @locks.delete(string_key)
+        true
+      end
+
+      def lock_exists?(key)
+        string_key = key.is_a?(LockKey) ? key.normalized_key : key.to_s
+        @locks.key?(string_key) || (Kannuki::Testing.test_mode? && Kannuki::Testing.lock_held?(string_key))
+      end
+
+      def supports_shared_locks?
+        true
+      end
+
+      def supports_transaction_locks?
+        true
+      end
+
+      def clear!
+        @locks.clear
+      end
+    end
+  end
+end

data/lib/kannuki/adapters/postgresql.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module Adapters
+    class PostgreSQL < Base
+      POLL_INTERVAL = 0.1
+
+      def acquire_lock(key, timeout:, shared:, transaction:)
+        numeric_key = key.is_a?(LockKey) ? key.numeric_key : LockKey.new(key).numeric_key
+
+        if transaction
+          acquire_transaction_lock(numeric_key, shared: shared)
+        else
+          acquire_session_lock(numeric_key, timeout: timeout, shared: shared)
+        end
+      end
+
+      def release_lock(key, transaction:)
+        return true if transaction
+
+        numeric_key = key.is_a?(LockKey) ? key.numeric_key : LockKey.new(key).numeric_key
+        result = select_value("SELECT pg_advisory_unlock(#{numeric_key})")
+        [true, 't'].include?(result)
+      end
+
+      def lock_exists?(key)
+        numeric_key = key.is_a?(LockKey) ? key.numeric_key : LockKey.new(key).numeric_key
+        result = select_value(<<~SQL)
+          SELECT EXISTS(
+            SELECT 1 FROM pg_locks
+            WHERE locktype = 'advisory'
+            AND classid = #{(numeric_key >> 32) & 0xFFFFFFFF}
+            AND objid = #{numeric_key & 0xFFFFFFFF}
+          )
+        SQL
+        [true, 't'].include?(result)
+      end
+
+      def supports_shared_locks?
+        true
+      end
+
+      def supports_transaction_locks?
+        true
+      end
+
+      private
+
+      def acquire_session_lock(numeric_key, timeout:, shared:)
+        lock_func = shared ? 'pg_advisory_lock_shared' : 'pg_advisory_lock'
+        try_func = shared ? 'pg_try_advisory_lock_shared' : 'pg_try_advisory_lock'
+
+        if timeout.nil?
+          execute("SELECT #{lock_func}(#{numeric_key})")
+          true
+        elsif timeout.zero?
+          result = select_value("SELECT #{try_func}(#{numeric_key})")
+          [true, 't'].include?(result)
+        else
+          poll_for_lock(try_func, numeric_key, timeout)
+        end
+      end
+
+      def acquire_transaction_lock(numeric_key, shared:)
+        try_func = shared ? 'pg_try_advisory_xact_lock_shared' : 'pg_try_advisory_xact_lock'
+        result = select_value("SELECT #{try_func}(#{numeric_key})")
+        [true, 't'].include?(result)
+      end
+
+      def poll_for_lock(try_func, numeric_key, timeout)
+        deadline = Time.now + timeout
+        loop do
+          result = select_value("SELECT #{try_func}(#{numeric_key})")
+          return true if [true, 't'].include?(result)
+          return false if Time.now >= deadline
+
+          sleep(POLL_INTERVAL)
+        end
+      end
+    end
+  end
+end

data/lib/kannuki/adapters.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'adapters/base'
+require_relative 'adapters/postgresql'
+require_relative 'adapters/mysql'
+require_relative 'adapters/null'

data/lib/kannuki/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Kannuki
+  class Configuration
+    attr_accessor :default_timeout, :default_strategy, :key_prefix, :enable_instrumentation, :retry_attempts,
+                  :retry_interval, :retry_backoff, :on_failure, :test_mode
+    attr_writer :logger
+
+    def initialize
+      @default_timeout = nil
+      @default_strategy = :blocking
+      @key_prefix = nil
+      @enable_instrumentation = true
+      @logger = nil
+      @retry_attempts = 3
+      @retry_interval = 0.5
+      @retry_backoff = :exponential
+      @on_failure = :return_false
+      @test_mode = false
+    end
+
+    def logger
+      @logger ||= if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+                    Rails.logger
+                  else
+                    Logger.new($stdout)
+                  end
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/kannuki/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Kannuki
+  class Error < StandardError; end
+
+  class LockNotAcquiredError < Error
+    attr_reader :lock_key, :timeout
+
+    def initialize(lock_key, timeout: nil)
+      @lock_key = lock_key
+      @timeout = timeout
+      super("Failed to acquire advisory lock: #{lock_key}" +
+        (timeout ? " (timeout: #{timeout}s)" : ''))
+    end
+  end
+
+  class LockTimeoutError < LockNotAcquiredError; end
+
+  class NotSupportedError < Error; end
+
+  class DeadlockError < Error
+    attr_reader :lock_key
+
+    def initialize(lock_key)
+      @lock_key = lock_key
+      super("Deadlock detected while acquiring lock: #{lock_key}")
+    end
+  end
+
+  class NestedLockError < Error
+    def initialize(outer_lock, inner_lock)
+      super("Cannot acquire nested advisory lock '#{inner_lock}' " \
+            "while holding '#{outer_lock}' (MySQL limitation)")
+    end
+  end
+end

data/lib/kannuki/instrumentation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+module Kannuki
+  module Instrumentation
+    NAMESPACE = 'kannuki'
+
+    class << self
+      def instrument(event, payload = {}, &block)
+        return yield unless Kannuki.configuration.enable_instrumentation
+
+        ActiveSupport::Notifications.instrument("#{event}.#{NAMESPACE}", payload, &block)
+      end
+
+      def subscribe(event, &block)
+        ActiveSupport::Notifications.subscribe("#{event}.#{NAMESPACE}", &block)
+      end
+
+      def unsubscribe(subscriber)
+        ActiveSupport::Notifications.unsubscribe(subscriber)
+      end
+
+      def acquired(lock_key, adapter:, duration:)
+        instrument('acquired', lock_key: lock_key, adapter: adapter, duration: duration)
+      end
+
+      def released(lock_key, adapter:, duration:)
+        instrument('released', lock_key: lock_key, adapter: adapter, duration: duration)
+      end
+
+      def failed(lock_key, adapter:, reason:, timeout: nil)
+        instrument('failed', lock_key: lock_key, adapter: adapter, reason: reason, timeout: timeout)
+      end
+
+      def timeout(lock_key, adapter:, timeout:)
+        instrument('timeout', lock_key: lock_key, adapter: adapter, timeout: timeout)
+      end
+
+      def waiting(lock_key, adapter:)
+        instrument('waiting', lock_key: lock_key, adapter: adapter)
+      end
+    end
+  end
+end

data/lib/kannuki/lock_key.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Kannuki
+  class LockKey
+    attr_reader :name, :normalized_key, :numeric_key
+
+    MAX_MYSQL_KEY_LENGTH = 64
+    POSTGRES_INT8_MAX = 9_223_372_036_854_775_807
+
+    def initialize(name, prefix: nil)
+      @name = name.to_s
+      @prefix = prefix || Kannuki.configuration.key_prefix
+      @normalized_key = build_normalized_key
+      @numeric_key = build_numeric_key
+    end
+
+    def to_s
+      @normalized_key
+    end
+
+    def to_i
+      @numeric_key
+    end
+
+    def ==(other)
+      case other
+      when LockKey
+        normalized_key == other.normalized_key
+      when String
+        normalized_key == other
+      when Integer
+        numeric_key == other
+      else
+        false
+      end
+    end
+    alias eql? ==
+
+    def hash
+      normalized_key.hash
+    end
+
+    class << self
+      def from_record(record, scope: nil)
+        parts = [record.class.table_name, record.id]
+        parts.unshift(record.public_send(scope)) if scope
+        new(parts.join('/'))
+      end
+
+      def from_job(job, key: nil)
+        if key.respond_to?(:call)
+          new(key.call(job))
+        elsif key
+          new(key.to_s)
+        else
+          new("#{job.class.name}/#{job.arguments.map(&:to_s).join('-')}")
+        end
+      end
+    end
+
+    private
+
+    def build_normalized_key
+      base = @prefix ? "#{@prefix}/#{@name}" : @name
+      if base.bytesize > MAX_MYSQL_KEY_LENGTH
+        "#{base[0, 31]}:#{Digest::MD5.hexdigest(base)}"
+      else
+        base
+      end
+    end
+
+    def build_numeric_key
+      Digest::MD5.hexdigest(@normalized_key).to_i(16) % POSTGRES_INT8_MAX
+    end
+  end
+end

data/lib/kannuki/lock_manager.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Kannuki
+  class LockManager
+    STRATEGY_MAP = {
+      blocking: Strategies::Blocking,
+      non_blocking: Strategies::NonBlocking,
+      retry: Strategies::Retry
+    }.freeze
+
+    class << self
+      def with_lock(name, **options, &block)
+        lock_key = build_lock_key(name, options)
+        adapter = resolve_adapter(options[:connection])
+        strategy = build_strategy(adapter, options)
+
+        result = strategy.execute(lock_key, &block)
+
+        if result.acquired?
+          result.value
+        else
+          false
+        end
+      end
+
+      def try_lock(name, **options, &block)
+        with_lock(name, **options.merge(timeout: 0), &block)
+      end
+
+      def lock!(name, **options, &block)
+        with_lock(name, **options.merge(on_conflict: :raise), &block)
+      end
+
+      def locked?(name, connection: nil)
+        lock_key = build_lock_key(name, {})
+        adapter = resolve_adapter(connection)
+        adapter.lock_exists?(lock_key)
+      end
+
+      def current_locks
+        Thread.current[:kannuki_locks] ||= Set.new
+      end
+
+      def holding_lock?(name)
+        lock_key = build_lock_key(name, {})
+        current_locks.include?(lock_key.to_s)
+      end
+
+      private
+
+      def build_lock_key(name, options)
+        case name
+        when LockKey
+          name
+        when ActiveRecord::Base
+          LockKey.from_record(name, scope: options[:scope])
+        else
+          LockKey.new(name, prefix: options[:prefix])
+        end
+      end
+
+      def resolve_adapter(connection)
+        return Adapters::Null.new if Kannuki.configuration.test_mode
+
+        conn = connection || ActiveRecord::Base.connection
+        adapter_name = conn.adapter_name.downcase
+
+        case adapter_name
+        when /postgresql/, /postgis/
+          Adapters::PostgreSQL.new(conn)
+        when /mysql/
+          Adapters::MySQL.new(conn)
+        else
+          Kannuki.configuration.logger.warn(
+            "[Kannuki] Unknown adapter '#{adapter_name}', falling back to Null adapter"
+          )
+          Adapters::Null.new(conn)
+        end
+      end
+
+      def build_strategy(adapter, options)
+        strategy_name = options.fetch(:strategy, Kannuki.configuration.default_strategy)
+        strategy_class = STRATEGY_MAP[strategy_name.to_sym]
+
+        raise ArgumentError, "Unknown strategy: #{strategy_name}" unless strategy_class
+
+        strategy_class.new(adapter, options)
+      end
+    end
+  end
+end

data/lib/kannuki/model_extension.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kannuki
+  module ModelExtension
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def kannuki(name, scope: nil, **options)
+        lock_name = name.to_s
+
+        define_method("with_#{lock_name}_lock") do |lock_options = {}, &block|
+          merged_options = options.merge(lock_options).merge(scope: scope)
+          lock_key = LockKey.from_record(self, scope: scope)
+          LockManager.with_lock(lock_key, **merged_options, &block)
+        end
+
+        define_method("try_#{lock_name}_lock") do |lock_options = {}, &block|
+          merged_options = options.merge(lock_options).merge(scope: scope, timeout: 0)
+          lock_key = LockKey.from_record(self, scope: scope)
+          LockManager.with_lock(lock_key, **merged_options, &block)
+        end
+
+        define_method("#{lock_name}_lock!") do |lock_options = {}, &block|
+          merged_options = options.merge(lock_options).merge(scope: scope, on_conflict: :raise)
+          lock_key = LockKey.from_record(self, scope: scope)
+          LockManager.with_lock(lock_key, **merged_options, &block)
+        end
+
+        define_method("#{lock_name}_locked?") do
+          lock_key = LockKey.from_record(self, scope: scope)
+          LockManager.locked?(lock_key)
+        end
+      end
+    end
+
+    def with_lock(name, **options, &block)
+      lock_key = LockKey.from_record(self, scope: options[:scope])
+      LockManager.with_lock("#{lock_key}/#{name}", **options, &block)
+    end
+  end
+end

data/lib/kannuki/railtie.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Kannuki
+  class Railtie < Rails::Railtie
+    initializer 'kannuki.configure_rails_initialization' do
+      ActiveSupport.on_load(:active_record) do
+        include Kannuki::ModelExtension
+      end
+
+      ActiveSupport.on_load(:active_job) do
+        include Kannuki::ActiveJobExtension
+      end
+    end
+
+    initializer 'kannuki.log_subscriber' do
+      if Kannuki.configuration.enable_instrumentation
+        ActiveSupport::Notifications.subscribe(/\.kannuki$/) do |name, start, finish, _id, payload|
+          event = name.sub('.kannuki', '')
+          duration = ((finish - start) * 1000).round(2)
+
+          message = case event
+                    when 'acquired'
+                      "Acquired lock: #{payload[:lock_key]} (#{duration}ms)"
+                    when 'released'
+                      "Released lock: #{payload[:lock_key]} (#{duration}ms)"
+                    when 'failed'
+                      "Failed to acquire lock: #{payload[:lock_key]} (reason: #{payload[:reason]})"
+                    when 'timeout'
+                      "Lock timeout: #{payload[:lock_key]} (timeout: #{payload[:timeout]}s)"
+                    when 'waiting'
+                      "Waiting for lock: #{payload[:lock_key]}"
+                    end
+
+          Kannuki.configuration.logger.debug("[Kannuki] #{message}") if message
+        end
+      end
+    end
+  end
+end

data/lib/kannuki/result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Kannuki
+  class Result
+    attr_reader :lock_key, :value, :duration, :adapter_name
+
+    def initialize(lock_key:, acquired:, value: nil, duration: nil, adapter_name: nil)
+      @lock_key = lock_key
+      @acquired = acquired
+      @value = value
+      @duration = duration
+      @adapter_name = adapter_name
+    end
+
+    def acquired?
+      @acquired
+    end
+
+    def success?
+      acquired?
+    end
+
+    def failed?
+      !acquired?
+    end
+
+    def to_s
+      if acquired?
+        "Lock acquired: #{lock_key} (#{duration&.round(3)}s)"
+      else
+        "Lock not acquired: #{lock_key}"
+      end
+    end
+  end
+end