Active Delivery

Active Delivery is a framework providing an entry point (single interface or abstraction) for all types of notifications: mailers, push notifications, whatever you want.

Since v1.0, Active Delivery is bundled with Abstract Notifier. See the docs on how to create custom notifiers below.

📖 Read the introduction post: "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 book.

Requirements:

Ruby ~> 2.7
Rails 6+ (optional).

NOTE: although most of the examples in this readme are Rails-specific, this gem could be used without Rails/ActiveSupport.

The problem

We need a way to handle different notifications channel (mail, push) in one place.

From the business-logic point of view, we want to notify a user, hence we need a separate abstraction layer as an entry point to different types of notifications.

The solution

Here comes Active Delivery.

In the simplest case when we have only mailers Active Delivery is just a wrapper for Mailer with (possibly) some additional logic provided (e.g., preventing emails to unsubscribed users).

Motivations behind Active Delivery:

Organize notifications-related logic:

# Before
def after_some_action
  MyMailer.with(user: user).some_action(resource).deliver_later if user.receive_emails?
  NotifyService.send_notification(user, "action") if whatever_else?
end

# After
def after_some_action
  MyDelivery.with(user: user).some_action(resource).deliver_later
end

Better testability (see Testing).

Installation

Add this line to your application's Gemfile:

gem "active_delivery", "~> 1.0"

And then execute:

bundle install

Usage

The Delivery class is used to trigger notifications. It describes how to notify a user (e.g., via email or push notification or both).

First, it's recommended to create a base class for all deliveries with the configuration of the lines:

# In the base class, you configure delivery lines
class ApplicationDelivery < ActiveDelivery::Base
  self.abstract_class = true

  # 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 } #=> 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
end

Then, you can create a delivery class for a specific notification type. We follow Action Mailer conventions, and create a delivery class per resource:

class PostsDelivery < ApplicationDelivery
end

In most cases, you just leave this class blank. The corresponding mailers, notifiers, etc., will be inferred automatically using the naming convention.

You don't need to define notification methods explicitly. Whenever you invoke a method on a delivery class, it will be proxied to the underlying line handlers (mailers, notifiers, etc.):

PostsDelivery.published(user, post).deliver_later

# Under the hood it calls
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.

Alternatively, you call the #notify method with the notification name and the arguments:

PostsDelivery.notify(:published, user, post)

# Under the hood it calls
PostsMailer.published(user, post).deliver_later
PostsSMSNotifier.published(user, post).notify_later
# ...

You can also define a notification method explicitly if you want to add some logic:

class PostsDelivery < ApplicationDelivery
  def published(user, post)
    # do something

    # return a delivery object (to chain #deliver_later, etc.)
    delivery(
      notification: :published,
      params: [user, post],
      # For kwargs, you options
      options: {},
      # Metadata that can be used by line handlers
      metadata: {}
    )
  end
end

Finally, you can disable the default automatic proxying behaviour via the ActiveDelivery.deliver_actions_required = true configuration option. Then, in each delivery class, you can specify the available actions via the .delivers method:

class PostDelivery < ApplicationDelivery
  delivers :published
end

ActiveDelivery.deliver_actions_required = true

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:

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:

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:

class PostsDelivery < ActiveDelivery::Base
  # You can pass a class name or a class itself
  mailer "CustomPostsMailer"
  # For other lines, you the line name as well
  # sms "MyPostsSMSNotifier"
end

Or you can provide a custom resolver by re-registering the line:

class PostsDelivery < ActiveDelivery::Base
  register_line :mailer, ActiveDelivery::Lines::Mailer, resolver: ->(_delivery_class) { CustomMailer }
end

Parameterized deliveries

Delivery also supports parameterized calling:

PostsDelivery.with(user: user).notify(:published, post)

The parameters could be accessed through the params instance method (e.g., to implement guard-like logic).

NOTE: When params are present, the parameterized mailer is used, i.e.:

PostsMailer.with(user: user).published(post)

Other line implementations MUST also have the #with method in their public interface.

See Rails docs for more information on parameterized mailers.

Callbacks support

NOTE: callbacks are only available if ActiveSupport is present in the application's runtime.

# Run method before delivering notification
# NOTE: when `false` is returned the execution is halted
before_notify :do_something

# You can specify a notification line (to run callback only for that line)
before_notify :do_mail_something, on: :mailer

# You can specify a notification name (to run callback only for specific notification)
after_notify :mark_user_as_notified, only: %i[user_reminder]

