acidic_job 1.0.0.rc2 → 1.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91e85393ede0eb0d4100449b323a12d1d447acc339a2e365926aae4a35ca34cb
-  data.tar.gz: 2278997e2ef132f34c26f31d2d17c6d54fcce32a52cb90517e1b678f43f83ede
+  metadata.gz: 8af9b244cf2343978f26322753e80c779c224ab6942c85de5a8fe05cf0ba55f2
+  data.tar.gz: 5f609ee36139400937e2a8b3cae42f721eb72f1abf6633ddbd275aa18c1b2242
 SHA512:
-  metadata.gz: 308a693c544f5cd2cc36872aaa403762b54fe474a2f2718e3e3fd03be355df92aa3c5cfcbf4b2be7f8f20207aa847c6174fcc09d4a5e9c169277c50b85f22441
-  data.tar.gz: 6329afd0ebbd5ce72bbeeb60aeb5359ffec646723b4c01bb110ce2084557de0282b33252d8a81519637c9a11bf5b241fcf1feefac3216c119beed1b22eb9f8cd
+  metadata.gz: 6becc8ed3a1c1c58e24d52753e53edb206854cec472ffb4438e4711ea2a8abcd5adae080c621ab7b8bd30eb386118a51012a4f446e997277da3e9b12e460c696
+  data.tar.gz: fe04f817a6c2cab6b2284f7ce0a79b44f452e1c490abac18e6385b801a7ca00860e0910286886da6d70270b508ca54fa3ae4c13369d539e47c3ea4d12e9316d8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    acidic_job (1.0.0.rc2)
+    acidic_job (1.0.0.rc3)
       activejob (>= 7.1)
       activerecord (>= 7.1)
       activesupport (>= 7.1)

data/app/models/acidic_job/entry.rb

@@ -4,16 +4,16 @@ module AcidicJob
   class Entry < Record
     belongs_to :execution, class_name: "AcidicJob::Execution"
 
-    def started?
-      action == "started"
-    end
+    scope :for_step, ->(step) { where(step: step) }
+    scope :for_action, ->(action) { where(action: action) }
+    scope :ordered, -> { order(timestamp: :asc) }
 
-    def succeeded?
-      action == "succeeded"
+    def self.most_recent
+      order(created_at: :desc).first
     end
 
-    def errored?
-      action == "errored"
+    def action?(check)
+      action == check
     end
   end
 end

data/app/models/acidic_job/execution.rb

@@ -29,7 +29,28 @@ module AcidicJob
     end
 
     def finished?
-      recover_to.to_s == FINISHED_RECOVERY_POINT
+      # rubocop:disable Style/MultipleComparison
+      recover_to.to_s == FINISHED_RECOVERY_POINT ||
+        recover_to.to_s == "FINISHED" # old value pre-1.0, remove at v1.0
+      # rubocop:enable Style/MultipleComparison
+    end
+
+    def defined?(step)
+      if definition.key?("steps")
+        definition["steps"].key?(step)
+      else
+        # TODO: add deprecation warning
+        definition.key?(step)
+      end
+    end
+
+    def definition_for(step)
+      if definition.key?("steps")
+        definition["steps"].fetch(step)
+      else
+        # TODO: add deprecation warning
+        definition.fetch(step)
+      end
     end
 
     def deserialized_job

data/lib/acidic_job/builder.rb

@@ -4,12 +4,21 @@ module AcidicJob
   class Builder
     attr_reader :steps
 
-    def initialize
+    def initialize(plugins)
+      @plugins = plugins
       @steps = []
     end
 
-    def step(method_name, transactional: false)
-      @steps << { "does" => method_name.to_s, "transactional" => transactional }
+    def step(method_name, **kwargs)
+      step = { "does" => method_name.to_s }
+
+      @plugins.each do |plugin|
+        next unless kwargs.key?(plugin.keyword)
+
+        step[plugin.keyword.to_s] = plugin.validate(kwargs[plugin.keyword])
+      end
+
+      @steps << step
       @steps
     end
 
@@ -17,13 +26,20 @@ module AcidicJob
       # [ { does: "step 1", transactional: true }, { does: "step 2", transactional: false }, ... ]
       @steps << { "does" => FINISHED_RECOVERY_POINT }
 
-      {}.tap do |workflow|
+      definition = {
+        "meta" => {
+          "version" => VERSION
+        },
+        "steps" => {}
+      }
+
+      definition.tap do |workflow|
         @steps.each_cons(2).map do |enter_step, exit_step|
           enter_name = enter_step["does"]
