axn 0.1.0.pre.alpha.2.4.1 → 0.1.0.pre.alpha.2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19221983bd11ff17620830a4807b4080f8ea35dfb07050e2af2e6c1dac1e1b7d
-  data.tar.gz: 7ac5fc8f9ae99bd9a5a189ad53f6113c4c544181ff760bbe923ca1867f011877
+  metadata.gz: bcb1f58a7413ccbfe7bca31932fb0b65a13c0e45dd1dcdb2c8477da829aa45d2
+  data.tar.gz: a26387dca45e8cd121ec50d39a137c9297a2f17b6d8270758a0212a0de42b450
 SHA512:
-  metadata.gz: 4115cc144bfac9420ff85de1ff9198efd092f63594811aed1afbf3ac5a07a5b73a9017b9d9665aac78e128c312d79e996d8dc2f8710fb30a8b9825a51caa30e5
-  data.tar.gz: 7528abe56dd99066409a59a57f07d04f9b9ea98fd399b62aab7318a762920027eb0870b7895b5f8bff525023a7d754c67f0d8c484661929c8a4dab1a360caf6f
+  metadata.gz: a07a81a6525e3c08ac68579166b782e0c589e41be6a0714cd4275f3f3b44d88570bd1ce43d7fac2596529d508a57cf52e6c0b4339f48ddfa8395848a9e67b899
+  data.tar.gz: f90dab3ada8f0fbb047227699e9a41ca43abf183b407af0b002bb58a033cd10ac09061353983b067d31a4ccee2802f3da705b210ece7be298cc921f5e8384553

data/.rubocop.yml

@@ -3,6 +3,10 @@ AllCops:
   SuggestExtensions: false
   NewCops: enable
 
+
+Style/MultilineBlockChain:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes
@@ -45,10 +49,10 @@ Lint/EmptyBlock:
   Enabled: false
 
 Naming/MethodParameterName:
-  AllowedNames: e
+  AllowedNames: e, on, id
 
 Metrics/ParameterLists:
-  Max: 7
+  Max: 9
 
 Layout/LineLength:
   Max: 160

data/CHANGELOG.md

@@ -1,7 +1,23 @@
 # Changelog
 
-## UNRELEASED
-* N/A
+## 0.1.0-alpha.2.5.1
+* Added new `model` validator for expectations
+* [FEAT] Extended `expects` with the `on:` key to allow declaring nested data shapes/validations
+
+## 0.1.0-alpha.2.5
+* Support blank exposures for `Action::Result.ok`
+* Modify Action::Failure's initialize signature (to better match StandardError)
+* Reduce reserved fields to allow some `expects` (e.g. `message`) that would shadow internals if used as `exposes`
+* Default logging changes:
+  * Add `default_log_level` and `default_autolog_level` class methods (so inheritable) via `Action.config`
+  * Remove `global_debug_logging?` from Configuration + unused `SA_DEBUG_TARGETS` approach to configuring logging
+* Improved testing ergonomics: the `type` expectation will now return `true` for _any_ `RSpec::Mocks::` subclass
+* Enqueueable improvements:
+  * Extracted out of Core
+  * Renamed to `Enqueueable::ViaSidekiq` (make it easier to support different background runners in the future)
+  * Added ability to call `.enqueue_all_in_background` to run an Action's class-level `.enqueue_all` method (if defined) on a background worker
+    (important if triggered via a clock process that is NOT intended to execute actual jobs)
+* Restructure internals (call/call! + run/run! + Action::Failure) to simplify upstream implementation since we always wrap any raised exceptions
 
 ## 0.1.0-alpha.2.4.1
 * [FEAT] Adds full suite of per-Axn callbacks: `on_exception`, `on_failure`, `on_error`, `on_success`

data/docs/recipes/testing.md