# if and unless options are also at your disposal
after_notify :mark_user_as_notified, if: -> { params[:user].present? }

# after_ and around_ callbacks are also supported
after_notify :cleanup

around_notify :set_context

# You can also skip callbacks in sub-classes
skip_before_notify :do_something, only: %i[some_reminder]

# NOTE: Specify `on` option for line-specific callbacks is required to skip them
skip_after_notify :do_mail_something, on: :mailer

Example:

# Let's log notifications
class MyDelivery < ActiveDelivery::Base
  after_notify do
    # You can access the notification name within the instance
    MyLogger.info "Delivery triggered: #{notification_name}"
  end
end

MyDeliver.notify(:something_wicked_this_way_comes)
#=> Delivery triggered: something_wicked_this_way_comes

Testing

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).

For Minitest, you also MUST include the test helper into your test class. For example:

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 RSpec matcher or assert_delivery_enqueued Minitest assertion:

# 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:

it "delivers to RSVPed members via .notify" do
  expect { subject }
    .to have_delivered_to(Community::EventsDelivery, :canceled, an_instance_of(event)).with(
      a_hash_including(profile: another_profile)
    ).and have_delivered_to(Community::EventsDelivery, :canceled, event).with(
      profile: profile
    )
end

If you want to test that no notification is delivered you can use negation

# 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

With RSpec, you can also use the #have_not_delivered_to matcher:

specify "when event is not found" do
  expect do
    described_class.perform_now(profile.id, "123", "one_hour_before")
  end.to have_not_delivered_to(Community::EventsDelivery)
end

Delivery classes

You can test Delivery classes as regular Ruby classes:

describe PostsDelivery do
  let(:user) { build_stubbed(:user) }
  let(:post) { build_stubbed(:post) }

  describe "#published" do
    it "sends a mail" do
      expect {
        described_class.published(user, post).deliver_now
      }.to change { ActionMailer::Base.deliveries.count }.by(1)

      mail = ActionMailer::Base.deliveries.last
      expect(mail.to).to eq([user.email])
      expect(mail.subject).to eq("New post published")
    end
  end
end

You can also use the #deliver_via RSpec matcher as follows:

describe PostsDelivery, type: :delivery do
  let(:user) { build_stubbed(:user) }
  let(:post) { build_stubbed(:post) }

  describe "#published" do
    it "delivers to mailer and sms" do
      expect {
        described_class.published(user, post).deliver_later
      }.to deliver_via(:mailer, :sms)
    end

    context "when user is not subscribed to SMS notifications" do
      let(:user) { build_stubbed(:user, sms_notifications: false) }

      it "delivers to mailer only" do
        expect {
          described_class.published(user, post).deliver_now
        }.to deliver_via(:mailer)
      end
    end
  end
end

Custom "lines"

The Line class describes the way you want to transfer your deliveries.

We only provide only Action Mailer line out-of-the-box.

A line connects delivery to the sender class responsible for sending notifications.

If you want to use parameterized deliveries, your sender class must respond to .with(params) method.

A full-featured line example: pigeons 🐦

Assume that we want to send messages via pigeons and we have the following sender class:

class EventPigeon
  class << self
    # Add `.with`  method as an alias
    alias_method :with, :new

    # delegate delivery action to the instance
    def message_arrived(*)
      new.message_arrived(*)
    end
  end

  def initialize(params = {})
    # do smth with params
  end

  def message_arrived(msg)
    # send a pigeon with the message
  end
end

Now we want to add a pigeon line to our EventDelivery, that is we want to send pigeons when we call EventDelivery.notify(:message_arrived, "ping-pong!").

Line class has the following API:

class PigeonLine < ActiveDelivery::Lines::Base
  # This method is used to infer sender class
  # `name` is the name of the delivery class
  def resolve_class(name)
    name.gsub(/Delivery$/, "Pigeon").safe_constantize
  end

  # This method should return true if the sender recognizes the delivery action
  def notify?(delivery_action)
    # `handler_class` is available within the line instance
    sender_class.respond_to?(delivery_action)
  end

  # 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, *, **)
    # For example, our EventPigeon class returns some `Pigeon` object
    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, *, **)
    pigeon = sender.public_send(delivery_action, *, **)
    # PigeonLaunchService do all the sending job
    PigeonLaunchJob.perform_later pigeon
  end
end

In the case of parameterized calling, some update needs to be done on the new Line. Here is an example:

