cmdx 1.11.0 → 1.13.0

data/examples/flipper_feature_flags.md

@@ -0,0 +1,50 @@
+# Flipper Feature Flags
+
+Control task execution based on Flipper feature flags.
+
+<https://github.com/flippercloud/flipper>
+
+### Setup
+
+```ruby
+# lib/cmdx_flipper_middleware.rb
+class CmdxFlipperMiddleware
+  def self.call(task, **options, &)
+    feature_name = options.fetch(:feature)
+    actor = options.fetch(:actor, -> { task.context[:user] })
+
+    # Resolve actor if it's a proc
+    actor = actor.call if actor.respond_to?(:call)
+
+    if Flipper.enabled?(feature_name, actor)
+      yield
+    else
+      # Option 1: Skip the task
+      task.skip!("Feature #{feature_name} is disabled")
+
+      # Option 2: Fail the task
+      # task.fail!("Feature #{feature_name} is disabled")
+    end
+  end
+end
+```
+
+### Usage
+
+```ruby
+class NewFeatureTask < CMDx::Task
+  # Execute only if :new_feature is enabled for the user in context
+  register :middleware, CmdxFlipperMiddleware,
+    feature: :new_feature
+
+  # Customize the actor resolution
+  register :middleware, CmdxFlipperMiddleware,
+    feature: :beta_access,
+    actor: -> { task.context[:company] }
+
+  def work
+    # ...
+  end
+end
+```
+

data/examples/redis_idempotency.md

@@ -0,0 +1,71 @@
+# Redis Idempotency
+
+Ensure tasks are executed exactly once using Redis to store execution state. This is critical for non-idempotent operations like charging a credit card or sending an email.
+
+### Setup
+
+```ruby
+# lib/cmdx_redis_idempotency_middleware.rb
+class CmdxRedisIdempotencyMiddleware
+  def self.call(task, **options, &block)
+    key = generate_key(task, options[:key])
+    ttl = options[:ttl] || 5.minutes.to_i
+
+    # Attempt to lock the key
+    if Redis.current.set(key, "processing", nx: true, ex: ttl)
+      begin
+        block.call.tap |result|
+          Redis.current.set(key, result.status, xx: true, ex: ttl)
+        end
+      rescue => e
+        Redis.current.del(key)
+        raise(e)
+      end
+    else
+      # Key exists, handle duplicate
+      status = Redis.current.get(key)
+
+      if status == "processing"
+        task.result.tap { |r| r.skip!("Duplicate request: currently processing", halt: true) }
+      else
+        task.result.tap { |r| r.skip!("Duplicate request: already processed (#{status})", halt: true) }
+      end
+    end
+  end
+
+  def self.generate_key(task, key_gen)
+    id = if key_gen.respond_to?(:call)
+           key_gen.call(task)
+         elsif key_gen.is_a?(Symbol)
+           task.send(key_gen)
+         else
+           task.context[:idempotency_key]
+         end
+
+    "cmdx:idempotency:#{task.class.name}:#{id}"
+  end
+end
+```
+
+### Usage
+
+```ruby
+class ChargeCustomer < CMDx::Task
+  # Use context[:payment_id] as the unique key
+  register :middleware, CmdxIdempotencyMiddleware,
+    key: ->(t) { t.context[:payment_id] }
+
+  def work
+    # Charge logic...
+  end
+end
+
+# First run: Executes
+ChargeCustomer.call(payment_id: "123")
+# => Success
+
+# Second run: Skips
+ChargeCustomer.call(payment_id: "123")
+# => Skipped (reason: "Duplicate request: already processed (success)")
+```
+

data/examples/sentry_error_tracking.md

