active_delivery 0.4.4 → 1.0.0

data/lib/active_delivery/base.rb

@@ -1,6 +1,38 @@
 # frozen_string_literal: true
 
 module ActiveDelivery
+  class Delivery # :nodoc:
+    attr_reader :params, :options, :metadata, :notification, :owner
+
+    def initialize(owner, notification:, params:, options:, metadata:)
+      @owner = owner
+      @notification = notification
+      @params = params.freeze
+      @options = options.freeze
+      @metadata = metadata.freeze
+    end
+
+    def deliver_later = owner.perform_notify(self)
+
+    def deliver_now = owner.perform_notify(self, sync: true)
+
+    def delivery_class = owner.class
+  end
+
+  class << self
+    # Whether to memoize resolved handler classes or not.
+    # Set to false if you're using a code reloader (e.g., Zeitwerk).
+    #
+    # Defaults to true (i.e. memoization is enabled
+    attr_accessor :cache_classes
+    # Whether to enforce specifying available delivery actions via .delivers in the
+    # delivery classes
+    attr_accessor :deliver_actions_required
+  end
+
+  self.cache_classes = true
+  self.deliver_actions_required = false
+
   # Base class for deliveries.
   #
   # Delivery object describes how to notify a user about
@@ -10,6 +42,8 @@ module ActiveDelivery
   # (i.e. mailers, notifiers). That means that calling a method on delivery class invokes the
   # same method on the corresponding class, e.g.:
   #
+  #   EventsDelivery.one_hour_before(profile, event).deliver_later
+  #   # or
   #   EventsDelivery.notify(:one_hour_before, profile, event)
   #
   #   # under the hood it calls
@@ -20,25 +54,25 @@ module ActiveDelivery
   #
   # Delivery also supports _parameterized_ calling:
   #
-  #   EventsDelivery.with(profile: profile).notify(:canceled, event)
+  #   EventsDelivery.with(profile: profile).canceled(event).deliver_later
   #
   # The parameters could be accessed through `params` instance method (e.g.
   # to implement guard-like logic).
   #
   # When params are presents the parametrized mailer is used, i.e.:
   #
-  #   EventsMailer.with(profile: profile).canceled(event)
+  #   EventsMailer.with(profile: profile).canceled(event).deliver_later
   #
   # See https://api.rubyonrails.org/classes/ActionMailer/Parameterized.html
   class Base
     class << self
       attr_accessor :abstract_class
 
-      alias with new
+      alias_method :with, :new
 
       # Enqueues delivery (i.e. uses #deliver_later for mailers)
-      def notify(*args, **kwargs)
-        new.notify(*args, **kwargs)
+      def notify(...)
+        new.notify(...)
       end
 
       # The same as .notify but delivers synchronously
@@ -47,24 +81,31 @@ module ActiveDelivery
         notify(mid, *args, **hargs, sync: true)
       end
 
+      alias_method :notify_now, :notify!
+
       def delivery_lines
-        @lines ||= begin
-          if superclass.respond_to?(:delivery_lines)
-            superclass.delivery_lines.each_with_object({}) do |(key, val), acc|
-              acc[key] = val.dup_for(self)
-            end
-          else
-            {}
+        @lines ||= if superclass.respond_to?(:delivery_lines)
+          superclass.delivery_lines.each_with_object({}) do |(key, val), acc|
+            acc[key] = val.dup_for(self)
           end
+        else
+          {}
         end
       end
 
-      def register_line(line_id, line_class, **options)
+      def register_line(line_id, line_class = nil, notifier: nil, **options)
+        raise ArgumentError, "A line class or notifier configuration must be provided" if line_class.nil? && notifier.nil?
+
+        # Configure Notifier
+        if line_class.nil?
+          line_class = ActiveDelivery::Lines::Notifier
+        end
+
         delivery_lines[line_id] = line_class.new(id: line_id, owner: self, **options)
 
         instance_eval <<~CODE, __FILE__, __LINE__ + 1
           def #{line_id}(val)
