background_worker 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d96a3cbffa01ee490b1a2542a80b8fdf9593aacc
+  data.tar.gz: 609ef34234495ba8fa0f17da87ead826a2c134b5
+SHA512:
+  metadata.gz: 2ae408b3eeb8261323d747d279c518a9a8e07906b86eb9b5c74d4d7b9830e58ef16dd146b480d4407e1a7fe7054d894c5ac7f8f65a29a48d5f063cd00ae61b8c
+  data.tar.gz: dd3a09b5ebe64ec8bffd43d8381b1024c1cc3344f74e24ba0cc423b7b0ad12cd37032e666ad50a4679eaed113f4f471d6104ee4fab1b2a834dd4fc67f1430820

data/.rubocop.yml

@@ -0,0 +1,11 @@
+Metrics/LineLength:
+  Max: 100
+
+Documentation:
+  Enabled: false
+
+Style/BlockDelimiters:
+  EnforcedStyle: semantic
+
+Style/TrivialAccessors:
+  AllowPredicates: true

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 The Sealink Travel Group
+
+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,64 @@
+Background Worker
+=================
+
+Provides a worker abstraction with an additional status channel.
+
+Start by making a worker class which extends from BackgroundWorker::Base
+
+    class MyWorker < BackgroundWorker::Base
+      def my_task(options={})
+        report_progress('Starting')
+        if options[:message].blank?
+          report_failed("No message provided")
+          return
+        end
+
+        puts options[:message]
+        {original_message: message}
+      end
+    end
+
+Then, when you want to perform a task in the background, use
+klass#perform_in_background which exists in Base:
+
+   worker_id = MyWorker.perform_in_background(:my_task, message: "hello!")
+
+# Backgrounded
+
+By default this will call your instance method in the foreground -- you have to
+provide an #enqueue_with configuration like so:
+
+    BackgroundWorker.configure(
+      enqueue_with: -> klass, method_name, options {
+        Resque.enqueue(klass, method_name, options)
+      }
+    )
+
+This is independent of the status reporting which (currently) always uses Redis.
+
+# Getting the status
+
+The worker_id you are returned can be used to get the status, and
+whether the worker has finished successfully, failed, or in progress:
+
+    state = BackgroundWorker.get_state_of(worker_id)
+
+The state is represented by a hash with the following keys:
+
+    message: Reported message
+    detailed_message: Detailed version of above when provided
+    status: :successful, :failed, or null if still processing
+    completed: True if report_failed, report_successful called (or worker
+               finished without exception -- which calls report_successful)
+    data: Arbitrary data returned by worker method on success or report_failed
+
+If an exception is raised, the worker will call #report_failed with the
+details. You can provide a callback with #after_exception in the config
+
+# INSTALLATION
+
+gem install background_worker
+
+or add to your Gemfile:
+gem 'background_worker'
+

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/background_worker.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'background_worker/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'background_worker'
+  spec.version       = BackgroundWorker::VERSION
+  spec.authors       = ['Michael Noack', 'Adam Davies', 'Alessandro Berardi']
+  spec.email         = ['development@travellink.com.au',
+                        'adzdavies@gmail.com',
+                        'berardialessandro@gmail.com']
+  spec.summary       = 'Background worker abstraction with status updates'
+  spec.description   = 'See README for full details'
+  spec.homepage      = 'http://github.com/sealink/background_worker'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rubocop'
+end

data/lib/background_worker/base.rb

