dexkit 0.1.0 → 0.3.0

data/lib/dex/event/handler.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    class Handler
+      attr_reader :event
+
+      def self.on(*event_classes)
+        event_classes.each do |ec|
+          Event.validate_event_class!(ec)
+          Bus.subscribe(ec, self)
+        end
+      end
+
+      def self.retries(count, **opts)
+        raise ArgumentError, "retries count must be a positive Integer" unless count.is_a?(Integer) && count > 0
+
+        if opts.key?(:wait)
+          wait = opts[:wait]
+          unless wait.is_a?(Numeric) || wait.is_a?(Proc)
+            raise ArgumentError, "wait: must be Numeric or Proc"
+          end
+        end
+
+        @_event_handler_retries = { count: count, **opts }
+      end
+
+      def self._event_handler_retry_config
+        if defined?(@_event_handler_retries)
+          @_event_handler_retries
+        elsif superclass.respond_to?(:_event_handler_retry_config)
+          superclass._event_handler_retry_config
+        end
+      end
+
+      def self._event_handle(event)
+        instance = new
+        instance.instance_variable_set(:@event, event)
+        instance.perform
+      end
+
+      def self._event_handle_from_payload(event_class_name, payload, metadata_hash)
+        event_class = Object.const_get(event_class_name)
+        event = _event_reconstruct(event_class, payload, metadata_hash)
+        _event_handle(event)
+      end
+
+      class << self
+        private
+
+        def _event_reconstruct(event_class, payload, metadata_hash)
+          coerced = event_class.send(:_coerce_serialized_hash, payload)
+          instance = event_class.allocate
+
+          event_class.literal_properties.each do |prop|
+            instance.instance_variable_set(:"@#{prop.name}", coerced[prop.name])
+          end
+
+          metadata = Event::Metadata.new(
+            id: metadata_hash["id"],
+            timestamp: Time.parse(metadata_hash["timestamp"]),
+            trace_id: metadata_hash["trace_id"],
+            caused_by_id: metadata_hash["caused_by_id"],
+            context: metadata_hash["context"]
+          )
+          instance.instance_variable_set(:@metadata, metadata)
+          instance.freeze
+          instance
+        end
+      end
+
+      def perform
+        raise NotImplementedError, "#{self.class.name} must implement #perform"
+      end
+    end
+  end
+end

data/lib/dex/event/metadata.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Dex
+  class Event
+    class Metadata
+      attr_reader :id, :timestamp, :trace_id, :caused_by_id, :context
+
+      def initialize(id:, timestamp:, trace_id:, caused_by_id:, context:)
+        @id = id
+        @timestamp = timestamp
+        @trace_id = trace_id
+        @caused_by_id = caused_by_id
+        @context = context
+        freeze
+      end
+
+      def self.build(caused_by_id: nil)
+        id = SecureRandom.uuid
+        trace_id = Trace.current_trace_id || id
+        caused = caused_by_id || Trace.current_event_id
+
+        ctx = if Dex.configuration.event_context
+          begin
+            Dex.configuration.event_context.call
+          rescue => e
+            Event._warn("event_context failed: #{e.message}")
+            nil
+          end
+        end
+
+        new(
+          id: id,
+          timestamp: Time.now.utc,
+          trace_id: trace_id,
+          caused_by_id: caused,
+          context: ctx
+        )
+      end
+
+      def as_json
+        h = {
+          "id" => @id,
+          "timestamp" => @timestamp.iso8601(6),
+          "trace_id" => @trace_id
+        }
+        h["caused_by_id"] = @caused_by_id if @caused_by_id
+        h["context"] = @context if @context
+        h
+      end
+    end
+  end
+end

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"