dexkit 0.6.0 → 0.8.0

data/lib/dex/operation/once_wrapper.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Dex
+  module OnceWrapper
+    extend Dex::Concern
+
+    module ClassMethods
+      def once(*props, expires_in: nil, &block)
+        if settings_for(:once)[:defined]
+          raise ArgumentError, "once can only be declared once per operation"
+        end
+
+        record_settings = settings_for(:record)
+        if record_settings[:enabled] == false
+          raise ArgumentError, "once requires record to be enabled"
+        end
+
+        if record_settings[:result] == false
+          raise ArgumentError, "once requires result recording (cannot use record result: false)"
+        end
+
+        if block && props.any?
+          raise ArgumentError, "once accepts either prop names or a block, not both"
+        end
+
+        if expires_in && !expires_in.is_a?(Numeric)
+          raise ArgumentError, "once :expires_in must be a duration, got: #{expires_in.inspect}"
+        end
+
+        _once_validate_props!(props) if props.any?
+
+        set(:once,
+          defined: true,
+          props: props.any? ? props : nil,
+          block: block || nil,
+          expires_in: expires_in)
+      end
+
+      def clear_once!(key = nil, **props)
+        derived = if key.is_a?(String)
+          key
+        elsif props.any?
+          _once_build_scoped_key(props)
+        else
+          raise ArgumentError, "pass a String key or keyword arguments matching the once props"
+        end
+        Dex.record_backend.update_record_by_once_key(derived, once_key: nil)
+      end
+
+      def _once_build_scoped_key(props_hash)
+        segments = props_hash.sort_by { |k, _| k.to_s }.map do |k, v|
+          "#{k}=#{URI.encode_www_form_component(v.to_s)}"
+        end
+        "#{name}/#{segments.join("/")}"
+      end
+
+      private
+
+      def _once_validate_props!(prop_names)
+        return unless respond_to?(:literal_properties)
+
+        defined_names = literal_properties.map(&:name).to_set
+        unknown = prop_names.reject { |p| defined_names.include?(p) }
+        return if unknown.empty?
+
+        raise ArgumentError,
+          "once references unknown prop(s): #{unknown.map(&:inspect).join(", ")}. " \
+          "Defined: #{defined_names.map(&:inspect).join(", ")}"
+      end
+    end
+
+    def once(key)
+      @_once_key = key
+      @_once_key_explicit = true
+      self
+    end
+
+    def _once_wrap
+      return yield unless _once_active?
+
+      key = _once_derive_key
+      return yield if key.nil? && _once_key_explicit?
+
+      _once_ensure_backend!
+
+      raise "once key must not be nil" if key.nil?
+
+      expires_in = self.class.settings_for(:once)[:expires_in]
+      expires_at = expires_in ? _once_current_time + expires_in : nil
+
+      existing = Dex.record_backend.find_by_once_key(key)
+      if existing
+        _once_finalize_duplicate!(existing)
+        return _once_replay!(existing)
+      end
+
+      expired = Dex.record_backend.find_expired_once_key(key)
+      Dex.record_backend.update_record(expired.id.to_s, once_key: nil) if expired
+
+      _once_claim!(key, expires_at) { yield }
+    end
+
+    private
+
+    def _once_key_explicit?
+      defined?(@_once_key_explicit) && @_once_key_explicit
+    end
+
+    def _once_active?
+      return true if _once_key_explicit?
+      self.class.settings_for(:once).fetch(:defined, false)
+    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)
+    end
+
+    def _once_derive_key
+      return @_once_key if _once_key_explicit?
+
+      settings = self.class.settings_for(:once)
+
+      if settings[:block]
+        instance_exec(&settings[:block])
+      elsif settings[:props]
+        props_hash = settings[:props].each_with_object({}) { |p, h| h[p] = public_send(p) }
+        self.class._once_build_scoped_key(props_hash)
+      else
+        hash = {}
+        if self.class.respond_to?(:literal_properties)
+          self.class.literal_properties.each { |p| hash[p.name] = public_send(p.name) }
+        end
+        self.class._once_build_scoped_key(hash)
+      end
+    end
+
+    def _once_claim!(key, expires_at)
+      begin
+        _once_acquire_key!(key, expires_at)
+      rescue => e
+        if Dex.record_backend.unique_constraint_error?(e)
+          existing = Dex.record_backend.find_by_once_key(key)
+          if existing
+            _once_finalize_duplicate!(existing)
+            return _once_replay!(existing)
+          end
+
+          raise "once key #{key.inspect} is claimed by another in-flight execution"
+        end
+        raise
+      end
+      yield
+    end
+
+    def _once_acquire_key!(key, expires_at)
+      if _once_has_pending_record?
+        Dex.record_backend.update_record(@_dex_record_id,
+          once_key: key, once_key_expires_at: expires_at)
+      else
+        record = Dex.record_backend.create_record(
+          name: self.class.name,
+          once_key: key,
+          once_key_expires_at: expires_at,
+          status: "pending"
+        )
+        @_dex_record_id = record.id.to_s
+      end
+    end
+
+    def _once_has_pending_record?
+      defined?(@_dex_record_id) && @_dex_record_id
+    end
+
+    def _once_finalize_duplicate!(source_record)
+      return unless _once_has_pending_record?
+
+      attrs = { performed_at: _once_current_time }
+      if source_record.status == "error"
+        attrs[:status] = "error"
+        attrs[:error_code] = source_record.error_code
+        attrs[:error_message] = source_record.error_message
+        attrs[:error_details] = source_record.respond_to?(:error_details) ? source_record.error_details : nil
+      else
+        attrs[:status] = "completed"
+        attrs[:result] = source_record.respond_to?(:result) ? source_record.result : nil
+      end
+      Dex.record_backend.update_record(@_dex_record_id, attrs)
+    rescue => e
+      Dex.warn("Failed to finalize replayed record: #{e.message}")
+    end
+
+    def _once_replay!(record)
+      case record.status
+      when "completed"
+        _once_replay_success(record)
+      when "error"
+        _once_replay_error(record)
+      end
+    end
+
+    def _once_replay_success(record)
+      stored = record.respond_to?(:result) ? record.result : nil
+      success_type = self.class.respond_to?(:_success_type) && self.class._success_type
+
+      if success_type && stored
+        self.class.send(:_coerce_value, success_type, stored)
+      elsif stored.is_a?(Hash) && stored.key?("_dex_value")
+        stored["_dex_value"]
+      else
+        stored
+      end
+    end
+
+    def _once_replay_error(record)
+      raise Dex::Error.new(
+        record.error_code.to_sym,
+        record.error_message,
+        details: record.respond_to?(:error_details) ? record.error_details : nil
+      )
+    end
+
+    def _once_current_time
+      Time.respond_to?(:current) ? Time.current : Time.now
+    end
+  end
+end

