action_figure 0.1.0 → 0.6.0

data/lib/action_figure/core.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module ActionFigure
+  # Provides the validation pipeline and DSL mixed into action classes via ActionFigure.[].
+  module Core
+    # Extended into dry-validation contract classes to provide cross-param rule helpers.
+    module CrossParamRuleHelpers
+      def exclusive_rule(*fields, message)
+        rule(*fields) do
+          present = fields.select { |f| values.key?(f) && !values[f].nil? }
+          present.each { |f| key(f).failure(message) } if present.size > 1
+        end
+      end
+
+      def any_rule(*fields, message)
+        rule(*fields) do
+          present = fields.select { |f| values.key?(f) && !values[f].nil? }
+          fields.each { |f| key(f).failure(message) } if present.empty?
+        end
+      end
+
+      def one_rule(*fields, message)
+        rule(*fields) do
+          present = fields.select { |f| values.key?(f) && !values[f].nil? }
+          fields.each { |f| key(f).failure(message) } unless present.size == 1
+        end
+      end
+
+      def all_rule(*fields, message)
+        rule(*fields) do
+          present = fields.select { |f| values.key?(f) && !values[f].nil? }
+          fields.each { |f| key(f).failure(message) } unless present.empty? || present.size == fields.size
+        end
+      end
+    end
+
+    # DSL class methods extended into action classes: params_schema, rules, entry_point.
+    #
+    # Note: ActionFigure does not support class inheritance. +params_schema+, +rules+, and
+    # +entry_point+ store state in class-level instance variables that are not inherited by
+    # subclasses. Define each action class independently.
+    module ClassMethods
+      def params_schema(&block)
+        if @params_schema_block && @rules_block
+          raise ArgumentError,
+                "params_schema already defined with rules — " \
+                "redefining it would silently drop the existing rules block"
+        end
+
+        @params_schema_block = block
+        @contract = nil
+      end
+
+      def rules(&block)
+        raise ArgumentError, "rules requires params_schema to be defined" unless @params_schema_block
+
+        @rules_block = block
+        @contract = nil
+      end
+
+      # Declares an alternative entry point method name (e.g. +entry_point :search+).
+      # May only be called once per class. Inheritance of action classes is not supported —
+      # +params_schema+, +rules+, and +entry_point+ are not inherited by subclasses.
+      def entry_point(name)
+        if @entry_point_name
+          raise ArgumentError,
+                "entry_point already defined as '#{@entry_point_name}' — " \
+                "each action class may declare only one entry point"
+        end
+
+        @explicit_entry_point = true
+        @entry_point_name = name
+        singleton_class.define_method(name) do |**kwargs|
+          notify { new.validated_call(**kwargs) }
+        end
+      end
+
+      def entry_point_name
+        @entry_point_name
+      end
+
+      def api_version(value = :_unset)
+        value == :_unset ? @api_version : (@api_version = value)
+      end
+
+      def contract
+        return nil unless @params_schema_block
+
+        @contract ||= build_contract
+      end
+
+      private
+
+      # no-op when notifications aren't turned on
+      def notify
+        yield
+      end
+
+      def method_added(name)
+        return if @explicit_entry_point
+        return unless public_method_defined?(name)
+        return unless instance_method(name).owner == self
+
+        if @entry_point_name
+          raise IndeterminantEntryPointError,
+                "Multiple public methods defined in #{self}: " \
+                ":#{@entry_point_name} and :#{name}. " \
+                "Either make one private or declare " \
+                "`entry_point :#{@entry_point_name}` to disambiguate."
+        end
+
+        @entry_point_name = name
+        singleton_class.define_method(name) do |**kwargs|
+          notify { new.validated_call(**kwargs) }
+        end
+      ensure
+        super
+      end
+
+      def build_contract
+        schema_block = @params_schema_block
+        rules_block = @rules_block
+
+        contract_class = Class.new(Dry::Validation::Contract) do
+          extend ActionFigure::Core::CrossParamRuleHelpers
+
+          params(&schema_block)
+          class_eval(&rules_block) if rules_block
+        end
+
+        contract_class.new
+      end
+    end
+
+    def entry_point_name
+      self.class.entry_point_name
+    end
+
+    def contract
+      self.class.contract
+    end
+
+    def validated_call(**kwargs)
+      kwargs = normalize_params(kwargs)
+
+      if contract && kwargs.key?(:params)
+        validate_and_call(**kwargs)
+      else
+        public_send(entry_point_name, **kwargs)
+      end
+    end
+
+    # Overrides ClassMethods#notify with ActiveSupport::Notifications when available.
+    # Extended onto action classes at include-time so the check happens once, not per call.
+    module Notifications
+      private
+
+      def notify
+        payload = { action: name }
+        ActiveSupport::Notifications.instrument("process.action_figure", payload) do
+          result = yield
+          payload[:status] = result[:status]
+          result
+        end
+      end
+    end
+
+    private
+
+    def normalize_params(kwargs)
+      raw = kwargs[:params]
+      return kwargs unless raw.respond_to?(:to_unsafe_h)
+
+      kwargs.merge(params: raw.to_unsafe_h)
+    end
+
+    def validate_and_call(**kwargs)
+      result = contract.call(kwargs[:params])
+
+      return UnprocessableContent(errors: result.errors.to_h) if result.failure?
+
+      extra_params_error = check_extra_params(kwargs[:params], result)
+      return extra_params_error if extra_params_error
+
+      public_send(entry_point_name, **kwargs.except(:params), params: result.to_h)
+    end
+
+    def check_extra_params(raw_params, result)
+      return unless ActionFigure.configuration.whiny_extra_params
+
+      extra_keys = raw_params.keys.map(&:to_sym) - result.to_h.keys
+      return if extra_keys.empty?
+
+      errors = extra_keys.to_h { |k| [k, ["is not allowed"]] }
+      UnprocessableContent(errors: errors)
+    end
+  end
+end

