hanikamu-operation 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ff21656b7650f8c722178312ccfe54ed372086a165bcf13bd358f27d5880dd6
-  data.tar.gz: 2b22c2521306b5e64a07bc510631c088d84100298947248fd4c27d8fdda8f3f2
+  metadata.gz: b935969d9ffb9b34935f54e2f9d8adf907603906916a4c1b555499bd25e97f28
+  data.tar.gz: 2fada67131e16535eb5c6480c3a80999315efd0306753aae615a6a582d9cb43d
 SHA512:
-  metadata.gz: 33b2a094c24b6d9690e2666a60cf2453d93b2e73113a8d7a247a46f7a0bfeca661301f61f711c26fa94a911d55655b4c9b181930a9fcb5b8f4bbbc8e416db55e
-  data.tar.gz: 536172f90b5899eed4abf90c95984498dabc4695aa340109430b8be7835076fccca466fad27ce377e01e94c518105ca2e211fc496030560d765ddd2331f8163b
+  metadata.gz: cc5970b13fd6511a024b14071b273350604ef811f8bb944ca03f6839ed7f03051d106c63f550225f2b4de181d60c7698f545ecd1219faa1bb813aaa76be340a3
+  data.tar.gz: a691099d6fb2be177d4e19bcfff74e9760716465b2a9ceaff2fa0df33a63027e199377749e285f4a8b9cad02224c93e347e4b229eab60f159aa2d4bc5e585454

data/.cursor/rules/docker-environment.mdc

@@ -0,0 +1,30 @@
+---
+description: Development environment runs via docker-compose. Use Makefile targets instead of local commands.
+alwaysApply: true
+---
+
+# Docker-Compose Development Environment
+
+This project runs entirely inside Docker. Never run Ruby, Bundler, or Redis commands directly on the host.
+
+## Makefile Targets
+
+Use these instead of raw commands:
+
+| Task | Command |
+|------|---------|
+| Run tests | `make rspec` |
+| Run linter (auto-fix) | `make cops` |
+| Open a shell in the container | `make shell` |
+| Open an IRB console | `make console` |
+| Install gems & rebuild | `make bundle` |
+| Build the Docker image | `make build` |
+
+## Important
+
+- All `make` targets use `docker-compose run --rm app` under the hood.
+- Redis is provided as a linked service (`redis://redis:6379/15`) — no local Redis needed.
+- After changing the Gemfile or gemspec, run `make build` to reinstall dependencies.
+- Never use `bundle exec` directly on the host; always go through `make` or `make shell`.
+- Run `make` commands directly without `cd` — use the `working_directory` parameter instead.
+- After every code change, run `make rspec` to verify specs still pass before moving on.

data/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "rubyLsp.rubyVersionManager": {
+    "identifier": "mise"
+  }
+}

data/CHANGELOG.md

@@ -7,3 +7,10 @@
 ## [0.1.1] - 2025-11-26
 
 - Updated Gemfile.lock
+
+## [0.1.2] - 2025-12-05
+
+- **Breaking Change**: Minimum Ruby version is now 3.4.0
+- Removed `redis-client` as direct dependency (now transitive through `redlock`)
+- Updated CI to test only Ruby 3.4
+- Improved README with clearer FormError vs GuardError examples

data/Dockerfile

@@ -1,5 +1,5 @@
 # Base image
-FROM ruby:3.4.4
+FROM ruby:4.0
 
 WORKDIR "/app"
 

data/Makefile

@@ -14,6 +14,10 @@ console: ## build the image
 rspec: ## build the image
 	docker-compose run --rm app bash -c "bundle exec rspec"
 
+.PHONY: bundle
+bundle: ## install gems and rebuild image
+	docker-compose run --rm app bundle install
+	$(MAKE) build
 
 .PHONY: cops
 cops: ## build the image

data/README.md

