Add optional operations/sidekiq async execution integration

.github/workflows/ci.yml

@@ -6,10 +6,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - { ruby: '2.7', rails: '5.2' }
-          - { ruby: '2.7', rails: '6.0' }
-          - { ruby: '3.0', rails: '6.1' }
-          - { ruby: '3.1', rails: '7.0' }
           - { ruby: '3.2', rails: '7.1' }
           - { ruby: '3.3', rails: '7.2' }
           - { ruby: '3.4', rails: '8.0' }
@@ -30,6 +26,6 @@ jobs:
     - uses: actions/checkout@v2
     - uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.7
+        ruby-version: '3.2'
         bundler-cache: true
     - run: bundle exec rubocop

.rubocop.yml

@@ -16,6 +16,6 @@ inherit_mode:
     - Exclude
 
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.2
   Exclude:
     - gemfiles/*

.rubocop_todo.yml

@@ -1,15 +1,14 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-09-27 05:26:10 UTC using RuboCop version 1.65.0.
+# on 2026-07-24 11:15:02 UTC using RuboCop version 1.88.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 3
-# Configuration parameters: EnforcedStyle, AllowedGems, Include.
+# Offense count: 6
+# Configuration parameters: EnforcedStyle, AllowedGems.
 # SupportedStyles: Gemfile, gems.rb, gemspec
-# Include: **/*.gemspec, **/Gemfile, **/gems.rb
 Gemspec/DevelopmentDependencies:
   Exclude:
     - 'operations.gemspec'
@@ -22,20 +21,21 @@ Metrics/AbcSize:
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 149
+  Max: 137
+
+# Offense count: 2
+# Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Exclude:
+    - 'lib/operations/components/idempotency.rb'
+    - 'lib/operations/form/base.rb'
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 144
+  Max: 141
 
 # Offense count: 3
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 7
-
-# Offense count: 1
-# Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
-RSpec/VerifiedDoubles:
-  Exclude:
-    - 'spec/operations/form_spec.rb'

Appraisals

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-%w[5.2 6.0 6.1 7.0 7.1 7.2 8.0].each do |version|
+%w[7.1 7.2 8.0].each do |version|
   appraise "rails.#{version}" do
     gem "activerecord", "~> #{version}.0"
     gem "activesupport", "~> #{version}.0"
-    gem "sqlite3", version > "7.0" ? "~> 2.1" : "~> 1.4"
+    gem "sqlite3", "~> 2.1"
   end
 end

CHANGELOG.md

@@ -4,10 +4,12 @@
 
 ### Added
 