data/lib/action_figure/format_registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+module ActionFigure
+  # Provides formatter registration and lookup for ActionFigure.
+  module FormatRegistry
+    # Stores the mapping of format names to formatter modules.
+    class Formats
+      def initialize
+        @formats = Concurrent::Map.new
+      end
+
+      def register_formatter(**formatters)
+        formatters.each { |name, mod| @formats[name] = mod }
+      end
+
+      def fetch(name)
+        @formats.fetch(name) do
+          raise ArgumentError,
+                "Unknown formatter: #{name}. Register it with ActionFigure.register_formatter(#{name}: MyFormatter)."
+        end
+      end
+    end
+
+    def register_formatter(**formatters)
+      format_registry.register_formatter(**formatters)
+    end
+
+    def fetch(name)
+      format_registry.fetch(name)
+    end
+
+    private
+
+    def format_registry
+      @format_registry ||= Formats.new
+    end
+  end
+end

data/lib/action_figure/formatter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  # Base module for ActionFigure response formatters.
+  # Include this in your formatter module to get a NoContent default
+  # and to signal that your module implements the formatter interface.
+  module Formatter
+    REQUIRED_METHODS = %i[Ok Created Accepted UnprocessableContent NotFound Forbidden Conflict PaymentRequired].freeze
+
+    def NoContent
+      { status: :no_content }
+    end
+  end
+end

