dexkit 0.6.0 → 0.8.0

data/lib/dex/event/handler.rb

@@ -5,15 +5,48 @@ module Dex
     class Handler
       include Dex::Executable
 
+      extend Registry
+
+      def self.deregister(klass)
+        if klass.respond_to?(:handled_events)
+          klass.handled_events.each { |ec| Bus.unsubscribe(ec, klass) }
+        end
+        super
+      end
+
       attr_reader :event
 
       def self.on(*event_classes)
         event_classes.each do |ec|
           Event.validate_event_class!(ec)
           Bus.subscribe(ec, self)
+          (@_handled_events ||= []) << ec
         end
       end
 
+      def self.handled_events
+        defined?(@_handled_events) ? @_handled_events.dup.freeze : [].freeze
+      end
+
+      def self.to_h
+        h = {}
+        h[:name] = name if name
+        event_names = handled_events.filter_map(&:name)
+        h[:events] = event_names unless event_names.empty?
+        retry_config = _event_handler_retry_config
+        h[:retries] = retry_config[:count] if retry_config
+        tx_s = settings_for(:transaction)
+        h[:transaction] = tx_s.fetch(:enabled, false)
+        h[:pipeline] = pipeline.steps.map(&:name)
+        h
+      end
+
+      def self.export(format: :hash)
+        raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash" unless format == :hash
+
+        registry.sort_by(&:name).map(&:to_h)
+      end
+
       def self.retries(count, **opts)
         raise ArgumentError, "retries count must be a positive Integer" unless count.is_a?(Integer) && count > 0
 

data/lib/dex/event.rb

@@ -15,6 +15,33 @@ module Dex
 
     include PropsSetup
     include TypeCoercion
+    include ContextSetup
+
+    extend Registry
+
+    class << self
+      def to_h
+        Export.build_hash(self)
+      end
+
+      def to_json_schema
+        Export.build_json_schema(self)
+      end
+
+      def export(format: :hash)
+        unless %i[hash json_schema].include?(format)
+          raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash, :json_schema"
+        end
+
+        sorted = registry.sort_by(&:name)
+        sorted.map do |klass|
+          case format
+          when :hash then klass.to_h
+          when :json_schema then klass.to_json_schema
+          end
+        end
+      end
+    end
 
     def self._warn(message)
       Dex.warn("Event: #{message}")
@@ -83,3 +110,4 @@ end
 require_relative "event/bus"
 require_relative "event/handler"
 require_relative "event/processor"
