axn 0.1.0.pre.alpha.1.1 → 0.1.0.pre.alpha.2

data/docs/usage/using.md

@@ -7,11 +7,11 @@ outline: deep
 
 ## Common Case
 
-An action is usually executed via `#call`, and _always_ returns an instance of the `Action::Result` class.
+An action executed via `#call` _always_ returns an instance of the `Action::Result` class.
 
-This means the result _always_ implements a consistent interface, including `ok?` and `error` (see [full details](/reference/action-result)) as well as any variables that it `exposes`.  Remember any exceptions have been swallowed.
+This means the result _always_ implements a consistent interface, including `ok?` and `error` (see [full details](/reference/action-result)) as well as any variables that the action `exposes`.
 
-As a consumer, you usually want a conditional that surfaces `error` unless the result is `ok?`, and otherwise takes whatever success action is relevant.
+As a consumer, you usually want a conditional that surfaces `error` unless the result is `ok?` (remember that any exceptions have been swallowed), and otherwise takes whatever success action is relevant.
 
 For example:
 
@@ -23,9 +23,9 @@ class MessagesController < ApplicationController
       message: params[:message],
     )
 
-    if result.ok?  # [!code focus:2]
+    if result.ok?  # [!code focus:3]
       @thread_id = result.thread_id # Because `thread_id` was explicitly exposed
-      flash.now[:success] = "Sent the Slack message"
+      flash.now[:success] = result.success
     else
       flash[:alert] = result.error # [!code focus]
       redirect_to action: :new
@@ -34,21 +34,13 @@ class MessagesController < ApplicationController
 end
 ```
 
-<!-- TODO: replace manual flash success with result.success (here and in guide?) -->
-
-
 ## Advanced Usage
 
 ### `#call!`
 
-::: danger ALPHA
-* TODO - flesh out this section
-:::
-
+An action executed via `#call!` (note the `!`) does _not_ swallow exceptions -- a _successful_ action will return an `Action::Result` just like `call`, but any exceptions will bubble up uncaught (note: technically they _will_ be caught, your on_exception handler triggered, and then re-raised) and any explicit `fail!` calls will raise an `Action::Failure` exception with your custom message.
 
-* `call!`
-    * call! -- will raise any exceptions OR our own Action::Failure if user-facing error occurred (otherwise non-bang will never raise)
-    * note call! still logs completion even if failure (from configuration's on_exception)
+This is a much less common pattern, as you're giving up the benefits of error swallowing and the consistent return interface guarantee, but it can be useful in limited contexts (usually for smaller, one-off scripts where it's easier to just let a failure bubble up rather than worry about adding conditionals for error handling).
 
 
 ### `#enqueue`

data/docs/usage/writing.md

@@ -66,10 +66,39 @@ See [the reference doc](/reference/instance) for a few more handy helper methods
 
 ## Customizing messages
 
-::: danger ALPHA
-* TODO: document `messages` setup
-:::
+The default `error` and `success` message strings ("Something went wrong" / "Action completed successfully", respectively) _are_ technically safe to show users, but you'll often want to set them to something more useful.
+
+There's a `messages` declaration for that -- you can set strings (most common) or a callable (note for the error case, if you give it a callable that expects a single argument, the exception that was raised will be passed in).
+
+For instance, configuring the action like this:
+
+```ruby
+class Foo
+  include Action
+
+  expects :name, type: String
+  exposes :meaning_of_life
+
+  messages success: -> { "Revealed the secret of life to #{name}" }, # [!code focus:2]
+           error: ->(e) { "No secret of life for you: #{e.message}" }
+
+  def call
+    fail! "Douglas already knows the meaning" if name == "Doug"
 
+    msg = "Hello #{name}, the meaning of life is 42"
+    expose meaning_of_life: msg
+  end
+end
+```
+
+Would give us these outputs:
+
+```ruby
+Foo.call.error # => "No secret of life for you: Name can't be blank"
+Foo.call(name: "Doug").error # => "Douglas already knows the meaning"
+Foo.call(name: "Adams").success # => "Revealed the secret of life to Adams"
+Foo.call(name: "Adams").meaning_of_life # => "Hello Adams, the meaning of life is 42"
+```
 
 ## Lifecycle methods
 
