active_saga 0.1.0

data/lib/active_workflow/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_support/logger"
+
+module ActiveWorkflow
+  # Holds gem-level configuration.
+  class Configuration
+    attr_accessor :store, :serializer, :logger, :clock
+
+    def initialize
+      @serializer = ActiveWorkflow::Serializers::Json.new
+      @logger     = ActiveSupport::Logger.new($stdout, level: :info)
+      @clock      = -> { Time.now.utc }
+    end
+
+    # Ensures store is set before usage.
+    def store!
+      raise ActiveWorkflow::Errors::Configuration, "ActiveWorkflow.store is not configured" unless store
+
+      store
+    end
+  end
+end

data/lib/active_workflow/context.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "active_support/hash_with_indifferent_access"
+
+module ActiveWorkflow
+  # TODO Revisit impl.
+  class Context
+    include Enumerable
+
+    def initialize(payload = {})
+      @payload = normalize(payload || {})
+    end
+
+    def [](key)
+      @payload[key.to_sym]
+    end
+
+    def []=(key, value)
+      @payload[key.to_sym] = normalize(value)
+    end
+
+    def fetch(key, *args)
+      @payload.fetch(key.to_sym, *args)
+    end
+
+    def merge!(other_hash)
+      other_hash.each_pair { |k, v| self[k] = v }
+      self
+    end
+
+    def to_h
+      deep_dup(@payload)
+    end
+
+    def each(&block)
+      @payload.each(&block)
+    end
+
+    def dup
+      self.class.new(to_h)
+    end
+
+    private
+
+    def normalize(value)
+      case value
+      when Context
+        value.to_h
+      when ActiveSupport::HashWithIndifferentAccess
+        normalize_hash(value.to_h)
+      when Hash
+        normalize_hash(value)
+      when Array
+        value.each_with_index do |item, index|
+          value[index] = normalize(item)
+        end
+        value
+      else
+        value
+      end
+    end
+
+    def normalize_hash(hash)
+      hash.each_with_object(ActiveSupport::HashWithIndifferentAccess.new) do |(key, val), memo|
+        memo[key] = normalize(val)
+      end
+    end
+
+    def deep_dup(value)
+      case value
+      when ActiveSupport::HashWithIndifferentAccess
+        ActiveSupport::HashWithIndifferentAccess.new(value.transform_values { |v| deep_dup(v) })
+      when Hash
+        value.each_with_object({}) { |(k, v), memo| memo[k] = deep_dup(v) }
+      when Array
+        value.map { |v| deep_dup(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/active_workflow/dsl/options.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  module DSL
+    # Configuration helpers shared by workflows.
+    module Options
+      def self.extended(base)
+        base.class_attribute :_aw_defaults, instance_writer: false, default: {}
+        base.class_attribute :_aw_timeout, instance_writer: false, default: nil
+        base.class_attribute :_aw_idempotency_block, instance_writer: false, default: nil
+      end
+
+      def defaults(opts = nil)
+        if opts
+          self._aw_defaults = (_aw_defaults.deep_dup || {}).deep_merge(opts.deep_symbolize_keys)
+        else
+          _aw_defaults.deep_dup || {}
+        end
+      end
+
+      def timeout(value = nil)
+        value ? self._aw_timeout = value : _aw_timeout
+      end
+
+      def idempotency_key(&block)
+        block ? self._aw_idempotency_block = block : _aw_idempotency_block
+      end
+
+      def resolve_defaults(step_options)
+        defaults.deep_merge(step_options.deep_symbolize_keys)
+      end
+    end
+  end
+end

data/lib/active_workflow/dsl/signals.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  module DSL
+    module Signals
+      def self.extended(base)
+        base.class_attribute :_aw_signal_handlers, instance_writer: false, default: {} # name => method
+      end
+
+      def inherited(subclass)
+        super
+        subclass._aw_signal_handlers = _aw_signal_handlers.dup
+      end
+
+      def signal(name, to:)
+        self._aw_signal_handlers = _aw_signal_handlers.merge(name.to_sym => to.to_sym)
+      end
+
+      def signal_handler_for(name)
+        _aw_signal_handlers[name.to_sym]
+      end
+    end
+  end
+end

data/lib/active_workflow/dsl/steps.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  module DSL
+    module Steps
+      StepDefinition = Struct.new(:name, :style, :callable, :options, keyword_init: true) do
+        def initialize(*)
+          super
+          self.options = self[:options]
+        end
+
+        def options
+          self[:options] ||= {}
+        end
+
+        def options=(value)
+          self[:options] = value.is_a?(Hash) ? normalize(value) : {}
+        end
+
+        def dup
+          self.class.new(name:, style:, callable:, options: deep_dup(options))
+        end
+
+        def to_h
+          { name:, style:, callable:, options: deep_dup(options) }
+        end
+
+        def async?
+          options[:async] || false
+        end
+
+        def dedupe?
+          options[:dedupe] || false
+        end
+
+        def fire_and_forget?
+          options[:fire_and_forget] || false
+        end
+
+        private
+
+        def normalize(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(k, v), memo|
+              memo[k.to_sym] = normalize(v)
+            end
+          when Array
+            value.map { |item| normalize(item) }
+          else
+            value
+          end
+        end
+
+        def deep_dup(hash)
+          case hash
+          when Hash
+            hash.each_with_object({}) do |(k, v), memo|
+              memo[k] = deep_dup(v)
+            end
+          when Array
+            hash.map { |item| deep_dup(item) }
+          else
+            hash
+          end
+        end
+      end
+
+      def self.extended(base)
+        base.class_attribute :_aw_steps, instance_writer: false, default: []
+      end
+
+      def inherited(subclass)
+        super
+        subclass._aw_steps = _aw_steps.map(&:dup)
+      end
+
+      def steps
+        _aw_steps
+      end
+
+      def step_definition(name)
+        steps.find { |definition| definition.name == name.to_sym } ||
+          raise(ActiveWorkflow::Errors::InvalidStep, "Unknown step: #{name}")
+      end
+
+      def step(name, **options)
+        register_step(:method, name, nil, options)
+      end
+
+      def task(name, handler = nil, **options, &block)
+        if handler && block
+          raise ActiveWorkflow::Errors::InvalidStep, "Provide a Task class or a block, not both"
+        end
+
+        callable = handler || block
+        style = if block
+          :block
+        elsif handler.is_a?(Class) && handler <= ActiveWorkflow::Task
+          :task
+        elsif handler.respond_to?(:call)
+          :callable
+        else
+          raise ActiveWorkflow::Errors::InvalidStep, "Task handler must be a Task subclass, callable, or block"
+        end
+
+        step_options = if handler.is_a?(Class) && handler <= ActiveWorkflow::Task
+          handler.async_options.deep_merge(options)
+        else
+          options
+        end
+
+        register_step(style, name, callable, step_options)
+      end
+
+      def wait_for_signal(name, **options)
+        register_step(:wait, name, nil, options)
+      end
+
+      private
+
+      def register_step(style, name, callable, options)
+        name = name.to_sym
+        step_options = resolve_defaults((options || {}).deep_symbolize_keys)
+        definition = StepDefinition.new(name:, style:, callable:, options: step_options)
+        remaining = _aw_steps.reject { |step| step.name == name }
+        self._aw_steps = remaining + [definition]
+      end
+    end
+  end
+end

data/lib/active_workflow/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  module Errors
+    class Error < StandardError; end
+
+    class Configuration < Error; end
+    class InvalidWorkflow < Error; end
+    class InvalidStep < Error; end
+    class InvalidTransition < Error; end
+    class StepTimeout < Error; end
+    class StepNotWaiting < Error; end
+    class SignalNotFound < Error; end
+    class IdempotencyConflict < Error; end
+    class StoreError < Error; end
+    class AsyncCompletionConflict < Error; end
+  end
+end

data/lib/active_workflow/execution.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  # Lightweight value object representing a workflow execution.
+  class Execution
+    attr_reader :id, :workflow_class, :state, :ctx, :cursor_step, :created_at, :updated_at, :cancelled_at
+
+    def initialize(id:, workflow_class:, state:, ctx:, cursor_step:, created_at:, updated_at:, cancelled_at: nil, store: ActiveWorkflow.store)
+      @id             = id
+      @workflow_class = workflow_class
+      @state          = state
+      @ctx            = ActiveWorkflow::Context.new(ctx)
+      @cursor_step    = cursor_step&.to_sym
+      @created_at     = created_at
+      @updated_at     = updated_at
+      @cancelled_at   = cancelled_at
+      @store          = store
+    end
+
+    def completed?
+      state == "completed"
+    end
+
+    def failed?
+      state == "failed"
+    end
+
+    def cancelled?
+      state == "cancelled"
+    end
+
+    # Blocks until execution reaches a terminal state or timeout expires.
+    # Returns the final execution snapshot.
+    #
+    # @param timeout [Numeric, nil] seconds to wait, nil for indefinite
+    # @param interval [Numeric] polling interval
+    def await(timeout: nil, interval: 0.5)
+      clock = ActiveWorkflow.configuration.clock
+      deadline = timeout && clock.call + timeout
+      loop do
+        break if terminal?
+        raise Timeout::Error, "Execution #{id} did not finish within #{timeout}s" if deadline && clock.call > deadline
+
+        sleep(interval)
+        reload!
+      end
+      self
+    end
+
+    def terminal?
+      %w[completed failed cancelled timed_out].include?(state)
+    end
+
+    def reload!
+      fresh = @store.load_execution(id)
+      update_from(fresh) if fresh
+      self
+    end
+
+    def cancel!(reason: nil)
+      ActiveWorkflow.cancel!(id, reason: reason)
+      reload!
+    end
+
+    private
+
+    def update_from(other)
+      @state       = other.state
+      @ctx         = other.ctx
+      @cursor_step = other.cursor_step
+      @created_at  = other.created_at
+      @updated_at  = other.updated_at
+      @cancelled_at = other.cancelled_at
+    end
+  end
+end

data/lib/active_workflow/jobs/runner_job.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  module Jobs
+    # Executes workflow transitions within Active Job.
+    class RunnerJob < ActiveJob::Base
+      queue_as :active_workflow
+
+      # We want retries for transient errors only; user-defined retries handled within workflow.
+      retry_on ActiveRecord::Deadlocked, wait: 1.second, attempts: 5 if defined?(ActiveRecord::Deadlocked)
+
+      def perform(execution_id)
+        execution = ActiveWorkflow.configuration.store.load_execution(execution_id)
+        if execution
+          workflow = execution.workflow_class || "UnknownWorkflow"
+          step = execution.cursor_step || "pending"
+          ActiveWorkflow.configuration.logger.info(
+            "ActiveWorkflow::RunnerJob executing #{workflow}##{step} (execution=#{execution_id}) (state=#{execution.state})"
+          )
+        end
+
+        ActiveWorkflow.configuration.store!.process_execution(execution_id)
+      rescue ActiveWorkflow::Errors::InvalidWorkflow => e
+        ActiveWorkflow.configuration.logger.error("ActiveWorkflow invalid workflow: #{e.message}")
+        raise
+      end
+    end
+  end
+end

data/lib/active_workflow/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ActiveWorkflow
+  class Railtie < Rails::Railtie
+    initializer "active_workflow.configure" do |_app|
+      ActiveWorkflow.configure do |config|
+        config.logger ||= Rails.logger
+      end
+    end
+
+    rake_tasks do
+      load "active_workflow/tasks.rake" if File.exist?(File.join(__dir__, "../../tasks.rake"))
+    end
+  end
+end

data/lib/active_workflow/serializers/json.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActiveWorkflow
+  module Serializers
+    # Simple JSON wrapper allowing custom serialization strategies.
+    class Json
+      def dump(object)
+        JSON.generate(object)
+      end
+
+      def load(payload)
+        return {} if payload.nil? || payload == ""
+
+        JSON.parse(payload)
+      end
+    end
+  end
+end