solidflow 0.1.0

data/lib/solid_flow/testing.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  module Testing
+    module_function
+
+    # Runs an execution synchronously until it reaches a terminal state or the
+    # provided iteration limit. Useful for unit-style workflow specs.
+    def drain_execution(execution_id, max_iterations: 100)
+      runner = SolidFlow::Runner.new
+      max_iterations.times do
+        runner.run(execution_id)
+
+        status = SolidFlow.store.with_execution(execution_id, lock: false) do |execution|
+          execution[:state]
+        end
+
+        break unless status == "running"
+      end
+    end
+
+    def start_and_drain(workflow_class, **input)
+      execution = workflow_class.start(**input)
+      drain_execution(execution.id)
+      execution
+    end
+  end
+end

data/lib/solid_flow/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  VERSION = "0.1.0"
+end

data/lib/solid_flow/wait.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  module Wait
+    class Instruction
+      attr_reader :type, :options
+
+      def initialize(type, options)
+        @type = type
+        @options = options
+      end
+
+      def to_h
+        { type:, options: options }
+      end
+    end
+
+    class TimerInstruction < Instruction
+      def initialize(options)
+        super(:timer, options)
+      end
+    end
+
+    class SignalInstruction < Instruction
+      def initialize(options)
+        super(:signal, options)
+      end
+    end
+
+    class Context
+      attr_reader :instructions
+
+      def initialize
+        @instructions = []
+      end
+
+      def for(seconds: nil, timestamp: nil, at: nil, metadata: {})
+        metadata_payload =
+          case metadata
+          when Hash
+            metadata.deep_dup
+          else
+            metadata
+          end
+        options = { metadata: metadata_payload }
+        if seconds
+          raise ArgumentError, "seconds must be positive" unless seconds.to_f.positive?
+
+          options[:delay_seconds] = seconds.to_f
+        elsif at || timestamp
+          target = at || timestamp
+          options[:run_at] = target
+        else
+          raise ArgumentError, "wait.for requires :seconds or :timestamp"
+        end
+
+        instruction = TimerInstruction.new(options)
+        @instructions << instruction
+        instruction
+      end
+
+      def for_signal(name, metadata: {})
+        metadata_payload =
+          case metadata
+          when Hash
+            metadata.deep_dup
+          else
+            metadata
+          end
+        instruction = SignalInstruction.new(signal: name.to_sym, metadata: metadata_payload)
+        @instructions << instruction
+        instruction
+      end
+    end
+  end
+end

