solidflow 0.1.0

data/lib/solid_flow/stores/active_record.rb

@@ -0,0 +1,461 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module SolidFlow
+  module Stores
+    class ActiveRecord < Base
+      THREAD_EXECUTION = :__solidflow_current_execution__
+
+      def start_execution(workflow_class:, input:, graph_signature:)
+        execution_id = SolidFlow.configuration.id_generator.call
+        now = time_provider.call
+        first_step = workflow_class.steps.first&.name
+        input_payload = input.respond_to?(:deep_stringify_keys) ? input.deep_stringify_keys : input
+
+        execution = SolidFlow::Execution.create!(
+          id: execution_id,
+          workflow: workflow_class.workflow_name,
+          state: "running",
+          ctx: input_payload,
+          cursor_step: first_step&.to_s,
+          cursor_index: 0,
+          graph_signature: graph_signature,
+          metadata: {},
+          started_at: now,
+          updated_at: now
+        )
+
+        append_event(
+          execution_id: execution.id,
+          type: :workflow_started,
+          payload: { input: input }
+        )
+
+        enqueue_execution(
+          execution_id: execution.id,
+          reason: :start
+        )
+
+        build_handle(execution)
+      end
+
+      def signal_execution(execution_id:, workflow_class:, signal_name:, payload:)
+        execution = SolidFlow::Execution.find(execution_id)
+
+        message = execution.signal_messages.create!(
+          signal_name: signal_name.to_s,
+          payload: payload,
+          metadata: {},
+          status: "pending",
+          received_at: time_provider.call
+        )
+
+        append_event(
+          execution_id: execution.id,
+          type: :signal_received,
+          payload: {
+            signal: signal_name,
+            payload: payload,
+            metadata: message.metadata,
+            received_at: message.received_at
+          }
+        )
+
+        enqueue_execution(
+          execution_id: execution.id,
+          reason: :signal
+        )
+
+        SolidFlow.instrument(
+          "solidflow.signal.received",
+          execution_id: execution.id,
+          workflow: workflow_class.workflow_name,
+          signal: signal_name,
+          payload:
+        )
+      end
+
+      def query_execution(execution_id:, workflow_class:)
+        execution = SolidFlow::Execution.find(execution_id)
+        events = load_history(execution_id)
+        state = Replay.new(
+          workflow_class:,
+          events:,
+          execution_record: serialize_execution(execution)
+        ).call
+
+        yield(state)
+      end
+
+      def with_execution(execution_id, lock: true)
+        SolidFlow::Execution.transaction do
+          relation = SolidFlow::Execution.where(id: execution_id)
+          relation = relation.lock("FOR UPDATE SKIP LOCKED") if lock
+          execution = relation.first
+          raise Errors::ExecutionNotFound, execution_id unless execution
+
+          previous = Thread.current[THREAD_EXECUTION]
+          Thread.current[THREAD_EXECUTION] = execution
+
+          yield serialize_execution(execution)
+        ensure
+          Thread.current[THREAD_EXECUTION] = previous
+        end
+      end
+
+      def load_history(execution_id)
+        SolidFlow::Event.where(execution_id:)
+                        .ordered
+                        .map(&:to_replay_event)
+      end
+
+      def append_event(execution_id:, type:, payload:, idempotency_key: nil)
+        execution = execution_for(execution_id)
+
+        next_sequence = (execution.events.maximum(:sequence) || 0) + 1
+
+        execution.events.create!(
+          sequence: next_sequence,
+          event_type: type.to_s,
+          payload: payload,
+          recorded_at: time_provider.call,
+          idempotency_key:
+        )
+      end
+
+      def update_execution(execution_id:, attributes:)
+        execution = execution_for(execution_id)
+        execution.update!(normalize_attributes(attributes))
+      end
+
+      def persist_context(execution_id:, ctx:)
+        execution = execution_for(execution_id)
+        execution.update!(ctx: ctx.deep_stringify_keys)
+      end
+
+      def enqueue_execution(execution_id:, reason:)
+        SolidFlow.instrument(
+          "solidflow.execution.enqueued",
+          execution_id:,
+          reason:
+        )
+        SolidFlow::Jobs::RunExecutionJob.perform_later(execution_id)
+      end
+
+      def schedule_task(execution_id:, step:, task:, arguments:, headers:, run_at: nil)
+        job = SolidFlow::Jobs::RunTaskJob
+        if run_at
+          job.set(wait_until: run_at).perform_later(execution_id, step, task, arguments, headers)
+        else
+          job.perform_later(execution_id, step, task, arguments, headers)
+        end
+      end
+
+      def record_task_result(execution_id:, workflow_class:, step:, result:, attempt:, idempotency_key:)
+        execution = execution_for(execution_id)
+
+        existing = execution.events.where(
+          event_type: "task_completed",
+          idempotency_key:
+        ).first
+
+        return if existing
+
+        ctx = execution.ctx_hash
+        ctx[step.to_s] = result
+
+        steps = workflow_class.steps
+        next_index = execution.cursor_index + 1
+        next_step = steps[next_index]&.name
+        new_state = next_step ? "running" : "completed"
+
+        execution.assign_attributes(
+          ctx: ctx.deep_stringify_keys,
+          cursor_index: next_index,
+          cursor_step: next_step&.to_s,
+          state: new_state,
+          last_error: nil
+        )
+        execution.save!
+
+        append_event(
+          execution_id:,
+          type: :task_completed,
+          payload: {
+            step: step,
+            result: result,
+            attempt: attempt,
+            ctx_snapshot: ctx,
+            idempotency_key:
+          },
+          idempotency_key: idempotency_key
+        )
+
+        if new_state == "completed"
+          append_event(
+            execution_id:,
+            type: :workflow_completed,
+            payload: {}
+          )
+          SolidFlow.instrument(
+            "solidflow.execution.completed",
+            execution_id:,
+            workflow: workflow_class.workflow_name
+          )
+        else
+          enqueue_execution(
+            execution_id:,
+            reason: :task_completed
+          )
+        end
+      end
+
+      def record_task_failure(execution_id:, workflow_class:, step:, attempt:, error:, retryable:)
+        execution = execution_for(execution_id)
+
+        execution.update!(
+          last_error: error,
+          state: retryable ? "running" : "failed"
+        )
+
+        append_event(
+          execution_id:,
+          type: :task_failed,
+          payload: {
+            step: step,
+            attempt: attempt,
+            error: error,
+            retryable: retryable
+          }
+        )
+
+        if retryable
+          enqueue_execution(
+            execution_id:,
+            reason: :task_failed
+          )
+        else
+          append_event(
+            execution_id:,
+            type: :workflow_failed,
+            payload: {
+              step: step,
+              error: error
+            }
+          )
+
+          SolidFlow.instrument(
+            "solidflow.execution.failed",
+            execution_id:,
+            step: step,
+            error: error
+          )
+        end
+      end
+
+      def schedule_timer(execution_id:, step:, run_at:, instruction:, metadata:)
+        execution = execution_for(execution_id)
+
+        timer = execution.timers.create!(
+          step: step.to_s,
+          run_at: run_at,
+          status: "scheduled",
+          instruction: instruction,
+          metadata: metadata
+        )
+
+        append_event(
+          execution_id:,
+          type: :timer_scheduled,
+          payload: {
+            step: step,
+            timer_id: timer.id,
+            run_at: run_at,
+            metadata: metadata
+          }
+        )
+
+        SolidFlow.instrument(
+          "solidflow.timer.scheduled",
+          execution_id: execution.id,
+          timer_id: timer.id,
+          step: step,
+          run_at: run_at
+        )
+      end
+
+      def mark_timer_fired(timer_id:)
+        timer = SolidFlow::Timer.lock.find(timer_id)
+        return if timer.fired?
+
+        timer.update!(status: "fired", fired_at: time_provider.call)
+
+        append_event(
+          execution_id: timer.execution_id,
+          type: :timer_fired,
+          payload: {
+            timer_id: timer.id,
+            step: timer.step
+          }
+        )
+
+        enqueue_execution(
+          execution_id: timer.execution_id,
+          reason: :timer_fired
+        )
+      end
+
+      def persist_signal_consumed(execution_id:, signal_name:)
+        message = SolidFlow::SignalMessage
+                  .where(execution_id:, signal_name: signal_name.to_s, status: "pending")
+                  .order(:received_at)
+                  .first
+
+        return unless message
+
+        message.update!(
+          status: "consumed",
+          consumed_at: time_provider.call
+        )
+
+        append_event(
+          execution_id:,
+          type: :signal_consumed,
+          payload: {
+            signal: signal_name
+          }
+        )
+
+        SolidFlow.instrument(
+          "solidflow.signal.consumed",
+          execution_id:,
+          signal: signal_name
+        )
+      end
+
+      def schedule_compensation(execution_id:, workflow_class:, step:, compensation_task:, context:)
+        execution = execution_for(execution_id)
+
+        already_scheduled = execution.events.where(event_type: "compensation_scheduled")
+                                            .where("payload ->> 'step' = ?", step.to_s)
+                                            .where("payload ->> 'task' = ?", compensation_task.to_s)
+                                            .exists?
+        return if already_scheduled
+
+        append_event(
+          execution_id:,
+          type: :compensation_scheduled,
+          payload: {
+            step: step,
+            task: compensation_task
+          }
+        )
+
+        headers = {
+          execution_id: execution_id,
+          step_name: step,
+          attempt: 1,
+          idempotency_key: Idempotency.digest(execution_id, step, "compensation"),
+          workflow_name: workflow_class.workflow_name,
+          metadata: execution.metadata,
+          compensation: true,
+          compensation_task: compensation_task
+        }
+
+        SolidFlow::Jobs::RunTaskJob.perform_later(
+          execution_id,
+          step,
+          compensation_task,
+          context,
+          headers
+        )
+
+        SolidFlow.instrument(
+          "solidflow.compensation.scheduled",
+          execution_id:,
+          step: step,
+          task: compensation_task
+        )
+      end
+
+      def record_compensation_result(execution_id:, step:, compensation_task:, result:)
+        append_event(
+          execution_id:,
+          type: :compensation_completed,
+          payload: {
+            step: step,
+            task: compensation_task,
+            result: result
+          }
+        )
+
+        SolidFlow.instrument(
+          "solidflow.compensation.completed",
+          execution_id:,
+          step: step,
+          task: compensation_task,
+          result: result
+        )
+      end
+
+      def record_compensation_failure(execution_id:, step:, compensation_task:, error:)
+        append_event(
+          execution_id:,
+          type: :compensation_failed,
+          payload: {
+            step: step,
+            task: compensation_task,
+            error: error
+          }
+        )
+
+        SolidFlow.instrument(
+          "solidflow.compensation.failed",
+          execution_id:,
+          step: step,
+          task: compensation_task,
+          error: error
+        )
+      end
+
+      private
+
+      def execution_for(execution_id)
+        current = Thread.current[THREAD_EXECUTION]
+        return current if current&.id == execution_id
+
+        SolidFlow::Execution.find(execution_id)
+      end
+
+      def serialize_execution(execution)
+        {
+          id: execution.id,
+          workflow: execution.workflow,
+          state: execution.state,
+          ctx: execution.ctx_hash,
+          cursor_step: execution.cursor_step,
+          cursor_index: execution.cursor_index,
+          graph_signature: execution.graph_signature,
+          metadata: execution.metadata || {}
+        }
+      end
+
+      def normalize_attributes(attributes)
+        attributes.transform_keys(&:to_s).tap do |normalized|
+          normalized["cursor_step"] = normalized["cursor_step"].to_s if normalized.key?("cursor_step") && !normalized["cursor_step"].nil?
+        end
+      end
+
+      def build_handle(execution)
+        OpenStruct.new(
+          id: execution.id,
+          workflow: execution.workflow,
+          state: execution.state,
+          cursor_step: execution.cursor_step,
+          cursor_index: execution.cursor_index
+        )
+      end
+    end
+  end
+end

