active_saga 0.1.0

data/lib/active_workflow/stores/base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  module Stores
+    # Base interface for persistence adapters.
+    class Base
+      attr_reader :logger, :serializer, :clock
+
+      def initialize(logger: ActiveWorkflow.configuration.logger,
+        serializer: ActiveWorkflow.configuration.serializer,
+        clock: ActiveWorkflow.configuration.clock)
+        @logger     = logger
+        @serializer = serializer
+        @clock      = clock
+      end
+
+      def start_execution(**)
+        raise NotImplementedError
+      end
+
+      def load_execution(_id)
+        raise NotImplementedError
+      end
+
+      def complete_step!(*_args)
+        raise NotImplementedError
+      end
+
+      def fail_step!(*_args)
+        raise NotImplementedError
+      end
+
+      def extend_timeout!(*_args)
+        raise NotImplementedError
+      end
+
+      def heartbeat!(*_args)
+        raise NotImplementedError
+      end
+
+      def signal!(*_args)
+        raise NotImplementedError
+      end
+
+      def process_execution(_execution_id)
+        raise NotImplementedError
+      end
+
+      def enqueue_runner(_execution_id, _step_name = nil)
+        raise NotImplementedError
+      end
+
+      def with_execution_lock(_execution_id)
+        raise NotImplementedError
+      end
+
+      def cancel_execution!(_execution_id, reason: nil)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/active_workflow/task.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  # Base class for reusable workflow tasks.
+  class Task
+    class << self
+      attr_reader :_aw_async_options
+
+      def async!(**options)
+        @_aw_async_options = options.deep_symbolize_keys
+      end
+
+      def async_options
+        _aw_async_options || {}
+      end
+    end
+
+    def initialize(context)
+      @context = context
+    end
+
+    attr_reader :context
+
+    def call(_ctx)
+      raise NotImplementedError, "Override #call in #{self.class.name}"
+    end
+
+    def compensate(_ctx, result: nil)
+      nil
+    end
+  end
+end

data/lib/active_workflow/version.rb

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

data/lib/active_workflow/workflow.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  # Base class for defining workflows.
+  class Workflow
+    extend DSL::Options
+    extend DSL::Steps
+    extend DSL::Signals
+
+    attr_reader :context, :execution_id
+
+    class << self
+      def start(**attrs)
+        options = attrs.dup
+        explicit_idempotency_key = options.delete(:idempotency_key)
+        metadata = options.delete(:metadata) { {} }
+
+        context = ActiveWorkflow::Context.new(options)
+        workflow = new(context: context)
+        workflow.before_start
+
+        idempotency_key = explicit_idempotency_key || workflow.compute_idempotency_key
+        store = ActiveWorkflow.configuration.store!
+
+        execution = store.start_execution(
+          workflow_class: name,
+          context: context.to_h,
+          steps: steps.map.with_index { |step, idx| build_step_payload(step, idx) },
+          idempotency_key:,
+          timeout: timeout,
+          metadata: (metadata || {}).deep_symbolize_keys
+        )
+
+        ActiveSupport::Notifications.instrument("active_workflow.execution.started",
+          execution_id: execution.id, workflow: name)
+
+        execution
+      end
+
+      def build_step_payload(step, idx)
+        {
+          name: step.name.to_s,
+          style: step.style.to_s,
+          callable: callable_identifier(step),
+          options: step.options,
+          position: idx
+        }
+      end
+
+      def callable_identifier(step)
+        case step.style
+        when :method
+          step.name.to_s
+        when :task
+          step.callable.is_a?(Class) ? step.callable.name : step.callable.class.name
+        when :block
+          "block"
+        when :wait
+          "wait"
+        else
+          step.callable.respond_to?(:name) ? step.callable.name : step.callable.to_s
+        end
+      end
+    end
+
+    def initialize(context:, execution_id: nil)
+      @context = context
+      @execution_id = execution_id
+    end
+
+    def ctx
+      context
+    end
+
+    def before_start; end
+
+    def compute_idempotency_key
+      block = self.class.idempotency_key
+      return unless block
+
+      instance_exec(&block)
+    end
+
+    def call_step_callable(step_definition)
+      positional, keyword = resolve_arguments(step_definition)
+
+      case step_definition.style
+      when :method
+        send(step_definition.name, *positional, **keyword)
+      when :task
+        run_task_step(step_definition, positional, keyword)
+      when :block
+        step_definition.callable.call(context, *positional, **keyword)
+      when :wait
+        :waiting
+      else
+        raise ActiveWorkflow::Errors::InvalidStep, "Unknown style #{step_definition.style}"
+      end
+    end
+
+    private
+
+    def resolve_arguments(step_definition)
+      args_option = step_definition.options[:args]
+      return [[], {}] unless args_option
+
+      value = case args_option
+      when Proc
+        instance_exec(context, &args_option)
+      else
+        args_option
+      end
+
+      case value
+      when Array
+        [value, {}]
+      when Hash
+        [[], value.symbolize_keys]
+      when nil
+        [[], {}]
+      else
+        [[value], {}]
+      end
+    end
+
+    def run_task_step(step_definition, positional, keyword)
+      callable = step_definition.callable
+      case callable
+      when Class
+        callable.new(context).call(context, *positional, **keyword)
+      else
+        callable.call(context, *positional, **keyword)
+      end
+    end
+  end
+end

