active_delivery 0.4.4 → 1.0.0

data/lib/abstract_notifier/base.rb

@@ -0,0 +1,217 @@
+# 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
+
+    def initialize(owner_class, action_name, params: {}, args: [], kwargs: {})
+      @owner_class = owner_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
+      owner_class.async_adapter.enqueue(owner_class.name, action_name, params:, args:, kwargs:)
+    end
+
+    def notify_now
+      return unless notification.payload
+
+      notifier.deliver!(notification)
+    end
+
+    private
+
+    attr_reader :owner_class, :params, :args, :kwargs
+
+    def notifier
+      @notifier ||= owner_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:, args:, 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:, 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/abstract_notifier/callbacks.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "active_support/version"
+require "active_support/callbacks"
+require "active_support/concern"
+
+module AbstractNotifier
+  # Add callbacks support to Abstract Notifier (requires ActiveSupport::Callbacks)
+  #
+  #   # Run method before seding notification
+  #   # NOTE: when `false` is returned the execution is halted
+  #   before_action :do_something
+  #
+  #   # after_ and around_ callbacks are also supported
+  #   after_action :cleanup
+  #
+  #   around_action :set_context
+  #
+  #   # Deliver callbacks are also available
+  #   before_deliver :do_something
+  #
+  #   # after_ and around_ callbacks are also supported
+  #   after_deliver :cleanup
+  #
+  #   around_deliver :set_context
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    include ActiveSupport::Callbacks
+
+    CALLBACK_TERMINATOR = ->(_target, result) { result.call == false }
+
+    included do
+      define_callbacks :action,
+        terminator: CALLBACK_TERMINATOR,
+        skip_after_callbacks_if_terminated: true
+
+      define_callbacks :deliver,
+        terminator: CALLBACK_TERMINATOR,
+        skip_after_callbacks_if_terminated: true
+
+      prepend InstanceExt
+    end
+
+    module InstanceExt
+      def process_action(...)
+        run_callbacks(:action) { super(...) }
+      end
+
+      def deliver!(...)
+        run_callbacks(:deliver) { super(...) }
+      end
+    end
+
+    class_methods do
+      def _normalize_callback_options(options)
+        _normalize_callback_option(options, :only, :if)
+        _normalize_callback_option(options, :except, :unless)
+      end
+
+      def _normalize_callback_option(options, from, to)
+        if (from = options[from])
+          from_set = Array(from).map(&:to_s).to_set
+          from = proc { |c| from_set.include? c.notification_name.to_s }
+          options[to] = Array(options[to]).unshift(from)
+        end
+      end
+
+      %i[before after around].each do |kind|
+        %i[action deliver].each do |event|
+          define_method "#{kind}_#{event}" do |*names, on: event, **options, &block|
+            _normalize_callback_options(options)
+
+            names.each do |name|
+              set_callback on, kind, name, options
+            end
+
+            set_callback on, kind, block, options if block
+          end
+
+          define_method "skip_#{kind}_#{event}" do |*names, on: event, **options|
+            _normalize_callback_options(options)
+
+            names.each do |name|
+              skip_callback(on, kind, name, options)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+AbstractNotifier::Base.include AbstractNotifier::Callbacks

data/lib/abstract_notifier/testing/minitest.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module AbstractNotifier
+  module TestHelper
+    def assert_notifications_sent(count, params)
+      yield
+      assert_equal deliveries.count, count
+      count.times do |i|
+        delivery = deliveries[0 - i]
+        if !params[:via]
+          delivery = delivery.dup
+          delivery.delete(:via)
+        end
+
+        msg = message(msg) { "Expected #{mu_pp(delivery)} to include #{mu_pp(params)}" }
+        assert hash_include?(delivery, params), msg
+      end
+    end
+
+    def assert_notifications_enqueued(count, params)
+      yield
+      assert_equal enqueued_deliveries.count, count
+      count.times do |i|
+        delivery = enqueued_deliveries[0 - i]
+        if !params[:via]
+          delivery = delivery.dup
+          delivery.delete(:via)
+        end
+
+        msg = message(msg) { "Expected #{mu_pp(delivery)} to include #{mu_pp(params)}" }
+        assert hash_include?(delivery, params), msg
+      end
+    end
+
+    private
+
+    def deliveries
+      AbstractNotifier::Testing::Driver.deliveries
+    end
+
+    def enqueued_deliveries
+      AbstractNotifier::Testing::Driver.enqueued_deliveries
+    end
+
+    def hash_include?(haystack, needle)
+      needle.all? do |k, v|
+        haystack.key?(k) && haystack[k] == v
+      end
+    end
+  end
+end

