durable_workflow 0.1.0

data/examples/item_processor.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Item Processor - Loop through collection and aggregate
+#
+# Demonstrates: Loop step, service calls for computation
+#
+# Run: ruby examples/item_processor.rb
+# Requires: Redis running on localhost:6379
+
+require "bundler/setup"
+require "durable_workflow"
+require "durable_workflow/storage/redis"
+
+# Service for item processing (must be globally accessible)
+module ItemProcessor
+  def self.process(items:)
+    total = 0
+    processed = []
+
+    items.each do |item|
+      line_total = item[:quantity] * item[:price]
+      total += line_total
+      processed << { name: item[:name], subtotal: line_total }
+    end
+
+    {
+      count: items.size,
+      total: total,
+      average: items.empty? ? 0 : total.to_f / items.size,
+      items: processed
+    }
+  end
+end
+
+DurableWorkflow.configure do |c|
+  c.store = DurableWorkflow::Storage::Redis.new(url: "redis://localhost:6379")
+end
+
+workflow = DurableWorkflow::Core::Parser.parse(<<~YAML)
+  id: item_processor
+  name: Item Processor
+  version: "1.0"
+
+  inputs:
+    items:
+      type: array
+      required: true
+
+  steps:
+    - id: start
+      type: start
+      next: process
+
+    - id: process
+      type: call
+      service: ItemProcessor
+      method: process
+      input:
+        items: "$input.items"
+      output: result
+      next: end
+
+    - id: end
+      type: end
+      result:
+        item_count: "$result.count"
+        total: "$result.total"
+        average: "$result.average"
+        items: "$result.items"
+YAML
+
+runner = DurableWorkflow::Runners::Sync.new(workflow)
+
+result = runner.run(input: {
+  items: [
+    { name: "Widget", quantity: 3, price: 10.00 },
+    { name: "Gadget", quantity: 2, price: 25.00 },
+    { name: "Gizmo", quantity: 5, price: 5.00 }
+  ]
+})
+
+puts "Processed #{result.output[:item_count]} items"
+puts "Total: $#{result.output[:total]}"
+puts "Average: $#{result.output[:average].round(2)}"
+puts "Breakdown:"
+result.output[:items].each do |item|
+  puts "  #{item[:name]}: $#{item[:subtotal]}"
+end
+# => Processed 3 items
+# => Total: $105.0
+# => Average: $35.0
+# => Breakdown:
+# =>   Widget: $30.0
+# =>   Gadget: $50.0
+# =>   Gizmo: $25.0

data/examples/order_fulfillment/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "durable_workflow", path: "../.."
+gem "redis"

data/examples/order_fulfillment/README.md

@@ -0,0 +1,84 @@
+# Order Fulfillment
+
+E-commerce order processing workflow demonstrating complex state transitions,
+service integration, parallel execution, and approval workflows.
+
+## Features
+
+- Multi-step order processing pipeline
+- Inventory checking and reservation
+- Payment processing with retry logic
+- Parallel shipping calculations
+- Approval workflow for high-value orders
+- Event streaming for order tracking
+
+## Setup
+
+```bash
+cd examples/order_fulfillment
+bundle install
+redis-server
+```
+
+## Usage
+
+```bash
+ruby run.rb
+```
+
+## Architecture
+
+```
+┌─────────────────┐
+│  Validate Order │
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ Check Inventory │
+└────────┬────────┘
+         ↓ (parallel)
+┌─────────┴─────────┐
+│   Reserve Stock   │
+│   Calculate Ship  │
+└─────────┬─────────┘
+         ↓
+┌─────────────────┐     ┌──────────────┐
+│  Check Amount   │────→│   Approval   │
+└────────┬────────┘     └──────┬───────┘
+         ↓                     ↓
+┌─────────────────┐
+│ Process Payment │
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ Create Shipment │
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│    Complete     │
+└─────────────────┘
+```
+
+## Order States
+
+- `pending` - Initial state
+- `validated` - Order validated
+- `inventory_reserved` - Stock reserved
+- `payment_pending` - Waiting for payment
+- `payment_approved` - High-value order approved
+- `paid` - Payment processed
+- `shipped` - Order shipped
+- `completed` - Order complete
+- `cancelled` - Order cancelled
+- `failed` - Processing failed
+
+## Event Types
+
+Subscribe to real-time order events:
+
+- `order.validated`
+- `order.inventory_reserved`
+- `order.payment_processed`
+- `order.shipped`
+- `order.completed`
+- `order.failed`