data/lib/active_workflow.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/module"
+require "active_support/core_ext/object"
+require "active_support/core_ext/array"
+require "active_support/core_ext/numeric/time"
+require "active_support/core_ext/hash"
+require "active_support/inflector"
+require "active_support/notifications"
+require "active_job"
+
+require_relative "active_workflow/version"
+require_relative "active_workflow/errors"
+require_relative "active_workflow/configuration"
+require_relative "active_workflow/context"
+require_relative "active_workflow/execution"
+require_relative "active_workflow/backoff"
+require_relative "active_workflow/dsl/options"
+require_relative "active_workflow/dsl/steps"
+require_relative "active_workflow/dsl/signals"
+require_relative "active_workflow/workflow"
+require_relative "active_workflow/task"
+require_relative "active_workflow/jobs/runner_job"
+require_relative "active_workflow/stores/base"
+require_relative "active_workflow/stores/active_record"
+require_relative "active_workflow/serializers/json"
+require_relative "active_workflow/railtie" if defined?(Rails::Railtie)
+
+module ActiveWorkflow
+  class << self
+    # @return [ActiveWorkflow::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields global configuration block and memoizes the configuration instance.
+    #
+    # @yieldparam [ActiveWorkflow::Configuration] config
+    def configure
+      yield(configuration)
+    end
+
+    # Resets configuration (mainly for tests)
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Delegates the store accessor for convenience.
+    #
+    # @return [ActiveWorkflow::Stores::Base]
+    def store
+      configuration.store!
+    end
+
+    # Entry point for async completions. Delegates to store and runner.
+    def complete_step!(execution_id, step_name, payload: nil, idempotency_key: nil)
+      with_instrumentation("complete", execution_id, step_name) do
+        store.complete_step!(execution_id, step_name.to_s, payload: payload, idempotency_key: idempotency_key)
+      end
+    end
+
+    def fail_step!(execution_id, step_name, error_class:, message:, details: {}, idempotency_key: nil)
+      with_instrumentation("fail", execution_id, step_name) do
+        store.fail_step!(execution_id, step_name.to_s,
+          error_class: error_class,
+          message: message,
+          details: details,
+          idempotency_key: idempotency_key)
+      end
+    end
+
+    def extend_timeout!(execution_id, step_name, by:)
+      store.extend_timeout!(execution_id, step_name.to_s, by: by)
+    end
+
+    def heartbeat!(execution_id, step_name, at: configuration.clock.call)
+      store.heartbeat!(execution_id, step_name.to_s, at: at)
+    end
+
+    def signal!(execution_id, name, payload: nil)
+      with_instrumentation("signal", execution_id, name) do
+        store.signal!(execution_id, name.to_s, payload: payload)
+      end
+    end
+
+    def cancel!(execution_id, reason: nil)
+      store.cancel_execution!(execution_id, reason: reason)
+    end
+
+    private
+
+    def with_instrumentation(action, execution_id, step_name)
+      ActiveSupport::Notifications.instrument("active_workflow.step.#{action}",
+        execution_id: execution_id,
+        step: step_name.to_s) { yield }
+    end
+  end
+end

data/lib/generators/active_workflow/install/install_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveWorkflow
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_initializer, type: :boolean, default: false, desc: "Skip initializer file"
+      class_option :skip_sample, type: :boolean, default: false, desc: "Skip sample workflow"
+
+      def copy_initializer
+        return if options[:skip_initializer]
+
+        template "initializer.rb", "config/initializers/active_workflow.rb"
+      end
+
+      def copy_migration
+        migration_template "migrations/create_active_workflow_tables.rb", "db/migrate/create_active_workflow_tables.rb"
+      end
+
+      def copy_sample_workflow
+        return if options[:skip_sample]
+
+        template "sample_workflow.rb", "app/workflows/sample_workflow.rb"
+      end
+
+      private
+
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          format("%03d", (current_migration_number(dirname) + 1))
+        end
+      end
+    end
+  end
+end

data/lib/generators/active_workflow/install/templates/initializer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+ActiveWorkflow.configure do |config|
+  config.logger     = Rails.logger
+  config.clock      = -> { Time.now.utc }
+  config.serializer = ActiveWorkflow::Serializers::Json.new
+  config.store      = ActiveWorkflow::Stores::ActiveRecord.new
+end

data/lib/generators/active_workflow/install/templates/migrations/create_active_workflow_tables.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class CreateActiveWorkflowTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :aw_executions do |t|
+      t.string  :workflow_class, null: false
+      t.string  :state, null: false
+      t.text    :ctx, null: false
+      t.string  :cursor_step
+      t.string  :idempotency_key
+      t.jsonb   :metadata, null: false, default: {}
+      t.datetime :timeout_at
+      t.string   :last_error_class
+      t.text     :last_error_message
+      t.datetime :last_error_at
+      t.datetime :last_enqueued_at
+      t.datetime :completed_at
+      t.datetime :cancelled_at
+
+      t.timestamps
+    end
+
+    add_index :aw_executions, :workflow_class
+    add_index :aw_executions, :state
+    add_index :aw_executions, :idempotency_key, unique: true
+
+    create_table :aw_steps do |t|
+      t.references :execution, null: false, foreign_key: { to_table: :aw_executions }
+      t.string  :name, null: false
+      t.string  :style, null: false
+      t.jsonb   :options, null: false, default: {}
+      t.string  :state, null: false
+      t.integer :position, null: false
+      t.integer :attempts, null: false, default: 0
+      t.datetime :scheduled_at
+      t.datetime :waiting_since
+      t.datetime :timeout_at
+      t.datetime :started_at
+      t.datetime :completed_at
+      t.datetime :last_error_at
+      t.string   :last_error_class
+      t.text     :last_error_message
+      t.jsonb    :last_error_details, null: false, default: {}
+      t.text     :last_error_backtrace
+      t.jsonb    :init_result
+      t.jsonb    :completion_payload
+      t.string   :completion_idempotency_key
+      t.string   :correlation_id
+      t.datetime :last_heartbeat_at
+
+      t.timestamps
+    end
+
+    add_index :aw_steps, [:execution_id, :position]
+    add_index :aw_steps, [:execution_id, :name]
+    add_index :aw_steps, [:execution_id, :completion_idempotency_key], unique: true, where: "completion_idempotency_key IS NOT NULL"
+
+    create_table :aw_events do |t|
+      t.references :execution, null: false, foreign_key: { to_table: :aw_executions }
+      t.string  :name, null: false
+      t.jsonb   :payload, null: false, default: {}
+      t.datetime :consumed_at
+
+      t.timestamps
+    end
+
+    add_index :aw_events, [:execution_id, :name]
+    add_index :aw_events, [:execution_id, :name], where: "consumed_at IS NULL", name: "index_aw_events_unconsumed"
+  end
+end

