active_job_channel 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 320dedafebbd7d4642c253ffe2e4293aa6d9ca20766000877e2fef2659751b6d
-  data.tar.gz: 2b38d9bc1f43db7580565df60ebccee630144322f54d96177626178273cb028f
+  metadata.gz: '058d0b861b22420aa23b79986d3d73bb01cbe27d7279ef706382edb7a4d47ba5'
+  data.tar.gz: 79aaf5fbd4416e22a93c9a14353ef41c7d6965d58670d4815e3af6f86b88f726
 SHA512:
-  metadata.gz: f77cd6a65e6b4573ff228ec71b7560f2fac1a29c73297a9e87add526bea6bb3015502b1b3ba139c44a84ded923723549ae4691d2d14fd0866a0e713df051a109
-  data.tar.gz: 97098bdf643d30d8048672957eda0ea6dabaf15fbd7f12a60843d78d727c002e3af8611120abb6170e600c5efae93f31eb2bcd9fdd7e2c2e629419e823c6d3ff
+  metadata.gz: 5f12183f81a90854fb76a584d93b96ef6e656f41b4ff0926ef6a242b275b14fe3e6172abd830264ee425732016fafc4b448476b3b32ba15d76f4f7c900b8ea96
+  data.tar.gz: b5e178a2ed8ac074fd4350d9f884373e142aa0ea73712570e3e10d86efc196f70eb4b083d604e78d8a4aec277b844d91bdb8aa2217634ed8274ff49813416bd0

data/README.md

@@ -1,5 +1,5 @@
-# `ActiveJobChannel`
-Uses `ActionCable` to alert front-end users of finished `ActiveJobs`
+# ActiveJobChannel
+Use ActionCable to alert front-end users of finished ActiveJobs
 
 ## Installation
 1. Install in your Gemfile
@@ -8,15 +8,60 @@ Uses `ActionCable` to alert front-end users of finished `ActiveJobs`
     gem 'active_job_channel'
     ```
 
-2. Setup an [`ActionCable` subscription adapter](http://edgeguides.rubyonrails.org/action_cable_overview.html#subscription-adapter)
+## Setup
+1. [Create ActionCable Connection](#create-actioncable-connection-optional) (optional)
+2. [Enable ActiveJobChannel for a job](#enable-activejobchannel-for-a-job)
+3. [Handle ActiveJobChannel broadcasts](#handle-activejobchannel-broadcasts)
+
+### Create ActionCable Connection (optional)
+
+You can skip this step if you're not concerned with authorizing or brodcasting 
+privately to ActionCable connections
+
+1. Setup an [ActionCable subscription adapter](http://edgeguides.rubyonrails.org/action_cable_overview.html#subscription-adapter)
     * Note: A persisted subscription adapter is required for handling notifications
-    from background `ActiveJob` processes. Currently only PostgreSQL and Redis
+    from background ActiveJob processes. Currently only PostgreSQL and Redis
     are supported.
+2. Follow the [official guide for setting up an ActionCable Connection](http://guides.rubyonrails.org/action_cable_overview.html#server-side-components-connections)
+3. If you would like notifications broadcast privately to ActionCable 
+    connections, set up a connection identifier for your connection using 
+    `identified_by`. The identifier you use will also need to be passed to your 
+    job.
+
+### Enable ActiveJobChannel for a job
+1. For each job you'd like to be notified about, call `active_job_channel` in 
+    its class
+2. To broadcast notifications privately, set the identifier you configured in
+    your ActionCable Connection setup to either the instance variable 
+    `@ajc_identifier` or the method `ajc_identifier`
+
+```ruby
+class MyJob < ActiveJob::Base
+  active_job_channel
+
+  def perform(current_user)
+    @ajc_identifier = current_user
+  end
+
+  private
+
+  # def ajc_identifier
+  #   User.find_by(key: value)
+  # end
+end
+```
 
-3. (Optional) If you need authorization for notifications, [set up your own
-    `ApplicationCable::Connection`](http://guides.rubyonrails.org/action_cable_overview.html#server-side-components-connections)
+#### Configuration
 
-3. Include `active_job_channel.js` in your layouts
+##### global_broadcast
+
+Notifications will be broadcast to `ajc_identifier` by default. To broadcast
+all notifications for a job to all ActionCable connections, pass 
+`{ global_broadcast: true }` to `active_job_channel`.
+
+### Handle ActiveJobChannel broadcasts
+
+1. Include `active_job_channel.js` in your layouts
 
     ```ruby
     javascript_include_tag 'active_job_channel'
