active_delivery

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.

Active Delivery is built by Evil Martians, an American design and engineering consultancy for developer tools, AI, and cybersecurity startups.

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:

…

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

…

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 (_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.

…

Example:

# Let's log notifications
class MyDelivery  Delivery triggered: something_wicked_this_way_comes

Handling line errors

By default, if an error occurred during a delivery line notification, the delivery chain is halted and the error is raised (i.e., if the first delivery line raised an error on triggering a notification, all other lines are skipped).

You can opt-in to ignoring line errors in your base delivery class:

…

Example:

class MyNotifier  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:

…

Abstract Notifier also provides Minitest assertions:

…

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.