cmdx 1.9.1 → 1.10.0

data/README.md

@@ -6,7 +6,7 @@
 
   Build business logic that’s powerful, predictable, and maintainable.
 
-  [Documentation](https://drexed.github.io/cmdx) · [Changelog](./CHANGELOG.md) · [Report Bug](https://github.com/drexed/cmdx/issues) · [Request Feature](https://github.com/drexed/cmdx/issues)
+  [Documentation](https://drexed.github.io/cmdx) · [Changelog](./CHANGELOG.md) · [Report Bug](https://github.com/drexed/cmdx/issues) · [Request Feature](https://github.com/drexed/cmdx/issues) · [LLM.md](https://raw.githubusercontent.com/drexed/cmdx/refs/heads/main/LLM.md)
 
   <img alt="Version" src="https://img.shields.io/gem/v/cmdx">
   <img alt="Build" src="https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg">

data/docs/basics/setup.md

@@ -24,6 +24,22 @@ end
 IncompleteTask.execute #=> raises CMDx::UndefinedMethodError
 ```
 
+## Rollback
+
+Undo any operations linked to the given status, helping to restore a pristine state.
+
+```ruby
+class ValidateDocument < CMDx::Task
+  def work
+    # Your logic here...
+  end
+
+  def rollback
+    # Your undo logic...
+  end
+end
+```
+
 ## Inheritance
 
 Share configuration across tasks using inheritance:
@@ -65,3 +81,4 @@ Tasks follow a predictable execution pattern:
 | **Execution** | `executing` | `success`/`failed`/`skipped` | `work` method runs |
 | **Completion** | `executed` | `success`/`failed`/`skipped` | Result finalized |
 | **Freezing** | `executed` | `success`/`failed`/`skipped` | Task becomes immutable |
+| **Rollback** | `executed` | `failed`/`skipped` | Work undone |

data/docs/callbacks.md

@@ -73,7 +73,7 @@ end
 
 ### Class or Module
 
-Implement reusable callback logic in dedicated classes:
+Implement reusable callback logic in dedicated modules and classes:
 
 ```ruby
 class BookingConfirmationCallback

data/docs/getting_started.md

@@ -78,6 +78,16 @@ CMDx.configure do |config|
 end
 ```
 
+### Rollback
+
+Control when a `rollback` of task execution is called.
+
+```ruby
+CMDx.configure do |config|
+  config.rollback_on = ["failed"] # String or Array[String]
+end
+```
+
 ### Backtraces
 
 Enable detailed backtraces for non-fault exceptions to improve debugging. Optionally clean up stack traces to remove framework noise.
@@ -258,7 +268,8 @@ class GenerateInvoice < CMDx::Task
     deprecated: true,                            # Task deprecations
     retries: 3,                                  # Non-fault exception retries
     retry_on: [External::ApiError],              # List of exceptions to retry on
-    retry_jitter: 1                              # Space between retry iteration, eg: current retry num + 1
+    retry_jitter: 1,                             # Space between retry iteration, eg: current retry num + 1
+    rollback_on: ["failed", "skipped"],          # Rollback on override
   )
 
   def work
@@ -269,7 +280,7 @@ end
 
 !!! warning "Important"
 
-    Retries reuse the same context. By default, all `StandardError` exceptions are retried unless you specify `retry_on`.
+    Retries reuse the same context. By default, all `StandardError` exceptions (including faults) are retried unless you specify `retry_on` option for specific matches.
 
 ### Registrations
 

data/docs/retries.md

@@ -0,0 +1,121 @@
+# Retries
+
+CMDx provides automatic retry functionality for tasks that encounter transient failures. This is essential for handling temporary issues like network timeouts, rate limits, or database locks without manual intervention.
+
+## Basic Usage
+
+Configure retries upto n attempts without any delay.
+
+```ruby
+class FetchExternalData < CMDx::Task
+  settings retries: 3
+
+  def work
+    response = HTTParty.get("https://api.example.com/data")
+    context.data = response.parsed_response
+  end
+end
+```
+
+When an exception occurs during execution, CMDx automatically retries up to the configured limit.
+
+## Selective Retries
+
+By default, CMDx retries on `StandardError` and its subclasses. Narrow this to specific exception types:
+
+```ruby
+class ProcessPayment < CMDx::Task
+  settings retries: 5, retry_on: [Stripe::RateLimitError, Net::ReadTimeout]
+
+  def work
+    # Your logic here...
+  end
+end
+```
+
+!!! warning "Important"
+
+    Only exceptions matching the `retry_on` configuration will trigger retries. Uncaught exceptions immediately fail the task.
+
+## Retry Jitter
+
+Add delays between retry attempts to avoid overwhelming external services or to implement exponential backoff strategies.
+
+### Fixed Value
+
+Use a numeric value to calculate linear delay (`jitter * current_retry`):
+
+```ruby
+class ImportRecords < CMDx::Task
+  settings retries: 3, retry_jitter: 0.5
+
+  def work
+    # Delays: 0s, 0.5s (retry 1), 1.0s (retry 2), 1.5s (retry 3)
+    context.records = ExternalAPI.fetch_records
+  end
+end
+```
+
+### Symbol References
+
+Define an instance method for custom delay logic:
+
+```ruby
+class SyncInventory < CMDx::Task
+  settings retries: 5, retry_jitter: :exponential_backoff
+
+  def work
+    context.inventory = InventoryAPI.sync
+  end
+
+  private
+
+  def exponential_backoff(current_retry)
+    2 ** current_retry # 2s, 4s, 8s, 16s, 32s
+  end
+end
+```
+
+### Proc or Lambda
+
+Pass a proc for inline delay calculations:
+
+```ruby
+class PollJobStatus < CMDx::Task
+  # Proc
+  settings retries: 10, retry_jitter: proc { |retry_count| [retry_count * 0.5, 5.0].min }
+
+  # Lambda
+  settings retries: 10, retry_jitter: ->(retry_count) { [retry_count * 0.5, 5.0].min }
+
+  def work
+    # Delays: 0.5s, 1.0s, 1.5s, 2.0s, 2.5s, 3.0s, 3.5s, 4.0s, 4.5s, 5.0s (capped)
+    context.status = JobAPI.check_status(context.job_id)
+  end
+end
+```
+
+### Class or Module
+
+Implement reusable delay logic in dedicated modules and classes:
+
+```ruby
+class ExponentialBackoff
+  def call(task, retry_count)
+    base_delay = task.context.base_delay || 1.0
+    [base_delay * (2 ** retry_count), 60.0].min
+  end
+end
+
+class FetchUserProfile < CMDx::Task
+  # Class or Module
+  settings retries: 4, retry_jitter: ExponentialBackoff
+
+  # Instance
+  settings retries: 4, retry_jitter: ExponentialBackoff.new
+
+  def work
+    # Your logic here...
+  end
+end
+```

data/docs/tips_and_tricks.md

@@ -145,7 +145,8 @@ class ConfigureCompany < CMDx::Task
 end
 ```
 
-## Advanced Examples
+## More Examples
 
 - [Active Record Query Tagging](https://github.com/drexed/cmdx/blob/main/examples/active_record_query_tagging.md)
 - [Paper Trail Whatdunnit](https://github.com/drexed/cmdx/blob/main/examples/paper_trail_whatdunnit.md)
+- [Stoplight Circuit Breaker](https://github.com/drexed/cmdx/blob/main/examples/stoplight_circuit_breaker.md)

data/examples/stoplight_circuit_breaker.md

@@ -0,0 +1,36 @@
+# Stoplight Circuit Breaker
+
+Integrate circuit breakers to protect external service calls and prevent cascading failures when dependencies are unavailable.
+
+<https://github.com/bolshakov/stoplight>
+
+### Setup
+
+```ruby
+# lib/cmdx_stoplight_middleware.rb
+class CmdxStoplightMiddleware
+  def self.call(task, **options, &)
+    light = Stoplight(options[:name] || task.class.name, **options)
+    light.run(&)
+  rescue Stoplight::Error::RedLight => e
+    task.result.tap { |r| r.fail!("[#{e.class}] #{e.message}", cause: e) }
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  # With default options
+  register :middleware, CmdxStoplightMiddleware
+
+  # With stoplight options
+  register :middleware, CmdxStoplightMiddleware, cool_off_time: 10
+
+  def work
+    # Do work...
+  end
+
+end
+```

data/lib/cmdx/configuration.rb

@@ -9,6 +9,9 @@ module CMDx
     # @rbs DEFAULT_BREAKPOINTS: Array[String]
     DEFAULT_BREAKPOINTS = %w[failed].freeze
 
+    # @rbs DEFAULT_ROLLPOINTS: Array[String]
+    DEFAULT_ROLLPOINTS = %w[failed].freeze
+
     # Returns the middleware registry for task execution.
     #
     # @return [MiddlewareRegistry] The middleware registry
@@ -110,6 +113,16 @@ module CMDx
     # @rbs @exception_handler: (Proc | nil)
     attr_accessor :exception_handler
 
+    # Returns the statuses that trigger a task execution rollback.
+    #
+    # @return [Array<String>] Array of status names that trigger rollback
+    #
+    # @example
+    #   config.rollback_on = ["failed", "skipped"]
+    #
+    # @rbs @rollback_on: Array[String]
+    attr_accessor :rollback_on
+
     # Initializes a new Configuration instance with default values.
     #
     # Creates new registry instances for middlewares, callbacks, coercions, and
@@ -131,6 +144,7 @@ module CMDx
 
       @task_breakpoints = DEFAULT_BREAKPOINTS
       @workflow_breakpoints = DEFAULT_BREAKPOINTS
+      @rollback_on = DEFAULT_ROLLPOINTS
 
       @backtrace = false
       @backtrace_cleaner = nil
@@ -162,6 +176,7 @@ module CMDx
         validators: @validators,
         task_breakpoints: @task_breakpoints,
         workflow_breakpoints: @workflow_breakpoints,
+        rollback_on: @rollback_on,
         backtrace: @backtrace,
         backtrace_cleaner: @backtrace_cleaner,
         exception_handler: @exception_handler,

data/lib/cmdx/executor.rb

@@ -118,15 +118,12 @@ module CMDx
     #
     # @return [Boolean] Whether execution should halt
     #
-    # @example
-    #   halt_execution?(fault_exception)
-    #
     # @rbs (Exception exception) -> bool
     def halt_execution?(exception)
-      breakpoints = task.class.settings[:breakpoints] || task.class.settings[:task_breakpoints]
-      breakpoints = Array(breakpoints).map(&:to_s).uniq
+      statuses = task.class.settings[:breakpoints] || task.class.settings[:task_breakpoints]
+      statuses = Array(statuses).map(&:to_s).uniq
 
-      breakpoints.include?(exception.result.status)
+      statuses.include?(exception.result.status)
     end
 
     # Determines if execution should be retried based on retry configuration.
@@ -135,9 +132,6 @@ module CMDx
     #
     # @return [Boolean] Whether execution should be retried
     #
-    # @example
-    #   retry_execution?(standard_error)
-    #
     # @rbs (Exception exception) -> bool
     def retry_execution?(exception)
       available_retries = (task.class.settings[:retries] || 0).to_i
@@ -157,7 +151,18 @@ module CMDx
         task.to_h.merge!(reason:, remaining_retries:)
       end
 
-      jitter = task.class.settings[:retry_jitter].to_f * current_retries
+      jitter = task.class.settings[:retry_jitter]
+      jitter =
+        if jitter.is_a?(Symbol)
+          task.send(jitter, current_retries)
+        elsif jitter.is_a?(Proc)
+          task.instance_exec(current_retries, &jitter)
+        elsif jitter.respond_to?(:call)
+          jitter.call(task, current_retries)
+        else
+          jitter.to_f * current_retries
+        end
+
       sleep(jitter) if jitter.positive?
 
       true
@@ -169,9 +174,6 @@ module CMDx
     #
     # @raise [Exception] The provided exception
     #
-    # @example
-    #   raise_exception(standard_error)
-    #
     # @rbs (Exception exception) -> void
     def raise_exception(exception)
       Chain.clear
@@ -244,7 +246,7 @@ module CMDx
       invoke_callbacks(:on_bad) if task.result.bad?
     end
 
-    # Finalizes execution by freezing the task and logging results.
+    # Finalizes execution by freezing the task, logging results, and rolling back work.
     #
     # @rbs () -> Result
     def finalize_execution!
@@ -253,6 +255,8 @@ module CMDx
 
       freeze_execution!
       clear_chain!
+
+      rollback_execution!
     end
 
     # Logs the execution result at the configured log level.
@@ -309,5 +313,18 @@ module CMDx
       Chain.clear
     end
 
+    # Rolls back the work of a task.
+    #
+    # @rbs () -> void
+    def rollback_execution!
+      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)
+
+      task.rollback
+    end
+
   end
 end

data/lib/cmdx/version.rb

@@ -5,6 +5,6 @@ module CMDx
   # @return [String] the version of the CMDx gem
   #
   # @rbs return: String
-  VERSION = "1.9.1"
+  VERSION = "1.10.0"
 
 end

data/mkdocs.yml

@@ -2,7 +2,7 @@
 
 site_name: CMDx
 site_url: https://drexed.github.io/cmdx/
-site_description: Build business logic that's powerful, predictable, and chaos-free.
+site_description: Build business logic that's powerful, predictable, and maintainable.
 site_author: drexed
 repo_name: drexed/cmdx
 repo_url: https://github.com/drexed/cmdx
@@ -108,9 +108,11 @@ nav:
   - Middlewares: middlewares.md
   - Logging: logging.md
   - Internationalization: internationalization.md
+  - Retries: retries.md
   - Deprecation: deprecation.md
   - Workflows: workflows.md
   - Tips and Tricks: tips_and_tricks.md
+  - LLM.md: https://raw.githubusercontent.com/drexed/cmdx/refs/heads/main/LLM.md
 
 extra:
   generator: false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 1.10.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -240,11 +240,13 @@ files:
 - docs/outcomes/result.md
 - docs/outcomes/states.md
 - docs/outcomes/statuses.md
+- docs/retries.md
 - docs/stylesheets/extra.css
 - docs/tips_and_tricks.md
 - docs/workflows.md
 - examples/active_record_query_tagging.md
 - examples/paper_trail_whatdunnit.md
+- examples/stoplight_circuit_breaker.md
 - lib/cmdx.rb
 - lib/cmdx/.DS_Store
 - lib/cmdx/attribute.rb