dexkit 0.9.0 → 0.11.0

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

@@ -180,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/outcome.rb

@@ -26,6 +26,10 @@ module Dex
         @value.respond_to?(method, include_private) || super
       end
 
+      def deconstruct
+        [@value]
+      end
+
       def deconstruct_keys(keys)
         return { value: @value } unless @value.respond_to?(:deconstruct_keys)
         @value.deconstruct_keys(keys)
@@ -49,6 +53,10 @@ module Dex
       def message = @error.message
       def details = @error.details
 
+      def deconstruct
+        [@error]
+      end
+
       def deconstruct_keys(keys)
         { code: @error.code, message: @error.message, details: @error.details }
       end
@@ -65,6 +73,12 @@ module Dex
       rescue Dex::Error => e
         Operation::Err.new(e)
       end
+
+      def async(*)
+        raise NoMethodError,
+          "safe and async are alternative execution strategies. " \
+          "For async outcome reconstruction, use wait/wait! on the ticket."
+      end
     end
   end
 end

data/lib/dex/operation/record_backend.rb

@@ -156,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

data/lib/dex/operation/record_wrapper.rb

@@ -88,7 +88,7 @@ module Dex
       else
         _record_success_attrs(interceptor.result)
       end
-      Dex.record_backend.update_record(@_dex_record_id, attrs)
+      Dex.record_backend.update_record(@_dex_record_id, _record_base_attrs(include_id: false).merge(attrs))
     rescue => e
       _record_handle_error(e)
     end
@@ -108,7 +108,7 @@ module Dex
       attrs[:once_key] = nil if defined?(@_once_key) || self.class.settings_for(:once).fetch(:defined, false)
 
       if _record_has_pending_record?
-        Dex.record_backend.update_record(@_dex_record_id, attrs)
+        Dex.record_backend.update_record(@_dex_record_id, _record_base_attrs(include_id: false).merge(attrs))
       else
         Dex.record_backend.create_record(_record_base_attrs.merge(attrs))
       end
@@ -116,8 +116,18 @@ module Dex
       _record_handle_error(e)
     end
 
-    def _record_base_attrs
-      attrs = { name: self.class.name }
+    def _record_base_attrs(include_id: true)
+      trace_snapshot = Dex::Trace.current
+      actor_frame = Dex::Trace.actor
+
+      attrs = {
+        name: self.class.name,
+        trace_id: Dex::Trace.trace_id,
+        trace: trace_snapshot,
+        actor_type: actor_frame&.dig(:actor_type),
+        actor_id: actor_frame&.dig(:id)&.to_s
+      }
+      attrs[:id] = @_dex_execution_id if include_id && defined?(@_dex_execution_id) && @_dex_execution_id
       attrs[:params] = _record_params? ? _record_params : nil
       attrs
     end

data/lib/dex/operation/result_wrapper.rb

@@ -57,18 +57,6 @@ module Dex
       throw(:_dex_halt, Operation::Halt.new(type: :success, value: attrs.empty? ? value : attrs))
     end
 
-    def assert!(*args, &block)
-      if block
-        code = args[0]
-        value = yield
-      else
-        value, code = args
-      end
-
-      error!(code) unless value
-      value
-    end
-
     private
 
     def _result_validate_success_type!(value)

data/lib/dex/operation/test_helpers/assertions.rb

@@ -52,39 +52,6 @@ module Dex
         result
       end
 
-      # --- One-liner assertions ---
-
-      def assert_operation(*args, returns: :_not_given, **params)
-        klass = _dex_resolve_subject(args)
-        result = klass.new(**params).safe.call
-        assert result.ok?, "Expected operation to succeed, got Err:\n#{_dex_format_err(result)}"
-        if returns != :_not_given
-          assert_equal returns, result.value, "Return value mismatch"
-        end
-        result
-      end
-
-      def assert_operation_error(*args, message: nil, details: nil, **params)
-        klass, code = _dex_resolve_subject_and_code(args)
-        result = klass.new(**params).safe.call
-        assert result.error?, "Expected operation to fail, got Ok:\n#{_dex_format_ok(result)}"
-        if code
-          assert_equal code, result.code, "Error code mismatch.\n#{_dex_format_err(result)}"
-        end
-        if message
-          case message
-          when Regexp
-            assert_match message, result.message
-          else
-            assert_equal message, result.message
-          end
-        end
-        details&.each do |key, val|
-          assert_equal val, result.details&.dig(key)
-        end
-        result
-      end
-
       # --- Contract assertions ---
 
       def assert_params(*args)
@@ -238,49 +205,6 @@ module Dex
         result
       end
 
