axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.4

data/lib/{action → axn}/context.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   class Context
-    attr_accessor :provided_data, :exposed_data
-
     def initialize(**provided_data)
       @provided_data = provided_data
       @exposed_data = {}
@@ -17,18 +15,38 @@ module Action
     # Framework state methods
     def ok? = !@failure
     def failed? = @failure || false
+    def finalized? = @finalized || false
 
     # Framework field accessors
-    attr_accessor :elapsed_time
+    attr_accessor :provided_data, :exposed_data, :elapsed_time
     attr_reader :exception
     private :elapsed_time=
 
+    #
+    # Here down intended for internal use only
+    #
+
     # INTERNAL: base for further filtering (for logging) or providing user with usage hints
     def __combined_data = @provided_data.merge(@exposed_data)
 
+    def __early_completion? = @early_completion || false
+
     def __record_exception(e)
       @exception = e
       @failure = true
+      @finalized = true
+    end
+
+    def __record_early_completion(message)
+      @early_completion_message = message unless message == Axn::Internal::EarlyCompletion.new.message
+      @early_completion = true
+      @finalized = true
+    end
+
+    def __early_completion_message = @early_completion_message.presence
+
+    def __finalize!
+      @finalized = true
     end
   end
 end

data/lib/axn/core/automatic_logging.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    module AutomaticLogging
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+          include InstanceMethods
+
+          # Single class_attribute - nil means disabled, any level means enabled
+          class_attribute :log_calls_level, default: Axn.config.log_level
+          class_attribute :log_errors_level, default: nil
+        end
+      end
+
+      module ClassMethods
+        def log_calls(level)
+          self.log_calls_level = level.presence
+        end
+
+        def log_errors(level)
+          self.log_errors_level = level.presence
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        def _with_logging
+          _log_before if self.class.log_calls_level
+          yield
+        ensure
+          _log_after if self.class.log_calls_level || self.class.log_errors_level
+        end
+
+        def _log_before
+          Axn::Util::Logging.log_at_level(
+            self.class,
+            level: self.class.log_calls_level,
+            message_parts: ["About to execute"],
+            join_string: " with: ",
+            before: _top_level_separator,
+            error_context: "logging before hook",
+            context_direction: :inbound,
+            context_instance: self,
+          )
+        end
+
+        def _log_after
+          # Check log_calls_level first (logs all outcomes)
+          if self.class.log_calls_level
+            _log_after_at_level(self.class.log_calls_level)
+            return
+          end
+
+          # Check log_errors_level (only logs when result.ok? is false)
+          return unless self.class.log_errors_level && !result.ok?
+
+          _log_after_at_level(self.class.log_errors_level)
+        end
+
+        def _log_after_at_level(level)
+          Axn::Util::Logging.log_at_level(
+            self.class,
+            level:,
+            message_parts: [
+              "Execution completed (with outcome: #{result.outcome}) in #{result.elapsed_time} milliseconds",
+            ],
+            join_string: ". Set: ",
+            after: _top_level_separator,
+            error_context: "logging after hook",
+            context_direction: :outbound,
+            context_instance: self,
+          )
+        end
+
+        def _top_level_separator
+          return if Axn.config.env.production?
+          return if Axn::Util::ExecutionContext.background?
+          return if Axn::Util::ExecutionContext.console?
+          return if NestingTracking._current_axn_stack.size > 1
+
+          "\n------\n"
+        end
+      end
+    end
+  end
+end