@@ -0,0 +1,86 @@
+module BackgroundWorker
+  class Base
+    attr_accessor :uid, :state
+
+    def initialize(options = {})
+      Time.zone = Setting.time_zone
+
+      @uid = options['uid']
+
+      # Store state persistently, to enable status checkups & progress reporting
+      @state = BackgroundWorker::PersistentState.new(@uid, options.except('uid'))
+      log("Created #{self.class}")
+      log("Options are: #{options.pretty_inspect}")
+    end
+
+    # Report progress...
+    def report_progress(message)
+      state.message = message
+      state.save
+    end
+
+    # Report a minor progress -- may get called a lot, so don't save it so often
+    def report_minor_progress(message)
+      state.message = message
+
+      # Only report minor events once per second
+      @last_report ||= Time.now - 2
+      time_elapsed =  Time.now - @last_report
+      return unless time_elapsed > 1
+
+      @last_report = Time.now
+      state.save
+    end
+
+    def report_successful(message = 'Finished successfully')
+      state.set_completed(message, :successful)
+    end
+
+    def report_failed(message = 'Failed', detailed_message = nil)
+      state.detailed_message = detailed_message
+      state.set_completed(message, :failed)
+    end
+
+    def logger
+      BackgroundWorker.logger
+    end
+
+    def log(message, options = {})
+      severity = options.fetch(:severity, :info)
+      logger.send(severity, "uid=#{uid} #{message}")
+    end
+
+    class << self
+      def get_state_of(worker_id)
+        BackgroundWorker::PersistentState.get_state_of(worker_id)
+      end
+
+      # Public method to do in background...
+      def perform_in_background(method_name, options = {})
+        method_name = method_name.to_sym
+        options[:uid] ||= BackgroundWorker::Uid.new(to_s, method_name).generate
+
+        # Store into shared-cache before kicking job off
+        BackgroundWorker::PersistentState.new(options[:uid], options.except(:uid))
+
+        # Enqueue to the background queue
+        BackgroundWorker.enqueue(self, method_name, options)
+
+        options[:uid]
+      end
+
+      # This method is called by the job runner
+      #
+      # It will just call your preferred method in the worker.
+      def perform(method_name, options = {})
+        BackgroundWorker.verify_active_connections!
+
+
+        worker = new(options)
+        execution = WorkerExecution.new(worker, method_name, options)
+        execution.call
+
+      end
+    end
+  end
+end

data/lib/background_worker/config.rb

@@ -0,0 +1,40 @@
+require 'logger'
+
+module BackgroundWorker
+  class Config
+
+     attr_reader :logger
+
+    # Configuration includes following options:
+    #   logger: what logger to user throughout
+    #   enqueue_with: callback to execute the process
+    #   after_exception: callback to handle exceptions (for example, error reporting service)
+    #
+    # eg:
+    # Config.new(
+    #   logger: Rails.logger,
+    #   enqueue_with: -> klass, method_name, opts { Resque.enqueue(klass, method_name, opts) },
+    #   after_exception: -> e { Airbrake.notify(e) }
+    # )
+    def initialize(attrs)
+      @logger = attrs.fetch(:logger, ::Logger.new(STDOUT))
+      @enqueue_with = attrs.fetch(:enqueue_with, method(:foreground_enqueue))
+      @after_exception = attrs.fetch(:after_exception, method(:default_after_exception))
+    end
+
+    # Callback fired when an exception occurs
+    def after_exception(e)
+      @after_exception.call(e)
+    end
+
+    def foreground_enqueue(klass, method_name, opts)
+      klass.perform(method_name, opts)
+    end
+
+    def default_after_exception(e)
+      logger.error '** No after_exception handler installed **'
+      logger.error "Exception: #{e}"
+      logger.error "#{e.backtrace.join("\n")}"
+    end
+  end
+end

data/lib/background_worker/persistent_state.rb

@@ -0,0 +1,53 @@
+# Progress reporter is used by background processes, to communicate with
+# standard rails controllers.
+#
+# It works by storing a hash of all progress-report data in a redis value
+# keyed by the worker_uid.
+module BackgroundWorker
+  class PersistentState
+    attr_accessor :message, :detailed_message, :status, :completed, :data
+
+    def initialize(worker_uid, data)
+      @message = 'Waiting for task to queue...'
+      @status = :processing
+      @completed = false
+
+      @worker_uid = worker_uid
+      @data = data
+      save
+    end
+
+    def set_completed(message, status)
+      self.status = status
+      self.message = message
+
+      self.completed = true
+      save
+    end
+
+    # Save persistently (well for an hour at least)
+    def save
+      Rails.cache.write(@worker_uid, generate_persistent_hash, expires_in: 1.hour)
+    end
+
+    # Get a report out the queue
+    # (was .get_report, then .progress)
+    def self.get_state_of(worker_uid)
+      Rails.cache.read(worker_uid)
+    end
+
+    private
+
+    # Generate a hash of this objects state
+    #  (representing this status progress report)
+    def generate_persistent_hash
+      {
+        message: message,
+        detailed_message: detailed_message,
+        status: status,
+        completed: completed,
+        data: data
+      }
+    end
+  end
+end