@@ -0,0 +1,46 @@
+# Sentry Error Tracking
+
+Report unhandled exceptions and unexpected task failures to Sentry with detailed context.
+
+<https://github.com/getsentry/sentry-ruby>
+
+### Setup
+
+```ruby
+# lib/cmdx_sentry_middleware.rb
+class CmdxSentryMiddleware
+  def self.call(task, **options, &)
+    Sentry.with_scope do |scope|
+      scope.set_tags(task: task.class.name)
+      scope.set_context(:user, Current.user.sentry_attributes)
+
+      yield.tap do |result|
+        # Optional: Report logical failures if needed
+        if Array(options[:report_on]).include?(result.status)
+          Sentry.capture_message("Task #{result.status}: #{result.reason}", level: :warning)
+        end
+      end
+    end
+  rescue => e
+    Sentry.capture_exception(e)
+    raise(e) # Re-raise to let the task handle the error or bubble up
+  end
+end
+```
+
+### Usage
+
+```ruby
+class ProcessPayment < CMDx::Task
+  # Report exceptions only
+  register :middleware, CmdxSentryMiddleware
+
+  # Report exceptions AND logical failures (result.failure?)
+  register :middleware, CmdxSentryMiddleware, report_on: %w[failed skipped]
+
+  def work
+    # ...
+  end
+end
+```
+

data/lib/cmdx/attribute.rb

@@ -112,6 +112,7 @@ module CMDx
       #
       # @param names [Array<Symbol, String>] The names of the attributes to create
       # @param options [Hash] Configuration options for the attributes
+      # @option options [Object] :* Any attribute configuration option
       #
       # @yield [self] Block to configure nested attributes
       #
@@ -137,6 +138,7 @@ module CMDx
       #
       # @param names [Array<Symbol, String>] The names of the attributes to create
       # @param options [Hash] Configuration options for the attributes
+      # @option options [Object] :* Any attribute configuration option
       #
       # @yield [self] Block to configure nested attributes
       #
@@ -154,6 +156,7 @@ module CMDx
       #
       # @param names [Array<Symbol, String>] The names of the attributes to create
       # @param options [Hash] Configuration options for the attributes
+      # @option options [Object] :* Any attribute configuration option
       #
       # @yield [self] Block to configure nested attributes
       #
@@ -238,6 +241,7 @@ module CMDx
     #
     # @param names [Array<Symbol, String>] The names of the child attributes
     # @param options [Hash] Configuration options for the child attributes
+    # @option options [Object] :* Any attribute configuration option
     #
     # @yield [self] Block to configure the child attributes
     #
@@ -257,6 +261,7 @@ module CMDx
     #
     # @param names [Array<Symbol, String>] The names of the optional child attributes
     # @param options [Hash] Configuration options for the child attributes
+    # @option options [Object] :* Any attribute configuration option
     #
     # @yield [self] Block to configure the child attributes
     #
@@ -274,6 +279,7 @@ module CMDx
     #
     # @param names [Array<Symbol, String>] The names of the required child attributes
     # @param options [Hash] Configuration options for the child attributes
+    # @option options [Object] :* Any attribute configuration option
     #
     # @yield [self] Block to configure the child attributes
     #

data/lib/cmdx/callback_registry.rb

@@ -53,9 +53,9 @@ module CMDx
     # @param type [Symbol] The callback type from TYPES
     # @param callables [Array<#call>] Callable objects to register
     # @param options [Hash] Options to pass to the callback
+    # @param block [Proc] Optional block to register as a callable
     # @option options [Hash] :if Condition hash for conditional execution
     # @option options [Hash] :unless Inverse condition hash for conditional execution
-    # @param block [Proc] Optional block to register as a callable
     #
     # @return [CallbackRegistry] self for method chaining
     #
@@ -83,6 +83,7 @@ module CMDx
     # @param callables [Array<#call>] Callable objects to remove
     # @param options [Hash] Options that were used during registration
     # @param block [Proc] Optional block to remove
+    # @option options [Object] :* Any option key-value pairs
     #
     # @return [CallbackRegistry] self for method chaining
     #

data/lib/cmdx/chain.rb

@@ -39,9 +39,10 @@ module CMDx
     # @return [Chain] A new chain instance
     #
     # @rbs () -> void