-          workflow[enter_name] = enter_step.merge("then" => exit_step["does"])
+          workflow["steps"][enter_name] = enter_step.merge("then" => exit_step["does"])
         end
       end
-      # { "step 1": { does: "step 1", transactional: true, then: "step 2" }, ...  }
+      # { meta: { ... }, steps: { "step 1": { does: "step 1", transactional: true, then: "step 2" }, ...  } }
     end
   end
 end

data/lib/acidic_job/errors.rb

@@ -98,5 +98,27 @@ module AcidicJob
       "step method cannot expect arguments: #{@step.inspect}"
     end
   end
+
+  class DoublePluginCallError < Error
+    def initialize(plugin, step)
+      @plugin_name = Module === plugin ? plugin.name : plugin.class.name # rubocop:disable Style/CaseEquality
+      @step = step
+    end
+
+    def message
+      "plugin `#{@plugin_name}` attempted to call step multiple times: #{@step.inspect}"
+    end
+  end
+
+  class MissingPluginCallError < Error
+    def initialize(plugin, step)
+      @plugin_name = Module === plugin ? plugin.name : plugin.class.name # rubocop:disable Style/CaseEquality
+      @step = step
+    end
+
+    def message
+      "plugin `#{@plugin_name}` failed to call step: #{@step.inspect}"
+    end
+  end
   # rubocop:enable Lint/MissingSuper
 end

data/lib/acidic_job/log_subscriber.rb

@@ -5,33 +5,33 @@ require "active_support/log_subscriber"
 module AcidicJob
   class LogSubscriber < ActiveSupport::LogSubscriber
     def define_workflow(event)
-      debug formatted_event(event, action: "Define workflow", **event.payload.slice("job_class", "job_id"))
+      debug formatted_event(event, title: "Define workflow", **event.payload.slice(:job_class, :job_id))
     end
 
     def initialize_workflow(event)
-      debug formatted_event(event, action: "Initialize workflow", **event.payload.slice("steps"))
+      debug formatted_event(event, title: "Initialize workflow", **event.payload.slice(:steps))
     end
 
     def process_workflow(event)
-      debug formatted_event(event, action: "Process workflow", **event.payload["execution"].slice("id", "recover_to"))
+      debug formatted_event(event, title: "Process workflow", **event.payload[:execution].slice(:id, :recover_to))
     end
 
     def process_step(event)
-      debug formatted_event(event, action: "Process step", **event.payload)
+      debug formatted_event(event, title: "Process step", **event.payload)
     end
 
     def perform_step(event)
-      debug formatted_event(event, action: "Perform step", **event.payload)
+      debug formatted_event(event, title: "Perform step", **event.payload)
     end
 
     def record_entry(event)
-      debug formatted_event(event, action: "Record entry", **event.payload.slice(:step, :action, :timestamp))
+      debug formatted_event(event, title: "Record entry", **event.payload.slice(:step, :action, :timestamp))
     end
 
     private
 
-    def formatted_event(event, action:, **attributes)
-      "AcidicJob-#{AcidicJob::VERSION} #{action} (#{event.duration.round(1)}ms)  #{formatted_attributes(**attributes)}"
+    def formatted_event(event, title:, **attributes)
+      "AcidicJob-#{AcidicJob::VERSION} #{title} (#{event.duration.round(1)}ms)  #{formatted_attributes(**attributes)}"
     end
 
     def formatted_attributes(**attributes)

data/lib/acidic_job/plugin_context.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module AcidicJob
+  class PluginContext
+    PLUGIN_INACTIVE = :__ACIDIC_JOB_PLUGIN_INACTIVE__
+
+    def initialize(plugin, job, execution, step_definition)
+      @plugin = plugin
+      @job = job
+      @execution = execution
+      @step_definition = step_definition
+    end
+
+    def definition
+      @step_definition.fetch(@plugin.keyword.to_s, PLUGIN_INACTIVE)
+    end
+
+    def current_step
+      @step_definition["does"]
+    end
+
+    def inactive?
+      definition == PLUGIN_INACTIVE
+    end
+
+    def entries_for_action(action)
+      @execution.entries.for_action(plugin_action(action))
+    end
+
+    def record!(step:, action:, timestamp:, **kwargs)
+      @execution.record!(
+        step: step,
+        action: plugin_action(action),
+        timestamp: timestamp,
+        **kwargs
+      )
+    end
+
+    def enqueue_job(...)
+      @job.enqueue(...)
+    end
+
+    def halt_step!
+      @job.halt_step!
+    end
+
+    def plugin_action(action)
+      "#{@plugin.keyword}/#{action}"
+    end
+  end
+end