data/examples/order_fulfillment/run.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "dotenv/load" if File.exist?(File.expand_path("../../.env", __dir__))
+require "securerandom"
+require "durable_workflow"
+require "durable_workflow/storage/redis"
+require_relative "services"
+
+DurableWorkflow.configure do |c|
+  c.store = DurableWorkflow::Storage::Redis.new(url: "redis://localhost:6379")
+end
+
+# Services are auto-resolved via Object.const_get
+
+workflow = DurableWorkflow.load(File.join(__dir__, "workflow.yml"))
+runner = DurableWorkflow::Runners::Stream.new(workflow)
+
+# Progress tracking
+runner.subscribe do |event|
+  case event.type
+  when "step.started"
+    puts "  [#{Time.now.strftime('%H:%M:%S')}] Starting: #{event.data[:step_id]}"
+  when "step.completed"
+    puts "  [#{Time.now.strftime('%H:%M:%S')}] Completed: #{event.data[:step_id]}"
+  when "workflow.completed"
+    puts "\n[DONE] Order processing completed"
+  when "workflow.failed"
+    puts "\n[FAILED] #{event.data[:error]}"
+  end
+end
+
+puts "=" * 60
+puts "Order Fulfillment Demo"
+puts "=" * 60
+
+# Sample order
+order = {
+  order_id: "ORD-#{SecureRandom.hex(4).upcase}",
+  customer: {
+    id: "CUST-001",
+    email: "alice@example.com",
+    name: "Alice Smith",
+    address: {
+      street: "123 Main St",
+      city: "San Francisco",
+      state: "CA",
+      zip: "94105",
+      country: "US"
+    }
+  },
+  items: [
+    { product_id: "PROD-001", quantity: 2, price: 29.99 },
+    { product_id: "PROD-002", quantity: 1, price: 49.99 }
+  ],
+  payment: {
+    method: "credit_card",
+    token: "tok_visa_4242"
+  },
+  options: {
+    expedited: false,
+    gift_wrap: false
+  }
+}
+
+puts "\nProcessing order: #{order[:order_id]}"
+puts "Customer: #{order[:customer][:name]}"
+puts "Items: #{order[:items].size}"
+puts "-" * 40
+
+result = runner.run(input: order)
+
+puts "\n" + "=" * 60
+puts "Order Result"
+puts "=" * 60
+puts "Order ID: #{result.output[:order_id]}"
+puts "Status: #{result.output[:status]}"
+puts "Total: $#{result.output.dig(:totals, :total)}" if result.output[:totals]
+puts "Payment ID: #{result.output[:payment_id]}" if result.output[:payment_id]
+puts "Tracking: #{result.output[:tracking_number]}" if result.output[:tracking_number]
+
+if result.output[:error]
+  puts "\nError: #{result.output[:error]}"
+end