-      # --- Batch assertions ---
-
-      def assert_all_succeed(*args, params_list:)
-        klass = _dex_resolve_subject(args)
-        results = params_list.map { |p| klass.new(**p).safe.call }
-        failures = results.each_with_index.reject { |r, _| r.ok? }
-        if failures.any?
-          msgs = failures.map { |r, i| "  [#{i}] #{params_list[i].inspect} => #{_dex_format_err(r)}" }
-          flunk "Expected all #{results.size} calls to succeed, but #{failures.size} failed:\n#{msgs.join("\n")}"
-        end
-        results
-      end
-
-      def assert_all_fail(*args, code:, params_list:, message: nil, details: nil)
-        klass = _dex_resolve_subject(args)
-        results = params_list.map { |p| klass.new(**p).safe.call }
-        failures = results.each_with_index.reject { |r, _| r.error? && r.code == code }
-        if failures.any?
-          msgs = failures.map { |r, i|
-            status = r.ok? ? "Ok(#{r.value.inspect})" : "Err(#{r.code})"
-            "  [#{i}] #{params_list[i].inspect} => #{status}"
-          }
-          flunk "Expected all #{results.size} calls to fail with #{code.inspect}, but #{failures.size} didn't:\n#{msgs.join("\n")}"
-        end
-        results.each_with_index do |r, i|
-          if message
-            case message
-            when Regexp
-              assert_match message, r.message,
-                "Error message mismatch at [#{i}] #{params_list[i].inspect}.\n#{_dex_format_err(r)}"
-            else
-              assert_equal message, r.message,
-                "Error message mismatch at [#{i}] #{params_list[i].inspect}.\n#{_dex_format_err(r)}"
-            end
-          end
-          details&.each do |key, val|
-            assert_equal val, r.details&.dig(key),
-              "Error details[:#{key}] mismatch at [#{i}] #{params_list[i].inspect}.\n#{_dex_format_err(r)}"
-          end
-        end
-        results
-      end
-
       private
 
       def _dex_format_err(result)
@@ -298,18 +222,6 @@ module Dex
         "  value: #{result.value.inspect}"
       end
 
-      def _dex_resolve_subject_and_code(args)
-        if args.first.is_a?(Class) && args.first < Dex::Operation
-          klass = args.shift
-          code = args.shift
-          [klass, code]
-        elsif args.first.is_a?(Symbol)
-          [_dex_resolve_subject([]), args.shift]
-        else
-          [_dex_resolve_subject([]), nil]
-        end
-      end
-
       def _dex_split_class_and_symbols(args)
         if args.first.is_a?(Class) && args.first < Dex::Operation
           [args[0..0], args[1..]]

data/lib/dex/operation/test_helpers.rb

@@ -97,6 +97,12 @@ module Dex
           Dex::Operation::Ok.new(result)
         end
 
+        trace = Dex::Trace.current + [{
+          type: :operation,
+          id: @_dex_execution_id,
+          class: self.class.name || self.class.to_s
+        }]
+
         entry = Dex::TestLog::Entry.new(
           type: "Operation",
           name: self.class.name || self.class.to_s,
@@ -104,7 +110,10 @@ module Dex
           params: _test_safe_params,
           result: safe_result,
           duration: duration,
-          caller_location: caller_locations(4, 1)&.first
+          caller_location: caller_locations(4, 1)&.first,
+          execution_id: @_dex_execution_id,
+          trace_id: @_dex_trace_id,
+          trace: trace
         )
         Dex::TestLog.record(entry)
       end
@@ -120,6 +129,7 @@ module Dex
 
       def setup
         super
+        Dex::Trace.clear!
         Dex::TestLog.clear!
         Dex::Operation::TestWrapper.clear_all_stubs!
       end

