active_delivery 1.0.0.rc2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9c65eedb249c1a52253ad6e2155271e8931b55e2e7e429baf9f72682a4bd60a
-  data.tar.gz: '048565d99b6da3903905740b90c726f1805376237e7af4cb7f526b83bea0857e'
+  metadata.gz: dfc96638e6c019dd1b13f57eef8ab3b9bf2a34df2b58ca7f7ea8ea167886c59e
+  data.tar.gz: b50d556edef4a01fc7d1a8af1659a05f99a821584c2d4818418401f3a03350dd
 SHA512:
-  metadata.gz: 0c753da1c2b0abf43e3361eff188c87e2f3eefa9f1c1a35c3a238810b8fd399e0f91196c5af94a3d50a66ccd1439adb166be95e416b531b00ffa4021550c1608
-  data.tar.gz: 225e522994457b30caad32e7ae5d0c93df5f2bca295fe63c460d3aa87f52478d387fc30950bc0b95a1f5ce93e42352588bc5310075bd55765cd67bb31b6e839f
+  metadata.gz: 518d226591f5114383c2d138c163b4bac13e62666cce4f7edde7d2df5bca7e770c17576f00fee378b9a8733cc72372960efa2692839a6dc4d274d130787fcb41
+  data.tar.gz: 2bd5eed0775fd32d83ca45364d8ecdc4f28c275eb2ffbbcad768ef98d8581b1cd0e66eb72f7e012c9d4dbd0a18e8a72cb40a858f0459614e18a5ee3e24fb0420

data/CHANGELOG.md

@@ -2,47 +2,75 @@
 
 ## master
 
+## 1.1.0 (2023-12-01) ❄️
+
+- Support delayed delivery options (e.g, `wait_until`). ([@palkan][])
+
+## 📬 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][])
 
+- **BREAKING** The `#resolve_class` method in Line classes now receive a delivery class instead of a name:
+
+  ```ruby
+  # before
+  def resolve_class(name)
+    name.gsub(/Delivery$/, "Channel").safe_constantize
+  end
+
+  # after
+  def resolve_class(name)
+    name.to_s.gsub(/Delivery$/, "Channel").safe_constantize
+  end
+  ```
+
 - 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
@@ -105,6 +113,9 @@ PostsDelivery.published(user, post).deliver_later
 PostsMailer.published(user, post).deliver_later
 PostsSMSNotifier.published(user, post).notify_later
 
+# You can also pass options supported by your async executor (such as ActiveJob)
+PostsDelivery.published(user, post).deliver_later(wait_until: 1.day.from_now)
+
 # and whaterver your ActionCableDeliveryLine does
 # under the hood.
 ```
@@ -153,6 +164,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:
@@ -659,7 +709,7 @@ end
 
 ### Background jobs / async notifications
 
-To use `#notify_later` you **must** configure an async adapter for Abstract Notifier.
+To use `#notify_later(**delivery_options)` you **must** configure an async adapter for Abstract Notifier.
 
 We provide an Active Job adapter out of the box and enable it if Active Job is found.
 
@@ -671,11 +721,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_delivery` method accepts notifier class, action name and notification parameters
+  def enqueue_delivery(delivery, **options)
+    # <Your implementation here>
+    # To trigger the notification delivery, you can use the following snippet:
+    #
+    #   AbstractNotifier::NotificationDelivery.new(
+    #     delivery.notifier_class, delivery.action_name, **delivery.delivery_params
+    #   ).notify_now
   end
 end
 
@@ -688,6 +741,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 +872,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,36 @@
+# 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, :queue
+
+      def initialize(queue: DEFAULT_QUEUE, job: DeliveryJob)
+        @job = job
+        @queue = queue
+      end
+
+      def enqueue(...)
+        job.set(queue: queue).perform_later(...)
+      end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :enqueue)
+
+      def enqueue_delivery(delivery, **opts)
+        job.set(queue: queue, **opts).perform_later(
+          delivery.notifier_class.name,
+          delivery.action_name,
+          **delivery.delivery_params
+        )
+      end
+    end
+  end
+end
+
+AbstractNotifier.async_adapter ||= :active_job

data/lib/.rbnext/3.0/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; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :process_action)
+
+    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