+require_relative "event/export"

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/explain.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module Explain
+      def explain(**kwargs)
+        error = nil
+        instance = begin
+          new(**kwargs)
+        rescue Literal::TypeError, ArgumentError => e
+          error = e
+          nil
+        end
+
+        info = {}
+        active = pipeline.steps.map(&:name).to_set
+
+        info[:operation] = name || "(anonymous)"
+        desc = description
+        info[:description] = desc if desc
+        info[:error] = "#{error.class}: #{error.message}" if error
+        info[:props] = _explain_props(instance)
+        info[:context] = _explain_context(instance, kwargs)
+        info[:guards] = active.include?(:guard) ? _explain_guards(instance) : { passed: true, results: [] }
+        info[:once] = active.include?(:once) ? _explain_once(instance) : { active: false }
+        info[:lock] = active.include?(:lock) ? _explain_lock(instance) : { active: false }
+        info[:record] = active.include?(:record) ? _explain_record : { enabled: false }
+        info[:transaction] = active.include?(:transaction) ? _explain_transaction : { enabled: false }
+        info[:rescue_from] = active.include?(:rescue) ? _explain_rescue : {}
+        info[:callbacks] = active.include?(:callback) ? _explain_callbacks : { before: 0, after: 0, around: 0 }
+
+        if instance
+          pipeline.steps.each do |step|
+            method_name = :"_#{step.name}_explain"
+            send(method_name, instance, info) if respond_to?(method_name, true)
+          end
+        end
+
+        info[:pipeline] = pipeline.steps.map(&:name)
+        info[:callable] = instance ? _explain_callable?(info) : false
+        info.freeze
+      end
+
+      private
+
+      def _explain_callable?(info)
+        return false unless info[:guards][:passed]
+
+        if info[:once][:active]
+          return false if ONCE_BLOCKING_STATUSES.include?(info[:once][:status])
+        end
+
+        true
+      end
+
+      ONCE_BLOCKING_STATUSES = %i[invalid pending misconfigured unavailable].freeze
+
+      def _explain_props(instance)
+        return {} unless respond_to?(:literal_properties)
+        return {} unless instance
+
+        literal_properties.each_with_object({}) do |prop, hash|
+          hash[prop.name] = instance.public_send(prop.name)
+        end
+      end
+
+      def _explain_context(instance, explicit_kwargs)
+        mappings = respond_to?(:context_mappings) ? context_mappings : {}
+        return { resolved: {}, mappings: {}, source: {} } if mappings.empty?
+
+        ambient = Dex.context
+        resolved = {}
+        source = {}
+
+        mappings.each do |prop_name, context_key|
+          resolved[prop_name] = instance.public_send(prop_name) if instance
+          source[prop_name] = if explicit_kwargs.key?(prop_name)
+            :explicit
+          elsif ambient.key?(context_key)
+            :ambient
+          elsif instance || _explain_prop_has_default?(prop_name)
+            :default
+          else
+            :missing
+          end
+        end
+
+        { resolved: resolved, mappings: mappings, source: source }
+      end
+
+      def _explain_guards(instance)
+        return { passed: false, results: [] } unless instance
+
+        all_results = instance.send(:_guard_evaluate_all)
+        results = all_results.map do |r|
+          entry = { name: r[:name], passed: r[:passed] }
+          entry[:message] = r[:message] if r[:message]
+          entry[:skipped] = true if r[:skipped]
+          entry
+        end
+        { passed: results.all? { |r| r[:passed] }, results: results }
+      end
+
+      def _explain_once(instance)
+        settings = settings_for(:once)
+        return { active: false } unless settings.fetch(:defined, false)
+
+        key = instance&.send(:_once_derive_key)
+        {
+          active: true,
+          key: key,
+          status: _explain_once_status(key),
+          expires_in: settings[:expires_in]
+        }
+      end
+
+      def _explain_once_status(key)
+        return :invalid if key.nil?
+        return :misconfigured if name.nil?
+        return :misconfigured unless pipeline.steps.any? { |s| s.name == :record }
+        return :unavailable unless Dex.record_backend
+        return :misconfigured unless Dex.record_backend.has_field?("once_key")
+
+        settings = settings_for(:once)
+        if settings[:expires_in] && !Dex.record_backend.has_field?("once_key_expires_at")
+          return :misconfigured
+        end
+
+        existing = Dex.record_backend.find_by_once_key(key)
+        return :exists if existing
+
+        if Dex.record_backend.has_field?("once_key_expires_at")
+          expired = Dex.record_backend.find_expired_once_key(key)
+          return :expired if expired
+        end
+
+        pending = Dex.record_backend.find_pending_once_key(key)
+        return :pending if pending
+
+        :fresh
+      end
+
+      def _explain_lock(instance)
+        settings = settings_for(:advisory_lock)
+        return { active: false } unless settings.fetch(:enabled, false)
+
+        key = if instance
+          instance.send(:_lock_key)
+        else
+          case settings[:key]
+          when String then settings[:key]
+          when nil then name
+          end
+        end
+
+        { active: true, key: key, timeout: settings[:timeout] }
+      end
+
+      def _explain_prop_has_default?(prop_name)
+        return false unless respond_to?(:literal_properties)
+
+        literal_properties.any? { |p| p.name == prop_name && p.default? }
+      end
+
+      def _explain_record
+        settings = settings_for(:record)
+        enabled = settings.fetch(:enabled, true) && !!Dex.record_backend && !!name
+        return { enabled: false } unless enabled
+
+        {
+          enabled: true,
+          params: settings.fetch(:params, true),
+          result: settings.fetch(:result, true)
+        }
+      end
+
+      def _explain_transaction
+        settings = settings_for(:transaction)
+        return { enabled: false } unless settings.fetch(:enabled, true)
+
+        adapter_name = settings.fetch(:adapter, Dex.transaction_adapter)
+        adapter = Operation::TransactionAdapter.for(adapter_name)
+        { enabled: !adapter.nil? }
+      end
+
+      def _explain_rescue
+        handlers = respond_to?(:_rescue_handlers) ? _rescue_handlers : []
+        handlers.each_with_object({}) do |h, hash|
+          hash[h[:exception_class].name] = h[:code]
+        end
+      end
+
+      def _explain_callbacks
+        return { before: 0, after: 0, around: 0 } unless respond_to?(:_callback_list)
+
+        {
+          before: _callback_list(:before).size,
+          after: _callback_list(:after).size,
+          around: _callback_list(:around).size
+        }
+      end
+    end
+  end
+end

