dexkit 0.5.0 → 0.7.0

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

data/lib/dex/operation/transaction_wrapper.rb

@@ -121,7 +121,8 @@ module Dex
       return if callbacks.empty?
 
       flush = -> { callbacks.each(&:call) }
-      adapter = _transaction_adapter
+      enabled = self.class.settings_for(:transaction).fetch(:enabled, true)
+      adapter = enabled && _transaction_adapter
       if adapter
         adapter.after_commit(&flush)
       else

data/lib/dex/operation.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Wrapper modules (loaded before class body so `include`/`use` can find them)
-require_relative "operation/settings"
 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"
@@ -10,9 +10,7 @@ require_relative "operation/async_wrapper"
 require_relative "operation/safe_wrapper"
 require_relative "operation/rescue_wrapper"
 require_relative "operation/callback_wrapper"
-
-# Pipeline (referenced inside class body)
-require_relative "operation/pipeline"
+require_relative "operation/guard_wrapper"
 
 module Dex
   class Operation
@@ -44,38 +42,25 @@ 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)
 
     class << self
       def contract
         Contract.new(
           params: _contract_params,
           success: _success_type,
-          errors: _declared_errors
+          errors: _declared_errors,
+          guards: _contract_guards
         )
       end
 
-      def inherited(subclass)
-        subclass.instance_variable_set(:@_pipeline, pipeline.dup)
-        super
-      end
-
-      def pipeline
-        @_pipeline ||= Pipeline.new
-      end
-
-      def use(mod, as: nil, wrap: nil, before: nil, after: nil, at: nil)
-        step_name = as || _derive_step_name(mod)
-        wrap_method = wrap || :"_#{step_name}_wrap"
-        pipeline.add(step_name, method: wrap_method, before: before, after: after, at: at)
-        include mod
-      end
-
       private
 
       def _contract_params
@@ -86,24 +71,18 @@ module Dex
         end
       end
 
-      def _derive_step_name(mod)
-        base = mod.name&.split("::")&.last
-        raise ArgumentError, "anonymous modules require explicit as: parameter" unless base
+      def _contract_guards
+        return [] unless respond_to?(:_guard_list)
 
-        base.sub(/Wrapper\z/, "")
-          .gsub(/([a-z])([A-Z])/, '\1_\2')
-          .downcase
-          .to_sym
+        _guard_list.map do |g|
+          { name: g.name, message: g.message, requires: g.requires }
+        end
       end
     end
 
     def perform(*, **)
     end
 
-    def call
-      self.class.pipeline.execute(self) { perform }
-    end
-
     def self.method_added(method_name)
       super
       return unless method_name == :perform
@@ -117,14 +96,15 @@ module Dex
       new(**kwargs).call
     end
 
-    include Settings
     include AsyncWrapper
     include SafeWrapper
 
     use ResultWrapper
+    use GuardWrapper
+    use OnceWrapper
     use LockWrapper
-    use TransactionWrapper
     use RecordWrapper
+    use TransactionWrapper
     use RescueWrapper
     use CallbackWrapper
   end

data/lib/dex/pipeline.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Dex
+  class Pipeline
+    Step = Data.define(:name, :method)
+
+    def initialize(steps = [])
+      @steps = steps.dup
+    end
+
+    def dup
+      self.class.new(@steps)
+    end
+
+    def steps
+      @steps.dup.freeze
+    end
+
+    def add(name, method: :"_#{name}_wrap", before: nil, after: nil, at: nil)
+      validate_positioning!(before, after, at)
+      step = Step.new(name: name, method: method)
+
+      if at == :outer then @steps.unshift(step)
+      elsif at == :inner then @steps.push(step)
+      elsif before then @steps.insert(find_index!(before), step)
+      elsif after then @steps.insert(find_index!(after) + 1, step)
+      else @steps.push(step)
+      end
+      self
+    end
+
+    def remove(name)
+      @steps.reject! { |s| s.name == name }
+      self
+    end
+
+    def execute(target)
+      chain = @steps.reverse_each.reduce(-> { yield }) do |next_step, step|
+        -> { target.send(step.method, &next_step) }
+      end
+      chain.call
+    end
+
+    private
+
+    def validate_positioning!(before, after, at)
+      count = [before, after, at].count { |v| !v.nil? }
+      raise ArgumentError, "specify only one of before:, after:, at:" if count > 1
+      raise ArgumentError, "at: must be :outer or :inner" if at && !%i[outer inner].include?(at)
+    end
+
+    def find_index!(name)
+      idx = @steps.index { |s| s.name == name }
+      raise ArgumentError, "pipeline step :#{name} not found" unless idx
+      idx
+    end
+  end
+end

data/lib/dex/test_helpers/assertions.rb

@@ -214,6 +214,29 @@ module Dex
         "Expected #{model_class.name} count to increase, but it stayed at #{count_before}"
     end
 
+    # --- Guard assertions ---
+
+    def assert_callable(*args, **params)
+      klass = _dex_resolve_subject(args)
+      result = klass.callable(**params)
+      assert result.ok?, "Expected operation to be callable, but guards failed:\n#{_dex_format_err(result)}"
+      result
+    end
+
+    def refute_callable(*args, **params)
+      klass_args, codes = _dex_split_class_and_symbols(args)
+      klass = _dex_resolve_subject(klass_args)
+      code = codes.first
+      result = klass.callable(**params)
+      refute result.ok?, "Expected operation to NOT be callable, but all guards passed"
+      if code
+        failed_codes = result.details.map { |f| f[:guard] }
+        assert_includes failed_codes, code,
+          "Expected guard :#{code} to fail, but it didn't.\n  Failed guards: #{failed_codes.inspect}"
+      end
+      result
+    end
+
     # --- Batch assertions ---
 
     def assert_all_succeed(*args, params_list:)

