dexkit 0.8.0 → 0.10.0

data/lib/dex/context_dsl.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Dex
+  # Shared context DSL extracted from ContextSetup.
+  #
+  # Provides the `context` class method, `context_mappings` inheritance,
+  # and `_context_own` storage.  Includers must implement:
+  #   _context_prop_declared?(name) → true/false
+  # and may override:
+  #   _context_field_label → "prop" | "field" (used in error messages)
+  module ContextDSL
+    def context(*names, **mappings)
+      names.each do |name|
+        unless name.is_a?(Symbol)
+          raise ArgumentError, "context shorthand must be a Symbol, got: #{name.inspect}"
+        end
+        mappings[name] = name
+      end
+
+      raise ArgumentError, "context requires at least one mapping" if mappings.empty?
+
+      label = _context_field_label
+      mappings.each do |prop_name, context_key|
+        unless _context_prop_declared?(prop_name)
+          raise ArgumentError,
+            "context references undeclared #{label} :#{prop_name}. Declare the #{label} before calling context."
+        end
+        unless context_key.is_a?(Symbol)
+          raise ArgumentError,
+            "context key must be a Symbol, got: #{context_key.inspect} for #{label} :#{prop_name}"
+        end
+      end
+
+      _context_own.merge!(mappings)
+    end
+
+    def context_mappings
+      parent = superclass.respond_to?(:context_mappings) ? superclass.context_mappings : {}
+      parent.merge(_context_own)
+    end
+
+    private
+
+    def _context_own
+      @_context_own_mappings ||= {}
+    end
+
+    def _context_prop_declared?(_name)
+      raise NotImplementedError, "#{self} must implement _context_prop_declared?"
+    end
+
+    def _context_field_label
+      "prop"
+    end
+  end
+end

data/lib/dex/context_setup.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Dex
-  # Shared context DSL for Operation and Event.
+  # Context DSL for Operation and Event (Literal::Properties-backed).
   #
   # Maps declared props to ambient context keys so they can be auto-filled
   # from Dex.context when not passed explicitly as kwargs.
@@ -9,34 +9,7 @@ module Dex
     extend Dex::Concern
 
     module ClassMethods
-      def context(*names, **mappings)
-        names.each do |name|
-          unless name.is_a?(Symbol)
-            raise ArgumentError, "context shorthand must be a Symbol, got: #{name.inspect}"
-          end
-          mappings[name] = name
-        end
-
-        raise ArgumentError, "context requires at least one mapping" if mappings.empty?
-
-        mappings.each do |prop_name, context_key|
-          unless _context_prop_declared?(prop_name)
-            raise ArgumentError,
-              "context references undeclared prop :#{prop_name}. Declare the prop before calling context."
-          end
-          unless context_key.is_a?(Symbol)
-            raise ArgumentError,
-              "context key must be a Symbol, got: #{context_key.inspect} for prop :#{prop_name}"
-          end
-        end
-
-        _context_own.merge!(mappings)
-      end
-
-      def context_mappings
-        parent = superclass.respond_to?(:context_mappings) ? superclass.context_mappings : {}
-        parent.merge(_context_own)
-      end
+      include ContextDSL
 
       def new(**kwargs)
         mappings = context_mappings
@@ -52,10 +25,6 @@ module Dex
 
       private
 
-      def _context_own
-        @_context_own_mappings ||= {}
-      end
-
       def _context_prop_declared?(name)
         respond_to?(:literal_properties) && literal_properties.any? { |p| p.name == name }
       end

data/lib/dex/event/bus.rb

@@ -44,19 +44,18 @@ module Dex
         def publish(event, sync:)
           return if Suppression.suppressed?(event.class)
 
-          persist(event)
+          trace_data = trace_data_for(event)
+          persist(event, trace_data)
           handlers = subscribers_for(event.class)
           return if handlers.empty?
 
-          event_frame = event.trace_frame
-
           handlers.each do |handler_class|
             if sync
-              Trace.restore(event_frame) do
+              Dex::Trace.restore(trace_data) do
                 handler_class._event_handle(event)
               end
             else
-              enqueue(handler_class, event, event_frame)
+              enqueue(handler_class, event, trace_data)
             end
           end
         end
@@ -67,20 +66,29 @@ module Dex
 
         private
 
-        def persist(event)
+        def persist(event, trace_data)
           store = Dex.configuration.event_store
           return unless store
 
