fractor 0.1.4 → 0.1.7

data/examples/workflow/retry/README.adoc

@@ -0,0 +1,248 @@
+= Retry Workflow Example
+
+This example demonstrates Fractor's retry and error handling capabilities for workflows.
+
+== Overview
+
+The retry feature allows workflows to automatically retry failed jobs with configurable backoff strategies. This is essential for handling transient errors in production systems, such as:
+
+* Temporary network issues
+* Rate-limited API calls
+* Database connection timeouts
+* Resource contention
+
+== Features Demonstrated
+
+=== Retry Strategies
+
+==== Exponential Backoff
+
+Delays increase exponentially between retries:
+
+[source,ruby]
+----
+retry_on_error max_attempts: 3,
+               backoff: :exponential,
+               initial_delay: 0.5,
+               max_delay: 5
+----
+
+Delay sequence: 0.5s → 1s → 2s → 4s (capped at 5s)
+
+==== Linear Backoff
+
+Delays increase linearly between retries:
+
+[source,ruby]
+----
+retry_on_error max_attempts: 5,
+               backoff: :linear,
+               initial_delay: 1,
+               increment: 0.5
+----
+
+Delay sequence: 1s → 1.5s → 2s → 2.5s → 3s
+
+==== Constant Delay
+
+Fixed delay between retries:
+
+[source,ruby]
+----
+retry_on_error max_attempts: 4,
+               backoff: :constant,
+               delay: 1
+----
+
+Delay sequence: 1s → 1s → 1s → 1s
+
+=== Error Handlers
+
+Add custom error handling logic:
+
+[source,ruby]
+----
+on_error do |error, context|
+  puts "Error in job: #{error.message}"
+  # Log to monitoring service
+  # Send alerts
+  # Update metrics
+end
+----
+
+=== Fallback Jobs
+
+Provide alternative execution paths when retries are exhausted:
+
+[source,ruby]
+----
+job "fetch_api_data" do
+  runs_with UnreliableApiWorker
+  retry_on_error max_attempts: 3, backoff: :exponential
+  fallback_to "fetch_cached_data"
+end
+
+job "fetch_cached_data" do
+  runs_with CachedDataWorker
+  inputs_from_workflow
+end
+----
+
+== Running the Example
+
+[source,shell]
+----
+ruby examples/workflow/retry/retry_workflow.rb
+----
+
+== Example Output
+
+----
+============================================================
+Retry Workflow Examples
+============================================================
+
+1. Exponential Backoff Retry (with fallback)
+------------------------------------------------------------
+Error in fetch_api_data: API timeout: https://api.example.com/data
+Executing fallback job
+Result: Using cached data from https://api.example.com/data
+Status: SUCCESS
+
+2. Linear Backoff Retry
+------------------------------------------------------------
+Job retry attempt: attempt 2/5, delay: 1.0s
+Job retry attempt: attempt 3/5, delay: 1.5s
+Job retry succeeded on attempt 3
+Result: Fresh data from https://api.example.com/data
+Status: SUCCESS
+
+3. Constant Delay Retry
+------------------------------------------------------------
+Job retry attempt: attempt 2/4, delay: 1.0s
+Job retry attempt: attempt 3/4, delay: 1.0s
+Job retry attempt: attempt 4/4, delay: 1.0s
+Workflow failed after retries: Job 'fetch_api_data' failed: API timeout
+----
+
+== Use Cases
+
+=== External API Calls
+
+[example]
+====
+[source,ruby]
+----
+job "call_payment_api" do
+  runs_with PaymentApiWorker
+  retry_on_error max_attempts: 5,
+                 backoff: :exponential,
+                 retryable_errors: [Net::HTTPRetriableError, Timeout::Error]
+end
+----
+====
+
+=== Database Operations
+
+[example]
+====
+[source,ruby]
+----
+job "save_to_database" do
+  runs_with DatabaseWorker
+  retry_on_error max_attempts: 3,
+                 backoff: :linear,
+                 retryable_errors: [ActiveRecord::ConnectionNotEstablished]
+end
+----
+====
+
+=== File I/O
+
+[example]
+====
+[source,ruby]
+----
+job "write_to_storage" do
+  runs_with StorageWorker
+  retry_on_error max_attempts: 4,
+                 backoff: :constant,
+                 delay: 2
+  fallback_to "write_to_local_cache"
+end
+----
+====
+
+== Best Practices
+
+. *Choose appropriate backoff strategy*
+  * Exponential: Best for most transient errors
+  * Linear: Good for predictable retry windows
+  * Constant: Use when timing is critical
+
+. *Set reasonable max_attempts*
+  * Too few: Might not recover from transient issues
+  * Too many: Wastes resources and delays failure detection
+
+. *Use retryable_errors selectively*
+  * Only retry errors that are likely to be transient
+  * Don't retry validation errors or permanent failures
+
+. *Implement fallback strategies*
+  * Provide cached data
+  * Use default values
+  * Degrade gracefully
+
+. *Monitor retry metrics*
+  * Track retry rates
+  * Alert on high retry counts
+  * Identify patterns in failures
+
+== Configuration Options
+
+[cols="1,1,3"]
+|===
+|Option |Type |Description
+
+|`max_attempts`
+|Integer
+|Maximum number of attempts (including initial attempt). Default: 3
+
+|`backoff`
+|Symbol
+|Retry strategy: `:exponential`, `:linear`, `:constant`, `:none`. Default: `:exponential`
+
+|`initial_delay`
+|Numeric
+|Initial delay in seconds. Default: 1
+
+|`max_delay`
+|Numeric
+|Maximum delay between retries. Default: nil (no cap)
+
+|`increment`
+|Numeric
+|(Linear only) Delay increment per attempt. Default: 1
+
+|`multiplier`
+|Numeric
+|(Exponential only) Delay multiplier per attempt. Default: 2
+
+|`delay`
+|Numeric
+|(Constant only) Fixed delay in seconds. Default: 1
+
+|`timeout`
+|Numeric
+|Job execution timeout in seconds. Default: nil
+
+|`retryable_errors`
+|Array<Class>
+|List of retryable error classes. Default: `[StandardError]`
+|===
+
+== See Also
+
+* link:../../../docs/workflows.adoc[Workflow Documentation]
+* link:../simple_linear/README.adoc[Simple Linear Workflow]
+* link:../conditional/README.adoc[Conditional Workflow]

