dexkit 0.5.0 → 0.7.0

data/lib/dex/context_setup.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dex
+  # Shared context DSL for Operation and Event.
+  #
+  # Maps declared props to ambient context keys so they can be auto-filled
+  # from Dex.context when not passed explicitly as kwargs.
+  module ContextSetup
+    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
+
+      def new(**kwargs)
+        mappings = context_mappings
+        unless mappings.empty?
+          ambient = Dex.context
+          mappings.each do |prop_name, context_key|
+            next if kwargs.key?(prop_name)
+            kwargs[prop_name] = ambient[context_key] if ambient.key?(context_key)
+          end
+        end
+        super
+      end
+
+      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
+    end
+  end
+end

data/lib/dex/event/handler.rb

@@ -3,6 +3,8 @@
 module Dex
   class Event
     class Handler
+      include Dex::Executable
+
       attr_reader :event
 
       def self.on(*event_classes)
@@ -36,7 +38,7 @@ module Dex
       def self._event_handle(event)
         instance = new
         instance.instance_variable_set(:@event, event)
-        instance.perform
+        instance.send(:call)
       end
 
       def self._event_handle_from_payload(event_class_name, payload, metadata_hash)
@@ -69,6 +71,23 @@ module Dex
         end
       end
 
+      use TransactionWrapper
+      use CallbackWrapper
+
+      transaction false
+      private :call
+
+      # Guard must be defined after `include Executable` (which defines #call).
+      def self.method_added(method_name)
+        super
+
+        if method_name == :call
+          raise ArgumentError, "#{name || "Handler"} must not define #call — define #perform instead"
+        end
+
+        private :perform if method_name == :perform
+      end
+
       def perform
         raise NotImplementedError, "#{self.class.name} must implement #perform"
       end

data/lib/dex/event.rb

@@ -1,7 +1,5 @@
 # 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"
@@ -17,6 +15,7 @@ module Dex
 
     include PropsSetup
     include TypeCoercion
+    include ContextSetup
 
     def self._warn(message)
       Dex.warn("Event: #{message}")

data/lib/dex/executable.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Dex
+  module Executable
+    def self.included(base)
+      base.include(Dex::Settings)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def inherited(subclass)
+        subclass.instance_variable_set(:@_pipeline, pipeline.dup)
+        super
+      end
+
+      def pipeline
+        @_pipeline ||= Pipeline.new
+      end
+
+      def use(mod, as: nil, wrap: nil, before: nil, after: nil, at: nil)
+        step_name = as || _derive_step_name(mod)
+        wrap_method = wrap || :"_#{step_name}_wrap"
+        pipeline.add(step_name, method: wrap_method, before: before, after: after, at: at)
+        include mod
+      end
+
+      private
+
+      def _derive_step_name(mod)
+        base = mod.name&.split("::")&.last
+        raise ArgumentError, "anonymous modules require explicit as: parameter" unless base
+
+        base.sub(/Wrapper\z/, "")
+          .gsub(/([a-z])([A-Z])/, '\1_\2')
+          .downcase
+          .to_sym
+      end
+    end
+
+    def call
+      self.class.pipeline.execute(self) { perform }
+    end
+  end
+end

data/lib/dex/operation/async_proxy.rb

@@ -21,7 +21,9 @@ module Dex
 
       def enqueue_direct_job
         job = apply_options(Operation::DirectJob)
-        job.perform_later(class_name: operation_class_name, params: serialized_params)
+        payload = { class_name: operation_class_name, params: serialized_params }
+        apply_once_payload!(payload)
+        job.perform_later(**payload)
       end
 
       def enqueue_record_job
@@ -32,7 +34,9 @@ module Dex
         )
         begin
           job = apply_options(Operation::RecordJob)
-          job.perform_later(class_name: operation_class_name, record_id: record.id.to_s)
+          payload = { class_name: operation_class_name, record_id: record.id.to_s }
+          apply_once_payload!(payload)
+          job.perform_later(**payload)
         rescue => e
           begin
             record.destroy
@@ -68,6 +72,18 @@ module Dex
         raise LoadError, "ActiveJob is required for async operations. Add 'activejob' to your Gemfile."
       end
 
+      def apply_once_payload!(payload)
+        return unless @operation.instance_variable_defined?(:@_once_key_explicit) &&
+          @operation.instance_variable_get(:@_once_key_explicit)
+
+        once_key = @operation.instance_variable_get(:@_once_key)
+        if once_key
+          payload[:once_key] = once_key
+        else
+          payload[:once_bypass] = true
+        end
+      end
+
       def merged_options
         @operation.class.settings_for(:async).merge(@runtime_options)
       end

