active_delivery 1.0.0.rc2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9c65eedb249c1a52253ad6e2155271e8931b55e2e7e429baf9f72682a4bd60a
-  data.tar.gz: '048565d99b6da3903905740b90c726f1805376237e7af4cb7f526b83bea0857e'
+  metadata.gz: 34afeceddc78be6864aed136f68bc0a0f0eb43c203ef1520260fe94a8c934b39
+  data.tar.gz: dab4270f8b7a4c5e14b18c3fd36ceb081587425f26a50060191778bab768d688
 SHA512:
-  metadata.gz: 0c753da1c2b0abf43e3361eff188c87e2f3eefa9f1c1a35c3a238810b8fd399e0f91196c5af94a3d50a66ccd1439adb166be95e416b531b00ffa4021550c1608
-  data.tar.gz: 225e522994457b30caad32e7ae5d0c93df5f2bca295fe63c460d3aa87f52478d387fc30950bc0b95a1f5ce93e42352588bc5310075bd55765cd67bb31b6e839f
+  metadata.gz: 67992b515155ae977dd2f839448b3fe89d8c1391906e3c20bd425782241378f70d0b933834433a5e30904a7f3a1176c1313cd690267f001258f9584b078f0367
+  data.tar.gz: c811abf777c5c0c7552749fcedd228e7914bc80ded1a14129f4194097d74049f72e80c229c59549ac09141fed3145ab4c4199706ca29055ce6a405c3c16e13a2

data/CHANGELOG.md

@@ -2,47 +2,57 @@
 
 ## master
 
+## 📬 1.0.0 (2023-08-29)
+
+- Add `resolver_pattern` option to specify naming pattern for notifiers without using Procs. ([@palkan][])
+
+- [!IMPORTANT] Notifier's `#notify_later` now do not process the action right away, only enqueue the job. ([@palkan][]).
+
+  This matches the Action Mailer behaviour. Now, the action is only invoked before the delivery attempt.
+
+- Add callbacks support to Abstract Notifier (`before_action`, `after_deliver`, etc.). ([@palkan][])
+
 - **Merge in abstract_notifier** ([@palkan][])
 