-          store.create!(
+          actor = actor_from_trace(trace_data[:frames])
+          attrs = safe_store_attributes(store, {
+            id: event.id,
+            trace_id: event.trace_id,
+            actor_type: actor&.dig(:actor_type),
+            actor_id: actor&.dig(:id),
+            trace: trace_data[:frames],
             event_type: event.class.name,
             payload: event._props_as_json,
             metadata: event.metadata.as_json
-          )
+          })
+
+          store.create!(**attrs)
         rescue => e
           Event._warn("Failed to persist event: #{e.message}")
         end
 
         def enqueue(handler_class, event, trace_data)
+          ensure_active_job_loaded!
           ctx = event.context
 
           Dex::Event::Processor.perform_later(
@@ -92,6 +100,75 @@ module Dex
             context: ctx
           )
         end
+
+        def trace_data_for(event)
+          ambient = Dex::Trace.dump
+          frames = if ambient && trace_matches_event?(ambient, event)
+            trace_frames(ambient)
+          elsif ambient
+            actor_frames(trace_frames(ambient))
+          else
+            []
+          end
+
+          {
+            trace_id: event.trace_id,
+            frames: frames,
+            event_context: event_context_for(event)
+          }
+        end
+
+        def actor_from_trace(frames)
+          Array(frames).find do |frame|
+            frame_type = frame[:type] || frame["type"]
+            frame_type && frame_type.to_sym == :actor
+          end
+        end
+
+        def actor_frames(frames)
+          Array(frames).select do |frame|
+            frame_type = frame[:type] || frame["type"]
+            frame_type && frame_type.to_sym == :actor
+          end
+        end
+
+        def trace_frames(trace_data)
+          Array(trace_data[:frames] || trace_data["frames"])
+        end
+
+        def trace_matches_event?(trace_data, event)
+          trace_id = trace_data[:trace_id] || trace_data["trace_id"]
+          trace_id.to_s == event.trace_id.to_s
+        end
+
+        def event_context_for(event)
+          {
+            id: event.id,
+            trace_id: event.trace_id,
+            event_class: event.class.name,
+            event_ancestry: event.event_ancestry
+          }
+        end
+
+        def safe_store_attributes(store, attributes)
+          if store.respond_to?(:column_names)
+            allowed = store.column_names.to_set
+            attributes.select { |key, _| allowed.include?(key.to_s) }
+          elsif store.respond_to?(:fields)
+            attributes.select do |key, _|
+              field_name = key.to_s
+              store.fields.key?(field_name) || (field_name == "id" && store.fields.key?("_id"))
+            end
+          else
+            attributes
+          end
+        end
+
+        def ensure_active_job_loaded!
+          return if defined?(ActiveJob::Base)
+
+          raise LoadError, "ActiveJob is required for async event handlers. Add 'activejob' to your Gemfile."
+        end
       end
     end
   end

data/lib/dex/event/handler.rb

@@ -69,9 +69,26 @@ module Dex
       end
 
       def self._event_handle(event)
+        execution_id = Dex::Id.generate("hd_")
+        auto_started = Dex::Trace.ensure_started!(trace_id: event.trace_id)
+        pushed = false
+        Dex::Trace.push(
+          type: :handler,
+          id: execution_id,
+          class: name,
+          event_class: event.class.name,
+          event_id: event.id,
+          event_ancestry: event.metadata.event_ancestry
+        )
+        pushed = true
+
         instance = new
         instance.instance_variable_set(:@event, event)
+        instance.instance_variable_set(:@_dex_execution_id, execution_id)
         instance.send(:call)
+      ensure
+        Dex::Trace.pop if pushed
+        Dex::Trace.stop! if auto_started
       end
 
       def self._event_handle_from_payload(event_class_name, payload, metadata_hash)
@@ -96,6 +113,7 @@ module Dex
             timestamp: Time.parse(metadata_hash["timestamp"]),
             trace_id: metadata_hash["trace_id"],
             caused_by_id: metadata_hash["caused_by_id"],
+            event_ancestry: metadata_hash["event_ancestry"] || [],
             context: metadata_hash["context"]
           )
           instance.instance_variable_set(:@metadata, metadata)

data/lib/dex/event/metadata.rb

@@ -1,25 +1,30 @@
 # frozen_string_literal: true
 
-require "securerandom"
-
 module Dex
   class Event
     class Metadata
-      attr_reader :id, :timestamp, :trace_id, :caused_by_id, :context
+      attr_reader :id, :timestamp, :trace_id, :caused_by_id, :event_ancestry, :context
 
-      def initialize(id:, timestamp:, trace_id:, caused_by_id:, context:)
+      def initialize(id:, timestamp:, trace_id:, caused_by_id:, event_ancestry:, context:)
         @id = id
         @timestamp = timestamp
         @trace_id = trace_id
         @caused_by_id = caused_by_id