-    def initialize
+    def initialize(dry_run: false)
       @id = Identifier.generate
       @results = []
+      @dry_run = !!dry_run
     end
 
     class << self
@@ -102,24 +103,35 @@ module CMDx
       #   puts "Chain size: #{chain.size}"
       #
       # @rbs (Result result) -> Chain
-      def build(result)
+      def build(result, dry_run: false)
         raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
-        self.current ||= new
+        self.current ||= new(dry_run:)
         current.results << result
         current
       end
 
     end
 
-    # Converts the chain to a hash representation.
+    # Returns whether the chain is running in dry-run mode.
     #
-    # @return [Hash] Hash containing chain id and serialized results
+    # @return [Boolean] Whether the chain is running in dry-run mode
     #
-    # @option return [String] :id The chain identifier
+    # @example
+    #   chain.dry_run? # => true
     #
+    # @rbs () -> bool
+    def dry_run?
+      !!@dry_run
+    end
+
+    # Converts the chain to a hash representation.
+    #
+    # @option return [String] :id The chain identifier
     # @option return [Array<Hash>] :results Array of result hashes
     #
+    # @return [Hash] Hash containing chain id and serialized results
+    #
     # @example
     #   chain_hash = chain.to_h
     #   puts chain_hash[:id]
@@ -128,7 +140,8 @@ module CMDx
     # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
-        id: id,
+        id:,
+        dry_run: dry_run?,
         results: results.map(&:to_h)
       }
     end

data/lib/cmdx/coercion_registry.rb

@@ -20,7 +20,7 @@ module CMDx
 
     # Initialize a new coercion registry.
     #
-    # @param registry [Hash<Symbol, Class>, nil] optional initial registry hash
+    # @param registry [Hash{Symbol => Class}, nil] optional initial registry hash
     #
     # @example
     #   registry = CoercionRegistry.new
@@ -95,6 +95,7 @@ module CMDx
     # @param task [Object] the task context for the coercion
     # @param value [Object] the value to coerce
     # @param options [Hash] additional options for the coercion
+    # @option options [Object] :* Any coercion option key-value pairs
     #
     # @return [Object] the coerced value
     #

data/lib/cmdx/coercions/boolean.rb

@@ -11,10 +11,10 @@ module CMDx
       extend self
 
       # @rbs FALSEY: Regexp
-      FALSEY = /^(false|f|no|n|0)$/i
+      FALSEY = /\A(false|f|no|n|0)\z/i
 
       # @rbs TRUTHY: Regexp
-      TRUTHY = /^(true|t|yes|y|1)$/i
+      TRUTHY = /\A(true|t|yes|y|1)\z/i
 
       # Converts a value to a Boolean
       #
@@ -40,7 +40,7 @@ module CMDx
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> bool
       def call(value, options = {})
-        case value.to_s.downcase
+        case value.to_s
         when FALSEY then false
         when TRUTHY then true
         else

data/lib/cmdx/coercions/complex.rb

@@ -14,6 +14,7 @@ module CMDx
       #
       # @param value [Object] The value to convert to Complex
       # @param options [Hash] Optional configuration parameters (currently unused)
+      # @option options [Object] :* Any configuration option (unused)
       #
       # @return [Complex] The converted Complex number value
       #

data/lib/cmdx/coercions/string.rb

@@ -15,6 +15,7 @@ module CMDx
       #
       # @param value [Object] The value to coerce to a string
       # @param options [Hash] Optional configuration parameters (unused in this coercion)
+      # @option options [Object] :* Any configuration option (unused)
       #
       # @return [String] The coerced string value
       #

data/lib/cmdx/coercions/symbol.rb

@@ -15,6 +15,7 @@ module CMDx
       #
       # @param value [Object] The value to coerce to a symbol
       # @param options [Hash] Optional configuration parameters (unused in this coercion)
+      # @option options [Object] :* Any configuration option (unused)
       #
       # @return [Symbol] The coerced symbol value
       #

data/lib/cmdx/configuration.rb

