dexkit 0.1.0 → 0.2.0

data/lib/dex/event/processor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    # Lazy-loaded ActiveJob processor (same pattern as Operation::DirectJob)
+    def self.const_missing(name)
+      return super unless name == :Processor && defined?(ActiveJob::Base)
+
+      const_set(:Processor, Class.new(ActiveJob::Base) do
+        def perform(handler_class:, event_class:, payload:, metadata:, trace: nil, context: nil, attempt_number: 1)
+          restore_context(context)
+
+          handler = Object.const_get(handler_class)
+          retry_config = handler._event_handler_retry_config
+
+          Dex::Event::Trace.restore(trace) do
+            handler._event_handle_from_payload(event_class, payload, metadata)
+          end
+        rescue => _e
+          if retry_config && attempt_number <= retry_config[:count]
+            delay = compute_delay(retry_config, attempt_number)
+            self.class.set(wait: delay).perform_later(
+              handler_class: handler_class,
+              event_class: event_class,
+              payload: payload,
+              metadata: metadata,
+              trace: trace,
+              context: context,
+              attempt_number: attempt_number + 1
+            )
+          else
+            raise
+          end
+        end
+
+        private
+
+        def restore_context(context)
+          return unless context
+
+          restorer = Dex.configuration.restore_event_context
+          return unless restorer
+
+          restorer.call(context)
+        rescue => e
+          Dex::Event._warn("restore_event_context failed: #{e.message}")
+        end
+
+        def compute_delay(config, attempt)
+          wait = config[:wait]
+          case wait
+          when Numeric then wait
+          when Proc then wait.call(attempt)
+          else
+            2**(attempt - 1) # exponential backoff
+          end
+        end
+      end)
+    end
+  end
+end

data/lib/dex/event/suppression.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    module Suppression
+      SUPPRESSED_KEY = :_dex_event_suppressed
+
+      class << self
+        include ExecutionState
+
+        def suppress(*classes, &block)
+          previous = _suppressed_set
+          new_set = previous.dup
+          if classes.empty?
+            new_set << :all
+          else
+            classes.each do |klass|
+              Event.validate_event_class!(klass)
+              new_set << klass
+            end
+          end
+          _set_suppressed(new_set)
+          yield
+        ensure
+          _set_suppressed(previous)
+        end
+
+        def suppressed?(event_class)
+          set = _suppressed_set
+          set.include?(:all) || set.any? { |k| k != :all && event_class <= k }
+        end
+
+        def clear!
+          _execution_state[SUPPRESSED_KEY] = Set.new
+        end
+
+        private
+
+        def _suppressed_set
+          _execution_state[SUPPRESSED_KEY] ||= Set.new
+        end
+
+        def _set_suppressed(set)
+          _execution_state[SUPPRESSED_KEY] = set
+        end
+      end
+    end
+  end
+end

data/lib/dex/event/trace.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    module Trace
+      STACK_KEY = :_dex_event_trace_stack
+
+      class << self
+        include ExecutionState
+
+        def with_event(event, &block)
+          stack = _stack
+          stack.push(event.trace_frame)
+          yield
+        ensure
+          stack.pop
+        end
+
+        def current_event_id
+          _stack.last&.dig(:id)
+        end
+
+        def current_trace_id
+          _stack.last&.dig(:trace_id)
+        end
+
+        def dump
+          frame = _stack.last
+          return nil unless frame
+
+          { id: frame[:id], trace_id: frame[:trace_id] }
+        end
+
+        def restore(data, &block)
+          return yield unless data
+
+          stack = _stack
+          stack.push(data)
+          yield
+        ensure
+          stack.pop if data
+        end
+
+        def clear!
+          _execution_state[STACK_KEY] = []
+        end
+
+        private
+
+        def _stack
+          _execution_state[STACK_KEY] ||= []
+        end
+      end
+    end
+  end
+end