data/lib/axn/core/context/facade.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "active_support/parameter_filter"
+
+module Axn
+  class ContextFacade
+    def initialize(action:, context:, declared_fields:, implicitly_allowed_fields: nil)
+      if self.class.name == "Axn::ContextFacade" # rubocop:disable Style/ClassEqualityComparison
+        raise "Axn::ContextFacade is an abstract class and should not be instantiated directly"
+      end
+
+      @context = context
+      @action = action
+      @declared_fields = declared_fields
+
+      (@declared_fields + Array(implicitly_allowed_fields)).each do |field|
+        if _model_fields.key?(field)
+          _define_model_field_method(field, _model_fields[field])
+        else
+          singleton_class.define_method(field) do
+            _context_data_source[field]
+          end
+        end
+      end
+    end
+
+    attr_reader :declared_fields
+
+    def inspect = ContextFacadeInspector.new(facade: self, action:, context:).call
+
+    def fail!(...)
+      raise Axn::ContractViolation::MethodNotAllowed, "Call fail! directly rather than on the context"
+    end
+
+    private
+
+    attr_reader :action, :context
+
+    def _model_fields
+      action.internal_field_configs.each_with_object({}) do |config, hash|
+        hash[config.field] = config.validations[:model] if config.validations.key?(:model)
+      end
+    end
+
+    def action_name = @action.class.name.presence || "The action"
+
+    def _define_model_field_method(field, options)
+      Axn::Util::Memoization.define_memoized_reader_method(singleton_class, field) do
+        Axn::Core::FieldResolvers.resolve(
+          type: :model,
+          field:,
+          options:,
+          provided_data: _context_data_source,
+        )
+      end
+    end
+
+    def _context_data_source = raise NotImplementedError
+
+    def _msg_resolver(event_type, exception:)
+      Axn::Core::Flow::Handlers::Resolvers::MessageResolver.new(
+        action._messages_registry,
+        event_type,
+        action:,
+        exception:,
+      )
+    end
+  end
+end

data/lib/{action → axn}/core/context/facade_inspector.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   class ContextFacadeInspector
     def initialize(action:, facade:, context:)
       @action = action
@@ -19,12 +19,12 @@ module Action
     attr_reader :action, :facade, :context
 
     def status
-      return unless facade.is_a?(Action::Result)
+      return unless facade.is_a?(Axn::Result)
 
       return "[OK]" if context.ok?
 