data/lib/dex/operation/guard_wrapper.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Dex
+  module GuardWrapper
+    extend Dex::Concern
+
+    GuardDefinition = Data.define(:name, :message, :requires, :block)
+
+    module ClassMethods
+      def guard(code, message = nil, requires: nil, &block)
+        raise ArgumentError, "guard code must be a Symbol, got: #{code.inspect}" unless code.is_a?(Symbol)
+        raise ArgumentError, "guard requires a block" unless block
+
+        requires = _guard_normalize_requires!(code, requires)
+        _guard_validate_unique!(code)
+
+        _guard_own << GuardDefinition.new(name: code, message: message, requires: requires, block: block)
+
+        error(code) if respond_to?(:error)
+      end
+
+      def _guard_list
+        parent = superclass.respond_to?(:_guard_list) ? superclass._guard_list : []
+        parent + _guard_own
+      end
+
+      def callable(**kwargs)
+        instance = new(**kwargs)
+        failures = instance.send(:_guard_evaluate)
+        if failures.empty?
+          Operation::Ok.new(nil)
+        else
+          first = failures.first
+          error = Dex::Error.new(first[:guard], first[:message], details: failures)
+          Operation::Err.new(error)
+        end
+      end
+
+      def callable?(*args, **kwargs)
+        if args.size > 1
+          raise ArgumentError, "callable? accepts at most one guard name, got #{args.size} arguments"
+        end
+
+        if args.first
+          guard_name = args.first
+          unless guard_name.is_a?(Symbol)
+            raise ArgumentError, "guard name must be a Symbol, got: #{guard_name.inspect}"
+          end
+          unless _guard_list.any? { |g| g.name == guard_name }
+            raise ArgumentError, "unknown guard :#{guard_name}. Declared: #{_guard_list.map(&:name).map(&:inspect).join(", ")}"
+          end
+          instance = new(**kwargs)
+          failures = instance.send(:_guard_evaluate)
+          failures.none? { |f| f[:guard] == guard_name }
+        else
+          callable(**kwargs).ok?
+        end
+      end
+
+      private
+
+      def _guard_own
+        @_guards ||= []
+      end
+
+      def _guard_normalize_requires!(code, requires)
+        return [] if requires.nil?
+
+        deps = Array(requires)
+        invalid = deps.reject { |d| d.is_a?(Symbol) }
+        if invalid.any?
+          raise ArgumentError,
+            "guard :#{code} requires: must be Symbol(s), got: #{invalid.map(&:inspect).join(", ")}"
+        end
+
+        all_names = _guard_list.map(&:name)
+        deps.each do |dep|
+          unless all_names.include?(dep)
+            raise ArgumentError,
+              "guard :#{code} requires :#{dep}, but no guard with that name has been declared"
+          end
+        end
+
+        deps.freeze
+      end
+
+      def _guard_validate_unique!(code)
+        all_names = _guard_list.map(&:name)
+        if all_names.include?(code)
+          raise ArgumentError, "duplicate guard name :#{code}"
+        end
+      end
+    end
+
+    def _guard_wrap
+      guards = self.class._guard_list
+      return yield if guards.empty?
+
+      failures = _guard_evaluate
+      unless failures.empty?
+        first = failures.first
+        error!(first[:guard], first[:message], details: failures)
+      end
+
+      yield
+    end
+
+    private
+
+    def _guard_evaluate
+      guards = self.class._guard_list
+      return [] if guards.empty?
+
+      blocked_names = Set.new
+      failures = []
+
+      guards.each do |guard|
+        if guard.requires.any? { |dep| blocked_names.include?(dep) }
+          blocked_names << guard.name
+          next
+        end
+
+        threat = catch(:_dex_halt) { instance_exec(&guard.block) }
+        if threat.is_a?(Operation::Halt)
+          raise ArgumentError,
+            "guard :#{guard.name} must return truthy/falsy, not call error!/success!/assert!"
+        end
+
+        if threat
+          blocked_names << guard.name
+          failures << { guard: guard.name, message: guard.message || guard.name.to_s }
+        end
+      end
+
+      failures
+    end
+  end
+end

data/lib/dex/operation/jobs.rb