@@ -77,11 +106,15 @@ In addition to `#call`, there are a few additional pieces to be aware of:
 
 ### `#rollback`
 
+::: danger ALPHA
+* ⚠️ `#rollback` is _expected_ to be added shortly, but is not yet functional!
+:::
+
 If you define a `#rollback` method, it'll be called (_before_ returning an `Action::Result` to the caller) whenever your action fails.
 
 ### Hooks
 
-`before`, `after`, and `around` hooks are also supported.
+`before` and `after` hooks are also supported. They can receive a block directly, or the symbol name of a local method.
 
 ### Concrete example
 
@@ -91,8 +124,8 @@ Given this series of methods and hooks:
 class Foo
   include Action
 
-  before { log("before hook") }
-  after { log("after hook") }
+  before { log("before hook") } # [!code focus:2]
+  after :log_after
 
   def call
     log("in call")
@@ -102,6 +135,12 @@ class Foo
   def rollback
     log("rolling back")
   end
+
+  private
+
+  def log_after
+    log("after hook")
+  end
 end
 ```
 

data/lib/action/attachable/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Action
+  module Attachable
+    module Base
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def axn_for_attachment(
+          attachment_type: "Action",
+          name: nil,
+          axn_klass: nil,
+          superclass: nil,
+          **kwargs,
+          &block
+        )
+          raise ArgumentError, "#{attachment_type} name must be a string or symbol" unless name.is_a?(String) || name.is_a?(Symbol)
+          raise ArgumentError, "#{attachment_type} '#{name}' must be given an existing action class or a block" if axn_klass.nil? && !block_given?
+
+          if axn_klass && block_given?
+            raise ArgumentError,
+                  "#{attachment_type} '#{name}' was given both an existing action class and a block - only one is allowed"
+          end
+
+          if axn_klass
+            unless axn_klass.respond_to?(:<) && axn_klass < Action
+              raise ArgumentError,
+                    "#{attachment_type} '#{name}' was given an already-existing class #{axn_klass.name} that does NOT inherit from Action as expected"
+            end
+
+            if kwargs.present?
+              raise ArgumentError, "#{attachment_type} '#{name}' was given an existing action class and also keyword arguments - only one is allowed"
+            end
+
+            return axn_klass
+          end
+
+          Axn::Factory.build(superclass: superclass || self, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/action/attachable/steps.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Action
+  module Attachable
+    module Steps
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_axn_steps, default: []
+      end
+
+      Entry = Data.define(:label, :axn)
+
+      class_methods do
+        def steps(*steps)
+          self._axn_steps += Array(steps).compact
+        end
+
+        def step(name, axn_klass = nil, **kwargs, &block)
+          axn_klass = axn_for_attachment(
+            name:,
+            axn_klass:,
+            attachment_type: "Step",
+            superclass: Object, # NOTE: steps skip inheriting from the wrapping class (to avoid duplicate field expectations/exposures)
+            **kwargs,
+            &block
+          )
+
+          # Add the step to the list of steps
+          steps Entry.new(label: name, axn: axn_klass)
+        end
+      end
+
+      def call
+        self.class._axn_steps.each_with_index do |step, idx|
+          # Set a default label if we were just given an array of unlabeled steps
+          # TODO: should Axn have a default label passed in already that we could pull out?
+          step = Entry.new(label: "Step #{idx + 1}", axn: step) if step.is_a?(Class)
+
+          hoist_errors(prefix: "#{step.label} step") do
+            step.axn.call(@context)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/attachable/subactions.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Action
+  module Attachable
+    module Subactions
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def axnable_method(name, axn_klass = nil, **action_kwargs, &block)
+          raise ArgumentError, "Unable to attach Axn -- '#{name}' is already taken" if respond_to?(name)
+
+          action_kwargs[:expose_return_as] ||= :value
+          axn_klass = axn_for_attachment(name:, axn_klass:, **action_kwargs, &block)
+
+          define_singleton_method("#{name}_axn") do |**kwargs|
+            axn_klass.call(**kwargs)
+          end
+
+          define_singleton_method("#{name}!") do |**kwargs|
+            result = axn_klass.call!(**kwargs)
+            result.public_send(action_kwargs[:expose_return_as])
+          end
+        end
+
+        def axn(name, axn_klass = nil, **action_kwargs, &block)
+          raise ArgumentError, "Unable to attach Axn -- '#{name}' is already taken" if respond_to?(name)
+
+          axn_klass = axn_for_attachment(name:, axn_klass:, **action_kwargs, &block)
+
+          define_singleton_method(name) do |**kwargs|
+            axn_klass.call(**kwargs)
+          end
+
+          # TODO: do we also need an instance-level version that auto-wraps in hoist_errors(label: name)?
+
+          define_singleton_method("#{name}!") do |**kwargs|
+            axn_klass.call!(**kwargs)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/attachable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "attachable/base"
+require_relative "attachable/steps"
+require_relative "attachable/subactions"
+
+module Action
+  module Attachable
+    extend ActiveSupport::Concern
+
+    included do
+      include Base
+      include Steps
+      include Subactions
+    end
+  end
+end

data/lib/action/{configuration.rb → core/configuration.rb}

@@ -12,7 +12,7 @@ module Action
 
     def on_exception(e, action:, context: {})
       if @on_exception
-        # TODO: only pass action: or context: if requested
+        # 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}")

data/lib/action/{context_facade.rb → core/context_facade.rb}

@@ -51,36 +51,15 @@ 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)
+      msg = action._error_msg
+
       unless only_default
-        msg = message_from_rescues
-        return msg if msg.present?
+        interceptor = action.class._error_interceptor_for(exception:, action:)
+        msg = interceptor.message if interceptor
       end
 
-      the_exception = @context.exception || (only_default ? Action::Failure.new(@context) : nil)
-      stringified(action._error_msg, exception: the_exception).presence || "Something went wrong"
-    end
-
-    def message_from_rescues
-      Array(action._error_rescues).each do |(matcher, value)|
-        matches = if matcher.respond_to?(:call)
-                    if matcher.arity == 1
-                      !!action.instance_exec(exception, &matcher)
-                    else
-                      !!action.instance_exec(&matcher)
-                    end
-                  elsif matcher.is_a?(String) || matcher.is_a?(Symbol)
-                    klass = Object.const_get(matcher.to_s)
-                    klass && exception.is_a?(klass)
-                  elsif matcher < Exception
-                    exception.is_a?(matcher)
-                  else
-                    action.warn("Ignoring matcher #{matcher.inspect} in rescues command")
-                  end
-
-        return stringified(value, exception:) if matches
-      end
-
-      nil
+      stringified(msg, exception:).presence || "Something went wrong"
     end
 
     # Allow for callable OR string messages
@@ -113,11 +92,22 @@ module Action
 
   # Outbound / External ContextFacade
   class Result < ContextFacade
+    # For ease of mocking return results in tests
+    class << self
+      def ok = Class.new { include(Action) }.call
+
+      def error(msg = "Something went wrong")
+        Class.new { include(Action) }.tap do |klass|
+          klass.define_method(:call) { fail!(msg) }
+        end.call
+      end
+    end
+
     # Poke some holes for necessary internal control methods
     delegate :called!, :rollback!, :each_pair, to: :context
 
     # External interface
-    delegate :success?, :failure?, :exception, to: :context
+    delegate :success?, :exception, to: :context
     def ok? = success?
 
     def error

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

@@ -4,8 +4,8 @@ require "active_model"
 require "active_support/core_ext/enumerable"
 require "active_support/core_ext/module/delegation"
 
-require "action/contract_validator"
-require "action/context_facade"
+require "action/core/contract_validator"
+require "action/core/context_facade"
 
 module Action
   module Contract
@@ -57,11 +57,19 @@ module Action
 
       private
 
+      RESERVED_FIELD_NAMES = %w[
+        declared_fields inspect fail!
+        default_error
+        called! rollback! each_pair success? exception ok ok? error success message
+      ].freeze
+
       def _parse_field_configs(*fields, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
                                **validations)
         # 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
 

data/lib/action/{exceptions.rb → core/exceptions.rb}

@@ -12,6 +12,8 @@ module Action
     end
 
     def message = @message.presence || "Execution was halted"
+
+    def inspect = "#<#{self.class.name} '#{message}'>"
   end
 
   class StepsRequiredForInheritanceSupportError < StandardError
@@ -33,6 +35,15 @@ module Action
   end
 
   class ContractViolation < StandardError
+    class ReservedAttributeError < ContractViolation
+      def initialize(name)
+        @name = name
+        super()
+      end
+
+      def message = "Cannot call expects or exposes with reserved field name: #{@name}"
+    end
+
     class MethodNotAllowed < ContractViolation; end
     class PreprocessingError < ContractViolation; end
 

data/lib/action/{hoist_errors.rb → core/hoist_errors.rb}

@@ -25,7 +25,7 @@ module Action
         result = begin
           yield
         rescue StandardError => e
-          warn "hoist_errors block swallowed an exception: #{e.message}"
+          log "hoist_errors block transforming a #{e.class.name} exception: #{e.message}"
           MinimalFailedResult.new(error: nil, exception: e)
         end
 
@@ -44,7 +44,8 @@ module Action
         @context.exception = result.exception if result.exception.present?
         @context.error_prefix = prefix if prefix.present?
 
-        fail! result.error
+        error = result.exception.is_a?(Action::Failure) ? result.exception.message : result.error
+        fail! error
       end
     end
   end

data/lib/action/{swallow_exceptions.rb → core/swallow_exceptions.rb}

@@ -2,20 +2,43 @@
 
 module Action
   module SwallowExceptions
+    CustomErrorInterceptor = Data.define(:matcher, :message, :should_report_error)
+    class CustomErrorInterceptor
+      def matches?(exception:, action:)
+        if matcher.respond_to?(:call)
+          if matcher.arity == 1
+            !!action.instance_exec(exception, &matcher)
+          else
+            !!action.instance_exec(&matcher)
+          end
+        elsif matcher.is_a?(String) || matcher.is_a?(Symbol)
+          klass = Object.const_get(matcher.to_s)
+          klass && exception.is_a?(klass)
+        elsif matcher < Exception
+          exception.is_a?(matcher)
+        else
+          action.warn("Ignoring apparently-invalid matcher #{matcher.inspect} -- could not find way to apply it")
+          false
+        end
+      rescue StandardError => e
+        action.warn("Ignoring #{e.class.name} raised while determining matcher: #{e.message}")
+        false
+      end
+    end
+
     def self.included(base)
       base.class_eval do
         class_attribute :_success_msg, :_error_msg
-        class_attribute :_error_rescues, default: []
+        class_attribute :_custom_error_interceptors, default: []
 
         include InstanceMethods
         extend ClassMethods
 
         def run_with_exception_swallowing!
           original_run!
-        rescue Action::Failure => e
-          # Just re-raise these (so we don't hit the unexpected-error case below)
-          raise e
         rescue StandardError => e
+          raise if e.is_a?(Action::Failure) # TODO: avoid raising if this was passed along from a child action (esp. if wrapped in hoist_errors)
+
           # Add custom hook for intercepting exceptions (e.g. Teamshares automatically logs to Honeybadger)
           trigger_on_exception(e)
 
@@ -36,6 +59,9 @@ module Action
         end
 
         def trigger_on_exception(e)
+          interceptor = self.class._error_interceptor_for(exception: e, action: self)
+          return if interceptor&.should_report_error == false
+
           Action.config.on_exception(e,
                                      action: self,
                                      context: respond_to?(:context_for_logging) ? context_for_logging : @context.to_h)
@@ -69,13 +95,32 @@ module Action
         true
       end
 
-      def rescues(matcher = nil, message = nil, **match_and_messages)
-        raise ArgumentError, "rescues must be called with a key, value pair or else keyword args" if [matcher, message].compact.size == 1
+      def error_from(matcher = nil, message = nil, **match_and_messages)
+        _register_error_interceptor(matcher, message, should_report_error: true, **match_and_messages)
+      end
 
-        { matcher => message }.compact.merge(match_and_messages).each { |mam| self._error_rescues += [mam] }
+      def rescues(matcher = nil, message = nil, **match_and_messages)
+        _register_error_interceptor(matcher, message, should_report_error: false, **match_and_messages)
       end
 
       def default_error = new.internal_context.default_error
+
+      # Private helpers
+
+      def _error_interceptor_for(exception:, action:)
+        Array(_custom_error_interceptors).detect do |int|
+          int.matches?(exception:, action:)
+        end
+      end
+
+      def _register_error_interceptor(matcher, message, should_report_error:, **match_and_messages)
+        method_name = should_report_error ? "error_from" : "rescues"
+        raise ArgumentError, "#{method_name} must be called with a key/value pair, or else keyword args" if [matcher, message].compact.size == 1
+
+        { matcher => message }.compact.merge(match_and_messages).each do |(matcher, message)| # rubocop:disable Lint/ShadowingOuterLocalVariable
+          self._custom_error_interceptors += [CustomErrorInterceptor.new(matcher:, message:, should_report_error:)]
+        end
+      end
     end
 
     module InstanceMethods

data/lib/axn/factory.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Axn
+  class Factory
+    class << self
+      # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
+      def build(
+        # Builder-specific options
+        superclass: nil,
+        expose_return_as: :nil,
+
+        # Expose standard class-level options
+        exposes: {},
+        expects: {},
+        messages: {},
+        before: nil,
+        after: nil,
+        around: nil,
+
+        # Allow dynamically assigning rollback method
+        rollback: nil,
+        &block
+      )
+        args = block.parameters.each_with_object(_hash_with_default_array) { |(type, name), hash| hash[type] << name }
+
+        if args[:opt].present? || args[:req].present? || args[:rest].present?
+          raise ArgumentError,
+                "[Axn::Factory] Cannot convert block to action: block expects positional arguments"
+        end
+        raise ArgumentError, "[Axn::Factory] Cannot convert block to action: block expects a splat of keyword arguments" if args[:keyrest].present?
+
+        # TODO: is there any way to support default arguments? (if so, set allow_blank: true for those)
+        if args[:key].present?
+          raise ArgumentError,
+                "[Axn::Factory] Cannot convert block to action: block expects keyword arguments with defaults (ruby does not allow introspecting)"
+        end
+
+        expects = _hydrate_hash(expects)
+        exposes = _hydrate_hash(exposes)
+
+        Array(args[:keyreq]).each do |name|
+          expects[name] ||= {}
+        end
+
+        # NOTE: inheriting from wrapping class, so we can set default values (e.g. for HTTP headers)
+        Class.new(superclass || Object) do
+          include Action unless self < Action
+
+          define_method(:call) do
+            unwrapped_kwargs = Array(args[:keyreq]).each_with_object({}) do |name, hash|
+              hash[name] = public_send(name)
+            end
+
+            retval = instance_exec(**unwrapped_kwargs, &block)
+            expose(expose_return_as => retval) if expose_return_as.present?
+          end
+        end.tap do |axn| # rubocop: disable Style/MultilineBlockChain
+          expects.each do |name, opts|
+            axn.expects(name, **opts)
+          end
+
+          exposes.each do |name, opts|
+            axn.exposes(name, **opts)
+          end
+
+          axn.messages(**messages) if messages.present?
+
+          # Hooks
+          axn.before(before) if before.present?
+          axn.after(after) if after.present?
+          axn.around(around) if around.present?
+
+          # Rollback
+          if rollback.present?
+            raise ArgumentError, "[Axn::Factory] Rollback must be a callable" unless rollback.respond_to?(:call) && rollback.respond_to?(:arity)
+            raise ArgumentError, "[Axn::Factory] Rollback must be a callable with no arguments" unless rollback.arity.zero?
+
+            axn.define_method(:rollback) do
+              instance_exec(&rollback)
+            end
+          end
+
+          # Default exposure
+          axn.exposes(expose_return_as, allow_blank: true) if expose_return_as.present?
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
+
+      private
+
+      def _hash_with_default_array = Hash.new { |h, k| h[k] = [] }
+
+      def _hydrate_hash(given)
+        return given if given.is_a?(Hash)
+
+        Array(given).each_with_object({}) do |key, acc|
+          acc[key] = {}
+        end
+      end
+    end
+  end
+end

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.1.1"
+  VERSION = "0.1.0-alpha.2"
 end