data/lib/acidic_job/plugins/transactional_step.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AcidicJob
+  module Plugins
+    module TransactionalStep
+      extend self
+
+      def keyword
+        :transactional
+      end
+
+      # transactional: true
+      # transactional: false
+      # transactional: { on: Model }
+      def validate(input)
+        return input if input in true | false
+
+        raise ArgumentError.new("argument must be boolean or hash") unless input in Hash
+        raise ArgumentError.new("argument hash must have `on` key") unless input in Hash[on:]
+        raise ArgumentError.new("`on` key must have module value") unless input in Hash[on: Module]
+
+        input
+      end
+
+      def around_step(context, &block)
+        return yield if context.definition == false
+
+        model = if context.definition == true
+                  AcidicJob::Execution
+                else
+                  context.definition["on"].constantize
+                end
+
+        model.transaction(&block)
+      end
+    end
+  end
+end

data/lib/acidic_job/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AcidicJob
-  VERSION = "1.0.0.rc2"
+  VERSION = "1.0.0.rc3"
 end

data/lib/acidic_job/workflow.rb

@@ -4,33 +4,31 @@ require "active_job"
 
 module AcidicJob
   module Workflow
-    NO_OP_WRAPPER = proc { |&block| block.call }
-    REPEAT_STEP = :REPEAT_STEP
-    HALT_STEP = :HALT_STEP
-    private_constant :NO_OP_WRAPPER, :REPEAT_STEP, :HALT_STEP
+    REPEAT_STEP = :__ACIDIC_JOB_REPEAT_STEP_SIGNAL__
+    HALT_STEP = :__ACIDIC_JOB_HALT_STEP_SIGNAL__
+    private_constant :REPEAT_STEP, :HALT_STEP
 
-    attr_reader :execution, :ctx
-
-    def execute_workflow(unique_by:, &block)
+    def execute_workflow(unique_by:, with: [Plugins::TransactionalStep], &block)
+      @__acidic_job_plugins__ = with
       serialized_job = serialize
 
       workflow_definition = AcidicJob.instrument(:define_workflow, **serialized_job) do
-        raise RedefiningWorkflowError if defined? @_builder
+        raise RedefiningWorkflowError if defined? @__acidic_job_builder__
 
-        @_builder = Builder.new
+        @__acidic_job_builder__ = Builder.new(@__acidic_job_plugins__)
 
         raise UndefinedWorkflowBlockError unless block_given?
         raise InvalidWorkflowBlockError if block.arity != 1
 
-        block.call @_builder
+        block.call @__acidic_job_builder__
 
-        raise MissingStepsError if @_builder.steps.empty?
+        raise MissingStepsError if @__acidic_job_builder__.steps.empty?
 
         # convert the array of steps into a hash of recovery_points and next steps
-        @_builder.define_workflow
+        @__acidic_job_builder__.define_workflow
       end
 
-      AcidicJob.instrument(:initialize_workflow, "definition" => workflow_definition) do
+      AcidicJob.instrument(:initialize_workflow, definition: workflow_definition) do
         transaction_args = case ::ActiveRecord::Base.connection.adapter_name.downcase.to_sym
                            # SQLite doesn't support `serializable` transactions
                            when :sqlite
@@ -40,7 +38,7 @@ module AcidicJob
                            end
         idempotency_key = Digest::SHA256.hexdigest(JSON.fast_generate([self.class.name, unique_by], strict: true))
 
-        @execution = ::ActiveRecord::Base.transaction(**transaction_args) do
+        @__acidic_job_execution__ = ::ActiveRecord::Base.transaction(**transaction_args) do
           record = Execution.find_by(idempotency_key: idempotency_key)
 
           if record.present?
@@ -62,41 +60,52 @@ module AcidicJob
               last_run_at: Time.current
             )
           else
+            starting_point = if workflow_definition.key?("steps")
+                               workflow_definition["steps"].keys.first
+                             else
+                               # TODO: add deprecation warning
+                               workflow_definition.keys.first
+                             end
+
             record = Execution.create!(
               idempotency_key: idempotency_key,
               serialized_job: serialized_job,
               definition: workflow_definition,
-              recover_to: workflow_definition.keys.first
+              recover_to: starting_point
             )
           end
 
           record
         end
       end