@@ -9,25 +9,33 @@ module Dex
       case name
       when :DirectJob
         const_set(:DirectJob, Class.new(ActiveJob::Base) do
-          def perform(class_name:, params:)
+          def perform(class_name:, params:, once_key: nil, once_bypass: false)
             klass = class_name.constantize
-            klass.new(**klass.send(:_coerce_serialized_hash, params)).call
+            op = klass.new(**klass.send(:_coerce_serialized_hash, params))
+            op.once(once_key) if once_key
+            op.once(nil) if once_bypass
+            op.call
           end
         end)
       when :RecordJob
         const_set(:RecordJob, Class.new(ActiveJob::Base) do
-          def perform(class_name:, record_id:)
+          def perform(class_name:, record_id:, once_key: nil, once_bypass: false)
             klass = class_name.constantize
             record = Dex.record_backend.find_record(record_id)
             params = klass.send(:_coerce_serialized_hash, record.params || {})
 
             op = klass.new(**params)
             op.instance_variable_set(:@_dex_record_id, record_id)
+            op.once(once_key) if once_key
+            op.once(nil) if once_bypass
 
             update_status(record_id, status: "running")
+            pipeline_started = true
             op.call
           rescue => e
-            handle_failure(record_id, e)
+            # RecordWrapper handles failures during op.call via its own rescue.
+            # This catches pre-pipeline failures (find_record, deserialization, etc.)
+            mark_failed(record_id, e) unless pipeline_started
             raise
           end
 
@@ -39,13 +47,12 @@ module Dex
             Dex.warn("Failed to update record status: #{e.message}")
           end
 
-          def handle_failure(record_id, exception)
-            error_value = if exception.is_a?(Dex::Error)
-              exception.code.to_s
-            else
-              exception.class.name
-            end
-            update_status(record_id, status: "failed", error: error_value)
+          def mark_failed(record_id, exception)
+            update_status(record_id,
+              status: "failed",
+              error_code: exception.class.name,
+              error_message: exception.message,
+              performed_at: Time.respond_to?(:current) ? Time.current : Time.now)
           end
         end)
       when :Job

