chrono_forge 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f65c15313d0538a84fe916c5d3fd1966e593364d00e777aa2d1693a5bc801102
-  data.tar.gz: 9a3a1c025dd348d46c9169bb03a3fc26a975b5c0eb5411d032410c9f8a70e564
+  metadata.gz: b16c027867c5aca8d3f168ccb252125feef563731af33f40a129bfa9bfb781c5
+  data.tar.gz: 0ebd43e1896ea8df4ceb00c9c9af49c57a1e74d309149e817e43f9acfdfd5b8a
 SHA512:
-  metadata.gz: 31c16f81bbfefd72f6ad4799a2ab7eeac2ffe11a8a8f2d12606632b36d843a8dc518c27a0e2f5a992184619004c7de5f3e60c4b19f55ab63b38f49e67ee32e79
-  data.tar.gz: 233e0badc22ad43f4084b2acfc83782d41da6b0949d6b7ee9b050b89ee4a9fbbbac46dd74029470af58dd4293767f1200ee46b3ed19dfa7eaba89c3901e8b3f8
+  metadata.gz: c94edc3ed7339bf3c7304c54e547bb1f86bc098dda586ffa049cfaf2fc29efcc7b44cce9429789ee1c3c5559dd3dd75859b75e74a27587c2a804160fee600f42
+  data.tar.gz: f7350954cace2c26ca57c7c0253a81d098a2eb655a5f283e6627eedec9d2b4acc11e0f58d3bebe47cd8a4c82907e1c4410d3655c43695ec8f02b8cc0af6a52c2

data/README.md

@@ -1,21 +1,26 @@
 # ChronoForge
 