data/examples/workflow/retry/retry_workflow.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "../../../lib/fractor"
+
+# Simulates an unreliable external API
+class UnreliableApiWorker < Fractor::Worker
+  input_type String
+  output_type Hash
+
+  def process(work)
+    api_url = work.input
+
+    # Simulate random failures (70% failure rate for demonstration)
+    if rand < 0.7
+      raise StandardError, "API timeout: #{api_url}"
+    end
+
+    # Simulate successful response
+    Fractor::WorkResult.new(
+      result: {
+        status: "success",
+        data: { url: api_url, timestamp: Time.now },
+      },
+      work: work,
+    )
+  end
+end
+
+# Fallback worker that uses cached data
+class CachedDataWorker < Fractor::Worker
+  input_type String
+  output_type Hash
+
+  def process(work)
+    api_url = work.input
+
+    # Return cached/default data
+    Fractor::WorkResult.new(
+      result: {
+        status: "cached",
+        data: { url: api_url, cached: true, timestamp: Time.now - 3600 },
+      },
+      work: work,
+    )
+  end
+end
+
+# Process the API response
+class ProcessResponseWorker < Fractor::Worker
+  input_type Hash
+  output_type String
+
+  def process(work)
+    response = work.input
+    status = response[:status]
+    data = response[:data]
+
+    message = if status == "success"
+                "Fresh data from #{data[:url]}"
+              else
+                "Using cached data from #{data[:url]}"
+              end
+
+    Fractor::WorkResult.new(result: message, work: work)
+  end
+end
+
+# Workflow demonstrating retry with exponential backoff
+class ExponentialRetryWorkflow < Fractor::Workflow
+  workflow "exponential-retry-demo" do
+    start_with "fetch_api_data"
+
+    job "fetch_api_data" do
+      runs_with UnreliableApiWorker
+      inputs_from_workflow
+
+      # Retry up to 3 times with exponential backoff
+      retry_on_error max_attempts: 3,
+                     backoff: :exponential,
+                     initial_delay: 0.5,
+                     max_delay: 5
+
+      # Add error handler for logging
+      on_error do |error, context|
+        puts "Error in fetch_api_data: #{error.message}"
+      end
+
+      # Fallback to cached data if all retries fail
+      fallback_to "fetch_cached_data"
+    end
+
+    job "fetch_cached_data" do
+      runs_with CachedDataWorker
+      inputs_from_workflow
+    end
+
+    job "process_response" do
+      runs_with ProcessResponseWorker
+      needs "fetch_api_data"
+      outputs_to_workflow
+    end
+  end
+end
+
+# Workflow demonstrating retry with linear backoff
+class LinearRetryWorkflow < Fractor::Workflow
+  workflow "linear-retry-demo" do
+    start_with "fetch_api_data"
+
+    job "fetch_api_data" do
+      runs_with UnreliableApiWorker
+      inputs_from_workflow
+
+      # Retry up to 5 times with linear backoff
+      retry_on_error max_attempts: 5,
+                     backoff: :linear,
+                     initial_delay: 1,
+                     increment: 0.5
+    end
+
+    job "process_response" do
+      runs_with ProcessResponseWorker
+      needs "fetch_api_data"
+      outputs_to_workflow
+    end
+  end
+end
+
+# Workflow demonstrating retry with constant delay
+class ConstantRetryWorkflow < Fractor::Workflow
+  workflow "constant-retry-demo" do
+    start_with "fetch_api_data"
+
+    job "fetch_api_data" do
+      runs_with UnreliableApiWorker
+      inputs_from_workflow
+
+      # Retry up to 4 times with constant 1 second delay
+      retry_on_error max_attempts: 4,
+                     backoff: :constant,
+                     delay: 1
+    end
+
+    job "process_response" do
+      runs_with ProcessResponseWorker
+      needs "fetch_api_data"
+      outputs_to_workflow
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  puts "=" * 60
+  puts "Retry Workflow Examples"
+  puts "=" * 60
+  puts
+
+  api_url = "https://api.example.com/data"
+
+  puts "1. Exponential Backoff Retry (with fallback)"
+  puts "-" * 60
+  workflow1 = ExponentialRetryWorkflow.new
+  result1 = workflow1.execute(api_url)
+  puts "Result: #{result1.output}"
+  puts "Status: #{result1.success? ? 'SUCCESS' : 'FAILED'}"
+  puts
+
+  puts "2. Linear Backoff Retry"
+  puts "-" * 60
+  workflow2 = LinearRetryWorkflow.new
+  begin
+    result2 = workflow2.execute(api_url)
+    puts "Result: #{result2.output}"
+    puts "Status: #{result2.success? ? 'SUCCESS' : 'FAILED'}"
+  rescue Fractor::WorkflowExecutionError => e
+    puts "Workflow failed after retries: #{e.message}"
+  end
+  puts
+
+  puts "3. Constant Delay Retry"
+  puts "-" * 60
+  workflow3 = ConstantRetryWorkflow.new
+  begin
+    result3 = workflow3.execute(api_url)
+    puts "Result: #{result3.output}"
+    puts "Status: #{result3.success? ? 'SUCCESS' : 'FAILED'}"
+  rescue Fractor::WorkflowExecutionError => e
+    puts "Workflow failed after retries: #{e.message}"
+  end
+  puts
+
+  puts "=" * 60
+  puts "Examples complete"
+  puts "=" * 60
+end

