dexkit 0.9.0 → 0.11.0

data/lib/dex/event/metadata.rb

@@ -1,33 +1,28 @@
 # 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
 
-      def initialize(id:, timestamp:, trace_id:, caused_by_id:, context:)
+      def initialize(id:, timestamp:, trace_id:, caused_by_id:, event_ancestry:)
         @id = id
         @timestamp = timestamp
         @trace_id = trace_id
         @caused_by_id = caused_by_id
-        @context = context
+        @event_ancestry = event_ancestry
         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
-
-        ctx = if Dex.configuration.event_context
-          begin
-            Dex.configuration.event_context.call
-          rescue => e
-            Event._warn("event_context failed: #{e.message}")
-            nil
-          end
+      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
 
         new(
@@ -35,7 +30,7 @@ module Dex
           timestamp: Time.now.utc,
           trace_id: trace_id,
           caused_by_id: caused,
-          context: ctx
+          event_ancestry: ancestry
         )
       end
 
@@ -43,10 +38,10 @@ 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
         h
       end
     end

data/lib/dex/event/processor.rb

@@ -7,13 +7,11 @@ module Dex
       return super unless name == :Processor && defined?(ActiveJob::Base)
 
       const_set(:Processor, Class.new(ActiveJob::Base) do
-        def perform(handler_class:, event_class:, payload:, metadata:, trace: nil, context: nil, attempt_number: 1)
-          restore_context(context)
-
+        def perform(handler_class:, event_class:, payload:, metadata:, trace: nil, attempt_number: 1)
           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
@@ -25,7 +23,6 @@ module Dex
               payload: payload,
               metadata: metadata,
               trace: trace,
-              context: context,
               attempt_number: attempt_number + 1
             )
           else
@@ -35,17 +32,6 @@ module Dex
 
         private
 
-        def restore_context(context)
-          return unless context
-
-          restorer = Dex.configuration.restore_event_context
-          return unless restorer
-
-          restorer.call(context)
-        rescue => e
-          Dex::Event._warn("restore_event_context failed: #{e.message}")
-        end
-
         def compute_delay(config, attempt)
           wait = config[:wait]
           case wait

data/lib/dex/event/test_helpers.rb

@@ -65,7 +65,7 @@ module Dex
       def setup
         super
         EventTestWrapper.clear_published!
-        Dex::Event::Trace.clear!
+        Dex::Trace.clear!
         Dex::Event::Suppression.clear!
       end
 

data/lib/dex/event.rb

@@ -3,13 +3,12 @@
 # Modules loaded before class body (no reference to Dex::Event needed)
 require_relative "event/execution_state"
 require_relative "event/metadata"
-require_relative "event/trace"
 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 +66,7 @@ module Dex
     def timestamp = metadata.timestamp
     def trace_id = metadata.trace_id
     def caused_by_id = metadata.caused_by_id
-    def context = metadata.context
-    def trace_frame = { id: id, trace_id: trace_id }
+    def event_ancestry = metadata.event_ancestry
 
     # Publishing
     def publish(sync: false)
@@ -77,7 +75,7 @@ module Dex
 
     def self.publish(sync: false, caused_by: nil, **kwargs)
       if caused_by
-        Trace.with_event(caused_by) do
+        Dex::Trace.with_event_context(caused_by) do
           new(**kwargs).publish(sync: sync)
         end
       else