data/lib/dex/operation/export.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module Export
+      module_function
+
+      def build_hash(source, contract) # rubocop:disable Metrics/MethodLength
+        h = {}
+        h[:name] = source.name if source&.name
+        desc = source&.description
+        h[:description] = desc if desc
+        h[:params] = _serialize_params(source, contract.params)
+        h[:success] = TypeSerializer.to_string(contract.success) if contract.success
+        h[:errors] = contract.errors unless contract.errors.empty?
+        h[:guards] = contract.guards unless contract.guards.empty?
+        ctx = _serialize_context(source)
+        h[:context] = ctx unless ctx.empty?
+        h[:pipeline] = source.pipeline.steps.map(&:name) if source
+        h[:settings] = _serialize_settings(source) if source
+        h
+      end
+
+      def build_json_schema(source, contract, section: :params) # rubocop:disable Metrics/MethodLength
+        case section
+        when :params then _params_schema(source, contract)
+        when :success then _success_schema(source, contract)
+        when :errors then _errors_schema(source, contract)
+        when :full then _full_schema(source, contract)
+        else
+          raise ArgumentError,
+            "unknown section: #{section.inspect}. Known: :params, :success, :errors, :full"
+        end
+      end
+
+      def _serialize_params(source, params)
+        descs = source&.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        params.each_with_object({}) do |(name, type), hash|
+          entry = { type: TypeSerializer.to_string(type), required: _required?(source, name) }
+          entry[:desc] = descs[name] if descs[name]
+          hash[name] = entry
+        end
+      end
+
+      def _required?(source, prop_name)
+        return true unless source&.respond_to?(:literal_properties)
+
+        prop = source.literal_properties.find { |p| p.name == prop_name }
+        return true unless prop
+
+        prop.required?
+      end
+
+      def _serialize_context(source)
+        source&.respond_to?(:context_mappings) ? source.context_mappings.presence || {} : {}
+      end
+
+      def _serialize_settings(source) # rubocop:disable Metrics/MethodLength
+        settings = {}
+
+        record_s = source.settings_for(:record)
+        settings[:record] = {
+          enabled: record_s.fetch(:enabled, true),
+          params: record_s.fetch(:params, true),
+          result: record_s.fetch(:result, true)
+        }
+
+        tx_s = source.settings_for(:transaction)
+        settings[:transaction] = { enabled: tx_s.fetch(:enabled, true) }
+
+        once_s = source.settings_for(:once)
+        settings[:once] = { defined: once_s.fetch(:defined, false) }
+
+        settings
+      end
+
+      def _params_schema(source, contract) # rubocop:disable Metrics/MethodLength
+        descs = source&.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        properties = {}
+        required = []
+
+        contract.params.each do |name, type|
+          prop_desc = descs[name]
+          schema = TypeSerializer.to_json_schema(type, desc: prop_desc)
+          properties[name.to_s] = schema
+          required << name.to_s if _required?(source, name)
+        end
+
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" }
+        result[:title] = source.name if source&.name
+        desc = source&.description
+        result[:description] = desc if desc
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _success_schema(source, contract)
+        return {} unless contract.success
+
+        schema = TypeSerializer.to_json_schema(contract.success)
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = "#{source&.name} success" if source&.name
+        result.merge(schema)
+      end
+
+      def _errors_schema(source, contract)
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = "#{source&.name} errors" if source&.name
+        result[:type] = "object"
+
+        properties = {}
+        contract.errors.each do |code|
+          properties[code.to_s] = {
+            type: "object",
+            properties: {
+              code: { const: code.to_s },
+              message: { type: "string" },
+              details: { type: "object" }
+            }
+          }
+        end
+        result[:properties] = properties unless properties.empty?
+        result
+      end
+
+      def _full_schema(source, contract)
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = source.name if source&.name
+        result[:description] = "Operation contract"
+        result[:properties] = {
+          params: _params_schema(source, contract).except(:$schema),
+          success: _success_schema(source, contract).except(:$schema),
+          errors: _errors_schema(source, contract).except(:$schema)
+        }
+        result
+      end
+
+      private_class_method :_serialize_params, :_required?, :_serialize_context, :_serialize_settings,
+        :_params_schema, :_success_schema, :_errors_schema, :_full_schema
+    end
+  end
+end

data/lib/dex/operation/guard_wrapper.rb

@@ -0,0 +1,149 @@
+# 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_all
+      guards = self.class._guard_list
+      return [] if guards.empty?
+
+      blocked_names = Set.new
+      results = []
+
+      guards.each do |guard|
+        if guard.requires.any? { |dep| blocked_names.include?(dep) }
+          blocked_names << guard.name
+          results << { name: guard.name, passed: false, skipped: true }
+          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
+          results << { name: guard.name, passed: false, message: guard.message || guard.name.to_s }
+        else
+          results << { name: guard.name, passed: true }
+        end
+      end
+
+      results
+    end
+
+    def _guard_evaluate
+      _guard_evaluate_all.filter_map do |r|
+        next if r[:passed] || r[:skipped]
+
+        { guard: r[:name], message: r[:message] }
+      end
+    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