data/examples/workflow/simple_linear/README.adoc

@@ -0,0 +1,267 @@
+= Simple Linear Workflow
+
+== Purpose
+
+Demonstrates sequential job processing with data transformation at each stage using Fractor's workflow system.
+
+== Focus
+
+This example focuses on demonstrating:
+
+* Sequential job dependencies using `needs`
+* Type-safe data flow with `input_type` and `output_type` declarations
+* Workflow entry point definition with `start_with`
+* Workflow exit point definition with `end_with`
+* Job output mapping using `inputs_from_job`
+* Data transformation through a pipeline of workers
+
+== Architecture
+
+.Data Flow Through Sequential Jobs
+[source]
+----
+[Workflow Input]
+      │
+      │ TextData { text: "hello world from fractor" }
+      ▼
+┌─────────────────┐
+│ Uppercase Job   │
+│ UppercaseWorker │
+└─────────────────┘
+      │
+      │ UppercaseOutput { uppercased_text: "HELLO...", char_count: 24 }
+      ▼
+┌─────────────────┐
+│  Reverse Job    │
+│  ReverseWorker  │
+└─────────────────┘
+      │
+      │ ReversedOutput { reversed_text: "ROTCARF...", word_count: 4 }
+      ▼
+┌─────────────────┐
+│ Finalize Job    │
+│ FinalizeWorker  │
+└─────────────────┘
+      │
+      │ FinalOutput { result: "ROTCARF MORF DLROW OLLEH", total_operations: 3 }
+      ▼
+[Workflow Output]
+----
+
+.Workflow Execution Flow
+[source]
+----
+Main Thread
+    │
+    ├─→ Create Workflow Input (TextData)
+    │
+    ├─→ Execute Workflow
+    │       │
+    │       ├─→ Validate Workflow Structure
+    │       │     • Check dependencies (topological sort)
+    │       │     • Verify entry/exit points
+    │       │     • Validate type declarations
+    │       │
+    │       ├─→ Execute Job: "uppercase"
+    │       │     │
+    │       │     ├─→ Create Work from workflow input
+    │       │     ├─→ Spawn Worker Ractor (UppercaseWorker)
+    │       │     ├─→ Process work
+    │       │     └─→ Store result in context
+    │       │
+    │       ├─→ Execute Job: "reverse"
+    │       │     │
+    │       │     ├─→ Build input from "uppercase" output
+    │       │     ├─→ Spawn Worker Ractor (ReverseWorker)
+    │       │     ├─→ Process work
+    │       │     └─→ Store result in context
+    │       │
+    │       └─→ Execute Job: "finalize"
+    │             │
+    │             ├─→ Build input from "reverse" output
+    │             ├─→ Spawn Worker Ractor (FinalizeWorker)
+    │             ├─→ Process work
+    │             └─→ Store result in context
+    │
+    └─→ Return Workflow Result
+            • Status: SUCCESS/FAILED
+            • Output: FinalOutput object
+            • Execution time
+            • Completed jobs list
+----
+
+== Key Components
+
+=== Data Models
+
+Each stage requires explicit input and output type declarations:
+
+[source,ruby]
+----
+class TextData
+  attr_accessor :text
+
+  def initialize(text:)
+    @text = text
+  end
+end
+
+class UppercaseOutput
+  attr_accessor :uppercased_text, :char_count
+
+  def initialize(uppercased_text:, char_count:)
+    @uppercased_text = uppercased_text
+    @char_count = char_count
+  end
+end
+----
+
+=== Workers
+
+Workers declare their expected input and output types using class methods:
+
+[source,ruby]
+----
+class UppercaseWorker < Fractor::Worker
+  input_type TextData      # <1>
+  output_type UppercaseOutput  # <2>
+
+  def process(work)
+    input = work.input
+    uppercased = input.text.upcase
+
+    output = UppercaseOutput.new(
+      uppercased_text: uppercased,
+      char_count: uppercased.length,
+    )
+
+    Fractor::WorkResult.new(result: output, work: work)  # <3>
+  end
+end
+----
+<1> Declares the expected input type for type validation
+<2> Declares the output type returned by this worker
+<3> Returns a WorkResult wrapping the output
+
+=== Workflow Definition
+
+The workflow DSL defines the job dependencies and data flow:
+
+[source,ruby]
+----
+class SimpleLinearWorkflow < Fractor::Workflow
+  workflow "simple-linear" do
+    # Declare workflow input/output types
+    input_type TextData      # <1>
+    output_type FinalOutput  # <2>
+
+    # Define workflow boundaries
+    start_with "uppercase"   # <3>
+    end_with "finalize"      # <4>
+
+    # Job 1: Uppercase the text
+    job "uppercase" do
+      runs_with UppercaseWorker  # <5>
+      inputs_from_workflow       # <6>
+    end
+
+    # Job 2: Reverse the uppercased text
+    job "reverse" do
+      needs "uppercase"              # <7>
+      runs_with ReverseWorker
+      inputs_from_job "uppercase"    # <8>
+    end
+
+    # Job 3: Finalize the result
+    job "finalize" do
+      needs "reverse"
+      runs_with FinalizeWorker
+      inputs_from_job "reverse"
+      outputs_to_workflow           # <9>
+      terminates_workflow           # <10>
+    end
+  end
+end
+----
+<1> Workflow accepts TextData as input
+<2> Workflow returns FinalOutput as output
+<3> First job to execute
+<4> Last job that completes the workflow
+<5> Associates job with worker class
+<6> Job takes input directly from workflow input
+<7> Job dependency - must run after "uppercase"
+<8> Job takes input from "uppercase" job's output
+<9> Job's output becomes workflow output
+<10> Job terminates the workflow when complete
+
+== Usage
+
+Run the example from the project root:
+
+[source,shell]
+----
+ruby examples/workflow/simple_linear/simple_linear_workflow.rb
+----
+
+== Expected Output
+
+[example]
+====
+[source]
+----
+Simple Linear Workflow Example
+==================================================
+
+Input: hello world from fractor
+
+Workflow Results:
+--------------------------------------------------
+Status: SUCCESS
+Execution Time: 0.002s
+Completed Jobs: uppercase, reverse, finalize
+
+Final Output:
+  Result: ROTCARF MORF DLROW OLLEH
+  Total Operations: 3
+----
+====
+
+== Learning Points
+
+=== Sequential Dependencies
+
+* Jobs execute in topological order based on `needs` declarations
+* Each job waits for its dependencies to complete before starting
+* The workflow engine automatically computes the execution order
+
+=== Type Safety
+
+* Workers declare expected input/output types using `input_type` and `output_type`
+* Workflow validates type compatibility at definition time
+* Type declarations serve as documentation and enable validation
+
+=== Data Flow
+
+* `inputs_from_workflow`: Job receives workflow input directly
+* `inputs_from_job "source"`: Job receives output from specified job
+* `outputs_to_workflow`: Job's output becomes the workflow result
+
+=== Workflow Boundaries
+
+* `start_with`: Defines entry point(s) for the workflow
+* `end_with`: Defines exit point(s) for the workflow
+* `terminates_workflow`: Marks jobs that complete the workflow
+
+=== Error Handling
+
+* If any job fails, the workflow stops immediately
+* Workflow result includes success status and error information
+* Completed jobs are tracked even if workflow fails partway through
+
+== Next Steps
+
+After understanding simple linear workflows, explore:
+
+* link:../fan_out/README.adoc[Fan-Out Workflow] - Parallel job execution patterns
+* link:../conditional/README.adoc[Conditional Workflow] - Runtime conditional execution
+* link:../README.adoc[Workflow Overview] - Complete workflow system documentation