@@ -28,40 +73,28 @@ Uses `ActionCable` to alert front-end users of finished `ActiveJobs`
       //= require active_job_channel
     ```
 
-## Usage
-For each job you'd like to be notified about, enable `active_job_channel`
+2. Customize the callbacks for broadcasted notifications:
 
-```ruby
-class MyJob < ActiveJob::Base
-  active_job_channel
-end
-```
+    ```javascript
+    //= require notifyjs
 
-To customize the client-side notification, define `ActiveJobChannel.received`
-after including `active_job_channel.js`. The current default simply logs the 
-job status to the javascript console.
+    ActiveJobChannel.onJobSuccess = function(job) { $.notify(job.name + ' succeeded!') }; 
+    ActiveJobChannel.onJobFailure = function(job) { $.notify(job.name + ' failed!') };
+    ```
 
-```javascript
-  //= require notifyjs
-  //= require active_job_channel
+    `job` has the attributes `name` and `status`. A failed `job` includes an 
+    `error` attribute. `status` is one of `success` or `failure`. 
 
-  ActiveJobChannel.received = function(data) {
-    var status = data.status;
-    var job_name = data.job_name;
-    if (status === 'success') { $.notify(job_name + ' succeeded!') }
-    else if (status === 'failure') { $.notify(job_name + ' failed!') }
-  }
-```
 
 ## Caveats
-`ActiveJobChannel` depends on `ActiveJob` and `ActionCable`, and, as such, is
+ActiveJobChannel depends on ActiveJob and ActionCable, and, as such, is
 subject to their limitations:
 
 * A persisted [subscription adapter](http://guides.rubyonrails.org/action_cable_overview.html#subscription-adapter)
-is required for `ActionCable` to handle notifications from background 
-`ActiveJob` processes
-* Because `ActiveJob` does not know when a job has permanently failed, 
-`ActiveJobChannel` sends notfications for each failure, retried or final
+is required for ActionCable to handle notifications from background 
+ActiveJob processes
+* Because ActiveJob does not know when a job has permanently failed, 
+ActiveJobChannel sends notfications for each failure, retried or final
 
 ## Todo
 - Better default front-end notification behavior

data/Rakefile

@@ -1,22 +1,20 @@
-#!/usr/bin/env rake
-
 begin
   require 'bundler/setup'
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+APP_RAKEFILE = File.expand_path('../spec/dummy/Rakefile', __FILE__)
 load 'rails/tasks/engine.rake'
 
 Bundler::GemHelper.install_tasks
 
-Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each { |f| load f }
 
 require 'rspec/core'
 require 'rspec/core/rake_task'
 
 desc 'Run all specs in spec directory (excluding plugin specs)'
-RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/lib/active_job_channel/broadcaster.rb

@@ -1,10 +1,30 @@
 module ActiveJobChannel
   module Broadcaster
+    class NoIdentifierError < NameError
+      MESSAGE = 'ActiveJobChannel expects an ActionCable Connection ' \
+        'identifier to broadcast to. The identifier should be made available ' \
+        'in your job via a method or an instance variable, either named ' \
+        '`ajc_identifier`. For details about setting up an identifier in ' \
+        'your ActionCable Connection, visit http://guides.rubyonrails.org/' \
+        "action_cable_overview.html#connection-setup\n\nTo broadcast " \
+        'globally without an identifier, pass in ' \
+        '`{ global_broadcast: true } ` to `active_job_channel` as part of an ' \
+        'options hash.'.freeze
+
+      def initialize(msg = MESSAGE)
+        super
+      end
+    end
+
     module ClassMethods
-      def active_job_channel
+      def active_job_channel(options = {})
+        class_attribute :ajc_config
+        self.ajc_config = { global_broadcast: false }
+        self.ajc_config.merge!(options)
+
         after_perform :broadcast_success
         rescue_from '::StandardError' do |exception|
-          broadcast_failure
+          broadcast_failure(exception)
           raise exception
         end
 
@@ -13,17 +33,41 @@ module ActiveJobChannel
     end
 
     module InstanceMethods
-      def broadcast_failure
-        ActiveJobChannel::Channel.broadcast_to(
-          'active_job_channel',
+      private
+
+      attr_writer :ajc_identifier
+
+      def ajc_channel_name
+        if ajc_config[:global_broadcast]
+          ::ActiveJobChannel::Channel::CHANNEL_NAME
+        else
+          [::ActiveJobChannel::Channel::CHANNEL_NAME, ajc_identifier].
+            compact.
+            join('#')
+        end
+      end
+
+      def ajc_identifier
+        raise NoIdentifierError if ajc_identifier_missing?
+        @ajc_identifier
+      end
+
+      def ajc_identifier_missing?
+        !ajc_config[:global_broadcast] && @ajc_identifier.nil?
+      end
+
+      def broadcast_failure(exception)
+        ActionCable.server.broadcast(
+          ajc_channel_name,
           status: 'failure',
-          job_name: self.class.to_s
+          job_name: self.class.to_s,
+          error: exception.inspect
         )
       end
 
       def broadcast_success
-        ActiveJobChannel::Channel.broadcast_to(
-          'active_job_channel',
+        ActionCable.server.broadcast(
+          ajc_channel_name,
           status: 'success',
           job_name: self.class.to_s
         )

data/lib/active_job_channel/channel.rb

@@ -1,7 +1,20 @@
 module ActiveJobChannel
   class Channel < ::ActionCable::Channel::Base
+    CHANNEL_NAME = 'active_job_channel'.freeze
+
     def subscribed
-      stream_from 'active_job_channel'
+      stream_from CHANNEL_NAME
+      stream_from private_stream if connection.connection_identifier.present?
+    end
+
+    private
+
+    def global_stream
+      stream_from CHANNEL_NAME
+    end
+
+    def private_stream
+      [CHANNEL_NAME, connection.connection_identifier].join('#')
     end
   end
 end

data/lib/active_job_channel/engine.rb

@@ -1,4 +1,6 @@
 module ActiveJobChannel
+  # An Engine ties us into a Rails app
+  # doc: http://guides.rubyonrails.org/engines.html
   class Engine < ::Rails::Engine
     ActiveSupport.on_load(:active_job) do
       require 'active_job_channel/broadcaster'

data/lib/active_job_channel/version.rb

@@ -1,3 +1,3 @@
 module ActiveJobChannel
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.0.3'.freeze
 end

data/spec/dummy/app/assets/javascripts/application.js

@@ -11,4 +11,4 @@
 // about supported directives.
 //
 //= require_tree .
-//= require 'active_job_channel/application'
+//= require 'active_job_channel'

data/spec/dummy/app/channels/application_cable/connection.rb

@@ -0,0 +1,9 @@
+module ApplicationCable
+  class Connection < ::ActionCable::Connection::Base
+    identified_by :current_user
+
+    def connect
+      self.current_user = 'bloop'
+    end
+  end
+end

data/spec/dummy/app/controllers/front_controller.rb

@@ -1,6 +1,6 @@
 class FrontController < ::ApplicationController
   def index
-    ::ApplicationJob.new.enqueue(wait: 5.seconds)
+    ::ApplicationJob.set(wait: 5.seconds).perform_later('bloop')
     render 'front/index'
   end
 end

data/spec/dummy/app/jobs/application_job.rb

@@ -1,7 +1,8 @@
 class ApplicationJob < ActiveJob::Base
-  active_job_channel
+  active_job_channel global_broadcast: true
 
-  def perform
+  def perform(identifier)
+    @ajc_identifier = identifier
     fake
   end