job-workflow 0.1.3

data/guides/DRY_RUN.md

@@ -0,0 +1,390 @@
+# Dry-Run Mode
+
+Dry-run mode allows you to test workflows without executing side effects. This is useful for:
+
+- Validating workflow logic before production deployment
+- Testing data transformations without modifying external systems
+- Debugging complex workflows safely
+- CI/CD pipeline integration for workflow validation
+
+## Basic Usage
+
+### Enabling Dry-Run Mode at Workflow Level
+
+Use the `dry_run` DSL method to enable dry-run mode for the entire workflow:
+
+```ruby
+class MyWorkflowJob < ActiveJob::Base
+  include JobWorkflow::DSL
+
+  # Always dry-run
+  dry_run true
+
+  task :send_email do |ctx|
+    if ctx.dry_run?
+      Rails.logger.info "[DRY-RUN] Would send email to #{ctx.arguments.email}"
+    else
+      Mailer.send_email(ctx.arguments.email)
+    end
+  end
+end
+```
+
+### Dynamic Dry-Run Configuration
+
+Use a Proc to dynamically determine dry-run mode based on context:
+
+```ruby
+class MyWorkflowJob < ActiveJob::Base
+  include JobWorkflow::DSL
+
+  argument :dry_run_mode, "bool", default: false
+
+  # Enable dry-run based on argument
+  dry_run { |context| context.arguments.dry_run_mode }
+
+  task :process_data do |ctx|
+    # ctx.dry_run? returns true when dry_run_mode argument is true
+  end
+end
+```
+
+### Task-Level Dry-Run
+
+You can also configure dry-run at the task level:
+
+```ruby
+class MyWorkflowJob < ActiveJob::Base
+  include JobWorkflow::DSL
+
+  task :safe_operation do |ctx|
+    # Normal execution
+  end
+
+  # This task always runs in dry-run mode
+  task :risky_operation, dry_run: true do |ctx|
+    ctx.skip_in_dry_run do
+      ExternalService.dangerous_call
+    end
+  end
+end
+```
+
+### Priority Rules
+
+When both workflow and task have dry-run configuration:
+
+1. **Workflow-level `dry_run: true`** takes priority - all tasks run in dry-run mode
+2. **Task-level settings** apply only when workflow doesn't enable dry-run
+
+```ruby
+class MyWorkflowJob < ActiveJob::Base
+  include JobWorkflow::DSL
+
+  # Workflow-level: always dry-run
+  dry_run true
+
+  # Even with dry_run: false, this task still runs in dry-run mode
+  # because workflow-level setting takes priority
+  task :task_one, dry_run: false do |ctx|
+    ctx.dry_run?  # => true (workflow setting wins)
+  end
+end
+```
+
+## Checking Dry-Run Status
+
+### Using `ctx.dry_run?`
+
+The `dry_run?` method returns the current dry-run status:
+
+```ruby
+task :process_order do |ctx|
+  if ctx.dry_run?
+    Rails.logger.info "[DRY-RUN] Would process order: #{ctx.arguments.order_id}"
+    return
+  end
+
+  Order.process(ctx.arguments.order_id)
+end
+```
+
+## Skipping Side Effects with `skip_in_dry_run`
+
+The `skip_in_dry_run` method provides a convenient way to skip side effects in dry-run mode:
+
+### Basic Usage
+
+```ruby
+task :charge_customer do |ctx|
+  ctx.skip_in_dry_run do
+    PaymentGateway.charge(ctx.arguments.amount)
+  end
+end
+```
+
+In dry-run mode:
+- The block is **not executed**
+- Returns `nil` by default
+
+In normal mode:
+- The block is executed normally
+- Returns the block's return value
+
+### With Fallback Value
+
+Specify a fallback value to return in dry-run mode:
+
+```ruby
+task :get_payment_token do |ctx|
+  token = ctx.skip_in_dry_run(fallback: "dry_run_token_#{SecureRandom.hex(8)}") do
+    PaymentGateway.create_token(ctx.arguments.card_info)
+  end
+
+  ctx.output[:payment_token] = token
+end
+```
+
+### Named Dry-Run Operations
+
+Use named operations for better instrumentation and debugging:
+
+```ruby
+task :complex_operation do |ctx|
+  # Named operation for payment
+  ctx.skip_in_dry_run(:payment) do
+    PaymentGateway.charge(ctx.arguments.amount)
+  end
+
+  # Named operation for notification
+  ctx.skip_in_dry_run(:notification) do
+    NotificationService.send(ctx.arguments.user_id, "Payment processed")
+  end
+end
+```
+
+### Named Operations with Fallback Values
+
+Combine operation names with fallback values for comprehensive testing:
+
+```ruby
+task :process_payment do |ctx|
+  payment_result = ctx.skip_in_dry_run(
+    :payment_processing,
+    fallback: { success: true, transaction_id: "dry_run_#{Time.current.to_i}", amount: ctx.arguments.amount }
+  ) do
+    PaymentService.process(
+      amount: ctx.arguments.amount,
+      customer_id: ctx.arguments.customer_id
+    )
+  end
+
+  ctx.output[:payment_result] = payment_result
+end
+```
+
+## Instrumentation
+
+Dry-run operations emit ActiveSupport::Notifications events for monitoring:
+
+### Event: `dry_run.skip.job_workflow`
+
+Emitted for each `skip_in_dry_run` call:
+
+```ruby
+ActiveSupport::Notifications.subscribe("dry_run.skip.job_workflow") do |name, start, finish, id, payload|
+  puts "Dry-run operation: #{payload[:dry_run_name]}"
+  puts "Task: #{payload[:task_name]}"
+  puts "Index: #{payload[:dry_run_index]}"
+  puts "Skipped: #{payload[:dry_run]}"
+end
+```
+
+Payload includes:
+- `job_id` - Job identifier
+- `job_name` - Job class name
+- `task_name` - Current task name
+- `each_index` - Index in collection (for `each:` tasks)
+- `dry_run_name` - Operation name (if provided)
+- `dry_run_index` - Sequential index of skip_in_dry_run calls within the task
+- `dry_run` - bool indicating if operation was skipped
+
+## Logging
+
+When using the default log subscriber, dry-run events are automatically logged:
+
+```
+[DRY-RUN] MyWorkflowJob#process_payment skip: payment (index: 0, skipped: true)
+```
+
+## Dry-Run vs Condition
+
+Dry-run mode and task conditions serve different purposes:
+
+| Feature | Dry-Run | Condition |
+|---------|---------|-----------|
+| **Purpose** | Skip side effects for safe testing | Control workflow logic flow |
+| **Scope** | Test/debug toggle for entire workflow or task | Control individual task execution |
+| **Usage** | Validate structure without external calls | Branch workflow based on data |
+| **With side effect** | Skips block execution (returns fallback) | Prevents task execution entirely |
+| **Instrumentation** | Emits `dry_run.skip/execute` events | Emits `task.skip` event |
+
+**When to use dry-run:**
+```ruby
+# Safe testing of workflow logic
+ctx.skip_in_dry_run do
+  PaymentGateway.charge(amount)
+end
+```
+
+**When to use condition:**
+```ruby
+# Control workflow flow based on data
+task :send_email, condition: ->(ctx) { ctx.arguments.email_enabled } do |ctx|
+  Mailer.send_email(ctx.arguments.email)
+end
+```
+
+You can combine both for comprehensive control:
+```ruby
+task :process_order, condition: ->(ctx) { ctx.arguments.order_id } do |ctx|
+  # Only runs if condition is true
+  # Within this task, you can still use skip_in_dry_run for side effects
+  ctx.skip_in_dry_run do
+    ExternalService.process(ctx.arguments.order_id)
+  end
+end
+```
+
+## Best Practices
+
+### 1. Use Meaningful Operation Names
+
+```ruby
+# Good - descriptive names help with debugging
+ctx.skip_in_dry_run(:payment_processing) { ... }
+ctx.skip_in_dry_run(:send_welcome_email) { ... }
+
+# Avoid - unnamed operations are harder to trace
+ctx.skip_in_dry_run { ... }
+```
+
+### 2. Provide Realistic Fallback Values
+
+```ruby
+# Good - realistic fallback for testing
+ctx.skip_in_dry_run(fallback: { id: "dry_run_123", status: "simulated" }) do
+  ExternalAPI.create_resource(data)
+end
+
+# Consider - nil might cause issues in subsequent tasks
+ctx.skip_in_dry_run do
+  ExternalAPI.create_resource(data)
+end
+```
+
+### 3. Log Dry-Run Actions
+
+```ruby
+task :process_data do |ctx|
+  if ctx.dry_run?
+    Rails.logger.info "[DRY-RUN] Processing: #{ctx.arguments.inspect}"
+  end
+
+  ctx.skip_in_dry_run(:database_write) do
+    Database.write(ctx.arguments.data)
+  end
+end
+```
+
+### 4. Use Environment-Based Configuration
+
+```ruby
+class ProductionWorkflowJob < ActiveJob::Base
+  include JobWorkflow::DSL
+
+  # Dry-run in non-production environments
+  dry_run { |_ctx| !Rails.env.production? }
+
+  # Or based on feature flags
+  dry_run { |_ctx| FeatureFlag.enabled?(:workflow_dry_run) }
+end
+```
+
+### 5. Test Both Modes
+
+```ruby
+RSpec.describe MyWorkflowJob do
+  context "in normal mode" do
+    it "executes side effects" do
+      expect(ExternalService).to receive(:call)
+      described_class.perform_now(dry_run_mode: false)
+    end
+  end
+
+  context "in dry-run mode" do
+    it "skips side effects" do
+      expect(ExternalService).not_to receive(:call)
+      described_class.perform_now(dry_run_mode: true)
+    end
+  end
+end
+```
+
+## Example: Complete Workflow
+
+```ruby
+class OrderProcessingJob < ActiveJob::Base
+  include JobWorkflow::DSL
+
+  argument :order_id, "Integer"
+  argument :dry_run_mode, "bool", default: false
+
+  # Dynamic dry-run based on argument
+  dry_run { |ctx| ctx.arguments.dry_run_mode }
+
+  task :validate_order, output: { order: "Hash[Symbol, untyped]" } do |ctx|
+    order = Order.find(ctx.arguments.order_id)
+    { order: order.attributes }
+  end
+
+  task :charge_payment, depends_on: [:validate_order] do |ctx|
+    order = ctx.output[:validate_order].first.order
+
+    result = ctx.skip_in_dry_run(:payment_processing, fallback: { success: true, transaction_id: "dry_run" }) do
+      PaymentService.process(
+        amount: order[:total],
+        customer_id: order[:customer_id]
+      )
+    end
+
+    Rails.logger.info "[#{ctx.dry_run? ? 'DRY-RUN' : 'LIVE'}] Payment result: #{result}"
+  end
+
+  task :send_confirmation, depends_on: [:charge_payment] do |ctx|
+    order = ctx.output[:validate_order].first.order
+
+    ctx.skip_in_dry_run(:email_notification) do
+      OrderMailer.confirmation(order[:id]).deliver_later
+    end
+  end
+
+  task :update_inventory, depends_on: [:charge_payment] do |ctx|
+    order = ctx.output[:validate_order].first.order
+
+    ctx.skip_in_dry_run(:inventory_update) do
+      InventoryService.decrement(order[:items])
+    end
+  end
+end
+
+# Usage
+OrderProcessingJob.perform_later(order_id: 123, dry_run_mode: true)  # Dry-run
+OrderProcessingJob.perform_later(order_id: 123, dry_run_mode: false) # Live
+```
+
+## See Also
+
+- [DSL_BASICS.md](DSL_BASICS.md) - Task configuration basics
+- [INSTRUMENTATION.md](INSTRUMENTATION.md) - Monitoring and observability
+- [TESTING_STRATEGY.md](TESTING_STRATEGY.md) - Testing workflows

data/guides/DSL_BASICS.md

@@ -0,0 +1,216 @@
+# DSL Basics
+
+## Defining Tasks
+
+### Simple Task
+
+The simplest task requires only a name and a block. Tasks can return outputs that are accessible to dependent tasks:
+
+```ruby
+task :simple_task, output: { result: "String" } do |ctx|
+  { result: "completed" }
+end
+
+# Access the output in another task
+task :next_task, depends_on: [:simple_task] do |ctx|
+  result = ctx.output[:simple_task].first.result
+  puts result  # => "completed"
+end
+```
+
+### Specifying Dependencies
+
+#### Single Dependency
+
+```ruby
+task :fetch_data, output: { data: "Hash" } do |ctx|
+  { data: API.fetch }
+end
+
+task :process_data, depends_on: [:fetch_data], output: { result: "String" } do |ctx|
+  data = ctx.output[:fetch_data].first.data
+  { result: process(data) }
+end
+```
+
+#### Multiple Dependencies
+
+```ruby
+task :task_a, output: { a: "Integer" } do |ctx|
+  { a: 1 }
+end
+
+task :task_b, output: { b: "Integer" } do |ctx|
+  { b: 2 }
+end
+
+task :task_c, depends_on: [:task_a, :task_b], output: { result: "Integer" } do |ctx|
+  a = ctx.output[:task_a].first.a
+  b = ctx.output[:task_b].first.b
+  { result: a + b }  # => 3
+end
+```
+
+### Dependency Resolution Order
+
+JobWorkflow automatically topologically sorts dependencies.
+
+```ruby
+# Correct order is executed regardless of definition order
+task :step3, depends_on: [:step2], output: { final: "bool" } do |ctx|
+  { final: true }
+end
+
+task :step1, output: { initial: "bool" } do |ctx|
+  { initial: true }
+end
+
+task :step2, depends_on: [:step1], output: { middle: "bool" } do |ctx|
+  { middle: true }
+end
+
+# Execution order: step1 → step2 → step3
+```
+
+## Working with Arguments
+
+### Defining Arguments
+
+Type information is specified as **strings**. This is used for RBS generation and documentation; runtime type checking is not performed.
+
+```ruby
+class TypedWorkflowJob < ApplicationJob
+  include JobWorkflow::DSL
+  
+  # Type information specified as strings (for RBS generation)
+  argument :user_id, "Integer"
+  argument :email, "String"
+  argument :created_at, "Time"
+  argument :metadata, "Hash"
+  
+  # Arrays and generics as strings too
+  argument :items, "Array[String]"
+  argument :config, "Hash[Symbol, String]"
+  
+  # Fields with default values
+  argument :optional_field, "String", default: ""
+end
+```
+
+### Accessing Arguments
+
+**Arguments are immutable and read-only**. Access them via `ctx.arguments`:
+
+```ruby
+task :example do |ctx|
+  # Reading arguments
+  user_id = ctx.arguments.user_id
+  email = ctx.arguments.email
+  
+  # Check if argument has value
+  if ctx.arguments.optional_field.present?
+    # Process
+  end
+end
+```
+
+**Important**: Arguments cannot be modified. To pass data between tasks, use task outputs:
+
+```ruby
+# ✅ Correct: Use outputs to pass data
+task :fetch, output: { result: "String" } do |ctx|
+  { result: "data" }
+end
+
+task :process, depends_on: [:fetch] do |ctx|
+  result = ctx.output[:fetch].first.result
+  process_data(result)
+end
+
+# ❌ Wrong: Cannot modify arguments
+task :wrong do |ctx|
+  ctx.arguments.user_id = 123  # Error: Arguments are immutable
+end
+```
+
+## Task Options
+
+### Retry Configuration
+
+```ruby
+argument :api_key, "String"
+
+# Simple retry (up to 3 times)
+task :flaky_api, retry: 3, output: { response: "Hash" } do |ctx|
+  api_key = ctx.arguments.api_key
+  { response: ExternalAPI.call(api_key) }
+end
+
+# Advanced retry configuration with exponential backoff
+task :advanced_retry,
+     retry: {
+       count: 5,                # Maximum retry attempts
+       strategy: :exponential,  # :linear or :exponential
+       base_delay: 2,           # Initial wait time in seconds
+       jitter: true             # Add ±randomness to prevent thundering herd
+     },
+     output: { result: "String" } do |ctx|
+  { result: unreliable_operation }
+  # Retry intervals: 2±1s, 4±2s, 8±4s, 16±8s, 32±16s
+end
+```
+
+### Conditional Execution
+
+```ruby
+argument :user, "User"
+argument :amount, "Integer"
+argument :verified, "bool"
+
+# condition: Execute only if condition returns true
+task :premium_feature,
+     condition: ->(ctx) { ctx.arguments.user.premium? },
+     output: { premium_result: "String" } do |ctx|
+  { premium_result: premium_process }
+end
+
+# Inverse condition using negation
+task :free_tier_limit,
+     condition: ->(ctx) { !ctx.arguments.user.premium? },
+     output: { limited_result: "String" } do |ctx|
+  { limited_result: limited_process }
+end
+
+# Complex condition
+task :complex,
+     condition: ->(ctx) { ctx.arguments.amount > 1000 && ctx.arguments.verified },
+     output: { vip_process: "bool" } do |ctx|
+  { vip_process: true }
+end
+```
+
+### Throttling
+
+```ruby
+argument :api_params, "Hash"
+
+# Simple syntax: Integer (recommended)
+task :api_call,
+     throttle: 10,  # Max 10 concurrent executions, default key
+     output: { response: "Hash" } do |ctx|
+  params = ctx.arguments.api_params
+  { response: RateLimitedAPI.call(params) }
+end
+
+# Advanced syntax: Hash
+task :api_call_advanced,
+     throttle: {
+       key: "external_api",     # Custom semaphore key
+       limit: 10,               # Concurrency limit
+       ttl: 120                 # Lease TTL in seconds (default: 180)
+     },
+     output: { response: "Hash" } do |ctx|
+  params = ctx.arguments.api_params
+  { response: RateLimitedAPI.call(params) }
+end
+```