Publish lifecycle events to routemaster

CHANGELOG.md

@@ -1,3 +1,9 @@
+# HEAD  (2017-07-28)
+
+Features:
+
+- Publish lifecycle events to Routemaster (#19)
+
 # v1.8.1 (2017-07-27)
 
 Features:

README.md

@@ -16,16 +16,18 @@
 **Table of Contents**
 
 - [Installation](#installation)
-- [Usage](#usage)
-- [Library features](#library-features)
-    - [New Relic configuration](#new-relic-configuration)
-    - [Rack middleware](#rack-middleware)
-    - [Database configuration](#database-configuration)
-    - [Sidekiq](#sidekiq)
-    - [HireFire Workers](#hirefire-workers)
-    - [Logging](#logging)
-    - [Google Oauth](#google-oauth)
+- [Configuration and usage](#configuration-and-usage)
+  - [New Relic configuration](#new-relic-configuration)
+  - [Rack middleware](#rack-middleware)
+  - [Database configuration](#database-configuration)
+  - [Sidekiq](#sidekiq)
+  - [HireFire (for Sidekiq workers)](#hirefire-for-sidekiq-workers)
+  - [Logging](#logging)
+  - [Google OAuth authentication](#google-oauth-authentication)
+  - [Routemaster Client](#routemaster-client)
 - [Command features](#command-features)
+  - [Usage](#usage)
+  - [Description](#description)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -57,8 +59,6 @@ And then execute:
 
 Then re-run your test suite to make sure everything is shipshape.
 
-## Usage
-
 ## Configuration and usage
 
 ### New Relic configuration
@@ -199,6 +199,14 @@ application.
 
 A simple but secure example is detailed in `README.google_oauth2.md`.
 
+### Routemaster Client
+
+When `ROUTEMASTER_ENABLED` is set to `true` we attempt to configure [`routemaster-client`](https://github.com/deliveroo/routemaster-client) on your application. In order for this to happen you need to set the following environment variables:
+
+* `ROOBUS_URL` – the full URL of your Routemaster application (mandatory)
+* `ROOBUS_UUID` – the UUID of your application, e.g. `logistics-dashboard` (mandatory)
+
+If you then want to enable the publishing of events onto the event bus, you need to set `ROUTEMASTER_PUBLISHING_ENABLED` to `true` and implement publishers as needed. An example of how to do this is detailed in [`README.routemaster_client.md`](README.routemaster_client.md).
 
 ## Command features
 

README.routemaster_client.md

@@ -0,0 +1,107 @@
+## Using the Routemaster Client feature
+
+[`routemaster-client`](https://github.com/deliveroo/routemaster-client) comes as a dependency of `roo_on_rails` with a basic implementation of lifecycle event publishers.
+
+This code example assumes that you are using the latest version of the [`roo_on_rails`](roo_on_rails) gem and that you have set the correct environment variables for Routemaster Client to work on your app, as explained in the main [`README.md`](roo_on_rails#routemaster-client) file.
+
+It also assumes that your app has an API for the resources you want to publish lifecycle events for, with matching routes and an `API_HOST` environment variable set.
+
+### Setup lifecycle events for your models
+
+We will most likely want to publish lifecycle events for several models, so to write slightly less code let's create a model concern first:
+
+```ruby
+# app/models/concerns/routemaster_lifecycle_events.rb
+require 'roo_on_rails/routemaster/lifecycle_events'
+
+module RoutemasterLifecycleEvents
+  extend ActiveSupport::Concern
+  include RooOnRails::Routemaster::LifecycleEvents
+
+  included do
+    publish_lifecycle_events
+  end
+end
+```
+
+Then let's include this concern to the relevant model(s):
+
+```ruby
+# app/models/order.rb
+class Order < ApplicationRecord
+  include RoutemasterLifecycleEvents
+
+  # ...
+end
+```
+
+And another one for the example:
+
+```ruby
+# app/models/rider.rb
+class Rider < ApplicationRecord
+  include RoutemasterLifecycleEvents
+
+  # ...
+end
+```
+
+### Create publishers for lifecycle events
+
+We have now configured our models to publish lifecycle events to Routemaster, but it won't send anything until you have enabled publishing and created matching publishers. Let's start with creating a `BasePublisher` that we can then inherit from:
+
+```ruby
+# app/publishers/base_publisher.rb
+require 'roo_on_rails/routemaster/publisher'
+
+class BasePublisher < RooOnRails::Routemaster::Publisher
+  include Rails.application.routes.url_helpers
+
+  def publish?
+    noop? || model.new_record? || model.previous_changes.any?
+  end
+end
+```
+
+Then create a publisher for each model with lifecycle events enabled:
+
+```ruby
+# app/publishers/order_publisher.rb
+class OrderPublisher < BasePublisher
+  def url
+    api_order_url(model, host: ENV.fetch('API_HOST'), protocol: 'https')
+  end
+end
+```
+
+and
+
+```ruby
+# app/publishers/rider_publisher.rb
+class RiderPublisher < BasePublisher
+  def url
+    api_rider_url(model, host: ENV.fetch('API_HOST'), protocol: 'https')
+  end
+end
+```
+
+### Register the publishers with Routemaster
+
+The final step is to tell Routemaster that these publishers exist, so that it can listen to their events. We're going to do this in an initialiser:
+
+```ruby
+# config/initilizers/routemaster.rb
+require 'roo_on_rails/routemaster/publishers'
+
+PUBLISHERS = [
+  OrderPublisher,
+  RiderPublisher
+].freeze
+
+PUBLISHERS.each do |publisher|
+  model_class = publisher.to_s.gsub("Publisher", "").constantize
+  RooOnRails::Routemaster::Publishers.register(publisher, model_class: model_class)
+end
+```
+
+We should now be all set for our app to publish lifecycle events for `orders` and `riders` onto the event bus, so that other apps can listen to them.

lib/roo_on_rails.rb

@@ -12,4 +12,5 @@ module RooOnRails
   require 'roo_on_rails/railties/sidekiq'
   require 'roo_on_rails/railties/rake_tasks'
   require 'roo_on_rails/railties/google_oauth'
+  require 'roo_on_rails/railties/routemaster'
 end

lib/roo_on_rails/config.rb

@@ -25,6 +25,14 @@ def google_auth_controller
         ENV.fetch('GOOGLE_AUTH_CONTROLLER')
       end
 
+      def routemaster_enabled?
+        enabled? 'ROUTEMASTER_ENABLED', default: false
+      end
+
+      def routemaster_publishing_enabled?
+        enabled? 'ROUTEMASTER_PUBLISHING_ENABLED', default: false
+      end
+
       private
 
       ENABLED_PATTERN = /\A(YES|TRUE|ON|1)\Z/i

lib/roo_on_rails/default.env

@@ -15,6 +15,9 @@ NEW_RELIC_DEVELOPER_MODE=false
 NEW_RELIC_LICENSE_KEY=override-me
 RACK_SERVICE_TIMEOUT=10
 RACK_WAIT_TIMEOUT=30
+ROOBUS_URL=''
+ROOBUS_UUID=''
+ROUTEMASTER_ENABLED=false
 SIDEKIQ_ENABLED=true
 SIDEKIQ_THREADS=25
 SIDEKIQ_DATABASE_REAPING_FREQUENCY=10

lib/roo_on_rails/railties/routemaster.rb

@@ -0,0 +1,36 @@
+require 'roo_on_rails/config'
+
+module RooOnRails
+  module Railties
+    class Routemaster < Rails::Railtie
+      initializer 'roo_on_rails.routemaster' do
+        next unless Config.routemaster_enabled?
+
+        $stderr.puts 'initializer roo_on_rails.routemaster'
+
+        abort 'Aborting: ROOBUS_URL and ROOBUS_UUID are required' if roobus_credentials_blank?
+
+        require 'routemaster/client'
+
+        ::Routemaster::Client.configure do |config|
+          config.url = roobus_url
+          config.uuid = roobus_uuid
+        end
+      end
+
+      private
+
+      def roobus_credentials_blank?
+        roobus_url.blank? && roobus_uuid.blank?
+      end
+
+      def roobus_url
+        ENV.fetch('ROOBUS_URL')
+      end
+
+      def roobus_uuid
+        ENV.fetch('ROOBUS_UUID')
+      end
+    end
+  end
+end

lib/roo_on_rails/routemaster/lifecycle_events.rb

@@ -0,0 +1,56 @@
+require 'active_support/concern'
+require 'new_relic/agent'
+require 'roo_on_rails/routemaster/publishers'
+
+module RooOnRails
+  module Routemaster
+    module LifecycleEvents
+      extend ActiveSupport::Concern
+
+      ACTIVE_RECORD_TO_ROUTEMASTER_EVENT_MAP = {
+        create: :created,
+        update: :updated,
+        destroy: :deleted,
+        noop: :noop
+      }.freeze
+      private_constant :ACTIVE_RECORD_TO_ROUTEMASTER_EVENT_MAP
+
+      def publish_lifecycle_event(event)
+        publishers = Routemaster::Publishers.for(self, routemaster_event_type(event))
+        publishers.each do |publisher|
+          begin
+            publisher.publish!
+          rescue => e
+            NewRelic::Agent.notice_error(e)
+          end
+        end
+      end
+
+      private
+
+      def routemaster_event_type(event)
+        ACTIVE_RECORD_TO_ROUTEMASTER_EVENT_MAP[event].tap do |type|
+          raise "invalid lifecycle event '#{event}'" unless type
+        end
+      end
+
+      %i(create update destroy noop).each do |event|
+        define_method("publish_lifecycle_event_on_#{event}") do
+          publish_lifecycle_event(event)
+        end
+      end
+
+      module ClassMethods
+        def publish_lifecycle_events(*events)
+          events = events.any? ? events : %i(create update destroy)
+          events.each do |event|
+            after_commit(
+              :"publish_lifecycle_event_on_#{event}",
+              on: event
+            )
+          end
+        end
+      end
+    end
+  end
+end

lib/roo_on_rails/routemaster/publisher.rb

@@ -0,0 +1,57 @@
+require 'roo_on_rails/config'
+require 'routemaster/client'
+
+module RooOnRails
+  module Routemaster
+    class Publisher
+      attr_reader :model, :event
+
+      def initialize(model, event, client: ::Routemaster::Client)
+        @model = model
+        @event = event
+        @client = client
+      end
+
+      def publish?
+        true
+      end
+
+      def will_publish?
+        Config.routemaster_publishing_enabled? && publish?
+      end
+
+      def publish!
+        return unless will_publish?
+        @client.send(event, topic, url, data: stringify_keys(data))
+      end
+
+      def topic
+        @model.class.name.tableize
+      end
+
+      def url
+        raise NotImplementedError
+      end
+
+      def data
+        nil
+      end
+
+      %i(created updated deleted noop).each do |event_type|
+        define_method :"#{event_type}?" do
+          event.to_sym == event_type
+        end
+      end
+
+      private
+
+      def stringify_keys(hash)
+        return hash if hash.nil? || hash.empty?
+
+        hash.each_with_object({}) do |(k, v), h|
+          h[k.to_s] = v.is_a?(Hash) ? stringify_keys(v) : v
+        end
+      end
+    end
+  end
+end

lib/roo_on_rails/routemaster/publishers.rb

@@ -0,0 +1,17 @@
+module RooOnRails
+  module Routemaster
+    module Publishers
+      @publishers = {}
+
+      def self.register(publisher_class, model_class:)
+        @publishers[model_class] ||= Set.new
+        @publishers[model_class] << publisher_class
+      end
+
+      def self.for(model, event)
+        publisher_classes = @publishers[model.class]
+        publisher_classes.map { |c| c.new(model, event) }
+      end
+    end
+  end
+end

roo_on_rails.gemspec

@@ -35,6 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'omniauth-google-oauth2'
   spec.add_runtime_dependency 'faraday'
   spec.add_runtime_dependency 'faraday_middleware'
+  spec.add_runtime_dependency 'routemaster-client'
 
   spec.add_development_dependency 'bundler', '~> 1.13'
   spec.add_development_dependency 'rake', '~> 10.0'