-ChronoForge is a Ruby gem that provides a robust framework for building durable, distributed workflows in Ruby on Rails applications. It offers a reliable way to handle long-running processes, state management, and error recovery.
+![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+> A robust framework for building durable, distributed workflows in Ruby on Rails applications
+
+ChronoForge provides a powerful solution for handling long-running processes, managing state, and recovering from failures in your Rails applications. Built on top of ActiveJob, it ensures your critical business processes remain resilient and traceable.
+
+## 🌟 Features
 
 - **Durable Execution**: Automatically tracks and recovers from failures during workflow execution
-- **State Management**: Built-in workflow state tracking with support for custom contexts
-- **Concurrency Control**: Advanced locking mechanisms to prevent concurrent execution of the same workflow
-- **Error Handling**: Comprehensive error tracking and retry strategies
-- **Execution Logging**: Detailed logging of workflow execution steps and errors
+- **State Management**: Built-in workflow state tracking with persistent context storage
+- **Concurrency Control**: Advanced locking mechanisms to prevent parallel execution of the same workflow
+- **Error Handling**: Comprehensive error tracking with configurable retry strategies
+- **Execution Logging**: Detailed logging of workflow steps and errors for visibility
 - **Wait States**: Support for time-based waits and condition-based waiting
-- **Database-Backed**: All workflow state is persisted to the database for durability
-- **ActiveJob Integration**: Seamlessly works with any ActiveJob backend
+- **Database-Backed**: All workflow state is persisted to ensure durability
+- **ActiveJob Integration**: Compatible with all ActiveJob backends, though database-backed processors (like Solid Queue) provide the most reliable experience for long-running workflows
 
-## Installation
+## 📦 Installation
 
-Add this line to your application's Gemfile:
+Add to your application's Gemfile:
 
 ```ruby
 gem 'chrono_forge'
@@ -27,7 +32,7 @@ Then execute:
 $ bundle install
 ```
 
-Or install it directly:
+Or install directly:
 
 ```bash
 $ gem install chrono_forge
@@ -40,7 +45,7 @@ $ rails generate chrono_forge:install
 $ rails db:migrate
 ```
 
-## Usage
+## 📋 Usage
 
 ### Basic Workflow Example
 
@@ -52,7 +57,7 @@ class OrderProcessingWorkflow < ApplicationJob
 
   def perform
     # Context can be used to pass and store data between executions
-    context["order_id"] = SecureRandom.hex
+    context.set_once "order_id", SecureRandom.hex
 
     # Wait until payment is confirmed
     wait_until :payment_confirmed?
@@ -74,22 +79,22 @@ class OrderProcessingWorkflow < ApplicationJob
   end
 
   def process_order
-    context["processed_at"] = Time.current.iso8601
     OrderProcessor.process(context["order_id"])
+    context["processed_at"] = Time.current.iso8601
   end
 
   def complete_order
-    context["completed_at"] = Time.current.iso8601
     OrderCompletionService.complete(context["order_id"])
+    context["completed_at"] = Time.current.iso8601
   end
 end
 ```
 
-### Workflow Features
+### Core Workflow Features
 
-#### Durable Execution
+#### ⚡ Durable Execution
 
-The `durably_execute` method ensures operations are executed exactly once:
+The `durably_execute` method ensures operations are executed exactly once, even if the job fails and is retried:
 
 ```ruby
 # Execute a method
@@ -101,7 +106,7 @@ durably_execute -> (ctx) {
 }
 ```
 
-#### Wait States
+#### ⏱️ Wait States
 
 ChronoForge supports both time-based and condition-based waits:
 
@@ -115,9 +120,9 @@ wait_until :payment_processed,
   check_interval: 5.minutes
 ```
 
-#### Workflow Context
+#### 🔄 Workflow Context
 
-ChronoForge provides a persistent context that survives job restarts:
+ChronoForge provides a persistent context that survives job restarts. The context behaves like a Hash but with additional capabilities:
 
 ```ruby
 # Set context values
@@ -126,11 +131,25 @@ context[:status] = "processing"
 
 # Read context values
 user_name = context[:user_name]
+
+# Using the fetch method (returns default if key doesn't exist)
+status = context.fetch(:status, "pending")
+
+# Set a value with the set method (alias for []=)
+context.set(:total_amount, 99.99)
+
+# Set a value only if the key doesn't already exist
+context.set_once(:created_at, Time.current.iso8601)
+
+# Check if a key exists
+if context.key?(:user_id)
+  # Do something with the user ID
+end
 ```
 
-### Error Handling
+### 🛡️ Error Handling
 
-ChronoForge automatically tracks errors and provides retry capabilities:
+ChronoForge automatically tracks errors and provides configurable retry capabilities:
 
 ```ruby
 class MyWorkflow < ApplicationJob
@@ -141,19 +160,19 @@ class MyWorkflow < ApplicationJob
   def should_retry?(error, attempt_count)
     case error
     when NetworkError
-      attempt_count < 5
+      attempt_count < 5  # Retry network errors up to 5 times
     when ValidationError
       false  # Don't retry validation errors
     else
-      attempt_count < 3
+      attempt_count < 3  # Default retry policy
     end
   end
 end
 ```
 
-## Testing
+## 🧪 Testing
 
-ChronoForge is designed to be easily testable using [ChaoticJob](https://github.com/fractaledmind/chaotic_job), a testing framework that makes it simple to test complex job workflows. Here's how to set up your test environment:
+ChronoForge is designed to be easily testable using [ChaoticJob](https://github.com/fractaledmind/chaotic_job), a testing framework that makes it simple to test complex job workflows:
 
 1. Add ChaoticJob to your Gemfile's test group:
 
@@ -196,22 +215,24 @@ class WorkflowTest < ActiveJob::TestCase
 end
 ```
 
-ChaoticJob provides several helpful methods for testing workflows:
+## 🗄️ Database Schema
 
-- `perform_all_jobs`: Processes all enqueued jobs, including those enqueued during job execution
-
-For testing with specific job processing libraries like Sidekiq or Delayed Job, you can still use their respective testing modes, but ChaoticJob is recommended for testing ChronoForge workflows as it better handles the complexities of nested job scheduling and wait states.
+ChronoForge creates three main tables:
 
+1. **chrono_forge_workflows**: Stores workflow state and context
+2. **chrono_forge_execution_logs**: Tracks individual execution steps
+3. **chrono_forge_error_logs**: Records detailed error information
 
-## Database Schema
+## 🔍 When to Use ChronoForge
 
-ChronoForge creates three main tables:
+ChronoForge is ideal for:
 
-1. `chrono_forge_workflows`: Stores workflow state and context
-2. `chrono_forge_execution_logs`: Tracks individual execution steps
-3. `chrono_forge_error_logs`: Records detailed error information
+- **Long-running business processes** - Order processing, account registration flows
+- **Processes requiring durability** - Financial transactions, data migrations
+- **Multi-step workflows** - Onboarding flows, approval processes, multi-stage jobs
+- **State machines with time-based transitions** - Document approval, subscription lifecycle
 
-## Development
+## 🚀 Development
 
 After checking out the repo, run:
 
@@ -227,7 +248,7 @@ The test suite uses SQLite by default and includes:
 - Integration tests with ActiveJob
 - Example workflow implementations
 
-## Contributing
+## 👥 Contributing
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/my-new-feature`)
@@ -237,6 +258,6 @@ The test suite uses SQLite by default and includes:
 
 Please include tests for any new features or bug fixes.
 
-## License
+## 📜 License
 
 This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/export.json

@@ -13,7 +13,7 @@
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/export.rb",
-    "contents": "require \"json\"\nrequire \"find\"\n\ndef export_files_to_json(directory, extensions, output_file, exceptions = [])\n  # Convert extensions to lowercase for case-insensitive matching\n  extensions = extensions.map(&:downcase)\n\n  # Array to store file data\n  files_data = []\n\n  # Find all files in directory and subdirectories\n  Find.find(directory) do |path|\n    # Skip if not a file\n    next unless File.file?(path)\n    next if exceptions.any? { |exception| path.include?(exception) }\n\n    # Check if file extension matches any in our list\n    ext = File.extname(path).downcase[1..-1] # Remove the leading dot\n    next unless extensions.include?(ext)\n\n    puts path\n\n    begin\n      # Read file contents\n      contents = File.read(path)\n\n      # Add to our array\n      files_data << {\n        \"path\" => path,\n        \"contents\" => contents\n      }\n    rescue => e\n      puts \"Error reading file #{path}: #{e.message}\"\n    end\n  end\n\n  # Write to JSON file\n  File.write(output_file, JSON.pretty_generate(files_data))\n\n  puts \"Successfully exported #{files_data.length} files to #{output_file}\"\nend\n\n# Example usage (uncomment and modify as needed):\ndirectory = \"/Users/stefan/Documents/plutonium/chrono_forge\"\nexceptions = [\"/.github/\", \"/.vscode/\", \"gemfiles\", \"pkg\", \"node_modules\"]\nextensions = [\"rb\", \"md\", \"yml\", \"yaml\", \"gemspec\"]\noutput_file = \"export.json\"\nexport_files_to_json(directory, extensions, output_file, exceptions)\n"
+    "contents": "require \"json\"\nrequire \"find\"\n\ndef export_files_to_json(directory, extensions, output_file, exceptions = [])\n  # Convert extensions to lowercase for case-insensitive matching\n  extensions = extensions.map(&:downcase)\n\n  # Array to store file data\n  files_data = []\n\n  # Find all files in directory and subdirectories\n  Find.find(directory) do |path|\n    # Skip if not a file\n    next unless File.file?(path)\n    next if exceptions.any? { |exception| path.include?(exception) }\n\n    # Check if file extension matches any in our list\n    ext = File.extname(path).downcase[1..] # Remove the leading dot\n    next unless extensions.include?(ext)\n\n    puts path\n\n    begin\n      # Read file contents\n      contents = File.read(path)\n\n      # Add to our array\n      files_data << {\n        \"path\" => path,\n        \"contents\" => contents\n      }\n    rescue => e\n      puts \"Error reading file #{path}: #{e.message}\"\n    end\n  end\n\n  # Write to JSON file\n  File.write(output_file, JSON.pretty_generate(files_data))\n\n  puts \"Successfully exported #{files_data.length} files to #{output_file}\"\nend\n\n# Example usage (uncomment and modify as needed):\ndirectory = \"/Users/stefan/Documents/plutonium/chrono_forge\"\nexceptions = [\"/.github/\", \"/.vscode/\", \"gemfiles\", \"pkg\", \"node_modules\"]\nextensions = [\"rb\", \"md\", \"yml\", \"yaml\", \"gemspec\"]\noutput_file = \"export.json\"\nexport_files_to_json(directory, extensions, output_file, exceptions)\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/error_log.rb",
@@ -25,7 +25,7 @@
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/executor/context.rb",
-    "contents": "module ChronoForge\n  module Executor\n    class Context\n      class ValidationError < Error; end\n\n      ALLOWED_TYPES = [\n        String,\n        Integer,\n        Float,\n        TrueClass,\n        FalseClass,\n        NilClass,\n        Hash,\n        Array\n      ]\n\n      def initialize(workflow)\n        @workflow = workflow\n        @context = workflow.context || {}\n        @dirty = false\n      end\n\n      def []=(key, value)\n        # Type and size validation\n        validate_value!(value)\n\n        @context[key.to_s] =\n          if value.is_a?(Hash) || value.is_a?(Array)\n            deep_dup(value)\n          else\n            value\n          end\n\n        @dirty = true\n      end\n\n      def [](key)\n        @context[key.to_s]\n      end\n\n      def save!\n        return unless @dirty\n\n        @workflow.update_column(:context, @context)\n        @dirty = false\n      end\n\n      private\n\n      def validate_value!(value)\n        unless ALLOWED_TYPES.any? { |type| value.is_a?(type) }\n          raise ValidationError, \"Unsupported context value type: #{value.inspect}\"\n        end\n\n        # Optional: Add size constraints\n        if value.is_a?(String) && value.size > 64.kilobytes\n          raise ValidationError, \"Context value too large\"\n        end\n      end\n\n      def deep_dup(obj)\n        JSON.parse(JSON.generate(obj))\n      rescue\n        obj.dup\n      end\n    end\n  end\nend\n"
+    "contents": "module ChronoForge\n  module Executor\n    class Context\n      class ValidationError < Error; end\n\n      ALLOWED_TYPES = [\n        String,\n        Integer,\n        Float,\n        TrueClass,\n        FalseClass,\n        NilClass,\n        Hash,\n        Array\n      ]\n\n      def initialize(workflow)\n        @workflow = workflow\n        @context = workflow.context || {}\n        @dirty = false\n      end\n\n      def []=(key, value)\n        set_value(key, value)\n      end\n\n      def [](key)\n        get_value(key)\n      end\n\n      # Fetches a value from the context\n      # Returns the value if the key exists, otherwise returns the default value\n      def fetch(key, default = nil)\n        key?(key) ? get_value(key) : default\n      end\n\n      # Sets a value in the context\n      # Alias for the []= method\n      def set(key, value)\n        set_value(key, value)\n      end\n\n      # Sets a value in the context only if the key doesn't already exist\n      # Returns true if the value was set, false otherwise\n      def set_once(key, value)\n        return false if key?(key)\n\n        set_value(key, value)\n        true\n      end\n\n      def key?(key)\n        @context.key?(key.to_s)\n      end\n\n      def save!\n        return unless @dirty\n\n        @workflow.update_column(:context, @context)\n        @dirty = false\n      end\n\n      private\n\n      def set_value(key, value)\n        validate_value!(value)\n\n        @context[key.to_s] =\n          if value.is_a?(Hash) || value.is_a?(Array)\n            deep_dup(value)\n          else\n            value\n          end\n\n        @dirty = true\n      end\n\n      def get_value(key)\n        @context[key.to_s]\n      end\n\n      def validate_value!(value)\n        unless ALLOWED_TYPES.any? { |type| value.is_a?(type) }\n          raise ValidationError, \"Unsupported context value type: #{value.inspect}\"\n        end\n\n        # Optional: Add size constraints\n        if value.is_a?(String) && value.size > 64.kilobytes\n          raise ValidationError, \"Context value too large\"\n        end\n      end\n\n      def deep_dup(obj)\n        JSON.parse(JSON.generate(obj))\n      rescue\n        obj.dup\n      end\n    end\n  end\nend\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/executor/execution_tracker.rb",
@@ -37,7 +37,7 @@
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/executor/methods/durably_execute.rb",
-    "contents": "module ChronoForge\n  module Executor\n    module Methods\n      module DurablyExecute\n        def durably_execute(method, **options)\n          # Create execution log\n          step_name = \"durably_execute$#{method}\"\n          execution_log = ExecutionLog.create_or_find_by!(\n            workflow: @workflow,\n            step_name: step_name\n          ) do |log|\n            log.started_at = Time.current\n          end\n\n          # Return if already completed\n          return if execution_log.completed?\n\n          # Execute with error handling\n          begin\n            # Update execution log with attempt\n            execution_log.update!(\n              attempts: execution_log.attempts + 1,\n              last_executed_at: Time.current\n            )\n\n            # Execute the method\n            if method.is_a?(Symbol)\n              send(method)\n            else\n              method.call(@context)\n            end\n\n            # Complete the execution\n            execution_log.update!(\n              state: :completed,\n              completed_at: Time.current\n            )\n            result\n          rescue HaltExecutionFlow\n            raise\n          rescue => e\n            # Log the error\n            Rails.logger.error { \"Error while durably executing #{method}: #{e.message}\" }\n            self.class::ExecutionTracker.track_error(workflow, e)\n\n            # Optional retry logic\n            if execution_log.attempts < (options[:max_attempts] || 3)\n              # Reschedule with exponential backoff\n              backoff = (2**[execution_log.attempts || 1, 5].min).seconds\n\n              self.class\n                .set(wait: backoff)\n                .perform_later(\n                  @workflow.key,\n                  retry_method: method\n                )\n\n              # Halt current execution\n              halt_execution!\n            else\n              # Max attempts reached\n              execution_log.update!(\n                state: :failed,\n                error_message: e.message,\n                error_class: e.class.name\n              )\n              raise ExecutionFailedError, \"#{step_name} failed after maximum attempts\"\n            end\n          end\n        end\n      end\n    end\n  end\nend\n"
+    "contents": "module ChronoForge\n  module Executor\n    module Methods\n      module DurablyExecute\n        def durably_execute(method, **options)\n          # Create execution log\n          step_name = \"durably_execute$#{method}\"\n          execution_log = ExecutionLog.create_or_find_by!(\n            workflow: @workflow,\n            step_name: step_name\n          ) do |log|\n            log.started_at = Time.current\n          end\n\n          # Return if already completed\n          return if execution_log.completed?\n\n          # Execute with error handling\n          begin\n            # Update execution log with attempt\n            execution_log.update!(\n              attempts: execution_log.attempts + 1,\n              last_executed_at: Time.current\n            )\n\n            # Execute the method\n            if method.is_a?(Symbol)\n              send(method)\n            else\n              method.call(@context)\n            end\n\n            # Complete the execution\n            execution_log.update!(\n              state: :completed,\n              completed_at: Time.current\n            )\n            \n            # return nil\n            nil\n          rescue HaltExecutionFlow\n            raise\n          rescue => e\n            # Log the error\n            Rails.logger.error { \"Error while durably executing #{method}: #{e.message}\" }\n            self.class::ExecutionTracker.track_error(workflow, e)\n\n            # Optional retry logic\n            if execution_log.attempts < (options[:max_attempts] || 3)\n              # Reschedule with exponential backoff\n              backoff = (2**[execution_log.attempts || 1, 5].min).seconds\n\n              self.class\n                .set(wait: backoff)\n                .perform_later(\n                  @workflow.key,\n                  retry_method: method\n                )\n\n              # Halt current execution\n              halt_execution!\n            else\n              # Max attempts reached\n              execution_log.update!(\n                state: :failed,\n                error_message: e.message,\n                error_class: e.class.name\n              )\n              raise ExecutionFailedError, \"#{step_name} failed after maximum attempts\"\n            end\n          end\n        end\n      end\n    end\n  end\nend\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/executor/methods/wait.rb",
@@ -61,7 +61,7 @@
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/version.rb",
-    "contents": "# frozen_string_literal: true\n\nmodule ChronoForge\n  VERSION = \"0.1.1\"\nend\n"
+    "contents": "# frozen_string_literal: true\n\nmodule ChronoForge\n  VERSION = \"0.2.0\"\nend\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/workflow.rb",

data/export.rb

@@ -15,7 +15,7 @@ def export_files_to_json(directory, extensions, output_file, exceptions = [])
     next if exceptions.any? { |exception| path.include?(exception) }
 
     # Check if file extension matches any in our list
-    ext = File.extname(path).downcase[1..-1] # Remove the leading dot
+    ext = File.extname(path).downcase[1..] # Remove the leading dot
     next unless extensions.include?(ext)
 
     puts path

data/lib/chrono_forge/executor/context.rb

@@ -21,21 +21,36 @@ module ChronoForge
       end
 
       def []=(key, value)
-        # Type and size validation
-        validate_value!(value)
+        set_value(key, value)
+      end
 
-        @context[key.to_s] =
-          if value.is_a?(Hash) || value.is_a?(Array)
-            deep_dup(value)
-          else
-            value
-          end
+      def [](key)
+        get_value(key)
+      end
 
-        @dirty = true
+      # Fetches a value from the context
+      # Returns the value if the key exists, otherwise returns the default value
+      def fetch(key, default = nil)
+        key?(key) ? get_value(key) : default
       end
 
-      def [](key)
-        @context[key.to_s]
+      # Sets a value in the context
+      # Alias for the []= method
+      def set(key, value)
+        set_value(key, value)
+      end
+
+      # Sets a value in the context only if the key doesn't already exist
+      # Returns true if the value was set, false otherwise
+      def set_once(key, value)
+        return false if key?(key)
+
+        set_value(key, value)
+        true
+      end
+
+      def key?(key)
+        @context.key?(key.to_s)
       end
 
       def save!
@@ -47,6 +62,23 @@ module ChronoForge
 
       private
 
+      def set_value(key, value)
+        validate_value!(value)
+
+        @context[key.to_s] =
+          if value.is_a?(Hash) || value.is_a?(Array)
+            deep_dup(value)
+          else
+            value
+          end
+
+        @dirty = true
+      end
+
+      def get_value(key)
+        @context[key.to_s]
+      end
+
       def validate_value!(value)
         unless ALLOWED_TYPES.any? { |type| value.is_a?(type) }
           raise ValidationError, "Unsupported context value type: #{value.inspect}"

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

@@ -35,7 +35,9 @@ module ChronoForge
               state: :completed,
               completed_at: Time.current
             )
-            result
+            
+            # return nil
+            nil
           rescue HaltExecutionFlow
             raise
           rescue => e

data/lib/chrono_forge/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chrono_forge
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-27 00:00:00.000000000 Z
+date: 2025-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord