chrono_forge 0.6.0 → 0.7.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ca8b29d2a6800467fd237f7fb998a243aa1f31d2de99543017e10f03f89c949
-  data.tar.gz: 60bb959cb97d8f782348bc80b1c7578c526e62e6a4454909308150c33cc06c9e
+  metadata.gz: 249a16358802f143b744130ac2807cea606fe1c3d4c4f2fc20b6ab83e4aaba9b
+  data.tar.gz: 4fe9d09279388146179f6f636f4b9a0601aaa758e7d2c0fccf035b278d7e9288
 SHA512:
-  metadata.gz: deb1092227fd41a1cb6ce6ac5784cbd8e571893a18294064e648bbbbaa50ca73046457860ccd93c922d44ad2cec197a6bfbdbc12829a12f209da2f978621d893
-  data.tar.gz: 3cca8a8acff06779828e648415333d85b8ad9161c0211ee30bc11263c3ee5dc953a637a3f8d1bde56c63d1286af01be2312697559b038776dbbf12366e1d2250
+  metadata.gz: 7fc5b49ed0beb6082b98a16e8ca764d6430a17a67e717e48350b416e6d2a5482cc05a0bc1f97a5b274c4f232eadfc3b1f9d8298b3e6bf05b9a85cfcd5e33dd41
+  data.tar.gz: 5b6a0c8ab5147b689563f2ab7516e78a93159437d10c8adab6de91a851abb1259e93a26413aa17617f17809ca30aec5ac14583bc51d9f7461de3848967a70f3a

data/README.md

