dexkit 0.8.0 → 0.10.0

data/lib/dex/form/export.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Dex
+  class Form
+    module Export
+      module_function
+
+      TYPE_MAP = {
+        string: { type: "string" },
+        integer: { type: "integer" },
+        float: { type: "number" },
+        decimal: { type: "number" },
+        boolean: { type: "boolean" },
+        date: { type: "string", format: "date" },
+        datetime: { type: "string", format: "date-time" },
+        time: { type: "string", format: "time" }
+      }.freeze
+
+      def build_hash(source)
+        h = _serialize_form_definition(source)
+        h[:name] = source.name if source.name
+        desc = source.description
+        h[:description] = desc if desc
+        h
+      end
+
+      def build_json_schema(source) # rubocop:disable Metrics/MethodLength
+        properties = {}
+        required = []
+
+        source._field_registry.each do |name, field_def|
+          schema = _field_to_schema(field_def)
+          properties[name.to_s] = schema
+          required << name.to_s if field_def.required
+        end
+
+        _add_nested_properties(source, properties, required)
+
+        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 _serialize_fields(source)
+        source._field_registry.each_with_object({}) do |(name, field_def), hash|
+          entry = { type: field_def.type, required: field_def.required }
+          entry[:desc] = field_def.desc if field_def.desc
+          entry[:default] = field_def.default if field_def.default?
+          hash[name] = entry
+        end
+      end
+
+      def _serialize_form_definition(source)
+        h = { fields: _serialize_fields(source) }
+        nested = _serialize_nested(source)
+        h[:nested] = nested unless nested.empty?
+        h
+      end
+
+      def _serialize_nested(source)
+        nested = {}
+        source._nested_ones.each do |name, klass|
+          nested[name] = { type: :one }.merge(_serialize_form_definition(klass))
+        end
+        source._nested_manys.each do |name, klass|
+          nested[name] = { type: :many }.merge(_serialize_form_definition(klass))
+        end
+        nested
+      end
+
+      def _field_to_schema(field_def)
+        schema = TYPE_MAP[field_def.type]&.dup || {}
+        schema[:description] = field_def.desc if field_def.desc
+        schema[:default] = _coerce_default(field_def) if field_def.default?
+        schema
+      end
+
+      def _coerce_default(field_def)
+        val = field_def.default
+        case field_def.type
+        when :integer then val.is_a?(Integer) ? val : val.to_i
+        when :float, :decimal then val.is_a?(Float) ? val : val.to_f
+        when :boolean then !!val
+        when :string, :date, :datetime, :time then val.to_s
+        else val
+        end
+      end
+
+      def _nested_json_schema(klass)
+        properties = {}
+        required = []
+
+        klass._field_registry.each do |name, field_def|
+          schema = _field_to_schema(field_def)
+          properties[name.to_s] = schema
+          required << name.to_s if field_def.required
+        end
+
+        _add_nested_properties(klass, properties, required)
+
+        result = { type: "object" }
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _add_nested_properties(source, properties, required)
+        source._nested_ones.each do |name, klass|
+          properties[name.to_s] = _nested_json_schema(klass)
+          required << name.to_s
+        end
+
+        source._nested_manys.each do |name, klass|
+          properties[name.to_s] = { type: "array", items: _nested_json_schema(klass) }
+        end
+      end
+
+      private_class_method :_serialize_fields, :_serialize_form_definition, :_serialize_nested, :_field_to_schema,
+        :_coerce_default, :_nested_json_schema, :_add_nested_properties
+    end
+  end
+end

data/lib/dex/form/nesting.rb

@@ -70,6 +70,8 @@ module Dex
 
         def _build_nested_class(name, class_name, &block)
           klass = Class.new(Dex::Form, &block)
+          klass.instance_variable_set(:@_dex_nested_form, true)
+          Dex::Form.deregister(klass)
           const_name = class_name || name.to_s.singularize.camelize
           const_set(const_name, klass)
           klass

data/lib/dex/form/uniqueness_validator.rb

@@ -50,8 +50,12 @@ module Dex
       end
 
       def _build_query(model_class, column, value)
-        if options[:case_sensitive] == false && value.is_a?(String) && model_class.respond_to?(:arel_table)
+        return model_class.where(column => value) unless options[:case_sensitive] == false && value.is_a?(String)
+
+        if model_class.respond_to?(:arel_table)
           model_class.where(model_class.arel_table[column].lower.eq(value.downcase))
