cmdx 1.9.1 → 1.10.1

data/docs/getting_started.md

@@ -2,10 +2,10 @@
 
 CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. It brings structure, consistency, and powerful developer tools to your business processes.
 
-**Common challenges it solves:**
+**Common challenges:**
 
 - Inconsistent service object patterns across your codebase
-- Limited logging makes debugging a nightmare
+- Black boxes make debugging a nightmare
 - Fragile error handling erodes confidence
 
 **What you get:**
@@ -17,332 +17,80 @@ CMDx is a Ruby framework for building maintainable, observable business logic th
 - Attribute validation with type coercions
 - Sensible defaults and developer-friendly APIs
 
-## The CERO Pattern
-
-CMDx embraces the Compose, Execute, React, Observe (CERO) pattern—a simple yet powerful approach to building reliable business logic.
-
-🧩 **Compose** — Define small, focused tasks with typed attributes and validations
-
-⚡ **Execute** — Run tasks with clear outcomes and pluggable behaviors
-
-🔄 **React** — Adapt to outcomes by chaining follow-up tasks or handling faults
-
-🔍 **Observe** — Capture structured logs and execution chains for debugging
-
 ## Installation
 
 Add CMDx to your Gemfile:
 
-```ruby
-gem 'cmdx'
-```
-
-For Rails applications, generate the configuration:
-
-```bash
-rails generate cmdx:install
-```
-
-This creates `config/initializers/cmdx.rb` file.
-
-## Configuration Hierarchy
-
-CMDx uses a straightforward two-tier configuration system:
-
-1. **Global Configuration** — Framework-wide defaults
-2. **Task Settings** — Class-level overrides using `settings`
-
-!!! warning "Important"
-
-    Task settings take precedence over global config. Settings are inherited from parent classes and can be overridden in subclasses.
-
-## Global Configuration
-
-Configure framework-wide defaults that apply to all tasks. These settings come with sensible defaults out of the box.
-
-### Breakpoints
-
-Control when `execute!` raises a `CMDx::Fault` based on task status.
-
-```ruby
-CMDx.configure do |config|
-  config.task_breakpoints = "failed" # String or Array[String]
-end
-```
-
-For workflows, configure which statuses halt the execution pipeline:
-
-```ruby
-CMDx.configure do |config|
-  config.workflow_breakpoints = ["skipped", "failed"]
-end
-```
-
-### Backtraces
+```sh
+gem install cmdx
 
-Enable detailed backtraces for non-fault exceptions to improve debugging. Optionally clean up stack traces to remove framework noise.
+# - or -
 
-!!! note
-
-    In Rails environments, `backtrace_cleaner` defaults to `Rails.backtrace_cleaner.clean`.
-
-```ruby
-CMDx.configure do |config|
-  # Truthy
-  config.backtrace = true
-
-  # Via callable (must respond to `call(backtrace)`)
-  config.backtrace_cleaner = AdvanceCleaner.new
-
-  # Via proc or lambda
-  config.backtrace_cleaner = ->(backtrace) { backtrace[0..5] }
-end
+bundle add cmdx
 ```
 
-### Exception Handlers
-
-Register handlers that run when non-fault exceptions occur.
+## Configuration
 
-!!! tip
-
-    Use exception handlers to send errors to your APM of choice.
-
-```ruby
-CMDx.configure do |config|
-  # Via callable (must respond to `call(task, exception)`)
-  config.exception_handler = NewRelicReporter
-
-  # Via proc or lambda
-  config.exception_handler = proc do |task, exception|
-    APMService.report(exception, extra_data: { task: task.name, id: task.id })
-  end
-end
-```
-
-### Logging
-
-```ruby
-CMDx.configure do |config|
-  config.logger = CustomLogger.new($stdout)
-end
-```
+For Rails applications, run the following command to generate a global configuration file in `config/initializers/cmdx.rb`.
 
-### Middlewares
-
-See the [Middlewares](middlewares.md#declarations) docs for task level configurations.
-
-```ruby
-CMDx.configure do |config|
-  # Via callable (must respond to `call(task, options)`)
-  config.middlewares.register CMDx::Middlewares::Timeout
-
-  # Via proc or lambda
-  config.middlewares.register proc { |task, options|
-    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    result = yield
-    end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    Rails.logger.debug { "task completed in #{((end_time - start_time) * 1000).round(2)}ms" }
-    result
-  }
-
-  # With options
-  config.middlewares.register AuditTrailMiddleware, service_name: "document_processor"
-
-  # Remove middleware
-  config.middlewares.deregister CMDx::Middlewares::Timeout
-end
-```
-
-!!! note
-
-    Middlewares are executed in registration order. Each middleware wraps the next, creating an execution chain around task logic.
-
-### Callbacks
-
-See the [Callbacks](callbacks.md#declarations) docs for task level configurations.
-
-```ruby
-CMDx.configure do |config|
-  # Via method
-  config.callbacks.register :before_execution, :initialize_user_session
-
-  # Via callable (must respond to `call(task)`)
-  config.callbacks.register :on_success, LogUserActivity
-
-  # Via proc or lambda
-  config.callbacks.register :on_complete, proc { |task|
-    execution_time = task.metadata[:runtime]
-    Metrics.timer("task.execution_time", execution_time, tags: ["task:#{task.class.name.underscore}"])
-  }
-
-  # With options
-  config.callbacks.register :on_failure, :send_alert_notification, if: :critical_task?
-
-  # Remove callback
-  config.callbacks.deregister :on_success, LogUserActivity
-end
-```
-
-### Coercions
-
-See the [Attributes - Coercions](attributes/coercions.md#declarations) docs for task level configurations.
-
-```ruby
-CMDx.configure do |config|
-  # Via callable (must respond to `call(value, options)`)
-  config.coercions.register :currency, CurrencyCoercion
-
-  # Via method (must match signature `def coordinates_coercion(value, options)`)
-  config.coercions.register :coordinates, :coordinates_coercion
-
-  # Via proc or lambda
-  config.coercions.register :tag_list, proc { |value, options|
-    delimiter = options[:delimiter] || ','
-    max_tags = options[:max_tags] || 50
-
-    tags = value.to_s.split(delimiter).map(&:strip).reject(&:empty?)
-    tags.first(max_tags)
-  }
-
-  # Remove coercion
-  config.coercions.deregister :currency
-end
+```bash
+rails generate cmdx:install
 ```
 