data/lib/dex/event.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "set"
+
+# Modules loaded before class body (no reference to Dex::Event needed)
+require_relative "event/execution_state"
+require_relative "event/metadata"
+require_relative "event/trace"
+require_relative "event/suppression"
+
+module Dex
+  class Event
+    RESERVED_PROP_NAMES = %i[
+      id timestamp trace_id caused_by_id caused_by
+      context publish metadata sync
+    ].to_set.freeze
+
+    include PropsSetup
+    include TypeCoercion
+
+    def self._warn(message)
+      Dex.warn("Event: #{message}")
+    end
+
+    def self.validate_event_class!(klass)
+      return if klass.is_a?(Class) && klass < Dex::Event
+
+      raise ArgumentError, "#{klass.inspect} is not a Dex::Event subclass"
+    end
+
+    # --- Instance ---
+
+    attr_reader :metadata
+
+    def after_initialize
+      @metadata = Metadata.build
+      freeze
+    end
+
+    # Metadata delegates
+    def id = metadata.id
+    def timestamp = metadata.timestamp
+    def trace_id = metadata.trace_id
+    def caused_by_id = metadata.caused_by_id
+    def context = metadata.context
+    def trace_frame = { id: id, trace_id: trace_id }
+
+    # Publishing
+    def publish(sync: false)
+      Bus.publish(self, sync: sync)
+    end
+
+    def self.publish(sync: false, caused_by: nil, **kwargs)
+      if caused_by
+        Trace.with_event(caused_by) do
+          new(**kwargs).publish(sync: sync)
+        end
+      else
+        new(**kwargs).publish(sync: sync)
+      end
+    end
+
+    # Tracing
+    def trace(&block)
+      Trace.with_event(self, &block)
+    end
+
+    # Suppression
+    def self.suppress(*classes, &block)
+      Suppression.suppress(*classes, &block)
+    end
+
+    # Serialization
+    def as_json
+      {
+        "type" => self.class.name,
+        "payload" => _props_as_json,
+        "metadata" => metadata.as_json
+      }
+    end
+  end
+end
+
+# Classes loaded after Event is defined (they reference Dex::Event)
+require_relative "event/bus"
+require_relative "event/handler"
+require_relative "event/processor"

data/lib/dex/event_test_helpers/assertions.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    module TestHelpers
+      def assert_event_published(event_class, msg: nil, **expected_props)
+        matching = _dex_find_published_events(event_class, expected_props)
+        assert matching.any?,
+          msg || _dex_event_published_failure_message(event_class, expected_props)
+      end
+
+      def refute_event_published(event_class = nil, msg: nil, **expected_props)
+        if event_class.nil?
+          assert _dex_published_events.empty?,
+            msg || "Expected no events published, but #{_dex_published_events.size} were:\n#{_dex_event_list}"
+        else
+          matching = _dex_find_published_events(event_class, expected_props)
+          assert matching.empty?,
+            msg || "Expected no #{event_class.name || event_class} events published, but found #{matching.size}"
+        end
+      end
+
+      def assert_event_count(event_class, count, msg: nil)
+        matching = _dex_find_published_events(event_class, {})
+        assert_equal count, matching.size,
+          msg || "Expected #{count} #{event_class.name || event_class} events, got #{matching.size}"
+      end
+
+      def assert_event_trace(parent, child, msg: nil)
+        assert_equal parent.id, child.caused_by_id,
+          msg || "Expected child event to be caused by parent (caused_by_id mismatch)"
+      end
+
+      def assert_same_trace(*events, msg: nil)
+        trace_ids = events.map(&:trace_id).uniq
+        assert_equal 1, trace_ids.size,
+          msg || "Expected all events to share the same trace_id, got: #{trace_ids.inspect}"
+      end
+
+      private
+
+      def _dex_find_published_events(event_class, expected_props)
+        _dex_published_events.select do |event|
+          next false unless event.is_a?(event_class)
+
+          expected_props.all? do |key, value|
+            event.respond_to?(key) && event.public_send(key) == value
+          end
+        end
+      end
+
+      def _dex_event_published_failure_message(event_class, expected_props)
+        name = event_class.name || event_class.to_s
+        if _dex_published_events.empty?
+          "Expected #{name} to be published, but no events were published"
+        else
+          msg = "Expected #{name} to be published"
+          msg += " with #{expected_props.inspect}" unless expected_props.empty?
+          msg + ", but only found:\n#{_dex_event_list}"
+        end
+      end
+
+      def _dex_event_list
+        _dex_published_events.map.with_index do |event, i|
+          "  #{i + 1}. #{event.class.name || event.class}"
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/dex/event_test_helpers.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    module EventTestWrapper
+      CAPTURING_KEY = :_dex_event_capturing
+      PUBLISHED_KEY = :_dex_event_published
+
+      @_installed = false
+
+      class << self
+        include ExecutionState
+
+        def install!
+          return if @_installed
+
+          Dex::Event::Bus.singleton_class.prepend(BusInterceptor)
+          @_installed = true
+        end
+
+        def installed?
+          @_installed
+        end
+
+        def capturing?
+          (_execution_state[CAPTURING_KEY] || 0) > 0
+        end
+
+        def begin_capture!
+          _execution_state[CAPTURING_KEY] = (_execution_state[CAPTURING_KEY] || 0) + 1
+        end
+
+        def end_capture!
+          depth = (_execution_state[CAPTURING_KEY] || 0) - 1
+          _execution_state[CAPTURING_KEY] = [depth, 0].max
+        end
+
+        def published_events
+          _execution_state[PUBLISHED_KEY] ||= []
+        end
+
+        def clear_published!
+          _execution_state[PUBLISHED_KEY] = []
+        end
+      end
+
+      module BusInterceptor
+        def publish(event, sync:)
+          if Dex::Event::EventTestWrapper.capturing?
+            return if Dex::Event::Suppression.suppressed?(event.class)
+
+            Dex::Event::EventTestWrapper.published_events << event
+          else
+            super(event, sync: true)
+          end
+        end
+      end
+    end
+
+    module TestHelpers
+      def self.included(base)
+        EventTestWrapper.install!
+      end
+
+      def setup
+        super
+        EventTestWrapper.clear_published!
+        Dex::Event::Trace.clear!
+        Dex::Event::Suppression.clear!
+      end
+
+      def capture_events
+        EventTestWrapper.begin_capture!
+        yield
+      ensure
+        EventTestWrapper.end_capture!
+      end
+
+      private
+
+      def _dex_published_events
+        EventTestWrapper.published_events
+      end
+    end
+  end
+end
+
+require_relative "event_test_helpers/assertions"

