axn 0.1.0.pre.alpha.1

data/docs/reference/instance.md

@@ -0,0 +1,17 @@
+::: danger ALPHA
+* TODO: convert this rough outline into actual documentation
+:::
+
+
+While coding:
+* `expose`
+* `fail!`
+* `log`
+* `try` - any exceptions raised by the block will trigger the on_exception handler, but then will be swallowed (the action is _not_ failed)
+    * Edge case: explicit `fail!` calls _will_ still fail the action
+* `hoist_errors`
+    * Edge case: intent is a single action call in the block -- if there are multiple calls, only the last one will be checked (anything explicitly _raised_ will still be handled).
+    <!-- TODO: is there difference between `SubAction.call!` and `hoist_errors { SubAction.call }`?? -->
+* `context_for_logging` (and decent #inspect support)
+
+

data/docs/usage/conventions.md

@@ -0,0 +1,38 @@
+---
+outline: deep
+---
+
+# Conventions
+
+This page serves as a repository for various softly-held opinions about _how_ it makes sense to use the library.
+
+::: warning DRAFT
+These conventions are still in flux as the library is solidified and we gain more experience using it in production. Take these notes with a grain of salt.
+:::
+
+## Organizing Actions (Rails)
+
+You _can_ `include Action` into _any_ Ruby class, but to keep track of things we've found it helpful to:
+
+  * Create a new `app/actions` folder for our actions
+  * Name them `Actions::[DOMAIN]::[VERB]` where `[DOMAIN]` is a (possibly nested) identifier and `[VERB]` is the action to be taken.
+
+    Examples:
+      * `Actions::User::Create`
+      * `Actions::Slack::Notify`
+
+For us, we've found the maintenance benefits of knowing roughly how the class will behave just by glancing at the name has been worth being a bit pedantic about the naming.
+
+## Naming conventions
+
+### The responsible user
+When tracking _who_ is responsible for the action being taken, one option is to inject it globally via `Current.user` (see: [Current Attributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html)), but that only works if you're _sure_ you're never going to want to enqueue the job on a background processor.
+
+More generally, we've adopted the convention of passing in the responsible user as `actor`:
+
+  ```ruby
+  class Foo
+    include Action
+    expects :actor, type: User # [!code focus]
+  end
+  ```

data/docs/usage/setup.md

@@ -0,0 +1,26 @@
+---
+outline: deep
+---
+# Getting Started
+
+## Installation
+
+Adding `axn` to your Gemfile is enough to start using `include Action`.
+<!-- todo bundler -->
+
+
+## Global Configuration
+
+A few configuration steps are _highly_ recommended to get the full benefits (e.g. making sure all your swallowed exceptions are getting reported to your error tracking service).
+
+The full set of available configuration settings is documented [over here](/reference/configuration), but there are two worth calling out specifically:
+
+### Error Tracking
+
+By default any swallowed errors are noted in the logs, but it's _highly recommended_ to [wire up an `on_exception` handler](/reference/configuration#on-exception).
+
+### Metrics / Tracing
+
+If you're using an APM provider, observability can be greatly enhanced by [configuring a `top_level_around_hook`](/reference/configuration#top-level-around-hook).
+
+

data/docs/usage/testing.md

@@ -0,0 +1,13 @@
+# Testing
+
+::: danger ALPHA
+* TODO: document testing patterns
+:::
+
+Configuring rspec to treat files in spec/actions as service specs:
+
+```ruby
+config.define_derived_metadata(file_path: %r{spec/actions}) do |metadata|
+  metadata[:type] = :service
+end
+```

data/docs/usage/using.md

@@ -0,0 +1,65 @@
+---
+outline: deep
+---
+
+
+# How to _use_ an Action
+
+## Common Case
+
+An action is usually executed via `#call`, and _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.
+
+As a consumer, you usually want a conditional that surfaces `error` unless the result is `ok?`, and otherwise takes whatever success action is relevant.
+
+For example:
+
+```ruby
+class MessagesController < ApplicationController
+  def create
+    result = Actions::Slack::Post.call( # [!code focus]
+      channel: "#engineering",
+      message: params[:message],
+    )
+
+    if result.ok?  # [!code focus:2]
+      @thread_id = result.thread_id # Because `thread_id` was explicitly exposed
+      flash.now[:success] = "Sent the Slack message"
+    else
+      flash[:alert] = result.error # [!code focus]
+      redirect_to action: :new
+    end
+  end
+end
+```
+
+<!-- TODO: replace manual flash success with result.success (here and in guide?) -->
+
+
+## Advanced Usage
+
+### `#call!`
+
+::: danger ALPHA
+* TODO - flesh out this section
+:::
+
+
+* `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)
+
+
+### `#enqueue`
+
+Before adopting this library, our code was littered with one-line workers whose only job was to fire off a service on a background job.  We were able to remove that entire glue layer by directly supporting enqueueing sidekiq jobs from the Action itself.
+
+::: danger ALPHA
+Sidekiq integration is NOT YET TESTED/NOT YET USED IN OUR APP, and naming will VERY LIKELY change to make it clearer which actions will be retried!
+:::
+
+* enqueue vs enqueue!
+    * 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)

