stateful_jobs 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+tmp
+
+*.sqlite3
+*.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stateful_jobs.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Kjell Schlitt
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+# StatefulJobs
+
+StatefulJobs is a Resque based library which allows you to integrate responsive background jobs in a very easy way.
+StatefulJobs wraps an ActiveRecord Model around a set of jobs and adds a polling mechanism to your frontend to get your users noticed about the state of their tasks.
+
+Very useful for:
+* background jobs which provide its state to the frontend
+* background jobs which need user interaction between several steps
+* a set of jobs which share process information
+
+All these jobs can either be implemented as a separate Class or inline with just a handy Proc.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```
+$ gem 'stateful_jobs'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install stateful_jobs
+```
+
+Add the provided jQuery Plugin to your application.js:
+```
+//= require stateful_jobs
+```
+
+Or place it manually wherever your application can load it.
+
+
+## Usage
+
+### Model
+
+```
+$ rails g model import current_job:string current_state:string some:string other:string attributes:integer
+```
+
+Define your Jobs:
+
+```ruby
+class Import < ActiveRecord::Base
+  include StatefulJobs::Model
+
+  # as a proc:
+  stateful_job :extract do |model|
+    puts "processing #{model}..."
+    # do some expensive work here...
+
+    true | false
+  end
+
+  # or as a separate class:
+  stateful_job :execute, ImportExecutionJob
+end
+
+class ImportExecutionJob < StatefulJobs::Job::Base
+  def perform
+    puts "processing #{@model}..."
+    # do some expensive work here...
+
+    true | false
+  end
+end
+```
+
+Your Model now has been equiped with following methods: `extract!`, `execute!` which automatically enqueue your job on resque.
+While a job is processed its state is set to `running`. Finished job's states are set depending on their return value. A sucessfully performed job's (returns true) state becomes `done`. If a Job returns false, its state is set to `failed`. Errors raising an Exception result into an `error` state.
+
+
+### Controller
+
+```ruby
+class ImportsController < ActiveRecord::Base
+  include StatefulJobs::Controller
+
+  stateful_jobs :import
+end
+```
+
+This adds a `state` member action to your controller returning the current job/state of your Model as JSON.
+Additionally each state gets his own action which is called for every state change of your job. It gets the current state passed as a `current_state` parameter.
+
+Your can sum up all these state actions into one centralized callback action if you want:
+
+```ruby
+class ImportsController < ActiveRecord::Base
+  include StatefulJobs::Controller
+
+  stateful_jobs :import, action: :state_changed
+end
+```
+
+`state_changed` now gets called with current_job and current_state as parameters on every state change.
+
+
+### Routes
+
+```ruby
+RailsApp::Application.routes.draw do
+  stateful_jobs :imports
+end
+```
+
+For a complete set of restful routes just use `stateful_jobs_resources :imports`.
+
+### View
+
+```erb
+<%= stateful_job :imports, @import, :div, class: 'spinner', interval: 3000 do %>
+  spinner
+<% end %>
+```
+
+Adds the followng to your html:
+
+```html
+<div class="spinner" id="import_1" data-id="1" data-current-job="current-job" data-current-state="current-state">
+  spinner
+</div>
+<script type="test/javascript">
+  $('#import_1').statefulJobs({'interval': 3000})
+</script>
+```
+
+The plugin now asks the server for a new state every 3 seconds. On state change the according state's action is invoked via ajax. If you want to be redirected instead of an ajax call, ajax can be disabled with `ajax: false` flag.
+While a job is running, the css class `running` is applied to your spinner's div.
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/app/assets/javascripts/stateful_jobs.js.coffee