data/lib/solid_flow/workflow.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/subclasses"
+require "active_support/core_ext/object/blank"
+require "set"
+
+module SolidFlow
+  # Base class that developers subclass to implement durable workflows.
+  # Provides a DSL for defining steps, signals, queries, and compensations.
+  class Workflow
+    StepDefinition = Struct.new(
+      :name,
+      :task,
+      :block,
+      :retry_policy,
+      :timeouts,
+      :idempotency_key,
+      :options,
+      keyword_init: true
+    ) do
+      def task?
+        task.present?
+      end
+
+      def block?
+        !block.nil?
+      end
+
+      def dup
+        self.class.new(
+          name:,
+          task:,
+          block:,
+          retry_policy: retry_policy.deep_dup,
+          timeouts: timeouts.deep_dup,
+          idempotency_key:,
+          options: options.deep_dup
+        )
+      end
+    end
+
+    class << self
+      def inherited(subclass)
+        super
+
+        SolidFlow.configuration.workflow_registry.register(subclass.workflow_name, subclass)
+        subclass.instance_variable_set(:@workflow_steps, workflow_steps.map(&:dup))
+        subclass.instance_variable_set(:@workflow_signals, workflow_signals.deep_dup)
+        subclass.instance_variable_set(:@workflow_queries, workflow_queries.deep_dup)
+        subclass.instance_variable_set(:@signal_handlers, signal_handlers.deep_dup)
+        subclass.instance_variable_set(:@query_handlers, query_handlers.deep_dup)
+        subclass.instance_variable_set(:@workflow_defaults, workflow_defaults.deep_dup)
+        subclass.instance_variable_set(:@workflow_compensations, workflow_compensations.deep_dup)
+      end
+
+      def workflow_name(value = nil)
+        if value
+          normalized = value.to_s
+          @workflow_name = normalized
+          SolidFlow.configuration.workflow_registry.register(normalized, self)
+          @workflow_name
+        else
+          @workflow_name ||= name || "anonymous_workflow"
+        end
+      end
+
+      def workflow_steps
+        @workflow_steps ||= []
+      end
+
+      def workflow_signals
+        @workflow_signals ||= {}
+      end
+
+      def workflow_queries
+        @workflow_queries ||= {}
+      end
+
+      def signal_handlers
+        @signal_handlers ||= {}
+      end
+
+      def query_handlers
+        @query_handlers ||= {}
+      end
+
+      def workflow_defaults
+        @workflow_defaults ||= {
+          retry: {},
+          timeouts: {}
+        }
+      end
+
+      def workflow_compensations
+        @workflow_compensations ||= {}
+      end
+
+      def defaults(options = {})
+        workflow_defaults.deep_merge!(options.deep_symbolize_keys)
+      end
+
+      def step(name, task: nil, **options, &block)
+        raise ArgumentError, "step #{name} already defined" if workflow_steps.any? { |s| s.name == name.to_sym }
+
+        retry_policy  = workflow_defaults[:retry].merge(options.delete(:retry) || {})
+        timeouts      = workflow_defaults[:timeouts].merge(options.delete(:timeouts) || {})
+        idempotency   = options.delete(:idempotency_key)
+
+        workflow_steps << StepDefinition.new(
+          name: name.to_sym,
+          task: task&.to_sym,
+          block: block,
+          retry_policy: retry_policy,
+          timeouts: timeouts,
+          idempotency_key: idempotency,
+          options: options
+        )
+      end
+
+      def signal(name, buffer: true)
+        workflow_signals[name.to_sym] = { buffer: }
+      end
+
+      def on_signal(name, method_name = nil, &block)
+        handler =
+          if method_name
+            lambda { |payload| send(method_name, payload) }
+          else
+            block
+          end
+
+        raise ArgumentError, "on_signal requires a block or method name" unless handler
+
+        signal_handlers[name.to_sym] = handler
+      end
+
+      def query(name)
+        workflow_queries[name.to_sym] = {}
+      end
+
+      def on_query(name, method_name = nil, &block)
+        handler =
+          if method_name
+            lambda { send(method_name) }
+          else
+            block
+          end
+
+        raise ArgumentError, "on_query requires a block or method name" unless handler
+
+        query_handlers[name.to_sym] = handler
+      end
+
+      def compensate(step_name, with:)
+        workflow_compensations[step_name.to_sym] = with.to_sym
+      end
+
+      def steps
+        workflow_steps.dup
+      end
+
+      def signals
+        workflow_signals.dup
+      end
+
+      def queries
+        workflow_queries.dup
+      end
+
+      def compensations
+        workflow_compensations.dup
+      end
+
+      def graph_signature
+        Determinism.graph_signature(self)
+      end
+
+      def start(**input)
+        SolidFlow.instrument("solidflow.execution.start", workflow: workflow_name, input:)
+        signature = graph_signature
+        SolidFlow.store.start_execution(
+          workflow_class: self,
+          input: input,
+          graph_signature: signature
+        )
+      end
+
+      def signal(execution_id, signal_name, payload = {})
+        raise Errors::UnknownSignal, signal_name unless signal_handlers.key?(signal_name.to_sym) || workflow_signals.key?(signal_name.to_sym)
+
+        normalized_payload = payload.is_a?(Hash) ? payload.deep_symbolize_keys : payload
+
+        SolidFlow.store.signal_execution(
+          execution_id:,
+          workflow_class: self,
+          signal_name: signal_name.to_sym,
+          payload: normalized_payload
+        )
+      end
+
+      def query(execution_id, query_name)
+        handler = query_handlers.fetch(query_name.to_sym) do
+          raise Errors::UnknownQuery, query_name
+        end
+
+        SolidFlow.store.query_execution(
+          execution_id:,
+          workflow_class: self
+        ) do |state|
+          workflow = new(ctx: state.ctx, execution: state.execution_state, history: state.history)
+          workflow.instance_exec(&handler)
+        end
+      end
+    end
+
+    attr_reader :ctx, :execution, :history
+
+    def initialize(ctx:, execution:, history: [])
+      @ctx         = ctx.with_indifferent_access
+      @execution   = execution
+      @history     = history
+      @wait_context = nil
+    end
+
+    def wait
+      @wait_context ||= Wait::Context.new
+    end
+
+    def reset_wait_context!
+      @wait_context = Wait::Context.new
+    end
+
+    def consume_wait_instructions
+      instructions = @wait_context&.instructions || []
+      @wait_context = nil
+      instructions
+    end
+
+    def apply_signal(name, payload)
+      handler = self.class.signal_handlers[name.to_sym]
+      raise Errors::UnknownSignal, name unless handler
+
+      instance_exec(payload.with_indifferent_access, &handler)
+    end
+
+    def signal_defined?(name)
+      self.class.signal_handlers.key?(name.to_sym) || self.class.workflow_signals.key?(name.to_sym)
+    end
+
+    def query_defined?(name)
+      self.class.query_handlers.key?(name.to_sym)
+    end
+
+    def cancel!(reason = "cancelled")
+      @cancelled = true
+      raise Errors::Cancelled, reason
+    end
+
+    def cancelled?
+      !!@cancelled
+    end
+  end
+end