data/lib/generators/active_workflow/install/templates/sample_workflow.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class SampleWorkflow < ActiveWorkflow::Workflow
+  idempotency_key { "sample:#{ctx[:reference]}" }
+  defaults retry: { max: 3, strategy: :exponential, first_delay: 2.seconds, jitter: true }
+
+  step :prepare_data
+  task :perform_remote_export, RemoteExportTask, async: true, timeout: 15.minutes, store_result_as: :export_job
+  wait_for_signal :approval, as: :approval_payload
+  task :finalize do |ctx|
+    Rails.logger.info("Finalizing workflow for #{ctx[:reference]} with #{ctx[:approval_payload]}")
+  end
+
+  def prepare_data
+    ctx[:prepared_at] = Time.now.utc
+  end
+end
+
+class RemoteExportTask < ActiveWorkflow::Task
+  async! timeout: 15.minutes
+
+  def call(ctx)
+    ExternalExporter.request!(ctx[:reference]).slice(:job_id, :correlation_id)
+  end
+
+  def compensate(ctx, result: nil)
+    ExternalExporter.cancel!(result[:job_id]) if result
+  end
+end

data/lib/generators/active_workflow/workflow/templates/workflow.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ActiveWorkflow::Workflow
+  # idempotency_key { "#{name.underscore}:#{ctx[:resource_id]}" }
+  # defaults retry: { max: 3, strategy: :exponential, first_delay: 2.seconds, jitter: true }
+
+  # Example step styles:
+  # step :do_something, timeout: 5.minutes
+  # task :perform_task, SomeTaskClass, dedupe: true
+  # task :notify do |ctx|
+  #   Notifications.deliver(ctx[:user_id])
+  # end
+  # wait_for_signal :approval, as: :approval_payload
+
+  def do_something
+    # ctx[:result] = Service.call!(ctx[:input])
+  end
+end

data/lib/generators/active_workflow/workflow/workflow_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ActiveWorkflow
+  module Generators
+    class WorkflowGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a workflow skeleton under app/workflows"
+
+      def create_workflow
+        template "workflow.rb", File.join("app/workflows", class_path, "#{file_name}.rb")
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: active_saga
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Laerti Papa
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-14 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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  ActiveWorkflow provides durable, idempotent workflow orchestration built on Rails Active Job.
+  It supports sync and async steps, retries with backoff, signals, compensations, and pluggable persistence stores.
+email:
+- laertis.pappas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ADAPTERS.md
+- CHANGELOG.md
+- GUIDE.md
+- LICENSE
+- README.md
+- lib/active_workflow.rb
+- lib/active_workflow/backoff.rb
+- lib/active_workflow/configuration.rb
+- lib/active_workflow/context.rb
+- lib/active_workflow/dsl/options.rb
+- lib/active_workflow/dsl/signals.rb
+- lib/active_workflow/dsl/steps.rb
+- lib/active_workflow/errors.rb
+- lib/active_workflow/execution.rb
+- lib/active_workflow/jobs/runner_job.rb
+- lib/active_workflow/railtie.rb
+- lib/active_workflow/serializers/json.rb
+- lib/active_workflow/stores/active_record.rb
+- lib/active_workflow/stores/base.rb
+- lib/active_workflow/task.rb
+- lib/active_workflow/version.rb
+- lib/active_workflow/workflow.rb
+- lib/generators/active_workflow/install/install_generator.rb
+- lib/generators/active_workflow/install/templates/initializer.rb
+- lib/generators/active_workflow/install/templates/migrations/create_active_workflow_tables.rb
+- lib/generators/active_workflow/install/templates/sample_workflow.rb
+- lib/generators/active_workflow/workflow/templates/workflow.rb
+- lib/generators/active_workflow/workflow/workflow_generator.rb
+homepage: https://github.com/laertispappas/active_saga
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/laertispappas/active_saga
+  source_code_uri: https://github.com/laertispappas/active_saga
+  changelog_uri: https://github.com/laertispappas/active_saga/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+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 workflow orchestration for Ruby on Rails'
+test_files: []