reactor.gem

A Sidekiq-backed pub/sub layer for your Rails app.

Build Status

This gem aims to provide the following tools to augment your ActiveRecord & Sidekiq stack.

  1. Barebones event API through Sidekiq to publish whatever you want
  2. Database-driven API to manage subscribers so that users may rewire whatever you let them (transactional emails, campaigns, etc...)
  3. Static/Code-driven API to subscribe a basic ruby block to an event.
  4. A new communication pattern between your ActiveRecord models that runs asynchronously through Sidekiq. a. describe model lifecycle events and callbacks with class-level helper methods/DSL

Installation

Add this line to your application's Gemfile:

gem 'reactor'

And then execute:

$ bundle

Or install it yourself as:

$ gem install reactor

Usage

Well, this is evolving, so it's probably best to go read the specs.

Barebones API

Reactor::Event.publish(:event_name, any: 'data', you: 'want')

ActiveModel extensions

Publishable

Describe lifecycle events like so

publishes :my_model_created

Schedule an event to get published at a specific time. Note: if timestamp is a property on an ActiveRecord::Model then updating that property will re-schedule the firing of the event

publishes :something_happened, at: :timestamp

Schedule an event to get published at a specific time using a method to generate the timestamp and following some other property. In this case the :something_happened event will be fired 72 hours after your model is created. The event will be re-scheduled if created_at is changed.

def reminder_email_time
  created_at + 72.hours
end

publishes :reminder_sent, at: :reminder_email_time, watch: :created_at

Scheduled events can check conditionally fire -- eg: in 2 days fire reminder_email if the user hasn't already responded.

publishes :reminder_sent, at: :reminder_email_time, if: -> { user.responded == false }

Subscribable

You can now bind any block to an event in your models like so

on_event :any_event do |event|
  event.target.do_something_about_it!
end

Static subscribers like these are automatically placed into Sidekiq and executed in the background

It's also possible to run a subscriber block in memory like so

on_event :any_event, in_memory: true do |event|
  event.target.do_something_about_it_and_make_the_user_wait!
end

ResourceActionable

Enforce a strict 1:1 match between your event model and database model with this controller mixin.

class PetsController < ApplicationController
  include Reactor::ResourceActionable
  actionable_resource :@pet

  # GET /pets
  # GET /pets.json
  def index
    @pets = current_user.pets

    respond_to do |format|
      format.html # index.html.erb
      format.json { render json: @pets }
    end
  end

  def show
    @pet = current_user.pets.find(params[:id])
    respond_to do |format|
      format.html # index.html.erb
      format.json { render json: @pet }
    end
  end
end

Now your index action (and any of the other RESTful actions in that controller) will fire a useful event for you to bind to and log.

Important Reactor::ResourceActionable has one major usage constraints:

Your controller must have a method called "action_event" with this signature.

def action_event(name, options = {})
  # Here's what ours looks like, but yours may look different.
  actor = options[:actor] || current_user
  actor.publish(name, options.merge(default_action_parameters))
  #where default_action_parameters includes things like ip_address, referrer, user_agent
end

Once you write your own action_event to describe your event data model's base attributes, your ResourceActionable endpoints will now fire events that map like so (for the example above):

index =>
"pets_indexed"
show =>
"pet_viewed", target: @pet
new =>
"new_pet_form_viewed"
edit =>
"edit_pet_form_viewed", target: @pet
create =>
when valid => "pet_created", target: @pet, attributes: params[:pet]
when invalid => "pet_create_failed", errors: @pet.errors, attributes: params[:pet]
update =>
when valid => "pet_updated", target: @pet, changes: @pet.previous_changes.as_json
when invalid => "pet_update_failed", target: @pet, errors: @pet.errors.as_json, attributes: params[:pet]
destroy =>
"pet_destroyed", last_snapshot: @pet.as_jsont
What for?

If you're obsessive about data like us, you'll have written a '*' subscriber that logs every event fired in the system. With information-dense resource information logged for each action a user performs, it will be trivial for a data analyst to determine patterns in user activity. For example, with the above data being logged for the pet resource, we can easily

  • determine which form field validations are constantly being hit by users
  • see if there are any fields that are consistently ignored on that form until later
  • recover data from the last_snapshot of a destroyed record
  • write a small conversion funnel analysis to see who never makes it back to a record to update it
  • bind arbitrary logic anywhere in the codebase (see next example) to that specific request without worrying about the logic being run during the request (all listeners are run in the background by Sidekiq)

For example, in an action mailer.

class MyMailer < ActionMailer::Base
  include Reactor::EventMailer

  on_event :pet_created do |event|
    @user = event.actor
    @pet = event.target
    mail to: @user.email, subject: "Your pet is already hungry!", body: "feed it."
  end
end

Or in a model, concern, or other business logic file.

class MyClass
  include Reactor::Subscribable

  on_event :pet_updated do |event|
     event.actor.recalculate_expensive_something_for(event.target)
  end
end

Testing

Calling Reactor.test_mode! enables test mode. (You should call this as early as possible, before your subscriber classes are declared). In test mode, no subscribers will fire unless they are specifically enabled, which can be accomplished by calling

Reactor.enable_test_mode_subscriber(MyAwesomeSubscriberClass)

We also provide

Reactor.with_subscriber_enabled(MyClass) do
  # stuff
end

for your testing convenience.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Open Source by Hired

We are Ruby developers ourselves, and we use all of our open source projects in production. We always encourge forks, pull requests, and issues. Get in touch with the Hired Engineering team at [email protected].