@@ -160,7 +160,7 @@ module CMDx
 
     # Converts the configuration to a hash representation.
     #
-    # @return [Hash<Symbol, Object>] hash containing all configuration values
+    # @return [Hash{Symbol => Object}] hash containing all configuration values
     #
     # @example
     #   config = Configuration.new
@@ -205,8 +205,6 @@ module CMDx
 
   # Configures CMDx using a block that receives the configuration instance.
   #
-  # @param block [Proc] the configuration block
-  #
   # @yield [Configuration] the configuration instance to configure
   #
   # @return [Configuration] the configured configuration instance

data/lib/cmdx/context.rb

@@ -109,7 +109,6 @@ module CMDx
     # Fetches a value from the context by key, with optional default value.
     #
     # @param key [String, Symbol] the key to fetch
-    # @param default [Object] the default value if key is not found
     #
     # @yield [key] a block to compute the default value
     #
@@ -165,6 +164,7 @@ module CMDx
       args.to_h.each { |key, value| self[key.to_sym] = value }
       self
     end
+    alias merge merge!
 
     # Deletes a key-value pair from the context.
     #
@@ -183,6 +183,7 @@ module CMDx
     def delete!(key, &)
       table.delete(key.to_sym, &)
     end
+    alias delete delete!
 
     # Compares this context with another object for equality.
     #
@@ -255,6 +256,7 @@ module CMDx
     # @param method_name [Symbol] the method name that was called
     # @param args [Array<Object>] arguments passed to the method
     # @param _kwargs [Hash] keyword arguments (unused)
+    # @option _kwargs [Object] :* Any keyword arguments (unused)
     #
     # @yield [Object] optional block
     #
@@ -263,7 +265,8 @@ module CMDx
     # @rbs (Symbol method_name, *untyped args, **untyped _kwargs) ?{ () -> untyped } -> untyped
     def method_missing(method_name, *args, **_kwargs, &)
       fetch(method_name) do
-        store(method_name[0..-2], args.first) if method_name.end_with?("=")
+        str_name = method_name.to_s
+        store(str_name.chop, args.first) if str_name.end_with?("=")
       end
     end
 

data/lib/cmdx/executor.rb

@@ -8,6 +8,8 @@ module CMDx
   # and proper error handling for different types of failures.
   class Executor
 
+    extend Forwardable
+
     # Returns the task being executed.
     #
     # @return [Task] The task instance
@@ -18,6 +20,8 @@ module CMDx
     # @rbs @task: Task
     attr_reader :task
 
+    def_delegators :task, :result
+
     # @param task [CMDx::Task] The task to execute
     #
     # @return [CMDx::Executor] A new executor instance
@@ -65,13 +69,13 @@ module CMDx
       rescue UndefinedMethodError => e
         raise(e) # No need to clear the Chain since exception is not being re-raised
       rescue Fault => e
-        task.result.throw!(e.result, halt: false, cause: e)
+        result.throw!(e.result, halt: false, cause: e)
       rescue StandardError => e
         retry if retry_execution?(e)
-        task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
         task.class.settings[:exception_handler]&.call(task, e)
       ensure
-        task.result.executed!
+        result.executed!
         post_execution!
       end
 
@@ -96,14 +100,14 @@ module CMDx
       rescue UndefinedMethodError => e
         raise_exception(e)
       rescue Fault => e
-        task.result.throw!(e.result, halt: false, cause: e)
+        result.throw!(e.result, halt: false, cause: e)
         halt_execution?(e) ? raise_exception(e) : post_execution!
       rescue StandardError => e
         retry if retry_execution?(e)
-        task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
         raise_exception(e)
       else
-        task.result.executed!
+        result.executed!
         post_execution!
       end
 
@@ -137,14 +141,14 @@ module CMDx
       available_retries = (task.class.settings[:retries] || 0).to_i
       return false unless available_retries.positive?
 
