mime_actor 0.6.1 → 0.6.3.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5a67bb80dd83c069ea2f06a4afea5e241987d8b9a2a30f0a3eb0d01748b3759
-  data.tar.gz: acb0cd8b89e39ea3962c0949bff4666c96c36f6c15eae5a3709775daa5ef2516
+  metadata.gz: 5221de8b1d1149a88de730ab8e6c6c764a22e7067b9e57b6265ce801c671ce3f
+  data.tar.gz: e98f9d6f3e5a8aa04f16cf77921edad0b4a61893ddb3c019157885079462fcde
 SHA512:
-  metadata.gz: e64c6a62feb248b76672d75ef4cf9bc0f822b0f2fd57311f879874e910377b80549b133c85b148fd61d44d91259c780299770d7fae4792dbab094c01676df201
-  data.tar.gz: 2577dc3d03d3fa233ba136613e63d0c18a3e59f51bac690b582b18f424cc4ee7e5fee736eafc76393a94af20e3fcf930cd953b4eec07f21282fa9b5dd7be552d
+  metadata.gz: 9f6ce7e70ab30a4be726f346beb517c8036c95a1d516c3012d9ed62723a14c130d4af05cdf3695244f5fcb56d33f83cf719369ead9d05eabeba89e5335de1f3a
+  data.tar.gz: 90e8ca69ac9ff99e9813c1dac19bc0826893f106968bb6c6684201a84523b13ab9df225fd597daf96379825080f9164ecfb19a6f7b48c8eabf217e5411654530

data/.rubocop.yml