class EventPigeon
  attr_reader :params

  class << self
    # Add `.with`  method as an alias
    alias_method :with, :new

    # delegate delivery action to the instance
    def message_arrived(*)
      new.message_arrived(*)
    end
  end

  def initialize(params = {})
    @params = params
    # do smth with params
  end

  def message_arrived(msg)
    # send a pigeon with the message
  end
end

class PigeonLine < ActiveDelivery::Lines::Base
  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, *, **kwargs.merge(params: line.params))
  end
end

class PigeonLaunchJob < ActiveJob::Base
  def perform(sender, delivery_action, *, params: nil, **)
    klass = sender.safe_constantize
    handler = params ? klass.with(**params) : klass.new

    handler.public_send(delivery_action, *, **)
  end
end

NOTE: we fall back to the superclass's sender class if resolve_class returns nil. You can disable automatic inference of sender classes by marking delivery as abstract:

# we don't want to use ApplicationMailer by default, don't we?
class ApplicationDelivery < ActiveDelivery::Base
  self.abstract_class = true
end

The final step is to register the line within your delivery class:

class EventDelivery < ActiveDelivery::Base
  # under the hood a new instance of PigeonLine is created
  # and used to send pigeons!
  register_line :pigeon, PigeonLine

  # you can pass additional options to customize your line
  # (and use multiple pigeons lines with different configuration)
  #
  # register_line :pigeon, PigeonLine, namespace: "AngryPigeons"
  #
  # now you can explicitly specify pigeon class
  # pigeon "MyCustomPigeon"
  #
  # or define pigeon specific callbacks
  #
  # before_notify :ensure_pigeon_is_not_dead, on: :pigeon
end

You can also unregister a line:

class NonMailerDelivery < ActiveDelivery::Base
  # Use unregister_line to remove any default or inherited lines
  unregister_line :mailer
end

An example of a universal sender: Action Cable

Although Active Delivery is designed to work with Action Mailer-like abstraction, it's flexible enough to support other use cases.

For example, for some notification channels, we don't need to create a separate class for each resource or context; we can send the payload right to the communication channel. Let's consider an Action Cable line as an example.

For every delivery, we want to broadcast a message via Action Cable to the stream corresponding to the delivery class name. For example:

# Our PostsDelivery example from the beginning
PostsDelivery.with(user:).notify(:published, post)

# Will results in the following Action Cable broadcast:
DeliveryChannel.broadcast_to user, {event: "posts.published", post_id: post.id}

The ActionCableDeliveryLine class can be implemented as follows:

class ActionCableDeliveryLine < ActiveDelivery::Line::Base
  # Context is our universal sender.
  class Context
    attr_reader :user

    def initialize(scope)
      @scope = scope
    end

    # User is required for this line
    def with(user:, **)
      @user = user
      self
    end
  end

  # The result of this callback is passed further to the `notify_now` method
  def resolve_class(name)
    Context.new(name.sub(/Delivery$/, "").underscore)
  end

  # We want to broadcast all notifications
  def notify?(...) = true

  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(*, **))

    DeliveryChannel.broadcast_to context.user, payload
  end

  # Broadcasts are asynchronous by nature, so we can just use `notify_now`
  alias_method :notify_later, :notify_now

  private

  def serialized_args(*args, **kwargs)
    # Code that convers AR objects into IDs, etc.
  end
end

Abstract Notifier

Abstract Notifier is a tool that allows you to describe/model any text-based notifications (such as Push Notifications) the same way Action Mailer does for email notifications.

Abstract Notifier (as the name states) doesn't provide any specific implementation for sending notifications. Instead, it offers tools to organize your notification-specific code and make it easily testable.

Notifier classes

A notifier object is very similar to an Action Mailer's mailer with the #notification method used instead of the #mail method:

