chrono_forge 0.6.0 → 0.7.0.rc1

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

@@ -2,9 +2,66 @@ module ChronoForge
   module Executor
     module Methods
       module DurablyExecute
-        def durably_execute(method, **options)
-          # Create execution log
-          step_name = "durably_execute$#{method}"
+        # Executes a method with automatic retry logic and durable execution tracking.
+        #
+        # This method provides fault-tolerant execution of instance methods with automatic
+        # retry on failure using exponential backoff. Each execution is tracked with its own
+        # execution log, ensuring idempotent behavior during workflow replays.
+        #
+        # @param method [Symbol] The name of the instance method to execute
+        # @param max_attempts [Integer] Maximum retry attempts before failing (default: 3)
+        # @param name [String, nil] Custom name for the execution step. Defaults to method name.
+        #   Used to create unique step names for execution logs.
+        #
+        # @return [nil]
+        #
+        # @raise [ExecutionFailedError] When the method fails after max_attempts
+        #
+        # @example Basic usage
+        #   durably_execute :send_welcome_email
+        #
+        # @example With custom retry attempts
+        #   durably_execute :critical_payment_processing, max_attempts: 5
+        #
+        # @example With custom name for tracking
+        #   durably_execute :complex_calculation, name: "phase_1_calculation"
+        #
+        # @example Method that might fail temporarily
+        #   def upload_to_s3
+        #     # This might fail due to network issues, rate limits, etc.
+        #     S3Client.upload(file_path, bucket: 'my-bucket')
+        #     Rails.logger.info "Successfully uploaded file to S3"
+        #   end
+        #
+        #   durably_execute :upload_to_s3, max_attempts: 5
+        #
+        # == Behavior
+        #
+        # === Idempotency
+        # Each execution gets a unique step name ensuring that workflow replays don't
+        # create duplicate executions. If a workflow is replayed and this step has
+        # already completed, it will be skipped.
+        #
+        # === Retry Logic
+        # - Failed executions are automatically retried with exponential backoff
+        # - Backoff calculation: 2^attempt seconds (capped at 2^5 = 32 seconds)
+        # - After max_attempts, ExecutionFailedError is raised
+        #
+        # === Error Handling
+        # - All exceptions except HaltExecutionFlow are caught and handled
+        # - Errors are logged and tracked in the execution log
+        # - ExecutionFailedError is raised after exhausting all retry attempts
+        # - HaltExecutionFlow exceptions are re-raised to allow workflow control flow
+        #
+        # === Execution Logs
+        # Creates execution log with step name: `durably_execute$#{name || method}`
+        # - Tracks attempt count, execution times, and completion status
+        # - Stores error details when failures occur
+        # - Enables monitoring and debugging of execution history
+        #
+        def durably_execute(method, max_attempts: 3, name: nil)
+          step_name = "durably_execute$#{name || method}"
+          # Find or create execution log
           execution_log = ExecutionLog.create_or_find_by!(
             workflow: @workflow,
             step_name: step_name
@@ -24,11 +81,7 @@ module ChronoForge
             )
 
             # Execute the method
