dexkit 0.10.0 → 0.11.0

data/lib/dex/id.rb

@@ -5,13 +5,53 @@ require "securerandom"
 module Dex
   module Id
     ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+    BASE = ALPHABET.length
     TIMESTAMP_WIDTH = 8
-    RANDOM_WIDTH = 12
+    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)
-      "#{prefix}#{base58_encode(current_milliseconds, TIMESTAMP_WIDTH)}#{random_suffix(RANDOM_WIDTH)}"
+    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)
@@ -19,7 +59,7 @@ module Dex
       value = number.to_i
 
       loop do
-        value, remainder = value.divmod(ALPHABET.length)
+        value, remainder = value.divmod(BASE)
         encoded.prepend(ALPHABET[remainder])
         break unless value.positive?
       end
@@ -27,12 +67,59 @@ module Dex
       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(ALPHABET.length)] }.join
+      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,6 +17,12 @@ 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
@@ -27,7 +33,8 @@ module Dex
           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
@@ -47,7 +54,8 @@ module Dex
             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

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/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)
@@ -199,30 +166,6 @@ module Dex
           "Expected no operations to be enqueued, but #{after_count - before_count} were"
       end
 
-      # --- Trace assertions ---
-
-      def assert_trace_includes(operation_class, msg: nil)
-        expected = operation_class.is_a?(Class) ? operation_class.name : operation_class.to_s
-        trace_classes = Dex::Trace.current.map { |frame| frame[:class] }.compact
-
-        assert_includes trace_classes, expected,
-          msg || "Expected trace to include #{expected.inspect}, got #{trace_classes.inspect}"
-      end
-
-      def assert_trace_actor(type:, id: :_not_given, msg: nil)
-        actor = Dex::Trace.actor
-        refute_nil actor, msg || "Expected a trace actor, but no actor is set"
-        assert_equal type.to_s, actor[:actor_type], msg || "Trace actor type mismatch"
-        assert_equal id.to_s, actor[:id], msg || "Trace actor id mismatch" unless id == :_not_given
-        actor
-      end
-
-      def assert_trace_depth(expected, msg: nil)
-        actual = Dex::Trace.current.size
-        assert_equal expected, actual,
-          msg || "Expected trace depth #{expected}, got #{actual}.\nTrace: #{Dex::Trace.current.inspect}"
-      end
-
       # --- Transaction assertions ---
 
       def assert_rolls_back(model_class, &block)
@@ -262,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)
@@ -322,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/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.rb

@@ -158,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/timeout.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Dex
+  class Timeout < StandardError
+    attr_reader :timeout, :ticket_id, :operation_name
+
+    def initialize(timeout:, ticket_id:, operation_name:)
+      @timeout = timeout.to_f
+      @ticket_id = ticket_id
+      @operation_name = operation_name
+      super("#{operation_name} did not complete within #{@timeout}s (ticket: #{ticket_id})")
+    end
+  end
+end