class EventsNotifier < ApplicationNotifier
  def canceled(profile, 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

# send notification later
EventsNotifier.canceled(profile, event).notify_later

# or immediately
EventsNotifier.canceled(profile, event).notify_now

Delivery drivers

To perform actual deliveries you must configure a delivery driver:

class ApplicationNotifier < AbstractNotifier::Base
  self.driver = MyFancySender.new
end

A driver could be any callable Ruby object (i.e., anything that responds to #call).

That's the developer's responsibility to implement the driver (we do not provide any drivers out-of-the-box; at least yet).

You can set different drivers for different notifiers.

Parameterized notifiers

Abstract Notifier supports parameterization the same way as Action Mailer:

class EventsNotifier < ApplicationNotifier
  def canceled(event)
    notification(
      body: "Event #{event.title} has been canceled",
      identity: params[:profile].notification_service_id
    )
  end
end

EventsNotifier.with(profile: profile).canceled(event).notify_later

Defaults

You can specify default notification fields at a class level:

class EventsNotifier < ApplicationNotifier
  # `category` field will be added to the notification
  # if missing
  default category: "EVENTS"

  # ...
end

NOTE: when subclassing notifiers, default parameters are merged.

You can also specify a block or a method name as the default params generator. This could be useful in combination with the #notification_name method to generate dynamic payloads:

class ApplicationNotifier < AbstractNotifier::Base
  default :build_defaults_from_locale

  private

  def build_defaults_from_locale
    {
      subject: I18n.t(notification_name, scope: [:notifiers, self.class.name.underscore])
    }
  end
end

Background jobs / async notifications

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.

A custom async adapter must implement the #enqueue method:

class MyAsyncAdapter
  # adapters may accept options
  def initialize(options = {})
  end

  # `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

# Configure globally
AbstractNotifier.async_adapter = MyAsyncAdapter.new

# or per-notifier
class EventsNotifier < AbstractNotifier::Base
  self.async_adapter = MyAsyncAdapter.new
end

Action and Delivery Callbacks

NOTE: callbacks are only available if ActiveSupport is present in the application's runtime.

# 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:

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:

# Track all sent notifications without peforming real actions.
# Required for using RSpec matchers.
#
# config/environments/test.rb
AbstractNotifier.delivery_mode = :test

# If you don't want to trigger notifications in development,
# you can make Abstract Notifier no-op.
#
# config/environments/development.rb
AbstractNotifier.delivery_mode = :noop

# Default delivery mode is "normal"
AbstractNotifier.delivery_mode = :normal

NOTE: we set delivery_mode = :test if RAILS_ENV or RACK_ENV env variable is equal to "test". Otherwise add require "abstract_notifier/testing" to your spec_helper.rb / rails_helper.rb manually.

NOTE: delivery mode affects all drivers.

Testing notifier deliveries

Abstract Notifier provides two convenient RSpec matchers:

# for testing sync notifications (sent with `notify_now`)
expect { EventsNotifier.with(profile: profile).canceled(event).notify_now }
  .to have_sent_notification(identify: "123", body: "Alarma!")

# for testing async notifications (sent with `notify_later`)
expect { EventsNotifier.with(profile: profile).canceled(event).notify_later }
  .to have_enqueued_notification(via: EventNotifier, identify: "123", body: "Alarma!")

# you can also specify the expected notifier class (useful when ypu have multiple notifier lines)
expect { EventsNotifier.with(profile: profile).canceled(event).notify_now }
  .to have_sent_notification(via: EventsNotifier, identify: "123", body: "Alarma!")

Abstract Notifier also provides Minitest assertions:

require "abstract_notifier/testing/minitest"

class EventsNotifierTestCase < Minitest::Test
  include AbstractNotifier::TestHelper

  test "canceled" do
    assert_notifications_sent 1, identify: "321", body: "Alarma!" do
      EventsNotifier.with(profile: profile).canceled(event).notify_now
    end

    assert_notifications_sent 1, via: EventNofitier, identify: "123", body: "Alarma!" do
      EventsNotifier.with(profile: profile).canceled(event).notify_now
    end

    assert_notifications_enqueued 1, via: EventNofitier, identify: "123", body: "Alarma!" do
      EventsNotifier.with(profile: profile).canceled(event).notify_later
    end
  end
end

NOTE: test mode activated automatically if RAILS_ENV or RACK_ENV env variable is equal to "test". Otherwise, add require "abstract_notifier/testing/rspec" to your spec_helper.rb / rails_helper.rb manually. This is also required if you're using Spring in a test environment (e.g. with help of spring-commands-rspec).

Notifier lines for Active Delivery

Abstract Notifier provides a notifier line for Active Delivery:

class ApplicationDelivery < ActiveDelivery::Base
  # Add notifier line to you delivery
  # By default, we use `*Delivery` -> `*Notifier` resolution mechanism
  register_line :notifier, notifier: true

  # You can define a custom suffix to use for notifier classes:
  #   `*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) }
end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/active_delivery.

License

The gem is available as open source under the terms of the MIT License.

active_delivery

Development

Runtime