data/lib/action_figure/formatters/default.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Formatters
+    # Implements Rails-style response helpers for use in action classes.
+    # Success responses use a { data: } envelope; errors live under an "errors" key on failure.
+    module Default
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil)
+        body = { data: resource }
+        body[:meta] = meta if meta
+        { json: body, status: :ok }
+      end
+
+      def Created(resource:, meta: nil)
+        body = { data: resource }
+        body[:meta] = meta if meta
+        { json: body, status: :created }
+      end
+
+      def Accepted(resource: nil, meta: nil)
+        body = { data: resource }
+        body[:meta] = meta if meta
+        { json: body, status: :accepted }
+      end
+
+      def UnprocessableContent(errors:)
+        { json: { errors: errors }, status: :unprocessable_content }
+      end
+
+      def NotFound(errors:)
+        { json: { errors: errors }, status: :not_found }
+      end
+
+      def Forbidden(errors:)
+        { json: { errors: errors }, status: :forbidden }
+      end
+
+      def Conflict(errors:)
+        { json: { errors: errors }, status: :conflict }
+      end
+
+      def PaymentRequired(errors:)
+        { json: { errors: errors }, status: :payment_required }
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/jsend.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Formatters
+    # Implements JSend response helpers for use in action classes.
+    module Jsend
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil)
+        body = { status: "success", data: resource }
+        body[:meta] = meta if meta
+        { json: body, status: :ok }
+      end
+
+      def Created(resource:, meta: nil)
+        body = { status: "success", data: resource }
+        body[:meta] = meta if meta
+        { json: body, status: :created }
+      end
+
+      def Accepted(resource: nil, meta: nil)
+        body = { status: "success" }
+        body[:data] = resource unless resource.nil?
+        body[:meta] = meta if meta
+        { json: body, status: :accepted }
+      end
+
+      def UnprocessableContent(errors:)
+        { json: { status: "fail", data: errors }, status: :unprocessable_content }
+      end
+
+      def NotFound(errors:)
+        { json: { status: "fail", data: errors }, status: :not_found }
+      end
+
+      def Forbidden(errors:)
+        { json: { status: "fail", data: errors }, status: :forbidden }
+      end
+
+      def Conflict(errors:)
+        { json: { status: "fail", data: errors }, status: :conflict }
+      end
+
+      def PaymentRequired(errors:)
+        { json: { status: "fail", data: errors }, status: :payment_required }
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/json_api/resource.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Formatters
+    module JsonApi
+      # Simple resource serialization
+      class Resource
+        def self.serialize(resource)
+          if resource.respond_to?(:attributes)
+            serialize_one(resource)
+          elsif !resource.is_a?(Hash) && resource.respond_to?(:each)
+            resource.map { |r| serialize(r) }
+          else
+            resource
+          end
+        end
+
+        def self.serialize_one(resource)
+          {
+            type: resource.class.model_name.element,
+            id: resource.id.to_s,
+            attributes: resource.attributes.except("id")
+          }
+        end
+
+        private_class_method :serialize_one
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/json_api.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "json_api/resource"
+
+module ActionFigure
+  module Formatters
+    # Implements JSON:API response helpers for use in action classes.
+    module JsonApi
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil)
+        body = { data: Resource.serialize(resource) }
+        body[:meta] = meta if meta
+        { json: body, status: :ok }
+      end
+
+      def Created(resource:, meta: nil)
+        body = { data: Resource.serialize(resource) }
+        body[:meta] = meta if meta
+        { json: body, status: :created }
+      end
+
+      def Accepted(resource: nil, meta: nil)
+        body = resource.nil? ? {} : { data: Resource.serialize(resource) }
+        body[:meta] = meta if meta
+        { json: body, status: :accepted }
+      end
+
+      def UnprocessableContent(errors:)
+        { json: { errors: convert_errors(errors, "422") }, status: :unprocessable_content }
+      end
+
+      def NotFound(errors:)
+        { json: { errors: convert_errors(errors, "404") }, status: :not_found }
+      end
+
+      def Forbidden(errors:)
+        { json: { errors: convert_errors(errors, "403") }, status: :forbidden }
+      end
+
+      def Conflict(errors:)
+        { json: { errors: convert_errors(errors, "409") }, status: :conflict }
+      end
+
+      def PaymentRequired(errors:)
+        { json: { errors: convert_errors(errors, "402") }, status: :payment_required }
+      end
+
+      private
+
+      def convert_errors(errors, status)
+        errors.flat_map do |field, messages|
+          pointer = field.to_sym == :base ? "/data" : "/data/attributes/#{field}"
+          messages.map do |message|
+            {
+              status: status,
+              detail: message,
+              source: { pointer: pointer }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/wrapped.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Formatters
+    # Implements uniform envelope response helpers for use in action classes.
+    # Every response uses the same { data:, errors:, status: } shape.
+    module Wrapped
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil)
+        body = { data: resource, errors: nil, status: "success" }
+        body[:meta] = meta if meta
+        { json: body, status: :ok }
+      end
+
+      def Created(resource:, meta: nil)
+        body = { data: resource, errors: nil, status: "success" }
+        body[:meta] = meta if meta
+        { json: body, status: :created }
+      end
+
+      def Accepted(resource: nil, meta: nil)
+        body = { data: resource, errors: nil, status: "success" }
+        body[:meta] = meta if meta
+        { json: body, status: :accepted }
+      end
+
+      def UnprocessableContent(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :unprocessable_content }
+      end
+
+      def NotFound(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :not_found }
+      end
+
+      def Forbidden(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :forbidden }
+      end
+
+      def Conflict(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :conflict }
+      end
+
+      def PaymentRequired(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :payment_required }
+      end
+    end
+  end
+end

data/lib/action_figure/testing/minitest.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Testing
+    # Minitest assertions for ActionFigure response results.
+    #
+    # Include in your test class to get assert_Ok, assert_Created, etc.:
+    #
+    #   class Users::CreateTest < Minitest::Test
+    #     include ActionFigure::Testing::Minitest
+    #   end
+    module Minitest
+      def assert_Ok(result, msg = nil)
+        assert_status(:ok, result, msg)
+      end
+
+      def assert_Created(result, msg = nil)
+        assert_status(:created, result, msg)
+      end
+
+      def assert_Accepted(result, msg = nil)
+        assert_status(:accepted, result, msg)
+      end
+
+      def assert_NoContent(result, msg = nil)
+        assert_status(:no_content, result, msg)
+      end
+
+      def assert_UnprocessableContent(result, msg = nil)
+        assert_status(:unprocessable_content, result, msg)
+      end
+
+      def assert_NotFound(result, msg = nil)
+        assert_status(:not_found, result, msg)
+      end
+
+      def assert_Forbidden(result, msg = nil)
+        assert_status(:forbidden, result, msg)
+      end
+
+      def assert_Conflict(result, msg = nil)
+        assert_status(:conflict, result, msg)
+      end
+
+      def assert_PaymentRequired(result, msg = nil)
+        assert_status(:payment_required, result, msg)
+      end
+
+      private
+
+      def assert_status(expected, result, msg)
+        actual = result[:status]
+        message = msg || "Expected result status to be #{expected.inspect}, but got #{actual.inspect}"
+        assert actual == expected, message
+      end
+    end
+  end
+end

