hanikamu-operation 0.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docker-compose.yml

@@ -0,0 +1,22 @@
+version: "3"
+networks:
+  docker-compose-example-tier:
+    driver: bridge
+services:
+  redis:
+    image: redis:7-alpine
+    networks:
+      - docker-compose-example-tier
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      HISTFILE: /app/tmp/ash_history
+      REDIS_URL: redis://redis:6379/15
+    volumes:
+      - .:/app
+    networks:
+      - docker-compose-example-tier
+    depends_on:
+      - redis

data/lib/hanikamu/operation.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Hanikamu
+  # :nodoc:
+  # rubocop:disable Metrics/ClassLength
+  class Operation < Hanikamu::Service
+    include ActiveModel::Validations
+
+    Error = Class.new(Hanikamu::Service::Error)
+
+    # Error classes
+    class FormError < Hanikamu::Service::Error
+      attr_reader :form
+
+      def initialize(form)
+        @form = form
+        super(form.is_a?(String) ? form : form.errors.full_messages.join(", "))
+      end
+
+      def errors
+        return @form if @form.is_a?(String)
+
+        @form.errors
+      end
+    end
+
+    class GuardError < Hanikamu::Service::Error
+      attr_reader :guard
+
+      def initialize(guard)
+        @guard = guard
+        super(guard.is_a?(String) ? guard : guard.errors.full_messages.join(", "))
+      end
+
+      def errors
+        return @guard if @guard.is_a?(String)
+
+        @guard.errors
+      end
+    end
+
+    class MissingBlockError < Hanikamu::Service::Error
+    end
+
+    class ConfigurationError < StandardError; end
+
+    # Configuration
+    setting :redis_client
+    setting :mutex_expire_milliseconds, default: 1500
+    setting :redlock_retry_count, default: 6
+    setting :redlock_retry_delay, default: 500
+    setting :redlock_retry_jitter, default: 50
+    setting :redlock_timeout, default: 0.1
+    setting :whitelisted_errors, default: [].freeze, constructor: ->(value) { Array(value) }
+
+    # Override configure to cascade whitelisted_errors to Hanikamu::Service
+    def self.configure
+      super do |config|
+        yield(config) if block_given?
+
+        # Always include Redlock::LockError alongside user-provided errors
+        whitelisted_errors = ([Redlock::LockError] + Array(config.whitelisted_errors)).uniq
+
+        # Set on both Operation and Service configs because:
+        # - Operation.config is checked when .call is invoked on Operation subclasses
+        # - Service.config is set for consistency when directly calling Hanikamu::Service
+        config.whitelisted_errors = whitelisted_errors
+        Hanikamu::Service.config.whitelisted_errors = whitelisted_errors
+      end
+    end
+
+    class << self
+      def redis_lock
+        @redis_lock ||= begin
+          unless config.redis_client
+            raise(
+              ConfigurationError,
+              "Hanikamu::Operation.config.redis_client is not configured. " \
+              "Please set it in an initializer: Hanikamu::Operation.config.redis_client = your_redis_client"
+            )
+          end
+
+          Redlock::Client.new(
+            [config.redis_client],
+            retry_count: config.redlock_retry_count,
+            retry_delay: config.redlock_retry_delay,
+            retry_jitter: config.redlock_retry_jitter,
+            redis_timeout: config.redlock_timeout
+          )
+        end
+      end
+
+      # DSL methods
+      def within_mutex(lock_key, expire_milliseconds: nil)
+        @_mutex_lock_key = lock_key
+        @_mutex_expire_milliseconds = expire_milliseconds || Hanikamu::Operation.config.mutex_expire_milliseconds
+      end
+
+      def within_transaction(klass)
+        @_transaction_klass = klass
+      end
+
+      def block(bool)
+        @_block = bool
+      end
+
+      # Define guard validations using a block
+      # The block is evaluated in the context of a Guard class
+      # rubocop:disable Metrics/MethodLength
+      def guard(&block)
+        return unless block
+
+        # Thread-safe constant definition with mutex
+        @guard_definition_mutex ||= Mutex.new
+        @guard_definition_mutex.synchronize do
+          # Remove existing Guard constant if it exists to support Rails reloading
+          remove_const(:Guard) if const_defined?(:Guard, false)
+
+          # Create a new Guard class with ActiveModel validations
+          guard_class = Class.new do
+            include ActiveModel::Validations
+
+            attr_reader :operation
+            alias service operation
+
+            def initialize(operation)
+              @operation = operation
+            end
+
+            # Helper to delegate methods to operation/service
+            def self.delegates(*methods)
+              methods.each do |method_name|
+                define_method(method_name) do
+                  operation.public_send(method_name)
+                end
+              end
+            end
+
+            class_eval(&block)
+          end
+
+          const_set(:Guard, guard_class)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      attr_reader :_mutex_lock_key, :_mutex_expire_milliseconds, :_transaction_klass, :_block
+    end
+
+    def call!(&block)
+      validate_block!(&block)
+
+      within_mutex! do
+        validate!
+        guard!
+
+        within_transaction! do
+          block ? execute(&block) : execute
+        end
+      end
+    end
+
+    def validate_block!(&block)
+      return unless self.class._block
+
+      raise Hanikamu::Operation::MissingBlockError, "This service requires a block to be called" unless block
+    end
+
+    def within_mutex!(&)
+      return yield if _lock_key.nil?
+
+      Hanikamu::Operation.redis_lock.lock!(_lock_key, self.class._mutex_expire_milliseconds, &)
+    end
+
+    def _lock_key
+      return if self.class._mutex_lock_key.blank?
+
+      public_send(self.class._mutex_lock_key)
+    end
+
+    def within_transaction!(&)
+      return yield if transaction_class.nil?
+
+      transaction_class.transaction(&)
+    end
+
+    private
+
+    def transaction_class
+      return if self.class._transaction_klass.nil?
+      return ActiveRecord::Base if self.class._transaction_klass == :base
+
+      self.class._transaction_klass
+    end
+
+    def validate!
+      raise Hanikamu::Operation::FormError, self unless valid?
+    end
+
+    def guard!
+      # Check for Guard constant defined directly on this class, not inherited
+      return unless self.class.const_defined?(:Guard, false)
+
+      # Always create a fresh guard instance for this specific operation
+      # This prevents guard leakage when operations call other operations
+      @guard = self.class.const_get(:Guard).new(self)
+      raise_guard_error! unless @guard.valid?
+    end
+
+    def raise_guard_error!
+      raise Hanikamu::Operation::GuardError, @guard
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/hanikamu-operation.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "hanikamu/service"
+require "active_model"
+require "active_support/core_ext/object/blank"
+require "redlock"
+require "hanikamu/operation"

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: hanikamu-operation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicolai Seerup
+- Alejandro Jimenez
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-11-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: hanikamu-service
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: redlock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Ruby gem for building robust service operations with guard validations,
+  distributed mutex locks via Redlock, database transactions, and comprehensive error
+  handling. Thread-safe and designed for production Rails applications.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Dockerfile
+- LICENSE.txt
+- Makefile
+- README.md
+- Rakefile
+- docker-compose.yml
+- lib/hanikamu-operation.rb
+- lib/hanikamu/operation.rb
+homepage: https://github.com/Hanikamu/hanikamu-operation
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Hanikamu/hanikamu-operation
+  source_code_uri: https://github.com/Hanikamu/hanikamu-operation
+  changelog_uri: https://github.com/Hanikamu/hanikamu-operation/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Service objects with guards, distributed locks, and transactions
+test_files: []