+        @event_ancestry = event_ancestry
         @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
+      def self.build
+        id = Dex::Id.generate("ev_")
+        trace_id = Dex::Trace.trace_id || Dex::Id.generate("tr_")
+        current_event = Dex::Trace.current_event_context
+        caused = current_event&.dig(:id)
+        ancestry = if current_event
+          Array(current_event[:event_ancestry]) + [caused].compact
+        else
+          []
+        end
 
         ctx = if Dex.configuration.event_context
           begin
@@ -35,6 +40,7 @@ module Dex
           timestamp: Time.now.utc,
           trace_id: trace_id,
           caused_by_id: caused,
+          event_ancestry: ancestry,
           context: ctx
         )
       end
@@ -43,7 +49,8 @@ module Dex
         h = {
           "id" => @id,
           "timestamp" => @timestamp.iso8601(6),
-          "trace_id" => @trace_id
+          "trace_id" => @trace_id,
+          "event_ancestry" => @event_ancestry
         }
         h["caused_by_id"] = @caused_by_id if @caused_by_id
         h["context"] = @context if @context

data/lib/dex/event/processor.rb

@@ -13,7 +13,7 @@ module Dex
           handler = Object.const_get(handler_class)
           retry_config = handler._event_handler_retry_config
 
-          Dex::Event::Trace.restore(trace) do
+          Dex::Trace.restore(trace) do
             handler._event_handle_from_payload(event_class, payload, metadata)
           end
         rescue => _e

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::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 "test_helpers/assertions"

data/lib/dex/event/trace.rb

@@ -3,52 +3,39 @@
 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
+          Dex::Trace.with_event_context(event, &block)
         end
 
         def current_event_id
-          _stack.last&.dig(:id)
+          Dex::Trace.current_event_id
         end
 
         def current_trace_id
-          _stack.last&.dig(:trace_id)
+          Dex::Trace.trace_id
         end
 
         def dump
-          frame = _stack.last
-          return nil unless frame
-
-          { id: frame[:id], trace_id: frame[:trace_id] }
+          Dex::Trace.dump
         end
 
         def restore(data, &block)
           return yield unless data
 
-          stack = _stack
-          stack.push(data)
-          yield
-        ensure
-          stack.pop if data
+          if data.is_a?(Hash) && (data.key?(:frames) || data.key?("frames"))
+            Dex::Trace.restore(data, &block)
+          else
+            Dex::Trace.restore_event_context(
+              event_id: data[:id] || data["id"],
+              trace_id: data[:trace_id] || data["trace_id"],
+              &block
+            )
+          end
         end
 
         def clear!
-          _execution_state[STACK_KEY] = []
-        end
-
-        private
-
-        def _stack
-          _execution_state[STACK_KEY] ||= []
+          Dex::Trace.clear!
         end
       end
     end

data/lib/dex/event.rb

@@ -9,7 +9,7 @@ require_relative "event/suppression"
 module Dex
   class Event
     RESERVED_PROP_NAMES = %i[
-      id timestamp trace_id caused_by_id caused_by
+      id timestamp trace_id caused_by_id caused_by event_ancestry
       context publish metadata sync
     ].to_set.freeze
 
@@ -67,8 +67,8 @@ module Dex
     def timestamp = metadata.timestamp
     def trace_id = metadata.trace_id
     def caused_by_id = metadata.caused_by_id
+    def event_ancestry = metadata.event_ancestry
     def context = metadata.context
-    def trace_frame = { id: id, trace_id: trace_id }
 
     # Publishing
     def publish(sync: false)
@@ -85,11 +85,6 @@ module Dex
       end
     end
 
-    # Tracing
-    def trace(&block)
-      Trace.with_event(self, &block)
-    end
-
     # Suppression
     def self.suppress(*classes, &block)
       Suppression.suppress(*classes, &block)

data/lib/dex/event_test_helpers.rb

@@ -1,88 +1,3 @@
 # 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"
+require_relative "event/test_helpers"

data/lib/dex/form/context.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Dex
+  class Form
+    # Context DSL for Form (ActiveModel::Attributes-backed).
+    #
+    # Same DSL as Operation/Event context, but checks attribute_names
+    # instead of literal_properties. Injection happens in Form#initialize.
+    module Context
+      extend Dex::Concern
+
+      module ClassMethods
+        include ContextDSL
+
+        private
+
+        def _context_prop_declared?(name)
+          attribute_names.include?(name.to_s)
+        end
+
+        def _context_field_label
+          "field"
+        end
+      end
+    end
+  end
+end