active_delivery 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34afeceddc78be6864aed136f68bc0a0f0eb43c203ef1520260fe94a8c934b39
-  data.tar.gz: dab4270f8b7a4c5e14b18c3fd36ceb081587425f26a50060191778bab768d688
+  metadata.gz: d05087cb016af8444f7668b81681675248b7b63f41f77a1d9fdb22b65ccb6845
+  data.tar.gz: d60851ccb9d9ea6557d131289942edf57b39c79a499e37d41f8f1d06b480446f
 SHA512:
-  metadata.gz: 67992b515155ae977dd2f839448b3fe89d8c1391906e3c20bd425782241378f70d0b933834433a5e30904a7f3a1176c1313cd690267f001258f9584b078f0367
-  data.tar.gz: c811abf777c5c0c7552749fcedd228e7914bc80ded1a14129f4194097d74049f72e80c229c59549ac09141fed3145ab4c4199706ca29055ce6a405c3c16e13a2
+  metadata.gz: 5a94a2fd3e2f19d9e99c0df6494752b23649802b064b390ea50d65506b01beb57650f31f5cd140495d6befa847a65423cc141ec8c313a6a116de69a4cd5576df
+  data.tar.gz: 4febe7f49e314d27f370642fa43085c5020dae8bac7fa9a3512514a6b861d17b726d4685ed91f081eab22f4c2af68a4117d37f8f29a576c78fe323f2c73b58e2

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## master
 
+## 1.2.0 (2024-02-05)
+
+- Add Minitest assertions (`assert_deliveries`, `assert_no_deliveries`, `assert_delivery_enqueued`). ([@palkan][])
+
+## 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][])
@@ -43,6 +51,20 @@
 
 - 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:

data/README.md

