active_saga 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f22bd87e089cbb7d4ccd08fe763e561743824bb335131d37a41e2b6b78f8da45
-  data.tar.gz: 8ba648a0deac1b45cd719fef2c23501d5f5e2ba9f098938ae75f302b6b72b2c8
+  metadata.gz: 6f65ca97601199df9c8aa9e181356b7e37d373978fbd356c56ea1d49ed56dea9
+  data.tar.gz: a666fb0d16559a8ae29bcf0ea0675205133f923d25da533d5ae35413302416b0
 SHA512:
-  metadata.gz: 72361a30caa2c5d3bf49474f10e0cfbf97a926e6280b57429c786e6fd27a801a1541488db02140a274dc425b7941e726145d5e2891123318ed3893b37d81dd96
-  data.tar.gz: 88ffd609d73f55490aea49d7d60871697b9e49fad0a8347cb01cc5fb3138cab8bd8635791b569b1bbfa62ccd3809c93c5d19226272e2c0098a0b54950a1c1566
+  metadata.gz: 258505e4e70af04dd2942d1d183f2bee1b64c80239f110b3156d216383c2a1eb9f39f36dc6412c897d7d95dfffc8ef1c040bbce6208487a50573e9eca13eafad
+  data.tar.gz: 569dcf7156607d0676576d1e5f89797fa0f2733336834a93ed2053e243b46411c0c60b2fdebdca122d6739f8b748ec88452c87de9db2119247999692138f84de

data/ADAPTERS.md

@@ -15,7 +15,7 @@ All adapters inherit from `ActiveSaga::Stores::Base` and must implement:
 - `extend_timeout!(execution_id, step_name, by:)`
 - `heartbeat!(execution_id, step_name, at:)`
 - `signal!(execution_id, name, payload:)`
-- `enqueue_runner(execution_id, run_at: nil)` – adapters may simply enqueue the internal runner job.
+- `enqueue_runner(execution, step_name: nil, run_at: nil)` – adapters may simply enqueue the internal runner job.
 - `cancel_execution!(execution_id, reason: nil)` – run compensations and cancel remaining steps.
 
 The methods must be **atomic**: never run business code outside a transaction or lock that protects

data/README.md

@@ -80,10 +80,11 @@ The installer creates:
 ```ruby
 # config/initializers/active_saga.rb
 ActiveSaga.configure do |c|
-  c.store      = ActiveSaga::Stores::ActiveRecord.new
+  c.store      = :active_record
   c.logger     = Rails.logger
   c.serializer = :json
   c.clock      = -> { Time.now.utc }
+  # c.queue    = :critical
 end
 ```
 
@@ -92,10 +93,11 @@ end
 class CheckoutFlow < ActiveSaga::Workflow
   idempotency_key { "checkout:#{ctx[:order_id]}" }
   defaults retry: { max: 5, backoff: :exponential, jitter: true, first_delay: 1.second }
+  queue :critical
   timeout 30.minutes
 
   step :charge_card, compensate: :refund_payment, retry: { max: 6, first_delay: 2.seconds }
-  task :reserve_stock, ReserveStockTask, dedupe: true
+  task :reserve_stock, ReserveStockTask, dedupe: true, queue: :fulfillment
   task :send_receipt,  fire_and_forget: true do |ctx|
     Mailers::Receipt.deliver_later(ctx[:order_id])
   end
@@ -327,7 +329,7 @@ step :slow_call, retry: { max: 10, backoff: :fixed, delay: 5.seconds }
 
 ```ruby
 ActiveSaga.configure do |c|
-  c.store      = ActiveSaga::Stores::ActiveRecord.new
+  c.store      = :active_record
   c.logger     = Rails.logger
   c.serializer = :json            # or a custom object responding to dump/load
   c.clock      = -> { Time.now.utc }
@@ -359,6 +361,7 @@ You can implement other stores (e.g., Redis) by following the `ActiveSaga::Store
 - A single internal job (e.g., `ActiveSaga::Jobs::RunnerJob`) receives execution/step IDs and performs the next transition safely.
 - **No dependency** on specific backends (Sidekiq, Solid Queue, etc.)—any Active Job adapter works.
 - Timers/backoffs are scheduled via `set(wait_until: ...)`.
+- Set a default queue with `queue :critical` in your workflow, and override individual steps via `queue: :fulfillment`.
 
 ---
 
@@ -383,6 +386,21 @@ Each event carries identifiers (execution_id, workflow, step), timings, attempts
 
 ---
 
