chrono_forge 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c9315ad74de7245484119f385f2eb9706d1e3e532e142696d03d204e37f81ad
-  data.tar.gz: 4ea5ef5858c6d5fc8903f5432dd1ddc643d3cb6d26e65693c8a30664224a51c5
+  metadata.gz: cbb73c055f7439bc5e787d68a6d46bbb687143a85a3d57dcade8910aaae93916
+  data.tar.gz: 7b40ca8cc17398e695434c3e1ab61c7cfa12dfeb0ac941dd257daa18b633dbed
 SHA512:
-  metadata.gz: 4713568fd2d32ddc70737fb5eb2f91db90aa41ff80d446afcd91f79719938e427f87b06da69dae18fb253c751aec07a70954e2f941053cb748db7fed04304ff0
-  data.tar.gz: caed47e85300d073b9ee1309d33b05047f2b0e6f60e95612ca247c86f233a32c823f9d68307e77384573c250b1779407e630a2f7ecd3557d2c033482f4326263
+  metadata.gz: 0a6db6125a515d250b19ba3bd59db16056973a0d23df3acf76b5341a7990f962694dec5b9732302a0a850844c62a97847640c289bdebcee0f684f691e214049f
+  data.tar.gz: 852d241932f2cfc28e48bb6713f79d0c5086dfe8f92b92828f6ef03943250c548cef331de43d208d756c209ea99633f3ab99229391dd8c207fed47b6e4bf31f4

data/README.md

@@ -288,6 +288,100 @@ ChronoForge is ideal for:
 - **Multi-step workflows** - Onboarding flows, approval processes, multi-stage jobs
 - **State machines with time-based transitions** - Document approval, subscription lifecycle
 
