cmdx 0.5.0 → 1.0.1

data/docs/interruptions/exceptions.md

@@ -1,29 +1,216 @@
 # Interruptions - Exceptions
 
-## Non-bang call
+CMDx provides robust exception handling that differs between the `call` and `call!`
+methods. Understanding how unhandled exceptions are processed is crucial for
+building reliable task execution flows and implementing proper error handling strategies.
 
-Any unhandled exception will be caught and halted using `fail!`.
-The original exception will be passed as metadata of the result object.
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Exception Handling Behavior](#exception-handling-behavior)
+- [Bang Call (`call!`)](#bang-call-call)
+- [Exception Classification](#exception-classification)
+
+## TLDR
+
+- **`call`** - Captures ALL exceptions, converts to failed results with metadata
+- **`call!`** - Lets exceptions propagate (except CMDx faults based on task_halt config)
+- **Exception info** - Available in `result.metadata[:original_exception]` and `result.metadata[:reason]`
+- **Guaranteed results** - `call` always returns a result object, never raises
+- **Fault vs Exception** - CMDx faults have special handling, other exceptions propagate in `call!`
+
+## Exception Handling Behavior
+
+### Non-bang Call (`call`)
+
+The `call` method captures **all** unhandled exceptions and converts them to
+failed results, ensuring that no exceptions escape the task execution boundary.
+This provides consistent, predictable behavior for result processing.
 
 ```ruby
-result = ProcessOrderTask.call
+class ProcessUserOrderTask < CMDx::Task
+
+  def call
+    # This will raise a NoMethodError
+    undefined_method_call
+  end
+
+end
+
+result = ProcessUserOrderTask.call
 result.state    #=> "interrupted"
 result.status   #=> "failed"
+result.failed?  #=> true
 result.metadata #=> {
-                #=>   reason: "[RuntimeError] method xyz is not defined",
-                #=>   original_exception: <RuntimeError message="method xyz is not defined">
+                #=>   reason: "[NoMethodError] undefined method `undefined_method_call`",
+                #=>   original_exception: <NoMethodError>
                 #=> }
 ```
 
-## Bang call
+> [!NOTE]
+> The `call` method ensures no exceptions escape task execution, making it ideal
+> for workflow processing and scenarios where you need guaranteed result objects.
+
+### Exception Metadata Structure
+
+Captured exceptions populate result metadata with structured information:
+
+```ruby
+class ConnectDatabaseTask < CMDx::Task
+
+  def call
+    # Simulate a database connection error
+    raise ActiveRecord::ConnectionNotEstablished, "Database unavailable"
+  end
+
+end
+
+result = ConnectDatabaseTask.call
+
+# Exception information in metadata
+result.metadata[:reason]                       #=> "[ActiveRecord::ConnectionNotEstablished] Database unavailable"
+result.metadata[:original_exception]           #=> <ActiveRecord::ConnectionNotEstablished>
+result.metadata[:original_exception].class     #=> ActiveRecord::ConnectionNotEstablished
+result.metadata[:original_exception].message   #=> "Database unavailable"
+result.metadata[:original_exception].backtrace #=> ["..."]
+```
+
+### Accessing Original Exception Details
+
+```ruby
+result = ProcessUserOrderTask.call
+
+if result.failed? && result.metadata[:original_exception]
+  original = result.metadata[:original_exception]
+
+  puts "Exception type: #{original.class}"
+  puts "Exception message: #{original.message}"
+  puts "Exception backtrace:"
+  puts original.backtrace.first(5).join("\n")
+
+  # Check exception type for specific handling
+  case original
+  when ActiveRecord::RecordNotFound
+    handle_missing_record(original)
+  when Net::TimeoutError
+    handle_timeout_error(original)
+  when StandardError
+    handle_generic_error(original)
+  end
+end
+```
+
+## Bang Call (`call!`)
+
+The `call!` method allows unhandled exceptions to propagate **unless** they are
+CMDx faults that match the `task_halt` configuration. This enables exception-based
+control flow while still providing structured fault handling.
+
+```ruby
+class ProcessUserOrderTask < CMDx::Task
+
+  def call
+    # This will raise a NoMethodError directly
+    undefined_method_call
+  end
+
+end
+
+begin
+  ProcessUserOrderTask.call!
+rescue NoMethodError => e
+  puts "Caught original exception: #{e.message}"
+  # Handle the original exception directly
+end
+```
+
+### Fault vs Exception Behavior
+
+```ruby
+class ProcessOrderPaymentTask < CMDx::Task
+
+  def call
+    if context.simulate_fault
+      fail!(reason: "Controlled failure") # Becomes CMDx::Failed
+    else
+      raise StandardError, "Uncontrolled error" # Remains StandardError
+    end
+  end
+
+end
+
+# Fault behavior (controlled)
+begin
+  ProcessOrderPaymentTask.call!(simulate_fault: true)
+rescue CMDx::Failed => e
+  puts "Caught CMDx fault: #{e.message}"
+end
+
+# Exception behavior (uncontrolled)
+begin
+  ProcessOrderPaymentTask.call!(simulate_fault: false)
+rescue StandardError => e
+  puts "Caught standard exception: #{e.message}"
+end
+```
 
-Any unhandled exception from a `call!` method will be raised as is.
+## Exception Classification
+
+### Protected Exceptions
+
+Certain CMDx-specific exceptions are always allowed to propagate and are never
+converted to failed results:
 
 ```ruby
-ProcessOrderTask.call! #=> raises NoMethodError, "method xyz is not defined"
+class ProcessUndefinedOrderTask < CMDx::Task
+  # Intentionally not implementing call method
+end
+
+# These exceptions always propagate regardless of call method
+begin
+  ProcessUndefinedOrderTask.call
+rescue CMDx::UndefinedCallError => e
+  puts "This exception is never converted to a failed result"
+end
+
+begin
+  ProcessUndefinedOrderTask.call!
+rescue CMDx::UndefinedCallError => e
+  puts "This exception propagates normally in call! too"
+end
 ```
 
+### CMDx Fault Handling
+
+CMDx faults have special handling in both call methods:
+
+```ruby
+class ProcessOrderWithHaltTask < CMDx::Task
+  # Configure to halt on failures
+  task_settings!(task_halt: [CMDx::Result::FAILED])
+
+  def call
+    fail!(reason: "This is a controlled failure")
+  end
+end
+
+# With call - fault becomes failed result
+result = ProcessOrderWithHaltTask.call
+result.failed? #=> true
+
+# With call! - fault becomes exception (due to task_halt configuration)
+begin
+  ProcessOrderWithHaltTask.call!
+rescue CMDx::Failed => e
+  puts "Fault converted to exception: #{e.message}"
+end
+```
+
+> [!IMPORTANT]
+> Always preserve original exception information in metadata when handling
+> exceptions manually. This maintains debugging capabilities and error traceability.
+
 ---
 
-- **Prev:** [Interruptions - Faults](https://github.com/drexed/cmdx/blob/main/docs/interruptions/faults.md)
-- **Next:** [Outcomes - Result](https://github.com/drexed/cmdx/blob/main/docs/outcomes/result.md)
+- **Prev:** [Interruptions - Faults](faults.md)
+- **Next:** [Outcomes - Result](../outcomes/result.md)

data/docs/interruptions/faults.md

@@ -1,89 +1,241 @@
 # Interruptions - Faults
 
-Faults are the mechanisms by which `CMDx` goes about halting execution of tasks
-via the `skip!` and `fail!` methods. When tasks are executed with bang `call!` method,
-a fault exception that matches the current task status will be raised.
+Faults are the exception mechanisms by which CMDx halts task execution via the
+`skip!` and `fail!` methods. When tasks are executed with the bang `call!` method,
+fault exceptions matching the task's interruption status are raised, enabling
+sophisticated exception handling and control flow patterns.
 
-## Rescue
+## Table of Contents
 
-Use the standard Ruby `rescue` method to handle any faults with custom logic.
+- [TLDR](#tldr)
+- [Fault Types](#fault-types)
+- [Basic Exception Handling](#basic-exception-handling)
+- [Fault Context Access](#fault-context-access)
+- [Advanced Fault Matching](#advanced-fault-matching)
+- [Fault Propagation (`throw!`)](#fault-propagation-throw)
+- [Fault Chain Analysis](#fault-chain-analysis)
+- [Task Halt Configuration](#task-halt-configuration)
+
+## TLDR
+
+- **Fault types** - `CMDx::Skipped` (from `skip!`) and `CMDx::Failed` (from `fail!`)
+- **Exception handling** - Use `rescue CMDx::Fault` to catch both types
+- **Full context** - Faults provide access to `result`, `task`, `context`, and `chain`
+- **Advanced matching** - Use `for?(TaskClass)` and `matches? { |f| condition }` for specific fault handling
+- **Propagation** - Use `throw!(result)` to bubble up failures while preserving fault context
+
+## Fault Types
+
+CMDx provides two primary fault types that inherit from the base `CMDx::Fault` class:
+
+- **`CMDx::Skipped`** - Raised when a task is skipped via `skip!`
+- **`CMDx::Failed`** - Raised when a task fails via `fail!`
+
+Both fault types provide full access to the task execution context, including
+the result object, task instance, context data, and chain information.
+
+> [!NOTE]
+> All fault exceptions (`CMDx::Skipped` and `CMDx::Failed`) inherit from the base `CMDx::Fault` class and provide access to the complete task execution context.
+
+## Basic Exception Handling
+
+Use standard Ruby `rescue` blocks to handle faults with custom logic:
 
 ```ruby
 begin
-  ProcessOrderTask.call!
-rescue CMDx::Skipped
-  # Do work on any skipped tasks
-rescue CMDx::Failed
-  # Do work on any failed tasks
-rescue CMDx::Fault
-  # Do work on any skipped or failed tasks
+  ProcessUserOrderTask.call!(order_id: 123)
+rescue CMDx::Skipped => e
+  # Handle skipped tasks
+  logger.info "Task skipped: #{e.message}"
+  e.result.metadata[:reason] #=> "Order already processed"
+rescue CMDx::Failed => e
+  # Handle failed tasks
+  logger.error "Task failed: #{e.message}"
+  e.result.metadata[:error_code] #=> "PAYMENT_DECLINED"
+rescue CMDx::Fault => e
+  # Handle any fault (skipped or failed)
+  logger.warn "Task interrupted: #{e.message}"
 end
 ```
 
-## For
+## Fault Context Access
 
-Faults can be matched for the task that caused it.
+Faults provide comprehensive access to task execution context:
 
 ```ruby
 begin
-  ProcessOrderTask.call!
-rescue CMDx::Skipped.for?(ProcessOrderTask, DeliverOrderTask)
-  # Do work on just skipped ProcessOrderTask or DeliverOrderTask tasks
+  ProcessUserOrderTask.call!(order_id: 123)
+rescue CMDx::Fault => e
+  # Result information
+  e.result.status            #=> "failed" or "skipped"
+  e.result.metadata[:reason] #=> "Insufficient inventory"
+  e.result.runtime           #=> 0.05
+
+  # Task information
+  e.task.class.name          #=> "ProcessUserOrderTask"
+  e.task.id                  #=> "abc123..."
+
+  # Context data
+  e.context.order_id         #=> 123
+  e.context.customer_email   #=> "user@example.com"
+
+  # Chain information
+  e.chain.id                 #=> "def456..."
+  e.chain.results.size       #=> 3
 end
 ```
 
-## Matches
+## Advanced Fault Matching
+
+### Task-Specific Matching (`for?`)
 
-Faults allow advance rescue matching with access to the underlying task internals.
+Match faults only from specific task classes using the `for?` method:
 
 ```ruby
 begin
-  ProcessOrderTask.call!
-rescue CMDx::Fault.matches? { |f| f.result.metadata[:reason].includes?("out of stock") }
-  # Do work on any skipped or failed tasks that have `:reason` metadata equals "out of stock"
+  WorkflowProcessUserOrdersTask.call!(orders: orders)
+rescue CMDx::Skipped.for?(ProcessUserOrderTask, ValidateUserOrderTask) => e
+  # Handle skips only from specific task types
+  logger.info "Order processing skipped: #{e.task.class.name}"
+  reschedule_order_processing(e.context.order_id)
+rescue CMDx::Failed.for?(ProcessOrderPaymentTask, ProcessCardChargeTask) => e
+  # Handle failures only from payment-related tasks
+  logger.error "Payment processing failed: #{e.message}"
+  retry_with_backup_payment_method(e.context)
 end
 ```
 
-> [!IMPORTANT]
-> All fault exceptions have access to the `for?` and `matches?` methods.
+### Custom Matching Logic (`matches?`)
 
-## Throw
+Use the `matches?` method with blocks for sophisticated fault matching:
 
-Throw the result of subtasks to bubble up fault as its own. Throwing will use the
-subtask results' status and metadata to create a matching halt on the parent task.
+```ruby
+begin
+  ProcessUserOrderTask.call!(order_id: 123)
+rescue CMDx::Fault.matches? { |f| f.result.metadata[:error_code] == "PAYMENT_DECLINED" } => e
+  # Handle specific payment errors
+  retry_with_different_payment_method(e.context)
+rescue CMDx::Fault.matches? { |f| f.context.order_value > 1000 } => e
+  # Handle high-value order failures differently
+  escalate_to_manager(e)
+rescue CMDx::Failed.matches? { |f| f.result.metadata[:reason]&.include?("timeout") } => e
+  # Handle timeout-specific failures
+  retry_with_longer_timeout(e)
+end
+```
+
+> [!TIP]
+> Use `for?` and `matches?` methods for advanced exception matching. The `for?` method is ideal for task-specific handling, while `matches?` enables custom logic-based fault filtering.
+
+## Fault Propagation (`throw!`)
+
+The `throw!` method enables fault propagation, allowing parent tasks to bubble up
+failures from subtasks while preserving the original fault information:
+
+### Basic Propagation
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessUserOrderTask < CMDx::Task
 
   def call
-    throw!(SendConfirmationNotificationsTask.call)
+    # Execute subtask and propagate its failure
+    validation_result = ValidateUserOrderTask.call(context)
+    throw!(validation_result) if validation_result.failed?
+
+    payment_result = ProcessOrderPaymentTask.call(context)
+    throw!(payment_result) # failed or skipped
 
-    # Do other work...
+    # Continue with main logic
+    finalize_order
   end
 
 end
+```
+
+### Propagation with Additional Context
+
+```ruby
+class ProcessOrderWorkflowTask < CMDx::Task
+
+  def call
+    step1_result = ValidateOrderDataTask.call(context)
+
+    if step1_result.failed?
+      # Propagate with additional context
+      throw!(step1_result, {
+        workflow_stage: "initial_validation",
+        attempted_at: Time.now,
+        can_retry: true
+      })
+    end
+
+    continue_workflow
+  end
 
-result = ProcessOrderTask.call
-result.state    #=> "interrupted"
-result.status   #=> "skipped"
-result.metadata #=> { reason: "Order confirmation could not be sent due to invalid email." }
+end
 ```
 
-> [!NOTE]
-> `throw!` will bubble any skipped and failed results. To only throw skipped results, just add
-> a conditional for the specific status.
+> [!IMPORTANT]
+> Use `throw!` to propagate failures while preserving the original fault context. This maintains the fault chain for debugging and provides better error traceability.
+
+## Fault Chain Analysis
+
+Results provide methods for analyzing fault propagation chains:
+
+```ruby
+result = ProcessOrderWorkflowTask.call(data: invalid_data)
+
+if result.failed?
+  # Find the original cause of failure
+  original_failure = result.caused_failure
+  puts "Original failure: #{original_failure.task.class.name}"
+  puts "Reason: #{original_failure.metadata[:reason]}"
+
+  # Find what threw the failure to this result
+  throwing_task = result.threw_failure
+  puts "Failure thrown by: #{throwing_task.task.class.name}" if throwing_task
+
+  # Check if this result caused or threw the failure
+  if result.caused_failure?
+    puts "This task was the original cause"
+  elsif result.threw_failure?
+    puts "This task threw a failure from another task"
+  elsif result.thrown_failure?
+    puts "This task failed due to a thrown failure"
+  end
+end
+```
 
-## Results
+## Task Halt Configuration
 
-The following represents a result output example of a thrown fault.
+Control which statuses raise exceptions using the `task_halt` setting:
 
 ```ruby
-result = ProcessOrderTask.call
-result.threw_failure  #=> <CMDx::Result[SendConfirmationNotificationsTask] ...>
-result.caused_failure #=> <CMDx::Result[DeliverEmailTask] ...>
+class ProcessUserOrderTask < CMDx::Task
+  # Only failed tasks raise exceptions on call!
+  task_settings!(task_halt: [CMDx::Result::FAILED])
+
+  def call
+    skip!(reason: "Order already processed") if already_processed?
+    # This will NOT raise an exception on call!
+  end
+end
+
+class ValidateUserDataTask < CMDx::Task
+  # Both failed and skipped tasks raise exceptions
+  task_settings!(task_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+
+  def call
+    skip!(reason: "Validation not required") if skip_validation?
+    # This WILL raise an exception on call!
+  end
+end
 ```
 
+> [!WARNING]
+> Task halt configuration only affects the `call!` method. The `call` method always captures all exceptions and converts them to result objects regardless of halt settings.
+
 ---
 
-- **Prev:** [Interruptions - Halt](https://github.com/drexed/cmdx/blob/main/docs/interruptions/halt.md)
-- **Next:** [Interruptions - Exceptions](https://github.com/drexed/cmdx/blob/main/docs/interruptions/exceptions.md)
+- **Prev:** [Interruptions - Halt](halt.md)
+- **Next:** [Interruptions - Exceptions](exceptions.md)