@@ -85,11 +83,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/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

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.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,125 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Dex
+  module Id
+    ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+    BASE = ALPHABET.length
+    TIMESTAMP_WIDTH = 8
+    DEFAULT_RANDOM_WIDTH = 12
+    MIN_RANDOM_WIDTH = 8
+    PREFIX_PATTERN = /\A[a-z][a-z0-9_]*_\z/
+    MIN_PAYLOAD_LENGTH = 9 # 8 timestamp + at least 1 random
+
+    ALPHABET_INDEX = ALPHABET.each_char.with_index.to_h.freeze
+
+    Parsed = Data.define(:prefix, :created_at, :random)
+
+    module_function
+
+    def generate(prefix, random: DEFAULT_RANDOM_WIDTH)
+      validate_prefix!(prefix)
+      validate_random_width!(random)
+
+      "#{prefix}#{base58_encode(current_milliseconds, TIMESTAMP_WIDTH)}#{random_suffix(random)}"
+    end
+
+    def parse(id)
+      id = String(id)
+      last_underscore = id.rindex("_")
+
+      unless last_underscore
+        raise ArgumentError,
+          "Cannot parse #{id.inspect}: no underscore found. Dex::Id strings have the format \"prefix_<timestamp><random>\"."
+      end
+
+      prefix = id[0..last_underscore]
+      payload = id[(last_underscore + 1)..]
+
+      if payload.length < MIN_PAYLOAD_LENGTH
+        raise ArgumentError,
+          "Cannot parse #{id.inspect}: payload after prefix is #{payload.length} characters, " \
+          "need at least #{MIN_PAYLOAD_LENGTH} (#{TIMESTAMP_WIDTH} timestamp + 1 random)."
+      end
+
+      validate_base58!(payload, id)
+
+      timestamp_chars = payload[0, TIMESTAMP_WIDTH]
+      random_chars = payload[TIMESTAMP_WIDTH..]
+
+      ms = base58_decode(timestamp_chars)
+      created_at = Time.at(ms / 1000, ms % 1000 * 1000, :usec).utc
+
+      Parsed.new(prefix: prefix, created_at: created_at, random: random_chars)
+    end
+
+    def base58_encode(number, width = nil)
+      encoded = +""
+      value = number.to_i
+
+      loop do
+        value, remainder = value.divmod(BASE)
+        encoded.prepend(ALPHABET[remainder])
+        break unless value.positive?
+      end
+
+      width ? encoded.rjust(width, ALPHABET[0]) : encoded
+    end
+
+    def base58_decode(string)
+      raise ArgumentError, "expected a String, got #{string.inspect}" unless string.is_a?(String)
+
+      value = 0
+      string.each_char do |char|
+        index = ALPHABET_INDEX[char]
+        raise ArgumentError, "invalid base58 character #{char.inspect} in #{string.inspect}" unless index
+
+        value = value * BASE + index
+      end
+      value
+    end
+
+    def random_suffix(width)
+      Array.new(width) { ALPHABET[SecureRandom.random_number(BASE)] }.join
+    end
+
+    def current_milliseconds
+      Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    end
+
+    def validate_prefix!(prefix)
+      raise ArgumentError, "prefix must be a non-empty String" unless prefix.is_a?(String) && !prefix.empty?
+
+      return if PREFIX_PATTERN.match?(prefix)
+
+      unless prefix.end_with?("_")
+        raise ArgumentError,
+          "Invalid prefix #{prefix.inspect}: prefix must end with underscore. Did you mean #{"#{prefix}_".inspect}?"
+      end
+
+      raise ArgumentError,
+        "Invalid prefix #{prefix.inspect}: prefix must match #{PREFIX_PATTERN.inspect} " \
+        "(lowercase alphanumeric with internal underscores, ending in underscore)."
+    end
+    private_class_method :validate_prefix!
+
+    def validate_random_width!(width)
+      unless width.is_a?(Integer) && width >= MIN_RANDOM_WIDTH
+        raise ArgumentError,
+          "random: must be an Integer >= #{MIN_RANDOM_WIDTH}, got #{width.inspect}."
+      end
+    end
+    private_class_method :validate_random_width!
+
+    def validate_base58!(payload, original_id)
+      payload.each_char do |char|
+        next if ALPHABET_INDEX.key?(char)
+
+        raise ArgumentError,
+          "Cannot parse #{original_id.inspect}: invalid base58 character #{char.inspect} in payload."
+      end
+    end
+    private_class_method :validate_base58!
+  end
+end

data/lib/dex/operation/async_proxy.rb

@@ -17,27 +17,45 @@ module Dex
         end
       end
 
+      def safe(*)
+        raise NoMethodError,
+          "safe and async are alternative execution strategies. " \
+          "For async outcome reconstruction, use wait/wait! on the ticket."
+      end
+
       private
 
       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)
+        job = job.perform_later(**payload)
+        Operation::Ticket.new(record: nil, job: job)
       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)
+          job = job.perform_later(**payload)
+          Operation::Ticket.new(record: record, job: job)
         rescue => e
           begin
             record.destroy

data/lib/dex/operation/guard_wrapper.rb

@@ -124,7 +124,7 @@ module Dex
         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!"
+            "guard :#{guard.name} must return truthy/falsy, not call error!/success!"
         end
 
         if threat