http_resque 0.0.2 → 0.0.3

data/README.markdown

@@ -1,3 +1,82 @@
-HTTP Resque
+http_resque
 ===========
-Docs forthcoming.
+http_resque helps you cleanly write integration tests for your Resque jobs. It's a thin HTTP API around the
+Resque daemon. With it you can manipulate the contents of the Resque queues using HTTP requests.
+
+This is a key ingredient for writing off-box integration tests for your background jobs. In addition to inspecting and clearing queues, you can run a Resque job _synchronously_. This allows you to test that your
+background jobs are working by making HTTP requests, which is the same simple way you'd test a running webapp or a RESTful API server.
+
+Making your background jobs easier to integration test is important -- background jobs are prone to failure
+because they run in the background, and frequently have environment-related bugs in production. Unit tests
+usually aren't good enough.
+
+Installation & Usage
+--------------------
+
+    gem install http_resque
+
+    QUEUE=* http_resque
+
+    or if you use Bundler:
+    QUEUE=* bundle exec http_resque
+
+Optional command line arguments:
+
+    $ http_resque -h
+            -p: the port to listen on. Defaults to the $PORT environment variable, or 4568.
+      --rakefile: the location of your Rakefile. The default is "./Rakefile".
+
+When run, http_resque starts a small web server and then invokes `rake resque:work` in a fork.
+
+REST APIs for Resque
+--------------------
+
+Once the http_resque server is started, you can access these URLs to manipulate your background jobs:
+
+### GET /queues/:queue_name/jobs
+
+Lists all jobs in the queue named "queue_name", oldest first.
+
+    $ curl localhost:4568/queues/my_test_queue/jobs
+
+    Response:
+    [
+      { "class" => "EmailComment", "args" => ["jack_sparrow@pirates.net"] },
+      ...
+    ]
+
+### DELETE /queues/:queue_name/jobs
+
+Deletes all jobs in the given queue.
+
+    $ curl -X DELETE localhost:4568/queues/my_test_queue/jobs
+
+### POST /queues/:queue_name/jobs
+
+Create a new background job. The body of the request should be in JSON and include "class" and "arguments".
+
+    $ curl -X POST localhost:4568/queues/my_test_queue/jobs \
+         -d '{ "class": "EmailComment", "arguments":["jack_sparrow@pirates.net"] }'
+
+### GET /queues/:queue_name/result_of_oldest_job
+
+Runs the oldest job on the given queue, and does not return until it's finished. If there was a problem
+running the job (like the job threw a Ruby exception), this will return a 500 status code with the exception
+details.
+
+    $ curl localhost:4568/queues/my_test_queue/result_of_oldest_job
+
+    A response with a status of:
+    200 if successful.
+    404 if there are no jobs in this queue.
+    500 if there was an error running the job.
+
+For further details, look at the web server's code in [bin/http_resque](https://github.com/philc/http_resque/blob/master/bin/http_resque). The code is shorter than this README.
+
+Contribute
+----------
+http_resque is pretty small and limited as is. If you need more CLI options or a different set of REST APIs, file an issue or send a pull request.
+
+Related
+-------
+[remote_http_testing](https://github.com/ooyala/remote_http_testing) - a small library for making remote HTTP requests and response assertions in tests.

data/bin/http_resque

@@ -1,40 +1,54 @@
 #!/usr/bin/env ruby
-
+#
 # This wraps the Resque process with a thin HTTP API which enables you to manipulate jobs using HTTP requests
-# and run jobs synchronously, off-box, for the purposes of integration testing background jobs. This is
-# necessary because background jobs fail notoriously often in production and so they need integration -- not
-# unit -- tests. This helps you to cleanly write those integration tests.
+# and run jobs synchronously, for the purposes of integration testing background jobs. See the README for
+# more details of why this is awesome.
 #
 # Usage:
-# QUEUE=* http_resque -p 8080
-# The server uses port 4567 by default. Use -p to specify an alternate port.
-# You'll note that the QUEUE environment variable is used just like it is when running `rake resque:work`.
-
+#   QUEUE=* http_resque
+#   Options:
+#          -p: the port to listen on. Defaults to the $PORT environment variable, or 4568.
+#  --rakefile: the location of your Rakefile. The default is "./Rakefile".
+#
 # Once it's started, you can access these URLs to manipulate jobs:
-#   GET    /queues/:queue/jobs
-#   DELETE /queues/:queue/jobs
-#   POST   /queues/:queue/jobs
-#   GET    /queues/:queue/result_of_oldest_job
+#   GET    /queues/:queue_name/jobs
+#   DELETE /queues/:queue_name/jobs
+#   POST   /queues/:queue_name/jobs
+#   GET    /queues/:queue_name/result_of_oldest_job
 
 require "sinatra/base"
 require "thin"
 require "resque"
 require "rake"
 require "json"
+require "trollop"
 
-# Load the Rakefile which should in turn require all of their Resque job classes.
-# TODO(philc): The path to this Rakefile should be an argument.
-load "./Rakefile"
+class HttpResqueServer < Sinatra::Base
+  cli_options = Trollop::options do
+    opt :rakefile, "The location of your Rakefile which loads your Resque workers.", :default => "./Rakefile"
+    opt :port, "The port this server should listen on."
+  end
 
-class HttpResque < Sinatra::Base
-  settings.server = "thin"
+  unless ENV["QUEUE"]
+    puts "You must set the QUEUE env var, just as you would when running `QUEUE=* rake resque:work`."
+    exit 1
+  end
 
   STDOUT.sync = STDERR.sync = true
 
+  begin
+    # Load their Rakefile, which should in turn require all of their Resque job classes.
+    load cli_options[:rakefile]
+  rescue LoadError
+    puts "Error loading Rakefile: #{cli_options[:rakefile]}. Give the path to your Rakefile using --rakefile."
+    exit 1
+  end
+
   # Run rake resque:work in a background process. It will exit when this process exits.
   fork { Rake::Task["resque:work"].invoke }
 
-  settings.port = ARGV.include?("-p") ? ARGV[ARGV.index("-p") + 1] : ENV["PORT"]
+  settings.port = cli_options[:port] || ENV["PORT"] || 4568
+  settings.server = "thin"
 
   get "/" do
     "http_resque is here."
@@ -56,9 +70,8 @@ class HttpResque < Sinatra::Base
   # - arguments: optional; an array of arguments for the Resque job.
   post "/queues/:queue/jobs" do
     halt(400, "Provide a valid JSON body.") unless json_body
-    klass = json_body["class"]
-    halt(400, "Specify a class.") unless klass
-    klass = Object.const_get(klass)
+    halt(400, "Specify a class.") unless json_body["class"]
+    klass = Object.const_get(json_body["class"])
     Resque.enqueue_to(params[:queue], klass, *json_body["arguments"])
     nil
   end
@@ -79,5 +92,5 @@ class HttpResque < Sinatra::Base
 
   def json_body() @json_body ||= JSON.parse(request.body.read) rescue nil end
 
-  run! if app_file == $0
+  run! if File.basename(app_file) == File.basename($0)
 end

data/http_resque.gemspec

@@ -8,7 +8,10 @@ Gem::Specification.new do |s|
   s.authors     = ["Phil Crosby"]
   s.email       = ["phil.crosby@gmail.com"]
   s.homepage    = "http://github.com/philc/http_resque"
-  s.summary     = "A small HTTP wrapper around Resque, so you can schedule and test jobs over HTTP."
+  s.summary     = "Schedule and test Resque jobs using HTTP requests."
+  s.description = "http_resque helps you cleanly write integration tests for your Resque jobs. It's a thin " +
+      "HTTP API around the Resque daemon. With it you can manipulate the contents of the Resque queues " +
+      "using HTTP requests."
 
   s.rubyforge_project = "http_resque"
 
@@ -22,4 +25,5 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency "rake"
   s.add_runtime_dependency "json"
   s.add_runtime_dependency "sinatra"
+  s.add_runtime_dependency "trollop"
 end

data/lib/http_resque.rb

@@ -1 +1 @@
-require "howdy/version"
+require "http_resque/version"

data/lib/http_resque/version.rb

@@ -1,3 +1,3 @@
 module HttpResque
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: http_resque
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Phil Crosby
@@ -88,7 +88,21 @@ dependencies:
         version: "0"
   type: :runtime
   version_requirements: *id005
-description: 
+- !ruby/object:Gem::Dependency 
+  name: trollop
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id006
+description: http_resque helps you cleanly write integration tests for your Resque jobs. It's a thin HTTP API around the Resque daemon. With it you can manipulate the contents of the Resque queues using HTTP requests.
 email: 
 - phil.crosby@gmail.com
 executables: 
@@ -139,6 +153,6 @@ rubyforge_project: http_resque
 rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
-summary: A small HTTP wrapper around Resque, so you can schedule and test jobs over HTTP.
+summary: Schedule and test Resque jobs using HTTP requests.
 test_files: []