-      if context.exception.is_a?(Action::Failure)
-        return context.exception.message.present? ? "[failed with '#{context.exception.message}']" : "[failed]"
+      if facade.outcome.failure?
+        return context.exception.default_message? ? "[failed]" : "[failed with '#{context.exception.message}']"
       end
 
       %([failed with #{context.exception.class.name}: '#{context.exception.message}'])
@@ -56,9 +56,36 @@ module Action
                           value.inspect
                         end
 
+      # Handle subfield filtering for hash values
+      if value.is_a?(Hash) && sensitive_subfields?(field)
+        filtered_value = filter_subfields(field, value)
+        return filtered_value.inspect
+      end
+
       inspection_filter.filter_param(field, inspected_value)
     end
 
-    def inspection_filter = action.send(:inspection_filter)
+    def inspection_filter = action.class.inspection_filter
+
+    def sensitive_subfields?(field)
+      action.subfield_configs.any? { |config| config.on == field && config.sensitive }
+    end
+
+    def filter_subfields(field, value)
+      # Build a nested structure with subfield paths for filtering
+      nested_data = { field => value }
+
+      # Create a filter with the subfield paths
+      sensitive_subfield_paths = action.subfield_configs
+                                       .select { |config| config.on == field && config.sensitive }
+                                       .map { |config| "#{field}.#{config.field}" }
+
+      return value if sensitive_subfield_paths.empty?
+
+      subfield_filter = ActiveSupport::ParameterFilter.new(sensitive_subfield_paths)
+      filtered_data = subfield_filter.filter(nested_data)
+
+      filtered_data[field]
+    end
   end
 end

data/lib/{action → axn}/core/context/internal.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "action/core/context/facade"
+require "axn/core/context/facade"
 
-module Action
+module Axn
   # Inbound / Internal ContextFacade
   class InternalContext < ContextFacade
-    def default_error = _msg_resolver(:error, exception: Action::Failure.new).resolve_default_message
+    def default_error = _msg_resolver(:error, exception: Axn::Failure.new).resolve_default_message
     def default_success = _msg_resolver(:success, exception: nil).resolve_default_message
 
     private
@@ -15,13 +15,13 @@ module Action
     def method_missing(method_name, ...) # rubocop:disable Style/MissingRespondToMissing (because we're not actually responding to anything additional)
       if @context.__combined_data.key?(method_name.to_sym)
         msg = <<~MSG
-          Method ##{method_name} is not available on Action::InternalContext!
+          Method ##{method_name} is not available on Axn::InternalContext!
 
           #{action_name} may be missing a line like:
             expects :#{method_name}
         MSG
 
-        raise Action::ContractViolation::MethodNotAllowed, msg
+        raise Axn::ContractViolation::MethodNotAllowed, msg
       end
 
       super

data/lib/{action → axn}/core/contract.rb

@@ -3,11 +3,11 @@
 require "active_support/core_ext/enumerable"
 require "active_support/core_ext/module/delegation"
 
-require "action/core/validation/fields"
-require "action/result"
-require "action/core/context/internal"
+require "axn/core/validation/fields"
+require "axn/result"
+require "axn/core/context/internal"
 
-module Action
+module Axn
   module Core
     module Contract
       def self.included(base)
@@ -27,20 +27,21 @@ module Action
           on: nil,
           allow_blank: false,
           allow_nil: false,
+          optional: false,
           default: nil,
           preprocess: nil,
           sensitive: false,
           **validations
         )
-          return _expects_subfields(*fields, on:, allow_blank:, allow_nil:, default:, preprocess:, sensitive:, **validations) if on.present?
-
           fields.each do |field|
             raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES_FOR_EXPECTATIONS.include?(field.to_s)
           end
 
-          _parse_field_configs(*fields, allow_blank:, allow_nil:, default:, preprocess:, sensitive:, **validations).tap do |configs|
+          return _expects_subfields(*fields, on:, allow_blank:, allow_nil:, optional:, default:, preprocess:, sensitive:, **validations) if on.present?
+
+          _parse_field_configs(*fields, allow_blank:, allow_nil:, optional:, default:, preprocess:, sensitive:, **validations).tap do |configs|
             duplicated = internal_field_configs.map(&:field) & configs.map(&:field)
-            raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
+            raise Axn::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(', ')}" if duplicated.any?
 
             # NOTE: avoid <<, which would update value for parents and children
             self.internal_field_configs += configs
@@ -51,6 +52,7 @@ module Action
           *fields,
           allow_blank: false,
           allow_nil: false,
+          optional: false,
           default: nil,
           sensitive: false,
           **validations
@@ -59,92 +61,108 @@ module Action
             raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES_FOR_EXPOSURES.include?(field.to_s)
           end
 
-          _parse_field_configs(*fields, allow_blank:, allow_nil:, default:, preprocess: nil, sensitive:, **validations).tap do |configs|
+          _parse_field_configs(*fields, allow_blank:, allow_nil:, optional:, default:, preprocess: nil, sensitive:, **validations).tap do |configs|
             duplicated = external_field_configs.map(&:field) & configs.map(&:field)
-            raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
+            raise Axn::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(', ')}" if duplicated.any?
 
             # NOTE: avoid <<, which would update value for parents and children
             self.external_field_configs += configs
           end
         end
 
