cmdx 1.12.0 → 1.14.0

data/docs/workflows.md

@@ -1,226 +0,0 @@
-# Workflows
-
-Compose multiple tasks into powerful, sequential pipelines. Workflows provide a declarative way to build complex business processes with conditional execution, shared context, and flexible error handling.
-
-## Declarations
-
-Tasks run in declaration order (FIFO), sharing a common context across the pipeline.
-
-!!! warning
-
-    Don't define a `work` method in workflows—the module handles execution automatically.
-
-### Task
-
-```ruby
-class OnboardingWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task CreateUserProfile
-  task SetupAccountPreferences
-
-  tasks SendWelcomeEmail, SendWelcomeSms, CreateDashboard
-end
-```
-
-!!! tip
-
-    Execute tasks in parallel via the [cmdx-parallel](https://github.com/drexed/cmdx-parallel) gem.
-
-### Group
-
-Group related tasks to share configuration:
-
-!!! warning "Important"
-
-    Settings and conditionals apply to all tasks in the group.
-
-```ruby
-class ContentModerationWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  # Screening phase
-  tasks ScanForProfanity, CheckForSpam, ValidateImages, breakpoints: ["skipped"]
-
-  # Review phase
-  tasks ApplyFilters, ScoreContent, FlagSuspicious
-
-  # Decision phase
-  tasks PublishContent, QueueForReview, NotifyModerators
-end
-```
-
-### Conditionals
-
-Conditionals support multiple syntaxes for flexible execution control:
-
-```ruby
-class ContentAccessCheck
-  def call(task)
-    task.context.user.can?(:publish_content)
-  end
-end
-
-class OnboardingWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  # If and/or Unless
-  task SendWelcomeEmail, if: :email_configured?, unless: :email_disabled?
-
-  # Proc
-  task SendWelcomeEmail, if: -> { Rails.env.production? && self.class.name.include?("Premium") }
-
-  # Lambda
-  task SendWelcomeEmail, if: proc { context.features_enabled? }
-
-  # Class or Module
-  task SendWelcomeEmail, unless: ContentAccessCheck
-
-  # Instance
-  task SendWelcomeEmail, if: ContentAccessCheck.new
-
-  # Conditional applies to all tasks of this declaration group
-  tasks SendWelcomeEmail, CreateDashboard, SetupTutorial, if: :email_configured?
-
-  private
-
-  def email_configured?
-    context.user.email_address == true
-  end
-
-  def email_disabled?
-    context.user.communication_preference == :disabled
-  end
-end
-```
-
-## Halt Behavior
-
-By default, skipped tasks don't stop the workflow—they're treated as no-ops. Configure breakpoints globally or per-task to customize this behavior.
-
-```ruby
-class AnalyticsWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task CollectMetrics      # If fails → workflow stops
-  task FilterOutliers      # If skipped → workflow continues
-  task GenerateDashboard   # Only runs if no failures occurred
-end
-```
-
-### Task Configuration
-
-Configure halt behavior for the entire workflow:
-
-```ruby
-class SecurityWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  # Halt on both failed and skipped results
-  settings(workflow_breakpoints: ["skipped", "failed"])
-
-  task PerformSecurityScan
-  task ValidateSecurityRules
-end
-
-class OptionalTasksWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  # Never halt, always continue
-  settings(breakpoints: [])
-
-  task TryBackupData
-  task TryCleanupLogs
-  task TryOptimizeCache
-end
-```
-
-### Group Configuration
-
-Different task groups can have different halt behavior:
-
-```ruby
-class SubscriptionWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task CreateSubscription, ValidatePayment, workflow_breakpoints: ["skipped", "failed"]
-
-  # Never halt, always continue
-  task SendConfirmationEmail, UpdateBilling, breakpoints: []
-end
-```
-
-## Nested Workflows
-
-Build hierarchical workflows by composing workflows within workflows:
-
-```ruby
-class EmailPreparationWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task ValidateRecipients
-  task CompileTemplate
-end
-
-class EmailDeliveryWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  tasks SendEmails, TrackDeliveries
-end
-
-class CompleteEmailWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task EmailPreparationWorkflow
-  task EmailDeliveryWorkflow, if: proc { context.preparation_successful? }
-  task GenerateDeliveryReport
-end
-```
-
-## Parallel Execution
-
-Run tasks concurrently using the [Parallel](https://github.com/grosser/parallel) gem. It automatically uses all available processors for maximum throughput.
-
-!!! warning
-
-    Context is read-only during parallel execution. Load all required data beforehand.
-
-```ruby
-class SendWelcomeNotifications < CMDx::Task
-  include CMDx::Workflow
-
-  # Default options (dynamically calculated to available processors)
-  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel
-
-  # Fix number of threads
-  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_threads: 2
-
-  # Fix number of forked processes
-  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_processes: 2
-
-  # NOTE: Reactors are not supported
-end
-```
-
-## Task Generator
-
-Generate new CMDx workflow tasks quickly using the built-in generator:
-
-```bash
-rails generate cmdx:workflow SendNotifications
-```
-
-This creates a new workflow task file with the basic structure:
-
-```ruby
-# app/tasks/send_notifications.rb
-class SendNotifications < CMDx::Task
-  include CMDx::Workflow
-
-  tasks Task1, Task2
-end
-```
-
-!!! tip
-
-    Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`

data/examples/active_record_database_transaction.md

@@ -1,27 +0,0 @@
-# Active Record Query Tagging
-
-Wrap task or workflow execution in a database transaction. This is essential for data integrity when multiple steps modify the database.
-
-### Setup
-
-```ruby
-# lib/cmdx_database_transaction_middleware.rb
-class CmdxDatabaseTransactionMiddleware
-  def self.call(task, **options, &)
-    ActiveRecord::Base.transaction(requires_new: true, &)
-  end
-end
-```
-
-### Usage
-
-```ruby
-class MyTask < CMDx::Task
-  register :middleware, CmdxDatabaseTransactionMiddleware
-
-  def work
-    # Do work...
-  end
-
-end
-```

data/examples/active_record_query_tagging.md

@@ -1,46 +0,0 @@
-# Active Record Query Tagging
-
-Add a comment to every query indicating some context to help you track down where that query came from, eg:
-
-```sh
-/*cmdx_task_class:ExportReportTask,cmdx_chain_id:018c2b95-b764-7615*/ SELECT * FROM reports WHERE id = 1
-```
-
-### Setup
-
-```ruby
-# config/application.rb
-config.active_record.query_log_tags_enabled = true
-config.active_record.query_log_tags += [
-  :cmdx_correlation_id,
-  :cmdx_chain_id,
-  :cmdx_task_class,
-  :cmdx_task_id
-]
-
-# lib/cmdx_query_tagging_middleware.rb
-class CmdxQueryTaggingMiddleware
-  def self.call(task, **options, &)
-    ActiveSupport::ExecutionContext.set(
-      cmdx_correlation_id: task.result.metadata[:correlation_id],
-      cmdx_chain_id: task.chain.id,
-      cmdx_task_class: task.class.name,
-      cmdx_task_id: task.id,
-      &
-    )
-  end
-end
-```
-
-### Usage
-
-```ruby
-class MyTask < CMDx::Task
-  register :middleware, CmdxQueryTaggingMiddleware
-
-  def work
-    # Do work...
-  end
-
-end
-```

data/examples/flipper_feature_flags.md

@@ -1,50 +0,0 @@
-# Flipper Feature Flags
-
-Control task execution based on Flipper feature flags.
-
-<https://github.com/flippercloud/flipper>
-
-### Setup
-
-```ruby
-# lib/cmdx_flipper_middleware.rb
-class CmdxFlipperMiddleware
-  def self.call(task, **options, &)
-    feature_name = options.fetch(:feature)
-    actor = options.fetch(:actor, -> { task.context[:user] })
-
-    # Resolve actor if it's a proc
-    actor = actor.call if actor.respond_to?(:call)
-
-    if Flipper.enabled?(feature_name, actor)
-      yield
-    else
-      # Option 1: Skip the task
-      task.skip!("Feature #{feature_name} is disabled")
-
-      # Option 2: Fail the task
-      # task.fail!("Feature #{feature_name} is disabled")
-    end
-  end
-end
-```
-
-### Usage
-
-```ruby
-class NewFeatureTask < CMDx::Task
-  # Execute only if :new_feature is enabled for the user in context
-  register :middleware, CmdxFlipperMiddleware,
-    feature: :new_feature
-
-  # Customize the actor resolution
-  register :middleware, CmdxFlipperMiddleware,
-    feature: :beta_access,
-    actor: -> { task.context[:company] }
-
-  def work
-    # ...
-  end
-end
-```
-

data/examples/paper_trail_whatdunnit.md

@@ -1,39 +0,0 @@
-# Paper Trail Whatdunnit
-
-Tag paper trail version records with which service made a change with a custom `whatdunnit` attribute.
-
-<https://github.com/paper-trail-gem/paper_trail?tab=readme-ov-file#4c-storing-metadata>
-
-### Setup
-
-```ruby
-# lib/cmdx_paper_trail_middleware.rb
-class CmdxPaperTrailMiddleware
-  def self.call(task, **options, &)
-    # This makes sure to reset the whatdunnit value to the previous
-    # value for nested task calls
-
-    begin
-      PaperTrail.request.controller_info ||= {}
-      old_whatdunnit = PaperTrail.request.controller_info[:whatdunnit]
-      PaperTrail.request.controller_info[:whatdunnit] = task.class.name
-      yield
-    ensure
-      PaperTrail.request.controller_info[:whatdunnit] = old_whatdunnit
-    end
-  end
-end
-```
-
-### Usage
-
-```ruby
-class MyTask < CMDx::Task
-  register :middleware, CmdxPaperTrailMiddleware
-
-  def work
-    # Do work...
-  end
-
-end
-```

data/examples/redis_idempotency.md

@@ -1,71 +0,0 @@
-# Redis Idempotency
-
-Ensure tasks are executed exactly once using Redis to store execution state. This is critical for non-idempotent operations like charging a credit card or sending an email.
-
-### Setup
-
-```ruby
-# lib/cmdx_redis_idempotency_middleware.rb
-class CmdxRedisIdempotencyMiddleware
-  def self.call(task, **options, &block)
-    key = generate_key(task, options[:key])
-    ttl = options[:ttl] || 5.minutes.to_i
-
-    # Attempt to lock the key
-    if Redis.current.set(key, "processing", nx: true, ex: ttl)
-      begin
-        block.call.tap |result|
-          Redis.current.set(key, result.status, xx: true, ex: ttl)
-        end
-      rescue => e
-        Redis.current.del(key)
-        raise(e)
-      end
-    else
-      # Key exists, handle duplicate
-      status = Redis.current.get(key)
-
-      if status == "processing"
-        task.result.tap { |r| r.skip!("Duplicate request: currently processing", halt: true) }
-      else
-        task.result.tap { |r| r.skip!("Duplicate request: already processed (#{status})", halt: true) }
-      end
-    end
-  end
-
-  def self.generate_key(task, key_gen)
-    id = if key_gen.respond_to?(:call)
-           key_gen.call(task)
-         elsif key_gen.is_a?(Symbol)
-           task.send(key_gen)
-         else
-           task.context[:idempotency_key]
-         end
-
-    "cmdx:idempotency:#{task.class.name}:#{id}"
-  end
-end
-```
-
-### Usage
-
-```ruby
-class ChargeCustomer < CMDx::Task
-  # Use context[:payment_id] as the unique key
-  register :middleware, CmdxIdempotencyMiddleware,
-    key: ->(t) { t.context[:payment_id] }
-
-  def work
-    # Charge logic...
-  end
-end
-
-# First run: Executes
-ChargeCustomer.call(payment_id: "123")
-# => Success
-
-# Second run: Skips
-ChargeCustomer.call(payment_id: "123")
-# => Skipped (reason: "Duplicate request: already processed (success)")
-```
-

data/examples/sentry_error_tracking.md

@@ -1,46 +0,0 @@
-# Sentry Error Tracking
-
-Report unhandled exceptions and unexpected task failures to Sentry with detailed context.
-
-<https://github.com/getsentry/sentry-ruby>
-
-### Setup
-
-```ruby
-# lib/cmdx_sentry_middleware.rb
-class CmdxSentryMiddleware
-  def self.call(task, **options, &)
-    Sentry.with_scope do |scope|
-      scope.set_tags(task: task.class.name)
-      scope.set_context(:user, Current.user.sentry_attributes)
-
-      yield.tap do |result|
-        # Optional: Report logical failures if needed
-        if Array(options[:report_on]).include?(result.status)
-          Sentry.capture_message("Task #{result.status}: #{result.reason}", level: :warning)
-        end
-      end
-    end
-  rescue => e
-    Sentry.capture_exception(e)
-    raise(e) # Re-raise to let the task handle the error or bubble up
-  end
-end
-```
-
-### Usage
-
-```ruby
-class ProcessPayment < CMDx::Task
-  # Report exceptions only
-  register :middleware, CmdxSentryMiddleware
-
-  # Report exceptions AND logical failures (result.failure?)
-  register :middleware, CmdxSentryMiddleware, report_on: %w[failed skipped]
-
-  def work
-    # ...
-  end
-end
-```
-

data/examples/sidekiq_async_execution.md

@@ -1,29 +0,0 @@
-# Sidekiq Async Execute
-
-Execute tasks asynchronously using Sidekiq without creating separate job classes.
-
-<https://github.com/sidekiq/sidekiq>
-
-### Setup
-
-```ruby
-class MyTask < CMDx::Task
-  include Sidekiq::Job
-
-  def work
-    # Do work...
-  end
-
-  # Use execute! to trigger Sidekiq's retry logic on failures/exceptions.
-  def perform
-    self.class.execute!
-  end
-
-end
-```
-
-### Usage
-
-```ruby
-MyTask.perform_async
-```

data/examples/stoplight_circuit_breaker.md

@@ -1,36 +0,0 @@
-# Stoplight Circuit Breaker
-
-Integrate circuit breakers to protect external service calls and prevent cascading failures when dependencies are unavailable.
-
-<https://github.com/bolshakov/stoplight>
-
-### Setup
-
-```ruby
-# lib/cmdx_stoplight_middleware.rb
-class CmdxStoplightMiddleware
-  def self.call(task, **options, &)
-    light = Stoplight(options[:name] || task.class.name, **options)
-    light.run(&)
-  rescue Stoplight::Error::RedLight => e
-    task.result.tap { |r| r.fail!("[#{e.class}] #{e.message}", cause: e) }
-  end
-end
-```
-
-### Usage
-
-```ruby
-class MyTask < CMDx::Task
-  # With default options
-  register :middleware, CmdxStoplightMiddleware
-
-  # With stoplight options
-  register :middleware, CmdxStoplightMiddleware, cool_off_time: 10
-
-  def work
-    # Do work...
-  end
-
-end
-```

data/src/cmdx-favicon.svg

@@ -1 +0,0 @@
-<svg width="104.098" height="112.266" viewBox="0 0 60 64.708" xmlns="http://www.w3.org/2000/svg"><path d="M29.907 17.723 26.4 23.17 13.384 3.323h3.507l9.508 14.77 1.938-3.139L18.737 0H7.291L26.4 29.262 45.045 0h-3.97L30 17.54zM9.23 61.293H6.091l18.646-29.447L4.43.093H.46l20.308 31.846L0 64.708l10.985-.092 39.138-61.2h3.323L31.57 37.754l13.662 21.415h3.97L35.445 37.754 59.537.093H48.37zm29.63-23.262 15.047 23.262H43.384l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H60L41.17 35.354l-.278-.461z" fill="#000"/></svg>

data/src/cmdx-logo.svg

@@ -1 +0,0 @@
-<svg width="352.2" height="112.266" viewBox="0 0 203 64.708" xmlns="http://www.w3.org/2000/svg" xmlSpace="preserve"><path d="M172.908 17.723 169.4 23.17 156.385 3.323h3.507l9.508 14.77 1.938-3.139L161.738 0h-11.446L169.4 29.262 188.046 0h-3.97L173 17.54zm-20.677 43.57h-3.139l18.646-29.447L147.431.093h-3.97l20.308 31.846L143 64.708l10.985-.092 39.138-61.2h3.323L174.57 37.754l13.662 21.415h3.969l-13.754-21.415L202.538.093H191.37zm29.63-23.262 15.047 23.262h-10.523l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H203l-18.83-29.262-.278-.461z" fill="#fe1817"/><path d="M41.667 14v12.8h-23.42c-3.214.272-5.665 3.05-5.665 6.318s2.45 5.937 5.664 6.318H33.17v4.248H18.246a10.65 10.65 0 0 1-9.858-10.62c0-5.447 4.194-10.077 9.64-10.512h19.39v-4.303H18.246v.054A14.823 14.823 0 0 0 4.248 33.118c0 7.898 6.21 14.38 13.998 14.815h19.172v-8.497h4.249v12.745h-23.42A19.063 19.063 0 0 1 0 33.118a19.033 19.033 0 0 1 18.246-19.063zM75 35.623 87.2 14h13.508v38.181H87.963v-14.27l-8.116 14.27h-9.749L57.734 30.504v-8.007l14.87 25.436h4.792l14.815-25.436v25.436h4.249V18.249H89.65l-14.76 25.49-14.542-25.49H53.54v29.684h4.194v-8.007l4.249 7.299v4.956H49.292v-38.18H62.8zM108.333 14h23.42C141.94 14.436 150 22.824 150 33.064c0 10.294-8.061 18.681-18.246 19.117h-23.42V22.497h23.42a10.65 10.65 0 0 1 9.858 10.621c0 5.447-4.194 10.13-9.64 10.566H116.83V30.286h4.248v9.15l10.676-.054c3.213-.273 5.664-3.05 5.664-6.264 0-2.778-1.743-5.065-4.194-5.991-.926-.382-1.47-.382-2.94-.382h-17.702v21.188h19.172a14.84 14.84 0 0 0 13.998-14.87c0-7.897-6.21-14.379-13.998-14.814h-23.42z"/></svg>