solidflow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4880f6ff9e531227b618a8fe2ff91bbb09688d60d6c9544b4a90e36b5922e00e
+  data.tar.gz: f63bf94ff8865affdb2ba9f7ca1909eb84c83ca46d1fe0d3d7c6c30ca03eecc8
+SHA512:
+  metadata.gz: d1a230750a5489a0c2818e419545ead56b863d0a5a591ee7e2c3bc90751e641b9a82ad86aef6ed05ebdb6a6883b6ea771dcc044af2ecd8bb515318f7ce27f667
+  data.tar.gz: 61804d906296b93dfe1be46b663bd2ae4e09dc90f4df0c429d3c999afe2854105e7e3d6540dddf146bfc30fa22e2c0d75a81c78acd3a103ff9f9fcb6263037cd

data/README.md

@@ -0,0 +1,70 @@
+# SolidFlow
+
+**SolidFlow** — Durable workflows for Ruby and Rails. Deterministic workflows, event‑sourced history, timers, signals, tasks, and SAGA compensations. Backed by ActiveJob and ActiveRecord. Production‑ready, scalable, and extensible.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "solidflow", path: "solidflow"
+```
+
+Then run `bundle install` and install the migrations:
+
+```bash
+bin/rails solidflow:install:migrations
+bin/rails db:migrate
+```
+
+## Quick Start
+
+Define a workflow and a task:
+
+```ruby
+class ReserveInventoryTask < SolidFlow::Task
+  def perform(order_id:)
+    Inventory.reserve(order_id: order_id)
+  end
+end
+
+class OrderFulfillmentWorkflow < SolidFlow::Workflow
+  signal :payment_captured
+
+  step :reserve_inventory, task: :reserve_inventory_task
+
+  step :await_payment do
+    wait.for(seconds: 30)
+    wait.for_signal(:payment_captured) unless ctx[:payment_received]
+  end
+
+  on_signal :payment_captured do |payload|
+    ctx[:payment_received] = true
+    ctx[:txn_id] = payload.fetch("txn_id")
+  end
+end
+```
+
+Kick off an execution:
+
+```ruby
+execution = OrderFulfillmentWorkflow.start(order_id: "ORD-1")
+OrderFulfillmentWorkflow.signal(execution.id, :payment_captured, txn_id: "txn-123")
+```
+
+## CLI
+
+```bash
+bin/solidflow start OrderFulfillmentWorkflow --args '{"order_id":"ORD-1"}'
+bin/solidflow signal <execution_id> payment_captured --payload '{"txn_id":"txn-123"}'
+bin/solidflow query <execution_id> status
+```
+
+## Testing
+
+```ruby
+execution = SolidFlow::Testing.start_and_drain(OrderFulfillmentWorkflow, order_id: "ORD-1")
+expect(execution.state).to eq("completed")
+```
+
+See `solid_flow_instructions.md` for the full architecture and feature specification.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require_relative "lib/solidflow"
+
+desc "Run test suite"
+task :spec do
+  exec("bundle exec rspec")
+end
+
+task default: :spec

data/app/jobs/solidflow/jobs/run_execution_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  module Jobs
+    class RunExecutionJob < ActiveJob::Base
+      queue_as do
+        SolidFlow.configuration.default_execution_queue
+      end
+
+      retry_exceptions = [ActiveRecord::Deadlocked]
+      retry_exceptions << ActiveRecord::LockWaitTimeout if defined?(ActiveRecord::LockWaitTimeout)
+      retry_on(*retry_exceptions, attempts: 5, wait: :exponentially_longer)
+
+      def perform(execution_id)
+        SolidFlow::Runner.new.run(execution_id)
+      rescue Errors::ExecutionNotFound => e
+        SolidFlow.logger.warn("SolidFlow execution not found: #{execution_id} (#{e.class}: #{e.message})")
+      end
+    end
+  end
+end

data/app/jobs/solidflow/jobs/run_task_job.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  module Jobs
+    class RunTaskJob < ActiveJob::Base
+      queue_as do
+        SolidFlow.configuration.default_task_queue
+      end
+
+      def perform(execution_id, step_name, task_name, arguments, headers)
+        headers = headers.deep_symbolize_keys
+        arguments = arguments.deep_symbolize_keys if arguments.respond_to?(:deep_symbolize_keys)
+
+        task_class = SolidFlow.task_registry.fetch(task_name)
+        workflow_class = SolidFlow.configuration.workflow_registry.fetch(headers.fetch(:workflow_name))
+        attempt = headers[:attempt] || 1
+        idempotency_key = headers[:idempotency_key]
+        compensation = headers[:compensation]
+
+        result = task_class.execute(arguments: arguments || {}, headers:)
+
+        SolidFlow.store.with_execution(execution_id) do |_|
+          if compensation
+            SolidFlow.store.record_compensation_result(
+              execution_id:,
+              step: step_name.to_sym,
+              compensation_task: headers[:compensation_task],
+              result:
+            )
+          else
+            SolidFlow.store.record_task_result(
+              execution_id:,
+              workflow_class:,
+              step: step_name.to_sym,
+              result:,
+              attempt:,
+              idempotency_key: idempotency_key
+            )
+          end
+        end
+
+        SolidFlow.instrument(
+          "solidflow.task.completed",
+          execution_id:,
+          workflow: workflow_class.workflow_name,
+          step: step_name,
+          task: task_name,
+          attempt:,
+          result:,
+          compensation: compensation
+        )
+      rescue Errors::TaskFailure => failure
+        retryable = retryable?(workflow_class, step_name, attempt, headers)
+
+        SolidFlow.store.with_execution(execution_id) do |_|
+          if headers[:compensation]
+            SolidFlow.store.record_compensation_failure(
+              execution_id:,
+              step: step_name.to_sym,
+              compensation_task: headers[:compensation_task],
+              error: {
+                message: failure.message,
+                class: failure.details&.fetch(:class, failure.class.name),
+                backtrace: Array(failure.details&.fetch(:backtrace, failure.backtrace))
+              }
+            )
+          else
+            SolidFlow.store.record_task_failure(
+              execution_id:,
+              workflow_class:,
+              step: step_name.to_sym,
+              attempt:,
+              error: {
+                message: failure.message,
+                class: failure.details&.fetch(:class, failure.class.name),
+                backtrace: Array(failure.details&.fetch(:backtrace, failure.backtrace))
+              },
+              retryable:
+            )
+          end
+        end
+
+        SolidFlow.instrument(
+          "solidflow.task.failed",
+          execution_id:,
+          workflow: workflow_class.workflow_name,
+          step: step_name,
+          task: task_name,
+          attempt:,
+          error: failure,
+          compensation: headers[:compensation]
+        )
+      end
+
+      private
+
+      def retryable?(workflow_class, step_name, attempt, headers)
+        return false if headers[:compensation]
+
+        step_definition = workflow_class.steps.find { |step| step.name.to_sym == step_name.to_sym }
+        policy = step_definition&.retry_policy || {}
+        max_attempts = policy[:max_attempts] || 1
+        attempt < max_attempts
+      end
+    end
+  end
+end

data/app/jobs/solidflow/jobs/timer_sweep_job.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  module Jobs
+    class TimerSweepJob < ActiveJob::Base
+      queue_as do
+        SolidFlow.configuration.default_timer_queue
+      end
+
+      def perform(batch_size: 100)
+        now = SolidFlow.configuration.time_provider.call
+
+        SolidFlow::Timer.transaction do
+          SolidFlow::Timer
+            .scheduled
+            .where("run_at <= ?", now)
+            .limit(batch_size)
+            .lock("FOR UPDATE SKIP LOCKED")
+            .each do |timer|
+              SolidFlow.store.mark_timer_fired(timer_id: timer.id)
+              SolidFlow.instrument(
+                "solidflow.timer.fired",
+                execution_id: timer.execution_id,
+                timer_id: timer.id,
+                step: timer.step
+              )
+            end
+        end
+      end
+    end
+  end
+end

data/app/models/solidflow/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  class ApplicationRecord < ActiveRecord::Base
+    primary_abstract_class
+  end
+end

data/app/models/solidflow/event.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  class Event < ApplicationRecord
+    self.table_name = "solidflow_events"
+
+    belongs_to :execution,
+               class_name: "SolidFlow::Execution",
+               inverse_of: :events
+
+    scope :ordered, -> { order(:sequence) }
+
+    def to_replay_event
+      Replay::Event.new(
+        id: id,
+        type: event_type,
+        sequence: sequence,
+        payload: payload,
+        recorded_at: recorded_at
+      )
+    end
+  end
+end

data/app/models/solidflow/execution.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  class Execution < ApplicationRecord
+    self.table_name = "solidflow_executions"
+
+    has_many :events,
+             class_name: "SolidFlow::Event",
+             foreign_key: :execution_id,
+             inverse_of: :execution,
+             dependent: :destroy
+
+    has_many :timers,
+             class_name: "SolidFlow::Timer",
+             foreign_key: :execution_id,
+             inverse_of: :execution,
+             dependent: :destroy
+
+    has_many :signal_messages,
+             class_name: "SolidFlow::SignalMessage",
+             foreign_key: :execution_id,
+             inverse_of: :execution,
+             dependent: :destroy
+
+    enum state: {
+      running: "running",
+      completed: "completed",
+      failed: "failed",
+      cancelled: "cancelled"
+    }
+
+    def ctx_hash
+      (self[:ctx] || {}).with_indifferent_access
+    end
+  end
+end

data/app/models/solidflow/signal_message.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  class SignalMessage < ApplicationRecord
+    self.table_name = "solidflow_signal_messages"
+
+    belongs_to :execution,
+               class_name: "SolidFlow::Execution",
+               inverse_of: :signal_messages
+
+    enum status: {
+      pending: "pending",
+      consumed: "consumed"
+    }
+  end
+end

data/app/models/solidflow/timer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  class Timer < ApplicationRecord
+    self.table_name = "solidflow_timers"
+
+    belongs_to :execution,
+               class_name: "SolidFlow::Execution",
+               inverse_of: :timers
+
+    enum status: {
+      scheduled: "scheduled",
+      fired: "fired",
+      cancelled: "cancelled"
+    }
+
+    scope :due, ->(now = Time.current) { scheduled.where("run_at <= ?", now) }
+  end
+end

data/bin/solidflow

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "solid_flow/cli"
+
+SolidFlow::CLI.start(ARGV)

data/db/migrate/001_create_solidflow_core_tables.rb

@@ -0,0 +1,71 @@
+class CreateSolidflowCoreTables < ActiveRecord::Migration[7.1]
+  def change
+    enable_extension "pgcrypto" unless extension_enabled?("pgcrypto")
+
+    create_table :solidflow_executions, id: :uuid do |t|
+      t.string  :workflow, null: false
+      t.string  :state, null: false, default: "running"
+      t.jsonb   :ctx, null: false, default: {}
+      t.string  :cursor_step
+      t.integer :cursor_index, null: false, default: 0
+      t.string  :graph_signature
+      t.jsonb   :metadata, null: false, default: {}
+      t.jsonb   :last_error
+      t.string  :shard_key
+      t.string  :account_id
+      t.datetime :started_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.timestamps
+    end
+
+    add_index :solidflow_executions, :workflow
+    add_index :solidflow_executions, %i[state workflow]
+    add_index :solidflow_executions, :shard_key
+    add_index :solidflow_executions, :account_id
+
+    create_table :solidflow_events, id: :uuid do |t|
+      t.uuid     :execution_id, null: false
+      t.integer  :sequence, null: false
+      t.string   :event_type, null: false
+      t.jsonb    :payload, null: false, default: {}
+      t.string   :idempotency_key
+      t.datetime :recorded_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.timestamps
+    end
+
+    add_index :solidflow_events, %i[execution_id sequence], unique: true
+    add_index :solidflow_events, :event_type
+    add_index :solidflow_events, %i[execution_id idempotency_key], unique: true, where: "idempotency_key IS NOT NULL"
+    add_foreign_key :solidflow_events, :solidflow_executions, column: :execution_id
+
+    create_table :solidflow_timers, id: :uuid do |t|
+      t.uuid     :execution_id, null: false
+      t.string   :step, null: false
+      t.datetime :run_at, null: false
+      t.string   :status, null: false, default: "scheduled"
+      t.jsonb    :instruction, null: false, default: {}
+      t.jsonb    :metadata, null: false, default: {}
+      t.datetime :fired_at
+      t.timestamps
+    end
+
+    add_index :solidflow_timers, :execution_id
+    add_index :solidflow_timers, %i[status run_at]
+    add_foreign_key :solidflow_timers, :solidflow_executions, column: :execution_id
+
+    create_table :solidflow_signal_messages, id: :uuid do |t|
+      t.uuid     :execution_id, null: false
+      t.string   :signal_name, null: false
+      t.jsonb    :payload, null: false, default: {}
+      t.jsonb    :metadata, null: false, default: {}
+      t.string   :status, null: false, default: "pending"
+      t.datetime :received_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.datetime :consumed_at
+      t.timestamps
+    end
+
+    add_index :solidflow_signal_messages, :execution_id
+    add_index :solidflow_signal_messages, %i[execution_id status]
+    add_index :solidflow_signal_messages, %i[execution_id signal_name status], name: "index_solidflow_signals_lookup"
+    add_foreign_key :solidflow_signal_messages, :solidflow_executions, column: :execution_id
+  end
+end

data/lib/solid_flow/cli.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "thor"
+require "json"
+
+module SolidFlow
+  class CLI < Thor
+    desc "start WORKFLOW", "Start a workflow execution"
+    option :args, type: :string, default: "{}", desc: "JSON payload with workflow input arguments"
+    def start(workflow_name)
+      workflow_class = SolidFlow.configuration.workflow_registry.fetch(workflow_name)
+      arguments = parse_json(options[:args])
+
+      execution = workflow_class.start(**symbolize_keys(arguments))
+      say("Started execution #{execution.id}", :green)
+    rescue Errors::ConfigurationError, JSON::ParserError => e
+      say("Failed to start workflow: #{e.message}", :red)
+      exit(1)
+    end
+
+    desc "signal EXECUTION_ID SIGNAL", "Send a signal to a workflow execution"
+    option :workflow, type: :string, desc: "Workflow name (optional; inferred if omitted)"
+    option :payload, type: :string, default: "{}", desc: "JSON payload for the signal"
+    def signal(execution_id, signal_name)
+      workflow_class = resolve_workflow(options[:workflow], execution_id)
+      payload = parse_json(options[:payload])
+
+      workflow_class.signal(execution_id, signal_name.to_sym, payload)
+      say("Signal #{signal_name} enqueued for execution #{execution_id}", :green)
+    rescue Errors::ConfigurationError, JSON::ParserError => e
+      say("Failed to send signal: #{e.message}", :red)
+      exit(1)
+    end
+
+    desc "query EXECUTION_ID QUERY", "Execute a read-only query against a workflow"
+    option :workflow, type: :string, desc: "Workflow name (optional; inferred if omitted)"
+    def query(execution_id, query_name)
+      workflow_class = resolve_workflow(options[:workflow], execution_id)
+      result = workflow_class.query(execution_id, query_name.to_sym)
+      say(JSON.pretty_generate(result))
+    rescue Errors::ConfigurationError => e
+      say("Failed to run query: #{e.message}", :red)
+      exit(1)
+    end
+
+    no_commands do
+      def parse_json(string)
+        return {} if string.nil? || string.strip.empty?
+
+        JSON.parse(string)
+      end
+
+      def symbolize_keys(hash)
+        return hash unless hash.respond_to?(:transform_keys)
+
+        hash.transform_keys(&:to_sym)
+      end
+
+      def resolve_workflow(name, execution_id)
+        return SolidFlow.configuration.workflow_registry.fetch(name) if name
+
+        SolidFlow.store.with_execution(execution_id, lock: false) do |execution|
+          return SolidFlow.configuration.workflow_registry.fetch(execution[:workflow])
+        end
+      end
+    end
+  end
+end

data/lib/solid_flow/determinism.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SolidFlow
+  module Determinism
+    module_function
+
+    def graph_signature(workflow_class)
+      payload = {
+        workflow: workflow_class.name,
+        steps: workflow_class.steps.map do |step|
+          {
+            name: step.name,
+            task: step.task,
+            block: step.block? ? "block" : nil,
+            retry: step.retry_policy,
+            timeouts: step.timeouts,
+            options: step.options
+          }
+        end,
+        signals: workflow_class.signals.keys.map(&:to_s).sort,
+        queries: workflow_class.queries.keys.map(&:to_s).sort,
+        compensations: workflow_class.compensations.transform_keys(&:to_s).transform_values(&:to_s).sort.to_h
+      }
+
+      Digest::SHA256.hexdigest(JSON.generate(payload))
+    end
+
+    def assert_graph!(workflow_class, persisted_signature)
+      signature = graph_signature(workflow_class)
+      return signature unless persisted_signature
+
+      return signature if signature == persisted_signature
+
+      raise Errors::NonDeterministicWorkflowError.new(expected: persisted_signature, actual: signature)
+    end
+  end
+end

data/lib/solid_flow/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module SolidFlow
+  class Engine < ::Rails::Engine
+    isolate_namespace SolidFlow
+    engine_name "solidflow"
+
+    initializer "solidflow.active_job" do
+      ActiveSupport.on_load(:active_job) do
+        queue_adapter # touch to ensure ActiveJob loaded
+      end
+    end
+
+    initializer "solidflow.append_migrations" do |app|
+      unless app.root.to_s.match?(root.to_s)
+        config_file = root.join("db/migrate")
+        app.config.paths["db/migrate"].concat([config_file.to_s])
+      end
+    end
+  end
+end

data/lib/solid_flow/errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  module Errors
+    # Base error for all SolidFlow failures.
+    class SolidFlowError < StandardError; end
+
+    class ConfigurationError < SolidFlowError; end
+    class DeterminismError   < SolidFlowError; end
+    class ExecutionNotFound  < SolidFlowError; end
+    class Cancelled          < SolidFlowError; end
+    class TimeoutError       < SolidFlowError; end
+    class TaskFailure        < SolidFlowError
+      attr_reader :details
+
+      def initialize(message = nil, details: nil)
+        @details = details
+        super(message || "Task execution failed")
+      end
+    end
+
+    class NonDeterministicWorkflowError < DeterminismError
+      attr_reader :expected, :actual
+
+      def initialize(expected:, actual:)
+        @expected = expected
+        @actual   = actual
+        super("Workflow definition diverged from persisted graph signature (expected: #{expected}, actual: #{actual})")
+      end
+    end
+
+    class UnknownSignal < SolidFlowError
+      def initialize(signal)
+        super("Unknown signal `#{signal}`")
+      end
+    end
+
+    class UnknownQuery < SolidFlowError
+      def initialize(query)
+        super("Unknown query `#{query}`")
+      end
+    end
+
+    class InvalidStep < SolidFlowError
+      def initialize(step)
+        super("Step `#{step}` is not defined on this workflow")
+      end
+    end
+
+    class WaitInstructionError < SolidFlowError; end
+  end
+end

data/lib/solid_flow/idempotency.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module SolidFlow
+  module Idempotency
+    module_function
+
+    def evaluate(key, workflow:, step:)
+      case key
+      when Proc
+        workflow.instance_exec(&key).to_s
+      when Symbol
+        workflow.public_send(key).to_s
+      when String
+        key
+      when Array
+        key.compact.map(&:to_s).join(":")
+      when nil
+        default(workflow.execution.id, step.name)
+      else
+        key.to_s
+      end
+    end
+
+    def default(execution_id, step_name, attempt = 0)
+      Digest::SHA256.hexdigest([execution_id, step_name, attempt].join(":"))
+    end
+
+    def digest(*parts)
+      Digest::SHA256.hexdigest(parts.flatten.compact.map(&:to_s).join("|"))
+    end
+  end
+end

data/lib/solid_flow/instrumentation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  module Instrumentation
+    module_function
+
+    def subscribe(logger: SolidFlow.logger)
+      ActiveSupport::Notifications.subscribe(/solidflow\./) do |event_name, start, finish, _id, payload|
+        next unless logger
+
+        duration = (finish - start) * 1000.0
+        logger.info("[#{event_name}] (#{format('%.1fms', duration)}) #{payload.compact}")
+      end
+    end
+  end
+end