@@ -31,6 +31,56 @@ before do
 end
 ```
 
+### `call!`
+
+The semantics of call-bang are a little different -- if Subaction is called via `call!`, you'll need slightly different code to handle success vs failure:
+
+### Success
+
+```ruby
+let(:subaction_response) { Action::Result.ok("custom message", foo: 1) }
+
+before do
+  expect(Subaction).to receive(:call!).and_return(subaction_response)
+end
+```
+
+### Failure
+
+Because `call!` will _raise_, we need to use `and_raise` rather than `and_return`:
+
+```ruby
+let(:subaction_exception) { SomeValidErrorClass.new("whatever you expect subclass to raise") }
+
+before do
+  expect(Subaction).to receive(:call!).and_raise(subaction_exception)
+end
+```
+
+NOTE: to mock subaction failing via explicit `fail!` call, you'd use an `Action::Failure` exception class.
+
+## Mocking Axn arguments
+
+Be aware that in order to improve testing ergonomics, the `type` validation will return `true` for _any_ `RSpec::Mocks::` subclass _as long as `Action.config.env.test?` is `true`_.
+
+This makes it much easier to test Axns, as you can pass in mocks without immediately failing the inbound validation.
+
+```ruby
+subject(:result) { action.call!(sym:) }
+
+let(:action) { build_action { expects :sym, type: Symbol } }
+
+context "with a symbol" do
+  let(:sym) { :hello }
+  it { is_expected.to be_ok }
+end
+
+context "with an RSpec double" do
+  let(:sym) { double(to_s: "hello") }  # [!code focus:2]
+  it { is_expected.to be_ok }
+end
+```
+
 ## RSpec configuration
 
 Configuring rspec to treat files in spec/actions as service specs (very optional):

data/docs/reference/class.md

@@ -1,3 +1,7 @@
+---
+outline: deep
+---
+
 # Class Methods
 
 ## `.expects` and `.exposes`
@@ -22,7 +26,7 @@ Both `expects` and `exposes` support the same core options:
 While we _support_ complex interface validations, in practice you usually just want a `type`, if anything.  Remember this is your validation about how the action is called, _not_ pretty user-facing errors (there's [a different pattern for that](/recipes/validating-user-input)).
 :::
 
-In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support two additional custom validators:
+In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support three additional custom validators:
 * `type: Foo` - fails unless the provided value `.is_a?(Foo)`
   * Edge case: use `type: :boolean` to handle a boolean field (since ruby doesn't have a Boolean class to pass in directly)
   * Edge case: use `type: :uuid` to handle a confirming given string is a UUID (with or without `-` chars)
@@ -31,11 +35,48 @@ In addition to the [standard ActiveModel validations](https://guides.rubyonrails
     ```ruby
     expects :foo, validate: ->(value) { "must be pretty big" unless value > 10 }
     ```
+* `model: true` (or `model: TheModelClass`) - allows auto-hydrating a record when only given its ID
+  * Example:
+    ```ruby
+    expects :user_id, model: true
+    ```
+    This line will add expectations that:
+      * `user_id` is provided
+      * `User.find(user_id)` returns a record
+
+    And, when used on `expects`, will create two reader methods for you:
+      * `user_id` (normal), _and_
+      * `user` (for the auto-found record)
+
+    ::: info NOTES
+    * The field name must end in `_id`
+    * This was designed for ActiveRecord models, but will work on any class that returns an instance from `find_by(id: <the provided ID>)`
+    :::
 
+### Details specific to `.exposes`
+
+Remember that you'll need [a corresponding `expose` call](/reference/instance#expose) for every variable you declare via `exposes`.
 
 
 ### Details specific to `.expects`
 
+#### Nested/Subfield expectations
+
+`expects` is for defining the inbound interface. Usually it's enough to declare the top-level fields you receive, but sometimes you want to make expectations about the shape of that data, and/or to define easy accessor methods for deeply nested fields. `expects` supports the `on` option for this (all the normal attributes can be applied as well, _except default, preprocess, and sensitive_):
+
+```ruby
+class Foo
+  expects :event
+  expects :data, type: Hash, on: :event  # [!code focus:2]
+  expects :some, :random, :fields, on: :data
+
+  def call
+    puts "THe event.data.random field's value is: #{random}"
+  end
+end
+```
+
+#### `preprocess`
 `expects` also supports a `preprocess` option that, if set to a callable, will be executed _before_ applying any validations.  This can be useful for type coercion, e.g.:
 
 ```ruby