-### Validators
-
-See the [Attributes - Validations](attributes/validations.md#declarations) docs for task level configurations.
-
-```ruby
-CMDx.configure do |config|
-  # Via callable (must respond to `call(value, options)`)
-  config.validators.register :username, UsernameValidator
-
-  # Via method (must match signature `def url_validator(value, options)`)
-  config.validators.register :url, :url_validator
-
-  # Via proc or lambda
-  config.validators.register :access_token, proc { |value, options|
-    expected_prefix = options[:prefix] || "tok_"
-    minimum_length = options[:min_length] || 40
-
-    value.start_with?(expected_prefix) && value.length >= minimum_length
-  }
+If not using Rails, manually copy the [configuration file](https://github.com/drexed/cmdx/blob/main/lib/generators/cmdx/templates/install.rb).
 
-  # Remove validator
-  config.validators.deregister :username
-end
-```
+## The CERO Pattern
 
-## Task Configuration
+CMDx embraces the Compose, Execute, React, Observe (CERO, pronounced "zero") pattern—a simple yet powerful approach to building reliable business logic.
 
-### Settings
+### Compose
 
-Override global configuration for specific tasks using `settings`:
+Build reusable, single-responsibility tasks with typed attributes, validation, and callbacks. Tasks can be chained together in workflows to create complex business processes from simple building blocks.
 
 ```ruby
-class GenerateInvoice < CMDx::Task
-  settings(
-    # Global configuration overrides
-    task_breakpoints: ["failed"],                # Breakpoint override
-    workflow_breakpoints: [],                    # Breakpoint override
-    backtrace: true,                             # Toggle backtrace
-    backtrace_cleaner: ->(bt) { bt[0..5] },      # Backtrace cleaner
-    logger: CustomLogger.new($stdout),           # Custom logger
-
-    # Task configuration settings
-    breakpoints: ["failed"],                     # Contextual pointer for :task_breakpoints and :workflow_breakpoints
-    log_level: :info,                            # Log level override
-    log_formatter: CMDx::LogFormatters::Json.new # Log formatter override
-    tags: ["billing", "financial"],              # Logging tags
-    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
-  )
-
+class AnalyzeMetrics < CMDx::Task
   def work
     # Your logic here...
   end
 end
 ```
 
-!!! warning "Important"
-
-    Retries reuse the same context. By default, all `StandardError` exceptions are retried unless you specify `retry_on`.
-
-### Registrations
+### Execute
 
-Register or deregister middlewares, callbacks, coercions, and validators for specific tasks:
+Invoke tasks with a consistent API that always returns a result object. Execution automatically handles validation, type coercion, error handling, and logging. Arguments are validated and coerced before your task logic runs.
 
 ```ruby
-class SendCampaignEmail < CMDx::Task
-  # Middlewares
-  register :middleware, CMDx::Middlewares::Timeout
-  deregister :middleware, AuditTrailMiddleware
-
-  # Callbacks
-  register :callback, :on_complete, proc { |task|
-    runtime = task.metadata[:runtime]
-    Analytics.track("email_campaign.sent", runtime, tags: ["task:#{task.class.name}"])
-  }
-  deregister :callback, :before_execution, :initialize_user_session
-
-  # Coercions
-  register :coercion, :currency, CurrencyCoercion
-  deregister :coercion, :coordinates
-
-  # Validators
-  register :validator, :username, :username_validator
-  deregister :validator, :url
+# Without args
+result = AnalyzeMetrics.execute
 
-  def work
-    # Your logic here...
-  end
-end
+# With args
+result = AnalyzeMetrics.execute(model: "blackbox", "sensitivity" => 3)
 ```
 
-## Configuration Management
+### React
 
-### Access
+Every execution returns a result object with a clear outcome. Check the result's state (`success?`, `failed?`, `skipped?`) and access returned values, error messages, and metadata to make informed decisions.
 
 ```ruby
-# Global configuration access
-CMDx.configuration.logger               #=> <Logger instance>
-CMDx.configuration.task_breakpoints     #=> ["failed"]
-CMDx.configuration.middlewares.registry #=> [<Middleware>, ...]
-
-# Task configuration access
-class ProcessUpload < CMDx::Task
-  settings(tags: ["files", "storage"])
-
-  def work
-    self.class.settings[:logger] #=> Global configuration value
-    self.class.settings[:tags]   #=> Task configuration value => ["files", "storage"]
-  end
+if result.success?
+  # Handle success
+elsif result.skipped?
+  # Handle skipped
+elsif result.failed?
+  # Handle failed
 end
 ```
 
-### Resetting
-
-!!! warning
-
-    Resetting affects your entire application. Use this primarily in test environments.
+### Observe
 
-```ruby
-# Reset to framework defaults
-CMDx.reset_configuration!
+Every task execution generates structured logs with execution chains, runtime metrics, and contextual metadata. Logs can be automatically correlated using chain IDs, making it easy to trace complex workflows and debug issues.
 
-# Verify reset
-CMDx.configuration.task_breakpoints     #=> ["failed"] (default)
-CMDx.configuration.middlewares.registry #=> Empty registry
+```log
+I, [2022-07-17T18:42:37.000000 #3784] INFO -- CMDx:
+index=1 chain_id="018c2b95-23j4-2kj3-32kj-3n4jk3n4jknf" type="Task" class="SendAnalyzedEmail" state="complete" status="success" metadata={runtime: 347}
 
-# Commonly used in test setup (RSpec example)
-RSpec.configure do |config|
-  config.before(:each) do
-    CMDx.reset_configuration!
-  end
-end
+I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
+index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
 ```
 
 ## Task Generator

data/docs/index.md

@@ -8,7 +8,7 @@ Build business logic that's powerful, predictable, and maintainable.
 
 ---
 
-Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
+Say goodbye to messy service objects. CMDx (pronounced "Command X") helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
 
 !!! note
 
@@ -24,7 +24,9 @@ CMDx works with any Ruby framework. Rails support is built-in, but it's framewor
 
 ```sh
 gem install cmdx
+
 # - or -
+
 bundle add cmdx
 ```
 
@@ -125,7 +127,7 @@ For backwards compatibility of certain functionality:
 
 ## Contributing
 
-Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](https://github.com/drexed/cmdx/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

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. Each retry attempt is logged at the `warn` level with retry metadata. If all retries are exhausted, the task fails with the original exception.
+
+## 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/stylesheets/extra.css

@@ -9,34 +9,34 @@
   --md-accent-fg-color--transparent:   hsla(#{hex2hsl(#fe1817)}, 0.1);
 }
 
-/* Atom One Light Pro syntax highlighting */
+/* GitHub High Contrast Light syntax highlighting */
 [data-md-color-scheme="default"] {
-  --md-code-hl-color:            #2c3036;
-  --md-code-hl-keyword-color:    #a626a4;
-  --md-code-hl-string-color:     #50a14f;
-  --md-code-hl-name-color:       #e4564a;
-  --md-code-hl-function-color:   #4078f2;
-  --md-code-hl-number-color:     #ca7601;
-  --md-code-hl-constant-color:   #c18401;
-  --md-code-hl-comment-color:    #9ca0a4;
-  --md-code-hl-operator-color:   #0184bc;
-  --md-code-hl-punctuation-color:#383a42;
-  --md-code-hl-variable-color:   #e4564a;
-  --md-code-hl-generic-color:    #e4564a;
+  --md-code-hl-color:            #0e1116;
+  --md-code-hl-keyword-color:    #a0095d;
+  --md-code-hl-string-color:     #024c1a;
+  --md-code-hl-name-color:       #622cbc;
+  --md-code-hl-function-color:   #622cbc;
+  --md-code-hl-number-color:     #0349b4;
+  --md-code-hl-constant-color:   #702c00;
+  --md-code-hl-comment-color:    #66707b;
+  --md-code-hl-operator-color:   #a0095d;
+  --md-code-hl-punctuation-color:#0e1116;
+  --md-code-hl-variable-color:   #702c00;
+  --md-code-hl-generic-color:    #622cbc;
 }
 
-/* Atom One Dark Pro syntax highlighting */
+/* GitHub High Contrast Dark syntax highlighting */
 [data-md-color-scheme="slate"] {
-  --md-code-hl-color:            #e5e5e6;
-  --md-code-hl-keyword-color:    #c678dd;
-  --md-code-hl-string-color:     #98c379;
-  --md-code-hl-name-color:       #e06c75;
-  --md-code-hl-function-color:   #61afef;
-  --md-code-hl-number-color:     #d19a66;
-  --md-code-hl-constant-color:   #d19a66;
-  --md-code-hl-comment-color:    #7f848e;
-  --md-code-hl-operator-color:   #56b6c2;
-  --md-code-hl-punctuation-color:#abb2bf;
-  --md-code-hl-variable-color:   #e06c75;
-  --md-code-hl-generic-color:    #e06c75;
+  --md-code-hl-color:            #f0f3f6;
+  --md-code-hl-keyword-color:    #ff9492;
+  --md-code-hl-string-color:     #addcff;
+  --md-code-hl-name-color:       #dbb7ff;
+  --md-code-hl-function-color:   #dbb7ff;
+  --md-code-hl-number-color:     #91cbff;
+  --md-code-hl-constant-color:   #ffb757;
+  --md-code-hl-comment-color:    #9ea7b3;
+  --md-code-hl-operator-color:   #ff9492;
+  --md-code-hl-punctuation-color:#f0f3f6;
+  --md-code-hl-variable-color:   #ffb757;
+  --md-code-hl-generic-color:    #dbb7ff;
 }

data/docs/tips_and_tricks.md

@@ -145,7 +145,9 @@ class ConfigureCompany < CMDx::Task
 end
 ```
 
-## Advanced Examples
+## Useful 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)
+- [Sidekiq Async Execution](https://github.com/drexed/cmdx/blob/main/examples/sidekiq_async_execution.md)
+- [Stoplight Circuit Breaker](https://github.com/drexed/cmdx/blob/main/examples/stoplight_circuit_breaker.md)

data/examples/sidekiq_async_execution.md

@@ -0,0 +1,29 @@
+# Sidekiq Async Execute
+
+Execute tasks asynchronously using Sidekiq without creating separate job classes.
+
+<https://github.com/sidekiq/sidekiq>
+
+### Setup
+
+```ruby
+class MyTask < CMDx::Task
+  include Sidekiq::Job
+
+  def work
+    # Do work...
+  end
+
+  # Use execute! to trigger Sidekiq's retry logic on failures/exceptions.
+  def perform
+    self.class.execute!
+  end
+
+end
+```
+
+### Usage
+
+```ruby
+MyTask.perform_async
+```

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
+```