data/lib/dex/operation/ticket.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    class Ticket
+      WAIT_MAX_RECOMMENDED = 10
+
+      attr_reader :record, :job
+
+      def initialize(record:, job:)
+        @record = record
+        @job = job
+      end
+
+      def self.from_record(record)
+        raise ArgumentError, "from_record requires a record, got nil" unless record
+
+        new(record: record, job: nil)
+      end
+
+      # --- Delegated accessors ---
+
+      def id
+        _require_record!("id")
+        record.id
+      end
+
+      def operation_name
+        _require_record!("operation_name")
+        record.name
+      end
+
+      def status
+        _require_record!("status")
+        record.status
+      end
+
+      def error_code
+        _require_record!("error_code")
+        record.error_code
+      end
+
+      def error_message
+        _require_record!("error_message")
+        record.error_message
+      end
+
+      def error_details
+        _require_record!("error_details")
+        record.error_details
+      end
+
+      # --- Predicates ---
+
+      def completed?
+        status == "completed"
+      end
+
+      def error?
+        status == "error"
+      end
+
+      def failed?
+        status == "failed"
+      end
+
+      def pending?
+        status == "pending"
+      end
+
+      def running?
+        status == "running"
+      end
+
+      def terminal?
+        completed? || error? || failed?
+      end
+
+      def recorded?
+        !record.nil?
+      end
+
+      # --- Reload ---
+
+      def reload
+        _require_record!("reload")
+        @record = Dex.record_backend.find_record(record.id)
+        self
+      end
+
+      # --- Outcome reconstruction ---
+
+      def outcome
+        _require_record!("outcome")
+
+        case status
+        when "completed"
+          value = _unwrap_result(record.result)
+          value = _coerce_typed_result(value)
+          Ok.new(_symbolize_keys(value))
+        when "error"
+          code = record.error_code&.to_sym
+          message = record.error_message
+          details = record.error_details
+          details = _symbolize_keys(details) if details.is_a?(Hash)
+          Err.new(Dex::Error.new(code, message, details: details))
+        end
+      end
+
+      # --- Wait ---
+
+      def wait(timeout, interval: 0.2)
+        _validate_wait_args!(timeout, interval)
+
+        if timeout.to_f > WAIT_MAX_RECOMMENDED
+          Dex.warn(
+            "Ticket#wait called with #{timeout}s timeout. " \
+            "Speculative sync is designed for short waits (under #{WAIT_MAX_RECOMMENDED}s). " \
+            "Consider client-side polling for long-running operations."
+          )
+        end
+
+        interval_fn = interval.respond_to?(:call) ? interval : ->(_) { interval }
+        deadline = _monotonic_now + timeout.to_f
+        attempt = 0
+
+        loop do
+          if terminal?
+            result = outcome
+            raise _build_operation_failed unless result
+            return result
+          end
+
+          remaining = deadline - _monotonic_now
+          return nil if remaining <= 0
+
+          pause = [interval_fn.call(attempt).to_f, 0.01].max
+          sleep [pause, remaining].min
+          attempt += 1
+          reload
+        end
+      end
+
+      def wait!(timeout, **opts)
+        result = wait(timeout, **opts)
+        raise Dex::Timeout.new(timeout: timeout, ticket_id: id, operation_name: operation_name) unless result
+        return result.value if result.ok?
+
+        raise result.error
+      end
+
+      # --- to_param ---
+
+      def to_param
+        id.to_s
+      end
+
+      # --- as_json ---
+
+      def as_json(*)
+        _require_record!("as_json")
+
+        data = { "id" => id.to_s, "name" => operation_name, "status" => status }
+
+        case status
+        when "completed"
+          result = _unwrap_result(record.result)
+          data["result"] = result unless result.nil?
+        when "error"
+          data["error"] = {
+            "code" => record.error_code,
+            "message" => record.error_message,
+            "details" => record.error_details
+          }.compact
+        end
+
+        data
+      end
+
+      # --- inspect ---
+
+      def inspect
+        if record
+          "#<Dex::Operation::Ticket #{operation_name} id=#{id.inspect} status=#{status.inspect}>"
+        else
+          "#<Dex::Operation::Ticket (unrecorded) job=#{job&.class&.name}>"
+        end
+      end
+
+      private
+
+      def _require_record!(method)
+        return if record
+
+        raise ArgumentError,
+          "#{method} requires a recorded operation. " \
+          "Enable recording with `record true` in your operation, or use `Ticket.from_record` with an existing record."
+      end
+
+      def _validate_wait_args!(timeout, interval)
+        unless record
+          raise ArgumentError,
+            "wait requires a recorded operation. Possible causes: " \
+            "(1) recording is not enabled — add `record true` to your operation; " \
+            "(2) `record params: false` is set — async operations store params in the record to reconstruct " \
+            "the operation in the background job, so params: false forces the direct (non-recorded) strategy. " \
+            "If you need to avoid storing params (e.g., PII), consider encrypting params at the model level instead."
+        end
+        unless _valid_duration?(timeout) && timeout.to_f > 0
+          raise ArgumentError, "timeout must be a positive Numeric, got: #{timeout.inspect}"
+        end
+        if !interval.respond_to?(:call) && !(_valid_duration?(interval) && interval.to_f > 0)
+          raise ArgumentError, "interval must be a positive number or a callable, got: #{interval.inspect}"
+        end
+      end
+
+      def _build_operation_failed
+        Dex::OperationFailed.new(
+          operation_name: record.name || "Unknown",
+          exception_class: record.error_code || "Unknown",
+          exception_message: record.error_message || "(no message recorded)"
+        )
+      end
+
+      def _valid_duration?(value)
+        return true if value.is_a?(Numeric)
+        return true if defined?(ActiveSupport::Duration) && value.is_a?(ActiveSupport::Duration)
+
+        false
+      end
+
+      def _coerce_typed_result(value)
+        return value if value.nil?
+
+        klass = record.name&.safe_constantize
+        return value unless klass
+
+        success_type = klass.respond_to?(:_success_type) && klass._success_type
+        return value unless success_type
+
+        klass.send(:_coerce_value, success_type, value)
+      rescue
+        value
+      end
+
+      def _unwrap_result(result)
+        return result unless result.is_a?(Hash) && result.key?("_dex_value")
+
+        result["_dex_value"]
+      end
+
+      def _symbolize_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(k, v), h| h[k.to_sym] = _symbolize_keys(v) }
+        when Array
+          value.map { |v| _symbolize_keys(v) }
+        else
+          value
+        end
+      end
+
+      def _monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/dex/operation/trace_wrapper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Dex
+  module TraceWrapper
+    extend Dex::Concern
+
+    def _trace_wrap
+      @_dex_execution_id ||= Dex::Id.generate("op_")
+
+      Dex::Trace.with_frame(
+        type: :operation,
+        id: @_dex_execution_id,
+        class: self.class.name
+      ) do
+        @_dex_trace_id = Dex::Trace.trace_id
+        yield
+      end
+    end
+  end
+end