@@ -0,0 +1,65 @@
+$.fn.extend
+  statefulJobs: (url, options = {}) ->
+    settings =
+      interval: 5000
+      final: 'done'
+      ajax: true
+      callback: null
+      action: null
+
+    settings = $.extend settings, options
+
+    return @each () ->
+      new StatefulJobs url, settings, $(this)
+
+class @StatefulJobs
+
+  @spinners = {}
+
+  constructor: (@url, @options, @element) ->
+    @currentJob   = @element.data('current-job')
+    @currentState = @element.data('current-state')
+    @element.removeData('current-job')
+    @element.removeData('current-state')
+    @options = $.extend @element.data(), @options
+
+    @timer = null
+
+    StatefulJobs.spinners[@options.id] = @
+
+    @start() unless @current == @options.final
+
+  getState: () =>
+    $.getJSON("#{@url}/#{@options.id}/state", @gotState)
+
+  gotState: (s) =>
+    if @currentJob != s.current_job or @currentState != s.current_state
+      @currentJob = s.current_job
+      @currentState = s.current_state
+      @element.removeClass('active')
+
+      if @options.callback
+        @options.callback(@)
+      else
+        if @options.action
+          url = "#{@url}/#{@options.id}/#{@options.action}?current_job=#{@currentJob}&current_state=#{@currentState}"
+        else
+          url = "#{@url}/#{@options.id}/#{@currentJob}?current_state=#{@currentState}"
+
+        if @options.ajax
+          $.getScript url
+        else
+          location.href = url
+    else
+      setTimeout @getState, @options.interval
+
+  start: ->
+    @element.addClass('active')
+    @timer = setTimeout @getState, @options.interval
+
+  stop: ->
+    @element.removeClass('active')
+    clearTimeout @timer
+
+  @get: (id) ->
+    StatefulJobs.spinners[id]

data/lib/stateful_jobs.rb

@@ -0,0 +1,14 @@
+require 'resque'
+
+require 'stateful_jobs/version'
+
+require 'stateful_jobs/engine'  if defined?(Rails)
+
+require 'stateful_jobs/controller'
+require 'stateful_jobs/model'
+require 'stateful_jobs/job'
+require 'stateful_jobs/job/base'
+require 'stateful_jobs/job/dispatcher'
+
+module StatefulJobs
+end

data/lib/stateful_jobs/controller.rb

@@ -0,0 +1,41 @@
+module StatefulJobs
+
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        attr_accessor :stateful_jobs_class, :stateful_jobs_options
+      end
+    end
+
+    module ClassMethods
+      def stateful_jobs klass, options = {}
+        self.stateful_jobs_class = klass.to_s.camelcase.constantize
+        self.stateful_jobs_options = options
+
+        if options[:action]
+          define_method options[:action] do
+          end
+        else
+          if self.stateful_jobs_class.stateful_jobs.is_a? Hash
+            self.stateful_jobs_class.stateful_jobs.keys.each do |job|
+              define_method job do
+              end
+            end
+          end
+        end
+      end
+    end
+
+    def state
+      render json: stateful_jobs_class.where(id: params[:id]).limit(1).select('current_job, current_state').first.to_json
+    end
+
+    def stateful_jobs_class
+      self.class.stateful_jobs_class
+    end
+
+  end
+
+end

data/lib/stateful_jobs/engine.rb

@@ -0,0 +1,11 @@
+require 'stateful_jobs/view_helpers'
+require 'stateful_jobs/routing.rb'
+
+module StatefulJobs
+  class Engine < Rails::Engine
+    initializer "stateful_jobs.view_helpers" do
+      ActionView::Base.send :include, ViewHelpers
+      ActionDispatch::Routing::Mapper.send :include, Routing::Mapper
+    end
+  end
+end

data/lib/stateful_jobs/job.rb

@@ -0,0 +1,9 @@
+module StatefulJobs
+  module Job
+
+    def self.enqueue model, job
+      Resque.enqueue Dispatcher, model.class.to_s, model.id, job
+    end
+
+  end
+end

data/lib/stateful_jobs/job/base.rb