-[Abstract Notifier](https://github.com/palkan/abstract_notifier) is now a part of Active Delivery.
+  [Abstract Notifier](https://github.com/palkan/abstract_notifier) is now a part of Active Delivery.
 
 - Add ability to specify delivery actions explicitly and disable implicit proxying. ([@palkan][])
 
-You can disable default Active Delivery behaviour of proxying action methods to underlying lines via the `ActiveDelivery.deliver_actions_required = true` configuration option. Then, in each delivery class, you can specify the available actions via the `.delivers` method:
+  You can disable default Active Delivery behaviour of proxying action methods to underlying lines via the `ActiveDelivery.deliver_actions_required = true` configuration option. Then, in each delivery class, you can specify the available actions via the `.delivers` method:
 
-```ruby
-class PostMailer < ApplicationMailer
-  def published(post)
-    # ...
-  end
+  ```ruby
+  class PostMailer < ApplicationMailer
+    def published(post)
+      # ...
+    end
 
-  def whatever(post)
-    # ...
+    def whatever(post)
+      # ...
+    end
   end
-end
 
-ActiveDelivery.deliver_actions_required = true
+  ActiveDelivery.deliver_actions_required = true
 
-class PostDelivery < ApplicationDelivery
-  delivers :published
-end
+  class PostDelivery < ApplicationDelivery
+    delivers :published
+  end
 
-PostDelivery.published(post) #=> ok
-PostDelivery.whatever(post) #=> raises NoMethodError
-```
+  PostDelivery.published(post) #=> ok
+  PostDelivery.whatever(post) #=> raises NoMethodError
+  ```
 
 - Add `#deliver_via(*lines)` RSpec matcher. ([@palkan][])
 
 - Provide ActionMailer-like interface to trigger notifications. ([@palkan][])
 
-Now you can send notifications as follows:
+  Now you can send notifications as follows:
 
-```ruby
-MyDelivery.with(user:).new_notification(payload).deliver_later
+  ```ruby
+  MyDelivery.with(user:).new_notification(payload).deliver_later
 
-# Equals to the old (and still supported)
-MyDelivery.with(user:).notify(:new_notification, payload)
-```
+  # Equals to the old (and still supported)
+  MyDelivery.with(user:).notify(:new_notification, payload)
+  ```
 
 - Support passing a string class name as a handler class. ([@palkan][])
 

data/README.md

@@ -79,8 +79,16 @@ class ApplicationDelivery < ActiveDelivery::Base
   # Mailers are enabled by default, everything else must be declared explicitly
 
   # For example, you can use a notifier line (see below) with a custom resolver
+  # (the argument is the delivery class)
   register_line :sms, ActiveDelivery::Lines::Notifier,
-    resolver: -> { _1.name.gsub(/Delivery$/, "SMSNotifier").safe_constantize }
+    resolver: -> { _1.name.gsub(/Delivery$/, "SMSNotifier").safe_constantize } #=> PostDelivery -> PostSMSNotifier
+
+  # Or you can use a name pattern to resolve notifier classes for delivery classes
+  # Available placeholders are:
+  #  - delivery_class — full delivery class name
+  #  - delivery_name — full delivery class name without the "Delivery" suffix
+  register_line :webhook, ActiveDelivery::Lines::Notifier,
+    resolver_pattern: "%{delivery_name}WebhookNotifier" #=> PostDelivery -> PostWebhookNotifier
 
   register_line :cable, ActionCableDeliveryLine
   # and more
@@ -153,6 +161,45 @@ PostDelivery.published(post) #=> ok
 PostDelivery.whatever(post) #=> raises NoMethodError
 ```
 
+### Organizing delivery and notifier classes
+
+There are two common ways to organize delivery and notifier classes in your codebase:
+
+```txt
+app/
+  deliveries/                                 deliveries/
+    application_delivery.rb                     application_delivery.rb
+    post_delivery.rb                            post_delivery/
+    user_delivery.rb                              post_mailer.rb
+  mailers/                                        post_sms_notifier.rb
+    application_mailer.rb                         post_webhook_notifier.rb
+    post_mailer.rb                              post_delivery.rb
+    user_mailer.rb                              user_delivery/
+  notifiers/                                      user_mailer.rb
+    application_notifier.rb                       user_sms_notifier.rb
+    post_sms_notifier.rb                          user_webhook_notifier.rb
+    post_webhook_notifier.rb                    user_delivery.rb
+    user_sms_notifier.rb
+    user_webhook_notifier.rb
+```
+
+The left side is a _flat_ structure, more typical for classic Rails applications. The right side follows the _sidecar pattern_ and aims to localize all the code related to a specific delivery class in a single directory. To use the sidecar version, you need to configure your delivery lines as follows:
+
+```ruby
+class ApplicationDelivery < ActiveDelivery::Base
+  self.abstract_class = true
+
+  register_line :mailer, ActiveDelivery::Lines::Mailer,
+    resolver_pattern: "%{delivery_class}::%{delivery_name}_mailer"
+  register_line :sms,
+    notifier: true,
+    resolver_pattern: "%{delivery_class}::%{delivery_name}_sms_notifier"
+  register_line :webhook,
+    notifier: true,
+    resolver_pattern: "%{delivery_class}::%{delivery_name}_webhook_notifier"
+end
+```
+
 ### Customizing delivery handlers
 
 You can specify a mailer class explicitly:
@@ -671,11 +718,14 @@ class MyAsyncAdapter
   def initialize(options = {})
   end
 
-  # `enqueue` method accepts notifier class and notification
-  # payload.
-  # We need to know notifier class to use its driver.
-  def enqueue(notifier_class, payload)
-    # your implementation here
+  # `enqueue` method accepts notifier class, action name and notification parameters
+  def enqueue(notifier_class, action_name, params:, args:, kwargs:)
+    # <Your implementation here>
+    # To trigger the notification delivery, you can use the following snippet:
+    #
+    #   AbstractNotifier::NotificationDelivery.new(
+    #     notifier_class.constantize, action_name, params:, args:, kwargs:
+    #   ).notify_now
   end
 end
 
@@ -688,6 +738,53 @@ class EventsNotifier < AbstractNotifier::Base
 end
 ```
 
+### Action and Delivery Callbacks
+
+**NOTE:** callbacks are only available if ActiveSupport is present in the application's runtime.
+
+```ruby
+# Run method before building a notification payload
+# NOTE: when `false` is returned the execution is halted
+before_action :do_something
+
+# Run method before delivering notification
+# NOTE: when `false` is returned the execution is halted
+before_deliver :do_something
+
+# Run method after the notification payload was build but before delivering
+after_action :verify_notification_payload
+
+# Run method after the actual delivery was performed
+after_deliver :mark_user_as_notified, if: -> { params[:user].present? }
+
+# after_ and around_ callbacks are also supported
+after_action_ :cleanup
+
+around_deliver :set_context
+
+# You can also skip callbacks in sub-classes
+skip_before_action :do_something, only: %i[some_reminder]
+```
+
+Example:
+
+```ruby
+class MyNotifier < AbstractNotifier::Base
+  # Log sent notifications
+  after_deliver do
+    # You can access the notification name within the instance or
+    MyLogger.info "Notification sent: #{notification_name}"
+  end
+
+  def some_event(body)
+    notification(body:)
+  end
+end
+
+MyNotifier.some_event("hello")
+#=> Notification sent: some_event
+```
+
 ### Delivery modes
 
 For test/development purposes there are two special _global_ delivery modes:
@@ -772,6 +869,9 @@ class ApplicationDelivery < ActiveDelivery::Base
   #   `*Delivery` -> `*CustomNotifier`
   register_line :custom_notifier, notifier: true, suffix: "CustomNotifier"
 
+  # Or using a custom pattern
+  register_line :custom_notifier, notifier: true, resolver_pattern: "%{delivery_name}CustomNotifier"
+
   # Or you can specify a Proc object to do custom resolution:
   register_line :some_notifier, notifier: true,
     resolver: ->(delivery_class) { resolve_somehow(delivery_class) }

data/lib/.rbnext/3.0/abstract_notifier/async_adapters/active_job.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AbstractNotifier
+  module AsyncAdapters
+    class ActiveJob
+      class DeliveryJob < ::ActiveJob::Base
+        def perform(notifier_class, *__rest__, &__block__)
+          AbstractNotifier::NotificationDelivery.new(notifier_class.constantize, *__rest__, &__block__).notify_now
+        end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :perform)
+      end
+
+      DEFAULT_QUEUE = "notifiers"
+
+      attr_reader :job
+
+      def initialize(queue: DEFAULT_QUEUE, job: DeliveryJob)
+        @job = job.set(queue: queue)
+      end
+
+      def enqueue(...)
+        job.perform_later(...)
+      end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :enqueue)
+    end
+  end
+end
+
+AbstractNotifier.async_adapter ||= :active_job

