cmdx 1.12.0 → 1.14.0

data/docs/interruptions/faults.md

@@ -1,169 +0,0 @@
-# Interruptions - Faults
-
-Faults are exceptions raised by `execute!` when tasks halt. They carry rich context about execution state, enabling sophisticated error handling patterns.
-
-## Fault Types
-
-| Type | Triggered By | Use Case |
-|------|--------------|----------|
-| `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 |
-
-!!! warning "Important"
-
-    All faults inherit from `CMDx::Fault` and expose result, task, context, and chain data.
-
-## Fault Handling
-
-```ruby
-begin
-  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 "Ticket processing interrupted: #{e.message}"
-  rollback_changes
-end
-```
-
-## Data Access
-
-Access rich execution data from fault exceptions:
-
-```ruby
-begin
-  LicenseActivation.execute!(license_key: key, machine_id: machine)
-rescue CMDx::Fault => e
-  # Result information
-  e.result.state     #=> "interrupted"
-  e.result.status    #=> "failed" or "skipped"
-  e.result.reason    #=> "License key already activated"
-
-  # Task information
-  e.task.class       #=> <LicenseActivation>
-  e.task.id          #=> "abc123..."
-
-  # Context data
-  e.context.license_key #=> "ABC-123-DEF"
-  e.context.machine_id  #=> "[FILTERED]"
-
-  # Chain information
-  e.chain.id         #=> "def456..."
-  e.chain.size       #=> 3
-end
-```
-
-## Advanced Matching
-
-### Task-Specific Matching
-
-Handle faults only from specific tasks using `for?`:
-
-```ruby
-begin
-  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
-  quarantine_for_review(e.context.document_id)
-end
-```
-
-### Custom Logic Matching
-
-```ruby
-begin
-  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
-
-Propagate failures with `throw!` to preserve context and maintain the error chain:
-
-### Basic Propagation
-
-```ruby
-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?
-
-    # Only throw if failed
-    data_result = DataProcessor.execute(context)
-    throw!(data_result) if data_result.failed?
-
-    # Continue processing
-    generate_report
-  end
-end
-```
-
-### Additional Metadata
-
-```ruby
-class BatchProcessor < CMDx::Task
-  def work
-    step_result = FileValidation.execute(context)
-
-    if step_result.failed?
-      throw!(step_result, {
-        batch_stage: "validation",
-        can_retry: true,
-        next_step: "file_repair"
-      })
-    end
-
-    continue_batch
-  end
-end
-```
-
-## Chain Analysis
-
-Trace fault origins and propagation through the execution chain:
-
-```ruby
-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.reason}"
-  end
-
-  # Find what propagated the failure
-  thrower = result.threw_failure
-  puts "Propagated by: #{thrower.task.class.name}" if thrower
-
-  # Analyze failure type
-  case
-  when result.caused_failure?
-    puts "This task was the original source"
-  when result.threw_failure?
-    puts "This task propagated a failure"
-  when result.thrown_failure?
-    puts "This task failed due to propagation"
-  end
-end
-```

data/docs/interruptions/halt.md