@@ -8,9 +8,8 @@ A Ruby gem that extends [hanikamu-service](https://github.com/Hanikamu/hanikamu-
 
 1. [Why Hanikamu::Operation?](#why-hanikamuoperation)
 2. [Quick Start](#quick-start)
-3. [Installation](#installation)
-4. [Setup](#setup)
-5. [Usage](#usage)
+3. [Setup](#setup)
+4. [Usage](#usage)
    - [Basic Operation](#basic-operation)
    - [Distributed Locking](#distributed-locking-with-within_mutex)
    - [Database Transactions](#database-transactions-with-within_transaction)
@@ -18,14 +17,14 @@ A Ruby gem that extends [hanikamu-service](https://github.com/Hanikamu/hanikamu-
    - [Guard Conditions](#guard-conditions)
    - [Block Requirements](#block-requirements)
    - [Complete Example](#complete-example-combining-all-features)
-6. [Error Handling](#error-handling)
-7. [Best Practices](#best-practices)
-8. [Configuration Reference](#configuration-reference)
-9. [Testing](#testing)
-10. [Development](#development)
-11. [Contributing](#contributing)
-12. [License](#license)
-13. [Credits](#credits)
+5. [Error Handling](#error-handling)
+6. [Best Practices](#best-practices)
+7. [Configuration Reference](#configuration-reference)
+8. [Testing](#testing)
+9. [Development](#development)
+10. [Contributing](#contributing)
+11. [License](#license)
+12. [Credits](#credits)
 
 ## Why Hanikamu::Operation?
 
@@ -63,9 +62,11 @@ Use `Hanikamu::Operation` (instead of plain `Hanikamu::Service`) when your busin
 
 **1. Install the gem**
 
+Requires Ruby 3.4.0 or later.
+
 ```ruby
 # Gemfile
-gem 'hanikamu-operation', '~> 0.1.1'
+gem 'hanikamu-operation', '~> 0.2.0'
 ```
 
 ```bash
@@ -122,32 +123,19 @@ else
 end
 ```
 
-## Installation
-
-Add to your application's Gemfile:
-
-```ruby
-gem 'hanikamu-operation', '~> 0.1.1'
-```
-
-Then execute:
-
-```bash
-bundle install
-```
-
 ## Setup
 
-### Rails Application Setup Guide
+### Rails Application Setup
 
 Follow these steps to integrate Hanikamu::Operation into a Rails application:
 
 **Step 1: Add the gem to your Gemfile**
 
+Requires Ruby 3.4.0 or later.
+
 ```ruby
 # Gemfile
-gem 'hanikamu-operation', '~> 0.1.1'
-gem 'redis-client', '~> 0.22'  # Required for distributed locking
+gem 'hanikamu-operation', '~> 0.2.0'
 ```
 
 ```bash
@@ -214,68 +202,7 @@ brew services start redis
 REDIS_URL=redis://localhost:6379/0
 ```
 
-**Step 5: Create your first operation**
-
-```bash
-# Create operations directory
-mkdir -p app/operations/users
-```
-
-```ruby
-# app/operations/users/create_user_operation.rb
-module Users
-  class CreateUserOperation < Hanikamu::Operation
-    attribute :email, Types::String
-    attribute :password, Types::String
-
-    validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
-    validates :password, length: { minimum: 8 }
-
-    within_transaction(:base)
-
-    def execute
-      user = User.create!(
-        email: email,
-        password: password
-      )
-
-      response user: user
-    end
-  end
-end
-```
-
-**Step 6: Use in your controller**
-
-```ruby
-# app/controllers/users_controller.rb
-class UsersController < ApplicationController
-  def create
-    result = Users::CreateUserOperation.call(user_params)
-
-    if result.success?
-      user = result.success.user
-      render json: { user: user }, status: :created
-    else
-      error = result.failure
-      case error
-      when Hanikamu::Operation::FormError
-        render json: { errors: error.errors.full_messages }, status: :unprocessable_entity
-      else
-        render json: { error: error.message }, status: :internal_server_error
-      end
-    end
-  end
-
-  private
-
-  def user_params
-    params.require(:user).permit(:email, :password)
-  end
-end
-```
-
-**Step 7: Configure for production**
+**Step 5: Production configuration**
 
 Set your Redis URL in production (Heroku, AWS, etc.):
 
@@ -284,71 +211,11 @@ Set your Redis URL in production (Heroku, AWS, etc.):
 heroku addons:create heroku-redis:mini
 # REDIS_URL is automatically set
 
-# Or set manually
+# Or set manually for other providers
 heroku config:set REDIS_URL=redis://your-redis-host:6379/0
 ```
 
-### Detailed Configuration Options
-
-If you need more control, create a detailed initializer:
-
-```ruby
-# config/initializers/hanikamu_operation.rb
-require 'redis-client'
-
-Hanikamu::Operation.configure do |config|
-  # Required: Redis client for distributed locking
-  config.redis_client = RedisClient.new(
-    url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0'),
-    reconnect_attempts: 3,
-    timeout: 1.0
-  )
-
-  # Optional: Customize Redlock settings (these are the defaults)
-  config.mutex_expire_milliseconds = 1500  # Lock TTL
-  config.redlock_retry_count = 6           # Number of retry attempts
-  config.redlock_retry_delay = 500         # Milliseconds between retries
-  config.redlock_retry_jitter = 50         # Random jitter to prevent thundering herd
-  config.redlock_timeout = 0.1             # Redis command timeout
-
-  # Optional: Add errors to whitelist (Redlock::LockError is always included by default)
-  config.whitelisted_errors = [CustomBusinessError]
-end
-```
-
-### Redis Setup by Environment
-
-**For Development (Docker Compose)**:
-
-```yaml
-# docker-compose.yml
-services:
-  redis:
-    image: redis:7-alpine
-    volumes:
-      - redis_data:/data
-    networks:
-      - app_network
-
-  app:
-    # ... your app config
-    environment:
-      REDIS_URL: redis://redis:6379/0
-    depends_on:
-      - redis
-    networks:
-      - app_network
-
-volumes:
-  redis_data:
-
-networks:
-  app_network:
-```
-
-**For Production**:
-
-Use a managed Redis service (AWS ElastiCache, Heroku Redis, Redis Labs, etc.) and set the `REDIS_URL` environment variable.
+For advanced configuration options, see the [Configuration Reference](#configuration-reference) section below.
 
 ## Usage
 
@@ -465,6 +332,38 @@ def mutex_lock
 end
 ```
 
+**Conditional locking with `:if` / `:unless`**:
+
+When the lock key is derived from an optional attribute, a `nil` value produces a degenerate shared key (e.g., `"Order$"`) that serializes all operations. Use `:if` or `:unless` to skip the Redis lock entirely when it isn't needed:
+
+```ruby
+class ProcessOrderOperation < Hanikamu::Operation
+  attribute :order_id?, Types::Params::Integer.optional
+
+  within_mutex(:mutex_lock, if: -> { order_id.present? })
+
+  def execute
+    # ...
+    response(successful: true)
+  end
+
+  def mutex_lock
+    "Order$#{order_id}"
+  end
+end
+```
+
+- When `order_id` is present, the lock is acquired on `"Order$42"` as usual.
+- When `order_id` is `nil`, no Redis round-trip occurs — the operation runs without a lock.
+
+The `:unless` option works inversely:
+
+```ruby
+within_mutex(:mutex_lock, unless: -> { order_id.nil? })
+```
+
+The lambda is evaluated via `instance_exec` on the operation instance, so it has access to all attributes and methods. Providing both `:if` and `:unless` raises `ArgumentError`.
+
 ### Database Transactions with `within_transaction`
 
 Ensure multiple database changes succeed or fail together atomically. If any database operation raises an exception, all changes are rolled back.
@@ -764,52 +663,68 @@ Operations validate at three distinct levels, each serving a specific purpose:
 
 ### FormError vs GuardError: Practical Examples
 
-**FormError Example** - Invalid or incorrect input arguments:
+Here's a complete example demonstrating the difference between form validations and guard conditions:
 
 ```ruby
-# Attempting to create a user with invalid inputs
-result = Users::CreateUserOperation.call(
-  email: "taken@example.com",
-  password: "short",
-  password_confirmation: "wrong"
-)
-# => Failure(#<Hanikamu::Operation::FormError: 
-#      Email has been taken, 
-#      Password is too short, 
-#      Password confirmation does not match password>)
-
-# Correcting the arguments allows success
-result = Users::CreateUserOperation.call(
-  email: "unique@example.com",
-  password: "securePassword123!",
-  password_confirmation: "securePassword123!"
-)
-# => Success(#<struct user=#<User id: 46, email: "unique@example.com">>)
+class TestOperation < Hanikamu::Operation
+  attribute :sentence, Types::String
+
+  # Form validation - checks input value format/content
+  validates :sentence, presence: true
+  validates :sentence, exclusion: { in: ["form_error"], message: "is not allowed" }
+
+  # Guard validation - checks business rules/state
+  guard do
+    delegates :sentence
+
+    validates :sentence, exclusion: { in: ["guard_error"], message: "is not allowed" }
+  end
+
+  within_mutex(:mutex_lock)
+  within_transaction(:base)
+
+  def execute
+    response(message: sentence.reverse)
+  end
+
+  def mutex_lock
+    self.class.name
+  end
+end
 ```
 
-**GuardError Example** - Valid arguments but invalid system state:
+**FormError Example** - Invalid input value triggers form validation:
 
 ```ruby
-# First attempt succeeds
-result = Users::CompleteUserOperation.call!(user_id: 46)
-# => Success(#<struct user=#<User id: 46, completed_at: "2025-11-26">>)
+# Form validation fails - input itself is invalid
+result = TestOperation.call(sentence: "form_error")
+# => Failure(#<Hanikamu::Operation::FormError: Sentence is not allowed>)
+
+# Correcting the input allows the operation to proceed
+result = TestOperation.call(sentence: "hello world")
+# => Success(#<struct message="dlrow olleh">)
+```
 
-# Second attempt fails due to state, even with valid arguments
-result = Users::CompleteUserOperation.call!(user_id: 46)
-# => Failure(#<Hanikamu::Operation::GuardError: User has already been completed>)
+**GuardError Example** - Valid input but business rule violated:
 
-# The arguments are still correct, but the operation cannot proceed
-# because the user's state has changed
+```ruby
+# Input passes form validation, but guard fails
+result = TestOperation.call(sentence: "guard_error")
+# => Failure(#<Hanikamu::Operation::GuardError: Sentence is not allowed>)
+
+# The input format is valid, but the business rule prevents execution
 ```
 
 **Type Error Example** - Wrong argument type:
 
 ```ruby
-# Passing wrong type raises immediately
-Users::CompleteUserOperation.call!(user_id: "not-a-number")
+# Passing wrong type raises immediately before any validations
+TestOperation.call!(sentence: 123)
 # => Raises Dry::Struct::Error
 ```
 
+**Key Insight**: Form validations check if the *input is correct*, while guards check if the *operation can proceed* given the current state.
+
 ### Using `.call!` (Raises Exceptions)
 
 ```ruby

data/lib/hanikamu/operation.rb

@@ -6,7 +6,7 @@ module Hanikamu
   class Operation < Hanikamu::Service
     include ActiveModel::Validations
 
-    Error = Class.new(Hanikamu::Service::Error)
+    class Error < Hanikamu::Service::Error; end
 
     # Error classes
     class FormError < Hanikamu::Service::Error
@@ -91,9 +91,15 @@ module Hanikamu
       end
 
       # DSL methods
-      def within_mutex(lock_key, expire_milliseconds: nil)
+      def within_mutex(lock_key, expire_milliseconds: nil, if: nil, unless: nil)
+        if_condition = binding.local_variable_get(:if)
+        unless_condition = binding.local_variable_get(:unless)
+        validate_mutex_conditions!(if_condition, unless_condition)
+
         @_mutex_lock_key = lock_key
         @_mutex_expire_milliseconds = expire_milliseconds || Hanikamu::Operation.config.mutex_expire_milliseconds
+        @_mutex_if_condition = if_condition
+        @_mutex_unless_condition = unless_condition
       end
 
       def within_transaction(klass)
@@ -144,7 +150,24 @@ module Hanikamu
       end
       # rubocop:enable Metrics/MethodLength
 
-      attr_reader :_mutex_lock_key, :_mutex_expire_milliseconds, :_transaction_klass, :_block
+      attr_reader :_mutex_lock_key, :_mutex_expire_milliseconds, :_mutex_if_condition, :_mutex_unless_condition,
+                  :_transaction_klass, :_block
+
+      private
+
+      def validate_mutex_conditions!(if_condition, unless_condition)
+        if if_condition && unless_condition
+          raise ArgumentError, "Cannot specify both :if and :unless conditions for within_mutex"
+        end
+
+        if if_condition && !if_condition.respond_to?(:call)
+          raise ArgumentError, "within_mutex :if condition must be a callable (e.g. a Proc or lambda)"
+        end
+
+        return unless unless_condition && !unless_condition.respond_to?(:call)
+
+        raise ArgumentError, "within_mutex :unless condition must be a callable (e.g. a Proc or lambda)"
+      end
     end
 
     def call!(&block)
@@ -167,15 +190,11 @@ module Hanikamu
     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?
+      return yield if self.class._mutex_lock_key.blank?
+      return yield unless _should_apply_mutex?
 
-      public_send(self.class._mutex_lock_key)
+      lock_key = public_send(self.class._mutex_lock_key)
+      Hanikamu::Operation.redis_lock.lock!(lock_key, self.class._mutex_expire_milliseconds, &)
     end
 
     def within_transaction!(&)
@@ -186,6 +205,13 @@ module Hanikamu
 
     private
 
+    def _should_apply_mutex?
+      return false if self.class._mutex_if_condition && !instance_exec(&self.class._mutex_if_condition)
+      return false if self.class._mutex_unless_condition && instance_exec(&self.class._mutex_unless_condition)
+
+      true
+    end
+
     def transaction_class
       return if self.class._transaction_klass.nil?
       return ActiveRecord::Base if self.class._transaction_klass == :base

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hanikamu-operation
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Nicolai Seerup
 - Alejandro Jimenez
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -102,11 +101,12 @@ dependencies:
 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:
+- ".cursor/rules/docker-environment.mdc"
+- ".vscode/settings.json"
 - CHANGELOG.md
 - Dockerfile
 - LICENSE.txt
@@ -124,7 +124,6 @@ metadata:
   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
@@ -132,15 +131,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Service objects with guards, distributed locks, and transactions
 test_files: []