data/lib/abstract_notifier/testing/rspec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module AbstractNotifier
+  class HaveSentNotification < RSpec::Matchers::BuiltIn::BaseMatcher
+    attr_reader :payload
+
+    def initialize(payload = nil)
+      @payload = payload
+      set_expected_number(:exactly, 1)
+    end
+
+    def exactly(count)
+      set_expected_number(:exactly, count)
+      self
+    end
+
+    def at_least(count)
+      set_expected_number(:at_least, count)
+      self
+    end
+
+    def at_most(count)
+      set_expected_number(:at_most, count)
+      self
+    end
+
+    def times
+      self
+    end
+
+    def once
+      exactly(:once)
+    end
+
+    def twice
+      exactly(:twice)
+    end
+
+    def thrice
+      exactly(:thrice)
+    end
+
+    def supports_block_expectations?
+      true
+    end
+
+    def matches?(proc)
+      raise ArgumentError, "have_sent_notification only supports block expectations" unless Proc === proc
+
+      raise "You can only use have_sent_notification matcher in :test delivery mode" unless AbstractNotifier.test?
+
+      original_deliveries_count = deliveries.count
+      proc.call
+      in_block_deliveries = deliveries.drop(original_deliveries_count)
+
+      @matching_deliveries, @unmatching_deliveries =
+        in_block_deliveries.partition do |actual_payload|
+          next true if payload.nil?
+
+          if payload.is_a?(::Hash) && !payload[:via]
+            actual_payload = actual_payload.dup
+            actual_payload.delete(:via)
+          end
+
+          payload === actual_payload
+        end
+
+      @matching_count = @matching_deliveries.size
+
+      case @expectation_type
+      when :exactly then @expected_number == @matching_count
+      when :at_most then @expected_number >= @matching_count
+      when :at_least then @expected_number <= @matching_count
+      end
+    end
+
+    def deliveries
+      AbstractNotifier::Testing::Driver.deliveries
+    end
+
+    def set_expected_number(relativity, count)
+      @expectation_type = relativity
+      @expected_number =
+        case count
+        when :once then 1
+        when :twice then 2
+        when :thrice then 3
+        else Integer(count)
+        end
+    end
+
+    def failure_message
+      (+"expected to #{verb_present} notification: #{payload_description}").tap do |msg|
+        msg << " #{message_expectation_modifier}, but"
+
+        if @unmatching_deliveries.any?
+          msg << " #{verb_past} the following notifications:"
+          @unmatching_deliveries.each do |unmatching_payload|
+            msg << "\n  #{unmatching_payload}"
+          end
+        else
+          msg << " haven't #{verb_past} anything"
+        end
+      end
+    end
+
+    def failure_message_when_negated
+      "expected not to #{verb_present} #{payload}"
+    end
+
+    def message_expectation_modifier
+      number_modifier = (@expected_number == 1) ? "once" : "#{@expected_number} times"
+      case @expectation_type
+      when :exactly then "exactly #{number_modifier}"
+      when :at_most then "at most #{number_modifier}"
+      when :at_least then "at least #{number_modifier}"
+      end
+    end
+
+    def payload_description
+      if payload.is_a?(RSpec::Matchers::Composable)
+        payload.description
+      else
+        payload
+      end
+    end
+
+    def verb_past
+      "sent"
+    end
+
+    def verb_present
+      "send"
+    end
+  end
+
+  class HaveEnqueuedNotification < HaveSentNotification
+    private
+
+    def deliveries
+      AbstractNotifier::Testing::Driver.enqueued_deliveries
+    end
+
+    def verb_past
+      "enqueued"
+    end
+
+    def verb_present
+      "enqueue"
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include(Module.new do
+    def have_sent_notification(*args)
+      AbstractNotifier::HaveSentNotification.new(*args)
+    end
+
+    def have_enqueued_notification(*args)
+      AbstractNotifier::HaveEnqueuedNotification.new(*args)
+    end
+  end)
+end