+        def inspection_filter
+          @inspection_filter ||= ActiveSupport::ParameterFilter.new(sensitive_fields)
+        end
+
+        def sensitive_fields
+          (internal_field_configs + external_field_configs + subfield_configs).select(&:sensitive).map(&:field)
+        end
+
+        def _declared_fields(direction)
+          raise ArgumentError, "Invalid direction: #{direction}" unless direction.nil? || %i[inbound outbound].include?(direction)
+
+          configs = case direction
+                    when :inbound then internal_field_configs
+                    when :outbound then external_field_configs
+                    else (internal_field_configs + external_field_configs)
+                    end
+
+          configs.map(&:field)
+        end
+
+        def context_for_logging(data:, direction: nil)
+          inspection_filter.filter(data.slice(*_declared_fields(direction)))
+        end
+
         private
 
         RESERVED_FIELD_NAMES_FOR_EXPECTATIONS = %w[
           fail! ok?
           inspect default_error
           each_pair
+          default_success
+          action_name
         ].freeze
 
         RESERVED_FIELD_NAMES_FOR_EXPOSURES = %w[
           fail! ok?
           inspect each_pair default_error
           ok error success message
+          result
+          outcome
+          exception
+          elapsed_time
+          finalized?
+          __action__
         ].freeze
 
         def _parse_field_configs(
           *fields,
           allow_blank: false,
           allow_nil: false,
+          optional: false,
           default: nil,
           preprocess: nil,
           sensitive: false,
           **validations
         )
+          # Handle optional: true by setting allow_blank: true
+          allow_blank ||= optional
+
           _parse_field_validations(*fields, allow_nil:, allow_blank:, **validations).map do |field, parsed_validations|
             _define_field_reader(field)
-            _define_model_reader(field, parsed_validations[:model]) if parsed_validations.key?(:model)
             FieldConfig.new(field:, validations: parsed_validations, default:, preprocess:, sensitive:)
           end
         end
 
-        def define_memoized_reader_method(field, &block)
-          define_method(field) do
-            ivar = :"@_memoized_reader_#{field}"
-            cached_val = instance_variable_get(ivar)
-            return cached_val if cached_val.present?
-
-            value = instance_exec(&block)
-            instance_variable_set(ivar, value)
-          end
-        end
-
         def _define_field_reader(field)
           # Allow local access to explicitly-expected fields -- even externally-expected needs to be available locally
           # (e.g. to allow success message callable to reference exposed fields)
           define_method(field) { internal_context.public_send(field) }
         end
 
-        def _define_model_reader(field, klass, &id_extractor)
-          name = field.to_s.delete_suffix("_id")
-          raise ArgumentError, "Model validation expects to be given a field ending in _id (given: #{field})" unless field.to_s.end_with?("_id")
-          raise ArgumentError, "Failed to define model reader - #{name} is already defined" if method_defined?(name)
-
-          id_extractor ||= -> { public_send(field) }
-
-          define_memoized_reader_method(name) do
-            Validators::ModelValidator.instance_for(field:, klass:, id: instance_exec(&id_extractor))
-          end
-        end
-
+        # This method applies any top-level options to each of the individual validations given.
+        # It also allows our custom validators to accept a direct value rather than a hash of options.
         def _parse_field_validations(
           *fields,
           allow_nil: false,
           allow_blank: false,
           **validations
         )
-          if allow_blank
-            validations.transform_values! do |v|
-              v = { value: v } unless v.is_a?(Hash)
-              { allow_blank: true }.merge(v)
-            end
-          elsif allow_nil
+          # Apply syntactic sugar for our custom validators (convert shorthand to full hash of options)
+          validations[:type] = Axn::Validators::TypeValidator.apply_syntactic_sugar(validations[:type], fields) if validations.key?(:type)
+          validations[:model] = Axn::Validators::ModelValidator.apply_syntactic_sugar(validations[:model], fields) if validations.key?(:model)
+          validations[:validate] = Axn::Validators::ValidateValidator.apply_syntactic_sugar(validations[:validate], fields) if validations.key?(:validate)
+
+          # Push allow_blank and allow_nil to the individual validations
+          if allow_blank || allow_nil
             validations.transform_values! do |v|
-              v = { value: v } unless v.is_a?(Hash)
-              { allow_nil: true }.merge(v)
+              { allow_blank:, allow_nil: }.merge(v)
             end
           else
-            validations[:presence] = true unless validations.key?(:presence) || Array(validations[:type]).include?(:boolean)
+            # Apply default presence validation (unless the type is boolean or params)
+            type_values = Array(validations.dig(:type, :klass))
+            validations[:presence] = true unless validations.key?(:presence) || type_values.include?(:boolean) || type_values.include?(:params)
           end
 
           fields.map { |field| [field, validations] }