@@ -1,216 +0,0 @@
-# Interruptions - Halt
-
-Stop task execution intentionally using `skip!` or `fail!`. Both methods signal clear intent about why execution stopped.
-
-## Skipping
-
-Use `skip!` when the task doesn't need to run. It's a no-op, not an error.
-
-!!! warning "Important"
-
-    Skipped tasks are considered "good" outcomes—they succeeded by doing nothing.
-
-```ruby
-class ProcessInventory < CMDx::Task
-  def work
-    # Without a reason
-    skip! if Array(ENV["DISABLED_TASKS"]).include?(self.class.name)
-
-    # With a reason
-    skip!("Warehouse closed") unless Time.now.hour.between?(8, 18)
-
-    inventory = Inventory.find(context.inventory_id)
-
-    if inventory.already_counted?
-      skip!("Inventory already counted today")
-    else
-      inventory.count!
-    end
-  end
-end
-
-result = ProcessInventory.execute(inventory_id: 456)
-
-# Executed
-result.status #=> "skipped"
-
-# Without a reason
-result.reason #=> "Unspecified"
-
-# With a reason
-result.reason #=> "Warehouse closed"
-```
-
-## Failing
-
-Use `fail!` when the task can't complete successfully. It signals controlled, intentional failure:
-
-```ruby
-class ProcessRefund < CMDx::Task
-  def work
-    # Without a reason
-    fail! if Array(ENV["DISABLED_TASKS"]).include?(self.class.name)
-
-    refund = Refund.find(context.refund_id)
-
-    # With a reason
-    if refund.expired?
-      fail!("Refund period has expired")
-    elsif !refund.amount.positive?
-      fail!("Refund amount must be positive")
-    else
-      refund.process!
-    end
-  end
-end
-
-result = ProcessRefund.execute(refund_id: 789)
-
-# Executed
-result.status #=> "failed"
-
-# Without a reason
-result.reason #=> "Unspecified"
-
-# With a reason
-result.reason #=> "Refund period has expired"
-```
-
-## Metadata Enrichment
-
-Enrich halt calls with metadata for better debugging and error handling:
-
-```ruby
-class ProcessRenewal < CMDx::Task
-  def work
-    license = License.find(context.license_id)
-
-    if license.already_renewed?
-      # Without metadata
-      skip!("License already renewed")
-    end
-
-    unless license.renewal_eligible?
-      # With metadata
-      fail!(
-        "License not eligible for renewal",
-        error_code: "LICENSE.NOT_ELIGIBLE",
-        retry_after: Time.current + 30.days
-      )
-    end
-
-    process_renewal
-  end
-end
-
-result = ProcessRenewal.execute(license_id: 567)
-
-# Without metadata
-result.metadata #=> {}
-
-# With metadata
-result.metadata #=> {
-                #     error_code: "LICENSE.NOT_ELIGIBLE",
-                #     retry_after: <Time 30 days from now>
-                #   }
-```
-
-## State Transitions
-
-Halt methods trigger specific state and status transitions:
-
-| Method | State | Status | Outcome |
-|--------|-------|--------|---------|
-| `skip!` | `interrupted` | `skipped` | `good? = true`, `bad? = true` |
-| `fail!` | `interrupted` | `failed` | `good? = false`, `bad? = true` |
-
-```ruby
-result = ProcessRenewal.execute(license_id: 567)
-
-# 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
-```
-
-## Execution Behavior
-
-Halt methods behave differently depending on the call method used:
-
-### Non-bang execution
-
-Returns result object without raising exceptions:
-
-```ruby
-result = ProcessRefund.execute(refund_id: 789)
-
-case result.status
-when "success"
-  puts "Refund processed: $#{result.context.refund.amount}"
-when "skipped"
-  puts "Refund skipped: #{result.reason}"
-when "failed"
-  puts "Refund failed: #{result.reason}"
-  handle_refund_error(result.metadata[:error_code])
-end
-```
-
-### Bang execution
-
-Raises exceptions for halt conditions based on `task_breakpoints` configuration:
-
-```ruby
-begin
-  result = ProcessRefund.execute!(refund_id: 789)
-  puts "Success: Refund processed"
-rescue CMDx::SkipFault => e
-  puts "Skipped: #{e.message}"
-rescue CMDx::FailFault => e
-  puts "Failed: #{e.message}"
-  handle_refund_failure(e.result.metadata[:error_code])
-end
-```
-
-## Best Practices
-
-Always provide a reason for better debugging and clearer exception messages:
-
-```ruby
-# Good: Clear, specific reason
-skip!("Document processing paused for compliance review")
-fail!("File format not supported by processor", code: "FORMAT_UNSUPPORTED")
-
-# Acceptable: Generic, non-specific reason
-skip!("Paused")
-fail!("Unsupported")
-
-# Bad: Default, cannot determine reason
-skip! #=> "Unspecified"
-fail! #=> "Unspecified"
-```
-
-## Manual Errors
-
-For rare cases, manually add errors before halting:
-
-!!! warning "Important"
-
-    Manual errors don't stop execution—you still need to call `fail!` or `skip!`.
-
-```ruby
-class ProcessRenewal < CMDx::Task
-  def work
-    if document.nonrenewable?
-      errors.add(:document, "not renewable")
-      fail!("document could not be renewed")
-    else
-      document.renew!
-    end
-  end
-end
-```

data/docs/logging.md