data/lib/dex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dex
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/dexkit.rb

@@ -14,7 +14,11 @@ require_relative "dex/concern"
 require_relative "dex/ref_type"
 require_relative "dex/type_coercion"
 require_relative "dex/props_setup"
+require_relative "dex/context_setup"
 require_relative "dex/error"
+require_relative "dex/settings"
+require_relative "dex/pipeline"
+require_relative "dex/executable"
 require_relative "dex/operation"
 require_relative "dex/event"
 require_relative "dex/form"
@@ -68,5 +72,20 @@ module Dex
     def transaction_adapter=(adapter)
       configuration.transaction_adapter = adapter
     end
+
+    CONTEXT_KEY = :_dex_context
+    EMPTY_CONTEXT = {}.freeze
+
+    def context
+      Fiber[CONTEXT_KEY] || EMPTY_CONTEXT
+    end
+
+    def with_context(**values)
+      previous = Fiber[CONTEXT_KEY]
+      Fiber[CONTEXT_KEY] = (previous || {}).merge(values)
+      yield
+    ensure
+      Fiber[CONTEXT_KEY] = previous
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexkit
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jacek Galanciak
@@ -166,6 +166,7 @@ files:
 - guides/llm/OPERATION.md
 - guides/llm/QUERY.md
 - lib/dex/concern.rb
+- lib/dex/context_setup.rb
 - lib/dex/error.rb
 - lib/dex/event.rb
 - lib/dex/event/bus.rb
@@ -177,6 +178,7 @@ files:
 - lib/dex/event/trace.rb
 - lib/dex/event_test_helpers.rb
 - lib/dex/event_test_helpers/assertions.rb
+- lib/dex/executable.rb
 - lib/dex/form.rb
 - lib/dex/form/nesting.rb
 - lib/dex/form/uniqueness_validator.rb
@@ -185,24 +187,26 @@ files:
 - lib/dex/operation/async_proxy.rb
 - lib/dex/operation/async_wrapper.rb
 - lib/dex/operation/callback_wrapper.rb
+- lib/dex/operation/guard_wrapper.rb
 - lib/dex/operation/jobs.rb
 - lib/dex/operation/lock_wrapper.rb
+- lib/dex/operation/once_wrapper.rb
 - lib/dex/operation/outcome.rb
-- lib/dex/operation/pipeline.rb
 - lib/dex/operation/record_backend.rb
 - lib/dex/operation/record_wrapper.rb
 - lib/dex/operation/rescue_wrapper.rb
 - lib/dex/operation/result_wrapper.rb
 - lib/dex/operation/safe_wrapper.rb
-- lib/dex/operation/settings.rb
 - lib/dex/operation/transaction_adapter.rb
 - lib/dex/operation/transaction_wrapper.rb
+- lib/dex/pipeline.rb
 - lib/dex/props_setup.rb
 - lib/dex/query.rb
 - lib/dex/query/backend.rb
 - lib/dex/query/filtering.rb
 - lib/dex/query/sorting.rb
 - lib/dex/ref_type.rb
+- lib/dex/settings.rb
 - lib/dex/test_helpers.rb
 - lib/dex/test_helpers/assertions.rb
 - lib/dex/test_helpers/execution.rb
@@ -211,14 +215,15 @@ files:
 - lib/dex/type_coercion.rb
 - lib/dex/version.rb
 - lib/dexkit.rb
-homepage: https://github.com/razorjack/dexkit
+homepage: https://dex.razorjack.net/
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/razorjack/dexkit
+  homepage_uri: https://dex.razorjack.net/
   source_code_uri: https://github.com/razorjack/dexkit
   changelog_uri: https://github.com/razorjack/dexkit/blob/master/CHANGELOG.md
+  documentation_uri: https://dex.razorjack.net/
 rdoc_options: []
 require_paths:
 - lib
@@ -235,5 +240,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: 'Dexkit: Rails Patterns Toolbelt. Equip to gain +4 DEX'
+summary: 'dexkit: Rails Patterns Toolbelt. Equip to gain +4 DEX'
 test_files: []

data/lib/dex/operation/pipeline.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module Dex
-  class Operation
-    class Pipeline
-      Step = Data.define(:name, :method)
-
-      def initialize(steps = [])
-        @steps = steps.dup
-      end
-
-      def dup
-        self.class.new(@steps)
-      end
-
-      def steps
-        @steps.dup.freeze
-      end
-
-      def add(name, method: :"_#{name}_wrap", before: nil, after: nil, at: nil)
-        validate_positioning!(before, after, at)
-        step = Step.new(name: name, method: method)
-
-        if at == :outer then @steps.unshift(step)
-        elsif at == :inner then @steps.push(step)
-        elsif before then @steps.insert(find_index!(before), step)
-        elsif after then @steps.insert(find_index!(after) + 1, step)
-        else @steps.push(step)
-        end
-        self
-      end
-
-      def remove(name)
-        @steps.reject! { |s| s.name == name }
-        self
-      end
-
-      def execute(operation)
-        chain = @steps.reverse_each.reduce(-> { yield }) do |next_step, step|
-          -> { operation.send(step.method, &next_step) }
-        end
-        chain.call
-      end
-
-      private
-
-      def validate_positioning!(before, after, at)
-        count = [before, after, at].count { |v| !v.nil? }
-        raise ArgumentError, "specify only one of before:, after:, at:" if count > 1
-        raise ArgumentError, "at: must be :outer or :inner" if at && !%i[outer inner].include?(at)
-      end
-
-      def find_index!(name)
-        idx = @steps.index { |s| s.name == name }
-        raise ArgumentError, "pipeline step :#{name} not found" unless idx
-        idx
-      end
-    end
-  end
-end