dexkit 0.7.0 → 0.9.0

data/lib/dex/operation/explain.rb

@@ -0,0 +1,208 @@
+# 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]
+        return false if info[:record][:enabled] && info[:record][:status] == :misconfigured
+
+        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.missing_fields(send(:_once_required_fields)).empty?
+
+        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)
+        }.tap do |entry|
+          missing = Dex.record_backend.missing_fields(send(:_record_required_fields))
+          if missing.empty?
+            entry[:status] = :ready
+          else
+            entry[:status] = :misconfigured
+            entry[:missing_fields] = missing
+          end
+        end
+      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

@@ -107,16 +107,17 @@ module Dex
 
     private
 
-    def _guard_evaluate
+    def _guard_evaluate_all
       guards = self.class._guard_list
       return [] if guards.empty?
 
       blocked_names = Set.new
-      failures = []
+      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
 
@@ -128,11 +129,21 @@ module Dex
 
         if threat
           blocked_names << guard.name
-          failures << { guard: guard.name, message: guard.message || guard.name.to_s }
+          results << { name: guard.name, passed: false, message: guard.message || guard.name.to_s }
+        else
+          results << { name: guard.name, passed: true }
         end
       end
 
-      failures
+      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/lock_wrapper.rb

@@ -54,11 +54,24 @@ module Dex
       _lock_ensure_loaded!
       key = _lock_key
       ActiveRecord::Base.with_advisory_lock!(key, **_lock_options, &block)
-    rescue WithAdvisoryLock::FailedToAcquireLock
-      raise Dex::Error.new(:lock_timeout, "Could not acquire advisory lock: #{key}")
+    rescue => e
+      if defined?(WithAdvisoryLock::FailedToAcquireLock) && e.is_a?(WithAdvisoryLock::FailedToAcquireLock)
+        raise Dex::Error.new(:lock_timeout, "Could not acquire advisory lock: #{key}")
+      end
+
+      raise
     end
 
     def _lock_ensure_loaded!
+      unless defined?(ActiveRecord::Base)
+        raise LoadError, "advisory_lock requires ActiveRecord and is not supported in Mongoid-only apps."
+      end
+
+      unless defined?(WithAdvisoryLock::FailedToAcquireLock)
+        raise LoadError,
+          "with_advisory_lock gem is required for advisory locking. Add 'with_advisory_lock' to your Gemfile."
+      end
+
       return if ActiveRecord::Base.respond_to?(:with_advisory_lock!)
 
       raise LoadError,

data/lib/dex/operation/once_wrapper.rb

@@ -44,6 +44,7 @@ module Dex
         else
           raise ArgumentError, "pass a String key or keyword arguments matching the once props"
         end
+        _once_validate_backend!
         Dex.record_backend.update_record_by_once_key(derived, once_key: nil)
       end
 
@@ -56,6 +57,27 @@ module Dex
 
       private
 
+      def _once_required_fields
+        fields =
+          if respond_to?(:_record_required_fields, true)
+            send(:_record_required_fields)
+          else
+            []
+          end
+
+        fields << "once_key"
+        fields << "once_key_expires_at" if settings_for(:once)[:expires_in]
+        fields.uniq
+      end
+
+      def _once_validate_backend!
+        unless Dex.record_backend
+          raise "once requires a record backend (configure Dex.record_class)"
+        end
+
+        Dex.record_backend.ensure_fields!(_once_required_fields, feature: "once")
+      end
+
       def _once_validate_props!(prop_names)
         return unless respond_to?(:literal_properties)
 
@@ -112,21 +134,7 @@ module Dex
     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)
+      self.class.send(:_once_validate_backend!)
     end
 
     def _once_derive_key

data/lib/dex/operation/record_backend.rb

@@ -42,6 +42,10 @@ module Dex
           raise NotImplementedError
         end
 