data/lib/solid_flow/stores/base.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SolidFlow
+  module Stores
+    class Base
+      def initialize(event_serializer:, time_provider:, logger:)
+        @event_serializer = event_serializer
+        @time_provider = time_provider
+        @logger = logger
+      end
+
+      attr_reader :event_serializer, :time_provider, :logger
+
+      def start_execution(workflow_class:, input:, graph_signature:)
+        raise NotImplementedError
+      end
+
+      def signal_execution(execution_id:, workflow_class:, signal_name:, payload:)
+        raise NotImplementedError
+      end
+
+      def query_execution(execution_id:, workflow_class:)
+        raise NotImplementedError
+      end
+
+      def with_execution(execution_id, lock: true)
+        raise NotImplementedError
+      end
+
+      def load_history(execution_id)
+        raise NotImplementedError
+      end
+
+      def append_event(execution_id:, type:, payload:)
+        raise NotImplementedError
+      end
+
+      def update_execution(execution_id:, attributes:)
+        raise NotImplementedError
+      end
+
+      def persist_context(execution_id:, ctx:)
+        raise NotImplementedError
+      end
+
+      def enqueue_execution(execution_id:, reason:)
+        raise NotImplementedError
+      end
+
+      def schedule_task(execution_id:, step:, task:, arguments:, headers:, run_at: nil)
+        raise NotImplementedError
+      end
+
+      def record_task_result(execution_id:, step:, result:, attempt:, ctx_snapshot:, idempotency_key:)
+        raise NotImplementedError
+      end
+
+      def record_task_failure(execution_id:, step:, attempt:, error:, retryable:)
+        raise NotImplementedError
+      end
+
+      def schedule_timer(execution_id:, step:, run_at:, instruction:, metadata:)
+        raise NotImplementedError
+      end
+
+      def mark_timer_fired(timer_id:)
+        raise NotImplementedError
+      end
+
+      def persist_signal_consumed(execution_id:, signal_name:)
+        raise NotImplementedError
+      end
+
+      def schedule_compensation(execution_id:, workflow_class:, step:, compensation_task:, context:)
+        raise NotImplementedError
+      end
+
+      def record_compensation_result(execution_id:, step:, compensation_task:, result:)
+        raise NotImplementedError
+      end
+
+      def record_compensation_failure(execution_id:, step:, compensation_task:, error:)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/solid_flow/task.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/string/inflections"
+
+module SolidFlow
+  # Base class for all stateless tasks executed out-of-band from the workflow process.
+  class Task
+    THREAD_KEY = :__solidflow_task_context__
+
+    class << self
+      attr_reader :timeout_config, :retry_config, :queue_name, :task_symbol
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@timeout_config, timeout_config&.dup)
+        subclass.instance_variable_set(:@retry_config, retry_config&.dup)
+        subclass.instance_variable_set(:@queue_name, queue_name)
+        subclass.instance_variable_set(:@task_symbol, subclass.default_task_symbol)
+        SolidFlow.task_registry.register(subclass.default_task_symbol, subclass)
+      end
+
+      def default_task_symbol
+        name.demodulize.underscore.to_sym
+      end
+
+      def register_as(name)
+        @task_symbol = name.to_sym
+        SolidFlow.task_registry.register(@task_symbol, self)
+      end
+
+      def timeout(value = nil)
+        if value
+          @timeout_config = value
+        else
+          @timeout_config
+        end
+      end
+
+      def retry(options = nil)
+        if options
+          @retry_config = options.deep_symbolize_keys
+        else
+          @retry_config || {}
+        end
+      end
+
+      def queue(name = nil)
+        if name
+          @queue_name = name
+        else
+          @queue_name || SolidFlow.configuration.default_task_queue
+        end
+      end
+
+      def execute(arguments:, headers:)
+        context = TaskContext.new(
+          execution_id: headers[:execution_id],
+          step_name: headers[:step_name],
+          attempt: headers[:attempt],
+          idempotency_key: headers[:idempotency_key],
+          workflow_name: headers[:workflow_name],
+          metadata: headers[:metadata] || {}
+        )
+
+        SolidFlow.instrument(
+          "solidflow.task.started",
+          task: task_symbol,
+          execution_id: context.execution_id,
+          step_name: context.step_name,
+          attempt: context.attempt
+        )
+
+        result = with_task_context(context) do
+          new.perform(**arguments.symbolize_keys)
+        end
+
+        SolidFlow.instrument(
+          "solidflow.task.completed",
+          task: task_symbol,
+          execution_id: context.execution_id,
+          step_name: context.step_name,
+          attempt: context.attempt,
+          result:
+        )
+
+        result
+      rescue StandardError => e
+        SolidFlow.instrument(
+          "solidflow.task.failed",
+          task: task_symbol,
+          execution_id: context.execution_id,
+          step_name: context.step_name,
+          attempt: context.attempt,
+          error: e
+        )
+        raise Errors::TaskFailure.new(e.message, details: { class: e.class.name, backtrace: e.backtrace })
+      end
+
+      def current_context
+        Thread.current[THREAD_KEY]
+      end
+
+      private
+
+      def with_task_context(context)
+        previous = Thread.current[THREAD_KEY]
+        Thread.current[THREAD_KEY] = context
+        yield
+      ensure
+        Thread.current[THREAD_KEY] = previous
+      end
+    end
+
+    class TaskContext
+      attr_reader :execution_id, :step_name, :attempt, :idempotency_key, :workflow_name, :metadata
+
+      def initialize(execution_id:, step_name:, attempt:, idempotency_key:, workflow_name:, metadata:)
+        @execution_id = execution_id
+        @step_name = step_name
+        @attempt = attempt
+        @idempotency_key = idempotency_key
+        @workflow_name = workflow_name
+        @metadata = metadata
+      end
+    end
+
+    def perform(**)
+      raise NotImplementedError, "Tasks must implement #perform"
+    end
+
+    def current_context
+      self.class.current_context
+    end
+
+    def current_execution_id
+      current_context&.execution_id
+    end
+
+    def current_step_name
+      current_context&.step_name
+    end
+
+    def current_attempt
+      current_context&.attempt
+    end
+
+    def current_idempotency_key
+      current_context&.idempotency_key
+    end
+  end
+end