+## 🧠 Advanced State Management
+
+ChronoForge workflows follow a sophisticated state machine model to ensure durability and fault tolerance. Understanding these states and transitions is essential for troubleshooting and recovery.
+
+### Workflow State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> created: Workflow Created
+    created --> idle: Initial State
+    idle --> running: Job Started
+    running --> idle: Waiting
+    running --> completed: All Steps Completed
+    running --> failed: Max Retries Exhausted
+    running --> stalled: Unrecoverable Error
+    idle --> running: Resumed
+    stalled --> [*]: Requires Manual Intervention
+    failed --> [*]: Requires Manual Intervention
+    completed --> [*]: Workflow Succeeded
+```
+
+### State Descriptions
+
+#### Created
+- **Description**: Initial state when a workflow record is first created
+- **Behavior**: Transitions immediately to idle state
+- **Duration**: Momentary
+
+#### Idle
+- **Description**: The workflow is waiting to be processed or between processing steps
+- **Behavior**: Not locked, available to be picked up by job processor
+- **Duration**: Can be minutes to days, depending on wait conditions
+
+#### Running
+- **Description**: The workflow is actively being processed
+- **Identifiers**: Has locked_at and locked_by values set
+- **Behavior**: Protected against concurrent execution
+- **Duration**: Should be brief unless performing long operations
+
+#### Completed
+- **Description**: The workflow has successfully executed all steps
+- **Identifiers**: Has completed_at timestamp, state = "completed"
+- **Behavior**: Final state, no further processing
+- **Typical Exit Points**: All processing completed successfully
+
+#### Failed
+- **Description**: The workflow has failed after exhausting retry attempts
+- **Identifiers**: Has failure-related data in error_logs, state = "failed"
+- **Behavior**: No automatic recovery, requires manual intervention
+- **Typical Exit Points**: Max retries exhausted, explicit failure, non-retryable error
+
+#### Stalled
+- **Description**: The workflow encountered an unrecoverable error but wasn't explicitly failed
+- **Identifiers**: Not completed, not running, has errors in error_logs
+- **Behavior**: Requires manual investigation and intervention
+- **Typical Exit Points**: ExecutionFailedError, unexpected exceptions, system failures
+
+### Handling Different Workflow States
+
+#### Recovering Stalled/Failed Workflows
+
+```ruby
+workflow = ChronoForge::Workflow.find_by(key: "order-123")
+
+if workflow.stalled? || workflow.failed?
+  job_class = workflow.job_class.constantize
+  
+  # Retry immediately
+  job_class.retry_now(workflow.key)
+  
+  # Or retry asynchronously
+  job_class.retry_later(workflow.key)
+end
+```
+
+#### Monitoring Running Workflows
+
+Long-running workflows might indicate issues:
+
+```ruby
+# Find workflows running for too long
+long_running = ChronoForge::Workflow.where(state: :running)
+                                   .where('locked_at < ?', 30.minutes.ago)
+
+long_running.each do |workflow|
+  # Log potential issues for investigation
+  Rails.logger.warn "Workflow #{workflow.key} has been running for >30 minutes"
+  
+  # Optionally force unlock if you suspect deadlock
+  # CAUTION: Only do this if you're certain the job is stuck
+  # workflow.update!(locked_at: nil, locked_by: nil, state: :idle)
+end
+```
+
 ## 🚀 Development
 
 After checking out the repo, run:

data/lib/chrono_forge/executor/lock_strategy.rb

@@ -22,20 +22,23 @@ module ChronoForge
             state: :running
           )
 
+          Rails.logger.debug { "ChronoForge:#{self.class} job(#{job_id}) acquired lock for workflow(#{workflow.key})" }
+
           workflow
         end
       end
 
-      def self.release_lock(job_id, workflow)
+      def self.release_lock(job_id, workflow, force: false)
         workflow = workflow.reload
-        if workflow.locked_by != job_id
+        if !force && workflow.locked_by != job_id
           raise LongRunningConcurrentExecutionError,
-            "#{self.class}(#{job_id}) executed longer than specified max_duration, " \
-            "allowing another instance(#{workflow.locked_by}) to acquire the lock."
+            "ChronoForge:#{self.class} job(#{job_id}) executed longer than specified max_duration, " \
+            "allowed another instance job(#{workflow.locked_by}) to acquire the lock."
         end
 
         columns = {locked_at: nil, locked_by: nil}
-        columns[:state] = :idle if workflow.running?
+        columns[:state] = :idle if force || workflow.running?
+
 
         workflow.update_columns(columns)
       end

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

@@ -35,7 +35,7 @@ module ChronoForge
               state: :completed,
               completed_at: Time.current
             )
-            
+
             # return nil
             nil
           rescue HaltExecutionFlow

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

@@ -0,0 +1,128 @@
+module ChronoForge
+  module Executor
+    module Methods
+      module WorkflowStates
+        private
+        
+        def complete_workflow!
+          # Create an execution log for workflow completion
+          execution_log = ExecutionLog.create_or_find_by!(
+            workflow: workflow,
+            step_name: "$workflow_completion$"
+          ) do |log|
+            log.started_at = Time.current
+          end
+
+          begin
+            execution_log.update!(
+              attempts: execution_log.attempts + 1,
+              last_executed_at: Time.current
+            )
+
+            workflow.completed_at = Time.current
+            workflow.completed!
+
+            # Mark execution log as completed
+            execution_log.update!(
+              state: :completed,
+              completed_at: Time.current
+            )
+
+            # Return the execution log for tracking
+            execution_log
+          rescue => e
+            # Log any errors
+            execution_log.update!(
+              state: :failed,
+              error_message: e.message,
+              error_class: e.class.name
+            )
+            raise
+          end
+        end
+
+        def fail_workflow!(error_log)
+          # Create an execution log for workflow failure
+          execution_log = ExecutionLog.create_or_find_by!(
+            workflow: workflow,
+            step_name: "$workflow_failure$#{error_log.id}"
+          ) do |log|
+            log.started_at = Time.current
+            log.metadata = {
+              error_log_id: error_log.id
+            }
+          end
+
+          begin
+            execution_log.update!(
+              attempts: execution_log.attempts + 1,
+              last_executed_at: Time.current
+            )
+
+            workflow.failed!
+
+            # Mark execution log as completed
+            execution_log.update!(
+              state: :completed,
+              completed_at: Time.current
+            )
+
+            # Return the execution log for tracking
+            execution_log
+          rescue => e
+            # Log any errors
+            execution_log.update!(
+              state: :failed,
+              error_message: e.message,
+              error_class: e.class.name
+            )
+            raise
+          end
+        end
+
+        def retry_workflow!
+          # Check if the workflow is stalled or failed
+          unless workflow.stalled? || workflow.failed?
+            raise WorkflowNotRetryableError, "Cannot retry workflow(#{workflow.key}) in #{workflow.state} state. Only stalled or failed workflows can be retried."
+          end
+
+          # Create an execution log for workflow retry
+          execution_log = ExecutionLog.create!(
+            workflow: workflow,
+            step_name: "$workflow_retry$#{Time.current.to_i}",
+            started_at: Time.current,
+            attempts: 1,
+            last_executed_at: Time.current,
+            metadata: {
+              previous_state: workflow.state,
+              requested_at: Time.current,
+              job_id: job_id
+            }
+          )
+
+          begin
+            # Release any existing locks
+            self.class::LockStrategy.release_lock(job_id, workflow, force: true)
+
+            # Mark execution log as completed
+            execution_log.update!(
+              state: :completed,
+              completed_at: Time.current
+            )
+
+            # Return the execution log for tracking
+            execution_log
+          rescue => e
+            # Log any errors
+            execution_log.update!(
+              state: :failed,
+              error_message: e.message,
+              error_class: e.class.name
+            )
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chrono_forge/executor/methods.rb

@@ -4,6 +4,7 @@ module ChronoForge
       include Methods::Wait
       include Methods::WaitUntil
       include Methods::DurablyExecute
+      include Methods::WorkflowStates
     end
   end
 end

data/lib/chrono_forge/executor.rb

@@ -8,24 +8,68 @@ module ChronoForge
 
     class HaltExecutionFlow < ExecutionFlowControl; end
 
+    class NotExecutableError < Error; end
+
+    class WorkflowNotRetryableError < NotExecutableError; end
+
     include Methods
 
-    def perform(key, attempt: 0, options: {}, **kwargs)
+    # Add class methods
+    def self.prepended(base)
+      class << base
+        # Enforce expected signature for perform_now with key as first arg and keywords after
+        def perform_now(key, **kwargs)
+          if !key.is_a?(String)
+            raise ArgumentError, "Workflow key must be a string as the first argument"
+          end
+          super(key, **kwargs)
+        end
+        
+        # Enforce expected signature for perform_later with key as first arg and keywords after
+        def perform_later(key, **kwargs)
+          if !key.is_a?(String)
+            raise ArgumentError, "Workflow key must be a string as the first argument"
+          end
+          super(key, **kwargs)
+        end
+        
+        # Add retry_now class method that calls perform_now with retry_workflow: true
+        def retry_now(key, **kwargs)
+          perform_now(key, retry_workflow: true, **kwargs)
+        end
+        
+        # Add retry_later class method that calls perform_later with retry_workflow: true
+        def retry_later(key, **kwargs)
+          perform_later(key, retry_workflow: true, **kwargs)
+        end
+      end
+    end
+
+    def perform(key, attempt: 0, retry_workflow: false, options: {}, **kwargs)
       # Prevent excessive retries
       if attempt >= self.class::RetryStrategy.max_attempts
-        Rails.logger.error { "Max attempts reached for job #{key}" }
+        Rails.logger.error { "ChronoForge:#{self.class} max attempts reached for job workflow(#{key})" }
         return
       end
 
       # Find or create job with comprehensive tracking
       setup_workflow(key, options, kwargs)
 
+      # Handle retry parameter - unlock and continue execution
+      retry_workflow! if retry_workflow
+
+      # Track if we acquired the lock
+      lock_acquired = false
+
       begin
-        # Skip if workflow cannot be executed
-        return unless workflow.executable?
+        # Raise error if workflow cannot be executed
+        unless workflow.executable?
+          raise NotExecutableError, "#{self.class}(#{key}) is not in an executable state"
+        end
 
         # Acquire lock with advanced concurrency protection
-        self.class::LockStrategy.acquire_lock(job_id, workflow, max_duration: max_duration)
+        @workflow = self.class::LockStrategy.acquire_lock(job_id, workflow, max_duration: max_duration)
+        lock_acquired = true
 
         # Execute core job logic
         super(**workflow.kwargs.symbolize_keys)
@@ -33,20 +77,22 @@ module ChronoForge
         # Mark as complete
         complete_workflow!
       rescue ExecutionFailedError => e
-        Rails.logger.error { "Execution step failed for #{key}" }
+        Rails.logger.error { "ChronoForge:#{self.class} execution step failed for workflow(#{key})" }
         self.class::ExecutionTracker.track_error(workflow, e)
         workflow.stalled!
         nil
       rescue HaltExecutionFlow
         # Halt execution
-        Rails.logger.debug { "Execution halted for #{key}" }
+        Rails.logger.debug { "ChronoForge:#{self.class} execution halted for workflow(#{key})" }
         nil
       rescue ConcurrentExecutionError
         # Graceful handling of concurrent execution
-        Rails.logger.warn { "Concurrent execution detected for job #{key}" }
+        Rails.logger.warn { "ChronoForge:#{self.class} concurrent execution detected for job #{key}" }
         nil
+      rescue NotExecutableError
+        raise
       rescue => e
-        Rails.logger.error { "An error occurred during execution of #{key}" }
+        Rails.logger.error { "ChronoForge:#{self.class} an error occurred during execution of workflow(#{key})" }
         error_log = self.class::ExecutionTracker.track_error(workflow, e)
 
         # Retry if applicable
@@ -56,90 +102,16 @@ module ChronoForge
           fail_workflow! error_log
         end
       ensure
-        context.save!
-        # Always release the lock
-        self.class::LockStrategy.release_lock(job_id, workflow)
+        # Only release lock if we acquired it
+        if lock_acquired
+          context.save!
+          self.class::LockStrategy.release_lock(job_id, workflow)
+        end
       end
     end
 
     private
 
-    def complete_workflow!
-      # Create an execution log for workflow completion
-      execution_log = ExecutionLog.create_or_find_by!(
-        workflow: workflow,
-        step_name: "$workflow_completion$"
-      ) do |log|
-        log.started_at = Time.current
-      end
-
-      begin
-        execution_log.update!(
-          attempts: execution_log.attempts + 1,
-          last_executed_at: Time.current
-        )
-
-        workflow.completed_at = Time.current
-        workflow.completed!
-
-        # Mark execution log as completed
-        execution_log.update!(
-          state: :completed,
-          completed_at: Time.current
-        )
-
-        # Return the execution log for tracking
-        execution_log
-      rescue => e
-        # Log any completion errors
-        execution_log.update!(
-          state: :failed,
-          error_message: e.message,
-          error_class: e.class.name
-        )
-        raise
-      end
-    end
-
-    def fail_workflow!(error_log)
-      # Create an execution log for workflow failure
-      execution_log = ExecutionLog.create_or_find_by!(
-        workflow: workflow,
-        step_name: "$workflow_failure$"
-      ) do |log|
-        log.started_at = Time.current
-        log.metadata = {
-          error_log_id: error_log.id
-        }
-      end
-
-      begin
-        execution_log.update!(
-          attempts: execution_log.attempts + 1,
-          last_executed_at: Time.current
-        )
-
-        workflow.failed!
-
-        # Mark execution log as completed
-        execution_log.update!(
-          state: :completed,
-          completed_at: Time.current
-        )
-
-        # Return the execution log for tracking
-        execution_log
-      rescue => e
-        # Log any completion errors
-        execution_log.update!(
-          state: :failed,
-          error_message: e.message,
-          error_class: e.class.name
-        )
-        raise
-      end
-    end
-
     def setup_workflow(key, options, kwargs)
       @workflow = find_workflow(key, options, kwargs)
       @context = Context.new(@workflow)

data/lib/chrono_forge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChronoForge
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chrono_forge
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 2025-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -196,6 +196,7 @@ files:
 - lib/chrono_forge/executor/methods/durably_execute.rb
 - lib/chrono_forge/executor/methods/wait.rb
 - lib/chrono_forge/executor/methods/wait_until.rb
+- lib/chrono_forge/executor/methods/workflow_states.rb
 - lib/chrono_forge/executor/retry_strategy.rb
 - lib/chrono_forge/version.rb
 - lib/chrono_forge/workflow.rb