-      current_retries = (task.result.metadata[:retries] ||= 0).to_i
+      current_retries = (result.metadata[:retries] ||= 0).to_i
       remaining_retries = available_retries - current_retries
       return false unless remaining_retries.positive?
 
       exceptions = Array(task.class.settings[:retry_on] || StandardError)
       return false unless exceptions.any? { |e| exception.class <= e }
 
-      task.result.metadata[:retries] += 1
+      result.metadata[:retries] += 1
 
       task.logger.warn do
         reason = "[#{exception.class}] #{exception.message}"
@@ -208,7 +212,7 @@ module CMDx
       task.class.settings[:attributes].define_and_verify(task)
       return if task.errors.empty?
 
-      task.result.fail!(
+      result.fail!(
         Locale.t("cmdx.faults.invalid"),
         errors: {
           full_message: task.errors.to_s,
@@ -223,7 +227,7 @@ module CMDx
     def execution!
       invoke_callbacks(:before_execution)
 
-      task.result.executing!
+      result.executing!
       task.work
     end
 
@@ -231,12 +235,12 @@ module CMDx
     #
     # @rbs () -> void
     def post_execution!
-      invoke_callbacks(:"on_#{task.result.state}")
-      invoke_callbacks(:on_executed) if task.result.executed?
+      invoke_callbacks(:"on_#{result.state}")
+      invoke_callbacks(:on_executed) if result.executed?
 
-      invoke_callbacks(:"on_#{task.result.status}")
-      invoke_callbacks(:on_good) if task.result.good?
-      invoke_callbacks(:on_bad) if task.result.bad?
+      invoke_callbacks(:"on_#{result.status}")
+      invoke_callbacks(:on_good) if result.good?
+      invoke_callbacks(:on_bad) if result.bad?
     end
 
     # Finalizes execution by freezing the task, logging results, and rolling back work.
@@ -246,26 +250,25 @@ module CMDx
       log_execution!
       log_backtrace! if task.class.settings[:backtrace]
 
+      rollback_execution!
       freeze_execution!
       clear_chain!
-
-      rollback_execution!
     end
 
     # Logs the execution result at the configured log level.
     #
     # @rbs () -> void
     def log_execution!
-      task.logger.info { task.result.to_h }
+      task.logger.info { result.to_h }
     end
 
     # Logs the backtrace of the exception if the task failed.
     #
     # @rbs () -> void
     def log_backtrace!
-      return unless task.result.failed?
+      return unless result.failed?
 
-      exception = task.result.caused_failure.cause
+      exception = result.caused_failure.cause
       return if exception.is_a?(Fault)
 
       task.logger.error do
@@ -287,11 +290,11 @@ module CMDx
       return if Coercions::Boolean.call(skip_freezing)
 
       task.freeze
-      task.result.freeze
+      result.freeze
 
       # Freezing the context and chain can only be done
       # once the outer-most task has completed.
-      return unless task.result.index.zero?
+      return unless result.index.zero?
 
       task.context.freeze
       task.chain.freeze
@@ -301,7 +304,7 @@ module CMDx
     #
     # @rbs () -> void
     def clear_chain!
-      return unless task.result.index.zero?
+      return unless result.index.zero?
 
       Chain.clear
     end
@@ -310,12 +313,14 @@ module CMDx
     #
     # @rbs () -> void
     def rollback_execution!
+      return if result.rolled_back?
       return unless task.respond_to?(:rollback)
 
       statuses = task.class.settings[:rollback_on]
       statuses = Array(statuses).map(&:to_s).uniq
-      return unless statuses.include?(task.result.status)
+      return unless statuses.include?(result.status)
 
+      result.rolled_back!
       task.rollback
     end
 

data/lib/cmdx/middleware_registry.rb

@@ -109,6 +109,7 @@ module CMDx
     #
     # @param index [Integer] Current middleware index in the chain
     # @param task [Object] The task object being processed
+    # @param block [Proc] Block to execute after middleware processing
     #
     # @yield [task] Block to execute after middleware processing
     # @yieldparam task [Object] The processed task object