data/lib/abstract_notifier/testing.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module AbstractNotifier
+  module Testing
+    module Driver
+      class << self
+        def deliveries
+          Thread.current[:notifier_deliveries] ||= []
+        end
+
+        def enqueued_deliveries
+          Thread.current[:notifier_enqueued_deliveries] ||= []
+        end
+
+        def clear
+          deliveries.clear
+          enqueued_deliveries.clear
+        end
+
+        def send_notification(data)
+          deliveries << data
+        end
+
+        def enqueue_notification(data)
+          enqueued_deliveries << data
+        end
+      end
+    end
+
+    module NotificationDelivery
+      def notify_now
+        return super unless AbstractNotifier.test?
+
+        payload = notification.payload
+
+        Driver.send_notification payload.merge(via: notifier.class)
+      end
+
+      def notify_later
+        return super unless AbstractNotifier.test?
+
+        payload = notification.payload
+
+        Driver.enqueue_notification payload.merge(via: notifier.class)
+      end
+    end
+  end
+end
+
+AbstractNotifier::NotificationDelivery.prepend AbstractNotifier::Testing::NotificationDelivery
+
+require "abstract_notifier/testing/rspec" if defined?(RSpec::Core)
+require "abstract_notifier/testing/minitest" if defined?(Minitest::Assertions)

data/lib/abstract_notifier/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AbstractNotifier
+  VERSION = "1.0.0"
+end

data/lib/abstract_notifier.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "abstract_notifier/version"
+
+# Abstract Notifier is responsible for generating and triggering text-based notifications
+# (like Action Mailer for email notifications).
+#
+# Example:
+#
+#   class ApplicationNotifier < AbstractNotifier::Base
+#     self.driver = NotifyService.new
+#
+#     def profile
+#       params[:profile] if params
+#     end
+#   end
+#
+#   class EventsNotifier < ApplicationNotifier
+#     def canceled(event)
+#       notification(
+#         # the only required option is `body`
+#         body: "Event #{event.title} has been canceled",
+#         # all other options are passed to delivery driver
+#         identity: profile.notification_service_id
+#       )
+#    end
+#   end
+#
+#   EventsNotifier.with(profile: profile).canceled(event).notify_later
+#
+module AbstractNotifier
+  DELIVERY_MODES = %i[test noop normal].freeze
+
+  class << self
+    attr_reader :delivery_mode
+    attr_reader :async_adapter
+
+    def delivery_mode=(val)
+      unless DELIVERY_MODES.include?(val)
+        raise ArgumentError, "Unsupported delivery mode: #{val}. " \
+                             "Supported values: #{DELIVERY_MODES.join(", ")}"
+      end
+
+      @delivery_mode = val
+    end
+
+    def async_adapter=(args)
+      adapter, options = Array(args)
+      @async_adapter = AsyncAdapters.lookup(adapter, options)
+    end
+
+    def noop?
+      delivery_mode == :noop
+    end
+
+    def test?
+      delivery_mode == :test
+    end
+  end
+
+  self.delivery_mode =
+    if ENV["RACK_ENV"] == "test" || ENV["RAILS_ENV"] == "test"
+      :test
+    else
+      :normal
+    end
+end
+
+require "abstract_notifier/base"
+require "abstract_notifier/async_adapters"
+
+require "abstract_notifier/callbacks" if defined?(ActiveSupport)
+require "abstract_notifier/async_adapters/active_job" if defined?(ActiveJob)
+
+require "abstract_notifier/testing" if ENV["RACK_ENV"] == "test" || ENV["RAILS_ENV"] == "test"