cmdx 1.13.0 → 1.14.0

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,90 +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, [2025-12-23T17:04:07.292614Z #20108] INFO -- cmdx: {index: 1, chain_id: "019b4c2b-087b-79be-8ef2-96c11b659df5", type: "Task", tags: [], class: "GenerateInvoice", dry_run: false, id: "019b4c2b-0878-704d-ba0b-daa5410123ec", state: "complete", status: "success", outcome: "success", metadata: {runtime: 187}}
-
-<!-- Skipped (INFO level) -->
-I, [2025-12-23T17:04:11.496881Z #20139] INFO -- cmdx: {index: 2, chain_id: "019b4c2b-18e8-7af6-a38b-63b042c4fbed", type: "Task", tags: [], class: "ValidateCustomer", dry_run: false, id: "019b4c2b-18e5-7230-af7e-5b4a4bd7cda2", state: "interrupted", status: "skipped", outcome: "skipped", metadata: {}, reason: "Customer already validated", cause: #<CMDx::SkipFault: Customer already validated>, rolled_back: false}
-
-<!-- Failed (INFO level) -->
-I, [2025-12-23T17:04:15.875306Z #20173] INFO -- cmdx: {index: 3, chain_id: "019b4c2b-2a02-7dbc-b713-b20a7379704f", type: "Task", tags: [], class: "CalculateTax", dry_run: false, id: "019b4c2b-2a00-70b7-9fab-2f14db9139ef", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}
-
-<!-- Failed Chain -->
-I, [2025-12-23T17:04:20.972539Z #20209] INFO -- cmdx: {index: 0, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Workflow", tags: [], class: "BillingWorkflow", dry_run: false, id: "019b4c2b-3de6-70b9-9c16-5be13b1a463c", state: "interrupted", status: "failed", outcome: "interrupted", metadata: {}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false, threw_failure: {index: 3, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Task", tags: [], class: "CalculateTax", id: "019b4c2b-3dec-70b3-969b-c5b7896e3b27", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}, caused_failure: {index: 3, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Task", tags: [], class: "CalculateTax", id: "019b4c2b-3dec-70b3-969b-c5b7896e3b27", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}}
-```
-
-!!! 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)
-```

data/docs/outcomes/result.md

@@ -1,197 +0,0 @@
-# Outcomes - Result
-
-Results are your window into task execution. They expose everything: outcome, state, timing, context, and metadata.
-
-## Result Attributes
-
-Access essential execution information:
-
-!!! warning "Important"
-
-    Results are immutable after execution completes.
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-# Object data
-result.task     #=> <BuildApplication>
-result.context  #=> <CMDx::Context>
-result.chain    #=> <CMDx::Chain>
-
-# Execution data
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-
-# Fault data
-result.reason   #=> "Build tool not found"
-result.cause    #=> <CMDx::FailFault>
-result.metadata #=> { error_code: "BUILD_TOOL.NOT_FOUND" }
-```
-
-## Lifecycle Information
-
-Check execution state, status, and rollback with predicate methods:
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-# State predicates (execution lifecycle)
-result.complete?    #=> true (successful completion)
-result.interrupted? #=> false (no interruption)
-result.executed?    #=> true (execution finished)
-
-# Status predicates (execution outcome)
-result.success?     #=> true (successful execution)
-result.failed?      #=> false (no failure)
-result.skipped?     #=> false (not skipped)
-
-# Outcome categorization
-result.good?        #=> true (success or skipped)
-result.bad?         #=> false (skipped or failed)
-
-# Rollback Status
-result.rolled_back? #=> true (execution was rolled back)
-```
-
-## Outcome Analysis
-
-Get a unified outcome string combining state and status:
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-result.outcome #=> "success" (state and status)
-```
-
-## Chain Analysis
-
-Trace fault origins and propagation:
-
-```ruby
-result = DeploymentWorkflow.execute(app_name: "webapp")
-
-if result.failed?
-  # Find the original cause of failure
-  if original_failure = result.caused_failure
-    puts "Root cause: #{original_failure.task.class.name}"
-    puts "Reason: #{original_failure.reason}"
-  end
-
-  # Find what threw the failure to this result
-  if throwing_task = result.threw_failure
-    puts "Failure source: #{throwing_task.task.class.name}"
-    puts "Reason: #{throwing_task.reason}"
-  end
-
-  # Failure classification
-  result.caused_failure?  #=> true if this result was the original cause
-  result.threw_failure?   #=> true if this result threw a failure
-  result.thrown_failure?  #=> true if this result received a thrown failure
-end
-```
-
-## Index and Position
-
-Results track their position within execution chains:
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-# Position in execution sequence
-result.index #=> 0 (first task in chain)
-
-# Access via chain
-result.chain.results[result.index] == result #=> true
-```
-
-## Block Yield
-
-Execute code with direct result access:
-
-```ruby
-BuildApplication.execute(version: "1.2.3") do |result|
-  if result.success?
-    notify_deployment_ready(result)
-  elsif result.failed?
-    handle_build_failure(result)
-  else
-    log_skip_reason(result)
-  end
-end
-```
-
-## Handlers
-
-Handle outcomes with functional-style methods. Handlers return the result for chaining:
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-# Status-based handlers
-result
-  .on(:success) { |result| notify_deployment_ready(result) }
-  .on(:failed) { |result| handle_build_failure(result) }
-  .on(:skipped) { |result| log_skip_reason(result) }
-
-# State-based handlers
-result
-  .on(:complete) { |result| update_build_status(result) }
-  .on(:interrupted) { |result| cleanup_partial_artifacts(result) }
-  .on(:executed) { |result| alert_operations_team(result) } #=> .on(:complete, :interrupted)
-
-# Outcome-based handlers
-result
-  .on(:good) { |result| increment_success_counter(result) } #=> .on(:success, :skipped)
-  .on(:bad) { |result| alert_operations_team(result) }      #=> .on(:failed, :skipped)
-```
-
-## Pattern Matching
-
-Use Ruby 3.0+ pattern matching for elegant outcome handling:
-
-!!! warning "Important"
-
-    Pattern matching works with both array and hash deconstruction.
-
-### Array Pattern
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-case result
-in ["complete", "success"]
-  redirect_to build_success_page
-in ["interrupted", "failed"]
-  retry_build_with_backoff(result)
-in ["interrupted", "skipped"]
-  log_skip_and_continue
-end
-```
-
-### Hash Pattern
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-case result
-in { state: "complete", status: "success" }
-  celebrate_build_success
-in { status: "failed", metadata: { retryable: true } }
-  schedule_build_retry(result)
-in { bad: true, metadata: { reason: String => reason } }
-  escalate_build_error("Build failed: #{reason}")
-end
-```
-
-### Pattern Guards
-
-```ruby
-case result
-in { status: "failed", metadata: { attempts: n } } if n < 3
-  retry_build_with_delay(result, n * 2)
-in { status: "failed", metadata: { attempts: n } } if n >= 3
-  mark_build_permanently_failed(result)
-in { runtime: time } if time > performance_threshold
-  investigate_build_performance(result)
-end
-```