@@ -169,59 +187,79 @@ module Action
           end
 
           kwargs.each do |key, value|
-            raise Action::ContractViolation::UnknownExposure, key unless result.respond_to?(key)
+            raise Axn::ContractViolation::UnknownExposure, key unless result.respond_to?(key)
 
             @__context.exposed_data[key] = value
           end
         end
 
+        # Set additional context to be included in exception logging
+        # This context is only used when exceptions occur, not in normal pre/post logging
+        def set_logging_context(**kwargs)
+          @__additional_logging_context ||= {}
+          @__additional_logging_context.merge!(kwargs)
+        end
+
+        # Clear any previously set additional logging context
+        def clear_logging_context
+          @__additional_logging_context = nil
+        end
+
         def context_for_logging(direction = nil)
-          inspection_filter.filter(@__context.__combined_data.slice(*_declared_fields(direction)))
+          base_context = self.class.context_for_logging(
+            data: @__context.__combined_data,
+            direction:,
+          )
+
+          # Only merge additional context for exception logging (direction is nil)
+          # Pre/post logging don't need additional context since they only log inputs/outputs
+          return base_context if direction
+
+          # Merge both explicit setter context and hook method context (if both exist)
+          explicit_context = @__additional_logging_context || {}
+          hook_context = respond_to?(:additional_logging_context, true) ? additional_logging_context : {}
+          base_context.merge(explicit_context).merge(hook_context)
         end
 
         private
 
-        def _with_contract
-          _apply_inbound_preprocessing!
-          _apply_defaults!(:inbound)
+        def _handle_early_completion_if_raised
+          yield
+          nil
+        rescue Axn::Internal::EarlyCompletion => e
+          @__context.__record_early_completion(e.message)
+          _trigger_on_success
+          true
+        end
+
+        def _with_contract(&)
+          return if _handle_early_completion_if_raised { _apply_inbound_preprocessing! }
+          return if _handle_early_completion_if_raised { _apply_defaults!(:inbound) }
+
           _validate_contract!(:inbound)
 
-          yield
+          if _handle_early_completion_if_raised(&)
+            # Even with early completion, we need to validate outbound and apply defaults
+            _apply_defaults!(:outbound)
+            _validate_contract!(:outbound)
+            return
+          end
 
           _apply_defaults!(:outbound)
           _validate_contract!(:outbound)
 
           # TODO: improve location of this triggering
-          _trigger_on_success if respond_to?(:_trigger_on_success)
+          @__context.__finalize! # Mark result as finalized
+          _trigger_on_success
         end
 
         def _build_context_facade(direction)
           raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
 
-          klass = direction == :inbound ? Action::InternalContext : Action::Result
-          implicitly_allowed_fields = direction == :inbound ? _declared_fields(:outbound) : []
-
-          klass.new(action: self, context: @__context, declared_fields: _declared_fields(direction), implicitly_allowed_fields:)
-        end
-
-        def inspection_filter
-          @inspection_filter ||= ActiveSupport::ParameterFilter.new(sensitive_fields)
-        end
-
-        def sensitive_fields
-          (internal_field_configs + external_field_configs).select(&:sensitive).map(&:field)
-        end
-
-        def _declared_fields(direction)
-          raise ArgumentError, "Invalid direction: #{direction}" unless direction.nil? || %i[inbound outbound].include?(direction)
-
-          configs = case direction
-                    when :inbound then internal_field_configs
-                    when :outbound then external_field_configs
-                    else (internal_field_configs + external_field_configs)
-                    end
+          klass = direction == :inbound ? Axn::InternalContext : Axn::Result
+          implicitly_allowed_fields = direction == :inbound ? self.class._declared_fields(:outbound) : []
 
-          configs.map(&:field)
+          klass.new(action: self, context: @__context, declared_fields: self.class._declared_fields(direction), implicitly_allowed_fields:)
         end
       end
     end