data/lib/dex/operation/record_backend.rb

@@ -34,6 +34,26 @@ module Dex
           record_class.find(id).update!(safe_attributes(attributes))
         end
 
+        def find_by_once_key(key)
+          raise NotImplementedError
+        end
+
+        def find_expired_once_key(key)
+          raise NotImplementedError
+        end
+
+        def find_pending_once_key(key)
+          raise NotImplementedError
+        end
+
+        def update_record_by_once_key(key, **attributes)
+          raise NotImplementedError
+        end
+
+        def unique_constraint_error?(exception)
+          raise NotImplementedError
+        end
+
         def safe_attributes(attributes)
           attributes.select { |key, _| has_field?(key.to_s) }
         end
@@ -49,12 +69,79 @@ module Dex
           @column_set = record_class.column_names.to_set
         end
 
+        def find_by_once_key(key)
+          scope = record_class.where(once_key: key, status: %w[completed error])
+          scope = scope.where("once_key_expires_at IS NULL OR once_key_expires_at >= ?", Time.now) if has_field?("once_key_expires_at")
+          scope.first
+        end
+
+        def find_expired_once_key(key)
+          return nil unless has_field?("once_key_expires_at")
+
+          record_class
+            .where(once_key: key, status: %w[completed error])
+            .where("once_key_expires_at IS NOT NULL AND once_key_expires_at < ?", Time.now)
+            .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))
+        end
+
+        def unique_constraint_error?(exception)
+          defined?(ActiveRecord::RecordNotUnique) && exception.is_a?(ActiveRecord::RecordNotUnique)
+        end
+
         def has_field?(field_name)
           @column_set.include?(field_name.to_s)
         end
       end
 
       class MongoidAdapter < Base
