cmdx 0.4.0 → 1.0.0

data/docs/interruptions/faults.md

@@ -1,89 +1,232 @@
 # 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.
+- [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)
+
+## 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?
 
-    # Do other work...
+    payment_result = ProcessOrderPaymentTask.call(context)
+    throw!(payment_result) # failed or skipped
+
+    # Continue with main logic
+    finalize_order
   end
 
 end
+```
+
+### Propagation with Additional Context
+
+```ruby
+class ProcessOrderWorkflowTask < CMDx::Task
 
-result = ProcessOrderTask.call
-result.state    #=> "interrupted"
-result.status   #=> "skipped"
-result.metadata #=> { reason: "Order confirmation could not be sent due to invalid email." }
+  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
+
+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.
 
-## Results
+## Fault Chain Analysis
 
-The following represents a result output example of a thrown fault.
+Results provide methods for analyzing fault propagation chains:
 
 ```ruby
-result = ProcessOrderTask.call
-result.threw_failure  #=> <CMDx::Result[SendConfirmationNotificationsTask] ...>
-result.caused_failure #=> <CMDx::Result[DeliverEmailTask] ...>
+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
 ```
 
+## Task Halt Configuration
+
+Control which statuses raise exceptions using the `task_halt` setting:
+
+```ruby
+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)

data/docs/interruptions/halt.md

@@ -1,80 +1,224 @@
 # Interruptions - Halt
 
-Halting stops execution of a task. Halt methods signal the intent as to why a task
-is stopped executing.
+Halting stops execution of a task with explicit intent signaling. Tasks provide
+two primary halt methods that control execution flow and result in different
+outcomes, each serving specific use cases in business logic.
 
-## Skip
+## Table of Contents
 
-The `skip!` method indicates that a task did not meet the criteria to continue execution.
+- [Skip (`skip!`)](#skip-skip)
+- [Fail (`fail!`)](#fail-fail)
+- [Metadata Enrichment](#metadata-enrichment)
+- [State Transitions](#state-transitions)
+- [Exception Behavior](#exception-behavior)
+- [The Reason Key](#the-reason-key)
+
+## Skip (`skip!`)
+
+The `skip!` method indicates that a task did not meet the criteria to continue
+execution. This represents a controlled, intentional interruption where the
+task determines that execution is not necessary or appropriate under current
+conditions.
+
+### Basic Usage
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessUserOrderTask < CMDx::Task
 
   def call
-    skip! if cart_abandoned?
+    context.order = Order.find(context.order_id)
 
-    # Do work...
+    # Skip if order is already processed
+    skip!(reason: "Order already processed") if context.order.processed?
+
+    # Skip if prerequisites aren't met
+    skip!(reason: "Payment method not configured") unless context.order.payment_method
+
+    # Continue with business logic
+    context.order.process!
   end
 
 end
 ```
 
-## Fail
+> [!NOTE]
+> Use `skip!` when a task cannot or should not execute under current conditions, but this is not an error. Skipped tasks are considered successful outcomes.
+
+## Fail (`fail!`)
 
-The `fail!` method indicates that a task met with incomplete, broken, or failed logic.
+The `fail!` method indicates that a task encountered an error condition that
+prevents successful completion. This represents controlled failure where the
+task explicitly determines that execution cannot continue successfully.
+
+### Basic Usage
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessOrderPaymentTask < CMDx::Task
 
   def call
-    fail! if cart_items_out_of_stock?
+    context.payment = Payment.find(context.payment_id)
+
+    # Fail on validation errors
+    fail!(reason: "Payment amount must be positive") unless context.payment.amount > 0
+
+    # Fail on business rule violations
+    fail!(reason: "Insufficient funds") unless sufficient_funds?
 
