cmdx 1.1.1 → 1.5.0

data/docs/interruptions/exceptions.md

@@ -1,232 +1,57 @@
 # Interruptions - Exceptions
 
-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.
+CMDx provides robust exception handling that differs between the `execute` and `execute!` methods. Understanding how unhandled exceptions are processed is crucial for building reliable task execution flows and implementing proper error handling strategies.
 
 ## Table of Contents
 
-- [TLDR](#tldr)
-- [Exception Handling Methods](#exception-handling-methods)
-- [Exception Metadata](#exception-metadata)
-- [Bang Call Behavior](#bang-call-behavior)
-- [Exception Classification](#exception-classification)
-- [Error Handling Patterns](#error-handling-patterns)
+- [Exception Handling](#exception-handling)
+  - [Non-bang execution](#non-bang-execution)
+  - [Bang execution](#bang-execution)
 
-## TLDR
-
-```ruby
-# Non-bang call - captures ALL exceptions
-result = ProcessOrderTask.call     # Never raises, always returns result
-result.failed?                     # true if exception occurred
-result.metadata[:original_exception] # Access original exception
-
-# Bang call - lets exceptions propagate
-ProcessOrderTask.call!             # Raises exceptions (except configured faults)
-
-# Exception info always available in metadata
-result.metadata[:reason]           # Human-readable error message
-result.metadata[:original_exception] # Original exception object
-```
-
-## Exception Handling Methods
+## Exception Handling
 
 > [!IMPORTANT]
-> The key difference: `call` guarantees a result object, while `call!` allows exceptions to propagate for standard error handling patterns.
-
-### Non-bang Call (`call`)
+> When designing tasks try not to `raise` your own exceptions directly, instead use `skip!` or `fail!` to signal intent clearly.
 
-The `call` method captures **all** unhandled exceptions and converts them to failed results, ensuring predictable behavior and consistent result processing.
+### Non-bang execution
 
-| Behavior | Description |
-|----------|-------------|
-| **Exception Capture** | All exceptions caught and converted |
-| **Return Value** | Always returns a result object |
-| **State** | `"interrupted"` for exception failures |
-| **Status** | `"failed"` for all captured exceptions |
-| **Metadata** | Exception details preserved |
+The `execute` method captures **all** unhandled exceptions and converts them to failed results, ensuring predictable behavior and consistent result processing.
 
 ```ruby
-class ProcessPaymentTask < CMDx::Task
-  def call
-    raise ActiveRecord::RecordNotFound, "Payment method not found"
+class CompressDocument < CMDx::Task
+  def work
+    document = Document.find(context.document_id)
+    document.compress!
   end
 end
 
-result = ProcessPaymentTask.call
+result = CompressDocument.execute(document_id: "unknown-doc-id")
 result.state    #=> "interrupted"
 result.status   #=> "failed"
 result.failed?  #=> true
+result.reason   #=> "[ActiveRecord::NotFoundError] record not found"
+result.cause    #=> <ActiveRecord::NotFoundError>
 ```
 
-### Bang Call (`call!`)
+### Bang execution
 
-The `call!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration.
+The `execute!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration.
 
 ```ruby
-class ProcessPaymentTask < CMDx::Task
-  def call
-    raise StandardError, "Payment gateway unavailable"
+class CompressDocument < CMDx::Task
+  def work
+    document = Document.find(context.document_id)
+    document.compress!
   end
 end
 
 begin
-  ProcessPaymentTask.call!
-rescue StandardError => e
+  CompressDocument.execute!(document_id: "unknown-doc-id")
+rescue ActiveRecord::NotFoundError => e
   puts "Handle exception: #{e.message}"
 end
 ```
 
-## Exception Metadata
-
-> [!NOTE]
-> Exception information is preserved in result metadata, providing full debugging context while maintaining clean result interfaces.
-
-### Metadata Structure
-
-```ruby
-result = ProcessPaymentTask.call
-
-# Exception metadata always includes:
-result.metadata[:reason]                  #=> "[StandardError] Payment gateway unavailable"
-result.metadata[:original_exception]      #=> <StandardError instance>
-
-# Access original exception properties
-exception = result.metadata[:original_exception]
-exception.class                          #=> StandardError
-exception.message                        #=> "Payment gateway unavailable"
-exception.backtrace                      #=> ["lib/tasks/payment.rb:15:in `call'", ...]
-```
-
-### Exception Type Checking
-
-```ruby
-class DatabaseTask < CMDx::Task
-  def call
-    raise ActiveRecord::ConnectionNotEstablished, "Database unavailable"
-  end
-end
-
-result = DatabaseTask.call
-
-if result.failed? && result.metadata[:original_exception]
-  case result.metadata[:original_exception]
-  when ActiveRecord::ConnectionNotEstablished
-    retry_with_fallback_database
-  when Net::TimeoutError
-    retry_with_increased_timeout
-  when StandardError
-    log_and_alert_administrators
-  end
-end
-```
-
-## Bang Call Behavior
-
-> [!WARNING]
-> `call!` propagates exceptions immediately, bypassing result object creation. Only use when you need direct exception handling or integration with exception-based error handling systems.
-
-### Fault vs Exception Handling
-
-CMDx faults receive special treatment based on `task_halt` configuration:
-
-```ruby
-class ProcessOrderTask < CMDx::Task
-  cmd_settings!(task_halt: [CMDx::Result::FAILED])
-
-  def call
-    if context.payment_invalid
-      fail!(reason: "Invalid payment method")  # CMDx fault
-    else
-      raise StandardError, "System error"     # Regular exception
-    end
-  end
-end
-
-# Fault behavior (converted to exception due to task_halt)
-begin
-  ProcessOrderTask.call!(payment_invalid: true)
-rescue CMDx::Failed => e
-  puts "Controlled fault: #{e.message}"
-end
-
-# Exception behavior (propagates normally)
-begin
-  ProcessOrderTask.call!(payment_invalid: false)
-rescue StandardError => e
-  puts "System exception: #{e.message}"
-end
-```
-
-## Exception Classification
-
-### Protected Exceptions
-
-> [!IMPORTANT]
-> CMDx framework exceptions always propagate regardless of call method, ensuring framework integrity and proper error reporting.
-
-Certain exceptions are never converted to failed results:
-
-```ruby
-class InvalidTask < CMDx::Task
-  # Intentionally not implementing call method
-end
-
-# Framework exceptions always propagate
-begin
-  InvalidTask.call  # Even non-bang call propagates framework exceptions
-rescue CMDx::UndefinedCallError => e
-  puts "Framework exception: #{e.message}"
-end
-```
-
-### Exception Hierarchy
-
-| Exception Type | `call` Behavior | `call!` Behavior |
-|----------------|-----------------|------------------|
-| **CMDx Framework** | Propagates | Propagates |
-| **CMDx Faults** | Converts to result | Respects `task_halt` config |
-| **Standard Exceptions** | Converts to result | Propagates |
-| **Custom Exceptions** | Converts to result | Propagates |
-
-## Error Handling Patterns
-
-### Graceful Degradation
-
-```ruby
-class ProcessUserDataTask < CMDx::Task
-  def call
-    user_data = fetch_user_data
-    process_data(user_data)
-  end
-
-  private
-
-  def fetch_user_data
-    # May raise various exceptions
-    external_api.get_user_data(context.user_id)
-  end
-end
-
-# Handle with graceful degradation
-result = ProcessUserDataTask.call(user_id: 12345)
-
-if result.failed?
-  case result.metadata[:original_exception]
-  when Net::TimeoutError
-    # Retry with cached data
-    fallback_processor.process_cached_data(user_id)
-  when JSON::ParserError
-    # Handle malformed response
-    error_reporter.log_api_format_error
-  else
-    # Generic error handling
-    notify_administrators(result.metadata[:reason])
-  end
-end
-```
-
-> [!TIP]
-> Use `call` for workflow processing where you need guaranteed result objects, and `call!` for direct integration with existing exception-based error handling patterns.
-
 ---
 
 - **Prev:** [Interruptions - Faults](faults.md)

data/docs/interruptions/faults.md

@@ -1,113 +1,72 @@
 # Interruptions - Faults
 
-Faults are exception mechanisms that halt task execution via `skip!` and `fail!` methods. When tasks execute with the `call!` method, fault exceptions matching the task's interruption status are raised, enabling sophisticated exception handling and control flow patterns.
+Faults are exception mechanisms that halt task execution via `skip!` and `fail!` methods. When tasks execute with the `execute!` method, fault exceptions matching the task's interruption status are raised, enabling sophisticated exception handling and control flow patterns.
 
 ## Table of Contents
 
-- [TLDR](#tldr)
 - [Fault Types](#fault-types)
-- [Exception Handling](#exception-handling)
-- [Fault Context Access](#fault-context-access)
+- [Fault Handling](#fault-handling)
+- [Data Access](#data-access)
 - [Advanced Matching](#advanced-matching)
+  - [Task-Specific Matching](#task-specific-matching)
+  - [Custom Logic Matching](#custom-logic-matching)
 - [Fault Propagation](#fault-propagation)
+  - [Basic Propagation](#basic-propagation)
+  - [Additional Metadata](#additional-metadata)
 - [Chain Analysis](#chain-analysis)
-- [Configuration](#configuration)
-
-## TLDR
-
-```ruby
-# Basic exception handling
-begin
-  PaymentProcessor.call!(amount: 100)
-rescue CMDx::Skipped => e
-  handle_skipped_payment(e.result.metadata[:reason])
-rescue CMDx::Failed => e
-  handle_failed_payment(e.result.metadata[:error])
-rescue CMDx::Fault => e
-  handle_any_interruption(e)
-end
-
-# Advanced matching
-rescue CMDx::Failed.for?(PaymentProcessor, CardValidator) => e
-rescue CMDx::Fault.matches? { |f| f.context.amount > 1000 } => e
-
-# Fault propagation
-throw!(validation_result) if validation_result.failed?
-```
 
 ## Fault Types
 
 | Type | Triggered By | Use Case |
 |------|--------------|----------|
-| `CMDx::Skipped` | `skip!` method | Optional processing, early returns |
-| `CMDx::Failed` | `fail!` method | Validation errors, processing failures |
 | `CMDx::Fault` | Base class | Catch-all for any interruption |
+| `CMDx::SkipFault` | `skip!` method | Optional processing, early returns |
+| `CMDx::FailFault` | `fail!` method | Validation errors, processing failures |
 
-> [!NOTE]
+> [!IMPORTANT]
 > All fault exceptions inherit from `CMDx::Fault` and provide access to the complete task execution context including result, task, context, and chain information.
 
-## Exception Handling
-
-### Basic Rescue Patterns
+## Fault Handling
 
 ```ruby
 begin
-  ProcessOrderTask.call!(order_id: 123)
-rescue CMDx::Skipped => e
-  logger.info "Order processing skipped: #{e.message}"
-  schedule_retry(e.context.order_id)
-rescue CMDx::Failed => e
-  logger.error "Order processing failed: #{e.message}"
-  notify_customer(e.context.customer_email, e.result.metadata[:error])
+  ProcessTicket.execute!(ticket_id: 456)
+rescue CMDx::SkipFault => e
+  logger.info "Ticket processing skipped: #{e.message}"
+  schedule_retry(e.context.ticket_id)
+rescue CMDx::FailFault => e
+  logger.error "Ticket processing failed: #{e.message}"
+  notify_admin(e.context.assigned_agent, e.result.metadata[:error_code])
 rescue CMDx::Fault => e
-  logger.warn "Order processing interrupted: #{e.message}"
-  rollback_transaction
-end
-```
-
-### Error-Specific Handling
-
-```ruby
-begin
-  PaymentProcessor.call!(card_token: token, amount: amount)
-rescue CMDx::Failed => e
-  case e.result.metadata[:error_code]
-  when "INSUFFICIENT_FUNDS"
-    suggest_different_payment_method
-  when "CARD_DECLINED"
-    request_card_verification
-  when "NETWORK_ERROR"
-    retry_payment_later
-  else
-    escalate_to_support(e)
-  end
+  logger.warn "Ticket processing interrupted: #{e.message}"
+  rollback_changes
 end
 ```
 
-## Fault Context Access
+## Data Access
 
-Faults provide comprehensive access to execution context:
+Faults provide comprehensive access to execution context, eg:
 
 ```ruby
 begin
-  UserRegistration.call!(email: email, password: password)
+  LicenseActivation.execute!(license_key: key, machine_id: machine)
 rescue CMDx::Fault => e
   # Result information
-  e.result.status            #=> "failed" or "skipped"
-  e.result.metadata[:reason] #=> "Email already exists"
-  e.result.runtime           #=> 0.05
+  e.result.state     #=> "interrupted"
+  e.result.status    #=> "failed" or "skipped"
+  e.result.reason    #=> "License key already activated"
 
   # Task information
-  e.task.class.name          #=> "UserRegistration"
-  e.task.id                  #=> "abc123..."
+  e.task.class       #=> <LicenseActivation>
+  e.task.id          #=> "abc123..."
 
   # Context data
-  e.context.email            #=> "user@example.com"
-  e.context.password         #=> "[FILTERED]"
+  e.context.license_key #=> "ABC-123-DEF"
+  e.context.machine_id  #=> "[FILTERED]"
 
-  # Chain information (for workflows)
-  e.chain&.id                #=> "def456..."
-  e.chain&.results&.size     #=> 3
+  # Chain information
+  e.chain.id         #=> "def456..."
+  e.chain.size       #=> 3
 end
 ```
 
@@ -115,18 +74,17 @@ end
 
 ### Task-Specific Matching
 
-> [!TIP]
-> Use `for?` to handle faults only from specific task classes, enabling targeted exception handling in complex workflows.
+Use `for?` to handle faults only from specific task classes, enabling targeted exception handling in complex workflows.
 
 ```ruby
 begin
-  PaymentWorkflow.call!(payment_data: data)
-rescue CMDx::Failed.for?(CardValidator, PaymentProcessor) => e
-  # Handle only payment-related failures
-  retry_with_backup_method(e.context)
-rescue CMDx::Skipped.for?(FraudCheck, RiskAssessment) => e
+  DocumentWorkflow.execute!(document_data: data)
+rescue CMDx::FailFault.for?(FormatValidator, ContentProcessor) => e
+  # Handle only document-related failures
+  retry_with_alternate_parser(e.context)
+rescue CMDx::SkipFault.for?(VirusScanner, ContentFilter) => e
   # Handle security-related skips
-  flag_for_manual_review(e.context.transaction_id)
+  quarantine_for_review(e.context.document_id)
 end
 ```
 
@@ -134,74 +92,76 @@ end
 
 ```ruby
 begin
-  OrderProcessor.call!(order: order_data)
-rescue CMDx::Fault.matches? { |f| f.context.order_value > 1000 } => e
-  escalate_high_value_failure(e)
-rescue CMDx::Failed.matches? { |f| f.result.metadata[:retry_count] > 3 } => e
-  abandon_processing(e)
-rescue CMDx::Fault.matches? { |f| f.result.metadata[:error_type] == "timeout" } => e
-  increase_timeout_and_retry(e)
+  ReportGenerator.execute!(report: report_data)
+rescue CMDx::Fault.matches? { |f| f.context.data_size > 10_000 } => e
+  escalate_large_dataset_failure(e)
+rescue CMDx::FailFault.matches? { |f| f.result.metadata[:attempt_count] > 3 } => e
+  abandon_report_generation(e)
+rescue CMDx::Fault.matches? { |f| f.result.metadata[:error_type] == "memory" } => e
+  increase_memory_and_retry(e)
 end
 ```
 
 ## Fault Propagation
 
-> [!IMPORTANT]
-> Use `throw!` to propagate failures while preserving fault context and maintaining the error chain for debugging.
+Use `throw!` to propagate failures while preserving fault context and maintaining the error chain for debugging.
 
 ### Basic Propagation
 
 ```ruby
-class OrderProcessor < CMDx::Task
-  def call
-    # Validate order data
-    validation_result = OrderValidator.call(context)
-    throw!(validation_result) if validation_result.failed?
+class ReportGenerator < CMDx::Task
+  def work
+    # Throw if skipped or failed
+    validation_result = DataValidator.execute(context)
+    throw!(validation_result)
+
+    # Only throw if skipped
+    check_permissions = CheckPermissions.execute(context)
+    throw!(check_permissions) if check_permissions.skipped?
 
-    # Process payment
-    payment_result = PaymentProcessor.call(context)
-    throw!(payment_result) if payment_result.failed?
+    # Only throw if failed
+    data_result = DataProcessor.execute(context)
+    throw!(data_result) if data_result.failed?
 
     # Continue processing
-    complete_order
+    generate_report
   end
 end
 ```
 
-### Propagation with Context
+### Additional Metadata
 
 ```ruby
-class WorkflowProcessor < CMDx::Task
-  def call
-    step_result = DataValidation.call(context)
+class BatchProcessor < CMDx::Task
+  def work
+    step_result = FileValidation.execute(context)
 
     if step_result.failed?
       throw!(step_result, {
-        workflow_stage: "validation",
+        batch_stage: "validation",
         can_retry: true,
-        next_step: "data_cleanup"
+        next_step: "file_repair"
       })
     end
 
-    continue_workflow
+    continue_batch
   end
 end
 ```
 
 ## Chain Analysis
 
-> [!NOTE]
-> Results provide methods to analyze fault propagation and identify original failure sources in complex execution chains.
+Results provide methods to analyze fault propagation and identify original failure sources in complex execution chains.
 
 ```ruby
-result = PaymentWorkflow.call(invalid_data)
+result = DocumentWorkflow.execute(invalid_data)
 
 if result.failed?
   # Trace the original failure
   original = result.caused_failure
   if original
     puts "Original failure: #{original.task.class.name}"
-    puts "Reason: #{original.metadata[:reason]}"
+    puts "Reason: #{original.reason}"
   end
 
   # Find what propagated the failure
@@ -220,46 +180,6 @@ if result.failed?
 end
 ```
 
-## Configuration
-
-### Task Halt Settings
-
-Control which statuses raise exceptions using `task_halt`:
-
-```ruby
-class DataProcessor < CMDx::Task
-  # Only failures raise exceptions
-  cmd_settings!(task_halt: [CMDx::Result::FAILED])
-
-  def call
-    skip!(reason: "No data to process") if data.empty?
-    # Skip will NOT raise exception on call!
-  end
-end
-
-class CriticalValidator < CMDx::Task
-  # Both failures and skips raise exceptions
-  cmd_settings!(task_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
-
-  def call
-    skip!(reason: "Validation bypassed") if bypass_mode?
-    # Skip WILL raise exception on call!
-  end
-end
-```
-
-> [!WARNING]
-> Task halt configuration only affects the `call!` method. The `call` method always captures exceptions and converts them to result objects regardless of halt settings.
-
-### Global Configuration
-
-```ruby
-# Configure default halt behavior
-CMDx.configure do |config|
-  config.task_halt = [CMDx::Result::FAILED]  # Default: only failures halt
-end
-```
-
 ---
 
 - **Prev:** [Interruptions - Halt](halt.md)