@@ -1,94 +0,0 @@
-# Logging
-
-CMDx automatically logs every task execution with structured data, making debugging and monitoring effortless. Choose from multiple formatters to match your logging infrastructure.
-
-## Formatters
-
-Choose the format that works best for your logging system:
-
-| Formatter | Use Case | Output Style |
-|-----------|----------|--------------|
-| `Line` | Traditional logging | Single-line format |
-| `Json` | Structured systems | Compact JSON |
-| `KeyValue` | Log parsing | `key=value` pairs |
-| `Logstash` | ELK stack | JSON with @version/@timestamp |
-| `Raw` | Minimal output | Message content only |
-
-Sample output:
-
-```log
-<!-- Success (INFO level) -->
-I, [2022-07-17T18:43:15.000000 #3784] INFO -- GenerateInvoice:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
-
-<!-- Skipped (WARN level) -->
-W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidateCustomer:
-index=1 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="ValidateCustomer" state="interrupted" status="skipped" reason="Customer already validated"
-
-<!-- Failed (ERROR level) -->
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CalculateTax:
-index=2 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="CalculateTax"  state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
-
-<!-- Failed Chain -->
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- BillingWorkflow:
-index=3 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="BillingWorkflow"  state="interrupted" status="failed" caused_failure={index: 2, class: "CalculateTax", status: "failed"} threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
-```
-
-!!! tip
-
-    Use logging as a low-level event stream to track all tasks in a request. Combine with correlation for powerful distributed tracing.
-
-## Structure
-
-Every log entry includes rich metadata. Available fields depend on execution context and outcome.
-
-### Core Fields
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| `severity` | Log level | `INFO`, `WARN`, `ERROR` |
-| `timestamp` | ISO 8601 execution time | `2022-07-17T18:43:15.000000` |
-| `pid` | Process ID | `3784` |
-
-### Task Information
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| `index` | Execution sequence position | `0`, `1`, `2` |
-| `chain_id` | Unique execution chain ID | `018c2b95-b764-7615...` |
-| `type` | Execution unit type | `Task`, `Workflow` |
-| `class` | Task class name | `GenerateInvoiceTask` |
-| `id` | Unique task instance ID | `018c2b95-b764-7615...` |
-| `tags` | Custom categorization | `["billing", "financial"]` |
-
-### Execution Data
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| `state` | Lifecycle state | `complete`, `interrupted` |
-| `status` | Business outcome | `success`, `skipped`, `failed` |
-| `outcome` | Final classification | `success`, `interrupted` |
-| `metadata` | Custom task data | `{order_id: 123, amount: 99.99}` |
-
-### Failure Chain
-
-| Field | Description |
-|-------|-------------|
-| `reason` | Reason given for the stoppage |
-| `caused` | Cause exception details |
-| `caused_failure` | Original failing task details |
-| `threw_failure` | Task that propagated the failure |
-
-## Usage
-
-Access the framework logger directly within tasks:
-
-```ruby
-class ProcessSubscription < CMDx::Task
-  def work
-    logger.debug { "Activated feature flags: #{Features.active_flags}" }
-    # Your logic here...
-    logger.info("Subscription processed")
-  end
-end
-```

data/docs/middlewares.md