data/lib/dex/operation/async_proxy.rb

@@ -9,41 +9,41 @@ module Dex
       end
 
       def call
-        _async_ensure_active_job_loaded!
-        if _async_use_record_strategy?
-          _async_enqueue_record_job
+        ensure_active_job_loaded!
+        if use_record_strategy?
+          enqueue_record_job
         else
-          _async_enqueue_direct_job
+          enqueue_direct_job
         end
       end
 
       private
 
-      def _async_enqueue_direct_job
-        job = _async_apply_options(Operation::DirectJob)
-        job.perform_later(class_name: _async_operation_class_name, params: _async_serialized_params)
+      def enqueue_direct_job
+        job = apply_options(Operation::DirectJob)
+        job.perform_later(class_name: operation_class_name, params: serialized_params)
       end
 
-      def _async_enqueue_record_job
+      def enqueue_record_job
         record = Dex.record_backend.create_record(
-          name: _async_operation_class_name,
-          params: _async_serialized_params,
+          name: operation_class_name,
+          params: serialized_params,
           status: "pending"
         )
         begin
-          job = _async_apply_options(Operation::RecordJob)
-          job.perform_later(class_name: _async_operation_class_name, record_id: record.id)
+          job = apply_options(Operation::RecordJob)
+          job.perform_later(class_name: operation_class_name, record_id: record.id)
         rescue => e
           begin
             record.destroy
           rescue => destroy_error
-            _async_log_warning("Failed to clean up pending record #{record.id}: #{destroy_error.message}")
+            Dex.warn("Failed to clean up pending record #{record.id}: #{destroy_error.message}")
           end
           raise e
         end
       end
 
-      def _async_use_record_strategy?
+      def use_record_strategy?
         return false unless Dex.record_backend
         return false unless @operation.class.name
 
@@ -54,54 +54,48 @@ module Dex
         true
       end
 
-      def _async_apply_options(job_class)
+      def apply_options(job_class)
         options = {}
-        options[:queue] = _async_queue if _async_queue
-        options[:wait_until] = _async_scheduled_at if _async_scheduled_at
-        options[:wait] = _async_scheduled_in if _async_scheduled_in
+        options[:queue] = queue if queue
+        options[:wait_until] = scheduled_at if scheduled_at
+        options[:wait] = scheduled_in if scheduled_in
         options.empty? ? job_class : job_class.set(**options)
       end
 
-      def _async_ensure_active_job_loaded!
+      def ensure_active_job_loaded!
         return if defined?(ActiveJob::Base)
 
         raise LoadError, "ActiveJob is required for async operations. Add 'activejob' to your Gemfile."
       end
 
-      def _async_merged_options
+      def merged_options
         @operation.class.settings_for(:async).merge(@runtime_options)
       end
 
-      def _async_queue = _async_merged_options[:queue]
-      def _async_scheduled_at = _async_merged_options[:at]
-      def _async_scheduled_in = _async_merged_options[:in]
-      def _async_operation_class_name = @operation.class.name
+      def queue = merged_options[:queue]
+      def scheduled_at = merged_options[:at]
+      def scheduled_in = merged_options[:in]
+      def operation_class_name = @operation.class.name
 
-      def _async_serialized_params
-        @_async_serialized_params ||= begin
+      def serialized_params
+        @serialized_params ||= begin
           hash = @operation._props_as_json
-          _async_validate_serializable!(hash)
+          validate_serializable!(hash)
           hash
         end
       end
 
-      def _async_log_warning(message)
-        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-          Rails.logger.warn "[Dex] #{message}"
-        end
-      end
-
-      def _async_validate_serializable!(hash, path: "")
+      def validate_serializable!(hash, path: "")
         hash.each do |key, value|
           current = path.empty? ? key.to_s : "#{path}.#{key}"
           case value
           when String, Integer, Float, NilClass, TrueClass, FalseClass
             next
           when Hash