-            delivery_lines[:#{line_id}].handler_class = val
+            delivery_lines[:#{line_id}].handler_class_name = val
           end
 
           def #{line_id}_class
@@ -82,11 +123,47 @@ module ActiveDelivery
         singleton_class.undef_method "#{line_id}_class"
       end
 
-      def abstract_class?
-        abstract_class == true
+      def abstract_class? = abstract_class == true
+
+      # Specify explicitly which actions are supported by the delivery.
+      def delivers(*actions)
+        actions.each do |mid|
+          class_eval <<~CODE, __FILE__, __LINE__ + 1
+            def self.#{mid}(...)
+              new.#{mid}(...)
+            end
+
+            def #{mid}(*args, **kwargs)
+              delivery(
+                notification: :#{mid},
+                params: args,
+                options: kwargs
+              )
+            end
+          CODE
+        end
+      end
+
+      def respond_to_missing?(mid, include_private = false)
+        unless ActiveDelivery.deliver_actions_required
+          return true if delivery_lines.any? { |_, line| line.notify?(mid) }
+        end
+
+        super
+      end
+
+      def method_missing(mid, *args, **kwargs)
+        return super unless respond_to_missing?(mid)
+
+        # Lazily define a class method to avoid lookups
+        delivers(mid)
+
+        public_send(mid, *args, **kwargs)
       end
     end
 
+    self.abstract_class = true
+
     attr_reader :params, :notification_name
 
     def initialize(**params)
@@ -96,29 +173,72 @@ module ActiveDelivery
 
     # Enqueues delivery (i.e. uses #deliver_later for mailers)
     def notify(mid, *args, **kwargs)
-      @notification_name = mid
-      do_notify(*args, **kwargs)
+      perform_notify(
+        delivery(notification: mid, params: args, options: kwargs)
+      )
     end
 
     # The same as .notify but delivers synchronously
     # (i.e. #deliver_now for mailers)
-    def notify!(mid, *args, **hargs)
-      notify(mid, *args, **hargs, sync: true)
+    def notify!(mid, *args, **kwargs)
+      perform_notify(
+        delivery(notification: mid, params: args, options: kwargs),
+        sync: true
+      )
     end
 
-    private
+    alias_method :notify_now, :notify!
 
-    def do_notify(*args, sync: false, **kwargs)
+    def respond_to_missing?(mid, include_private = false)
+      unless ActiveDelivery.deliver_actions_required
+        return true if delivery_lines.any? { |_, line| line.notify?(mid) }
+      end
+
+      super
+    end
+
+    def method_missing(mid, *args, **kwargs)
+      return super unless respond_to_missing?(mid)
+
+      # Lazily define a method to avoid future lookups
+      self.class.class_eval <<~CODE, __FILE__, __LINE__ + 1
+        def #{mid}(*args, **kwargs)
+          delivery(
+            notification: :#{mid},
+            params: args,
+            options: kwargs
+          )
+        end
+      CODE
+
+      public_send(mid, *args, **kwargs)
+    end
+
+    protected
+
+    def perform_notify(delivery, sync: false)
       delivery_lines.each do |type, line|
-        next if line.handler_class.nil?
-        next unless line.notify?(notification_name)
+        next unless line.notify?(delivery.notification)
 
-        notify_line(type, *args, params: params, sync: sync, **kwargs)
+        notify_line(type, line, delivery, sync:)
       end
     end
 
-    def notify_line(type, *args, **kwargs)
-      delivery_lines[type].notify(notification_name, *args, **kwargs)
+    private
+
+    def notify_line(type, line, delivery, sync:)
+      line.notify(
+        delivery.notification,
+        *delivery.params,
+        params:,
+        sync:,
+        **delivery.options
+      )
+      true
+    end
+
+    def delivery(notification:, params: nil, options: nil, metadata: nil)
+      Delivery.new(self, notification:, params:, options:, metadata:)
     end
 
     def delivery_lines

data/lib/active_delivery/callbacks.rb

@@ -8,7 +8,7 @@ module ActiveDelivery
   # Add callbacks support to Active Delivery (requires ActiveSupport::Callbacks)
   #
   #   # Run method before delivering notification
-  #   # NOTE: when `false` is returned the executation is halted
+  #   # NOTE: when `false` is returned the execution is halted
   #   before_notify :do_something
   #
   #   # You can specify a notification method (to run callback only for that method)
@@ -26,11 +26,7 @@ module ActiveDelivery
 
     include ActiveSupport::Callbacks
 
-    CALLBACK_TERMINATOR = if ::ActiveSupport::VERSION::MAJOR >= 5
-      ->(_target, result) { result.call == false }
-    else
-      ->(_target, result) { result == false }
-    end
+    CALLBACK_TERMINATOR = ->(_target, result) { result.call == false }
 
     included do
       # Define "global" callbacks
@@ -41,17 +37,19 @@ module ActiveDelivery
     end
 
     module InstanceExt
-      def do_notify(*args, **kwargs)
-        run_callbacks(:notify) { super(*args, **kwargs) }
+      def perform_notify(delivery, ...)
+        # We need to store the notification name to be able to use it in callbacks if/unless
+        @notification_name = delivery.notification
+        run_callbacks(:notify) { super(delivery, ...) }
       end
 
-      def notify_line(*args, **kwargs)
-        run_callbacks(args.first) { super(*args, **kwargs) }
+      def notify_line(kind, ...)
+        run_callbacks(kind) { super(kind, ...) }
       end
     end
 
     module SingltonExt
-      def register_line(line_id, *args, **kwargs)
+      def register_line(line_id, ...)
         super
         define_line_callbacks line_id
       end
@@ -77,22 +75,24 @@ module ActiveDelivery
           skip_after_callbacks_if_terminated: true
       end
 
-      def before_notify(method_or_block = nil, on: :notify, **options, &block)
-        method_or_block ||= block
-        _normalize_callback_options(options)
-        set_callback on, :before, method_or_block, options
-      end
+      %i[before after around].each do |kind|
+        define_method "#{kind}_notify" do |*names, on: :notify, **options, &block|
+          _normalize_callback_options(options)
 
-      def after_notify(method_or_block = nil, on: :notify, **options, &block)
-        method_or_block ||= block
-        _normalize_callback_options(options)
-        set_callback on, :after, method_or_block, options
-      end
+          names.each do |name|
+            set_callback on, kind, name, options
+          end
 
-      def around_notify(method_or_block = nil, on: :notify, **options, &block)
-        method_or_block ||= block
-        _normalize_callback_options(options)
-        set_callback on, :around, method_or_block, options
+          set_callback on, kind, block, options if block
+        end
+
+        define_method "skip_#{kind}_notify" do |*names, on: :notify, **options|
+          _normalize_callback_options(options)
+
+          names.each do |name|
+            skip_callback(on, kind, name, options)
+          end
+        end
       end
     end
   end

data/lib/active_delivery/ext/string_constantize.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActiveDelivery
+  module Ext
+    # Add simple safe_constantize method to String
+    module StringConstantize
+      refine String do
+        def safe_constantize
+          names = split("::")
+
+          return nil if names.empty?
+
+          # Remove the first blank element in case of '::ClassName' notation.
+          names.shift if names.size > 1 && names.first.empty?
+
+          names.inject(Object) do |constant, name|
+            break if constant.nil?
+            constant.const_get(name, false) if constant.const_defined?(name, false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_delivery/lines/base.rb

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
+unless "".respond_to?(:safe_constantize)
+  require "active_delivery/ext/string_constantize"
+  using ActiveDelivery::Ext::StringConstantize
+end
+
 module ActiveDelivery
   module Lines
     class Base
       attr_reader :id, :options
       attr_accessor :owner
-      attr_writer :handler_class
+      attr_accessor :handler_class_name
 
       def initialize(id:, owner:, **options)
         @id = id
         @owner = owner
         @options = options.tap(&:freeze)
-        @resolver = options[:resolver]
+        @resolver = options[:resolver] || build_pattern_resolver(options[:resolver_pattern])
       end
 
       def dup_for(new_owner)
-        self.class.new(id: id, **options, owner: new_owner)
+        self.class.new(id:, **options, owner: new_owner)
       end
 
       def resolve_class(name)
@@ -23,13 +28,13 @@ module ActiveDelivery
       end
 
       def notify?(method_name)
-        handler_class.respond_to?(method_name)
+        handler_class&.respond_to?(method_name)
       end
 
-      def notify_now(handler, mid, *args, **kwargs)
+      def notify_now(handler, mid, ...)
       end
 
-      def notify_later(handler, mid, *args, **kwargs)
+      def notify_later(handler, mid, ...)
       end
 
       def notify(mid, *args, params:, sync:, **kwargs)
@@ -38,26 +43,47 @@ module ActiveDelivery
       end
 
       def handler_class
-        return @handler_class if instance_variable_defined?(:@handler_class)
+        if ::ActiveDelivery.cache_classes
+          return @handler_class if instance_variable_defined?(:@handler_class)
+        end
 
         return @handler_class = nil if owner.abstract_class?
 
-        @handler_class = resolve_class(owner.name) ||
-          superclass_handler
+        superline = owner.superclass.delivery_lines[id] if owner.superclass.respond_to?(:delivery_lines) && owner.superclass.delivery_lines[id]
+
+        # If an explicit class name has been specified somewhere in the ancestor chain, use it.
+        class_name = @handler_class_name || superline&.handler_class_name
+
+        @handler_class =
+          if class_name
+            class_name.is_a?(Class) ? class_name : class_name.safe_constantize
+          else
+            resolve_class(owner) || superline&.handler_class
+          end
       end
 
       private
 
-      def superclass_handler
-        handler_method = "#{id}_class"
+      attr_reader :resolver
 
-        return if ActiveDelivery::Base == owner.superclass
-        return unless owner.superclass.respond_to?(handler_method)
+      def build_pattern_resolver(pattern)
+        return unless pattern
 
-        owner.superclass.public_send(handler_method)
-      end
+        proc do |delivery|
+          delivery_class = delivery.name
 
-      attr_reader :resolver
+          next unless delivery_class
+
+          *namespace, delivery_name = delivery_class.split("::")
+
+          delivery_namespace = ""
+          delivery_namespace = "#{namespace.join("::")}::" unless namespace.empty?
+
+          delivery_name = delivery_name.sub(/Delivery$/, "")
+
+          (pattern % {delivery_class:, delivery_name:, delivery_namespace:}).safe_constantize
+        end
+      end
     end
   end
 end

data/lib/active_delivery/lines/mailer.rb

@@ -1,34 +1,23 @@
 # frozen_string_literal: true
 
-if ActionMailer::VERSION::MAJOR < 5 || (ActionMailer::VERSION::MAJOR == 5 && ActionMailer::VERSION::MINOR < 2)
-  require "active_delivery/action_mailer/parameterized"
-end
-
 module ActiveDelivery
   module Lines
     class Mailer < Base
-      alias mailer_class handler_class
+      alias_method :mailer_class, :handler_class
 
-      DEFAULT_RESOLVER = ->(name) { name.gsub(/Delivery$/, "Mailer").safe_constantize }
+      DEFAULT_RESOLVER = ->(klass) { klass.name&.gsub(/Delivery$/, "Mailer")&.safe_constantize }
 
       def notify?(method_name)
+        return unless mailer_class
         mailer_class.action_methods.include?(method_name.to_s)
       end
 
-      def notify_now(mailer, mid, *args, **kwargs)
-        if kwargs.empty?
-          mailer.public_send(mid, *args).deliver_now
-        else
-          mailer.public_send(mid, *args, **kwargs).deliver_now
-        end
+      def notify_now(mailer, mid, ...)
+        mailer.public_send(mid, ...).deliver_now
       end
 
-      def notify_later(mailer, mid, *args, **kwargs)
-        if kwargs.empty?
-          mailer.public_send(mid, *args).deliver_later
-        else
-          mailer.public_send(mid, *args, **kwargs).deliver_later
-        end
+      def notify_later(mailer, mid, ...)
+        mailer.public_send(mid, ...).deliver_later
       end
     end
 

data/lib/active_delivery/lines/notifier.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+unless "".respond_to?(:safe_constantize)
+  require "active_delivery/ext/string_constantize"
+  using ActiveDelivery::Ext::StringConstantize
+end
+
+module ActiveDelivery
+  module Lines
+    # AbstractNotifier line for Active Delivery.
+    #
+    # You must provide custom `resolver` to infer notifier class
+    # (if String#safe_constantize is defined, we convert "*Delivery" -> "*Notifier").
+    #
+    # Resolver is a callable object.
+    class Notifier < ActiveDelivery::Lines::Base
+      DEFAULT_SUFFIX = "Notifier"
+
+      def initialize(**opts)
+        super
+        @resolver ||= build_resolver(options.fetch(:suffix, DEFAULT_SUFFIX))
+      end
+
+      def resolve_class(klass)
+        resolver&.call(klass)
+      end
+
+      def notify?(method_name)
+        return unless handler_class
+        handler_class.action_methods.include?(method_name.to_s)
+      end
+
+      def notify_now(handler, mid, *args)
+        handler.public_send(mid, *args).notify_now
+      end
+
+      def notify_later(handler, mid, *args)
+        handler.public_send(mid, *args).notify_later
+      end
+
+      private
+
+      attr_reader :resolver
+
+      def build_resolver(suffix)
+        lambda do |klass|
+          klass_name = klass.name
+          klass_name&.sub(/Delivery\z/, suffix)&.safe_constantize
+        end
+      end
+    end
+  end
+end

data/lib/active_delivery/raitie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveDelivery
+  class Railtie < Rails::Railtie
+    config.after_initialize do |app|
+      ActiveDelivery.cache_classes = app.config.cache_classes
+    end
+  end
+end