data/lib/dex/operation.rb

@@ -4,6 +4,7 @@
 require_relative "operation/result_wrapper"
 require_relative "operation/once_wrapper"
 require_relative "operation/record_wrapper"
+require_relative "operation/trace_wrapper"
 require_relative "operation/transaction_wrapper"
 require_relative "operation/lock_wrapper"
 require_relative "operation/async_wrapper"
@@ -139,6 +140,7 @@ module Dex
     include AsyncWrapper
     include SafeWrapper
 
+    use TraceWrapper, at: :outer
     use ResultWrapper
     use GuardWrapper
     use OnceWrapper
@@ -156,6 +158,7 @@ require_relative "operation/async_proxy"
 require_relative "operation/record_backend"
 require_relative "operation/transaction_adapter"
 require_relative "operation/jobs"
+require_relative "operation/ticket"
 require_relative "operation/explain"
 require_relative "operation/export"
 

data/lib/dex/operation_failed.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Dex
+  class OperationFailed < StandardError
+    attr_reader :operation_name, :exception_class, :exception_message
+
+    def initialize(operation_name:, exception_class:, exception_message:)
+      @operation_name = operation_name
+      @exception_class = exception_class
+      @exception_message = exception_message
+      super("#{operation_name} failed with #{exception_class}: #{exception_message}")
+    end
+  end
+end

data/lib/dex/query/export.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dex
+  class Query
+    module Export
+      module_function
+
+      def build_hash(source)
+        h = {}
+        h[:name] = source.name if source.name
+        desc = source.description
+        h[:description] = desc if desc
+        h[:props] = _serialize_props(source)
+        ctx = _serialize_context(source)
+        h[:context] = ctx unless ctx.empty?
+        h[:filters] = source.filters unless source.filters.empty?
+        h[:sorts] = source.sorts unless source.sorts.empty?
+        h
+      end
+
+      def build_json_schema(source) # rubocop:disable Metrics/MethodLength
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        properties = {}
+        required = []
+
+        if source.respond_to?(:literal_properties)
+          source.literal_properties.each do |prop|
+            prop_desc = descs[prop.name]
+            schema = TypeSerializer.to_json_schema(prop.type, desc: prop_desc)
+            properties[prop.name.to_s] = schema
+            required << prop.name.to_s if prop.required?
+          end
+        end
+
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = source.name if source.name
+        desc = source.description
+        result[:description] = desc if desc
+        result[:type] = "object"
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _serialize_props(source)
+        return {} unless source.respond_to?(:literal_properties)
+
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        source.literal_properties.each_with_object({}) do |prop, hash|
+          entry = { type: TypeSerializer.to_string(prop.type), required: prop.required? }
+          entry[:desc] = descs[prop.name] if descs[prop.name]
+          hash[prop.name] = entry
+        end
+      end
+
+      def _serialize_context(source)
+        source.respond_to?(:context_mappings) ? source.context_mappings.presence || {} : {}
+      end
+
+      private_class_method :_serialize_props, :_serialize_context
+    end
+  end
+end