+        elsif _mongoid_model_class?(model_class)
+          model_class.where(column => /\A#{Regexp.escape(value)}\z/i)
         else
           model_class.where(column => value)
         end
@@ -78,9 +82,21 @@ module Dex
       def _exclude_current_record(query, form)
         return query unless form.record&.persisted?
 
+        if _mongoid_record?(form.record)
+          return query.where(:_id.ne => form.record.id)
+        end
+
         pk = form.record.class.primary_key
         query.where.not(pk => form.record.public_send(pk))
       end
+
+      def _mongoid_model_class?(model_class)
+        defined?(Mongoid::Document) && model_class.include?(Mongoid::Document)
+      end
+
+      def _mongoid_record?(record)
+        _mongoid_model_class?(record.class)
+      end
     end
   end
 end

data/lib/dex/form.rb

@@ -3,6 +3,7 @@
 require "active_model"
 
 require_relative "form/nesting"
+require_relative "form/context"
 
 module Dex
   class Form
@@ -15,8 +16,17 @@ module Dex
     end
 
     include Nesting
+    include Context
     include Match
 
+    extend Registry
+
+    FIELD_DEFAULT_UNSET = Object.new.freeze
+
+    FieldDef = Data.define(:name, :type, :desc, :required, :default) do
+      def default? = !default.equal?(Dex::Form::FIELD_DEFAULT_UNSET)
+    end
+
     class ValidationError < StandardError
       attr_reader :form
 
@@ -27,6 +37,37 @@ module Dex
     end
 
     class << self
+      def _field_registry
+        @_field_registry ||= {}
+      end
+
+      def _required_fields
+        _field_registry.each_with_object([]) do |(name, f), list|
+          list << name if f.required
+        end
+      end
+
+      def field(name, type, desc: nil, default: FIELD_DEFAULT_UNSET, **options)
+        raise ArgumentError, "field name must be a Symbol, got #{name.inspect}" unless name.is_a?(Symbol)
+        raise ArgumentError, "field type must be a Symbol, got #{type.inspect}" unless type.is_a?(Symbol)
+        raise ArgumentError, "desc must be a String, got #{desc.inspect}" if desc && !desc.is_a?(String)
+
+        am_options = options.dup
+        am_options[:default] = default unless default.equal?(FIELD_DEFAULT_UNSET)
+        attribute name, type, **am_options
+        _field_registry[name] = FieldDef.new(name: name, type: type, desc: desc, required: true, default: default)
+      end
+
+      def field?(name, type, desc: nil, default: FIELD_DEFAULT_UNSET, **options)
+        raise ArgumentError, "field name must be a Symbol, got #{name.inspect}" unless name.is_a?(Symbol)
+        raise ArgumentError, "field type must be a Symbol, got #{type.inspect}" unless type.is_a?(Symbol)
+        raise ArgumentError, "desc must be a String, got #{desc.inspect}" if desc && !desc.is_a?(String)
+
+        actual_default = default.equal?(FIELD_DEFAULT_UNSET) ? nil : default
+        attribute name, type, default: actual_default, **options
+        _field_registry[name] = FieldDef.new(name: name, type: type, desc: desc, required: false, default: default)
+      end
+
       def model(klass = nil)
         if klass
           raise ArgumentError, "model must be a Class, got #{klass.inspect}" unless klass.is_a?(Class)
@@ -42,9 +83,38 @@ module Dex
 
       def inherited(subclass)
         super
+        subclass.instance_variable_set(:@_field_registry, _field_registry.dup)
         subclass.instance_variable_set(:@_nested_ones, _nested_ones.dup)
         subclass.instance_variable_set(:@_nested_manys, _nested_manys.dup)
       end
+
+      def _dex_nested_form?
+        !!instance_variable_get(:@_dex_nested_form)
+      end
+
+      # Export
+
+      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.reject { |klass| klass._dex_nested_form? }.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
 
     silence_redefinition_of_method :model_name
@@ -66,6 +136,18 @@ module Dex
       # setters are assignable; everything else is silently dropped.
       attributes = attributes.to_unsafe_h if attributes.respond_to?(:to_unsafe_h)
       attrs = (attributes || {}).transform_keys(&:to_s)
+
+      # Context injection — fill ambient values for unmapped keys
+      mappings = self.class.context_mappings
+      unless mappings.empty?
+        ambient = Dex.context
+        mappings.each do |attr_name, context_key|
+          str_name = attr_name.to_s
+          next if attrs.key?(str_name)
+          attrs[str_name] = ambient[context_key] if ambient.key?(context_key)
+        end
+      end
+
       record = attrs.delete("record")
       @record = record if record.nil? || record.respond_to?(:persisted?)
       provided_keys = attrs.keys
@@ -95,9 +177,10 @@ module Dex
     end
 
     def valid?(context = nil)
-      super_result = super
-      nested_result = _validate_nested(context)
-      super_result && nested_result
+      super
+      _fix_boolean_presence_errors
+      nested_valid = _validate_nested(context)
+      errors.empty? && nested_valid
     end
 
     def to_h
@@ -111,8 +194,40 @@ module Dex
 
     alias_method :to_hash, :to_h
 
+    validate :_validate_required_fields
+
     private
 
+    def _validate_required_fields
+      explicit = self.class.validators
+        .select { |v| v.is_a?(ActiveModel::Validations::PresenceValidator) }
+        .reject { |v| v.options.key?(:on) || v.options.key?(:if) || v.options.key?(:unless) }
+        .flat_map(&:attributes).map(&:to_sym).to_set
+
+      self.class._required_fields.each do |name|
+        next if explicit.include?(name)
+        field_def = self.class._field_registry[name]
+        value = public_send(name)
+        blank = (field_def.type == :boolean) ? value.nil? : value.blank?
+        errors.add(name, :blank) if blank
+      end
+    end
+
+    def _fix_boolean_presence_errors
+      explicit = self.class.validators
+        .select { |v| v.is_a?(ActiveModel::Validations::PresenceValidator) }
+        .reject { |v| v.options.key?(:on) || v.options.key?(:if) || v.options.key?(:unless) }
+        .flat_map(&:attributes).map(&:to_sym)
+
+      explicit.each do |name|
+        field_def = self.class._field_registry[name]
+        next unless field_def&.type == :boolean
+        next if public_send(name).nil?
+
+        errors.delete(name, :blank)
+      end
+    end
+
     def _extract_nested_attributes(attrs)
       nested_keys = self.class._nested_ones.keys.map(&:to_s) +
         self.class._nested_manys.keys.map(&:to_s)
@@ -140,3 +255,4 @@ module Dex
 end
 
 require_relative "form/uniqueness_validator"
+require_relative "form/export"

data/lib/dex/id.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Dex
+  module Id
+    ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+    TIMESTAMP_WIDTH = 8
+    RANDOM_WIDTH = 12
+
+    module_function
+
+    def generate(prefix)
+      "#{prefix}#{base58_encode(current_milliseconds, TIMESTAMP_WIDTH)}#{random_suffix(RANDOM_WIDTH)}"
+    end
+
+    def base58_encode(number, width = nil)
+      encoded = +""
+      value = number.to_i
+
+      loop do
+        value, remainder = value.divmod(ALPHABET.length)
+        encoded.prepend(ALPHABET[remainder])
+        break unless value.positive?
+      end
+
+      width ? encoded.rjust(width, ALPHABET[0]) : encoded
+    end
+
+    def random_suffix(width)
+      Array.new(width) { ALPHABET[SecureRandom.random_number(ALPHABET.length)] }.join
+    end
+
+    def current_milliseconds
+      Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    end
+  end
+end

data/lib/dex/operation/async_proxy.rb

@@ -21,20 +21,31 @@ module Dex
 
       def enqueue_direct_job
         job = apply_options(Operation::DirectJob)
-        payload = { class_name: operation_class_name, params: serialized_params }
+        payload = {
+          class_name: operation_class_name,
+          params: serialized_params,
+          trace: Dex::Trace.dump
+        }
         apply_once_payload!(payload)
         job.perform_later(**payload)
       end
 
       def enqueue_record_job
+        @operation.send(:_record_validate_backend!, async: true)
+        execution_id = Dex::Id.generate("op_")
         record = Dex.record_backend.create_record(
+          id: execution_id,
           name: operation_class_name,
           params: serialized_params,
           status: "pending"
         )
         begin
           job = apply_options(Operation::RecordJob)
-          payload = { class_name: operation_class_name, record_id: record.id.to_s }
+          payload = {
+            class_name: operation_class_name,
+            record_id: record.id.to_s,
+            trace: Dex::Trace.dump
+          }
           apply_once_payload!(payload)
           job.perform_later(**payload)
         rescue => e

data/lib/dex/operation/explain.rb

@@ -45,6 +45,7 @@ module Dex
 
       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])