data/docs/usage/writing.md

@@ -0,0 +1,118 @@
+---
+outline: deep
+---
+
+# How to _build_ an Action
+
+The core boilerplate is pretty minimal:
+
+```ruby
+class Foo
+  include Action
+
+  def call
+    # ... do some stuff here?
+  end
+end
+```
+
+## Declare the interface
+
+The first step is to determine what arguments you expect to be passed into `call`.  These are declared via the `expects` keyword.
+
+If you want to expose any results to the caller, declare that via the `exposes` keyword.
+
+Both of these optionally accept `type:`, `allow_blank:`, and any other ActiveModel validation (see: [reference](/reference/class)).
+
+
+```ruby
+class Foo
+  include Action
+
+  expects :name, type: String # [!code focus:2]
+  exposes :meaning_of_life
+
+  def call
+    # ... do some stuff here?
+  end
+end
+```
+
+## Implement the action
+
+Once the interface is defined, you're primarily focused on defining the `call` method.
+
+To abort execution with a specific error message, call `fail!`.
+
+If you declare that your action `exposes` anything, you need to actually `expose` it.
+
+```ruby
+class Foo
+  include Action
+
+  expects :name, type: String
+  exposes :meaning_of_life
+
+  def call
+    fail! "Douglas already knows the meaning" if name == "Doug" # [!code focus]
+
+    msg = "Hello #{name}, the meaning of life is 42"
+    expose meaning_of_life: msg # [!code focus]
+  end
+end
+```
+
+See [the reference doc](/reference/instance) for a few more handy helper methods (e.g. `#log`).
+
+## Customizing messages
+
+::: danger ALPHA
+* TODO: document `messages` setup
+:::
+
+
+## Lifecycle methods
+
+In addition to `#call`, there are a few additional pieces to be aware of:
+
+### `#rollback`
+
+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.
+
+### Concrete example
+
+Given this series of methods and hooks:
+
+```ruby
+class Foo
+  include Action
+
+  before { log("before hook") }
+  after { log("after hook") }
+
+  def call
+    log("in call")
+    raise "oh no something borked"
+  end
+
+  def rollback
+    log("rolling back")
+  end
+end
+```
+
+`Foo.call` would fail (because of the raise), but along the way would end up logging:
+
+```text
+before hook
+in call
+after hook
+rolling back
+```
+
+## Debugging
+Remember you can [enable debug logging](/reference/configuration.html#global-debug-logging) to print log lines before and after each action is executed.

data/lib/action/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Action
+  class Configuration
+    include Action::Logging
+    attr_accessor :global_debug_logging, :top_level_around_hook
+    attr_writer :logger, :env, :on_exception, :additional_includes
+
+    def global_debug_logging? = !!global_debug_logging
+
+    def additional_includes = @additional_includes ||= []
+
+    def on_exception(e, action:, context: {})
+      if @on_exception
+        # TODO: only pass action: or context: if requested
+        @on_exception.call(e, action:, context:)
+      else
+        log("[#{action.class.name.presence || "Anonymous Action"}] Exception swallowed: #{e.class.name} - #{e.message}")
+      end
+    end
+
+    def logger
+      @logger ||= begin
+        Rails.logger
+      rescue NameError
+        Logger.new($stdout).tap do |l|
+          l.level = Logger::INFO
+        end
+      end
+    end
+
+    def env
+      @env ||= ENV["RACK_ENV"].presence || ENV["RAILS_ENV"].presence || "development"
+      ActiveSupport::StringInquirer.new(@env)
+    end
+  end
+
+  class << self
+    def config = @config ||= Configuration.new
+
+    def configure
+      self.config ||= Configuration.new
+      yield(config) if block_given?
+    end
+  end
+end

data/lib/action/context_facade.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "active_support/parameter_filter"
+
+module Action
+  class ContextFacade
+    def initialize(action:, context:, declared_fields:, implicitly_allowed_fields: nil)
+      if self.class.name == "Action::ContextFacade" # rubocop:disable Style/ClassEqualityComparison
+        raise "Action::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|
+        singleton_class.define_method(field) { @context.public_send(field) }
+      end
+    end
+
+    attr_reader :declared_fields
+
+    def inspect = Inspector.new(facade: self, action:, context:).call
+
+    def fail!(...)
+      raise Action::ContractViolation::MethodNotAllowed, "Call fail! directly rather than on the context"
+    end
+
+    private
+
+    attr_reader :action, :context
+
+    def exposure_method_name = raise NotImplementedError
+
+    # Add nice error message for missing methods
+    def method_missing(method_name, ...) # rubocop:disable Style/MissingRespondToMissing (because we're not actually responding to anything additional)
+      if context.respond_to?(method_name)
+        msg = <<~MSG
+          Method ##{method_name} is not available on #{self.class.name}!
+
+          #{@action.class.name || "The action"} may be missing a line like:
+            #{exposure_method_name} :#{method_name}
+        MSG
+
+        raise Action::ContractViolation::MethodNotAllowed, msg
+      end
+
+      super
+    end
+
+    def determine_error_message(only_default: false)
+      return @context.error_from_user if @context.error_from_user.present?
+
+      unless only_default
+        msg = message_from_rescues
+        return msg if msg.present?
+      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
+    end
+
+    # Allow for callable OR string messages
+    def stringified(msg, exception: nil)
+      return msg.presence unless msg.respond_to?(:call)
+
+      # The error message callable can take the exception as an argument
+      if exception && msg.arity == 1
+        action.instance_exec(exception, &msg)
+      else
+        action.instance_exec(&msg)
+      end
+    rescue StandardError => e
+      action.warn("Ignoring #{e.class.name} raised while determining message callable: #{e.message}")
+      nil
+    end
+  end
+
+  # Inbound / Internal ContextFacade
+  class InternalContext < ContextFacade
+    # So can be referenced from within e.g. rescues callables
+    def default_error
+      [@context.error_prefix, determine_error_message(only_default: true)].compact.join(" ").squeeze(" ")
+    end
+
+    private
+
+    def exposure_method_name = :gets
+  end
+
+  # Outbound / External ContextFacade
+  class Result < ContextFacade
+    # Poke some holes for necessary internal control methods
+    delegate :called!, :rollback!, :each_pair, to: :context
+
+    # External interface
+    delegate :success?, :failure?, :exception, to: :context
+    def ok? = success?
+
+    def error
+      return if ok?
+
+      [@context.error_prefix, determine_error_message].compact.join(" ").squeeze(" ")
+    end
+
+    def success
+      return unless ok?
+
+      stringified(action._success_msg).presence || "Action completed successfully"
+    end
+
+    def ok = success
+
+    def message = error || success
+
+    private
+
+    def exposure_method_name = :sets
+  end
+
+  class Inspector
+    def initialize(action:, facade:, context:)
+      @action = action
+      @facade = facade
+      @context = context
+    end
+
+    def call
+      str = [status, visible_fields].compact_blank.join(" ")
+
+      "#<#{class_name} #{str}>"
+    end
+
+    private
+
+    attr_reader :action, :facade, :context
+
+    def status
+      return unless facade.is_a?(Action::Result)
+
+      return "[OK]" if context.success?
+      return "[failed with '#{context.error_from_user}']" unless context.exception
+
+      %([failed with #{context.exception.class.name}: '#{context.exception.message}'])
+    end
+
+    def visible_fields
+      declared_fields.map do |field|
+        value = facade.public_send(field)
+
+        "#{field}: #{format_for_inspect(field, value)}"
+      end.join(", ")
+    end
+
+    def class_name = facade.class.name
+    def declared_fields = facade.send(:declared_fields)
+
+    def format_for_inspect(field, value)
+      return value.inspect if value.nil?
+
+      # Initially based on https://github.com/rails/rails/blob/800976975253be2912d09a80757ee70a2bb1e984/activerecord/lib/active_record/attribute_methods.rb#L527
+      inspected_value = if value.is_a?(String) && value.length > 50
+                          "#{value[0, 50]}...".inspect
+                        elsif value.is_a?(Date) || value.is_a?(Time)
+                          %("#{value.to_fs(:inspect)}")
+                        elsif defined?(::ActiveRecord::Relation) && value.instance_of?(::ActiveRecord::Relation)
+                          # Avoid hydrating full AR relation (i.e. avoid loading records just to report an error)
+                          "#{value.name}::ActiveRecord_Relation"
+                        else
+                          value.inspect
+                        end
+
+      inspection_filter.filter_param(field, inspected_value)
+    end
+
+    def inspection_filter = action.send(:inspection_filter)
+  end
+end