+        def find_by_once_key(key)
+          now = Time.now
+          record_class.where(
+            :once_key => key,
+            :status.in => %w[completed error]
+          ).and(
+            record_class.or(
+              { once_key_expires_at: nil },
+              { :once_key_expires_at.gte => now }
+            )
+          ).first
+        end
+
+        def find_expired_once_key(key)
+          return nil unless has_field?("once_key_expires_at")
+
+          record_class.where(
+            :once_key => key,
+            :status.in => %w[completed error],
+            :once_key_expires_at.ne => nil,
+            :once_key_expires_at.lt => Time.now
+          ).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))
+        end
+
+        def unique_constraint_error?(exception)
+          defined?(Mongo::Error::OperationFailure) &&
+            exception.is_a?(Mongo::Error::OperationFailure) &&
+            exception.code == 11_000
+        end
+
         def has_field?(field_name)
           record_class.fields.key?(field_name.to_s)
         end

data/lib/dex/operation/record_wrapper.rb

@@ -7,26 +7,27 @@ module Dex
     def _record_wrap
       interceptor = Operation::HaltInterceptor.new { yield }
 
-      if interceptor.success?
-        if _record_has_pending_record?
-          _record_update_done!(interceptor.result)
-        elsif _record_enabled?
-          _record_save!(interceptor.result)
-        end
+      if _record_has_pending_record?
+        _record_update_outcome!(interceptor)
+      elsif _record_enabled?
+        _record_save!(interceptor)
       end
 
       interceptor.rethrow!
       interceptor.result
+    rescue => e
+      _record_failure!(e) if _record_has_pending_record? || _record_enabled?
+      raise
     end
 
     module ClassMethods
       def record(enabled = nil, **options)
-        validate_options!(options, %i[params response], :record)
+        validate_options!(options, %i[params result], :record)
 
         if enabled == false
           set :record, enabled: false
         elsif enabled == true || enabled.nil?
-          merged = { enabled: true, params: true, response: true }.merge(options)
+          merged = { enabled: true, params: true, result: true }.merge(options)
           set :record, **merged
         else
           raise ArgumentError,
@@ -49,27 +50,78 @@ module Dex
       defined?(@_dex_record_id) && @_dex_record_id
     end
 
-    def _record_save!(result)
-      Dex.record_backend.create_record(_record_attributes(result))
+    def _record_save!(interceptor)
+      attrs = _record_base_attrs
+      if interceptor.error?
+        attrs.merge!(_record_error_attrs(code: interceptor.halt.error_code,
+          message: interceptor.halt.error_message,
+          details: interceptor.halt.error_details))
+      else
+        attrs.merge!(_record_success_attrs(interceptor.result))
+      end
+      Dex.record_backend.create_record(attrs)
     rescue => e
       _record_handle_error(e)
     end
 
-    def _record_update_done!(result)
-      attrs = { status: "done", performed_at: _record_current_time }
-      attrs[:response] = _record_response(result) if _record_response?
+    def _record_update_outcome!(interceptor)
+      attrs = if interceptor.error?
+        _record_error_attrs(code: interceptor.halt.error_code,
+          message: interceptor.halt.error_message,
+          details: interceptor.halt.error_details)
+      else
+        _record_success_attrs(interceptor.result)
+      end
       Dex.record_backend.update_record(@_dex_record_id, attrs)
     rescue => e
       _record_handle_error(e)
     end
 
