Abstract Notifier
Abstract Notifier is a tool which 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.
Requirements:
- Ruby ~> 2.4
NOTE: although most of the examples in this readme are Rails-specific, this gem could be used without Rails/ActiveSupport.
Installation
Add this line to your application's Gemfile:
gem "abstract_notifier"
And then execute:
$ bundle
Usage
Notifier class is very similar to Action Mailer mailer class with notification
method instead of a 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
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 a developer 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 support 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
you must configure async_adapter
.
We provide Active Job adapter out-of-the-box and use it if Active Job is present.
The custom async adapter must implement enqueue
method:
class MyAsyncAdapter
# adapters may accept options
def initialize(options = {})
end
# `enqueue` method accepts notifier class and notification
# payload.
# We need to know notifier class to use its driver.
def enqueue(notifier_class, payload)
# your implementation here
end
end
# Configure globally
AbstractNotifier.async_adapter = MyAsyncAdapter.new
# or per-notifier
class EventsNotifier < AbstractNotifier::Base
self.async_adapter = MyAsyncAdapter.new
end
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
Abstract Notifier provides two convinient 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(identify: "123", body: "Alarma!")
Abstract Notifier provides two convinient minitest assertions:
require 'abstract_notifier/testing/minitest'
class EventsNotifierTestCase < Minitest::Test
include AbstractNotifier::TestHelper
test 'canceled' do
assert_notifications_sent 1, identify: "123", body: "Alarma!" do
EventsNotifier.with(profile: profile).canceled(event).notify_now
end
assert_notifications_enqueued 1, 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 test environment (e.g. with help of spring-commands-rspec).
Related projects
active_delivery
Active Delivery is the next-level abstraction which allows combining multiple notification channels in one place.
Abstract Notifier provides a notifier line for Active Delivery:
class ApplicationDelivery < ActiveDelivery::Base
# Add notifier line to you delivery
register_line :notifier, ActiveDelivery::Lines::Notifier,
# you may provide a resolver, which infers notifier class
# from delivery name (resolver is a callable).
resolver: ->(name) { resolve_somehow(name) }
end
NOTE: we automatically add :notifier
line with "*Delivery" -> *Notifier
resolution mechanism if #safe_constantize
method is defined for String, i.e., you don't have to configure the default notifier line when running Rails.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/abstract_notifier.
License
The gem is available as open source under the terms of the MIT License.