qless 0.9.2 → 0.9.3

data/Gemfile

@@ -6,3 +6,5 @@ gemspec
 group :development do
   gem 'debugger', :platform => :mri
 end
+
+gem 'thin' # needed by qless-web binary

data/README.md

@@ -20,7 +20,7 @@ put in. So if a worker is working on a job, and you move it, the worker's reques
 complete the job will be ignored.
 
 A job can be `canceled`, which means it disappears into the ether, and we'll never
-pay it any mind every again. A job can be `dropped`, which is when a worker fails
+pay it any mind ever again. A job can be `dropped`, which is when a worker fails
 to heartbeat or complete the job in a timely fashion, or a job can be `failed`,
 which is when a host recognizes some systematically problematic state about the
 job. A worker should only fail a job if the error is likely not a transient one;
@@ -189,17 +189,20 @@ Then run the `qless:work` rake task:
 rake qless:work
 ```
 
-The following signals are supported:
+The following signals are supported in the parent process:
 
 * TERM: Shutdown immediately, stop processing jobs.
 *  INT: Shutdown immediately, stop processing jobs.
 * QUIT: Shutdown after the current job has finished processing.
 * USR1: Kill the forked child immediately, continue processing jobs.
-* USR2: Don't process any new jobs
+* USR2: Don't process any new jobs, and dump the current backtrace.
 * CONT: Start processing jobs again after a USR2
 
 You should send these to the master process, not the child.
 
+The child process supports the `USR2` signal, whch causes it to
+dump its current backtrace.
+
 Workers also support middleware modules that can be used to inject
 logic before, after or around the processing of a single job in
 the child process. This can be useful, for example, when you need to
@@ -228,6 +231,42 @@ Qless::Worker.class_eval do
 end
 ```
 
+Per-Job Middlewares
+===================
+
+Qless also supports middleware on a per-job basis, when you have some
+orthogonal logic to run in the context of some (but not all) jobs.
+
+Per-job middlewares are defined the same as worker middlewares:
+
+``` ruby
+module ReEstablishDBConnection
+  def around_perform(job)
+    MyORM.establish_connection
+    super
+  end
+end
+```
+
+To add them to a job class, you first have to make your job class
+middleware-enabled by extending it with
+`Qless::Job::SupportsMiddleware`, then extend your middleware
+modules:
+
+``` ruby
+class MyJobClass
+  extend Qless::Job::SupportsMiddleware
+  extend ReEstablishDBConnection
+  extend MyOtherAwesomeMiddleware
+
+  def self.perform(job)
+  end
+end
+```
+
+Note that `Qless::Job::SupportsMiddleware` must be extended onto your
+job class _before_ any other middleware modules.
+
 Web Interface
 =============
 

data/Rakefile

@@ -11,7 +11,8 @@ RSpec::Core::RakeTask.new(:spec) do |t|
 end
 
 # TODO: bump this up as test coverage increases. It was 90.29 when I last updated it on 2012-05-21.
-min_coverage_threshold = 90.0
+# On travis where we skip JS tests, it's at 83.9 on 2013-01-15
+min_coverage_threshold = 83.5
 desc "Checks the spec coverage and fails if it is less than #{min_coverage_threshold}%"
 task :check_coverage do
   percent = File.read("./coverage/coverage_percent.txt").to_f
@@ -24,5 +25,28 @@ end
 
 task default: [:spec, :check_coverage]
 
-
 require 'qless/tasks'
+
+namespace :qless do
+  task :setup do
+    require 'qless'
+    queue = Qless::Client.new.queues["example"]
+    queue.client.redis.flushdb
+
+    ENV['QUEUES'] = queue.name
+    ENV['VVERBOSE'] = '1'
+
+    class ExampleJob
+      def self.perform(job)
+        sleep_time = job.data.fetch("sleep")
+        print "Sleeping for #{sleep_time}..."
+        sleep sleep_time
+        puts "done"
+      end
+    end
+
+    20.times do |i|
+      queue.put(ExampleJob, sleep: i)
+    end
+  end
+end