-    # Do work...
+    # Continue with processing
+    process_payment
   end
 
 end
 ```
 
-## Metadata
+> [!IMPORTANT]
+> Use `fail!` when a task encounters an error that prevents successful completion. Failed tasks represent error conditions that need to be handled or corrected.
+
+## Metadata Enrichment
+
+Both halt methods accept metadata to provide context about the interruption.
+Metadata is stored as a hash and becomes available through the result object.
 
-Pass metadata to enrich faults with additional contextual information. Metadata requires
-that it be passed as a hash object. Internal failures will hydrate metadata into its result,
-eg: failed validations and unrescued exceptions.
+### Structured Metadata
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessUserOrderTask < CMDx::Task
 
   def call
-    if cart_abandoned?
-      skip!(reason: "Cart was abandoned due to 30 days of inactivity")
-    elsif cart_items_out_of_stock?
-      fail!(reason: "Items in the cart are out of stock", item: [123, 987])
-    else
-      # Do work...
+    context.order = Order.find(context.order_id)
+
+    if context.order.status == "cancelled"
+      skip!(
+        reason: "Order was cancelled",
+        order_id: context.order.id,
+        cancelled_at: context.order.cancelled_at,
+        reason_code: context.order.cancellation_reason
+      )
     end
+
+    unless inventory_available?
+      fail!(
+        reason: "Insufficient inventory",
+        required_quantity: context.order.quantity,
+        available_quantity: current_inventory,
+        restock_date: estimated_restock_date,
+        error_code: "INVENTORY_DEPLETED"
+      )
+    end
+
+    process_order
   end
 
 end
+```
+
+### Accessing Metadata
+
+```ruby
+result = ProcessUserOrderTask.call(order_id: 123)
+
+# Check result status
+result.skipped?                #=> true
+result.failed?                 #=> false
+
+# Access metadata
+result.metadata[:reason]       #=> "Order was cancelled"
+result.metadata[:order_id]     #=> 123
+result.metadata[:cancelled_at] #=> 2023-01-01 10:00:00 UTC
+result.metadata[:reason_code]  #=> "customer_request"
+```
+
+## State Transitions
+
+Halt methods trigger specific state and status transitions:
+
+### Skip Transitions
+- **State**: `initialized` → `executing` → `interrupted`
+- **Status**: `success` → `skipped`
+- **Result**: `good? = true`, `bad? = true`
+
+### Fail Transitions
+- **State**: `initialized` → `executing` → `interrupted`
+- **Status**: `success` → `failed`
+- **Result**: `good? = false`, `bad? = true`
+
+```ruby
+result = ProcessUserOrderTask.call(order_id: 123)
+
+# State information
+result.state        #=> "interrupted"
+result.status       #=> "skipped" or "failed"
+result.interrupted? #=> true
+result.complete?    #=> false
+
+# Outcome categorization
+result.good?        #=> true for skipped, false for failed
+result.bad?         #=> true for both skipped and failed
+```
+
+## Exception Behavior
+
+Halt methods behave differently depending on the call method used:
+
+### With `call` (Non-bang)
+Returns a result object without raising exceptions:
+
+```ruby
+result = ProcessUserOrderTask.call(order_id: 123)
+
+case result.status
+when "success"
+  puts "Order processed successfully"
+when "skipped"
+  puts "Order skipped: #{result.metadata[:reason]}"
+when "failed"
+  puts "Order failed: #{result.metadata[:reason]}"
+end
+```
+
+### With `call!` (Bang)
+Raises fault exceptions based on `task_halt` configuration:
 
-result = ProcessOrderTask.call
-result.metadata #=> { reason: "Items in the cart are out of stock", item: [123, 987] }
+```ruby
+begin
+  result = ProcessUserOrderTask.call!(order_id: 123)
+  puts "Success: #{result.context.order.id}"
+rescue CMDx::Skipped => e
+  puts "Skipped: #{e.message}"
+  puts "Order ID: #{e.context.order_id}"
+rescue CMDx::Failed => e
+  puts "Failed: #{e.message}"
+  puts "Error code: #{e.result.metadata[:error_code]}"
+end
 ```
 
-> [!Important]
-> The `:reason` key is used to define the fault exception message. While not
-> required, it is strongly recommended that it is used on every halt method.
+> [!WARNING]
+> The `call!` method raises exceptions for halt conditions based on the `task_halt` configuration. The `call` method always returns result objects without raising exceptions.
+
+## The Reason Key
 
-## Results
+The `:reason` key in metadata has special significance:
 
-The following represents a result output example of a halted task.
+- Used as the exception message when faults are raised
+- Provides human-readable explanation of the halt
+- Strongly recommended for all halt calls
 
 ```ruby
-result = ProcessOrderTask.call
-result.status   #=> "failed"
-result.metadata #=> { reason: "Cart was abandoned due to 30 days of inactivity" }
+# Good: Provides clear reason
+skip!(reason: "User already has an active session")
+fail!(reason: "Credit card expired", code: "EXPIRED_CARD")
+
+# Acceptable: Other metadata without reason
+skip!(status: "redundant", timestamp: Time.now)
+
+# Fallback: Default message if no reason provided
+skip! # Exception message: "no reason given"
 ```
 
+> [!TIP]
+> Always try to include a `:reason` key in metadata when using halt methods. This provides clear context for debugging and creates meaningful exception messages when using `call!`.
+
 ---
 
-- **Prev:** [Basics - Run](https://github.com/drexed/cmdx/blob/main/docs/basics/run.md)
-- **Next:** [Interruptions - Faults](https://github.com/drexed/cmdx/blob/main/docs/interruptions/faults.md)
+- **Prev:** [Basics - Chain](../basics/chain.md)
+- **Next:** [Interruptions - Faults](faults.md)