data/lib/.rbnext/3.0/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); end
+
+    def deliver_now ;  owner.perform_notify(self, sync: true); end
+
+    def delivery_class ;  owner.class; end
+  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; end
+
+      # 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,31 +172,74 @@ module ActiveDelivery
     end
 
     # Enqueues delivery (i.e. uses #deliver_later for mailers)
-    def notify(mid, *__rest__, &__block__)
-      @notification_name = mid
-      do_notify(*__rest__, &__block__)
-    end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :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)
       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)
       end
     end
 
-    def notify_line(type, *__rest__, &__block__)
-      delivery_lines[type].notify(notification_name, *__rest__, &__block__)
-    end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :notify_line)
+    private
+
+    def notify_line(type, line, delivery, sync:)
+      line.notify(
+        delivery.notification,
+        *delivery.params,
+        params: params,
+        sync: sync,
+        **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
       self.class.delivery_lines

data/lib/.rbnext/3.0/active_delivery/callbacks.rb

@@ -37,9 +37,11 @@ module ActiveDelivery
     end
 
     module InstanceExt
-      def do_notify(...)
-        run_callbacks(:notify) { super(...) }
-      end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :do_notify)
+      def perform_notify(delivery, *__rest__, &__block__)
+        # 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, *__rest__, &__block__) }
+      end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :perform_notify)
 
       def notify_line(kind, *__rest__, &__block__)
         run_callbacks(kind) { super(kind, *__rest__, &__block__) }
@@ -73,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
+
+          set_callback on, kind, block, options if block
+        end
+
+        define_method "skip_#{kind}_notify" do |*names, on: :notify, **options|
+          _normalize_callback_options(options)
 
-      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
+          names.each do |name|
+            skip_callback(on, kind, name, options)
+          end
+        end
       end
     end
   end

data/lib/.rbnext/3.0/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, *__rest__, &__block__)
@@ -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 owner.superclass == ActiveDelivery::Base
-        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_class, delivery_name: delivery_name, delivery_namespace: delivery_namespace}).safe_constantize
+        end
+      end
     end
   end
 end

data/lib/.rbnext/3.0/active_delivery/lines/mailer.rb

@@ -5,9 +5,10 @@ module ActiveDelivery
     class Mailer < Base
       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