data/lib/background_worker/uid.rb

@@ -0,0 +1,25 @@
+# Generates a unique identifier for a particular job identified by class_name/method
+module BackgroundWorker
+  class Uid
+    attr_reader :class_name, :method
+
+    def initialize(class_name, method)
+      @class_name = class_name
+      @method = method
+    end
+
+    def generate
+      "#{generate_uid_name}:#{generate_uid_hash}"
+    end
+
+    private
+
+    def generate_uid_hash
+      ::Digest::MD5.hexdigest("#{class_name}:#{method}:#{rand(1 << 64)}:#{Time.now}")
+    end
+
+    def generate_uid_name
+      "#{class_name.underscore}/#{method}".split('/').join(':')
+    end
+  end
+end

data/lib/background_worker/version.rb

@@ -0,0 +1,3 @@
+module BackgroundWorker
+  VERSION = '0.0.3'
+end

data/lib/background_worker/worker_execution.rb

@@ -0,0 +1,44 @@
+module BackgroundWorker
+  class WorkerExecution
+    attr_reader :worker, :method_name, :options
+
+    def initialize(worker, method_name, options)
+      fail ArgumentError, "'uid' is required to identify worker" unless options['uid'].present?
+      @worker = worker
+      @method_name = method_name
+      @options = options
+    end
+
+    def call
+      worker.send(method_name, options)
+      report_implicitly_successful unless completed?
+
+    rescue StandardError => e
+      log_worker_error(e)
+      BackgroundWorker.after_exception.call(e)
+
+    ensure
+      log_worker_finality
+    end
+
+    private
+
+    def completed?
+      worker.state.completed
+    end
+
+    def report_implicitly_successful
+      worker.report_successful
+    end
+
+    def log_worker_error(e)
+      worker.log("Implicit failure: Exception: #{e}", severity: :error)
+      worker.report_failed("An unhandled error occurred: #{e}") unless completed?
+    end
+
+    def log_worker_finality
+      worker.log "Final state: #{worker.state.data}"
+      worker.log "Job was #{worker.state.status}"
+    end
+  end
+end

data/lib/background_worker.rb

@@ -0,0 +1,42 @@
+require 'background_worker/version'
+require 'background_worker/config'
+require 'background_worker/uid'
+require 'background_worker/base'
+require 'background_worker/persistent_state'
+
+module BackgroundWorker
+  # Configure worker
+  #
+  # eg:
+  # BackgroundWorker.configure(
+  #   logger: Rails.logger,
+  #   enqueue_with: -> klass, method_name, opts { Resque.enqueue(klass, method_name, opts) },
+  #   after_exception: -> e { Airbrake.notify(e) }
+  # )
+  def self.configure(options)
+    @config = Config.new(options)
+  end
+
+  def self.enqueue(klass, method_name, options)
+    config.enqueue_with.call(klass, method_name, options)
+  end
+
+  def self.logger
+    config.logger
+  end
+
+  def self.verify_active_connections!
+    Rails.cache.reconnect if defined?(Rails)
+    ActiveRecord::Base.verify_active_connections! if defined?(ActiveRecord)
+  end
+
+  def self.after_exception(e)
+    config.after_exception(e)
+  end
+
+  def self.config
+    raise "Not configured!" unless @config
+    @config
+  end
+
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: background_worker
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Michael Noack
+- Adam Davies
+- Alessandro Berardi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: See README for full details
+email:
+- development@travellink.com.au
+- adzdavies@gmail.com
+- berardialessandro@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- background_worker.gemspec
+- lib/background_worker.rb
+- lib/background_worker/base.rb
+- lib/background_worker/config.rb
+- lib/background_worker/persistent_state.rb
+- lib/background_worker/uid.rb
+- lib/background_worker/version.rb
+- lib/background_worker/worker_execution.rb
+homepage: http://github.com/sealink/background_worker
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Background worker abstraction with status updates
+test_files: []