@@ -0,0 +1,22 @@
+module StatefulJobs
+  module Job
+
+    class Base
+
+      attr_reader :model
+
+      def initialize m
+        @model = m
+      end
+
+      def self.perform m
+        self.new(m).perform
+      end
+
+      def perform
+      end
+
+    end
+
+  end
+end

data/lib/stateful_jobs/job/dispatcher.rb

@@ -0,0 +1,31 @@
+module StatefulJobs
+  module Job
+
+    class Dispatcher
+      @queue = :stateful_jobs
+
+      def self.perform model, id, job_name
+        begin
+          model_class = const_get(model)
+          model = model_class.find id
+
+          job = model_class.stateful_job_for(job_name)
+
+          model.current_job = job_name
+          model.current_state = 'running'
+          model.save validate: false
+
+          if job.is_a?(Class)? job.perform(model) : job.call(model)
+            model_class.where(id: id).update_all current_state: 'done', updated_at: Time.now
+          else
+            model_class.where(id: id).update_all current_state: 'failed', updated_at: Time.now
+          end
+        rescue Exception => e
+          model_class.where(id: id).update_all current_state: 'error', updated_at: Time.now
+          raise e
+        end
+      end
+    end
+
+  end
+end

data/lib/stateful_jobs/model.rb

@@ -0,0 +1,36 @@
+module StatefulJobs
+
+  module Model
+
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        attr_accessor :stateful_jobs
+      end
+    end
+
+    def stateful_jobs
+      self.class.stateful_jobs.keys
+    end
+
+    module ClassMethods
+      def stateful_job name, klass = nil, &block
+        @stateful_jobs ||= {}
+        name = name.to_sym
+
+        @stateful_jobs[name] = (block_given?)? block : klass
+
+        define_method "#{name}!" do
+          StatefulJobs::Job.enqueue self, name
+        end
+      end
+
+      def stateful_job_for j
+        @stateful_jobs[j.to_sym]
+      end
+    end
+
+  end
+
+end

data/lib/stateful_jobs/routing.rb

@@ -0,0 +1,59 @@
+module StatefulJobs
+  module Routing
+    module Mapper
+
+      def stateful_jobs_resource *resources, &block
+        options = resources.extract_options!.dup
+
+        path_name = resources.first
+
+        if options[:controller]
+          controller = "#{options[:controller].camelcase}Controller".constantize
+        else
+          controller = "#{resources.first.to_s.pluralize.camelcase}Controller".constantize
+        end
+
+        create_stateful_jobs_routes path_name, controller
+
+        resources(*resources, &block)
+      end
+
+      def stateful_jobs_resources *resources, &block
+        options = resources.extract_options!.dup
+
+        path_name = resources.first
+
+        if options[:controller]
+          controller = "#{options[:controller].camelcase}Controller".constantize
+        else
+          controller = "#{resources.first.to_s.camelcase}Controller".constantize
+        end
+
+        create_stateful_jobs_routes path_name, controller
+
+        resources(*resources, &block)
+      end
+
+      def stateful_jobs controller
+        path_name = controller
+        controller = "#{controller.to_s.camelcase}Controller".constantize
+        create_stateful_jobs_routes path_name, controller
+      end
+
+    private
+
+      def create_stateful_jobs_routes path_name, controller
+        get "#{path_name}/:id/state", to: "#{path_name}#state", as: "#{path_name}_state".to_sym
+
+        if controller.stateful_jobs_options[:action]
+          get "#{path_name}/:id/#{controller.stateful_jobs_options[:action]}", to: "#{path_name}##{controller.stateful_jobs_options[:action]}", as: "#{path_name}_#{stateful_jobs_options[:action]}".to_sym
+        else
+          controller.stateful_jobs_class.stateful_jobs.keys.each do |job|
+            get "#{path_name}/:id/#{job}", to: "#{path_name}##{job}", as: "#{path_name}_#{job}".to_sym
+          end
+        end
+      end
+
+    end
+  end
+end