sidekiq-job_monitor 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e3c554ad234720879c74de12d2cf115cb1708012
-  data.tar.gz: cc071f88a7897b1b81e0bd4969b0100b3e046544
+  metadata.gz: 3b1d3e4b21e888c43304c1353a7cd44d9bd9fb7f
+  data.tar.gz: a4b8740f91c16aeb23fccf94f0c47c980857bb28
 SHA512:
-  metadata.gz: f2a7a616be721bb98f986d7e730a8417fc4aa4a92807dd2b9dcf4825299f18b68f47d822d55cd76aed0604821e8e8db9861e80a4e0fb5f5bd92aaf3a3e5b6d24
-  data.tar.gz: f20aed8dca5422ad05d0b541ba158b214b4c55e9dc9b0333cfc67cad8fddbf86ddd2186e4a391b458167a1f4fa9337a8cee9a75fdf5917176a54335999e9d5e0
+  metadata.gz: 3549b4f766d1742c3222f316797c5ba60ac519579beb2b21a05ab752114fce74450ebca64284feeacd5c6d87666fc7415eb9992a016fb88a7a858592f5e22deb
+  data.tar.gz: b7810de4b7c3030f9feff07e38c28bc6ba68daddb2d3d993c819737ee8d3423ac781cc097c1a47fc5ca3f218f93c69a13dd0cd257ea936f0d1b6335c20e98120

data/README.md

@@ -0,0 +1,138 @@
+# Sidekiq Job Monitor
+
+This gem allows you to easily monitor your jobs progression from your client.
+
+This is often useful when the user has to wait for a specific job to complete
+to access some produced data.
+
+The original use case was to allow users to see a "work in progress" modal
+while a big document was being generated, and then redirect them to download
+it when the job has completed.
+
+The gem plugs into Sidekiq's job processor as a middleware to track the
+job progress and make it available through an JSON endpoint.
+
+There's also a simple javascript client that allows you to hook into the
+complete and failed events.
+
+## Installation
+
+Add to your Gemfile and `bundle install`:
+
+```ruby
+gem 'sidekiq-job_monitor'
+```
+
+Mount the engine in your routes.rb :
+
+```ruby
+mount Sidekiq::JobMonitor::Engine => '/job-monitor', as: :job_monitor
+```
+
+## Usage
+
+The supported workflow for the gem is the following :
+
+1. The user requests a document that need time to be processed
+2. The server enqueues a sidekiq job in high priority queue and returns a waiting message in the form of a modal (for instance)
+3. The client polls the server to know when the job is done
+4. When the job is done, the server returns data to the client so that it can take some action to deliver the document
+
+### 1. Requesting the document
+
+Add a link to the job starting endpoint as a remote link :
+
+```erb
+<%= link_to 'Download report', build_report_path(@report), remote: true, data: { :'job-monitor-link' => true }
+```
+
+Initialize the javascript client and make it handle the main events :
+
+```javascript
+$(function() {
+  $('[data-job-monitor-link]').each(function(i, el) {
+    $(el).sidekiqJobMonitor({
+      onStart: function($el) {
+        // If you return a modal box from the server, initialize it
+        $el.appendTo('body').modal();
+        // Handle the "complete" event and redirect the user to a target
+        // URL where it will be able to download the document
+        $el.on('complete', function(e, monitor, data) {
+          window.location.href = data.url;
+        });
+        // You can also stop monitoring the progress, for instance when the
+        // modal is closed :
+        $el.on('hide', function() {
+          $el.trigger('stop');
+        });
+      }
+    });
+  });
+});
+```
+
+### 2. The server enqueues a sidekiq job in high priority queue and returns a waiting message
+
+Enqueue a job with a worker as usual, and store the Job ID in the controller
+
+```ruby
+class ReportsController
+  def build
+    @job_id = MyReportWorker.perform_async(params[:id])
+    render layout: false
+  end
+end
+```
+
+Render a modal and return the monitoring URL as the main returned node's
+`[data-monitor-url]` attribute, with the URL returned by `job_monitor.job_progress_path(job_id)` :
+
+```erb
+<div class="modal" data-monitor-url="<%= job_monitor.job_progress_path(@job_id) %>">
+  <!-- Snip -->
+  Please wait ...
+  <!-- Snip -->
+</div>
+```
+
+### 3. The client polls the server to know when the job is done
+
+This part is already covered by the javascript code we wrote in step 1.
+
+All you need is the correct plugin initialization and returning the
+`data-monitor-url` attribute on the main returned node.
+
+### 4. The client polls the server to know when the job is done
+
+When the job is done, a javascript `complete` event is triggered on the modal.
+We already handled that in step 1.
+
+All we need now is to provide the `url` field in the data object returned by
+the server upon job completion.
+
+To do so, we add the `#monitoring_data` method to our worker class.
+This method takes the exact same arguments as the `#perform` method, plus
+the current job state (pending, processing, complete or failed) as the last
+argument.
+
+```ruby
+class MyReportWorker
+  include Sidekiq::Worker
+
+  def perform(report_id)
+    # Your worker logic here as usual ...
+  end
+
+  def monitoring_data(report_id, state)
+    # Pseudo logic to get the desired URL
+    { url: Report.find(report_id).document_url } if state == 'complete'
+  end
+end
+```
+
+Those fields will be added to the data hash returned by the server as JSON
+and passed to the `complete` event callback as the last argument.
+
+## Licence
+
+This project rocks and uses MIT-LICENSE.

data/app/assets/javascripts/sidekiq-job_monitor.coffee

@@ -4,9 +4,10 @@ class Sidekiq.JobMonitor
   constructor: (markup, options = {}) ->
     @$el = $(markup)
     @monitorURL = @$el.data('monitor-url')
-    setTimeout(@monitorProgress, 1000)
-    $('body').trigger('start', [this])
+    @monitor()
     options.onStart?(@$el)
+    @$el.on('stop', @stopMonitoring)
+    $('body').trigger('start', [this])
 
   monitorProgress: =>
     $.getJSON(@monitorURL)
@@ -17,7 +18,10 @@ class Sidekiq.JobMonitor
     if data.state is 'complete'
       @jobComplete(data)
     else
-      setTimeout(@monitorProgress, 1000)
+      @monitor()
+
+  monitor: ->
+    @monitorTimer = setTimeout(@monitorProgress, 1000)
 
   jobComplete: (data) ->
     console.log "trigger completion : ", this, data
@@ -26,9 +30,8 @@ class Sidekiq.JobMonitor
   jobFailed: =>
     @$el.trigger('failed', [this])
 
-  trigger: (eventName, args...) ->
-    args = [this].concat(args)
-    @$el.trigger(eventName, args)
+  stopMonitoring: =>
+    clearTimeout(@monitorTimer) if @monitorTimer
 
 $.fn.sidekiqJobMonitor = (options = {}) ->
   @each (i, el) ->

data/lib/sidekiq/job_monitor/version.rb

@@ -1,5 +1,5 @@
 module Sidekiq
   module JobMonitor
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-job_monitor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - vala
@@ -46,6 +46,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - MIT-LICENSE
+- README.md
 - Rakefile
 - app/assets/javascripts/sidekiq-job_monitor.coffee
 - app/assets/javascripts/sidekiq_job_monitor/application.js