data/lib/dex/operation/once_wrapper.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Dex
+  module OnceWrapper
+    extend Dex::Concern
+
+    module ClassMethods
+      def once(*props, expires_in: nil, &block)
+        if settings_for(:once)[:defined]
+          raise ArgumentError, "once can only be declared once per operation"
+        end
+
+        record_settings = settings_for(:record)
+        if record_settings[:enabled] == false
+          raise ArgumentError, "once requires record to be enabled"
+        end
+
+        if record_settings[:result] == false
+          raise ArgumentError, "once requires result recording (cannot use record result: false)"
+        end
+
+        if block && props.any?
+          raise ArgumentError, "once accepts either prop names or a block, not both"
+        end
+
+        if expires_in && !expires_in.is_a?(Numeric)
+          raise ArgumentError, "once :expires_in must be a duration, got: #{expires_in.inspect}"
+        end
+
+        _once_validate_props!(props) if props.any?
+
+        set(:once,
+          defined: true,
+          props: props.any? ? props : nil,
+          block: block || nil,
+          expires_in: expires_in)
+      end
+
+      def clear_once!(key = nil, **props)
+        derived = if key.is_a?(String)
+          key
+        elsif props.any?
+          _once_build_scoped_key(props)
+        else
+          raise ArgumentError, "pass a String key or keyword arguments matching the once props"
+        end
+        Dex.record_backend.update_record_by_once_key(derived, once_key: nil)
+      end
+
+      def _once_build_scoped_key(props_hash)
+        segments = props_hash.sort_by { |k, _| k.to_s }.map do |k, v|
+          "#{k}=#{URI.encode_www_form_component(v.to_s)}"
+        end
+        "#{name}/#{segments.join("/")}"
+      end
+
+      private
+
+      def _once_validate_props!(prop_names)
+        return unless respond_to?(:literal_properties)
+
+        defined_names = literal_properties.map(&:name).to_set
+        unknown = prop_names.reject { |p| defined_names.include?(p) }
+        return if unknown.empty?
+
+        raise ArgumentError,
+          "once references unknown prop(s): #{unknown.map(&:inspect).join(", ")}. " \
+          "Defined: #{defined_names.map(&:inspect).join(", ")}"
+      end
+    end
+
+    def once(key)
+      @_once_key = key
+      @_once_key_explicit = true
+      self
+    end
+
+    def _once_wrap
+      return yield unless _once_active?
+
+      key = _once_derive_key
+      return yield if key.nil? && _once_key_explicit?
+
+      _once_ensure_backend!
+
+      raise "once key must not be nil" if key.nil?
+
+      expires_in = self.class.settings_for(:once)[:expires_in]
+      expires_at = expires_in ? _once_current_time + expires_in : nil
+
+      existing = Dex.record_backend.find_by_once_key(key)
+      if existing
+        _once_finalize_duplicate!(existing)
+        return _once_replay!(existing)
+      end
+
+      expired = Dex.record_backend.find_expired_once_key(key)
+      Dex.record_backend.update_record(expired.id.to_s, once_key: nil) if expired
+
+      _once_claim!(key, expires_at) { yield }
+    end
+
+    private
+
+    def _once_key_explicit?
+      defined?(@_once_key_explicit) && @_once_key_explicit
+    end
+
+    def _once_active?
+      return true if _once_key_explicit?
+      self.class.settings_for(:once).fetch(:defined, false)
+    end
+
+    def _once_ensure_backend!
+      unless Dex.record_backend
+        raise "once requires a record backend (configure Dex.record_class)"
+      end
+
+      return if self.class.instance_variable_defined?(:@_once_fields_checked)
+
+      unless Dex.record_backend.has_field?("once_key")
+        raise "once requires once_key column on #{Dex.record_class}. Run the migration to add it."
+      end
+
+      if self.class.settings_for(:once)[:expires_in] && !Dex.record_backend.has_field?("once_key_expires_at")
+        raise "once with expires_in requires once_key_expires_at column on #{Dex.record_class}. Run the migration to add it."
+      end
+
+      self.class.instance_variable_set(:@_once_fields_checked, true)
+    end
+
+    def _once_derive_key
+      return @_once_key if _once_key_explicit?
+
+      settings = self.class.settings_for(:once)
+
+      if settings[:block]
+        instance_exec(&settings[:block])
+      elsif settings[:props]
+        props_hash = settings[:props].each_with_object({}) { |p, h| h[p] = public_send(p) }
+        self.class._once_build_scoped_key(props_hash)
+      else
+        hash = {}
+        if self.class.respond_to?(:literal_properties)
+          self.class.literal_properties.each { |p| hash[p.name] = public_send(p.name) }
+        end
+        self.class._once_build_scoped_key(hash)
+      end
+    end
+
+    def _once_claim!(key, expires_at)
+      begin
+        _once_acquire_key!(key, expires_at)
+      rescue => e
+        if Dex.record_backend.unique_constraint_error?(e)
+          existing = Dex.record_backend.find_by_once_key(key)
+          if existing
+            _once_finalize_duplicate!(existing)
+            return _once_replay!(existing)
+          end
+
+          raise "once key #{key.inspect} is claimed by another in-flight execution"
+        end
+        raise
+      end
+      yield
+    end
+
+    def _once_acquire_key!(key, expires_at)
+      if _once_has_pending_record?
+        Dex.record_backend.update_record(@_dex_record_id,
+          once_key: key, once_key_expires_at: expires_at)
+      else
+        record = Dex.record_backend.create_record(
+          name: self.class.name,
+          once_key: key,
+          once_key_expires_at: expires_at,
+          status: "pending"
+        )
+        @_dex_record_id = record.id.to_s
+      end
+    end
+
+    def _once_has_pending_record?
+      defined?(@_dex_record_id) && @_dex_record_id
+    end
+
+    def _once_finalize_duplicate!(source_record)
+      return unless _once_has_pending_record?
+
+      attrs = { performed_at: _once_current_time }
+      if source_record.status == "error"
+        attrs[:status] = "error"
+        attrs[:error_code] = source_record.error_code
+        attrs[:error_message] = source_record.error_message
+        attrs[:error_details] = source_record.respond_to?(:error_details) ? source_record.error_details : nil
+      else
+        attrs[:status] = "completed"
+        attrs[:result] = source_record.respond_to?(:result) ? source_record.result : nil
+      end
+      Dex.record_backend.update_record(@_dex_record_id, attrs)
+    rescue => e
+      Dex.warn("Failed to finalize replayed record: #{e.message}")
+    end
+
+    def _once_replay!(record)
+      case record.status
+      when "completed"
+        _once_replay_success(record)
+      when "error"
+        _once_replay_error(record)
+      end
+    end
+
+    def _once_replay_success(record)
+      stored = record.respond_to?(:result) ? record.result : nil
+      success_type = self.class.respond_to?(:_success_type) && self.class._success_type
+
+      if success_type && stored
+        self.class.send(:_coerce_value, success_type, stored)
+      elsif stored.is_a?(Hash) && stored.key?("_dex_value")
+        stored["_dex_value"]
+      else
+        stored
+      end
+    end
+
+    def _once_replay_error(record)
+      raise Dex::Error.new(
+        record.error_code.to_sym,
+        record.error_message,
+        details: record.respond_to?(:error_details) ? record.error_details : nil
+      )
+    end
+
+    def _once_current_time
+      Time.respond_to?(:current) ? Time.current : Time.now
+    end
+  end
+end