+- Add optional `operations/sidekiq` integration for asynchronous operation execution: `Operations::Sidekiq::Convenience`, `Operations::Sidekiq::Command`, `Operations::Sidekiq::Job`, and the `Serializer`/`Deserializer` that encode rich argument types over Sidekiq.
 - Allow receiving params in preconditions. [\#56](https://github.com/BookingSync/operations/pull/56) ([pyromaniac](https://github.com/pyromaniac))
 
 ### Changes
 
+- Require Ruby >= 3.2 and drop Rails < 7.1 from the CI / appraisal matrix (the optional `operations/sidekiq` integration relies on a modern Sidekiq).
 - Changed `Operations::Command::OperationFailed#message` to include detailed error messages. [\#55](https://github.com/BookingSync/operations/pull/55) ([Azdaroth](https://github.com/Azdaroth))
 - Rename Operations::Form#model_name parameter to param_key and make it public preserving backwards compatibility. [\#52](https://github.com/BookingSync/operations/pull/52) ([pyromaniac](https://github.com/pyromaniac))
 

README.md

@@ -851,6 +851,83 @@ In this case, `Order::MarkAsCompleted.system.call(...)` will be used in, say, co
 
 `Operations::Convenience` is an optional module that contains helpers for simpler operation definitions. See module documentation for more details.
 
+### Asynchronous execution (Sidekiq)
+
+Any operation can be executed asynchronously via Sidekiq. This part of the
+framework is optional and must be required explicitly:
+
+```ruby
+require "operations/sidekiq"
+```
+
+It expects Sidekiq to be available in the host application. `Money` and
+GlobalID-able objects are serialized transparently when those libraries are
+loaded, but they are not hard dependencies of the gem.
+
+The simplest way to schedule an operation is `Operations::Sidekiq::Convenience`.
+It exposes a `<name>_async` (and `<name>_try_async`) counterpart for every
+singleton method that returns a command:
+
+```ruby
+class Rental::Create
+  extend Operations::Sidekiq::Convenience
+
+  def self.default
+    @default ||= Operations::Command.new(...)
+  end
+end
+
+# Enqueues a job that runs `Rental::Create.default.call!(params, **context)`
+Rental::Create.default_async.call(params, **context)
+
+# Same, but `try_call!` instead of `call!`
+Rental::Create.default_try_async.call(params, **context)
+
+# Scheduling / queue options
+Rental::Create.default_async.in(5.minutes).set(queue: :slow).call(params, **context)
+Rental::Create.default_async.at(1.hour.from_now).call(params, **context)
+```
+
+Default Sidekiq options, a custom job class, a default delay and a
+retries-exhausted callback can be configured per operation:
+
+```ruby
+class Rental::Create
+  extend Operations::Sidekiq::Convenience[
+    queue: :important,
+    on_retries_exhausted: Rental::NotifyFailure.default
+  ]
+  # ...
+end
+```
+
+`Operations::Sidekiq::Command` can also be used directly when you need more
+control, and `Operations::Sidekiq::Serializer` / `Operations::Sidekiq::Deserializer`
+handle encoding richer argument types (`Time`, `Date`, `BigDecimal`, `Symbol`,
+`Range`, `Module`/`Class`, `Dry::Struct`, `Money`, GlobalID-able objects and
+symbol-keyed hashes) that Sidekiq does not support out of the box.
+
+Jobs are executed by `Operations::Sidekiq::Job`. To add application-specific
+instrumentation (for example a Sentry scope or a transaction name) subclass it
+and override `#instrument`. Naming the subclass explicitly also keeps the
+enqueued job class name stable in Redis:
+
+```ruby
+class OperationJob < Operations::Sidekiq::Job
+  private
+
+  def instrument(container_class)
+    Sentry.configure_scope do |scope|
+      scope.set_transaction_name("Sidekiq/OperationJob/#{container_class}")
+      yield
+    end
+  end
+end
+
+# Point operations at your job class through the convenience configuration:
+extend Operations::Sidekiq::Convenience[job_class: OperationJob]
+```
+
 ### Form objects
 
 Form objects were refactored to be separate from Command. Please check [UPGRADING_FORMS.md](UPGRADING_FORMS.md) for more details.

lib/operations.rb

@@ -36,8 +36,8 @@ class Error < StandardError
   class << self
     attr_reader :default_config
 
-    def configure(configuration = nil, **options)
-      @default_config = (configuration || Configuration).new(**options)
+    def configure(configuration = nil, **)
+      @default_config = (configuration || Configuration).new(**)
     end
   end
 

lib/operations/command.rb

@@ -286,8 +286,8 @@ def possible(params = EMPTY_HASH, **context)
 
   # Returns boolean result instead of Operations::Result for validate method.
   # True on success and false on failure.
-  def valid?(*args, **kwargs)
-    validate(*args, **kwargs).success?
+  def valid?(*, **)
+    validate(*, **).success?
   end
 
   def to_hash

lib/operations/components/base.rb

@@ -24,10 +24,10 @@ class Operations::Components::Base
 
   private
 
-  def result(**options)
+  def result(**)
     ::Operations::Result.new(
       component: self.class.name.demodulize.underscore.to_sym,
-      **options
+      **
     )
   end
 

lib/operations/convenience.rb

@@ -64,10 +64,10 @@ def self.extended(mod)
     mod.extend Dry::Initializer
   end
 
-  def method_missing(name, *args, **kwargs, &block)
+  def method_missing(name, ...)
     name_without_suffix = name.to_s.delete_suffix("!").to_sym
     if name.to_s.end_with?("!") && respond_to?(name_without_suffix)
-      public_send(name_without_suffix, *args, **kwargs, &block).method(:call!)
+      public_send(name_without_suffix, ...).method(:call!)
     else
       super
     end
@@ -77,10 +77,10 @@ def respond_to_missing?(name, *)
     (name.to_s.end_with?("!") && respond_to?(name.to_s.delete_suffix("!").to_sym)) || super
   end
 
-  def contract(prefix = nil, from: OperationContract, &block)
+  def contract(prefix = nil, from: OperationContract, &)
     contract = Class.new(from)
     contract.config.messages.namespace = name.underscore
-    contract.class_eval(&block)
+    contract.class_eval(&)
     const_set(:"#{prefix.to_s.camelize}Contract", contract)
   end
 

lib/operations/form.rb

@@ -58,10 +58,10 @@ def self.inherited(subclass)
     option :base_class, type: Operations::Types::Class, default: proc { ::Operations::Form::Base }
   end)
 
-  def initialize(command, hydrator: nil, hydrators: [], model_name: nil, **options)
+  def initialize(command, hydrator: nil, hydrators: [], model_name: nil, **)
     hydrators.push(hydrator) if hydrator.present?
 
-    super(command, hydrators: hydrators, param_key: model_name, **options)
+    super(command, hydrators: hydrators, param_key: model_name, **)
   end
 
   def build(params = EMPTY_HASH, **context)

lib/operations/form/base.rb

@@ -60,8 +60,8 @@ def self.extended(base)
       end
     end
 
-    def attribute(name, **options)
-      attribute = Operations::Form::Attribute.new(name, **options)
+    def attribute(name, **)
+      attribute = Operations::Form::Attribute.new(name, **)
 
       self.attributes = attributes.merge(
         attribute.name => attribute
@@ -100,7 +100,7 @@ def type_for_attribute(name)
       self.class.attributes[name.to_sym].model_type
     end
 
-    def has_attribute?(name) # rubocop:disable Naming/PredicateName
+    def has_attribute?(name) # rubocop:disable Naming/PredicatePrefix
       self.class.attributes.key?(name.to_sym)
     end
 
@@ -117,17 +117,17 @@ def assigned_attributes
     end
 
     # For now we gracefully return nil for unknown methods
-    def method_missing(name, *args, **kwargs)
+    def method_missing(name, *, **)
       build_attribute_name = build_attribute_name(name)
       build_attribute = self.class.attributes[build_attribute_name]
       plural_build_attribute = self.class.attributes[build_attribute_name.to_s.pluralize.to_sym]
 
       if has_attribute?(name)
         read_attribute(name)
       elsif build_attribute&.form
-        build_attribute.form.new(*args, **kwargs)
+        build_attribute.form.new(*, **)
       elsif plural_build_attribute&.form
-        plural_build_attribute.form.new(*args, **kwargs)
+        plural_build_attribute.form.new(*, **)
       elsif operation_result
         operation_result.context[name]
       end

lib/operations/form/builder.rb

@@ -7,7 +7,7 @@
 class Operations::Form::Builder
   extend Dry::Initializer
 
-  NESTED_ATTRIBUTES_SUFFIX = %r{_attributes\z}.freeze
+  NESTED_ATTRIBUTES_SUFFIX = %r{_attributes\z}
 
   option :base_class, Operations::Types::Instance(Class)
 

lib/operations/result.rb

@@ -100,7 +100,7 @@ def to_hash(include_command: false)
 
   def errors_with_code?(name, *names)
     names = [name] + names
-    (errors.map { |error| error.meta[:code] } & names).present?
+    errors.map { |error| error.meta[:code] }.intersect?(names)
   end
 
   def context_to_hash