-    def _record_attributes(result)
-      attrs = { name: self.class.name, performed_at: _record_current_time, status: "done" }
+    def _record_failure!(exception)
+      attrs = if exception.is_a?(Dex::Error)
+        _record_error_attrs(code: exception.code, message: exception.message, details: exception.details)
+      else
+        {
+          status: "failed",
+          error_code: exception.class.name,
+          error_message: exception.message,
+          performed_at: _record_current_time
+        }
+      end
+
+      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)
+      else
+        Dex.record_backend.create_record(_record_base_attrs.merge(attrs))
+      end
+    rescue => e
+      _record_handle_error(e)
+    end
+
+    def _record_base_attrs
+      attrs = { name: self.class.name }
       attrs[:params] = _record_params? ? _record_params : nil
-      attrs[:response] = _record_response? ? _record_response(result) : nil
       attrs
     end
 
+    def _record_success_attrs(result)
+      attrs = { status: "completed", performed_at: _record_current_time }
+      attrs[:result] = _record_result(result) if _record_result?
+      attrs
+    end
+
+    def _record_error_attrs(code:, message:, details:)
+      {
+        status: "error",
+        error_code: code.to_s,
+        error_message: message || code.to_s,
+        error_details: _record_sanitize_details(details),
+        performed_at: _record_current_time
+      }
+    end
+
     def _record_params
       _props_as_json
     end
@@ -78,11 +130,11 @@ module Dex
       self.class.settings_for(:record).fetch(:params, true)
     end
 
-    def _record_response?
-      self.class.settings_for(:record).fetch(:response, true)
+    def _record_result?
+      self.class.settings_for(:record).fetch(:result, true)
     end
 
-    def _record_response(result)
+    def _record_result(result)
       success_type = self.class.respond_to?(:_success_type) && self.class._success_type
 
       if success_type
@@ -91,7 +143,7 @@ module Dex
         case result
         when nil then nil
         when Hash then result
-        else { value: result }
+        else { _dex_value: result } # namespaced key so replay can distinguish wrapped primitives from user hashes
         end
       end
     end
@@ -100,6 +152,21 @@ module Dex
       Time.respond_to?(:current) ? Time.current : Time.now
     end
 
+    def _record_sanitize_details(details)
+      _record_sanitize_value(details)
+    end
+
+    def _record_sanitize_value(value)
+      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 Array then value.map { |v| _record_sanitize_value(v) }
+      when Exception then "#{value.class}: #{value.message}"
+      else value.to_s
+      end
+    end
+
     def _record_handle_error(error)
       Dex.warn("Failed to record operation: #{error.message}")
     end

data/lib/dex/operation.rb

@@ -2,6 +2,7 @@
 
 # Wrapper modules (loaded before class body so `include`/`use` can find them)
 require_relative "operation/result_wrapper"
+require_relative "operation/once_wrapper"
 require_relative "operation/record_wrapper"
 require_relative "operation/transaction_wrapper"
 require_relative "operation/lock_wrapper"
@@ -9,6 +10,7 @@ require_relative "operation/async_wrapper"
 require_relative "operation/safe_wrapper"
 require_relative "operation/rescue_wrapper"
 require_relative "operation/callback_wrapper"
+require_relative "operation/guard_wrapper"
 
 module Dex
   class Operation
@@ -40,23 +42,65 @@ module Dex
       end
     end
 
-    RESERVED_PROP_NAMES = %i[call perform async safe initialize].to_set.freeze
+    RESERVED_PROP_NAMES = %i[call perform async safe once initialize].to_set.freeze
 
     include Executable
     include PropsSetup
     include TypeCoercion
+    include ContextSetup
 
-    Contract = Data.define(:params, :success, :errors)
+    Contract = Data.define(:params, :success, :errors, :guards) do
+      attr_reader :source_class
+
+      def initialize(params:, success:, errors:, guards:, source_class: nil)
+        @source_class = source_class
+        super(params: params, success: success, errors: errors, guards: guards)
+      end
+
+      def to_h
+        if @source_class
+          Operation::Export.build_hash(@source_class, self)
+        else
+          super
+        end
+      end
+
+      def to_json_schema(**options)
+        unless @source_class
+          raise ArgumentError, "to_json_schema requires a source_class (use OperationClass.contract.to_json_schema)"
+        end
+
+        Operation::Export.build_json_schema(@source_class, self, **options)
+      end
+    end
+
+    extend Registry
 
     class << self
       def contract
         Contract.new(
           params: _contract_params,
           success: _success_type,
-          errors: _declared_errors
+          errors: _declared_errors,
+          guards: _contract_guards,
+          source_class: self
         )
       end
 