@@ -10,6 +10,8 @@ Since v1.0, Active Delivery is bundled with [Abstract Notifier](https://github.c
 
 📖 Read the introduction post: ["Crafting user notifications in Rails with Active Delivery"](https://evilmartians.com/chronicles/crafting-user-notifications-in-rails-with-active-delivery)
 
+📖 Read more about designing notifications layer in Ruby on Rails applications in the [Layered design for Ruby on Rails applications](https://www.packtpub.com/product/layered-design-for-ruby-on-rails-applications/9781801813785) book.
+
 <a href="https://evilmartians.com/?utm_source=action_policy">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
@@ -56,7 +58,7 @@ end
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "active_delivery", "1.0.0.rc2"
+gem "active_delivery", "~> 1.0"
 ```
 
 And then execute:
@@ -113,6 +115,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.
 ```
@@ -288,17 +293,36 @@ MyDeliver.notify(:something_wicked_this_way_comes)
 
 ## Testing
 
-**NOTE:** Currently, only RSpec matchers are provided.
+### Setup
+
+Test mode is activated automatically if `RAILS_ENV` or `RACK_ENV` env variable is equal to "test". Otherwise, add `require "active_delivery/testing/rspec"` to your `spec_helper.rb` / `rails_helper.rb` manually or `require "active_delivery/testing/minitest"`. This is also required if you're using Spring in the test environment (e.g. with help of [spring-commands-rspec](https://github.com/jonleighton/spring-commands-rspec)).
+
+For Minitest, you also MUST include the test helper into your test class. For example:
+
+```ruby
+class ActiveSupport::TestCase
+  # ...
+  include ActiveDelivery::TestHelper
+end
+```
 
 ### Deliveries
 
-Active Delivery provides an elegant way to test deliveries in your code (i.e., when you want to check whether a notification has been sent) through a `have_delivered_to` matcher:
+Active Delivery provides an elegant way to test deliveries in your code (i.e., when you want to check whether a notification has been sent) through a `have_delivered_to` RSpec matcher or `assert_delivery_enqueued` Minitest assertion:
 
 ```ruby
+# RSpec
 it "delivers notification" do
   expect { subject }.to have_delivered_to(Community::EventsDelivery, :modified, event)
     .with(profile: profile)
 end
+
+# Minitest
+def test_delivers_notification
+  assert_delivery_enqueued(Community::EventsDelivery, :modified, with: [event]) do
+    some_action
+  end
+end
 ```
 
 You can also use such RSpec features as compound expectations and composed matchers:
@@ -317,14 +341,27 @@ end
 If you want to test that no notification is delivered you can use negation
 
 ```ruby
+# RSpec
 specify "when event is not found" do
   expect do
     described_class.perform_now(profile.id, "123", "one_hour_before")
   end.not_to have_delivered_to(Community::EventsDelivery)
 end
+
+# Minitest
+def test_no_notification_if_event_is_not_found
+  assert_no_deliveries do
+    some_action
+  end
+
+  # Alternatively, you can use the positive assertion
+  assert_deliveries(0) do
+    some_action
+  end
+end
 ```
 
-or use the `#have_not_delivered_to` matcher:
+With RSpec, you can also use the `#have_not_delivered_to` matcher:
 
 ```ruby
 specify "when event is not found" do
@@ -357,7 +394,7 @@ describe PostsDelivery do
 end
 ```
 
-You can also use the `#deliver_via` matchers as follows:
+You can also use the `#deliver_via` RSpec matcher as follows:
 
 ```ruby
 describe PostsDelivery, type: :delivery do
@@ -384,8 +421,6 @@ describe PostsDelivery, type: :delivery do
 end
 ```
 
-**NOTE:** test mode activated automatically if `RAILS_ENV` or `RACK_ENV` env variable is equal to "test". Otherwise, add `require "active_delivery/testing/rspec"` to your `spec_helper.rb` / `rails_helper.rb` manually. This is also required if you're using Spring in the test environment (e.g. with help of [spring-commands-rspec](https://github.com/jonleighton/spring-commands-rspec)).
-
 ## Custom "lines"
 
 The _Line_ class describes the way you want to _transfer_ your deliveries.
@@ -407,8 +442,8 @@ class EventPigeon
     alias_method :with, :new
 
     # delegate delivery action to the instance
-    def message_arrived(*args)
-      new.message_arrived(*args)
+    def message_arrived(*)
+      new.message_arrived(*)
     end
   end
 
@@ -444,17 +479,17 @@ class PigeonLine < ActiveDelivery::Lines::Base
   # Called when we want to send message synchronously
   # `sender` here either `sender_class` or `sender_class.with(params)`
   # if params passed.
-  def notify_now(sender, delivery_action, *args, **kwargs)
+  def notify_now(sender, delivery_action, *, **)
     # For example, our EventPigeon class returns some `Pigeon` object
-    pigeon = sender.public_send(delivery_action, *args, **kwargs)
+    pigeon = sender.public_send(delivery_action, *, **)
     # PigeonLaunchService do all the sending job
     PigeonService.launch pigeon
   end
 
   # Called when we want to send a message asynchronously.
   # For example, you can use a background job here.
-  def notify_later(sender, delivery_action, *args, **kwargs)
-    pigeon = sender.public_send(delivery_action, *args, **kwargs)
+  def notify_later(sender, delivery_action, *, **)
+    pigeon = sender.public_send(delivery_action, *, **)
     # PigeonLaunchService do all the sending job
     PigeonLaunchJob.perform_later pigeon
   end
@@ -472,8 +507,8 @@ class EventPigeon
     alias_method :with, :new
 
     # delegate delivery action to the instance
-    def message_arrived(*args)
-      new.message_arrived(*args)
+    def message_arrived(*)
+      new.message_arrived(*)
     end
   end
 
@@ -488,18 +523,18 @@ class EventPigeon
 end
 
 class PigeonLine < ActiveDelivery::Lines::Base
-  def notify_later(sender, delivery_action, *args, **kwargs)
+  def notify_later(sender, delivery_action, *, **kwargs)
     # `to_s` is important for serialization. Unless you might have error
-    PigeonLaunchJob.perform_later sender.class.to_s, delivery_action, *args, **kwargs.merge(params: line.params)
+    PigeonLaunchJob.perform_later(sender.class.to_s, delivery_action, *, **kwargs.merge(params: line.params))
   end
 end
 
 class PigeonLaunchJob < ActiveJob::Base
-  def perform(sender, delivery_action, *args, params: nil, **kwargs)
+  def perform(sender, delivery_action, *, params: nil, **)
     klass = sender.safe_constantize
     handler = params ? klass.with(**params) : klass.new
 
-    handler.public_send(delivery_action, *args, **kwargs)
+    handler.public_send(delivery_action, *, **)
   end
 end
 ```
@@ -588,12 +623,12 @@ class ActionCableDeliveryLine < ActiveDelivery::Line::Base
   # We want to broadcast all notifications
   def notify?(...) = true
 
-  def notify_now(context, delivery_action, *args, **kwargs)
+  def notify_now(context, delivery_action, *, **)
     # Skip if no user provided
     return unless context.user
 
     payload = {event: [context.scope, delivery_action].join(".")}
-    payload.merge!(serialized_args(*args, **kwargs))
+    payload.merge!(serialized_args(*, **))
 
     DeliveryChannel.broadcast_to context.user, payload
   end
@@ -706,7 +741,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.
 
@@ -718,13 +753,13 @@ class MyAsyncAdapter
   def initialize(options = {})
   end
 
-  # `enqueue` method accepts notifier class, action name and notification parameters
-  def enqueue(notifier_class, action_name, params:, args:, kwargs:)
+  # `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(
-    #     notifier_class.constantize, action_name, params:, args:, kwargs:
+    #     delivery.notifier_class, delivery.action_name, **delivery.delivery_params
     #   ).notify_now
   end
 end

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

@@ -11,15 +11,24 @@ module AbstractNotifier
 
       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(...)
-        job.perform_later(...)
+        job.set(queue: queue).perform_later(...)
       end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :enqueue)
+
+      def enqueue_delivery(delivery, **__kwrest__)
+        job.set(queue: queue, **__kwrest__).perform_later(
+          delivery.notifier_class.name,
+          delivery.action_name,
+          **delivery.delivery_params
+        )
+      end
     end
   end
 end

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(**__kwrest__)
+      if notifier_class.async_adapter.respond_to?(:enqueue_delivery)
+        notifier_class.async_adapter.enqueue_delivery(self, **__kwrest__)
+      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?(*__rest__)
+        notifier_class.respond_to_missing?(*__rest__)
+      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

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

@@ -12,9 +12,9 @@ module ActiveDelivery
       @metadata = metadata.freeze
     end
 
-    def deliver_later ;  owner.perform_notify(self); end
+    def deliver_later(**opts) ;  owner.perform_notify(self, enqueue_options: opts); end
 
-    def deliver_now ;  owner.perform_notify(self, sync: true); end
+    def deliver_now(**opts) ;  owner.perform_notify(self, sync: true); end
 
     def delivery_class ;  owner.class; end
   end
@@ -77,8 +77,8 @@ module ActiveDelivery
 
       # 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, *__rest__, **hargs)
+        notify(mid, *__rest__, **hargs, sync: true)
       end
 
       alias_method :notify_now, :notify!
@@ -93,7 +93,7 @@ module ActiveDelivery
         end
       end
 
-      def register_line(line_id, line_class = nil, notifier: nil, **options)
+      def register_line(line_id, line_class = nil, notifier: nil, **__kwrest__)
         raise ArgumentError, "A line class or notifier configuration must be provided" if line_class.nil? && notifier.nil?
 
         # Configure Notifier
@@ -101,7 +101,7 @@ module ActiveDelivery
           line_class = ActiveDelivery::Lines::Notifier
         end
 
-        delivery_lines[line_id] = line_class.new(id: line_id, owner: self, **options)
+        delivery_lines[line_id] = line_class.new(id: line_id, owner: self, **__kwrest__)
 
         instance_eval <<~CODE, __FILE__, __LINE__ + 1
           def #{line_id}(val)
@@ -152,13 +152,13 @@ module ActiveDelivery
         super
       end
 
-      def method_missing(mid, *args, **kwargs)
+      def method_missing(mid, *__rest__, **__kwrest__)
         return super unless respond_to_missing?(mid)
 
         # Lazily define a class method to avoid lookups
         delivers(mid)
 
-        public_send(mid, *args, **kwargs)
+        public_send(mid, *__rest__, **__kwrest__)
       end
     end
 
@@ -197,7 +197,7 @@ module ActiveDelivery
       super
     end
 
-    def method_missing(mid, *args, **kwargs)
+    def method_missing(mid, *__rest__, **__kwrest__)
       return super unless respond_to_missing?(mid)
 
       # Lazily define a method to avoid future lookups
@@ -211,27 +211,28 @@ module ActiveDelivery
         end
       CODE
 
-      public_send(mid, *args, **kwargs)
+      public_send(mid, *__rest__, **__kwrest__)
     end
 
     protected
 
-    def perform_notify(delivery, sync: false)
+    def perform_notify(delivery, sync: false, enqueue_options: {})
       delivery_lines.each do |type, line|
         next unless line.notify?(delivery.notification)
 
-        notify_line(type, line, delivery, sync: sync)
+        notify_line(type, line, delivery, sync: sync, enqueue_options: enqueue_options)
       end
     end
 
     private
 
-    def notify_line(type, line, delivery, sync:)
+    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

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

@@ -37,9 +37,21 @@ module ActiveDelivery
       def notify_later(handler, mid, *__rest__, &__block__)
       end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :notify_later)
 
-      def notify(mid, *args, params:, sync:, **kwargs)
+      def notify_later_with_options(handler, enqueue_options, mid, *__rest__, &__block__)
+        notify_later(handler, mid, *__rest__, &__block__)
+      end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :notify_later_with_options)
+
+      def notify(mid, *__rest__, params:, sync:, enqueue_options:, **__kwrest__)
         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, *__rest__, **__kwrest__)
+        end
+
+        if enqueue_options.empty?
+          notify_later(clazz, mid, *__rest__, **__kwrest__)
+        else
+          notify_later_with_options(clazz, enqueue_options, mid, *__rest__, **__kwrest__)
+        end
       end
 
       def handler_class

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

@@ -19,6 +19,10 @@ module ActiveDelivery
       def notify_later(mailer, mid, *__rest__, &__block__)
         mailer.public_send(mid, *__rest__, &__block__).deliver_later
       end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :notify_later)
+
+      def notify_later_with_options(mailer, enqueue_options, mid, *__rest__, &__block__)
+        mailer.public_send(mid, *__rest__, &__block__).deliver_later(**enqueue_options)
+      end; respond_to?(:ruby2_keywords, true) && (ruby2_keywords :notify_later_with_options)
     end
 
     ActiveDelivery::Base.register_line :mailer, Mailer, resolver: Mailer::DEFAULT_RESOLVER