data/lib/action_figure/testing/rspec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "rspec/matchers"
+
+module ActionFigure
+  module Testing
+    # RSpec custom matchers for ActionFigure response results.
+    #
+    # Require in your spec_helper.rb to get be_Ok, be_Created, etc.:
+    #
+    #   require 'action_figure/testing/rspec'
+    #
+    #   RSpec.describe Users::Create do
+    #     it "returns ok" do
+    #       expect(Users::Create.call(params: ...)).to be_Ok
+    #     end
+    #   end
+    module RSpec
+      MATCHERS = {
+        Ok: :ok,
+        Created: :created,
+        Accepted: :accepted,
+        NoContent: :no_content,
+        UnprocessableContent: :unprocessable_content,
+        NotFound: :not_found,
+        Forbidden: :forbidden,
+        Conflict: :conflict,
+        PaymentRequired: :payment_required
+      }.freeze
+
+      MATCHERS.each do |name, status|
+        ::RSpec::Matchers.define :"be_#{name}" do
+          match { |result| result[:status] == status }
+          failure_message do |result|
+            "expected result status to be #{status.inspect}, but got #{result[:status].inspect}"
+          end
+          failure_message_when_negated do
+            "expected result not to have status #{status.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_figure/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionFigure
-  VERSION = "0.1.0"
+  VERSION = "0.6.0"
 end

data/lib/action_figure.rb

@@ -1,6 +1,74 @@
 # frozen_string_literal: true
 
 require_relative "action_figure/version"
+require_relative "action_figure/configuration"
+require_relative "action_figure/format_registry"
+require_relative "action_figure/formatter"
+require_relative "action_figure/core"
+require_relative "action_figure/formatters/jsend"
+require_relative "action_figure/formatters/json_api"
+require_relative "action_figure/formatters/default"
+require_relative "action_figure/formatters/wrapped"
 
+# ActionFigure provides explicit, purpose-driven operation classes for Rails controller actions.
 module ActionFigure
+  extend Configuration
+  extend FormatRegistry
+
+  class IndeterminantEntryPointError < StandardError; end
+
+  register_formatter(jsend: Formatters::Jsend)
+  register_formatter(jsonapi: Formatters::JsonApi)
+  register_formatter(default: Formatters::Default)
+  register_formatter(wrapped: Formatters::Wrapped)
+
+  def self.[](format = configuration.format)
+    format_modules.compute_if_absent(format) { build_format_module(format, fetch(format)) }
+  end
+
+  def self.included(base)
+    base.include(self[])
+  end
+
+  def self.register_formatter(**formatters)
+    formatters.each_value do |mod|
+      missing = Formatter::REQUIRED_METHODS.reject { |m| mod.method_defined?(m) }
+      raise ArgumentError, "#{mod} is missing formatter methods: #{missing.join(", ")}" if missing.any?
+    end
+    formatters.each_key { |name| clear_format_module_cache(name) }
+    super
+  end
+
+  def self.clear_format_module_cache(name)
+    format_modules.delete(name)
+  end
+
+  def self.build_format_module(name, formatter)
+    mod = new_format_module(formatter)
+    const_name = :"Format_#{name}"
+    remove_const(const_name) if const_defined?(const_name, false)
+    const_set(const_name, mod)
+  end
+  private_class_method :build_format_module
+
+  def self.new_format_module(formatter)
+    Module.new do
+      def self.included(base)
+        base.extend(ActionFigure::Core::ClassMethods)
+        return unless defined?(ActiveSupport::Notifications) &&
+                      ActionFigure.configuration.activesupport_notifications
+
+        base.extend(ActionFigure::Core::Notifications)
+      end
+
+      include ActionFigure::Core
+      include formatter
+    end
+  end
+  private_class_method :new_format_module
+
+  def self.format_modules
+    @format_modules ||= Concurrent::Map.new
+  end
+  private_class_method :format_modules
 end