dexkit 0.6.0 → 0.7.0

data/lib/dex/operation/guard_wrapper.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Dex
+  module GuardWrapper
+    extend Dex::Concern
+
+    GuardDefinition = Data.define(:name, :message, :requires, :block)
+
+    module ClassMethods
+      def guard(code, message = nil, requires: nil, &block)
+        raise ArgumentError, "guard code must be a Symbol, got: #{code.inspect}" unless code.is_a?(Symbol)
+        raise ArgumentError, "guard requires a block" unless block
+
+        requires = _guard_normalize_requires!(code, requires)
+        _guard_validate_unique!(code)
+
+        _guard_own << GuardDefinition.new(name: code, message: message, requires: requires, block: block)
+
+        error(code) if respond_to?(:error)
+      end
+
+      def _guard_list
+        parent = superclass.respond_to?(:_guard_list) ? superclass._guard_list : []
+        parent + _guard_own
+      end
+
+      def callable(**kwargs)
+        instance = new(**kwargs)
+        failures = instance.send(:_guard_evaluate)
+        if failures.empty?
+          Operation::Ok.new(nil)
+        else
+          first = failures.first
+          error = Dex::Error.new(first[:guard], first[:message], details: failures)
+          Operation::Err.new(error)
+        end
+      end
+
+      def callable?(*args, **kwargs)
+        if args.size > 1
+          raise ArgumentError, "callable? accepts at most one guard name, got #{args.size} arguments"
+        end
+
+        if args.first
+          guard_name = args.first
+          unless guard_name.is_a?(Symbol)
+            raise ArgumentError, "guard name must be a Symbol, got: #{guard_name.inspect}"
+          end
+          unless _guard_list.any? { |g| g.name == guard_name }
+            raise ArgumentError, "unknown guard :#{guard_name}. Declared: #{_guard_list.map(&:name).map(&:inspect).join(", ")}"
+          end
+          instance = new(**kwargs)
+          failures = instance.send(:_guard_evaluate)
+          failures.none? { |f| f[:guard] == guard_name }
+        else
+          callable(**kwargs).ok?
+        end
+      end
+
+      private
+
+      def _guard_own
+        @_guards ||= []
+      end
+
+      def _guard_normalize_requires!(code, requires)
+        return [] if requires.nil?
+
+        deps = Array(requires)
+        invalid = deps.reject { |d| d.is_a?(Symbol) }
+        if invalid.any?
+          raise ArgumentError,
+            "guard :#{code} requires: must be Symbol(s), got: #{invalid.map(&:inspect).join(", ")}"
+        end
+
+        all_names = _guard_list.map(&:name)
+        deps.each do |dep|
+          unless all_names.include?(dep)
+            raise ArgumentError,
+              "guard :#{code} requires :#{dep}, but no guard with that name has been declared"
+          end
+        end
+
+        deps.freeze
+      end
+
+      def _guard_validate_unique!(code)
+        all_names = _guard_list.map(&:name)
+        if all_names.include?(code)
+          raise ArgumentError, "duplicate guard name :#{code}"
+        end
+      end
+    end
+
+    def _guard_wrap
+      guards = self.class._guard_list
+      return yield if guards.empty?
+
+      failures = _guard_evaluate
+      unless failures.empty?
+        first = failures.first
+        error!(first[:guard], first[:message], details: failures)
+      end
+
+      yield
+    end
+
+    private
+
+    def _guard_evaluate
+      guards = self.class._guard_list
+      return [] if guards.empty?
+
+      blocked_names = Set.new
+      failures = []
+
+      guards.each do |guard|
+        if guard.requires.any? { |dep| blocked_names.include?(dep) }
+          blocked_names << guard.name
+          next
+        end
+
+        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!"
+        end
+
+        if threat
+          blocked_names << guard.name
+          failures << { guard: guard.name, message: guard.message || guard.name.to_s }
+        end
+      end
+
+      failures
+    end
+  end
+end

data/lib/dex/operation/jobs.rb

@@ -9,25 +9,33 @@ module Dex
       case name
       when :DirectJob
         const_set(:DirectJob, Class.new(ActiveJob::Base) do
-          def perform(class_name:, params:)
+          def perform(class_name:, params:, once_key: nil, once_bypass: false)
             klass = class_name.constantize
-            klass.new(**klass.send(:_coerce_serialized_hash, params)).call
+            op = klass.new(**klass.send(:_coerce_serialized_hash, params))
+            op.once(once_key) if once_key
+            op.once(nil) if once_bypass
+            op.call
           end
         end)
       when :RecordJob
         const_set(:RecordJob, Class.new(ActiveJob::Base) do
-          def perform(class_name:, record_id:)
+          def perform(class_name:, record_id:, 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.once(once_key) if once_key
+            op.once(nil) if once_bypass
 
             update_status(record_id, status: "running")
+            pipeline_started = true
             op.call
           rescue => e
-            handle_failure(record_id, e)
+            # RecordWrapper handles failures during op.call via its own rescue.
+            # This catches pre-pipeline failures (find_record, deserialization, etc.)
+            mark_failed(record_id, e) unless pipeline_started
             raise
           end
 
@@ -39,13 +47,12 @@ module Dex
             Dex.warn("Failed to update record status: #{e.message}")
           end
 
-          def handle_failure(record_id, exception)
-            error_value = if exception.is_a?(Dex::Error)
-              exception.code.to_s
-            else
-              exception.class.name
-            end
-            update_status(record_id, status: "failed", error: error_value)
+          def mark_failed(record_id, exception)
+            update_status(record_id,
+              status: "failed",
+              error_code: exception.class.name,
+              error_message: exception.message,
+              performed_at: Time.respond_to?(:current) ? Time.current : Time.now)
           end
         end)
       when :Job

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,22 @@ 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 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 +65,71 @@ 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 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 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