-      @ctx ||= Context.new(@execution)
+      @__acidic_job_context__ ||= Context.new(@__acidic_job_execution__)
 
-      AcidicJob.instrument(:process_workflow, execution: @execution.attributes) do
+      AcidicJob.instrument(:process_workflow, execution: @__acidic_job_execution__.attributes) do
         # if the workflow record is already marked as finished, immediately return its result
-        return true if @execution.finished?
+        return true if @__acidic_job_execution__.finished?
 
         loop do
-          break if @execution.finished?
+          break if @__acidic_job_execution__.finished?
 
-          current_step = @execution.recover_to
+          current_step = @__acidic_job_execution__.recover_to
 
-          if not @execution.definition.key?(current_step) # rubocop:disable Style/Not
+          if not @__acidic_job_execution__.defined?(current_step) # rubocop:disable Style/Not
             raise UndefinedStepError.new(current_step)
           end
 
-          step_definition = @execution.definition[current_step]
+          step_definition = @__acidic_job_execution__.definition_for(current_step)
           AcidicJob.instrument(:process_step, **step_definition) do
             recover_to = catch(:halt) { take_step(step_definition) }
             case recover_to
             when HALT_STEP
-              @execution.record!(step: step_definition.fetch("does"), action: :halted, timestamp: Time.now)
+              @__acidic_job_execution__.record!(
+                step: step_definition.fetch("does"),
+                action: :halted,
+                timestamp: Time.now
+              )
               return true
             else
-              @execution.update!(recover_to: recover_to)
+              @__acidic_job_execution__.update!(recover_to: recover_to)
             end
           end
         end
@@ -114,11 +123,19 @@ module AcidicJob
     def step_retrying?
       step_name = caller_locations.first.label
 
-      if not @execution.definition.key?(step_name) # rubocop:disable Style/IfUnlessModifier, Style/Not
+      if not @__acidic_job_execution__.defined?(step_name) # rubocop:disable Style/IfUnlessModifier, Style/Not
         raise UndefinedStepError.new(step_name)
       end
 
-      @execution.entries.where(step: step_name, action: "started").count > 1
+      @__acidic_job_execution__.entries.where(step: step_name, action: "started").count > 1
+    end
+
+    def execution
+      @__acidic_job_execution__
+    end
+
+    def ctx
+      @__acidic_job_context__
     end
 
     private
@@ -127,11 +144,11 @@ module AcidicJob
       curr_step = step_definition.fetch("does")
       next_step = step_definition.fetch("then")
 
-      return next_step if @execution.entries.exists?(step: curr_step, action: :succeeded)
+      return next_step if @__acidic_job_execution__.entries.exists?(step: curr_step, action: :succeeded)
 
       rescued_error = nil
       begin
-        @execution.record!(step: curr_step, action: :started, timestamp: Time.now)
+        @__acidic_job_execution__.record!(step: curr_step, action: :started, timestamp: Time.now)
         result = AcidicJob.instrument(:perform_step, **step_definition) do
           perform_step_for(step_definition)
         end
@@ -139,7 +156,7 @@ module AcidicJob
         when REPEAT_STEP
           curr_step
         else
-          @execution.record!(step: curr_step, action: :succeeded, timestamp: Time.now, result: result)
+          @__acidic_job_execution__.record!(step: curr_step, action: :succeeded, timestamp: Time.now, result: result)
           next_step
         end
       rescue StandardError => e
@@ -148,7 +165,7 @@ module AcidicJob
       ensure
         if rescued_error
           begin