+        def find_pending_once_key(key)
+          raise NotImplementedError
+        end
+
         def update_record_by_once_key(key, **attributes)
           raise NotImplementedError
         end
@@ -54,6 +58,19 @@ module Dex
           attributes.select { |key, _| has_field?(key.to_s) }
         end
 
+        def missing_fields(*fields)
+          fields.flatten.uniq.reject { |field_name| has_field?(field_name) }
+        end
+
+        def ensure_fields!(*fields, feature:)
+          missing = missing_fields(*fields)
+          return if missing.empty?
+
+          raise ArgumentError,
+            "Dex record_class #{record_class} is missing required attributes for #{feature}: #{missing.join(", ")}. " \
+            "Define these attributes on #{record_class} or disable #{feature}."
+        end
+
         def has_field?(field_name)
           raise NotImplementedError
         end
@@ -80,6 +97,10 @@ module Dex
             .first
         end
 
+        def find_pending_once_key(key)
+          record_class.where(once_key: key, status: %w[pending running]).first
+        end
+
         def update_record_by_once_key(key, **attributes)
           record = record_class.where(once_key: key, status: %w[completed error]).first
           record&.update!(safe_attributes(attributes))
@@ -119,6 +140,10 @@ module Dex
           ).first
         end
 
+        def find_pending_once_key(key)
+          record_class.where(:once_key => key, :status.in => %w[pending running]).first
+        end
+
         def update_record_by_once_key(key, **attributes)
           record = record_class.where(:once_key => key, :status.in => %w[completed error]).first
           record&.update!(safe_attributes(attributes))

data/lib/dex/operation/record_wrapper.rb

@@ -5,6 +5,7 @@ module Dex
     extend Dex::Concern
 
     def _record_wrap
+      _record_validate_backend! if _record_enabled? || _record_has_pending_record?
       interceptor = Operation::HaltInterceptor.new { yield }
 
       if _record_has_pending_record?
@@ -34,6 +35,14 @@ module Dex
             "record expects true, false, or nil, got: #{enabled.inspect}"
         end
       end
+
+      def _record_required_fields(async: false)
+        settings = settings_for(:record)
+        fields = %w[name status performed_at error_code error_message error_details]
+        fields << "params" if async || settings.fetch(:params, true)
+        fields << "result" if settings.fetch(:result, true)
+        fields
+      end
     end
 
     private
@@ -46,6 +55,13 @@ module Dex
       record_settings.fetch(:enabled, true)
     end
 
+    def _record_validate_backend!(async: false)
+      Dex.record_backend.ensure_fields!(
+        self.class.send(:_record_required_fields, async: async),
+        feature: async ? "async recording" : "operation recording"
+      )
+    end
+
     def _record_has_pending_record?
       defined?(@_dex_record_id) && @_dex_record_id
     end
@@ -142,8 +158,8 @@ module Dex
       else
         case result
         when nil then nil
-        when Hash then result
-        else { _dex_value: result } # namespaced key so replay can distinguish wrapped primitives from user hashes
+        when Hash then _record_sanitize_value(result)
+        else { "_dex_value" => _record_sanitize_value(result) } # namespaced key so replay can distinguish wrapped primitives from user hashes
         end
       end
     end
@@ -160,10 +176,19 @@ module Dex
       case value
       when NilClass, String, Integer, Float, TrueClass, FalseClass then value
       when Symbol then value.to_s
-      when Hash then value.transform_values { |v| _record_sanitize_value(v) }
+      when Hash
+        value.each_with_object({}) do |(key, nested_value), result|
+          result[key.to_s] = _record_sanitize_value(nested_value)
+        end
       when Array then value.map { |v| _record_sanitize_value(v) }
       when Exception then "#{value.class}: #{value.message}"
-      else value.to_s
+      else
+        if value.respond_to?(:as_json)
+          serialized = value.as_json
+          return _record_sanitize_value(serialized) unless serialized.equal?(value)
+        end
+
+        value.to_s
       end
     end