@@ -44,11 +85,6 @@ expects :date, type: Date, preprocess: ->(d) { d.is_a?(Date) ? d : Date.parse(d)
 
 will succeed if given _either_ an actual Date object _or_ a string that Date.parse can convert into one.  If the preprocess callable raises an exception, that'll be swallowed and the action failed.
 
-### Details specific to `.exposes`
-
-Remember that you'll need [a corresponding `expose` call](/reference/instance#expose) for every variable you declare via `exposes`.
-
-
 ## `.messages`
 
 The `messages` declaration allows you to customize the `error` and `success` messages on the returned result.

data/docs/reference/configuration.md

@@ -11,7 +11,8 @@ Somewhere at boot (e.g. `config/initializers/actions.rb` in Rails), you can call
 
     c.additional_includes = []
 
-    c.global_debug_logging = false
+    c.default_log_level = :info
+    c.default_autolog_level = :debug
 
     c.logger = ...
   end
@@ -84,21 +85,17 @@ For example:
 
 For a practical example of this in practice, see [our 'memoization' recipe](/recipes/memoization).
 
-## `global_debug_logging`
+## `default_log_level`
 
-By default, every `action.call` will emit _debug_ log lines when it is called and after it completes:
+Sets the log level used when you call `log "Some message"` in your Action.  Note this is read via a `default_log_level` class method, so you can easily use inheritance to support different log levels for different sets of actions.
+
+## `default_autolog_level`
+
+By default, every `action.call` will emit log lines when it is called and after it completes:
 
   ```
     [YourCustomAction] About to execute with: {:foo=>"bar"}
     [YourCustomAction] Execution completed (with outcome: success) in 0.957 milliseconds
   ```
 
-You can bump the log level from `debug` to `info` for specific actions by including their class name (comma separated, if multiple) in a `SA_DEBUG_TARGETS` ENV variable.
-
-You can also turn this on _globally_ by setting `global_debug_logging = true`.
-
-```ruby
-  Action.configure do |c|
-    c.global_debug_logging = true
-  end
-```
+You can change the default _auto_-log level separately from the log level used for your explicit `log` calls (just like above, via Action.config or a `default_autolog_level` class method).

data/docs/reference/instance.md

@@ -61,6 +61,12 @@ Accepts a `prefix` keyword argument -- when set, prefixes the `error` message fr
 
 NOTE: expects a single action call in the block -- if there are multiple calls, only the last one will be checked for `ok?` (although anything _raised_ in the block will still be handled).
 
+::: tip Versus `call!`
+* If you just want to make sure your action fails if the subaction fails: call subaction via `call!` (any failures will raise, which will fail the parent).
+  * Note this passes _child_ exception into _parent_ `messages :error` parsing.
+* If you want _the child's_ `result.error` to become the _parent's_ `result.error` on failure, use `hoist_errors` + `call`
+:::
+
 ### Example
 
 ```ruby

data/docs/usage/using.md

@@ -55,3 +55,33 @@ Sidekiq integration is NOT YET TESTED/NOT YET USED IN OUR APP, and naming will V
     * enqueue will not retry even if fails
     * enqueue! will go through normal sidekiq retries on any failure (including user-facing `fail!`)
     * Note implicit GlobalID support (if not serializable, will get ArgumentError at callsite)
+
+
+### `.enqueue_all_in_background`
+
+In practice it's fairly common to need to enqueue a bunch of sidekiq jobs from a clock process.
+
+One approach is to define a class-level `.enqueue_all` method on your Action... but that ends up executing the enqueue_all logic directly from the clock process, which is undesirable.
+
+
+::: danger ALPHA
+We are actively testing this pattern -- not yet certain we'll keep it past beta.
+:::
+
+Therefore we've added an `.enqueue_all_in_background` method that will automatically call your `.enqueue_all` _from a background job_ rather than directly on the active process.
+
+```ruby
+class Foo
+  include Action
+
+  def self.enqueue_all
+    SomeModel.some_scope.find_each do |record|
+      enqueue(record:)
+    end
+  end
+
+  ...
+end
+
+Foo.enqueue_all # works, but `SomeModel.some_scope.find_each` is executed in the current context
+Foo.enqueue_all_in_background # same, but runs in the background (via Action::Enqueueable::EnqueueAllWorker)

data/lib/action/core/configuration.rb

@@ -3,10 +3,11 @@
 module Action
   class Configuration
     include Action::Logging
-    attr_accessor :global_debug_logging, :top_level_around_hook
-    attr_writer :logger, :env, :on_exception, :additional_includes
+    attr_accessor :top_level_around_hook
+    attr_writer :logger, :env, :on_exception, :additional_includes, :default_log_level, :default_autolog_level
 
-    def global_debug_logging? = !!global_debug_logging
+    def default_log_level = @default_log_level ||= :info
+    def default_autolog_level = @default_autolog_level ||= :info
 
     def additional_includes = @additional_includes ||= []
 
@@ -15,7 +16,7 @@ module Action
         # TODO: only pass action: or context: if requested (and update documentation)
         @on_exception.call(e, action:, context:)
       else
-        log("[#{action.class.name.presence || "Anonymous Action"}] Exception swallowed: #{e.class.name} - #{e.message}")
+        log("[#{action.class.name.presence || "Anonymous Action"}] Exception raised: #{e.class.name} - #{e.message}")
       end
     end
 

data/lib/action/core/context_facade.rb

@@ -51,7 +51,9 @@ module Action
     def determine_error_message(only_default: false)
       return @context.error_from_user if @context.error_from_user.present?
 
-      exception = @context.exception || (only_default ? Action::Failure.new(@context) : nil)
+      # We need an exception for interceptors, and also in case the messages.error callable expects an argument
+      exception = @context.exception || Action::Failure.new
+
       msg = action._error_msg
 
       unless only_default
@@ -73,7 +75,7 @@ module Action
         action.instance_exec(&msg)
       end
     rescue StandardError => e
-      action.warn("Ignoring #{e.class.name} raised while determining message callable: #{e.message}")
+      action.warn("Ignoring #{e.class.name} while determining message callable: #{e.message}")
       nil
     end
   end
@@ -95,7 +97,9 @@ module Action
     # For ease of mocking return results in tests
     class << self
       def ok(msg = nil, **exposures)
-        Axn::Factory.build(exposes: exposures.keys, messages: { success: msg }) do
+        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+
+        Axn::Factory.build(exposes:, messages: { success: msg }) do
           exposures.each do |key, value|
             expose(key, value)
           end
@@ -103,7 +107,10 @@ module Action
       end
 
       def error(msg = nil, **exposures, &block)
-        Axn::Factory.build(exposes: exposures.keys, rescues: [-> { true }, msg]) do
+        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+        rescues = [-> { true }, msg]
+
+        Axn::Factory.build(exposes:, rescues:) do
           exposures.each do |key, value|
             expose(key, value)
           end
@@ -162,7 +169,9 @@ module Action
       return unless facade.is_a?(Action::Result)
 
       return "[OK]" if context.success?
-      return "[failed with '#{context.error_from_user}']" unless context.exception
+      unless context.exception
+        return context.error_from_user.present? ? "[failed with '#{context.error_from_user}']" : "[failed]"
+      end
 
       %([failed with #{context.exception.class.name}: '#{context.exception.message}'])
     end

data/lib/action/core/contract.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
-require "active_model"
 require "active_support/core_ext/enumerable"
 require "active_support/core_ext/module/delegation"
 
-require "action/core/contract_validator"
+require "action/core/validation/fields"
 require "action/core/context_facade"
 
 module Action
@@ -34,8 +33,22 @@ module Action
     FieldConfig = Data.define(:field, :validations, :default, :preprocess, :sensitive)
 
     module ClassMethods
-      def expects(*fields, allow_blank: false, allow_nil: false, default: nil, preprocess: nil, sensitive: false,
-                  **validations)
+      def expects(
+        *fields,
+        on: nil,
+        allow_blank: false,
+        allow_nil: 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|
           duplicated = internal_field_configs.map(&:field) & configs.map(&:field)
           raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
@@ -45,7 +58,18 @@ module Action
         end
       end
 
-      def exposes(*fields, allow_blank: false, allow_nil: false, default: nil, sensitive: false, **validations)
+      def exposes(
+        *fields,
+        allow_blank: false,
+        allow_nil: false,
+        default: nil,
+        sensitive: false,
+        **validations
+      )
+        fields.each do |field|
+          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|
           duplicated = external_field_configs.map(&:field) & configs.map(&:field)
           raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
@@ -57,22 +81,56 @@ module Action
 
       private
 
-      RESERVED_FIELD_NAMES = %w[
-        declared_fields inspect fail!
-        default_error
-        called! rollback! each_pair success? exception ok ok? error success message
+      RESERVED_FIELD_NAMES_FOR_EXPECTATIONS = %w[
+        called! fail! rollback! success? ok?
+        inspect default_error
+        each_pair
+      ].freeze
+
+      RESERVED_FIELD_NAMES_FOR_EXPOSURES = %w[
+        called! fail! rollback! success? ok?
+        inspect each_pair default_error
+        ok error success message
       ].freeze
 
-      def _parse_field_configs(*fields, allow_nil: false, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
-                               **validations)
+      def _parse_field_configs(
+        *fields,
+        allow_blank: false,
+        allow_nil: false,
+        default: nil,
+        preprocess: nil,
+        sensitive: false,
+        **validations
+      )
+        _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_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)
-        fields.each do |field|
-          raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES.include?(field.to_s)
+        define_method(field) { internal_context.public_send(field) }
+      end
 
-          define_method(field) { internal_context.public_send(field) }
+      def _define_model_reader(field, klass)
+        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)
+
+        define_method(name) do
+          Validators::ModelValidator.instance_for(field:, klass:, id: public_send(field))
         end
+      end
 
+      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)
@@ -87,7 +145,7 @@ module Action
           validations[:presence] = true unless validations.key?(:presence) || Array(validations[:type]).include?(:boolean)
         end
 
-        fields.map { |field| FieldConfig.new(field:, validations:, default:, preprocess:, sensitive:) }
+        fields.map { |field| [field, validations] }
       end
     end
 
@@ -123,9 +181,9 @@ module Action
         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) : []
+        implicitly_allowed_fields = direction == :inbound ? _declared_fields(:outbound) : []
 
-        klass.new(action: self, context: @context, declared_fields: declared_fields(direction), implicitly_allowed_fields:)
+        klass.new(action: self, context: @context, declared_fields: _declared_fields(direction), implicitly_allowed_fields:)
       end
     end
 
@@ -152,7 +210,7 @@ module Action
         context = direction == :inbound ? internal_context : external_context
         exception_klass = direction == :inbound ? Action::InboundValidationError : Action::OutboundValidationError
 
-        ContractValidator.validate!(validations:, context:, exception_klass:)
+        Validation::Fields.validate!(validations:, context:, exception_klass:)
       end
 
       def _apply_defaults!(direction)
@@ -173,7 +231,7 @@ module Action
       end
 
       def context_for_logging(direction = nil)
-        inspection_filter.filter(@context.to_h.slice(*declared_fields(direction)))
+        inspection_filter.filter(@context.to_h.slice(*_declared_fields(direction)))
       end
 
       protected
@@ -186,7 +244,7 @@ module Action
         (internal_field_configs + external_field_configs).select(&:sensitive).map(&:field)
       end
 
-      def declared_fields(direction)
+      def _declared_fields(direction)
         raise ArgumentError, "Invalid direction: #{direction}" unless direction.nil? || %i[inbound outbound].include?(direction)
 
         configs = case direction

data/lib/action/core/contract_for_subfields.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "action/core/validation/subfields"
+
+module Action
+  module ContractForSubfields
+    # TODO: add default, preprocess, sensitive options for subfields?
+    # SubfieldConfig = Data.define(:field, :validations, :default, :preprocess, :sensitive)
+    SubfieldConfig = Data.define(:field, :validations, :on)
+
+    def self.included(base)
+      base.class_eval do
+        class_attribute :subfield_configs, default: []
+
+        extend ClassMethods
+        include InstanceMethods
+
+        before { _validate_subfields_contract! }
+      end
+    end
+
+    module ClassMethods
+      def _expects_subfields(
+        *fields,
+        on:,
+        readers: true,
+        allow_blank: false,
+        allow_nil: false,
+
+        # TODO: add support for these three options for subfields
+        default: nil,
+        preprocess: nil,
+        sensitive: false,
+
+        **validations
+      )
+        # TODO: add support for these three options for subfields
+        raise ArgumentError, "expects does not support :default key when also given :on" if default.present?
+        raise ArgumentError, "expects does not support :preprocess key when also given :on" if preprocess.present?
+        raise ArgumentError, "expects does not support :sensitive key when also given :on" if sensitive.present?
+
+        unless internal_field_configs.map(&:field).include?(on) || subfield_configs.map(&:field).include?(on)
+          raise ArgumentError,
+                "expects called with `on: #{on}`, but no such method exists (are you sure you've declared `expects :#{on}`?)"
+        end
+
+        raise ArgumentError, "expects does not support expecting fields on nested attributes (i.e. `on` cannot contain periods)" if on.to_s.include?(".")
+
+        # TODO: consider adding support for default, preprocess, sensitive options for subfields?
+        _parse_subfield_configs(*fields, on:, readers:, allow_blank:, allow_nil:, **validations).tap do |configs|
+          duplicated = subfield_configs.map(&:field) & configs.map(&:field)
+          raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
+
+          # NOTE: avoid <<, which would update value for parents and children
+          self.subfield_configs += configs
+        end
+      end
+
+      private
+
+      def _parse_subfield_configs(
+        *fields,
+        on:,
+        readers:,
+        allow_blank: false,
+        allow_nil: false,
+        # default: nil,
+        # preprocess: nil,
+        # sensitive: false,
+        **validations
+      )
+        _parse_field_validations(*fields, allow_nil:, allow_blank:, **validations).map do |field, parsed_validations|
+          _define_subfield_reader(field, on:, validations: parsed_validations) if readers
+          SubfieldConfig.new(field:, validations: parsed_validations, on:)
+        end
+      end
+
+      def _define_subfield_reader(field, on:, validations:)
+        # Don't create top-level readers for nested fields
+        return if field.to_s.include?(".")
+
+        raise ArgumentError, "expects does not support duplicate sub-keys (i.e. `#{field}` is already defined)" if method_defined?(field)
+
+        define_memoized_reader_method(field) do
+          public_send(on).fetch(field)
+        end
+
+        _define_model_reader(field, validations[:model]) if validations.key?(:model)
+      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
+    end
+
+    module InstanceMethods
+      def _validate_subfields_contract!
+        return if subfield_configs.blank?
+
+        subfield_configs.each do |config|
+          Validation::Subfields.validate!(
+            field: config.field,
+            validations: config.validations,
+            source: public_send(config.on),
+            exception_klass: Action::InboundValidationError,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/action/core/event_handlers.rb

@@ -27,7 +27,7 @@ module Action
         action.instance_exec(exception, &@handler)
         true
       rescue StandardError => e
-        action.warn("Ignoring #{e.class.name} in when evaluating #{self.class.name} handler: #{e.message}")
+        action.warn("Ignoring #{e.class.name} when evaluating handler: #{e.message}")
         nil
       end
     end
@@ -54,7 +54,7 @@ module Action
           false
         end
       rescue StandardError => e
-        action.warn("Ignoring #{e.class.name} raised while determining matcher: #{e.message}")
+        action.warn("Ignoring #{e.class.name} while determining matcher: #{e.message}")
         false
       end