-            @execution.record!(
+            @__acidic_job_execution__.record!(
               step: curr_step,
               action: :errored,
               timestamp: Time.now,
@@ -159,7 +176,7 @@ module AcidicJob
             # We're already inside an error condition, so swallow any additional
             # errors from here and just send them to logs.
             logger.error(
-              "Failed to store exception at step #{curr_step} for execution ##{@execution.id} because of #{e}."
+              "Failed to store exception at step #{curr_step} for execution ##{@__acidic_job_execution__.id}: #{e}."
             )
           end
         end
@@ -168,15 +185,38 @@ module AcidicJob
 
     def perform_step_for(step_definition)
       step_name = step_definition.fetch("does")
-      step_method = method(step_name)
+      begin
+        step_method = method(step_name)
+      rescue NameError
+        raise UndefinedMethodError.new(step_name)
+      end
 
       raise InvalidMethodError.new(step_name) unless step_method.arity.zero?
 
-      wrapper = step_definition["transactional"] ? @execution.method(:with_lock) : NO_OP_WRAPPER
+      plugin_pipeline_callable = @__acidic_job_plugins__.reverse.reduce(step_method) do |callable, plugin|
+        context = PluginContext.new(plugin, self, @__acidic_job_execution__, step_definition)
+
+        if context.inactive?
+          callable
+        else
+          proc do
+            called = false
+
+            result = plugin.around_step(context) do
+              raise DoublePluginCallError.new(plugin, step_name) if called
+
+              called = true
+              callable.call
+            end
+
+            raise MissingPluginCallError.new(plugin, step_name) unless called
+
+            result
+          end
+        end
+      end
 
-      catch(:repeat) { wrapper.call { step_method.call } }
-    rescue NameError
-      raise UndefinedMethodError.new(step_name)
+      catch(:repeat) { plugin_pipeline_callable.call }
     end
   end
 end

data/lib/acidic_job.rb

@@ -6,6 +6,8 @@ require_relative "acidic_job/errors"
 require_relative "acidic_job/builder"
 require_relative "acidic_job/context"
 require_relative "acidic_job/arguments"
+require_relative "acidic_job/plugin_context"
+require_relative "acidic_job/plugins/transactional_step"
 require_relative "acidic_job/log_subscriber"
 require_relative "acidic_job/workflow"
 
@@ -15,13 +17,13 @@ module AcidicJob
   extend self
 
   DEFAULT_LOGGER = ActiveSupport::Logger.new($stdout)
-  FINISHED_RECOVERY_POINT = "FINISHED"
+  FINISHED_RECOVERY_POINT = "__ACIDIC_JOB_WORKFLOW_FINISHED__"
 
   mattr_accessor :logger, default: DEFAULT_LOGGER
   mattr_accessor :connects_to
 
   def instrument(channel, **options, &block)
-    ActiveSupport::Notifications.instrument("#{channel}.acidic_job", **options, &block)
+    ActiveSupport::Notifications.instrument("#{channel}.acidic_job", **options.deep_symbolize_keys, &block)
   end
 
   ActiveSupport.run_load_hooks(:acidic_job, self)

data/lib/generators/acidic_job/templates/create_acidic_job_tables_migration.rb.erb

@@ -7,24 +7,25 @@ class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version
       t.datetime    :locked_at, 			null: true
       t.string      :recover_to, 	    null: true
       t.json        :definition, 			null: true,   default: "{}"
+
       t.timestamps
     end
 
     create_table :acidic_job_entries do |t|
       t.references :execution, null: false, foreign_key: { to_table: :acidic_job_executions }
-      t.string :step, null: false
-      t.string :action, null: false
-      t.datetime :timestamp, null: false
-      t.json :data
+      t.string     :step,      null: false
+      t.string     :action,    null: false
+      t.datetime   :timestamp, null: false
+      t.json       :data,      null: true,  default: "{}"
 
       t.timestamps
     end
-    add_index :acidic_job_entries, [:execution_id, :step]
+    add_index :acidic_job_entries, [:execution_id, :step, :action]
 
     create_table :acidic_job_values do |t|
       t.references :execution, null: false, foreign_key: { to_table: :acidic_job_executions }
-      t.string :key, null: false
-      t.json :value, null: false,   default: "{}"
+      t.string     :key,       null: false
+      t.json       :value,     null: false, default: "{}"
 
       t.timestamps
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: acidic_job
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc2
+  version: 1.0.0.rc3
 platform: ruby
 authors:
 - fractaledmind
 bindir: exe
 cert_chain: []
-date: 2025-05-14 00:00:00.000000000 Z
+date: 2025-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -260,6 +260,8 @@ files:
 - lib/acidic_job/engine.rb
 - lib/acidic_job/errors.rb
 - lib/acidic_job/log_subscriber.rb
+- lib/acidic_job/plugin_context.rb
+- lib/acidic_job/plugins/transactional_step.rb
 - lib/acidic_job/serializers/exception_serializer.rb
 - lib/acidic_job/serializers/job_serializer.rb
 - lib/acidic_job/serializers/new_record_serializer.rb