active_delivery 1.0.0 → 1.2.0

data/lib/.rbnext/3.2/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(*__rest__)
+      AbstractNotifier::HaveSentNotification.new(*__rest__)
+    end
+
+    def have_enqueued_notification(*__rest__)
+      AbstractNotifier::HaveEnqueuedNotification.new(*__rest__)
+    end
+  end)
+end

data/lib/.rbnext/3.2/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(**__kwrest__)
+        return super unless AbstractNotifier.test?
+
+        payload = notification.payload
+
+        Driver.enqueue_notification payload.merge(via: notifier.class, **__kwrest__)
+      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/.rbnext/3.2/active_delivery/base.rb

@@ -0,0 +1,249 @@
+# 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
+  # an event (e.g. via email or via push notification or both).
+  #
+  # Delivery class acts like a proxy in front of the different delivery channels
+  # (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
+  #   EventsMailer.one_hour_before(profile, event).deliver_later
+  #
+  #   # and
+  #   EventsNotifier.one_hour_before(profile, event).notify_later
+  #
+  # Delivery also supports _parameterized_ calling:
+  #
+  #   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).deliver_later
+  #
+  # See https://api.rubyonrails.org/classes/ActionMailer/Parameterized.html
+  class Base
+    class << self
+      attr_accessor :abstract_class
+
+      alias_method :with, :new
+
+      # Enqueues delivery (i.e. uses #deliver_later for mailers)
+      def notify(...)
+        new.notify(...)
+      end
+
+      # The same as .notify but delivers synchronously
+      # (i.e. #deliver_now for mailers)
+      def notify!(mid, *__rest__, **hargs)
+        notify(mid, *__rest__, **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|
+            acc[key] = val.dup_for(self)
+          end
+        else
+          {}
+        end
+      end
+
+      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
+        if line_class.nil?
+          line_class = ActiveDelivery::Lines::Notifier
+        end
+
+        delivery_lines[line_id] = line_class.new(id: line_id, owner: self, **__kwrest__)
+
+        instance_eval <<~CODE, __FILE__, __LINE__ + 1
+          def #{line_id}(val)
+            delivery_lines[:#{line_id}].handler_class_name = val
+          end
+
+          def #{line_id}_class
+            delivery_lines[:#{line_id}].handler_class
+          end
+        CODE
+      end
+
+      def unregister_line(line_id)
+        removed_line = delivery_lines.delete(line_id)
+
+        return if removed_line.nil?
+
+        singleton_class.undef_method line_id
+        singleton_class.undef_method "#{line_id}_class"
+      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, *__rest__, **__kwrest__)
+        return super unless respond_to_missing?(mid)
+
+        # Lazily define a class method to avoid lookups
+        delivers(mid)
+
+        public_send(mid, *__rest__, **__kwrest__)
+      end
+    end
+
+    self.abstract_class = true
+
+    attr_reader :params, :notification_name
+
+    def initialize(**params)
+      @params = params
+      @params.freeze
+    end
+
+    # Enqueues delivery (i.e. uses #deliver_later for mailers)
+    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, **kwargs)
+      perform_notify(
+        delivery(notification: mid, params: args, options: kwargs),
+        sync: true
+      )
+    end
+
+    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 method_missing(mid, *__rest__, **__kwrest__)
+      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, *__rest__, **__kwrest__)
+    end
+
+    protected
+
+    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:, enqueue_options:)
+      end
+    end
+
+    private
+
+    def notify_line(type, line, delivery, sync:, enqueue_options:)
+      line.notify(
+        delivery.notification,
+        *delivery.params,
+        params:,
+        sync:,
+        enqueue_options:,
+        **delivery.options
+      )
+      true
+    end
+
+    def delivery(notification:, params: nil, options: nil, metadata: nil)
+      Delivery.new(self, notification:, params:, options:, metadata:)
+    end
+
+    def delivery_lines
+      self.class.delivery_lines
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# 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_accessor :handler_class_name
+
+      def initialize(id:, owner:, **options)
+        @id = id
+        @owner = owner
+        @options = options.tap(&:freeze)
+        @resolver = options[:resolver] || build_pattern_resolver(options[:resolver_pattern])
+      end
+
+      def dup_for(new_owner)
+        self.class.new(id:, **options, owner: new_owner)
+      end
+
+      def resolve_class(name)
+        resolver&.call(name)
+      end
+
+      def notify?(method_name)
+        handler_class&.respond_to?(method_name)
+      end
+
+      def notify_now(handler, mid, ...)
+      end
+
+      def notify_later(handler, mid, ...)
+      end
+
+      def notify_later_with_options(handler, enqueue_options, mid, ...)
+        notify_later(handler, mid, ...)
+      end
+
+      def notify(mid, *__rest__, params:, sync:, enqueue_options:, **__kwrest__)
+        clazz = params.empty? ? handler_class : handler_class.with(**params)
+        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
+        if ::ActiveDelivery.cache_classes
+          return @handler_class if instance_variable_defined?(:@handler_class)
+        end
+
+        return @handler_class = nil if owner.abstract_class?
+
+        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
+
+      attr_reader :resolver
+
+      def build_pattern_resolver(pattern)
+        return unless pattern
+
+        proc do |delivery|
+          delivery_class = delivery.name
+
+          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_name:, delivery_namespace:}).safe_constantize
+        end
+      end
+    end
+  end
+end

data/lib/.rbnext/3.2/active_delivery/lines/notifier.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+unless "".respond_to?(:safe_constantize)
+  require "active_delivery/ext/string_constantize"
+  using ActiveDelivery::Ext::StringConstantize
+end
+
+module ActiveDelivery
+  module Lines
+    # AbstractNotifier line for Active Delivery.
+    #
+    # You must provide custom `resolver` to infer notifier class
+    # (if String#safe_constantize is defined, we convert "*Delivery" -> "*Notifier").
+    #
+    # Resolver is a callable object.
+    class Notifier < ActiveDelivery::Lines::Base
+      DEFAULT_SUFFIX = "Notifier"
+
+      def initialize(**opts)
+        super
+        @resolver ||= build_resolver(options.fetch(:suffix, DEFAULT_SUFFIX))
+      end
+
+      def resolve_class(klass)
+        resolver&.call(klass)
+      end
+
+      def notify?(method_name)
+        return unless handler_class
+        handler_class.action_methods.include?(method_name.to_s)
+      end
+
+      def notify_now(handler, mid, *__rest__)
+        handler.public_send(mid, *__rest__).notify_now
+      end
+
+      def notify_later(handler, mid, *__rest__)
+        handler.public_send(mid, *__rest__).notify_later
+      end
+
+      def notify_later_with_options(handler, enqueue_options, mid, *__rest__)
+        handler.public_send(mid, *__rest__).notify_later(**enqueue_options)
+      end
+
+      private
+
+      attr_reader :resolver
+
+      def build_resolver(suffix)
+        lambda do |klass|
+          klass_name = klass.name
+          klass_name&.sub(/Delivery\z/, suffix)&.safe_constantize
+        end
+      end
+    end
+  end
+end