data/lib/solid_flow.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "logger"
+require "active_support"
+require "active_support/core_ext/module"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/object/deep_dup"
+require "active_support/notifications"
+require "active_support/time"
+require "zeitwerk"
+require "securerandom"
+require "thread"
+require "digest"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/../app")
+loader.setup
+
+require "solid_flow/engine" if defined?(Rails::Engine)
+
+module SolidFlow
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def logger
+      configuration.logger
+    end
+
+    def store
+      configuration.store
+    end
+
+    def task_registry
+      configuration.task_registry
+    end
+
+    def instrument(event, payload = {})
+      ActiveSupport::Notifications.instrument(event, payload)
+    end
+  end
+
+  # Minimal dependency injection container for runtime components.
+  class Configuration
+    attr_accessor :logger,
+                  :event_serializer,
+                  :store,
+                  :task_registry,
+                  :workflow_registry,
+                  :default_execution_queue,
+                  :default_task_queue,
+                  :default_timer_queue,
+                  :time_provider,
+                  :id_generator
+
+    def initialize
+      @logger                 = Logger.new($stdout, level: Logger::INFO)
+      @event_serializer       = Serializers::Oj.new
+      @workflow_registry      = Registries::WorkflowRegistry.new
+      @task_registry          = Registries::TaskRegistry.new
+      @default_execution_queue = "solidflow"
+      @default_task_queue      = "solidflow_tasks"
+      @default_timer_queue     = "solidflow_timers"
+      @time_provider          = -> { Time.current }
+      @id_generator           = -> { SecureRandom.uuid }
+      @store                  = Stores::ActiveRecord.new(event_serializer: @event_serializer,
+                                                        time_provider: @time_provider,
+                                                        logger: @logger)
+    end
+  end
+end

data/lib/solidflow.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "solid_flow"

metadata

@@ -0,0 +1,213 @@
+--- !ruby/object:Gem::Specification
+name: solidflow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Laerti Papa
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+description: |
+  SolidFlow provides deterministic workflow orchestration for Ruby on Rails using ActiveJob
+  and ActiveRecord. It features event-sourced history, replay, timers, signals, tasks, and SAGA
+  compensations designed for production-grade systems.
+email:
+- laertis.pappas@gmail.com
+executables:
+- solidflow
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- app/jobs/solidflow/jobs/run_execution_job.rb
+- app/jobs/solidflow/jobs/run_task_job.rb
+- app/jobs/solidflow/jobs/timer_sweep_job.rb
+- app/models/solidflow/application_record.rb
+- app/models/solidflow/event.rb
+- app/models/solidflow/execution.rb
+- app/models/solidflow/signal_message.rb
+- app/models/solidflow/timer.rb
+- bin/solidflow
+- db/migrate/001_create_solidflow_core_tables.rb
+- lib/solid_flow.rb
+- lib/solid_flow/cli.rb
+- lib/solid_flow/determinism.rb
+- lib/solid_flow/engine.rb
+- lib/solid_flow/errors.rb
+- lib/solid_flow/idempotency.rb
+- lib/solid_flow/instrumentation.rb
+- lib/solid_flow/registries/task_registry.rb
+- lib/solid_flow/registries/workflow_registry.rb
+- lib/solid_flow/replay.rb
+- lib/solid_flow/runner.rb
+- lib/solid_flow/serializers/oj.rb
+- lib/solid_flow/signals.rb
+- lib/solid_flow/stores/active_record.rb
+- lib/solid_flow/stores/base.rb
+- lib/solid_flow/task.rb
+- lib/solid_flow/testing.rb
+- lib/solid_flow/version.rb
+- lib/solid_flow/wait.rb
+- lib/solid_flow/workflow.rb
+- lib/solidflow.rb
+homepage: https://github.com/laertispappas/solidflow
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/laertispappas/solidflow
+  source_code_uri: https://github.com/laertispappas/solidflow
+  changelog_uri: https://github.com/laertispappas/solidflow/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Durable workflows for Ruby & Rails
+test_files: []