-            if method.is_a?(Symbol)
-              send(method)
-            else
-              method.call(@context)
-            end
+            send(method)
 
             # Complete the execution
             execution_log.update!(
@@ -46,9 +99,9 @@ module ChronoForge
             self.class::ExecutionTracker.track_error(workflow, e)
 
             # Optional retry logic
-            if execution_log.attempts < (options[:max_attempts] || 3)
+            if execution_log.attempts < max_attempts
               # Reschedule with exponential backoff
-              backoff = (2**[execution_log.attempts || 1, 5].min).seconds
+              backoff = (2**[execution_log.attempts, 5].min).seconds
 
               self.class
                 .set(wait: backoff)

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

@@ -0,0 +1,298 @@
+module ChronoForge
+  module Executor
+    module Methods
+      module DurablyRepeat
+        # Schedules a method to be called repeatedly at specified intervals until a condition is met.
+        #
+        # This method provides durable, idempotent periodic task execution with automatic catch-up
+        # for missed executions using timeout-based fast-forwarding. Each repetition gets its own
+        # execution log, ensuring proper tracking and retry behavior.
+        #
+        # @param method [Symbol] The name of the instance method to execute repeatedly.
+        #   The method can optionally accept the scheduled execution time as its first argument.
+        # @param every [ActiveSupport::Duration] The interval between executions (e.g., 3.days, 1.hour)
+        # @param till [Symbol, Proc] The condition to check for stopping repetition. Should return
+        #   true when repetition should stop. Can be a symbol for instance methods or a callable.
+        # @param start_at [Time, nil] When to start the periodic task. Defaults to coordination_log.created_at + every
+        # @param max_attempts [Integer] Maximum retry attempts per individual execution (default: 3)
+        # @param timeout [ActiveSupport::Duration] How long after scheduled time an execution is
+        #   considered stale and skipped (default: 1.hour). This enables catch-up behavior.
+        # @param on_error [Symbol] How to handle repetition failures after max_attempts. Options:
+        #   - :continue (default): Log failure and continue with next scheduled execution
+        #   - :fail_workflow: Raise ExecutionFailedError to fail the entire workflow
+        # @param name [String, nil] Custom name for the periodic task. Defaults to method name.
+        #   Used to create unique step names for execution logs.
+        #
+        # @return [nil]
+        #
+        # @example Basic usage
+        #   durably_repeat :send_reminder_email, every: 3.days, till: :user_onboarded?
+        #
+        # @example Method with scheduled execution time parameter
+        #   def send_reminder_email(next_execution_at)
+        #     # Can access the scheduled execution time
+        #     lateness = Time.current - next_execution_at
+        #     Rails.logger.info "Email scheduled for #{next_execution_at}, running #{lateness.to_i}s late"
+        #     UserMailer.reminder_email(user_id, scheduled_for: next_execution_at).deliver_now
+        #   end
+        #
+        #   durably_repeat :send_reminder_email, every: 3.days, till: :user_onboarded?
+        #
+        # @example Resilient background task (default)
+        #   durably_repeat :cleanup_temp_files,
+        #     every: 1.day,
+        #     till: :cleanup_complete?,
+        #     on_error: :continue
+        #
+        # @example Critical task that should fail workflow on error
+        #   durably_repeat :process_payments,
+        #     every: 1.hour,
+        #     till: :all_payments_processed?,
+        #     on_error: :fail_workflow
+        #
+        # @example Advanced usage with all options
+        #   def generate_daily_report(scheduled_time)
+        #     report_date = scheduled_time.to_date
+        #     DailyReportService.new(date: report_date).generate
+        #   end
+        #
+        #   durably_repeat :generate_daily_report,
+        #     every: 1.day,
+        #     till: :reports_complete?,
+        #     start_at: Date.tomorrow.beginning_of_day,
+        #     max_attempts: 5,
+        #     timeout: 2.hours,
+        #     on_error: :fail_workflow,
+        #     name: "daily_reports"
+        #
+        # == Behavior
+        #
+        # === Method Parameters
+        # Your periodic method can optionally receive the scheduled execution time:
+        # - Method with no parameters: `def my_task; end` - called as `my_task()`
+        # - Method with parameter: `def my_task(next_execution_at); end` - called as `my_task(scheduled_time)`
+        #
+        # This allows methods to:
+        # - Log lateness/timing information
+        # - Perform time-based calculations
+        # - Include scheduled time in notifications
+        # - Generate reports for specific time periods
+        #
+        # === Idempotency
+        # Each execution gets a unique step name based on the scheduled execution time, ensuring
+        # that workflow replays don't create duplicate tasks.
+        #
+        # === Catch-up Mechanism
+        # If a workflow is paused and resumes later, the timeout parameter handles catch-up:
+        # - Executions older than `timeout` are automatically skipped
+        # - The periodic schedule integrity is maintained
+        # - Eventually reaches current/future execution times
+        #
+        # === Error Handling
+        # - Individual execution failures are retried up to `max_attempts` with exponential backoff
+        # - After max attempts, behavior depends on `on_error` parameter:
+        #   - `:continue`: Failed execution is logged, next execution is scheduled
+        #   - `:fail_workflow`: ExecutionFailedError is raised, failing the entire workflow
+        # - Timeouts are not considered errors and always continue to the next execution
+        #
+        # === Execution Logs
+        # Creates two types of execution logs:
+        # - Coordination log: `durably_repeat$#{name}` - tracks overall periodic task state
+        # - Repetition logs: `durably_repeat$#{name}$#{timestamp}` - tracks individual executions
+        #
+        def durably_repeat(method, every:, till:, start_at: nil, max_attempts: 3, timeout: 1.hour, on_error: :continue, name: nil)
+          step_name = "durably_repeat$#{name || method}"
+
+          # Get or create the main coordination log for this periodic task
+          coordination_log = ExecutionLog.create_or_find_by!(
+            workflow: @workflow,
+            step_name: step_name
+          ) do |log|
+            log.started_at = Time.current
+            log.metadata = {last_execution_at: nil}
+          end
+
+          # Return if already completed
+          return if coordination_log.completed?
+
+          # Update coordination log attempt tracking
+          coordination_log.update!(
+            attempts: coordination_log.attempts + 1,
+            last_executed_at: Time.current
+          )
+
+          # Check if we should stop repeating
+          condition_met = if till.is_a?(Symbol)
+            send(till)
+          else
+            till.call(context)
+          end
+          if condition_met
+            coordination_log.update!(
+              state: :completed,
+              completed_at: Time.current
+            )
+            return
+          end
+
+          # Calculate next execution time
+          metadata = coordination_log.metadata
+          last_execution_at = metadata["last_execution_at"] ? Time.parse(metadata["last_execution_at"]) : nil
+
+          next_execution_at = if last_execution_at
+            last_execution_at + every
+          elsif start_at
+            start_at
+          else
+            coordination_log.created_at + every
+          end
+
+          execute_or_schedule_repetition(method, coordination_log, next_execution_at, every, max_attempts, timeout, on_error)
+          nil
+        end
+
+        private
+
+        def execute_or_schedule_repetition(method, coordination_log, next_execution_at, every, max_attempts, timeout, on_error)
+          step_name = "#{coordination_log.step_name}$#{next_execution_at.to_i}"
+
+          # Create execution log for this specific repetition
+          repetition_log = ExecutionLog.create_or_find_by!(
+            workflow: @workflow,
+            step_name: step_name
+          ) do |log|
+            log.started_at = Time.current
+            log.metadata = {
+              scheduled_for: next_execution_at,
+              timeout_at: next_execution_at + timeout,
+              parent_id: coordination_log.id
+            }
+          end
+
+          # Return if this repetition is already completed
+          return if repetition_log.completed?
+
+          # Update execution log with attempt
+          repetition_log.update!(
+            attempts: repetition_log.attempts + 1,
+            last_executed_at: Time.current
+          )
+
+          # Check if it's time to execute this repetition
+          if next_execution_at <= Time.current
+            execute_repetition_now(method, repetition_log, coordination_log, next_execution_at, every, max_attempts, timeout, on_error)
+          else
+            schedule_repetition_for_later(repetition_log, next_execution_at)
+          end
+        end
+
+        def schedule_repetition_for_later(repetition_log, next_execution_at)
+          # Calculate delay until execution time
+          delay = [next_execution_at - Time.current, 0].max.seconds
+
+          # Schedule the workflow to run at the specified time
+          self.class
+            .set(wait: delay)
+            .perform_later(@workflow.key)
+
+          # Halt current execution until scheduled time
+          halt_execution!
+        end
+
+        def execute_repetition_now(method, repetition_log, coordination_log, execution_time, every, max_attempts, timeout, on_error)
+          # Check for timeout
+          if Time.current > repetition_log.metadata["timeout_at"]
+            repetition_log.update!(
+              state: :failed,
+              error_message: "Execution timed out",
+              error_class: "TimeoutError"
+            )
+
+            # Timeouts are part of the catch-up mechanism, always continue to next execution
+            schedule_next_execution_after_completion(coordination_log, execution_time, every)
+            return
+          end
+
+          execute_periodic_method(method, execution_time)
+          repetition_log.update!(
+            state: :completed,
+            completed_at: Time.current
+          )
+
+          # Update coordination log with successful execution and schedule next
+          coordination_log.update!(
+            metadata: coordination_log.metadata.merge(
+              "last_execution_at" => execution_time.iso8601
+            ),
+            last_executed_at: Time.current
+          )
+
+          schedule_next_execution_after_completion(coordination_log, execution_time, every)
+        rescue HaltExecutionFlow
+          raise
+        rescue => e
+          # Log the error
+          Rails.logger.error { "Error in periodic task #{method}: #{e.message}" }
+          self.class::ExecutionTracker.track_error(@workflow, e)
+
+          # Handle retry logic for this specific repetition
+          if repetition_log.attempts < max_attempts
+            # Reschedule this same repetition with exponential backoff
+            backoff = (2**[repetition_log.attempts, 5].min).seconds
+
+            self.class
+              .set(wait: backoff)
+              .perform_later(@workflow.key)
+
+            # Halt current execution
+            halt_execution!
+          else
+            # Max attempts reached for this repetition
+            repetition_log.update!(
+              state: :failed,
+              error_message: e.message,
+              error_class: e.class.name
+            )
+
+            # Handle failure based on on_error setting
+            if on_error == :fail_workflow
+              raise ExecutionFailedError, "Periodic task #{method} failed after #{max_attempts} attempts: #{e.message}"
+            else
+              # Continue with next execution despite this failure
+              schedule_next_execution_after_completion(coordination_log, execution_time, every)
+            end
+          end
+        end
+
+        def execute_periodic_method(method, next_execution_at)
+          # Check if the method accepts an argument by looking at its arity
+          method_obj = self.method(method)
+
+          if method_obj.arity != 0
+            # Method accepts arguments (either required or optional), pass next_execution_at
+            send(method, next_execution_at)
+          else
+            # Method takes no arguments
+            send(method)
+          end
+        end
+
+        def schedule_next_execution_after_completion(coordination_log, current_execution_time, every)
+          # Calculate next execution time
+          next_execution_time = current_execution_time + every
+
+          # Calculate delay until next execution
+          delay = [next_execution_time - Time.current, 0].max.seconds
+
+          # Schedule the workflow to run for the next periodic execution
+          self.class
+            .set(wait: delay)
+            .perform_later(@workflow.key)
+
+          # Halt current execution
+          halt_execution!
+        end
+      end
+    end
+  end
+end

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

@@ -2,11 +2,82 @@ module ChronoForge
   module Executor
     module Methods
       module Wait
-        def wait(duration, name, **options)
-          # Create execution log
+        # Pauses workflow execution for a specified duration.
+        #
+        # This method provides durable waiting that persists across workflow restarts and
+        # system interruptions. The wait duration and completion state are tracked in
+        # execution logs, ensuring that workflows can resume properly after delays.
+        #
+        # @param duration [ActiveSupport::Duration] How long to wait (e.g., 5.minutes, 2.hours, 1.day)
+        # @param name [String] A unique name for this wait step, used for tracking and idempotency
+        #
+        # @return [nil]
+        #
+        # @example Basic usage
+        #   wait 30.minutes, "cool_down_period"
+        #
+        # @example Waiting between API calls
+        #   wait 5.seconds, "rate_limit_delay"
+        #
+        # @example Daily processing delay
+        #   wait 1.day, "daily_batch_interval"
+        #
+        # @example Workflow with multiple wait steps
+        #   def process_user_onboarding
+        #     send_welcome_email
+        #     wait 1.hour, "welcome_email_delay"
+        #
+        #     send_tutorial_email
+        #     wait 1.day, "tutorial_followup_delay"
+        #
+        #     send_feedback_request
+        #   end
+        #
+        # @example Waiting for external system processing
+        #   def handle_payment_processing
+        #     initiate_payment_request
+        #
+        #     # Give payment processor time to handle the request
+        #     wait 10.minutes, "payment_processing_window"
+        #
+        #     check_payment_status
+        #   end
+        #
+        # == Behavior
+        #
+        # === Duration Handling
+        # - Accepts any ActiveSupport::Duration (seconds, minutes, hours, days, etc.)
+        # - Wait time is calculated from the first execution attempt
+        # - Completion is checked against the originally scheduled end time
+        #
+        # === Idempotency
+        # - Each wait step must have a unique name within the workflow
+        # - If workflow is replayed after the wait period has passed, the step is skipped
+        # - Wait periods are not recalculated on workflow restarts
+        #
+        # === Resumability
+        # - Wait state is persisted in execution logs with target end time
+        # - Workflows can be stopped and restarted without affecting wait behavior
+        # - System restarts don't reset or extend wait periods
+        # - Scheduled execution resumes automatically when wait period completes
+        #
+        # === Scheduling
+        # - Uses background job scheduling to resume workflow after wait period
+        # - Halts current workflow execution until scheduled time
+        # - Automatically reschedules if workflow is replayed before wait completion
+        #
+        # === Execution Logs
+        # Creates execution log with step name: `wait$#{name}`
+        # - Stores target end time in metadata as "wait_until"
+        # - Tracks attempt count and execution times
+        # - Marks as completed when wait period has elapsed
+        #
+        def wait(duration, name)
+          step_name = "wait$#{name}"
+          # Find or create execution log
           execution_log = ExecutionLog.create_or_find_by!(
             workflow: @workflow,
-            step_name: "wait$#{name}"
+            step_name: step_name
           ) do |log|
             log.started_at = Time.current
             log.metadata = {

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

@@ -4,13 +4,92 @@ module ChronoForge
 
     module Methods
       module WaitUntil
-        def wait_until(condition, **options)
-          # Default timeout and check interval
-          timeout = options[:timeout] || 1.hour
-          check_interval = options[:check_interval] || 15.minutes
-
-          # Find or create execution log
+        # Waits until a specified condition becomes true, with configurable timeout and polling interval.
+        #
+        # This method provides durable waiting behavior that can survive workflow restarts and delays.
+        # It periodically checks a condition method until it returns true or a timeout is reached.
+        # The waiting state is persisted, making it resilient to system interruptions.
+        #
+        # @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 timeout [ActiveSupport::Duration] Maximum time to wait for condition (default: 1.hour)
+        # @param check_interval [ActiveSupport::Duration] Time between condition checks (default: 15.minutes)
+        # @param retry_on [Array<Class>] Exception classes that should trigger retries instead of failures
+        #
+        # @return [true] When the condition is met
+        #
+        # @raise [WaitConditionNotMet] When timeout is reached before condition is met
+        # @raise [ExecutionFailedError] When condition evaluation fails with non-retryable error
+        #
+        # @example Basic usage
+        #   wait_until :payment_confirmed?
+        #
+        # @example With custom timeout and check interval
+        #   wait_until :external_api_ready?, timeout: 30.minutes, check_interval: 1.minute
+        #
+        # @example With retry on specific errors
+        #   wait_until :database_migration_complete?,
+        #     timeout: 2.hours,
+        #     check_interval: 30.seconds,
+        #     retry_on: [ActiveRecord::ConnectionNotEstablished, Net::TimeoutError]
+        #
+        # @example Waiting for external system
+        #   def third_party_service_ready?
+        #     response = HTTParty.get("https://api.example.com/health")
+        #     response.code == 200 && response.body.include?("healthy")
+        #   rescue Net::TimeoutError
+        #     false # Will be retried at next check interval
+        #   end
+        #
+        #   wait_until :third_party_service_ready?,
+        #     timeout: 1.hour,
+        #     check_interval: 2.minutes,
+        #     retry_on: [Net::TimeoutError, Net::HTTPClientException]
+        #
+        # @example Waiting for file processing
+        #   def file_processing_complete?
+        #     job_status = ProcessingJobStatus.find_by(file_id: @file_id)
+        #     job_status&.completed? || false
+        #   end
+        #
+        #   wait_until :file_processing_complete?,
+        #     timeout: 45.minutes,
+        #     check_interval: 30.seconds
+        #
+        # == Behavior
+        #
+        # === Condition Evaluation
+        # The condition method is called on each check interval:
+        # - Should return truthy value when condition is met
+        # - Should return falsy value when condition is not yet met
+        # - Can raise exceptions that will be handled based on retry_on parameter
+        #
+        # === Timeout Handling
+        # - Timeout is calculated from the first execution start time
+        # - When timeout is reached, WaitConditionNotMet exception is raised
+        # - Timeout checking happens before each condition evaluation
+        #
+        # === Error Handling
+        # - Exceptions during condition evaluation are caught and logged
+        # - If exception class is in retry_on array, it triggers retry with exponential backoff
+        # - Other exceptions cause immediate failure with ExecutionFailedError
+        # - Retry backoff: 2^attempt seconds (capped at 2^5 = 32 seconds)
+        #
+        # === Persistence and Resumability
+        # - Wait state is persisted in execution logs with metadata
+        # - Workflow can be stopped/restarted without losing wait progress
+        # - Timeout calculation persists across restarts
+        # - Check intervals are maintained even after system interruptions
+        #
+        # === Execution Logs
+        # Creates execution log with step name: `wait_until$#{condition}`
+        # - Stores timeout deadline and check interval in metadata
+        # - Tracks attempt count and execution times
+        # - Records final result (true for success, :timed_out for timeout)
+        #
+        def wait_until(condition, timeout: 1.hour, check_interval: 15.minutes, retry_on: [])
           step_name = "wait_until$#{condition}"
+          # Find or create execution log
           execution_log = ExecutionLog.create_or_find_by!(
             workflow: @workflow,
             step_name: step_name
@@ -18,8 +97,7 @@ module ChronoForge
             log.started_at = Time.current
             log.metadata = {
               timeout_at: timeout.from_now,
-              check_interval: check_interval,
-              condition: condition.to_s
+              check_interval: check_interval
             }
           end
 
@@ -35,13 +113,7 @@ module ChronoForge
               last_executed_at: Time.current
             )
 
-            condition_met = if condition.is_a?(Proc)
-              condition.call(@context)
-            elsif condition.is_a?(Symbol)
-              send(condition)
-            else
-              raise ArgumentError, "Unsupported condition type"
-            end
+            condition_met = send(condition)
           rescue HaltExecutionFlow
             raise
           rescue => e
@@ -50,9 +122,9 @@ module ChronoForge
             self.class::ExecutionTracker.track_error(workflow, e)
 
             # Optional retry logic
-            if (options[:retry_on] || []).include?(e.class)
+            if retry_on.include?(e.class)
               # Reschedule with exponential backoff
-              backoff = (2**[execution_log.attempts || 1, 5].min).seconds
+              backoff = (2**[execution_log.attempts, 5].min).seconds
 
               self.class
                 .set(wait: backoff)
@@ -77,6 +149,8 @@ module ChronoForge
             execution_log.update!(
               state: :completed,
               completed_at: Time.current,
+              error_message: "Execution timed out",
+              error_class: "TimeoutError",
               metadata: execution_log.metadata.merge("result" => true)
             )
             return true
@@ -87,7 +161,7 @@ module ChronoForge
           if Time.current > metadata["timeout_at"]
             execution_log.update!(
               state: :failed,
-              metadata: metadata.merge("result" => nil)
+              metadata: metadata.merge("result" => :timed_out)
             )
             Rails.logger.warn { "Timeout reached for condition '#{condition}'." }
             raise WaitConditionNotMet, "Condition '#{condition}' not met within timeout period"