+      def export(format: :hash, **options)
+        unless %i[hash json_schema].include?(format)
+          raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash, :json_schema"
+        end
+
+        sorted = registry.sort_by(&:name)
+        sorted.map do |klass|
+          case format
+          when :hash then klass.contract.to_h
+          when :json_schema then klass.contract.to_json_schema(**options)
+          end
+        end
+      end
+
       private
 
       def _contract_params
@@ -66,6 +110,14 @@ module Dex
           hash[prop.name] = prop.type
         end
       end
+
+      def _contract_guards
+        return [] unless respond_to?(:_guard_list)
+
+        _guard_list.map do |g|
+          { name: g.name, message: g.message, requires: g.requires }
+        end
+      end
     end
 
     def perform(*, **)
@@ -88,9 +140,11 @@ module Dex
     include SafeWrapper
 
     use ResultWrapper
+    use GuardWrapper
+    use OnceWrapper
     use LockWrapper
-    use TransactionWrapper
     use RecordWrapper
+    use TransactionWrapper
     use RescueWrapper
     use CallbackWrapper
   end
@@ -102,6 +156,10 @@ require_relative "operation/async_proxy"
 require_relative "operation/record_backend"
 require_relative "operation/transaction_adapter"
 require_relative "operation/jobs"
+require_relative "operation/explain"
+require_relative "operation/export"
+
+Dex::Operation.extend(Dex::Operation::Explain)
 
 # Top-level aliases (depend on Operation::Ok/Err)
 require_relative "match"

data/lib/dex/props_setup.rb

@@ -17,10 +17,17 @@ module Dex
     end
 
     module ClassMethods
-      def prop(name, type, kind = :keyword, **options, &block)
+      def prop(name, type, kind = :keyword, desc: nil, **options, &block)
         if const_defined?(:RESERVED_PROP_NAMES) && self::RESERVED_PROP_NAMES.include?(name)
           raise ArgumentError, "Property :#{name} is reserved."
         end
+        if !desc.nil?
+          raise ArgumentError, "desc: must be a String, got #{desc.class}" unless desc.is_a?(String)
+
+          _prop_desc_own[name] = desc
+        elsif superclass.respond_to?(:prop_descriptions) && superclass.prop_descriptions.key?(name)
+          _prop_desc_own[name] = nil
+        end
         options[:reader] = :public unless options.key?(:reader)
         if type.is_a?(Dex::RefType) && !block
           ref = type
@@ -29,7 +36,12 @@ module Dex
         super(name, type, kind, **options, &block)
       end
 
-      def prop?(name, type, kind = :keyword, **options, &block)
+      def prop?(name, type, kind = :keyword, desc: nil, **options, &block)
+        if !desc.nil?
+          raise ArgumentError, "desc: must be a String, got #{desc.class}" unless desc.is_a?(String)
+
+          _prop_desc_own[name] = desc
+        end
         options[:reader] = :public unless options.key?(:reader)
         options[:default] = nil unless options.key?(:default)
         if type.is_a?(Dex::RefType) && !block
@@ -39,9 +51,20 @@ module Dex
         prop(name, _Nilable(type), kind, **options, &block)
       end
 
+      def prop_descriptions
+        parent = superclass.respond_to?(:prop_descriptions) ? superclass.prop_descriptions : {}
+        parent.merge(_prop_desc_own).compact
+      end
+
       def _Ref(model_class, lock: false) # rubocop:disable Naming/MethodName
         Dex::RefType.new(model_class, lock: lock)
       end
+
+      private
+
+      def _prop_desc_own
+        @_prop_desc_own ||= {}
+      end
     end
   end
 end