active_delivery 1.0.0.rc2 → 1.1.0

data/lib/.rbnext/3.1/abstract_notifier/base.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module AbstractNotifier
+  # NotificationDelivery payload wrapper which contains
+  # information about the current notifier class
+  # and knows how to trigger the delivery
+  class NotificationDelivery
+    attr_reader :action_name, :notifier_class
+
+    def initialize(notifier_class, action_name, params: {}, args: [], kwargs: {})
+      @notifier_class = notifier_class
+      @action_name = action_name
+      @params = params
+      @args = args
+      @kwargs = kwargs
+    end
+
+    def processed
+      return @processed if instance_variable_defined?(:@processed)
+
+      @processed = notifier.process_action(action_name, *args, **kwargs) || Notification.new(nil)
+    end
+
+    alias_method :notification, :processed
+
+    def notify_later(**opts)
+      if notifier_class.async_adapter.respond_to?(:enqueue_delivery)
+        notifier_class.async_adapter.enqueue_delivery(self, **opts)
+      else
+        notifier_class.async_adapter.enqueue(notifier_class.name, action_name, params: params, args: args, kwargs: kwargs)
+      end
+    end
+
+    def notify_now
+      return unless notification.payload
+
+      notifier.deliver!(notification)
+    end
+
+    def delivery_params ;  {params: params, args: args, kwargs: kwargs}; end
+
+    private
+
+    attr_reader :params, :args, :kwargs
+
+    def notifier
+      @notifier ||= notifier_class.new(action_name, **params)
+    end
+  end
+
+  # Notification object contains the compiled payload to be delivered
+  class Notification
+    attr_reader :payload
+
+    def initialize(payload)
+      @payload = payload
+    end
+  end
+
+  # Base class for notifiers
+  class Base
+    class ParamsProxy
+      attr_reader :notifier_class, :params
+
+      def initialize(notifier_class, params)
+        @notifier_class = notifier_class
+        @params = params
+      end
+
+      # rubocop:disable Style/MethodMissingSuper
+      def method_missing(method_name, *args, **kwargs)
+        NotificationDelivery.new(notifier_class, method_name, params: params, args: args, kwargs: kwargs)
+      end
+      # rubocop:enable Style/MethodMissingSuper
+
+      def respond_to_missing?(*args)
+        notifier_class.respond_to_missing?(*args)
+      end
+    end
+
+    class << self
+      attr_writer :driver
+
+      def driver
+        return @driver if instance_variable_defined?(:@driver)
+
+        @driver =
+          if superclass.respond_to?(:driver)
+            superclass.driver
+          else
+            raise "Driver not found for #{name}. " \
+                  "Please, specify driver via `self.driver = MyDriver`"
+          end
+      end
+
+      def async_adapter=(args)
+        adapter, options = Array(args)
+        @async_adapter = AsyncAdapters.lookup(adapter, options)
+      end
+
+      def async_adapter
+        return @async_adapter if instance_variable_defined?(:@async_adapter)
+
+        @async_adapter =
+          if superclass.respond_to?(:async_adapter)
+            superclass.async_adapter
+          else
+            AbstractNotifier.async_adapter
+          end
+      end
+
+      def default(method_name = nil, **hargs, &block)
+        return @defaults_generator = block if block
+
+        return @defaults_generator = proc { send(method_name) } unless method_name.nil?
+
+        @default_params =
+          if superclass.respond_to?(:default_params)
+            superclass.default_params.merge(hargs).freeze
+          else
+            hargs.freeze
+          end
+      end
+
+      def defaults_generator
+        return @defaults_generator if instance_variable_defined?(:@defaults_generator)
+
+        @defaults_generator =
+          if superclass.respond_to?(:defaults_generator)
+            superclass.defaults_generator
+          end
+      end
+
+      def default_params
+        return @default_params if instance_variable_defined?(:@default_params)
+
+        @default_params =
+          if superclass.respond_to?(:default_params)
+            superclass.default_params.dup
+          else
+            {}
+          end
+      end
+
+      def method_missing(method_name, *args, **kwargs)
+        if action_methods.include?(method_name.to_s)
+          NotificationDelivery.new(self, method_name, args: args, kwargs: kwargs)
+        else
+          super
+        end
+      end
+
+      def with(params)
+        ParamsProxy.new(self, params)
+      end
+
+      def respond_to_missing?(method_name, _include_private = false)
+        action_methods.include?(method_name.to_s) || super
+      end
+
+      # See https://github.com/rails/rails/blob/b13a5cb83ea00d6a3d71320fd276ca21049c2544/actionpack/lib/abstract_controller/base.rb#L74
+      def action_methods
+        @action_methods ||= begin
+          # All public instance methods of this class, including ancestors
+          methods = (public_instance_methods(true) -
+            # Except for public instance methods of Base and its ancestors
+            Base.public_instance_methods(true) +
+            # Be sure to include shadowed public instance methods of this class
+            public_instance_methods(false))
+
+          methods.map!(&:to_s)
+
+          methods.to_set
+        end
+      end
+    end
+
+    attr_reader :params, :notification_name
+
+    def initialize(notification_name, **params)
+      @notification_name = notification_name
+      @params = params.freeze
+    end
+
+    def process_action(...)
+      public_send(...)
+    end
+
+    def deliver!(notification)
+      self.class.driver.call(notification.payload)
+    end
+
+    def notification(**payload)
+      merge_defaults!(payload)
+
+      payload[:body] = implicit_payload_body unless payload.key?(:body)
+
+      raise ArgumentError, "Notification body must be present" if
+        payload[:body].nil? || payload[:body].empty?
+
+      @notification = Notification.new(payload)
+    end
+
+    private
+
+    def implicit_payload_body
+      # no-op — override to provide custom logic
+    end
+
+    def merge_defaults!(payload)
+      defaults =
+        if self.class.defaults_generator
+          instance_exec(&self.class.defaults_generator)
+        else
+          self.class.default_params
+        end
+
+      defaults.each do |k, v|
+        payload[k] = v unless payload.key?(k)
+      end
+    end
+  end
+end