@@ -119,12 +120,7 @@ module Dex
         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
+        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
@@ -171,7 +167,15 @@ module Dex
           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

data/lib/dex/operation/jobs.rb

@@ -9,29 +9,30 @@ module Dex
       case name
       when :DirectJob
         const_set(:DirectJob, Class.new(ActiveJob::Base) do
-          def perform(class_name:, params:, once_key: nil, once_bypass: false)
+          def perform(class_name:, params:, trace: nil, once_key: nil, once_bypass: false)
             klass = class_name.constantize
             op = klass.new(**klass.send(:_coerce_serialized_hash, params))
             op.once(once_key) if once_key
             op.once(nil) if once_bypass
-            op.call
+            Dex::Trace.restore(trace) { op.call }
           end
         end)
       when :RecordJob
         const_set(:RecordJob, Class.new(ActiveJob::Base) do
-          def perform(class_name:, record_id:, once_key: nil, once_bypass: false)
+          def perform(class_name:, record_id:, trace: nil, 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.instance_variable_set(:@_dex_execution_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
+            Dex::Trace.restore(trace) { op.call }
           rescue => e
             # RecordWrapper handles failures during op.call via its own rescue.
             # This catches pre-pipeline failures (find_record, deserialization, etc.)

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
@@ -172,6 +180,7 @@ module Dex
           once_key: key, once_key_expires_at: expires_at)
       else
         record = Dex.record_backend.create_record(
+          id: @_dex_execution_id,
           name: self.class.name,
           once_key: key,
           once_key_expires_at: expires_at,

data/lib/dex/operation/record_backend.rb

@@ -58,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
@@ -143,7 +156,8 @@ module Dex
         end
 
         def has_field?(field_name)
-          record_class.fields.key?(field_name.to_s)
+          field_name = field_name.to_s
+          record_class.fields.key?(field_name) || (field_name == "id" && record_class.fields.key?("_id"))
         end
       end
     end