+## Debugging Helpers
+
+Quick helpers make it easier to inspect running or finished executions from the console:
+
+```ruby
+ActiveSaga.executions(limit: 20).map { |exec| [exec.id, exec.state] }
+ActiveSaga.steps_for_execution(execution_id)
+ActiveSaga.events_for_execution(execution_id)
+ActiveSaga.failure_summary(execution_id)
+```
+
+These APIs surface the stored step/event data without querying the tables directly.
+
+---
+
 ## Generators
 
 ```bash

data/lib/active_saga/configuration.rb

@@ -5,12 +5,14 @@ require "active_support/logger"
 module ActiveSaga
   # Holds gem-level configuration.
   class Configuration
-    attr_accessor :store, :serializer, :logger, :clock
+    attr_accessor :serializer, :logger, :clock, :queue
+    attr_reader :store
 
     def initialize
       @serializer = ActiveSaga::Serializers::Json.new
       @logger     = ActiveSupport::Logger.new($stdout, level: :info)
       @clock      = -> { Time.now.utc }
+      @queue      = :active_saga
     end
 
     # Ensures store is set before usage.
@@ -19,5 +21,40 @@ module ActiveSaga
 
       store
     end
+
+    def store=(value)
+      @store = normalize_store(value)
+    end
+
+    private
+
+    def normalize_store(value)
+      return nil if value.nil?
+
+      case value
+      when Symbol, String
+        resolve_store_class(value).new
+      when Class
+        ensure_store_class!(value)
+        value.new
+      else
+        value
+      end
+    end
+
+    def resolve_store_class(name)
+      case name.to_sym
+      when :active_record
+        ActiveSaga::Stores::ActiveRecord
+      else
+        raise ActiveSaga::Errors::Configuration, "Unknown store adapter: #{name}"
+      end
+    end
+
+    def ensure_store_class!(klass)
+      return if klass <= ActiveSaga::Stores::Base
+
+      raise ActiveSaga::Errors::Configuration, "Store class must inherit from ActiveSaga::Stores::Base"
+    end
   end
 end

data/lib/active_saga/dsl/options.rb

@@ -8,6 +8,7 @@ module ActiveSaga
         base.class_attribute :_as_defaults, instance_writer: false, default: {}
         base.class_attribute :_as_timeout, instance_writer: false, default: nil
         base.class_attribute :_as_idempotency_block, instance_writer: false, default: nil
+        base.class_attribute :_as_queue, instance_writer: false, default: nil
       end
 
       def defaults(opts = nil)
@@ -26,8 +27,14 @@ module ActiveSaga
         block ? self._as_idempotency_block = block : _as_idempotency_block
       end
 
+      def queue(value = nil)
+        value ? self._as_queue = value : _as_queue
+      end
+
       def resolve_defaults(step_options)
-        defaults.deep_merge(step_options.deep_symbolize_keys)
+        base_defaults = defaults
+        base_defaults[:queue] ||= _as_queue if _as_queue
+        base_defaults.deep_merge(step_options.deep_symbolize_keys)
       end
     end
   end

data/lib/active_saga/jobs/runner_job.rb

@@ -4,7 +4,9 @@ module ActiveSaga
   module Jobs
     # Executes workflow transitions within Active Job.
     class RunnerJob < ActiveJob::Base
-      queue_as :active_saga
+      queue_as do
+        ActiveSaga.configuration.queue || :active_saga
+      end
 
       # 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)

data/lib/active_saga/stores/active_record.rb

@@ -99,7 +99,7 @@ module ActiveSaga
           end
         end
 
-        enqueue_runner(record.id) unless steps.empty?
+        enqueue_runner(record, step_name: steps.first && steps.first[:name]) unless steps.empty?
         build_execution(record)
       end
 
@@ -127,14 +127,43 @@ module ActiveSaga
         build_execution(record) if record
       end
 
-      def enqueue_runner(execution_id, run_at: nil)
-        if run_at
-          ActiveSaga::Jobs::RunnerJob.set(wait_until: run_at).perform_later(execution_id)
-        else
-          ActiveSaga::Jobs::RunnerJob.perform_later(execution_id)
+      def executions(limit: 100, offset: 0, workflow_class: nil, state: nil, order: :desc)
+        scope = Models::Execution.order(created_at: order == :asc ? :asc : :desc)
+        if workflow_class
+          name = workflow_class.is_a?(Class) ? workflow_class.name : workflow_class.to_s
+          scope = scope.where(workflow_class: name)
+        end
+        scope = scope.where(state:) if state
+        scope = scope.offset(offset) if offset&.positive?
+        scope = scope.limit(limit) if limit
+        scope.map { |record| build_execution(record) }
+      end
+
+      def steps_for(execution_id)
+        Models::Step.where(execution_id: execution_id).order(:position).map do |step|
+          step.attributes.deep_symbolize_keys
+        end
+      end
+
+      def events_for(execution_id)
+        Models::Event.where(execution_id: execution_id).order(:created_at).map do |event|
+          event.attributes.deep_symbolize_keys
         end
       end
 
+      def enqueue_runner(execution, step_name: nil, run_at: nil)
+        return if execution.nil?
+
+        options = {}
+        options[:wait_until] = run_at if run_at
+        queue = queue_for_execution(execution, step_name)
+        options[:queue] = queue if queue
+
+        job = ActiveSaga::Jobs::RunnerJob
+        job = job.set(options) if options.any?
+        job.perform_later(execution.id)
+      end
+
       def with_execution_lock(execution_id)
         ::ActiveRecord::Base.transaction do
           record = Models::Execution.lock.find_by(id: execution_id)
@@ -194,7 +223,7 @@ module ActiveSaga
 
           persist_context(execution, ctx)
           advance_cursor(execution, step)
-          enqueue_runner(execution.id)
+          enqueue_runner(execution, step_name: execution.cursor_step)
         end
       end
 
@@ -252,7 +281,7 @@ module ActiveSaga
           apply_signal_handler(execution, name, payload)
 
           if execution.steps.where(name: name.to_s, state: "waiting").exists?
-            enqueue_runner(execution.id)
+            enqueue_runner(execution, step_name: name)
           end
         end
       end
@@ -374,7 +403,7 @@ module ActiveSaga
             attempts: current_attempts + 1,
             wait: delay)
 
-          enqueue_runner(execution.id, run_at: scheduled_at)
+          enqueue_runner(execution, step_name: step.name, run_at: scheduled_at)
         else
           transition_to_failed!(execution, step)
         end
@@ -392,6 +421,23 @@ module ActiveSaga
 
       private
 
+      def queue_for_execution(execution, step_name)
+        name = step_name || execution.cursor_step
+        queue = nil
+        if name
+          definition = execution.workflow_class.constantize.step_definition(name.to_sym)
+          queue = definition.options[:queue] if definition.options.key?(:queue)
+        end
+        queue = queue.to_s if queue.is_a?(Symbol)
+        queue ||= ActiveSaga.configuration.queue
+        queue = queue.to_s if queue.is_a?(Symbol)
+        queue
+      rescue ActiveSaga::Errors::InvalidStep
+        queue = ActiveSaga.configuration.queue
+        queue = queue.to_s if queue.is_a?(Symbol)
+        queue
+      end
+
       def run_compensations!(execution, upto:)
         return unless upto
 
@@ -627,7 +673,7 @@ module ActiveSaga
           ActiveSupport::Notifications.instrument("active_saga.step.waiting",
             execution_id: execution.id, workflow: execution.workflow_class, step: definition.name)
           
-          store.enqueue_runner(execution.id, run_at: timeout_at) if timeout_at
+          store.enqueue_runner(execution, step_name: definition.name, run_at: timeout_at) if timeout_at
         end
 
         def mark_skipped(step, definition)

data/lib/active_saga/stores/base.rb

@@ -1,3 +1,4 @@
+
 # frozen_string_literal: true
 
 module ActiveSaga
@@ -46,7 +47,7 @@ module ActiveSaga
         raise NotImplementedError
       end
 
-      def enqueue_runner(_execution_id, _step_name = nil)
+      def enqueue_runner(_execution, step_name: nil, run_at: nil)
         raise NotImplementedError
       end
 
@@ -57,6 +58,18 @@ module ActiveSaga
       def cancel_execution!(_execution_id, reason: nil)
         raise NotImplementedError
       end
+
+      def executions(**_options)
+        raise NotImplementedError
+      end
+
+      def steps_for(_execution_id)
+        raise NotImplementedError
+      end
+
+      def events_for(_execution_id)
+        raise NotImplementedError
+      end
     end
   end
 end

data/lib/active_saga/task.rb

@@ -13,7 +13,7 @@ module ActiveSaga
       def async_options
         _as_async_options || {}
       end
-      end
+    end
 
     def initialize(context)
       @context = context

data/lib/active_saga/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveSaga
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/lib/active_saga.rb

@@ -88,6 +88,48 @@ module ActiveSaga
       store.cancel_execution!(execution_id, reason: reason)
     end
 
+    def execution(execution_id)
+      store.load_execution(execution_id)
+    end
+
+    def executions(**options)
+      store.executions(**options)
+    end
+
+    def steps_for_execution(execution_id)
+      store.steps_for(execution_id)
+    end
+
+    def events_for_execution(execution_id)
+      store.events_for(execution_id)
+    end
+
+    def failure_summary(execution_id)
+      execution = store.load_execution(execution_id)
+      return { execution_id:, state: nil, failures: [] } unless execution
+
+      steps = store.steps_for(execution_id)
+      failures = steps.select { |step| %w[failed timed_out].include?(step[:state]) }
+        .map do |step|
+          {
+            name: step[:name],
+            state: step[:state],
+            attempts: step[:attempts],
+            last_error_class: step[:last_error_class],
+            last_error_message: step[:last_error_message],
+            last_error_details: step[:last_error_details],
+            last_error_at: step[:last_error_at]
+          }
+        end
+
+      {
+        execution_id: execution.id,
+        workflow: execution.workflow_class,
+        state: execution.state,
+        failures: failures
+      }
+    end
+
     private
 
     def with_instrumentation(action, execution_id, step_name)

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

@@ -4,5 +4,5 @@ ActiveSaga.configure do |config|
   config.logger     = Rails.logger
   config.clock      = -> { Time.now.utc }
   config.serializer = ActiveSaga::Serializers::Json.new
-  config.store      = ActiveSaga::Stores::ActiveRecord.new
+  config.store      = :active_record
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_saga
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Laerti Papa