@@ -146,30 +146,262 @@ OrderProcessingWorkflow.perform_later(
 
 #### ⚡ Durable Execution
 
-The `durably_execute` method ensures operations are executed exactly once, even if the job fails and is retried:
+The `durably_execute` method ensures operations are executed exactly once with automatic retry logic and fault tolerance:
 
 ```ruby
-# Execute a method
-durably_execute(:process_payment, max_attempts: 3)
+# Basic execution
+durably_execute :send_welcome_email
 
-# Or with a block
-durably_execute -> (ctx) {
-  Payment.process(ctx[:payment_id])
-}
+# With custom retry attempts
+durably_execute :critical_payment_processing, max_attempts: 5
+
+# With custom name for tracking multiple calls to same method
+durably_execute :upload_file, name: "profile_image_upload"
+
+# Complex example with error-prone operation
+class FileProcessingWorkflow < ApplicationJob
+  prepend ChronoForge::Executor
+
+  def perform(file_id:)
+    @file_id = file_id
+    
+    # This might fail due to network issues, rate limits, etc.
+    durably_execute :upload_to_s3, max_attempts: 5
+    
+    # Process file after successful upload
+    durably_execute :generate_thumbnails, max_attempts: 3
+  end
+
+  private
+
+  def upload_to_s3
+    file = File.find(@file_id)
+    S3Client.upload(file.path, bucket: 'my-bucket')
+    Rails.logger.info "Successfully uploaded file #{@file_id} to S3"
+  end
+
+  def generate_thumbnails
+    ThumbnailService.generate(@file_id)
+  end
+end
 ```
 
+**Key Features:**
+- **Idempotent**: Same operation won't be executed twice during replays
+- **Automatic Retries**: Failed executions retry with exponential backoff (2^attempt seconds, capped at 32s)
+- **Error Tracking**: All failures are logged with detailed error information
+- **Configurable**: Customize retry attempts and step naming
+
 #### ⏱️ Wait States
 
-ChronoForge supports both time-based and condition-based waits:
+ChronoForge supports three types of wait states, each optimized for different use cases:
+
+**1. Time-based Waits (`wait`)**
+
+For simple delays and scheduled pauses:
+
+```ruby
+# Simple delays
+wait 30.minutes, "cooling_period"
+wait 1.day, "daily_batch_interval"
+
+# Complex workflow with multiple waits
+def user_onboarding_flow
+  send_welcome_email
+  wait 1.hour, "welcome_delay"
+  
+  send_tutorial_email
+  wait 2.days, "tutorial_followup"
+  
+  send_feedback_request
+end
+```
+
+**2. Automated Condition Waits (`wait_until`)**
+
+For conditions that can be automatically polled at regular intervals:
 
 ```ruby
-# Wait for a specific duration
-wait 1.hour, :cooling_period
+# Wait for external API
+wait_until :external_api_ready?, 
+  timeout: 30.minutes, 
+  check_interval: 1.minute
+
+# Wait with retry on specific errors
+wait_until :database_migration_complete?,
+  timeout: 2.hours,
+  check_interval: 30.seconds,
+  retry_on: [ActiveRecord::ConnectionNotEstablished, Net::TimeoutError]
+
+# Complex condition example
+def third_party_service_ready?
+  response = HTTParty.get("https://api.example.com/health")
+  response.code == 200 && response.body.include?("healthy")
+rescue Net::TimeoutError, Net::HTTPClientException
+  false # Will be retried at next check interval
+end
 
-# Wait until a condition is met
-wait_until :payment_processed, 
+wait_until :third_party_service_ready?,
   timeout: 1.hour,
-  check_interval: 5.minutes
+  check_interval: 2.minutes,
+  retry_on: [Net::TimeoutError, Net::HTTPClientException]
+```
+
+**3. Event-driven Waits (`continue_if`)**
+
+For conditions that depend on external events like webhooks, requiring manual workflow continuation:
+
+```ruby
+# Basic usage - wait for webhook-driven state change
+continue_if :payment_confirmed?
+
+# With custom name for better tracking
+continue_if :payment_confirmed?, name: "stripe_webhook"
+
+# Wait for manual approval
+continue_if :document_approved?
+
+# Wait for external file processing
+continue_if :processing_complete?
+
+# Multiple waits with same condition but different contexts
+continue_if :external_system_ready?, name: "payment_gateway"
+# ... other steps ...
+continue_if :external_system_ready?, name: "inventory_system"
+
+# Complete workflow example
+class PaymentWorkflow < ApplicationJob
+  prepend ChronoForge::Executor
+
+  def perform(order_id:)
+    @order_id = order_id
+    
+    # Initialize payment
+    durably_execute :create_payment_request
+    
+    # Wait for external payment confirmation (webhook-driven)
+    continue_if :payment_confirmed?, name: "stripe_confirmation"
+    
+    # Complete order after payment
+    durably_execute :fulfill_order
+  end
+
+  private
+
+  def payment_confirmed?
+    PaymentService.confirmed?(@order_id)
+  end
+end
+
+# Later, when webhook arrives:
+PaymentService.mark_confirmed(order_id)
+PaymentWorkflow.perform_later("order-#{order_id}", order_id: order_id)
+```
+
+**When to Use Each Wait Type:**
+
+| Wait Type | Use Case | Polling | Resource Usage | Response Time |
+|-----------|----------|---------|----------------|---------------|
+| `wait` | Fixed delays, rate limiting | None | Minimal | Exact timing |
+| `wait_until` | API readiness, data processing | Automatic | Medium | Check interval |
+| `continue_if` | Webhooks, user actions, file uploads | Manual only | Minimal | Immediate |
+
+**Key Differences:**
+
+- **`wait`**: Time-based, no condition checking, resumes automatically
+- **`wait_until`**: Condition-based with automatic polling, resumes when condition becomes true or timeout
+- **`continue_if`**: Condition-based without polling, requires manual workflow retry when condition might have changed
+
+#### 🔄 Periodic Tasks
+
+The `durably_repeat` method enables robust periodic task execution within workflows. Tasks are scheduled at regular intervals until a specified condition is met, with automatic catch-up for missed executions and configurable error handling.
+
+```ruby
+class NotificationWorkflow < ApplicationJob
+  prepend ChronoForge::Executor
+
+  def perform(user_id:)
+    @user_id = user_id
+    
+    # Send reminders every 3 days until user completes onboarding
+    durably_repeat :send_reminder_email, 
+      every: 3.days, 
+      till: :user_onboarded?
+    
+    # Critical payment processing every hour - fail workflow if it fails
+    durably_repeat :process_pending_payments,
+      every: 1.hour,
+      till: :all_payments_processed?,
+      on_error: :fail_workflow
+  end
+
+  private
+
+  def send_reminder_email(scheduled_time = nil)
+    # Optional parameter receives the scheduled execution time
+    if scheduled_time
+      lateness = Time.current - scheduled_time
+      Rails.logger.info "Reminder scheduled for #{scheduled_time}, running #{lateness.to_i}s late"
+    end
+    
+    UserMailer.onboarding_reminder(@user_id).deliver_now
+  end
+
+  def user_onboarded?
+    User.find(@user_id).onboarded?
+  end
+
+  def process_pending_payments
+    PaymentProcessor.process_pending_for_user(@user_id)
+  end
+
+  def all_payments_processed?
+    Payment.where(user_id: @user_id, status: :pending).empty?
+  end
+end
+```
+
+**Key Features:**
+
+- **Idempotent Execution**: Each repetition gets a unique execution log, preventing duplicates during replays
+- **Automatic Catch-up**: Missed executions due to downtime are automatically skipped using timeout-based fast-forwarding
+- **Flexible Timing**: Support for custom start times and precise interval scheduling
+- **Error Resilience**: Individual execution failures don't break the periodic schedule
+- **Configurable Error Handling**: Choose between continuing despite failures or failing the entire workflow
+
+**Advanced Options:**
+
+```ruby
+durably_repeat :generate_daily_report,
+  every: 1.day,                          # Execution interval
+  till: :reports_complete?,              # Stop condition
+  start_at: Date.tomorrow.beginning_of_day, # Custom start time (optional)
+  max_attempts: 5,                       # Retries per execution (default: 3)
+  timeout: 2.hours,                      # Catch-up timeout (default: 1.hour)
+  on_error: :fail_workflow,              # Error handling (:continue or :fail_workflow)
+  name: "daily_reports"                  # Custom task name (optional)
+```
+
+**Method Parameters:**
+
+Your periodic methods can optionally receive the scheduled execution time as their first argument:
+
+```ruby
+# Without scheduled time parameter
+def cleanup_files
+  FileCleanupService.perform
+end
+
+# With scheduled time parameter
+def cleanup_files(scheduled_time)
+  # Use scheduled time for business logic
+  cleanup_date = scheduled_time.to_date
+  FileCleanupService.perform(date: cleanup_date)
+  
+  # Log timing information
+  delay = Time.current - scheduled_time
+  Rails.logger.info "Cleanup was #{delay.to_i} seconds late"
+end
 ```
 
 #### 🔄 Workflow Context
@@ -413,3 +645,27 @@ Please include tests for any new features or bug fixes.
 ## 📜 License
 
 This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 📚 API Reference
+
+### Core Workflow Methods
+
+| Method | Purpose | Key Parameters |
+|--------|---------|----------------|
+| `durably_execute` | Execute method with retry logic | `method`, `max_attempts: 3`, `name: nil` |
+| `wait` | Time-based pause | `duration`, `name` |
+| `wait_until` | Condition-based waiting | `condition`, `timeout: 1.hour`, `check_interval: 15.minutes`, `retry_on: []` |
+| `continue_if` | Manual continuation wait | `condition`, `name: nil` |
+| `durably_repeat` | Periodic task execution | `method`, `every:`, `till:`, `start_at: nil`, `max_attempts: 3`, `timeout: 1.hour`, `on_error: :continue` |
+
+### Context Methods
+
+| Method | Purpose | Example |
+|--------|---------|---------|
+| `context[:key] = value` | Set context value | `context[:user_id] = 123` |
+| `context[:key]` | Get context value | `user_id = context[:user_id]` |
+| `context.set(key, value)` | Set context value (alias) | `context.set(:status, "active")` |
+| `context.set_once(key, value)` | Set only if key doesn't exist | `context.set_once(:created_at, Time.current)` |
+| `context.fetch(key, default)` | Get with default value | `context.fetch(:count, 0)` |
+| `context.key?(key)` | Check if key exists | `context.key?(:user_id)` |
+

data/examples/continue_if_webhook_example.rb

@@ -0,0 +1,134 @@
+# Example: Webhook-driven Payment Processing Workflow
+#
+# This example demonstrates how to use continue_if for workflows that need to wait
+# for external events like webhook notifications without consuming resources on polling.
+
+class PaymentProcessingWorkflow < ApplicationJob
+  prepend ChronoForge::Executor
+
+  def perform(order_id:)
+    @order_id = order_id
+
+    # Store order details in durable context
+    context[:order_id] = @order_id
+    context[:created_at] = Time.current.iso8601
+
+    # Step 1: Initialize payment request
+    durably_execute :initialize_payment
+
+    # Step 2: Wait for payment confirmation (webhook-driven)
+    # This will halt the workflow until manually retried when webhook arrives
+    continue_if :payment_confirmed?, name: "stripe_payment_webhook"
+
+    # Step 3: Process successful payment
+    durably_execute :process_payment_success
+
+    # Step 4: Send confirmation to customer
+    durably_execute :send_confirmation
+  end
+
+  private
+
+  def initialize_payment
+    # Create payment request with external payment provider
+    payment_request = PaymentService.create_payment_request(
+      order_id: @order_id,
+      amount: Order.find(@order_id).total_amount
+    )
+
+    context[:payment_request_id] = payment_request.id
+    context[:payment_status] = "pending"
+
+    Rails.logger.info "Payment request created for order #{@order_id}: #{payment_request.id}"
+  end
+
+  def payment_confirmed?
+    # Check if payment has been confirmed by webhook
+    payment_id = context[:payment_request_id]
+    payment = PaymentService.find_payment(payment_id)
+
+    confirmed = payment&.status == "confirmed"
+
+    if confirmed
+      context[:payment_status] = "confirmed"
+      context[:confirmed_at] = Time.current.iso8601
+    end
+
+    Rails.logger.debug "Payment confirmation check for #{payment_id}: #{confirmed}"
+    confirmed
+  end
+
+  def process_payment_success
+    # Update order status and inventory
+    order = Order.find(@order_id)
+    order.mark_as_paid!
+
+    # Update inventory
+    InventoryService.reserve_items(order.items)
+
+    context[:processed_at] = Time.current.iso8601
+    Rails.logger.info "Payment processed successfully for order #{@order_id}"
+  end
+
+  def send_confirmation
+    # Send confirmation email to customer
+    order = Order.find(@order_id)
+    OrderMailer.payment_confirmation(order).deliver_now
+
+    context[:confirmation_sent_at] = Time.current.iso8601
+    Rails.logger.info "Confirmation email sent for order #{@order_id}"
+  end
+end
+
+# Webhook handler that resumes the workflow
+class PaymentWebhookController < ApplicationController
+  def receive
+    payment_id = params[:payment_id]
+    status = params[:status]
+
+    if status == "confirmed"
+      # Update payment status in your system
+      PaymentService.update_payment_status(payment_id, "confirmed")
+
+      # Find and continue the corresponding workflow
+      order_id = PaymentService.find_payment(payment_id).order_id
+      workflow_key = "payment-#{order_id}"
+
+      # Continue the workflow from where it left off (continue_if)
+      PaymentProcessingWorkflow.perform_later(workflow_key, order_id: order_id)
+
+      Rails.logger.info "Payment confirmed via webhook, continuing workflow #{workflow_key}"
+    end
+
+    head :ok
+  end
+end
+
+# Usage example:
+#
+# 1. Start the workflow:
+#    PaymentProcessingWorkflow.perform_later("payment-order-123", order_id: "order-123")
+#
+# 2. Workflow will:
+#    - Create payment request
+#    - Check if payment is confirmed (initially false)
+#    - Halt execution and wait in idle state
+#
+# 3. When webhook arrives:
+#    - PaymentWebhookController#receive processes webhook
+#    - Updates payment status to "confirmed"
+#    - Calls PaymentProcessingWorkflow.perform_later("payment-order-123", order_id: "order-123")
+#
+# 4. Workflow resumes:
+#    - Re-evaluates payment_confirmed? (now returns true)
+#    - Continues with processing payment success
+#    - Sends confirmation email
+#    - Completes workflow
+
+# Key benefits of continue_if vs wait_until:
+#
+# 1. No resource consumption: No background polling jobs
+# 2. Instant response: Resumes immediately when condition changes
+# 3. Webhook-friendly: Perfect for external event-driven workflows
+# 4. Durable: Survives system restarts and deployments
+# 5. Traceable: All state changes are logged in execution logs

data/lib/chrono_forge/executor/methods/continue_if.rb

@@ -0,0 +1,159 @@
+module ChronoForge
+  module Executor
+    module Methods
+      module ContinueIf
+        # Waits until a specified condition becomes true, without any automatic polling or time-based checks.
+        #
+        # This method provides a durable pause state that can only be resumed by manually retrying
+        # the workflow (typically triggered by external events like webhooks). Unlike wait_until,
+        # this method does not automatically poll the condition - it simply evaluates the condition
+        # once and either proceeds (if true) or halts execution (if false) until manually retried.
+        #
+        # @param condition [Symbol] The name of the instance method to evaluate as the condition.
+        #   The method should return a truthy value when the condition is met.
+        # @param name [String, nil] Optional custom name for this step. If not provided, uses the condition name.
+        #   Useful for tracking multiple calls to the same condition or providing more descriptive names.
+        #
+        # @return [true] When the condition is met
+        #
+        # @example Basic usage
+        #   continue_if :payment_confirmed?
+        #
+        # @example With custom name
+        #   continue_if :payment_confirmed?, name: "stripe_payment_confirmation"
+        #
+        # @example Waiting for external webhook
+        #   continue_if :webhook_received?
+        #
+        # @example Waiting for manual approval
+        #   continue_if :approval_granted?
+        #
+        # @example Multiple continue_if with same condition but different names
+        #   continue_if :external_system_ready?, name: "payment_system_ready"
+        #   # ... other workflow steps ...
+        #   continue_if :external_system_ready?, name: "inventory_system_ready"
+        #
+        # @example Complete workflow with manual continuation
+        #   def perform(order_id:)
+        #     @order_id = order_id
+        #
+        #     # Process initial order
+        #     durably_execute :initialize_order
+        #
+        #     # Wait for external payment confirmation (webhook-driven)
+        #     continue_if :payment_confirmed?, name: "stripe_webhook"
+        #
+        #     # Complete order processing
+        #     durably_execute :complete_order
+        #   end
+        #
+        #   private
+        #
+        #   def payment_confirmed?
+        #     PaymentService.confirmed?(@order_id)
+        #   end
+        #
+        #   # Later, when webhook arrives:
+        #   # PaymentService.mark_confirmed(order_id)
+        #   # OrderProcessingWorkflow.perform_later("order-#{order_id}", order_id: order_id)
+        #
+        # == Behavior
+        #
+        # === Condition Evaluation
+        # The condition method is called once per workflow execution:
+        # - If truthy, execution continues immediately
+        # - If falsy, workflow execution halts until manually retried
+        # - No automatic polling or retry attempts are made
+        #
+        # === Manual Retry Required
+        # Unlike other wait states, continue_if requires external intervention:
+        # - Call Workflow.perform_later(key, **kwargs) to continue the workflow
+        # - Typically triggered by webhooks, background jobs, or manual intervention
+        # - No timeout or automatic resumption
+        #
+        # === Error Handling
+        # - Exceptions during condition evaluation cause workflow failure
+        # - No automatic retry on condition evaluation errors
+        # - Use try/catch in condition methods for error handling
+        #
+        # === Persistence and Resumability
+        # - Wait state is persisted in execution logs
+        # - Workflow can be stopped/restarted without losing wait progress
+        # - Condition evaluation state persists across restarts
+        # - Safe for system interruptions and deployments
+        #
+        # === Execution Logs
+        # Creates execution log with step name: `continue_if$#{name || condition}`
+        # - Tracks attempt count and execution times
+        # - Records final result (true for success)
+        #
+        # === Use Cases
+        # Perfect for workflows that depend on:
+        # - External webhook notifications
+        # - Manual approval processes
+        # - File uploads or external processing completion
+        # - Third-party system state changes
+        # - User actions or form submissions
+        #
+        def continue_if(condition, name: nil)
+          step_name = "continue_if$#{name || condition}"
+
+          # Find or create execution log
+          execution_log = ExecutionLog.create_or_find_by!(
+            workflow: @workflow,
+            step_name: step_name
+          ) do |log|
+            log.started_at = Time.current
+            log.metadata = {
+              condition: condition.to_s,
+              name: name
+            }
+          end
+
+          # Return if already completed
+          if execution_log.completed?
+            return execution_log.metadata["result"]
+          end
+
+          # Evaluate condition once
+          begin
+            execution_log.update!(
+              attempts: execution_log.attempts + 1,
+              last_executed_at: Time.current
+            )
+
+            condition_met = send(condition)
+          rescue HaltExecutionFlow
+            raise
+          rescue => e
+            # Log the error and fail the execution
+            Rails.logger.error { "Error evaluating condition #{condition}: #{e.message}" }
+            self.class::ExecutionTracker.track_error(workflow, e)
+
+            execution_log.update!(
+              state: :failed,
+              error_message: e.message,
+              error_class: e.class.name
+            )
+            raise ExecutionFailedError, "#{step_name} failed with an error: #{e.message}"
+          end
+
+          # Handle condition met
+          if condition_met
+            execution_log.update!(
+              state: :completed,
+              completed_at: Time.current,
+              metadata: execution_log.metadata.merge("result" => true)
+            )
+            return true
+          end
+
+          # Condition not met - halt execution without scheduling any retry
+          # Workflow will remain in idle state until manually retried
+          Rails.logger.debug { "Condition not met for #{step_name}, workflow will wait for manual retry" }
+          halt_execution!
+        end
+      end
+    end
+  end
+end