resque 1.7.0 → 1.7.1

data/HISTORY.md

@@ -1,6 +1,11 @@
+## 1.7.1 (2010-04-02)
+
+* Bugfix: Make job hook execution order consistent
+* Bugfix: stdout buffering in child process
+
 ## 1.7.0 (2010-03-31)
 
-* Job hooks API. See HOOKS.md.
+* Job hooks API. See docs/HOOKS.md.
 * web: Hovering over dates shows a timestamp
 * web: AJAXify retry action for failed jobs
 * web bugfix: Fix pagination bug

data/README.markdown

@@ -662,7 +662,7 @@ For a list of available plugins see
 
 If you'd like to write your own plugin, or want to customize Resque
 using hooks (such as `Resque.after_fork`), see
-[HOOKS.md](http://github.com/defunkt/resque/blob/master/HOOKS.md).
+[docs/HOOKS.md](http://github.com/defunkt/resque/blob/master/HOOKS.md).
 
 
 Namespaces
@@ -762,7 +762,7 @@ Mailing List
 
 To join the list simply send an email to <resque@librelist.com>. This
 will subscribe you and send you information about your subscription,
-include unsubscribe information.
+including unsubscribe information.
 
 The archive can be found at <http://librelist.com/browser/>.
 

data/Rakefile

@@ -1,29 +1,44 @@
+#
+# Setup
+#
+
 load 'tasks/redis.rake'
+require 'rake/testtask'
 
 $LOAD_PATH.unshift 'lib'
 require 'resque/tasks'
 
+def command?(command)
+  system("type #{command} > /dev/null")
+end
+
+
+#
+# Tests
+#
+
 task :default => :test
 
-desc "Run tests"
+desc "Run the test suite"
 task :test do
-  begin
-    require 'redgreen'
-  rescue LoadError
+  rg = command?(:rg)
+  Dir['test/**/*_test.rb'].each do |f|
+    rg ? sh("rg #{f}") : ruby(f)
   end
+end
 
-  # Don't use the rake/testtask because it loads a new
-  # Ruby interpreter - we want to run tests with the current
-  # `rake` so our library manager still works
-  Dir['test/*_test.rb'].each do |f|
-    require f
+if command? :kicker
+  desc "Launch Kicker (like autotest)"
+  task :kicker do
+    puts "Kicking... (ctrl+c to cancel)"
+    exec "kicker -e rake test lib examples"
   end
 end
 
-desc "Activate kicker - gem install kicker"
-task :kick do
-  exec "kicker -e rake lib test"
-end
+
+#
+# Gem
+#
 
 task :install => [ 'redis:install', 'dtach:install' ]
 
@@ -36,8 +51,7 @@ begin
 
   Jeweler::Tasks.new do |gemspec|
     gemspec.name = "resque"
-    gemspec.summary = ""
-    gemspec.description = ""
+    gemspec.summary = "Resque is a Redis-backed queueing system."
     gemspec.email = "chris@ozmm.org"
     gemspec.homepage = "http://github.com/defunkt/resque"
     gemspec.authors = ["Chris Wanstrath"]
@@ -48,18 +62,45 @@ begin
     gemspec.add_dependency "vegas", ">=0.1.2"
     gemspec.add_dependency "sinatra", ">=0.9.2"
     gemspec.add_development_dependency "jeweler"
+
+    gemspec.description = <<description
+    Resque is a Redis-backed Ruby library for creating background jobs,
+    placing those jobs on multiple queues, and processing them later.
+
+    Background jobs can be any Ruby class or module that responds to
+    perform. Your existing classes can easily be converted to background
+    jobs or you can create new classes specifically to do work. Or, you
+    can do both.
+
+    Resque is heavily inspired by DelayedJob (which rocks) and is
+    comprised of three parts:
+
+    * A Ruby library for creating, querying, and processing jobs
+    * A Rake task for starting a worker which processes jobs
+    * A Sinatra app for monitoring queues, jobs, and workers.
+description
   end
 rescue LoadError
   puts "Jeweler not available. Install it with: "
   puts "gem install jeweler"
 end
 
+
+#
+# Documentation
+#
+
 begin
   require 'sdoc_helpers'
 rescue LoadError
   puts "sdoc support not enabled. Please gem install sdoc-helpers."
 end
 
+
+#
+# Publishing
+#
+
 desc "Push a new version to Gemcutter"
 task :publish => [ :test, :gemspec, :build ] do
   system "git tag v#{Resque::Version}"

data/{HOOKS.md → docs/HOOKS.md}

@@ -60,7 +60,9 @@ like this:
 
 Once this hook is made available to your job (either by way of
 inheritence or `extend`), it will be run before the job's `perform`
-method is called.
+method is called. Hooks of each type are executed in alphabetical order,
+so `before_perform_a` will always be executed before `before_perform_b`.
+An unnamed hook (`before_perform`) will be executed first.
 
 The available hooks are:
 
@@ -117,4 +119,3 @@ Modules are even better because jobs can use many of them.
         ...
       end
     end
-

data/docs/PLUGINS.md

@@ -0,0 +1,93 @@
+Resque Plugins
+==============
+
+Resque encourages plugin development. For a list of available plugins,
+please see <http://wiki.github.com/defunkt/resque/plugins>.
+
+The `docs/HOOKS.md` file included with Resque documents the available
+hooks you can use to add or change Resque functionality. This document
+describes best practice for plugins themselves.
+
+
+Version
+-------
+
+Plugins should declare the major.minor version of Resque they are
+known to work with explicitly in their README.
+
+For example, if your plugin depends on features in Resque 2.1, please
+list "Depends on Resque 2.1" very prominently near the beginning of
+your README.
+
+Because Resque uses [Semantic Versioning][sv], you can safely make the
+following assumptions:
+
+* Your plugin will work with 2.2, 2.3, etc - no methods will be
+  removed or changed, only added.
+* Your plugin might not work with 3.0+, as APIs may change or be
+  removed.
+
+
+Namespace
+---------
+
+All plugins should live under the `Resque::Plugins` module to avoid
+clashing with first class Resque constants or other Ruby libraries.
+
+Good:
+
+* Resque::Plugins::Lock
+* Resque::Plugins::FastRetry
+
+Bad:
+
+* Resque::Lock
+* ResqueQueue
+
+
+Gem Name
+--------
+
+Gem names should be in the format of `resque-FEATURE`, where `FEATURE`
+succinctly describes the feature your plugin adds to Resque.
+
+Good:
+
+* resque-status
+* resque-scheduler
+
+Bad:
+
+* multi-queue
+* defunkt-resque-lock
+
+
+Hooks
+-----
+
+Job hook names should be namespaced to work properly.
+
+Good:
+
+* before_perform_lock
+* around_perform_check_status
+
+Bad:
+
+* before_perform
+* on_failure
+
+
+Lint
+----
+
+Plugins should test compliance to this document using the
+`Resque::Plugin.lint` method.
+
+For example:
+
+    def test_lint
+      assert Resque::Plugin.lint(Resque::Plugins::Lock)
+    end
+
+[sv]: http://semver.org/

data/lib/resque.rb

@@ -17,6 +17,7 @@ require 'resque/helpers'
 require 'resque/stat'
 require 'resque/job'
 require 'resque/worker'
+require 'resque/plugin'
 
 module Resque
   include Helpers

data/lib/resque/job.rb

@@ -109,10 +109,10 @@ module Resque
       job_args = args || []
       job_was_performed = false
 
-      before_hooks  = job.methods.grep(/^before_perform/)
-      around_hooks  = job.methods.grep(/^around_perform/)
-      after_hooks   = job.methods.grep(/^after_perform/)
-      failure_hooks = job.methods.grep(/^on_failure/)
+      before_hooks  = Plugin.before_hooks(job)
+      around_hooks  = Plugin.around_hooks(job)
+      after_hooks   = Plugin.after_hooks(job)
+      failure_hooks = Plugin.failure_hooks(job)
 
       begin
         # Execute before_perform hook. Abort the job gracefully if
@@ -132,7 +132,7 @@ module Resque
         else
           # We want to nest all around_perform plugins, with the last one
           # finally calling perform
-          stack = around_hooks.inject(nil) do |last_hook, hook|
+          stack = around_hooks.reverse.inject(nil) do |last_hook, hook|
             if last_hook
               lambda do
                 job.send(hook, *job_args) { last_hook.call }

data/lib/resque/plugin.rb

@@ -0,0 +1,46 @@
+module Resque
+  module Plugin
+    extend self
+
+    LintError = Class.new(RuntimeError)
+
+    # Ensure that your plugin conforms to good hook naming conventions.
+    #
+    #   Resque::Plugin.lint(MyResquePlugin)
+    def lint(plugin)
+      hooks = before_hooks(plugin) + around_hooks(plugin) + after_hooks(plugin)
+
+      hooks.each do |hook|
+        if hook =~ /perform$/
+          raise LintError, "#{plugin}.#{hook} is not namespaced"
+        end
+      end
+
+      failure_hooks(plugin).each do |hook|
+        if hook =~ /failure$/
+          raise LintError, "#{plugin}.#{hook} is not namespaced"
+        end
+      end
+    end
+
+    # Given an object, returns a list `before_perform` hook names.
+    def before_hooks(job)
+      job.methods.grep(/^before_perform/).sort
+    end
+
+    # Given an object, returns a list `around_perform` hook names.
+    def around_hooks(job)
+      job.methods.grep(/^around_perform/).sort
+    end
+
+    # Given an object, returns a list `after_perform` hook names.
+    def after_hooks(job)
+      job.methods.grep(/^after_perform/).sort
+    end
+
+    # Given an object, returns a list `on_failure` hook names.
+    def failure_hooks(job)
+      job.methods.grep(/^on_failure/).sort
+    end
+  end
+end

data/lib/resque/version.rb

@@ -1,3 +1,3 @@
 module Resque
-  Version = '1.7.0'
+  Version = '1.7.1'
 end

data/lib/resque/worker.rb

@@ -207,6 +207,10 @@ module Resque
       prune_dead_workers
       run_hook :before_first_fork
       register_worker
+
+      # Fix buffering so we can `rake resque:work > resque.log` and
+      # get output from the child in there.
+      $stdout.sync = true
     end
 
     # Enables GC Optimizations if you're running REE.

data/test/job_plugins_test.rb

@@ -0,0 +1,209 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+context "Multiple plugins with multiple hooks" do
+  include PerformJob
+
+  module Plugin1
+    def before_perform_record_history1(history)
+      history << :before1
+    end
+    def after_perform_record_history1(history)
+      history << :after1
+    end
+  end
+
+  module Plugin2
+    def before_perform_record_history2(history)
+      history << :before2
+    end
+    def after_perform_record_history2(history)
+      history << :after2
+    end
+  end
+
+  class ManyBeforesJob
+    extend Plugin1
+    extend Plugin2
+    def self.perform(history)
+      history << :perform
+    end
+  end
+
+  test "hooks of each type are executed in alphabetical order" do
+    result = perform_job(ManyBeforesJob, history=[])
+    assert_equal true, result, "perform returned true"
+    assert_equal [:before1, :before2, :perform, :after1, :after2], history
+  end
+end
+
+context "Resque::Plugin ordering before_perform" do
+  include PerformJob
+
+  module BeforePerformPlugin
+    def before_perform1(history)
+      history << :before_perform1
+    end
+  end
+
+  class BeforePerformJob
+    extend BeforePerformPlugin
+    def self.perform(history)
+      history << :perform
+    end
+    def self.before_perform(history)
+      history << :before_perform
+    end
+  end
+
+  test "before_perform hooks are executed in order" do
+    result = perform_job(BeforePerformJob, history=[])
+    assert_equal true, result, "perform returned true"
+    assert_equal [:before_perform, :before_perform1, :perform], history
+  end
+end
+
+context "Resque::Plugin ordering after_perform" do
+  include PerformJob
+
+  module AfterPerformPlugin
+    def after_perform_record_history(history)
+      history << :after_perform1
+    end
+  end
+
+  class AfterPerformJob
+    extend AfterPerformPlugin
+    def self.perform(history)
+      history << :perform
+    end
+    def self.after_perform(history)
+      history << :after_perform
+    end
+  end
+
+  test "after_perform hooks are executed in order" do
+    result = perform_job(AfterPerformJob, history=[])
+    assert_equal true, result, "perform returned true"
+    assert_equal [:perform, :after_perform, :after_perform1], history
+  end
+end
+
+context "Resque::Plugin ordering around_perform" do
+  include PerformJob
+
+  module AroundPerformPlugin1
+    def around_perform1(history)
+      history << :around_perform_plugin1
+      yield
+    end
+  end
+
+  class AroundPerformJustPerformsJob
+    extend AroundPerformPlugin1
+    def self.perform(history)
+      history << :perform
+    end
+  end
+
+  test "around_perform hooks are executed before the job" do
+    result = perform_job(AroundPerformJustPerformsJob, history=[])
+    assert_equal true, result, "perform returned true"
+    assert_equal [:around_perform_plugin1, :perform], history
+  end
+
+  class AroundPerformJob
+    extend AroundPerformPlugin1
+    def self.perform(history)
+      history << :perform
+    end
+    def self.around_perform(history)
+      history << :around_perform
+      yield
+    end
+  end
+
+  test "around_perform hooks are executed in order" do
+    result = perform_job(AroundPerformJob, history=[])
+    assert_equal true, result, "perform returned true"
+    assert_equal [:around_perform, :around_perform_plugin1, :perform], history
+  end
+
+  module AroundPerformPlugin2
+    def around_perform2(history)
+      history << :around_perform_plugin2
+      yield
+    end
+  end
+
+  class AroundPerformJob2
+    extend AroundPerformPlugin1
+    extend AroundPerformPlugin2
+    def self.perform(history)
+      history << :perform
+    end
+    def self.around_perform(history)
+      history << :around_perform
+      yield
+    end
+  end
+
+  test "many around_perform are executed in order" do
+    result = perform_job(AroundPerformJob2, history=[])
+    assert_equal true, result, "perform returned true"
+    assert_equal [:around_perform, :around_perform_plugin1, :around_perform_plugin2, :perform], history
+  end
+
+  module AroundPerformDoesNotYield
+    def around_perform0(history)
+      history << :around_perform0
+    end
+  end
+
+  class AroundPerformJob3
+    extend AroundPerformPlugin1
+    extend AroundPerformPlugin2
+    extend AroundPerformDoesNotYield
+    def self.perform(history)
+      history << :perform
+    end
+    def self.around_perform(history)
+      history << :around_perform
+      yield
+    end
+  end
+
+  test "the job is aborted if an around_perform hook does not yield" do
+    result = perform_job(AroundPerformJob3, history=[])
+    assert_equal false, result, "perform returned false"
+    assert_equal [:around_perform, :around_perform0], history
+  end
+end
+
+context "Resque::Plugin ordering on_failure" do
+  include PerformJob
+
+  module OnFailurePlugin
+    def on_failure1(exception, history)
+      history << "#{exception.message} plugin"
+    end
+  end
+
+  class FailureJob
+    extend OnFailurePlugin
+    def self.perform(history)
+      history << :perform
+      raise StandardError, "oh no"
+    end
+    def self.on_failure(exception, history)
+      history << exception.message
+    end
+  end
+
+  test "on_failure hooks are executed in order" do
+    history = []
+    assert_raises StandardError do
+      perform_job(FailureJob, history)
+    end
+    assert_equal [:perform, "oh no", "oh no plugin"], history
+  end
+end

data/test/plugin_test.rb

@@ -0,0 +1,116 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+context "Resque::Plugin finding hooks" do
+  module SimplePlugin
+    extend self
+    def before_perform1; end
+    def before_perform; end
+    def before_perform2; end
+    def after_perform1; end
+    def after_perform; end
+    def after_perform2; end
+    def perform; end
+    def around_perform1; end
+    def around_perform; end
+    def around_perform2; end
+    def on_failure1; end
+    def on_failure; end
+    def on_failure2; end
+  end
+
+  test "before_perform hooks are found and sorted" do
+    assert_equal ["before_perform", "before_perform1", "before_perform2"], Resque::Plugin.before_hooks(SimplePlugin)
+  end
+
+  test "after_perform hooks are found and sorted" do
+    assert_equal ["after_perform", "after_perform1", "after_perform2"], Resque::Plugin.after_hooks(SimplePlugin)
+  end
+
+  test "around_perform hooks are found and sorted" do
+    assert_equal ["around_perform", "around_perform1", "around_perform2"], Resque::Plugin.around_hooks(SimplePlugin)
+  end
+
+  test "on_failure hooks are found and sorted" do
+    assert_equal ["on_failure", "on_failure1", "on_failure2"], Resque::Plugin.failure_hooks(SimplePlugin)
+  end
+end
+
+context "Resque::Plugin linting" do
+  module BadBefore
+    def self.before_perform; end
+  end
+  module BadAfter
+    def self.after_perform; end
+  end
+  module BadAround
+    def self.around_perform; end
+  end
+  module BadFailure
+    def self.on_failure; end
+  end
+
+  test "before_perform must be namespaced" do
+    begin
+      Resque::Plugin.lint(BadBefore)
+      assert false, "should have failed"
+    rescue Resque::Plugin::LintError => e
+      assert_equal "BadBefore.before_perform is not namespaced", e.message
+    end
+  end
+
+  test "after_perform must be namespaced" do
+    begin
+      Resque::Plugin.lint(BadAfter)
+      assert false, "should have failed"
+    rescue Resque::Plugin::LintError => e
+      assert_equal "BadAfter.after_perform is not namespaced", e.message
+    end
+  end
+
+  test "around_perform must be namespaced" do
+    begin
+      Resque::Plugin.lint(BadAround)
+      assert false, "should have failed"
+    rescue Resque::Plugin::LintError => e
+      assert_equal "BadAround.around_perform is not namespaced", e.message
+    end
+  end
+
+  test "on_failure must be namespaced" do
+    begin
+      Resque::Plugin.lint(BadFailure)
+      assert false, "should have failed"
+    rescue Resque::Plugin::LintError => e
+      assert_equal "BadFailure.on_failure is not namespaced", e.message
+    end
+  end
+
+  module GoodBefore
+    def self.before_perform1; end
+  end
+  module GoodAfter
+    def self.after_perform1; end
+  end
+  module GoodAround
+    def self.around_perform1; end
+  end
+  module GoodFailure
+    def self.on_failure1; end
+  end
+
+  test "before_perform1 is an ok name" do
+    Resque::Plugin.lint(GoodBefore)
+  end
+
+  test "after_perform1 is an ok name" do
+    Resque::Plugin.lint(GoodAfter)
+  end
+
+  test "around_perform1 is an ok name" do
+    Resque::Plugin.lint(GoodAround)
+  end
+
+  test "on_failure1 is an ok name" do
+    Resque::Plugin.lint(GoodFailure)
+  end
+end

data/test/worker_test.rb

@@ -17,7 +17,7 @@ context "Resque::Worker" do
     @worker.work(0)
     assert_equal 1, Resque::Failure.count
   end
-  
+
   test "failed jobs report excpetion and message" do
     Resque::Job.create(:jobs, BadJobWithSyntaxError)
     @worker.work(0)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: resque
 version: !ruby/object:Gem::Version 
-  version: 1.7.0
+  version: 1.7.1
 platform: ruby
 authors: 
 - Chris Wanstrath
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-31 00:00:00 -07:00
+date: 2010-04-02 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -62,7 +62,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-description: ""
+description: "    Resque is a Redis-backed Ruby library for creating background jobs,\n    placing those jobs on multiple queues, and processing them later.\n\n    Background jobs can be any Ruby class or module that responds to\n    perform. Your existing classes can easily be converted to background\n    jobs or you can create new classes specifically to do work. Or, you\n    can do both.\n\n    Resque is heavily inspired by DelayedJob (which rocks) and is\n    comprised of three parts:\n\n    * A Ruby library for creating, querying, and processing jobs\n    * A Rake task for starting a worker which processes jobs\n    * A Sinatra app for monitoring queues, jobs, and workers.\n"
 email: chris@ozmm.org
 executables: 
 - resque
@@ -77,7 +77,6 @@ files:
 - .kick
 - CONTRIBUTORS
 - HISTORY.md
-- HOOKS.md
 - LICENSE
 - README.markdown
 - Rakefile
@@ -85,6 +84,8 @@ files:
 - bin/resque-web
 - config.ru
 - deps.rip
+- docs/HOOKS.md
+- docs/PLUGINS.md
 - examples/async_helper.rb
 - examples/demo/README.markdown
 - examples/demo/Rakefile
@@ -106,6 +107,7 @@ files:
 - lib/resque/failure/redis.rb
 - lib/resque/helpers.rb
 - lib/resque/job.rb
+- lib/resque/plugin.rb
 - lib/resque/server.rb
 - lib/resque/server/public/idle.png
 - lib/resque/server/public/jquery-1.3.2.min.js
@@ -134,6 +136,8 @@ files:
 - tasks/redis.rake
 - tasks/resque.rake
 - test/job_hooks_test.rb
+- test/job_plugins_test.rb
+- test/plugin_test.rb
 - test/redis-test.conf
 - test/resque-web_test.rb
 - test/resque_test.rb
@@ -166,9 +170,11 @@ rubyforge_project:
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: ""
+summary: Resque is a Redis-backed queueing system.
 test_files: 
 - test/job_hooks_test.rb
+- test/job_plugins_test.rb
+- test/plugin_test.rb
 - test/resque-web_test.rb
 - test/resque_test.rb
 - test/test_helper.rb