@@ -16,6 +16,9 @@ Style/BlockComments:
   Exclude:
     - spec/*_helper.rb
 
+Style/RegexpLiteral:
+  EnforcedStyle: percent_r
+
 Metrics/AbcSize:
   Enabled: false
   

data/lib/mime_actor/action.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
+require "mime_actor/callbacks"
+require "mime_actor/logging"
 require "mime_actor/scene"
 require "mime_actor/stage"
-require "mime_actor/rescue"
 
 require "active_support/concern"
 require "active_support/core_ext/object/blank"
@@ -23,9 +26,9 @@ module MimeActor
     include AbstractController::Rendering # required by MimeResponds
     include ActionController::MimeResponds
 
+    include Callbacks
     include Scene
     include Stage
-    include Rescue
     include Logging
 
     # The core logic where rendering logics are collected as `Proc` and passed over to `ActionController::MimeResponds`
@@ -44,7 +47,6 @@ module MimeActor
     #   end
     #
     def start_scene(action)
-      action = action&.to_sym
       formats = acting_scenes.fetch(action, {})
 
       if formats.empty?
@@ -54,8 +56,10 @@ module MimeActor
 
       respond_to do |collector|
         formats.each do |format, actor|
-          dispatch = self.class.dispatch_cue(action: action, format: format, context: self) do
-            cue_actor(actor.presence || "#{action}_#{format}")
+          dispatch = lambda do
+            run_act_callbacks(format) do
+              cue_actor(actor.presence || "#{action}_#{format}", action:, format:)
+            end
           end
           collector.public_send(format, &dispatch)
         end

data/lib/mime_actor/callbacks.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+require "mime_actor/validator"
+
+require "active_support/callbacks"
+require "active_support/concern"
+require "active_support/core_ext/array/wrap"
+require "active_support/core_ext/object/blank"
+
+module MimeActor
+  # # MimeActor Callbacks
+  #
+  # MimeActor provides hooks during the life cycle of an act. Available callbacks are:
+  #
+  # - before_act
+  # - around_act
+  # - after_act
+  #
+  # NOTE: Calling the same callback multiple times will overwrite previous callback definitions.
+  #
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    include ActiveSupport::Callbacks
+    include MimeActor::Validator
+
+    included do
+      define_callbacks :act, skip_after_callbacks_if_terminated: true
+
+      %i[before after around].each { |kind| define_act_callbacks(kind) }
+    end
+
+    module ClassMethods
+      class ActionMatcher
+        def initialize(actions)
+          @actions = Array.wrap(actions).to_set(&:to_s)
+        end
+
+        def match?(controller)
+          @actions.include?(controller.action_name)
+        end
+
+        alias after  match?
+        alias before match?
+        alias around match?
+      end
+
+      def callback_chain_name(format = nil)
+        if format.present?
+          validate!(:format, format)
+          :"act_#{format}"
+        else
+          :act
+        end
+      end
+
+      def callback_chain_defined?(name)
+        !!get_callbacks(name)
+      end
+
+      private
+
+      def define_callback_chain(name)
+        return if callback_chain_defined?(name)
+
+        define_callbacks name, skip_after_callbacks_if_terminated: true
+      end
+
+      def configure_callbacks(callbacks, actions, formats, block)
+        options = {}
+        options[:if] = ActionMatcher.new(actions) if actions.present?
+        callbacks.push(block) if block
+
+        formats = Array.wrap(formats)
+        formats << nil if formats.empty?
+
+        callbacks.each do |callback|
+          formats.each do |format|
+            chain = callback_chain_name(format)
+            define_callback_chain(chain)
+            yield chain, callback, options
+          end
+        end
+      end
+
+      def validate_callback_options!(action, format)
+        validate!(:action_or_actions, action) if action.present?
+        validate!(:format_or_formats, format) if format.present?
+      end
+
+      def define_act_callbacks(kind)
+        module_eval(
+          # def self.before_act(*callbacks, action: nil, format: nil, &block)
+          #   validate_callback_options!(action, format)
+          #   configure_callbacks(callbacks, action, format, block) do |chain, callback, options|
+          #     set_callback(chain, :before, callback, options)
+          #   end
+          # end
+          #
+          # def self.prepend_before_act(*callbacks, action: nil, format: nil, &block)
+          #   validate_callback_options!(action, format)
+          #   configure_callbacks(callbacks, action, format, block) do |chain, callback, options|
+          #     set_callback(chain, :before, callback, options.merge!(prepend: true))
+          #   end
+          # end
+          <<-RUBY, __FILE__, __LINE__ + 1
+            def self.#{kind}_act(*callbacks, action: nil, format: nil, &block)
+              validate_callback_options!(action, format)
+              configure_callbacks(callbacks, action, format, block) do |chain, callback, options|
+                set_callback(chain, :#{kind}, callback, options)
+              end
+            end
+
+            def self.prepend_#{kind}_act(*callbacks, action: nil, format: nil, &block)
+              validate_callback_options!(action, format)
+              configure_callbacks(callbacks, action, format, block) do |chain, callback, options|
+                set_callback(chain, :#{kind}, callback, options.merge!(prepend: true))
+              end
+            end
+          RUBY
+        )
+      end
+    end
+
+    # Callbacks invocation sequence depends on the order of callback definition.
+    # (except for callbacks with `format` filter).
+    #
+    # @example callbacks with/without action filter
+    #   before_act :my_before_act_one
+    #   before_act :my_before_act_two, action: :create
+    #   before_act :my_before_act_three
+    #
+    #   around_act :my_around_act_one
+    #   around_act :my_around_act_two, action: :create
+    #   around_act :my_around_act_three
+    #
+    #   after_act :my_after_act_one
+    #   after_act :my_after_act_two, action: :create
+    #   after_act :my_after_act_three
+    #
+    #   # actual sequence:
+    #   # - my_before_act_one
+    #   # - my_before_act_two
+    #   # - my_before_act_three
+    #   # - my_around_act_one
+    #   # - my_around_act_two
+    #   # - my_around_act_three
+    #   # - my_after_act_three
+    #   # - my_after_act_two
+    #   # - my_after_act_one
+    #
+    # @example callbacks with format filter
+    #   before_act :my_before_act_one
+    #   before_act :my_before_act_two, action: :create
+    #   before_act :my_before_act_three, action: :create, format: :html
+    #   before_act :my_before_act_four
+    #
+    #   around_act :my_around_act_one
+    #   around_act :my_around_act_two, action: :create, format: :html
+    #   around_act :my_around_act_three, action: :create
+    #   around_act :my_around_act_four
+    #
+    #   after_act :my_after_act_one, format: :html
+    #   after_act :my_after_act_two
+    #   after_act :my_after_act_three, action: :create
+    #   after_act :my_after_act_four
+    #
+    #   # actual sequence:
+    #   # - my_before_act_one
+    #   # - my_before_act_two
+    #   # - my_before_act_four
+    #   # - my_around_act_one
+    #   # - my_around_act_three
+    #   # - my_around_act_four
+    #   # - my_before_act_three
+    #   # - my_around_act_two
+    #   # - my_after_act_one
+    #   # - my_after_act_four
+    #   # - my_after_act_three
+    #   # - my_after_act_two
+    #
+    def run_act_callbacks(format)
+      action_chain = self.class.callback_chain_name
+      format_chain = self.class.callback_chain_name(format)
+
+      if self.class.callback_chain_defined?(format_chain)
+        run_callbacks action_chain do
+          run_callbacks format_chain do
+            yield if block_given?
+          end
+        end
+      else
+        run_callbacks action_chain do
+          yield if block_given?
+        end
+      end
+    end
+  end
+end

data/lib/mime_actor/dispatcher.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+require "mime_actor/errors"
+
+module MimeActor
+  module Dispatcher
+    class MethodCall
+      attr_reader :method_name, :args
+
+      def initialize(method_name, *args)
+        @method_name = method_name
+        @args = args
+        validate!
+      end
+
+      def call(target)
+        raise MimeActor::ActorNotFound, method_name unless target.respond_to?(method_name)
+
+        method_call = target.method(method_name)
+        filtered_args = method_call.arity.negative? ? args : args.take(method_call.arity)
+        method_call.call(*filtered_args)
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "invalid method name: #{method_name.inspect}" unless method_name in String | Symbol
+      end
+    end
+
+    class InstanceExec
+      attr_reader :block, :args
+
+      def initialize(block, *args)
+        @block = block
+        @args = args
+        validate!
+      end
+
+      def call(target)
+        filtered_args = block.arity.negative? ? args : args.take(block.arity)
+        target.instance_exec(*filtered_args, &block)
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "invalid block: #{block.inspect}" unless block in Proc
+      end
+    end
+
+    def self.build(callable, *args)
+      case callable
+      when String, Symbol
+        MethodCall.new(callable, *args)
+      when Proc
+        InstanceExec.new(callable, *args)
+      end
+    end
+  end
+end

data/lib/mime_actor/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "set"
 
 module MimeActor

data/lib/mime_actor/rescue.rb

@@ -2,7 +2,7 @@
 
 # :markup: markdown
 
-require "mime_actor/stage"
+require "mime_actor/dispatcher"
 require "mime_actor/validator"
 
 require "active_support/concern"
@@ -22,7 +22,6 @@ module MimeActor
   module Rescue
     extend ActiveSupport::Concern
 
-    include Stage
     include Validator
 
     included do
@@ -50,19 +49,11 @@ module MimeActor
         raise ArgumentError, "error filter is required" if klazzes.empty?
         raise ArgumentError, "provide either the with: argument or a block" unless with.present? ^ block_given?
 
-        if block_given?
-          with = block
-        else
-          validate!(:with, with)
-        end
+        validate!(:with, with) if with.present?
+        with = block if block_given?
 
-        if action.present?
-          action.is_a?(Enumerable) ? validate!(:actions, action) : validate!(:action, action)
-        end
-
-        if format.present?
-          format.is_a?(Enumerable) ? validate!(:formats, format) : validate!(:format, format)
-        end
+        validate!(:action_or_actions, action) if action.present?
+        validate!(:format_or_formats, format) if format.present?
 
         klazzes.each do |klazz|
           validate!(:klazz, klazz)
@@ -139,5 +130,55 @@ module MimeActor
         end
       end
     end
+
+    # Resolve the error provided with the registered handlers.
+    #
+    # The handled error will be returned to indicate successful handling.
+    #
+    # @param error the error instance to rescue
+    # @param action the `action` filter
+    # @param format the `format` filter
+    # @param visited the errors to skip after no rescue handler matched the filter
+    #
+    def rescue_actor(error, action:, format:, visited: [])
+      return if visited.include?(error)
+
+      visited << error
+      rescuer = find_rescuer(error, format:, action:)
+      if (dispatch = MimeActor::Dispatcher.build(rescuer, error, format, action))
+        dispatch.call(self)
+        error
+      elsif error&.cause
+        rescue_actor(error.cause, format:, action:, visited:)
+      end
+    end
+
+    private
+
+    def find_rescuer(error, format:, action:)
+      return unless error
+
+      *_, rescuer = actor_rescuers.reverse_each.detect do |rescuee, format_filter, action_filter|
+        next if action_filter.present? && !Array.wrap(action_filter).include?(action)
+        next if format_filter.present? && !Array.wrap(format_filter).include?(format)
+        next unless (klazz = constantize_rescuee(rescuee))
+
+        error.is_a?(klazz)
+      end
+      rescuer
+    end
+
+    def constantize_rescuee(class_or_name)
+      case class_or_name
+      when String, Symbol
+        begin
+          const_get(class_or_name)
+        rescue NameError
+          class_or_name.safe_constantize
+        end
+      else
+        class_or_name
+      end
+    end
   end
 end

data/lib/mime_actor/scene.rb

@@ -6,7 +6,6 @@ require "mime_actor/errors"
 require "mime_actor/validator"
 
 require "active_support/concern"
-require "active_support/core_ext/array/extract_options"
 require "active_support/core_ext/array/wrap"
 require "active_support/core_ext/module/attribute_accessors"
 require "active_support/core_ext/object/blank"
@@ -87,26 +86,19 @@ module MimeActor
 
         raise ArgumentError, "provide either the with: argument or a block" if with.present? && block_given?
 
-        if block_given?
-          with = block
-        elsif with.present?
-          validate!(:with, with)
-        end
+        validate!(:with, with) if with.present?
+        with = block if block_given?
 
-        case actions = on
-        when Enumerable
-          validate!(:actions, actions)
-        when Symbol, String
-          validate!(:action, actions)
-        else
-          raise ArgumentError, "action is required"
-        end
+        raise ArgumentError, "action is required" unless (actions = on).present?
+
+        validate!(:action_or_actions, actions)
 
         Array.wrap(actions).each do |action|
           formats.each { |format| compose_scene(action, format, with) }
         end
       end
 
+      # TODO: remove on next breaking change release
       alias act_on_format respond_act_to
 
       private
@@ -122,7 +114,7 @@ module MimeActor
       end
 
       def define_scene(action)
-        class_eval(
+        module_eval(
           # def index
           #   self.respond_to?(:start_scene) && self.start_scene(:index)
           # end

data/lib/mime_actor/stage.rb

@@ -2,8 +2,9 @@
 
 # :markup: markdown
 
-require "mime_actor/errors"
+require "mime_actor/dispatcher"
 require "mime_actor/logging"
+require "mime_actor/rescue"
 
 require "active_support/concern"
 require "active_support/core_ext/module/attribute_accessors"
@@ -16,10 +17,11 @@ module MimeActor
   module Stage
     extend ActiveSupport::Concern
 
+    include Rescue
     include Logging
 
     included do
-      mattr_accessor :raise_on_missing_actor, instance_writer: false, default: false
+      mattr_accessor :raise_on_actor_error, instance_writer: false, default: false
     end
 
     module ClassMethods
@@ -46,13 +48,13 @@ module MimeActor
       # @param block the `block` to be evaluated
       #
       # @example Dispatch a cue that prints out a text
-      #   dispatch = self.class.dispatch_cue(action: :create, format: :json, context: self) do
+      #   dispatch = self.class.dispatch_act(action: :create, format: :json, context: self) do
       #       puts "completed the dispatch"
       #   end
       #
       #   dispatch.call == "completed the dispatch" # true
       #
-      def dispatch_cue(action: nil, format: nil, context: self, &block)
+      def dispatch_act(action: nil, format: nil, context: self, &block)
         raise ArgumentError, "block must be provided" unless block_given?
 
         lambda do
@@ -61,6 +63,9 @@ module MimeActor
           (respond_to?(:rescue_actor) && rescue_actor(e, action:, format:, context:)) || raise
         end
       end
+
+      # TODO: remove on next breaking change release
+      alias dispatch_cue dispatch_act
     end
 
     # Calls the `actor` and passing arguments to it.
@@ -68,40 +73,25 @@ module MimeActor
     #
     # NOTE: method call on actor if it is String or Symbol. Proc#call if actor is Proc
     #
-    # @param actor either a method name or a block to evaluate
-    def cue_actor(actor, *args)
-      result = case actor
-               when String, Symbol
-                 actor_method_call(actor, *args)
-               when Proc
-                 actor_proc_call(actor, *args)
-               else
-                 raise TypeError, "invalid actor, got: #{actor.inspect}"
-               end
+    # @param actor either a method name or a Proc to evaluate
+    # @param args arguments to be passed when calling the actor
+    #
+    def cue_actor(actor, *args, action:, format:)
+      dispatcher = MimeActor::Dispatcher.build(actor, *args)
+      raise TypeError, "invalid actor, got: #{actor.inspect}" unless dispatcher
 
+      result = dispatcher.call(self)
       if block_given?
         yield result
       else
         result
       end
-    end
-
-    private
-
-    def actor_method_call(actor_method, *args)
-      unless self.class.actor?(actor_method)
-        raise MimeActor::ActorNotFound, actor_method if raise_on_missing_actor
-
-        logger.warn { "actor #{actor_method.inspect} not found" }
-        return
-      end
-
-      public_send(actor_method, *args)
-    end
-
-    def actor_proc_call(actor_proc, *args)
-      passable_args = actor_proc.arity.negative? ? args : args.take(actor_proc.arity)
-      instance_exec(*passable_args, &actor_proc)
+    rescue MimeActor::ActorNotFound => e
+      logger.error { "actor error, cause: #{e.inspect}" } unless raise_on_actor_error
+      raise e if raise_on_actor_error
+    rescue StandardError => e
+      rescued = rescue_actor(e, action:, format:)
+      rescued || raise
     end
   end
 end

data/lib/mime_actor/validator.rb

@@ -32,7 +32,7 @@ module MimeActor
       # @param rule the name of validator
       def validate!(rule, *args)
         validator = "validate_#{rule}"
-        raise NameError, "Validator not found, got: #{validator.inspect}" unless respond_to?(validator, true)
+        raise NameError, "Validator not found, got: #{validator.inspect}" unless respond_to?(validator)
 
         error = send(validator, *args)
         raise error if error
@@ -53,6 +53,13 @@ module MimeActor
         NameError.new("invalid actions, got: #{rejected.map(&:inspect).join(", ")}") if rejected.size.positive?
       end
 
+      # Validate against `actions` rule if argument is a Enumerable. otherwise, validate against `action` rule.
+      #
+      # @param unchecked the `actions` or `action` to be validated
+      def validate_action_or_actions(unchecked)
+        unchecked.is_a?(Enumerable) ? validate_actions(unchecked) : validate_action(unchecked)
+      end
+
       # Validate `format` must be a Symbol and a valid MIME type
       #
       # @param unchecked the `format` to be validated
@@ -73,6 +80,13 @@ module MimeActor
         NameError.new("invalid formats, got: #{rejected.map(&:inspect).join(", ")}") if rejected.size.positive?
       end
 
+      # Validate against `formats` rule if argument is a Enumerable. otherwise, validate against `format` rule.
+      #
+      # @param unchecked the `formats` or `format` to be validated
+      def validate_format_or_formats(unchecked)
+        unchecked.is_a?(Enumerable) ? validate_formats(unchecked) : validate_format(unchecked)
+      end
+
       # Validate `klazz` must be a Class/Module or a String referencing a Class/Module
       #
       # @param unchecked the `klazz` to be validated

data/lib/mime_actor/version.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module MimeActor
   def self.version
-    gem_version
+    VERSION::STRING
   end
 
   def self.gem_version
-    Gem::Version.new VERSION::STRING
+    Gem::Version.new(VERSION::STRING)
   end
 
   module VERSION
     MAJOR = 0
     MINOR = 6
-    BUILD = 1
-    PRE   = nil
+    BUILD = 3
+    PRE   = "alpha"
 
     STRING = [MAJOR, MINOR, BUILD, PRE].compact.join(".")
   end

data/lib/mime_actor.rb

@@ -7,6 +7,7 @@ require "mime_actor/version"
 require "mime_actor/errors"
 
 require "active_support/dependencies/autoload"
+require "active_support/deprecation"
 
 module MimeActor
   extend ActiveSupport::Autoload
@@ -17,4 +18,18 @@ module MimeActor
   autoload :Rescue
   autoload :Validator
   autoload :Logging
+
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("0.7.0", "MimeActor")
+  end
+
+  [
+    [MimeActor::Rescue::ClassMethods, { rescue_actor: "use #rescue_actor instance method" }],
+    [MimeActor::Scene::ClassMethods, { act_on_format: :respond_act_to }],
+    [MimeActor::Stage::ClassMethods, { actor?: "no longer supported, use Object#respond_to?" }],
+    [MimeActor::Stage::ClassMethods, { dispatch_cue: "no longer support anonymous proc with rescue" }],
+    [MimeActor::Stage::ClassMethods, { dispatch_act: "no longer support anonymous proc with rescue" }]
+  ].each do |klazz, *args|
+    deprecator.deprecate_methods(klazz, *args)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mime_actor
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.3.alpha
 platform: ruby
 authors:
 - Ryan Chang
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-03 00:00:00.000000000 Z
+date: 2024-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -71,6 +71,8 @@ files:
 - codecov.yml
 - lib/mime_actor.rb
 - lib/mime_actor/action.rb
+- lib/mime_actor/callbacks.rb
+- lib/mime_actor/dispatcher.rb
 - lib/mime_actor/errors.rb
 - lib/mime_actor/logging.rb
 - lib/mime_actor/rescue.rb