-            _async_validate_serializable!(value, path: current)
+            validate_serializable!(value, path: current)
           when Array
             value.each_with_index do |v, i|
-              _async_validate_serializable!({ i => v }, path: current)
+              validate_serializable!({ i => v }, path: current)
             end
           else
             raise ArgumentError,

data/lib/dex/operation/async_wrapper.rb

@@ -2,33 +2,17 @@
 
 module Dex
   module AsyncWrapper
-    ASYNC_KNOWN_OPTIONS = %i[queue in at].freeze
-
     module ClassMethods
       def async(**options)
-        unknown = options.keys - AsyncWrapper::ASYNC_KNOWN_OPTIONS
-        if unknown.any?
-          raise ArgumentError,
-            "unknown async option(s): #{unknown.map(&:inspect).join(", ")}. " \
-            "Known: #{AsyncWrapper::ASYNC_KNOWN_OPTIONS.map(&:inspect).join(", ")}"
-        end
-
+        validate_options!(options, %i[queue in at], :async)
         set(:async, **options)
       end
     end
 
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+    extend Dex::Concern
 
     def async(**options)
-      unknown = options.keys - AsyncWrapper::ASYNC_KNOWN_OPTIONS
-      if unknown.any?
-        raise ArgumentError,
-          "unknown async option(s): #{unknown.map(&:inspect).join(", ")}. " \
-          "Known: #{AsyncWrapper::ASYNC_KNOWN_OPTIONS.map(&:inspect).join(", ")}"
-      end
-
+      self.class.validate_options!(options, %i[queue in at], :async)
       Operation::AsyncProxy.new(self, **options)
     end
   end

data/lib/dex/operation/callback_wrapper.rb

@@ -2,9 +2,7 @@
 
 module Dex
   module CallbackWrapper
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+    extend Dex::Concern
 
     module ClassMethods
       def before(callable = nil, &block)
@@ -57,24 +55,22 @@ module Dex
     def _callback_wrap
       return yield unless self.class._callback_any?
 
-      halted = nil
+      success_halt = nil
       result = _callback_run_around(self.class._callback_list(:around)) do
         _callback_run_before
-        caught = catch(:_dex_halt) { yield }
-        if caught.is_a?(Operation::Halt)
-          if caught.success?
-            halted = caught
-            _callback_run_after
-            caught.value
-          else
-            throw(:_dex_halt, caught)
-          end
+        interceptor = Operation::HaltInterceptor.new { yield }
+        if interceptor.error?
+          interceptor.rethrow!
+        elsif interceptor.halted?
+          success_halt = interceptor
+          _callback_run_after
+          interceptor.result
         else
           _callback_run_after
-          caught
+          interceptor.result
         end
       end
-      throw(:_dex_halt, halted) if halted
+      success_halt&.rethrow!
       result
     end
 

data/lib/dex/operation/jobs.rb

@@ -11,7 +11,7 @@ module Dex
         const_set(:DirectJob, Class.new(ActiveJob::Base) do
           def perform(class_name:, params:)
             klass = class_name.constantize
-            klass.new(**klass.send(:_dex_coerce_serialized_hash, params)).call
+            klass.new(**klass.send(:_coerce_serialized_hash, params)).call
           end
         end)
       when :RecordJob
@@ -19,39 +19,33 @@ module Dex
           def perform(class_name:, record_id:)
             klass = class_name.constantize
             record = Dex.record_backend.find_record(record_id)
-            params = klass.send(:_dex_coerce_serialized_hash, record.params || {})
+            params = klass.send(:_coerce_serialized_hash, record.params || {})
 
             op = klass.new(**params)
             op.instance_variable_set(:@_dex_record_id, record_id)
 
-            _dex_update_status(record_id, status: "running")
+            update_status(record_id, status: "running")
             op.call
           rescue => e
-            _dex_handle_failure(record_id, e)
+            handle_failure(record_id, e)
             raise
           end
 
           private
 
-          def _dex_update_status(record_id, **attributes)
+          def update_status(record_id, **attributes)
             Dex.record_backend.update_record(record_id, attributes)
           rescue => e
-            _dex_log_warning("Failed to update record status: #{e.message}")
+            Dex.warn("Failed to update record status: #{e.message}")
           end
 
-          def _dex_handle_failure(record_id, exception)
+          def handle_failure(record_id, exception)
             error_value = if exception.is_a?(Dex::Error)
               exception.code.to_s
             else
               exception.class.name
             end
-            _dex_update_status(record_id, status: "failed", error: error_value)
-          end
-
-          def _dex_log_warning(message)
-            if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-              Rails.logger.warn "[Dex] #{message}"
-            end
+            update_status(record_id, status: "failed", error: error_value)
           end
         end)
       when :Job