active_job_channel 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e15e3cd0deda9ddda3a0d594f125554938b14233444b6f7f6f53ae24cbb3bbac
-  data.tar.gz: 448bfe9ff104ebc3f489de2fe8f95591fcca443efef647d63c264717187542ba
+  metadata.gz: 67acfe4dc3f2f46d29abb91af96f618e518f42393bb178ea06e593271beb285c
+  data.tar.gz: 44bb11f232a8959da9caa402d40adf829f4f0da49210367af2f10d70f7dde7c2
 SHA512:
-  metadata.gz: 52748705d9f2f217353138fc768910c5e2ef5daa4df099fc9f9e2a6a863c82df66dfadadc1d8a8307a8bc719a0fbf2bb1d5a6d336e7f20458787810e1a18762c
-  data.tar.gz: 56dad2e05f5e500f228c0b0c1ee89d53ad3064d54946ab599a0613706f940ce60b34d91ae70b4674871b85fd804788ff398776d50b23bd2c118615fc26f295d9
+  metadata.gz: 967364ada0575ce6b4070106e853b03ae23df6ba41604171f502526e5fc3ee033245d231d958a2f655c4bef06544dd55ffee89dad571b7b75215185290ddf7dc
+  data.tar.gz: fbe0e3f83a1963247d50773a4c8110d8f6bed0f87e614783a069622a231ba122194c835fa274d237167ab6a3ef80320dac9fa2afeca7f69ba05ce322fdeff16f

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [semver 2.0.0](http://semver.org/spec/v2.0.0.html) and the
+recommendations of [keepachangelog.com](http://keepachangelog.com/).
+
+## Unreleased
+### Added
+### Changed
+
+## 0.4.0 - 2018-02-11
+### Added
+- `4a74b7a4b75cce1903c9825113a27d502dccf23a` The name of the job's class is
+included in ActiveJobChannel's own exceptions
+
+### Changed
+- `fc1ea49962418d512c8725d8a6af6e08c506019d` Broadcast all job data generated by
+ActiveJob. This alters the structure of the broadcasted JSON object
+- `5e71bcd` User must now explicitly require `ActiveJobChannel` in a job. This 
+is to not to add unwanted methods to other jobs.
+
+## 0.3.0 - 2018-01-14
+Previous releases did not follow semantic versioning. This release is 
+functionally equivalent to 0.0.3, but adheres to semantic versioning. This 
+release has non-functional changes, mostly additional specs and doc updates.
+
+## 0.0.3 - 2018-01-13
+### Added
+- Broadcast notifications privately to connection identifiers
+- Option to broadcast notifications globally to all connections
+- Configurable client-side broadcast callbacks `ActiveJobChannel.onJobSuccess`
+    and `ActiveJobChannel.onJobFailure`
+
+## 0.0.2 - 2017-12-02
+- Use our own websocket endpoint
+- Use `stream_from` rather than `stream_for` when connecting to our channel
+- Simplify organization
+
+## 0.0.1 - 2017-12-02
+- Initial release

data/README.md

@@ -1,8 +1,22 @@
 [![Gem Version](https://badge.fury.io/rb/active_job_channel.svg)](https://badge.fury.io/rb/active_job_channel)
+[![Build Status](https://travis-ci.org/shanecav84/active_job_channel.svg?branch=master)](https://travis-ci.org/shanecav84/active_job_channel)
 
 # ActiveJobChannel
 Use ActionCable to alert front-end users of finished ActiveJobs
 
+* [Installation](#installation)
+* [Setup](#setup)
+  1. [Create ActionCable Connection](#create-connection) (optional)
+  2. [Enable ActiveJobChannel for a job](#enable-active_job_channel)
+      * [Configuration](#configuration)
+        * [`global_brodcast`](#global_broadcast)
+  3. [Handle ActiveJobChannel broadcasts](#handle-broadcasts)
+* [Caveats](#caveats)
+* [Todo](#todo)
+* [Contributing](#contributing)
+    * [Dev setup](#dev-setup)
+* [License](#license)
+
 ## Installation
 1. Install in your Gemfile
 
@@ -11,11 +25,8 @@ Use ActionCable to alert front-end users of finished ActiveJobs
     ```
 
 ## 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)
+### <a name="create-connection"></a> 1. Create ActionCable Connection (optional)
 
 You can skip this step if you're not concerned with authorizing or brodcasting 
 privately to ActionCable connections
@@ -30,28 +41,43 @@ privately to ActionCable connections
     `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
+### <a name="enable-active_job_channel"></a> 2. Enable ActiveJobChannel for a job
+1. For each job you'd like to be notified about, include `ActiveJobChannel` and 
+    call `active_job_channel` in its class
+2. Private vs. Public broadcasts
+    1. To broadcast notifications privately to a specific connection, 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
+      include ActiveJobChannel
+      active_job_channel
+    
+      def perform(current_user)
+        @ajc_identifier = current_user
+      end
+    
+      private
+    
+      # def ajc_identifier
+      #   User.find_by(key: value)
+      # end
+    end
+    ```
+    
+    2. To broadcast publicly to all ActionCable connections, pass 
+    `{ global_broadcast: true }` to `active_job_channel` and do not set `ajc_identifier`
+    
+    ```ruby
+    class MyJob < ActiveJob::Base
+      include ActiveJobChannel
+      active_job_channel global_broadcast: true
+    
+      def perform; end
+    end
+    ```
 
-  # def ajc_identifier
-  #   User.find_by(key: value)
-  # end
-end
-```
 
 #### Configuration
 
@@ -61,7 +87,7 @@ 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
+### <a name="handle-broadcasts"></a> 3. Handle ActiveJobChannel broadcasts
 
 1. Include `active_job_channel.js` in your layouts
 
@@ -80,12 +106,25 @@ all notifications for a job to all ActionCable connections, pass
     ```javascript
     //= require notifyjs
 
-    ActiveJobChannel.onJobSuccess = function(job) { $.notify(job.name + ' succeeded!') }; 
-    ActiveJobChannel.onJobFailure = function(job) { $.notify(job.name + ' failed!') };
+    ActiveJobChannel.onJobSuccess = function(job) { $.notify(job.data.job_class + ' succeeded!') }; 
+    ActiveJobChannel.onJobFailure = function(job) { $.notify(job.data.job_class + ' failed!') };
     ```
 
-    `job` has the attributes `name` and `status`. A failed `job` includes an 
-    `error` attribute. `status` is one of `success` or `failure`. 
+    `job` is a JSON object that has the attributes `status` and `data`. The value
+    of `status` can be one of `success` or `failure`. The value of `data` is a
+    JSON object of [job data serialized by ActiveJob](https://github.com/rails/rails/blob/649f19cab1d4dd805c915912ede29c86655084cd/activejob/lib/active_job/core.rb#L79). 
+    It has the following keys:
+    - "job_class"
+    - "job_id" - Internal ActiveJob job identifier
+    - "provider_job_id" - ID optionally provided by ActiveJob queue adapter
+    - "queue_name"
+    - "priority"
+    - "arguments" - arguments passed to the job
+    - "executions" - how many times the job was attempted
+    - "locale"
+
+    A failed `job` includes an `error` attribute with the result of calling
+    `inspect` on the exception that precpitated the failure.
 
 
 ## Caveats
@@ -101,5 +140,24 @@ ActiveJobChannel sends notfications for each failure, retried or final
 ## Todo
 - Better default front-end notification behavior
 
+## Contributing
+   
+Issues and pull requests are welcome.
+
+### Dev setup
+
+1. Clone the project
+   ```bash
+   git clone https://github.com/shanecav84/active_job_channel
+   ```
+2. Install dependencies
+   ```bash
+   bundle install
+   ```
+3. Run the tests
+   ```bash
+   bundle exec rake
+   ```
+
 ## License
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -24,6 +24,8 @@ RuboCop::RakeTask.new
 require 'rspec/core'
 require 'rspec/core/rake_task'
 desc 'Run all specs in spec directory (excluding plugin specs)'
-RSpec::Core::RakeTask.new
+RSpec::Core::RakeTask.new do |t|
+  t.verbose = false
+end
 
 task default: %i[bundle:audit rubocop spec]

data/lib/active_job_channel.rb

@@ -1,4 +1,9 @@
+require 'active_job_channel/broadcaster'
 require 'active_job_channel/engine'
+require 'active_job_channel/exceptions'
+require 'active_support/concern'
 
-# Top-level namespace
-module ActiveJobChannel; end
+module ActiveJobChannel
+  extend ActiveSupport::Concern
+  include ::ActiveJobChannel::Broadcaster
+end

data/lib/active_job_channel/broadcaster.rb

@@ -1,22 +1,11 @@
+require 'active_support/concern'
+require 'active_job_channel/channel'
+
 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
+    extend ActiveSupport::Concern
 
-    module ClassMethods
+    class_methods do
       def active_job_channel(options = {})
         class_attribute :ajc_config
         self.ajc_config = { global_broadcast: false }
@@ -27,18 +16,21 @@ module ActiveJobChannel
           broadcast_failure(exception)
           raise exception
         end
-
-        include ActiveJobChannel::Broadcaster::InstanceMethods
       end
     end
 
-    module InstanceMethods
+    # rubocop:disable Metrics/BlockLength
+    included do
       private
 
       attr_writer :ajc_identifier
 
       def ajc_channel_name
         if ajc_config[:global_broadcast]
+          if ajc_identifier.present?
+            raise UnnecessaryIdentifierError, self.class.to_s
+          end
+
           ::ActiveJobChannel::Channel::CHANNEL_NAME
         else
           [::ActiveJobChannel::Channel::CHANNEL_NAME, ajc_identifier].
@@ -48,7 +40,10 @@ module ActiveJobChannel
       end
 
       def ajc_identifier
-        raise NoIdentifierError if ajc_identifier_missing?
+        if ajc_identifier_missing?
+          raise ::ActiveJobChannel::NoIdentifierError, self.class.to_s
+        end
+
         @ajc_identifier
       end
 
@@ -57,21 +52,22 @@ module ActiveJobChannel
       end
 
       def broadcast_failure(exception)
-        ActionCable.server.broadcast(
+        ::ActionCable.server.broadcast(
           ajc_channel_name,
           status: 'failure',
-          job_name: self.class.to_s,
+          data: serialize,
           error: exception.inspect
         )
       end
 
       def broadcast_success
-        ActionCable.server.broadcast(
+        ::ActionCable.server.broadcast(
           ajc_channel_name,
           status: 'success',
-          job_name: self.class.to_s
+          data: serialize
         )
       end
     end
+    # rubocop:enable Metrics/BlockLength
   end
 end

data/lib/active_job_channel/channel.rb

@@ -1,3 +1,5 @@
+require 'action_cable'
+
 module ActiveJobChannel
   class Channel < ::ActionCable::Channel::Base
     CHANNEL_NAME = 'active_job_channel'.freeze
@@ -9,10 +11,6 @@ module ActiveJobChannel
 
     private
 
-    def global_stream
-      stream_from CHANNEL_NAME
-    end
-
     def private_stream
       [CHANNEL_NAME, connection.connection_identifier].join('#')
     end

data/lib/active_job_channel/engine.rb

@@ -1,18 +1,18 @@
+require 'rails'
+
 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
+    ::ActiveSupport.on_load(:active_job) do
       require 'active_job_channel/broadcaster'
-      ActiveJob::Base.send :extend, ActiveJobChannel::Broadcaster::ClassMethods
     end
 
-    ActiveSupport.on_load(:action_cable) do
+    ::ActiveSupport.on_load(:action_cable) do
       require 'active_job_channel/channel'
-    end
-
-    routes.draw do
-      mount ActionCable.server => '/cable/active_job_channel'
+      routes.draw do
+        mount ::ActionCable.server => '/cable/active_job_channel'
+      end
     end
   end
 end

data/lib/active_job_channel/exceptions.rb

@@ -0,0 +1,46 @@
+module ActiveJobChannel
+  class Error < StandardError; end
+
+  class NoIdentifierError < ::ActiveJobChannel::Error
+    attr_reader :job_class
+
+    def initialize(job_class)
+      @job_class = job_class
+      super(generate_message)
+    end
+
+    private
+
+    def generate_message
+      'ActiveJobChannel has been configured to broadcast privately for ' \
+        "#{job_class}, but an `ajc_identifier` has not been set. 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.'
+    end
+  end
+
+  class UnnecessaryIdentifierError < ::ActiveJobChannel::Error
+    attr_reader :job_class
+
+    def initialize(job_class)
+      @job_class = job_class
+      super(generate_message)
+    end
+
+    private
+
+    def generate_message
+      'ActiveJobChannel has been configured to broadcast globally for ' \
+        "#{job_class}, but an `ajc_identifier` has been set. If the job " \
+        'information should be broadcast globally, remove the ' \
+        '`ajc_identifier`. Otherwise, pass in `{ global_broadcast: true } ` ' \
+        'to `active_job_channel` as part of an options hash'
+    end
+  end
+end

data/lib/active_job_channel/version.rb

@@ -1,3 +1,3 @@
 module ActiveJobChannel
-  VERSION = '0.3.0'.freeze
+  VERSION = '0.4.0'.freeze
 end

data/spec/active_job_channel/broadcaster_spec.rb

@@ -1,12 +1,14 @@
-require 'active_job_channel/broadcaster'
 require 'spec_helper'
+require 'active_job'
 
 module ActiveJobChannel
   module Broadcaster
     RSpec.describe ClassMethods do
       before(:each) do
-        class DummyJob < ActiveJob::Base
+        class DummyJob < ::ActiveJob::Base
+          include ActiveJobChannel
           active_job_channel global_broadcast: true
+
           def perform
             fake
           end
@@ -15,7 +17,6 @@ module ActiveJobChannel
 
           def fake; end
         end
-        DummyJob.extend(described_class)
       end
 
       describe '.active_job_channel' do
@@ -33,6 +34,9 @@ module ActiveJobChannel
           allow_any_instance_of(DummyJob).
             to receive(:fake).
             and_raise(StandardError)
+          allow_any_instance_of(DummyJob).
+            to receive(:serialize).
+            and_return({})
           expect_any_instance_of(DummyJob).
             to receive(:broadcast_failure).
             with(StandardError).
@@ -45,7 +49,7 @@ module ActiveJobChannel
             with(
               ::ActiveJobChannel::Channel::CHANNEL_NAME,
               status: 'failure',
-              job_name: DummyJob.to_s,
+              data: {},
               error: StandardError.new.inspect
             )
 
@@ -62,6 +66,9 @@ module ActiveJobChannel
             allow_any_instance_of(DummyJob).
               to receive(:ajc_identifier).
               and_return(ajc_identifier)
+            allow_any_instance_of(DummyJob).
+              to receive(:serialize).
+              and_return({})
             expect_any_instance_of(DummyJob).
               to receive(:broadcast_failure).
               with(StandardError).
@@ -77,7 +84,7 @@ module ActiveJobChannel
                 "#{::ActiveJobChannel::Channel::CHANNEL_NAME}#" \
                   "#{ajc_identifier}",
                 status: 'failure',
-                job_name: DummyJob.to_s,
+                data: {},
                 error: StandardError.new.inspect
               )
 
@@ -91,6 +98,9 @@ module ActiveJobChannel
           expect_any_instance_of(DummyJob).
             to receive(:broadcast_success).
             and_call_original
+          allow_any_instance_of(DummyJob).
+            to receive(:serialize).
+            and_return({})
 
           action_cable_server = double 'action_cable_server'
           allow(ActionCable).to receive(:server).and_return(action_cable_server)
@@ -99,45 +109,58 @@ module ActiveJobChannel
             with(
               ::ActiveJobChannel::Channel::CHANNEL_NAME,
               status: 'success',
-              job_name: DummyJob.to_s
+              data: {}
             )
 
           DummyJob.perform_now
         end
+      end
 
-        context 'with ajc_identifier' do
-          it 'broadcast success to the identifier' do
-            DummyJob.active_job_channel global_broadcast: false
-            ajc_identifier = 'ajc_identifier'
-            allow_any_instance_of(DummyJob).
-              to receive(:ajc_identifier).
-              and_return(ajc_identifier)
-            expect_any_instance_of(DummyJob).
-              to receive(:broadcast_success).
-              and_call_original
+      describe 'ajc_identifier' do
+        it 'broadcasts success to the identifier' do
+          DummyJob.active_job_channel global_broadcast: false
+          ajc_identifier = 'ajc_identifier'
+          allow_any_instance_of(DummyJob).
+            to receive(:ajc_identifier).
+            and_return(ajc_identifier)
+          allow_any_instance_of(DummyJob).
+            to receive(:serialize).
+            and_return({})
+          expect_any_instance_of(DummyJob).
+            to receive(:broadcast_success).
+            and_call_original
 
-            action_cable_server = double 'action_cable_server'
-            allow(ActionCable).
-              to receive(:server).
-              and_return(action_cable_server)
-            expect(action_cable_server).
-              to receive(:broadcast).
-              with(
-                "#{::ActiveJobChannel::Channel::CHANNEL_NAME}#" \
-                  "#{ajc_identifier}",
-                status: 'success',
-                job_name: DummyJob.to_s
-              )
+          action_cable_server = double 'action_cable_server'
+          allow(ActionCable).
+            to receive(:server).
+            and_return(action_cable_server)
+          expect(action_cable_server).
+            to receive(:broadcast).
+            with(
+              "#{::ActiveJobChannel::Channel::CHANNEL_NAME}#" \
+                "#{ajc_identifier}",
+              status: 'success',
+              data: {}
+            )
 
-            DummyJob.perform_now
-          end
+          DummyJob.perform_now
+        end
+
+        it 'must not be set for a global broadcast' do
+          DummyJob.active_job_channel global_broadcast: true
+          allow_any_instance_of(DummyJob).
+            to receive(:ajc_identifier).
+            and_return('ajc_identifier')
+          expect { DummyJob.perform_now }.
+            to raise_error(::ActiveJobChannel::UnnecessaryIdentifierError).
+            with_message(/DummyJob/)
         end
-      end
 
-      describe 'NoIdentifierError' do
-        it 'is raised when ajc_identifier is missing for private broadcast' do
+        it 'must be set for a private broadcast' do
           DummyJob.active_job_channel global_broadcast: false
-          expect { DummyJob.perform_now }.to raise_error(NoIdentifierError)
+          expect { DummyJob.perform_now }.
+            to raise_error(::ActiveJobChannel::NoIdentifierError).
+            with_message(/DummyJob/)
         end
       end
     end