data/{bin → exe}/qless-web

@@ -9,8 +9,9 @@ rescue LoadError
 end
 
 require 'qless/server'
+client = Qless::Client.new
 
-Vegas::Runner.new(Qless::Server, 'qless-web', {
+Vegas::Runner.new(Qless::Server.new(client), 'qless-web', {
   :before_run => lambda {|v|
     path = (ENV['RESQUECONFIG'] || v.args.first)
     load path.to_s.strip if path
@@ -20,4 +21,4 @@ Vegas::Runner.new(Qless::Server, 'qless-web', {
   #   runner.logger.info "Using Redis connection '#{redis_conf}'"
   #   Resque.redis = redis_conf
   # }
-end
+end

data/lib/qless.rb

@@ -3,15 +3,28 @@ require "redis"
 require "json"
 require "securerandom"
 
+module Qless
+  # Define our error base class before requiring the other
+  # files so they can define subclasses.
+  Error = Class.new(StandardError)
+
+  # to maintain backwards compatibility with v2.x of that gem we need this constant because:
+  # * (lua.rb) the #evalsha method signature changed between v2.x and v3.x of the redis ruby gem
+  # * (worker.rb) in v3.x you have to reconnect to the redis server after forking the process
+  USING_LEGACY_REDIS_VERSION = ::Redis::VERSION.to_f < 3.0
+end
+
 require "qless/version"
 require "qless/config"
 require "qless/queue"
 require "qless/job"
-require "qless/lua"
+require "qless/lua_script"
 
 module Qless
   extend self
 
+  UnsupportedRedisVersionError = Class.new(Error)
+
   def generate_jid
     SecureRandom.uuid.gsub('-', '')
   end
@@ -27,27 +40,25 @@ module Qless
     @worker_name ||= [Socket.gethostname, Process.pid.to_s].join('-')
   end
 
-  class UnsupportedRedisVersionError < StandardError; end
-
   class ClientJobs
     def initialize(client)
       @client = client
     end
-    
+
     def complete(offset=0, count=25)
       @client._jobs.call([], ['complete', offset, count])
     end
-    
+
     def tracked
       results = JSON.parse(@client._track.call([], []))
       results['jobs'] = results['jobs'].map { |j| Job.new(@client, j) }
       results
     end
-    
+
     def tagged(tag, offset=0, count=25)
       JSON.parse(@client._tag.call([], ['get', tag, offset, count]))
     end
-    
+
     def failed(t=nil, start=0, limit=25)
       if not t
         JSON.parse(@client._failed.call([], []))
@@ -57,7 +68,7 @@ module Qless
         results
       end
     end
-    
+
     def [](id)
       results = @client._get.call([], [id])
       if results.nil?
@@ -70,41 +81,41 @@ module Qless
       Job.new(@client, JSON.parse(results))
     end
   end
-  
+
   class ClientWorkers
     def initialize(client)
       @client = client
     end
-    
+
     def counts
       JSON.parse(@client._workers.call([], [Time.now.to_i]))
     end
-    
+
     def [](name)
       JSON.parse(@client._workers.call([], [Time.now.to_i, name]))
     end
   end
-  
+
   class ClientQueues
     def initialize(client)
       @client = client
     end
-    
+
     def counts
       JSON.parse(@client._queues.call([], [Time.now.to_i]))
     end
-    
+
     def [](name)
       Queue.new(name, @client)
     end
   end
-  
+
   class ClientEvents
     def initialize(redis)
       @redis   = redis
       @actions = Hash.new()
     end
-    
+
     def canceled(&block) ; @actions[:canceled ] = block; end
     def completed(&block); @actions[:completed] = block; end
     def failed(&block)   ; @actions[:failed   ] = block; end
@@ -113,7 +124,7 @@ module Qless
     def put(&block)      ; @actions[:put      ] = block; end
     def track(&block)    ; @actions[:track    ] = block; end
     def untrack(&block)  ; @actions[:untrack  ] = block; end
-    
+
     def listen
       yield(self) if block_given?
       @redis.subscribe(:canceled, :completed, :failed, :popped, :stalled, :put, :track, :untrack) do |on|
@@ -125,19 +136,20 @@ module Qless
         end
       end
     end
-    
+
     def stop
       @redis.unsubscribe
     end
   end
-  
+
   class Client
     # Lua scripts
     attr_reader :_cancel, :_config, :_complete, :_fail, :_failed, :_get, :_heartbeat, :_jobs, :_peek, :_pop
     attr_reader :_priority, :_put, :_queues, :_recur, :_retry, :_stats, :_tag, :_track, :_workers, :_depends
+    attr_reader :_pause, :_unpause, :_deregister_workers
     # A real object
     attr_reader :config, :redis, :jobs, :queues, :workers
-    
+
     def initialize(options = {})
       # This is the redis instance we're connected to
       @redis   = options[:redis] || Redis.connect(options) # use connect so REDIS_URL will be honored
@@ -145,10 +157,11 @@ module Qless
       assert_minimum_redis_version("2.5.5")
       @config = Config.new(self)
       ['cancel', 'config', 'complete', 'depends', 'fail', 'failed', 'get', 'heartbeat', 'jobs', 'peek', 'pop',
-        'priority', 'put', 'queues', 'recur', 'retry', 'stats', 'tag', 'track', 'workers'].each do |f|
-        self.instance_variable_set("@_#{f}", Lua.new(f, @redis))
+        'priority', 'put', 'queues', 'recur', 'retry', 'stats', 'tag', 'track', 'workers', 'pause', 'unpause',
+        'deregister_workers'].each do |f|
+        self.instance_variable_set("@_#{f}", Qless::LuaScript.new(f, @redis))
       end
-      
+
       @jobs    = ClientJobs.new(self)
       @queues  = ClientQueues.new(self)
       @workers = ClientWorkers.new(self)
@@ -157,29 +170,43 @@ module Qless
     def inspect
       "<Qless::Client #{@options} >"
     end
-    
+
     def events
       # Events needs its own redis instance of the same configuration, because
       # once it's subscribed, we can only use pub-sub-like commands. This way,
       # we still have access to the client in the normal case
       @events ||= ClientEvents.new(Redis.connect(@options))
     end
-    
+
     def track(jid)
       @_track.call([], ['track', jid, Time.now.to_i])
     end
-    
+
     def untrack(jid)
       @_track.call([], ['untrack', jid, Time.now.to_i])
     end
-    
+
     def tags(offset=0, count=100)
       JSON.parse(@_tag.call([], ['top', offset, count]))
     end
+
+    def deregister_workers(*worker_names)
+      _deregister_workers.call([], worker_names)
+    end
+
+    def bulk_cancel(jids)
+      @_cancel.call([], jids)
+    end
+
+    def new_redis_connection
+      ::Redis.new(url: redis.id)
+    end
+
   private
 
     def assert_minimum_redis_version(version)
-      redis_version = @redis.info.fetch("redis_version")
+      # remove the "-pre2" from "2.6.8-pre2"
+      redis_version = @redis.info.fetch("redis_version").split('-').first
       return if Gem::Version.new(redis_version) >= Gem::Version.new(version)
 
       raise UnsupportedRedisVersionError,

data/lib/qless/config.rb

@@ -1,5 +1,3 @@
-require "qless/lua"
-require "redis"
 require "json"
 
 module Qless
@@ -28,4 +26,4 @@ module Qless
       @client._config.call([], ['unset', option])
     end
   end
-end
+end

data/lib/qless/job.rb

@@ -1,18 +1,19 @@
 require "qless"
 require "qless/queue"
-require "qless/lua"
 require "redis"
 require "json"
 
 module Qless
   class BaseJob
+    attr_reader :client
+
     def initialize(client, jid)
       @client = client
       @jid    = jid
     end
 
     def klass
-      @klass ||= @klass_name.split('::').inject(Kernel) { |context, name| context.const_get(name) }
+      @klass ||= @klass_name.split('::').inject(Object) { |context, name| context.const_get(name) }
     end
 
     def queue
@@ -21,12 +22,30 @@ module Qless
   end
 
   class Job < BaseJob
-    attr_reader :jid, :expires_at, :state, :queue_name, :history, :worker_name, :failure, :klass_name, :tracked, :dependencies, :dependents
-    attr_reader :original_retries, :retries_left
+    attr_reader :jid, :expires_at, :state, :queue_name, :worker_name, :failure, :klass_name, :tracked, :dependencies, :dependents
+    attr_reader :original_retries, :retries_left, :raw_queue_history
     attr_accessor :data, :priority, :tags
 
+    MiddlewareMisconfiguredError = Class.new(StandardError)
+
+    module SupportsMiddleware
+      def around_perform(job)
+        perform(job)
+      end
+    end
+
     def perform
-      klass.perform(self)
+      middlewares = Job.middlewares_on(klass)
+
+      if middlewares.last == SupportsMiddleware
+        klass.around_perform(self)
+      elsif middlewares.any?
+        raise MiddlewareMisconfiguredError, "The middleware chain for #{klass} " +
+          "(#{middlewares.inspect}) is misconfigured. Qless::Job::SupportsMiddleware " +
+          "must be extended onto your job class first if you want to use any middleware."
+      else
+        klass.perform(self)
+      end
     end
 
     def self.build(client, klass, attributes = {})
@@ -49,29 +68,38 @@ module Qless
         "dependents"       => []
       }
       attributes = defaults.merge(Qless.stringify_hash_keys(attributes))
-      attributes["data"] = JSON.load(JSON.dump attributes["data"])
+      attributes["data"] = JSON.parse(JSON.dump attributes["data"])
       new(client, attributes)
     end
 
+    def self.middlewares_on(job_klass)
+      job_klass.singleton_class.ancestors.select do |ancestor|
+        ancestor.method_defined?(:around_perform)
+      end
+    end
+
     def initialize(client, atts)
       super(client, atts.fetch('jid'))
       %w{jid data priority tags state tracked
-        failure history dependencies dependents}.each do |att|
+        failure dependencies dependents}.each do |att|
         self.instance_variable_set("@#{att}".to_sym, atts.fetch(att))
       end
 
-      @expires_at       = atts.fetch('expires')
-      @klass_name       = atts.fetch('klass')
-      @queue_name       = atts.fetch('queue')
-      @worker_name      = atts.fetch('worker')
-      @original_retries = atts.fetch('retries')
-      @retries_left     = atts.fetch('remaining')
+      @expires_at        = atts.fetch('expires')
+      @klass_name        = atts.fetch('klass')
+      @queue_name        = atts.fetch('queue')
+      @worker_name       = atts.fetch('worker')
+      @original_retries  = atts.fetch('retries')
+      @retries_left      = atts.fetch('remaining')
+      @raw_queue_history = atts.fetch('history')
 
       # This is a silly side-effect of Lua doing JSON parsing
       @tags         = [] if @tags == {}
       @dependents   = [] if @dependents == {}
       @dependencies = [] if @dependencies == {}
       @state_changed = false
+      @before_callbacks = Hash.new { |h, k| h[k] = [] }
+      @after_callbacks  = Hash.new { |h, k| h[k] = [] }
     end
 
     def priority=(priority)
@@ -93,7 +121,7 @@ module Qless
     end
 
     def description
-      "#{@jid} (#{@klass_name} / #{@queue_name})"
+      "#{@klass_name} (#{@jid} / #{@queue_name} / #{@state})"
     end
 
     def inspect
@@ -104,9 +132,57 @@ module Qless
       @expires_at - Time.now.to_f
     end
 
+    def reconnect_to_redis
+      @client.redis.client.reconnect
+    end
+
+    def history
+      warn "WARNING: Qless::Job#history is deprecated; use Qless::Job#raw_queue_history instead" +
+           "; called from:\n#{caller.first}\n"
+      raw_queue_history
+    end
+
+    def queue_history
+      @queue_history ||= @raw_queue_history.map do |history_event|
+        history_event.each_with_object({}) do |(key, value), hash|
+          # The only Numeric (Integer or Float) values we get in the history are timestamps
+          hash[key] = if value.is_a?(Numeric)
+            Time.at(value).utc
+          else
+            value
+          end
+        end
+      end
+    end
+
+    def initially_put_at
+      @initially_put_at ||= history_timestamp('put', :min)
+    end
+
+    def to_hash
+      {
+        jid: jid,
+        expires_at: expires_at,
+        state: state,
+        queue_name: queue_name,
+        history: raw_queue_history,
+        worker_name: worker_name,
+        failure: failure,
+        klass_name: klass_name,
+        tracked: tracked,
+        dependencies: dependencies,
+        dependents: dependents,
+        original_retries: original_retries,
+        retries_left: retries_left,
+        data: data,
+        priority: priority,
+        tags: tags
+      }
+    end
+
     # Move this from it's current queue into another
     def move(queue)
-      note_state_change do
+      note_state_change :move do
         @client._put.call([queue], [
           @jid, @klass_name, JSON.generate(@data), Time.now.to_f, 0
         ])
@@ -115,7 +191,7 @@ module Qless
 
     # Fail a job
     def fail(group, message)
-      note_state_change do
+      note_state_change :fail do
         @client._fail.call([], [
           @jid,
           @worker_name,
@@ -134,13 +210,15 @@ module Qless
         JSON.generate(@data)]) || false
     end
 
+    CantCompleteError = Class.new(Qless::Error)
+
     # Complete a job
     # Options include
     # => next (String) the next queue
     # => delay (int) how long to delay it in the next queue
     def complete(nxt=nil, options={})
-      response = note_state_change do
-        if nxt.nil?
+      note_state_change :complete do
+        response = if nxt.nil?
           @client._complete.call([], [
             @jid, @worker_name, @queue_name, Time.now.to_f, JSON.generate(@data)])
         else
@@ -148,8 +226,19 @@ module Qless
             @jid, @worker_name, @queue_name, Time.now.to_f, JSON.generate(@data), 'next', nxt, 'delay',
             options.fetch(:delay, 0), 'depends', JSON.generate(options.fetch(:depends, []))])
         end
+
+        if response
+          response
+        else
+          description = if reloaded_instance = @client.jobs[@jid]
+                          reloaded_instance.description
+                        else
+                          self.description + " -- can't be reloaded"
+                        end
+
+          raise CantCompleteError, "Failed to complete #{description}"
+        end
       end
-      response.nil? ? false : response
     end
 
     def state_changed?
@@ -157,7 +246,7 @@ module Qless
     end
 
     def cancel
-      note_state_change do
+      note_state_change :cancel do
         @client._cancel.call([], [@jid])
       end
     end
@@ -179,7 +268,7 @@ module Qless
     end
 
     def retry(delay=0)
-      note_state_change do
+      note_state_change :retry do
         results = @client._retry.call([], [@jid, @queue_name, @worker_name, Time.now.to_f, delay])
         results.nil? ? false : results
       end
@@ -193,13 +282,29 @@ module Qless
       !!@client._depends.call([], [@jid, 'off'] + jids)
     end
 
+    [:fail, :complete, :cancel, :move, :retry].each do |event|
+      define_method :"before_#{event}" do |&block|
+        @before_callbacks[event] << block
+      end
+
+      define_method :"after_#{event}" do |&block|
+        @after_callbacks[event].unshift block
+      end
+    end
+
   private
 
-    def note_state_change
+    def note_state_change(event)
+      @before_callbacks[event].each { |blk| blk.call(self) }
       result = yield
       @state_changed = true
+      @after_callbacks[event].each { |blk| blk.call(self) }
       result
     end
+
+    def history_timestamp(name, selector)
+      queue_history.map { |q| q[name] }.compact.send(selector)
+    end
   end
 
   class RecurringJob < BaseJob