data/lib/.rbnext/3.1/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(**opts) = owner.perform_notify(self, enqueue_options: opts)
+
+    def deliver_now(**opts) = 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,14 +54,14 @@ 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
@@ -47,6 +81,8 @@ module ActiveDelivery
         notify(mid, *args, **hargs, sync: true)
       end
 
+      alias_method :notify_now, :notify!
+
       def delivery_lines
         @lines ||= if superclass.respond_to?(:delivery_lines)
           superclass.delivery_lines.each_with_object({}) do |(key, val), acc|
@@ -57,12 +93,19 @@ module ActiveDelivery
         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
@@ -81,8 +124,46 @@ module ActiveDelivery
       end
 
       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)
@@ -91,30 +172,74 @@ module ActiveDelivery
     end
 
     # Enqueues delivery (i.e. uses #deliver_later for mailers)
-    def notify(mid, ...)
-      @notification_name = mid
-      do_notify(...)
+    def notify(mid, *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 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 do_notify(*args, sync: false, **kwargs)
+    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, enqueue_options: {})
       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: sync, enqueue_options: enqueue_options)
       end
     end
 
-    def notify_line(type, ...)
-      delivery_lines[type].notify(notification_name, ...)
+    private
+
+    def notify_line(type, line, delivery, sync:, enqueue_options:)
+      line.notify(
+        delivery.notification,
+        *delivery.params,
+        params: params,
+        sync: sync,
+        enqueue_options: enqueue_options,
+        **delivery.options
+      )
+      true
+    end
+
+    def delivery(notification:, params: nil, options: nil, metadata: nil)
+      Delivery.new(self, notification: notification, params: params, options: options, metadata: metadata)
     end
 
     def delivery_lines

data/lib/.rbnext/3.1/active_delivery/lines/base.rb

@@ -1,17 +1,22 @@
 # 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)
@@ -23,7 +28,7 @@ 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, ...)
@@ -32,32 +37,65 @@ module ActiveDelivery
       def notify_later(handler, mid, ...)
       end
 
-      def notify(mid, *args, params:, sync:, **kwargs)
+      def notify_later_with_options(handler, enqueue_options, mid, ...)
+        notify_later(handler, mid, ...)
+      end
+
+      def notify(mid, *args, params:, sync:, enqueue_options:, **kwargs)
         clazz = params.empty? ? handler_class : handler_class.with(**params)
-        sync ? notify_now(clazz, mid, *args, **kwargs) : notify_later(clazz, mid, *args, **kwargs)
+        if sync
+          return notify_now(clazz, mid, *args, **kwargs)
+        end
+
+        if enqueue_options.empty?
+          notify_later(clazz, mid, *args, **kwargs)
+        else
+          notify_later_with_options(clazz, enqueue_options, mid, *args, **kwargs)
+        end
       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
+
+      def build_pattern_resolver(pattern)
+        return unless pattern
 
-        return if owner.superclass == ActiveDelivery::Base
-        return unless owner.superclass.respond_to?(handler_method)
+        proc do |delivery|
+          delivery_class = delivery.name
 
-        owner.superclass.public_send(handler_method)
-      end
+          next unless delivery_class
 
-      attr_reader :resolver
+          *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_class, delivery_name: delivery_name, delivery_namespace: delivery_namespace}).safe_constantize
+        end
+      end
     end
   end
 end

data/lib/abstract_notifier/async_adapters/active_job.rb

@@ -4,21 +4,30 @@ module AbstractNotifier
   module AsyncAdapters
     class ActiveJob
       class DeliveryJob < ::ActiveJob::Base
-        def perform(notifier_class, payload)
-          AbstractNotifier::Notification.new(notifier_class.constantize, payload).notify_now
+        def perform(notifier_class, ...)
+          AbstractNotifier::NotificationDelivery.new(notifier_class.constantize, ...).notify_now
         end
       end
 
       DEFAULT_QUEUE = "notifiers"
 
-      attr_reader :job
+      attr_reader :job, :queue
 
       def initialize(queue: DEFAULT_QUEUE, job: DeliveryJob)
-        @job = job.set(queue: queue)
+        @job = job
+        @queue = queue
       end
 
-      def enqueue(notifier_class, payload)
-        job.perform_later(notifier_class.name, payload)
+      def enqueue(...)
+        job.set(queue:).perform_later(...)
+      end
+
+      def enqueue_delivery(delivery, **opts)
+        job.set(queue:, **opts).perform_later(
+          delivery.notifier_class.name,
+          delivery.action_name,
+          **delivery.delivery_params
+        )
       end
     end
   end