data/examples/order_fulfillment/services.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+# Order validation and calculation service
+module OrderService
+  class << self
+    def validate_order(order_id:, customer:, items:)
+      errors = []
+
+      errors << "Order ID required" if order_id.nil? || order_id.to_s.empty?
+      errors << "Customer required" if customer.nil?
+      errors << "Customer email required" if customer && customer[:email].to_s.empty?
+      errors << "Items required" if items.nil? || items.empty?
+
+      items&.each_with_index do |item, i|
+        errors << "Item #{i + 1}: product_id required" if item[:product_id].to_s.empty?
+        errors << "Item #{i + 1}: quantity must be positive" if item[:quantity].to_i <= 0
+        errors << "Item #{i + 1}: price required" if item[:price].to_f <= 0
+      end
+
+      {
+        valid: errors.empty?,
+        errors: errors.empty? ? nil : errors,
+        validated_at: Time.now.iso8601
+      }
+    end
+
+    def calculate_totals(items:, options:)
+      subtotal = items.sum { |item| item[:quantity] * item[:price] }
+      tax = subtotal * 0.08
+      shipping = (options && options[:expedited]) ? 14.99 : 5.99
+      total = subtotal + tax + shipping
+
+      {
+        subtotal: subtotal.round(2),
+        tax: tax.round(2),
+        shipping: shipping,
+        total: total.round(2)
+      }
+    end
+  end
+end
+
+# Inventory management service
+module InventoryService
+  STOCK = {
+    "PROD-001" => { name: "Widget Pro", quantity: 100, price: 29.99 },
+    "PROD-002" => { name: "Gadget Plus", quantity: 50, price: 49.99 },
+    "PROD-003" => { name: "Gizmo Max", quantity: 0, price: 99.99 },
+    "PROD-004" => { name: "Device Ultra", quantity: 25, price: 199.99 }
+  }
+
+  RESERVATIONS = {}
+
+  class << self
+    def check_availability(items:)
+      available = []
+      unavailable = []
+
+      items.each do |item|
+        stock = STOCK[item[:product_id]]
+        if stock && stock[:quantity] >= item[:quantity]
+          available << item[:product_id]
+        else
+          unavailable << {
+            product_id: item[:product_id],
+            requested: item[:quantity],
+            available: stock&.dig(:quantity) || 0
+          }
+        end
+      end
+
+      {
+        all_available: unavailable.empty?,
+        available: available,
+        unavailable: unavailable,
+        checked_at: Time.now.iso8601
+      }
+    end
+
+    def reserve(items:, order_id:)
+      reservation_id = "RES-#{SecureRandom.hex(6).upcase}"
+
+      items.each do |item|
+        stock = STOCK[item[:product_id]]
+        stock[:quantity] -= item[:quantity] if stock
+      end
+
+      RESERVATIONS[reservation_id] = {
+        order_id: order_id,
+        items: items,
+        reserved_at: Time.now.iso8601
+      }
+
+      {
+        id: reservation_id,
+        order_id: order_id,
+        items: items.size,
+        reserved_at: Time.now.iso8601
+      }
+    end
+  end
+end
+
+# Shipping service
+module ShippingService
+  class << self
+    def create_shipment(order_id:, customer:, items:)
+      tracking = "TRK#{SecureRandom.hex(8).upcase}"
+      address = customer[:address] || {}
+
+      {
+        shipment_id: "SHIP-#{SecureRandom.hex(6).upcase}",
+        order_id: order_id,
+        tracking_number: tracking,
+        carrier: "FastShip",
+        destination: "#{address[:city]}, #{address[:state]}",
+        estimated_delivery: (Date.today + 5).iso8601,
+        created_at: Time.now.iso8601
+      }
+    end
+  end
+end
+
+# Payment processing service
+module PaymentService
+  class << self
+    def charge(payment:, amount:)
+      token = payment[:token]
+
+      # Simulate declined cards
+      if token == "declined"
+        raise "Card declined"
+      end
+
+      {
+        success: true,
+        payment_id: "PAY-#{SecureRandom.hex(8).upcase}",
+        amount: amount,
+        payment_method: payment[:method],
+        processed_at: Time.now.iso8601
+      }
+    end
+  end
+end

data/examples/order_fulfillment/workflow.yml

@@ -0,0 +1,188 @@
+id: order_fulfillment
+name: Order Fulfillment
+version: "1.0"
+description: E-commerce order processing pipeline
+
+inputs:
+  order_id:
+    type: string
+    required: true
+    description: Unique order identifier
+  customer:
+    type: object
+    required: true
+    description: Customer information
+  items:
+    type: array
+    required: true
+    description: Order line items
+  payment:
+    type: object
+    required: true
+    description: Payment information
+  options:
+    type: object
+    required: false
+    description: Order options
+
+steps:
+  - id: start
+    type: start
+    next: validate
+
+  - id: validate
+    type: call
+    service: OrderService
+    method: validate_order
+    input:
+      order_id: "$input.order_id"
+      customer: "$input.customer"
+      items: "$input.items"
+    output: validation
+    on_error: failed
+    next: check_validation
+
+  - id: check_validation
+    type: router
+    routes:
+      - when:
+          field: validation.valid
+          op: eq
+          value: true
+        then: check_inventory
+    default: failed
+
+  - id: check_inventory
+    type: call
+    service: InventoryService
+    method: check_availability
+    input:
+      items: "$input.items"
+    output: inventory
+    next: inventory_decision
+
+  - id: inventory_decision
+    type: router
+    routes:
+      - when:
+          field: inventory.all_available
+          op: eq
+          value: true
+        then: calculate_totals
+    default: out_of_stock
+
+  - id: out_of_stock
+    type: assign
+    set:
+      status: out_of_stock
+      error: "Items not available"
+      totals: null
+      payment_result: null
+      shipment: null
+    next: end
+
+  - id: calculate_totals
+    type: call
+    service: OrderService
+    method: calculate_totals
+    input:
+      items: "$input.items"
+      options: "$input.options"
+    output: totals
+    next: check_approval
+
+  - id: check_approval
+    type: router
+    routes:
+      - when:
+          field: totals.total
+          op: gt
+          value: 1000
+        then: require_approval
+    default: process_payment
+
+  - id: require_approval
+    type: approval
+    prompt: "High-value order requires approval"
+    context:
+      order_id: "$input.order_id"
+      total: "$totals.total"
+    on_reject: rejected
+    next: process_payment
+
+  - id: rejected
+    type: assign
+    set:
+      status: rejected
+      error: "Order rejected by manager"
+      payment_result: null
+      shipment: null
+    next: end
+
+  - id: process_payment
+    type: call
+    service: PaymentService
+    method: charge
+    input:
+      payment: "$input.payment"
+      amount: "$totals.total"
+    output: payment_result
+    on_error: payment_failed
+    next: reserve_inventory
+
+  - id: payment_failed
+    type: assign
+    set:
+      status: payment_failed
+      error: "Payment processing failed"
+      payment_result: null
+      shipment: null
+    next: end
+
+  - id: reserve_inventory
+    type: call
+    service: InventoryService
+    method: reserve
+    input:
+      items: "$input.items"
+      order_id: "$input.order_id"
+    output: reservation
+    next: create_shipment
+
+  - id: create_shipment
+    type: call
+    service: ShippingService
+    method: create_shipment
+    input:
+      order_id: "$input.order_id"
+      customer: "$input.customer"
+      items: "$input.items"
+    output: shipment
+    next: completed
+
+  - id: completed
+    type: assign
+    set:
+      status: completed
+      error: null
+    next: end
+
+  - id: failed
+    type: assign
+    set:
+      status: failed
+      error: "Order validation failed"
+      totals: null
+      payment_result: null
+      shipment: null
+    next: end
+
+  - id: end
+    type: end
+    result:
+      order_id: "$input.order_id"
+      status: "$status"
+      totals: "$totals"
+      payment_id: "$payment_result.payment_id"
+      tracking_number: "$shipment.tracking_number"
+      error: "$error"