@@ -1,191 +0,0 @@
-# Middlewares
-
-Wrap task execution with middleware for cross-cutting concerns like authentication, caching, timeouts, and monitoring. Think Rack middleware, but for your business logic.
-
-See [Global Configuration](getting_started.md#middlewares) for framework-wide setup.
-
-## Execution Order
-
-Middleware wraps task execution in layers, like an onion:
-
-!!! note
-
-    First registered = outermost wrapper. They execute in registration order.
-
-```ruby
-class ProcessCampaign < CMDx::Task
-  register :middleware, AuditMiddleware         # 1st: outermost wrapper
-  register :middleware, AuthorizationMiddleware # 2nd: middle wrapper
-  register :middleware, CacheMiddleware         # 3rd: innermost wrapper
-
-  def work
-    # Your logic here...
-  end
-end
-
-# Execution flow:
-# 1. AuditMiddleware (before)
-# 2.   AuthorizationMiddleware (before)
-# 3.     CacheMiddleware (before)
-# 4.       [task execution]
-# 5.     CacheMiddleware (after)
-# 6.   AuthorizationMiddleware (after)
-# 7. AuditMiddleware (after)
-```
-
-## Declarations
-
-### Proc or Lambda
-
-Use anonymous functions for simple middleware logic:
-
-```ruby
-class ProcessCampaign < CMDx::Task
-  # Proc
-  register :middleware, proc do |task, options, &block|
-    result = block.call
-    Analytics.track(result.status)
-    result
-  end
-
-  # Lambda
-  register :middleware, ->(task, options, &block) {
-    result = block.call
-    Analytics.track(result.status)
-    result
-  }
-end
-```
-
-### Class or Module
-
-For complex middleware logic, use classes or modules:
-
-```ruby
-class TelemetryMiddleware
-  def call(task, options)
-    result = yield
-    Telemetry.record(result.status)
-  ensure
-    result # Always return result
-  end
-end
-
-class ProcessCampaign < CMDx::Task
-  # Class or Module
-  register :middleware, TelemetryMiddleware
-
-  # Instance
-  register :middleware, TelemetryMiddleware.new
-
-  # With options
-  register :middleware, MonitoringMiddleware, service_key: ENV["MONITORING_KEY"]
-  register :middleware, MonitoringMiddleware.new(ENV["MONITORING_KEY"])
-end
-```
-
-## Removals
-
-Remove class or module-based middleware globally or per-task:
-
-!!! warning
-
-    Each `deregister` call removes one middleware. Use multiple calls for batch removals.
-
-```ruby
-class ProcessCampaign < CMDx::Task
-  # Class or Module (no instances)
-  deregister :middleware, TelemetryMiddleware
-end
-```
-
-## Built-in
-
-### Timeout
-
-Prevent tasks from running too long:
-
-```ruby
-class ProcessReport < CMDx::Task
-  # Default timeout: 3 seconds
-  register :middleware, CMDx::Middlewares::Timeout
-
-  # Seconds (takes Numeric, Symbol, Proc, Lambda, Class, Module)
-  register :middleware, CMDx::Middlewares::Timeout, seconds: :max_processing_time
-
-  # If or Unless (takes Symbol, Proc, Lambda, Class, Module)
-  register :middleware, CMDx::Middlewares::Timeout, unless: -> { self.class.name.include?("Quick") }
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def max_processing_time
-    Rails.env.production? ? 2 : 10
-  end
-end
-
-# Slow task
-result = ProcessReport.execute
-
-result.state    #=> "interrupted"
-result.status   #=> "failure"
-result.reason   #=> "[CMDx::TimeoutError] execution exceeded 3 seconds"
-result.cause    #=> <CMDx::TimeoutError>
-result.metadata #=> { limit: 3 }
-```
-
-### Correlate
-
-Add correlation IDs for distributed tracing and request tracking:
-
-```ruby
-class ProcessExport < CMDx::Task
-  # Default correlation ID generation
-  register :middleware, CMDx::Middlewares::Correlate
-
-  # Seconds (takes Object, Symbol, Proc, Lambda, Class, Module)
-  register :middleware, CMDx::Middlewares::Correlate, id: proc { |task| task.context.session_id }
-
-  # If or Unless (takes Symbol, Proc, Lambda, Class, Module)
-  register :middleware, CMDx::Middlewares::Correlate, if: :correlation_enabled?
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def correlation_enabled?
-    ENV["CORRELATION_ENABLED"] == "true"
-  end
-end
-
-result = ProcessExport.execute
-result.metadata #=> { correlation_id: "550e8400-e29b-41d4-a716-446655440000" }
-```
-
-### Runtime
-
-Track task execution time in milliseconds using a monotonic clock:
-
-```ruby
-class PerformanceMonitoringCheck
-  def call(task)
-    task.context.tenant.monitoring_enabled?
-  end
-end
-
-class ProcessExport < CMDx::Task
-  # Default timeout is 3 seconds
-  register :middleware, CMDx::Middlewares::Runtime
-
-  # If or Unless (takes Symbol, Proc, Lambda, Class, Module)
-  register :middleware, CMDx::Middlewares::Runtime, if: PerformanceMonitoringCheck
-end
-
-result = ProcessExport.execute
-result.metadata #=> { runtime: 1247 } (ms)
-```