data/examples/parallel_fetch.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Parallel Fetch - Execute multiple operations concurrently
+#
+# Demonstrates: Parallel step, concurrent execution
+#
+# Run: ruby examples/parallel_fetch.rb
+# Requires: Redis running on localhost:6379, async gem
+
+require "bundler/setup"
+require "durable_workflow"
+require "durable_workflow/storage/redis"
+
+DurableWorkflow.configure do |c|
+  c.store = DurableWorkflow::Storage::Redis.new(url: "redis://localhost:6379")
+end
+
+# Mock services (must be globally accessible constants)
+module UserService
+  def self.get_profile(user_id:)
+    sleep(0.1) # Simulate latency
+    { id: user_id, name: "User #{user_id}", email: "user#{user_id}@example.com" }
+  end
+end
+
+module OrderService
+  def self.get_recent(user_id:, limit:)
+    sleep(0.1)
+    limit.times.map { |i| { id: "ORD-#{i}", amount: rand(10..100) } }
+  end
+end
+
+module NotificationService
+  def self.get_unread(user_id:)
+    sleep(0.1)
+    rand(0..5).times.map { |i| { id: "NOTIF-#{i}", message: "Notification #{i}" } }
+  end
+end
+
+workflow = DurableWorkflow::Core::Parser.parse(<<~YAML)
+  id: dashboard_data
+  name: Dashboard Data Fetch
+  version: "1.0"
+
+  inputs:
+    user_id:
+      type: string
+      required: true
+
+  steps:
+    - id: start
+      type: start
+      next: fetch_all
+
+    - id: fetch_all
+      type: parallel
+      branches:
+        - id: get_profile
+          type: call
+          service: UserService
+          method: get_profile
+          input:
+            user_id: "$input.user_id"
+          output: profile
+
+        - id: get_orders
+          type: call
+          service: OrderService
+          method: get_recent
+          input:
+            user_id: "$input.user_id"
+            limit: 5
+          output: orders
+
+        - id: get_notifications
+          type: call
+          service: NotificationService
+          method: get_unread
+          input:
+            user_id: "$input.user_id"
+          output: notifications
+      next: end
+
+    - id: end
+      type: end
+      result:
+        user: "$profile"
+        recent_orders: "$orders"
+        notifications: "$notifications"
+YAML
+
+runner = DurableWorkflow::Runners::Sync.new(workflow)
+
+start_time = Time.now
+result = runner.run(input: { user_id: "USER-123" })
+elapsed = Time.now - start_time
+
+puts "Fetched dashboard data in #{elapsed.round(2)}s (parallel, not sequential 0.3s)"
+puts "User: #{result.output[:user][:name]}"
+puts "Orders: #{result.output[:recent_orders].size}"
+puts "Notifications: #{result.output[:notifications].size}"