beaneater 0.1.0 → 0.1.1

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# CHANGELOG for Beaneater
+
+## 0.1.2 (Unreleased)
+
+## 0.1.1 (Nov 4 2012)
+
+* Add `Jobs#find_all` to fix #10
+* Fixed issue with `tubes-list` by merging results
+* Add `Job#ttr`, `Job#pri`, `Job#delay`
+* Improved yardocs coverage and accuracy
+
+## 0.1.0 (Nov 1 2012)
+
+* Initial release!

data/README.md

@@ -3,7 +3,7 @@
 Beaneater is the best way to interact with beanstalkd from within Ruby.
 [Beanstalkd](http://kr.github.com/beanstalkd/) is a simple, fast work queue. Its interface is generic, but was
 originally designed for reducing the latency of page views in high-volume web applications by
-running time-consuming tasks asynchronously. Read the
+running time-consuming tasks asynchronously. Read the [yardocs](http://rdoc.info/github/beanstalkd/beaneater) and/or the
 [beanstalk protocol](https://github.com/kr/beanstalkd/blob/master/doc/protocol.md) for more details.
 
 
@@ -13,32 +13,35 @@ Illya has an excellent blog post
 [Scalable Work Queues with Beanstalk](http://www.igvita.com/2010/05/20/scalable-work-queues-with-beanstalk/) and
 Adam Wiggins posted [an excellent comparison](http://adam.heroku.com/past/2010/4/24/beanstalk_a_simple_and_fast_queueing_backend/).
 
-You will quickly see that **beanstalkd** is an underrated but incredible project that is extremely well-suited as a job queue.
-Significantly better suited for this task than Redis or a database. Beanstalk is a simple,
-and a very fast work queue service rolled into a single binary - it is the memcached of work queues.
-Originally built to power the backend for the 'Causes' Facebook app, it is a mature and production ready open source project.
-[PostRank](http://www.postrank.com) uses beanstalk to reliably process millions of jobs a day.
+You will find that **beanstalkd** is an underrated but incredibly
+powerful project that is extremely well-suited as a job or messaging queue.
+Significantly better suited for this task than Redis or a traditional RDBMS. Beanstalk is a simple,
+and fast work queue service rolled into a single binary - it is the memcached of work queues.
+Originally built to power the backend for the 'Causes' Facebook app,
+it is a mature and production ready open source project.
+[PostRank](http://www.postrank.com) has used beanstalk to reliably process millions of jobs a day.
 
 A single instance of Beanstalk is perfectly capable of handling thousands of jobs a second (or more, depending on your job size)
 because it is an in-memory, event-driven system. Powered by libevent under the hood,
-it requires zero setup (launch and forget, à la memcached), optional log based persistence, an easily parsed ASCII protocol,
-and a rich set of tools for job management that go well beyond a simple FIFO work queue.
+it requires zero setup (launch and forget, à la memcached), optional log based persistence,
+an easily parsed ASCII protocol, and a rich set of tools for job management
+that go well beyond a simple FIFO work queue.
 
 Beanstalkd supports the following features out of the box:
 
 | Feature | Description                     |
 | ------- | ------------------------------- |
-| **Parallel Queues** | Supports multiple work queues created on demand. |
+| **Parallelized**    | Supports multiple work queues created on demand. |
 | **Reliable**        | Beanstalk’s reserve, work, delete cycle ensures reliable processing. |
 | **Scheduling**      | Delay enqueuing jobs by a specified interval to schedule processing later |
-| **Fast**            | Processes thousands of jobs per second; **significantly** faster than alternatives. |
+| **Fast**            | Processes thousands of jobs per second without breaking a sweat. |
 | **Priorities**      | Specify priority so important jobs can be processed quickly. |
 | **Persistence**     | Jobs are stored in memory for speed, but logged to disk for safe keeping. |
 | **Federation**      | Horizontal scalability provided through federation by the client. |
 | **Error Handling**  | Bury any job which causes an error for later debugging and inspection.|
 
-Keep in mind that these features are supported out of the box with beanstalk and require no special code within this gem to support.
-In the end, **beanstalk is the ideal job queue** while also being ridiculously easy to install and setup.
+Keep in mind that these features are supported out of the box with beanstalk and requires no special ruby specific logic.
+In the end, **beanstalk is the ideal job queue** and has the added benefit of being easy to setup and configure.
 
 ## Installation
 
@@ -47,7 +50,6 @@ Install beanstalkd:
 Mac OS
 
 ```
-brew update
 brew install beanstalkd
 beanstalkd -p 11300
 ```
@@ -74,6 +76,29 @@ gem 'beaneater'
 
 and run `bundle install` to install the dependency.
 
+## Quick Overview:
+
+The concise summary of how to use beaneater:
+
+```ruby
+# Connect to pool
+@beanstalk = Beaneater::Pool.new(['localhost:11300'])
+# Enqueue jobs to tube
+@tube = @beanstalk.tubes["my-tube"]
+@tube.put '{ "key" : "foo" }', :pri => 5
+@tube.put '{ "key" : "bar" }', :delay => 3
+# Process jobs from tube
+while @tube.peek(:ready)
+  job = @tube.reserve
+  puts "job value is #{job.body["key"]}!"
+  job.delete
+end
+# Disconnect the pool
+@beanstalk.close
+```
+
+For a more detailed rundown, check out the __Usage__ section below.
+
 ## Usage
 
 ### Connection
@@ -82,6 +107,11 @@ To interact with a beanstalk queue, first establish a connection by providing a
 
 ```ruby
 @beanstalk = Beaneater::Pool.new(['10.0.1.5:11300'])
+
+# Or if ENV['BEANSTALKD_URL] == 'localhost:11300,127.0.0.1:11300'
+@beanstalk = Beaneater::Pool.new
+@beanstalk.connections.first # => localhost:11300
+@beanstalk.connections.last # => 127.0.0.1:11300
 ```
 
 You can conversely close and dispose of a pool at any time with:
@@ -277,6 +307,13 @@ inspected using the 'peek' commands. To find and peek at a particular job based
 # => <Beaneater::Job id=123 body="foo">
 ```
 
+You can also `find_all` jobs across all connections:
+
+```ruby
+@beanstalk.jobs.find_all(123)
+# => [<Beaneater::Job id=123 body="foo">, <Beaneater::Job id=123 body="bar">]
+```
+
 or you can peek at jobs within a tube:
 
 ```ruby
@@ -346,6 +383,7 @@ are listed below:
 | Beaneater::InvalidTubeName  | Specified tube name for use or watch is not valid.    |
 | Beaneater::NotFoundError    | Specified job or tube could not be found.             |
 | Beaneater::TimedOutError    | Job could not be reserved within time specified.      |
+| Beaneater::JobNotReserved   | Job has not been reserved and action cannot be taken. |
 
 There are other exceptions that are less common such as `OutOfMemoryError`, `DrainingError`,
 `DeadlineSoonError`, `InternalError`, `BadFormatError`, `UnknownCommandError`,
@@ -389,11 +427,15 @@ more details about the stats commands.
 
 There are other resources helpful when learning about beanstalk:
 
+ * [Beaneater Yardocs](http://rdoc.info/github/beanstalkd/beaneater)
+ * [Beaneater on Rubygems](https://rubygems.org/gems/beaneater)
  * [Beanstalkd homepage](http://kr.github.com/beanstalkd/)
  * [beanstalk on github](https://github.com/kr/beanstalkd)
  * [beanstalk protocol](https://github.com/kr/beanstalkd/blob/master/doc/protocol.md)
+ * [Backburner](https://github.com/nesquena/backburner) - Ruby job queue for Rails/Sinatra
 
 ## Contributors
 
  - [Nico Taing](https://github.com/Nico-Taing) - Creator and co-maintainer
- - [Nathan Esquenazi](https://github.com/nesquena) - Contributor and co-maintainer
+ - [Nathan Esquenazi](https://github.com/nesquena) - Contributor and co-maintainer
+ - [Keith Rarick](https://github.com/kr) - Much code inspired and adapted from beanstalk-client

data/Rakefile

@@ -3,6 +3,7 @@ require 'rake/testtask'
 require 'yard'
 require 'redcarpet'
 
+# rake test
 Rake::TestTask.new do |t|
   t.libs.push "lib"
   t.test_files = FileList[File.expand_path('../test/**/*_test.rb', __FILE__)] -
@@ -10,6 +11,13 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
+# rake test:integration
+Rake::TestTask.new("test:integration") do |t|
+  t.libs.push "lib"
+  t.test_files = FileList[File.expand_path('../test/**/beaneater_test.rb', __FILE__)]
+  t.verbose = true
+end
+
 # rake test:full
 Rake::TestTask.new("test:full") do |t|
   t.libs.push "lib"

data/TODO

@@ -1,2 +1 @@
-- Add YARD docs for all classes (see REF file)
 - Remove connection from pool if it's not responding and be able to add more connections and reattempt later

data/lib/beaneater/connection.rb

@@ -1,42 +1,50 @@
 require 'yaml'
 
 module Beaneater
-  # Represents a connection to beanstalkd server
+  # Represents a connection to a beanstalkd instance.
   class Connection
 
-    # @!attribute telnet_connection
-    #   @return [Net::Telnet] returns Telnet connection object
     # @!attribute address
     #   @return [String] returns Beanstalkd server address
+    #   @example
+    #     @conn.address # => "localhost:11300"
     # @!attribute host
     #   @return [String] returns Beanstalkd server host
+    #   @example
+    #     @conn.host # => "localhost"
     # @!attribute port
     #  @return [Integer] returns Beanstalkd server port
-    attr_reader :telnet_connection, :address, :host, :port
+    #  @example
+    #    @conn.port # => "11300"
+    # @!attribute telnet_connection
+    #   @return [Net::Telnet] returns Telnet connection object
+    attr_reader :address, :host, :port, :telnet_connection
 
-    # Default port value
+    # Default port value for beanstalk connection
     DEFAULT_PORT = 11300
 
-    # Initialize new connection
+    # Initializes new connection.
     #
-    # @param [String] address beanstalkd address
+    # @param [String] address beanstalkd instance address.
     # @example
     #   Beaneater::Connection.new('localhost')
     #   Beaneater::Connection.new('localhost:11300')
+    #
     def initialize(address)
       @address = address
       @telnet_connection = establish_connection
       @mutex = Mutex.new
     end
 
-    # Send commands to beanstalkd server via telnet_connection
+    # Send commands to beanstalkd server via telnet_connection.
     #
     # @param [String] command Beanstalkd command
-    # @param [Hash] options Settings for telnet
+    # @param [Hash{Symbol => String,Boolean}] options Settings for telnet
     # @option options [Boolean] FailEOF raises EOF Exeception
-    #
+    # @return [Array<Hash{String => String, Number}>] Beanstalkd command response
     # @example
-    #   @beaneater_connection.transmit('bury 123')
+    #   @conn.transmit('bury 123')
+    #
     def transmit(command, options={}, &block)
       @mutex.lock
       if telnet_connection
@@ -49,19 +57,21 @@ module Beaneater
       @mutex.unlock
     end
 
-    # Close connection with beanstalkd server
+    # Close connection with beanstalkd server.
     #
     # @example
-    #  @beaneater_connection.close
+    #  @conn.close
+    #
     def close
       @telnet_connection.close
       @telnet_connection = nil
     end
 
-    # Returns string representation of job
+    # Returns string representation of job.
     #
     # @example
-    #  @beaneater_connection.inspect
+    #  @conn.inspect
+    #
     def to_s
       "#<Beaneater::Connection host=#{host.inspect} port=#{port.inspect}>"
     end
@@ -90,7 +100,7 @@ module Beaneater
     #
     # @param [String] cmd Beanstalk command transmitted
     # @param [String] res Telnet command response
-    # @return [Hash] Beanstalk command response with `status`, `id`, `body`, and `connection`
+    # @return [Array<Hash{String => String, Number}>] Beanstalk response with `status`, `id`, `body`, and `connection`
     # @raise [Beaneater::UnexpectedResponse] Response from beanstalk command was an error status
     # @example
     #  parse_response("delete 56", "DELETED 56\nFOO")

data/lib/beaneater/errors.rb

@@ -1,5 +1,5 @@
 module Beaneater
-  # Raises when the beanstalkd instance cannot be accessed
+  # Raises when a beanstalkd instance is no longer accessible.
   class NotConnected < RuntimeError; end
   # Raises when the tube name specified is invalid.
   class InvalidTubeName < RuntimeError; end
@@ -15,13 +15,15 @@ module Beaneater
 
     # @!attribute status
     #   @return [String] returns beanstalkd response status
+    #   @example @ex.status # => "NOT_FOUND"
     # @!attribute cmd
     #   @return [String] returns beanstalkd request command
+    #   @example @ex.cmd # => "stats-job 23"
     attr_reader :status, :cmd
 
     # Initialize unexpected response error
     #
-    # @param [UnexpectedResponse] status Unexpected response object
+    # @param [Beaneater::UnexpectedResponse] status Unexpected response object
     # @param [String] cmd Beanstalkd request command
     #
     # @example
@@ -37,6 +39,7 @@ module Beaneater
     # @param [String] status Beanstalkd error status
     # @param [String] cmd Beanstalkd request command
     #
+    # @return [Beaneater::UnexpectedResponse] Exception for the status provided
     # @example
     #   Beaneater::UnexpectedResponse.new('NOT_FOUND', 'bury 123')
     #

data/lib/beaneater/job/collection.rb

@@ -1,30 +1,29 @@
 module Beaneater
-  # Exception to stop processing jobs
+  # Exception to stop processing jobs during a `process!` loop.
+  # Simply `raise AbortProcessingError` in any job process handler to stop the processing loop.
   class AbortProcessingError < RuntimeError; end
 
-  # Represents collection of jobs related commands.
+  # Represents collection of job-related commands.
   class Jobs < PoolCommand
 
     # @!attribute processors
     #   @return [Array<Proc>] returns Collection of proc to handle beanstalkd jobs
     attr_reader :processors
 
-    # Number of retries to process a job
+    # Number of retries to process a job.
     MAX_RETRIES = 3
 
-    # Delay in seconds before to make job ready again
+    # Delay in seconds before to make job ready again.
     RELEASE_DELAY = 1
 
-    # Peek (or find) a job across all beanstalkd servers from pool
-    #
-    # @param [Integer] id Job id
-    #
-    # @raise [Beaneater::NotFoundError] Job not found
+    # Peek (or find) first job from beanstalkd pool.
     #
+    # @param [Integer] id Job id to find
+    # @return [Beaneater::Job] Job matching given id
     # @example
+    #   @beaneater_pool.jobs[123] # => <Beaneater::Job>
     #   @beaneater_pool.jobs.find(123) # => <Beaneater::Job>
     #   @beaneater_pool.jobs.peek(123) # => <Beaneater::Job>
-    #   @beaneater_pool.jobs.find[123] # => <Beaneater::Job>
     #
     # @api public
     def find(id)
@@ -36,13 +35,28 @@ module Beaneater
     alias_method :peek, :find
     alias_method :[], :find
 
-    # Add processor to handle beanstalkd job
+    # Find all jobs with specified id fromm all beanstalkd servers in pool.
+    #
+    # @param [Integer] id Job id to find
+    # @return [Array<Beaneater::Job>] Jobs matching given id
+    # @example
+    #   @beaneater_pool.jobs.find_all(123) # => [<Beaneater::Job>, <Beaneater::Job>]
+    #
+    # @api public
+    def find_all(id)
+      res = transmit_to_all("peek #{id}")
+      res.compact.map { |r| Job.new(r) }
+    rescue Beaneater::NotFoundError => ex
+      []
+    end
+
+    # Register a processor to handle beanstalkd job on particular tube.
     #
     # @param [String] tube_name Tube name
-    # @param [Hash] options settings for processor
+    # @param [Hash{String=>RuntimeError}] options settings for processor
+    # @param [Proc] block Process beanstalkd job
     # @option options [Integer] max_retries Number of retries to process a job
     # @option options [Array<RuntimeError>] retry_on Collection of errors to rescue and re-run processor
-    # @param [Proc] block Process beanstalkd job
     #
     # @example
     #   @beanstalk.jobs.register('some-tube', :retry_on => [SomeError]) do |job|
@@ -61,10 +75,10 @@ module Beaneater
       @processors[tube_name.to_s] = { :block => block, :retry_on => retry_on, :max_retries => max_retries }
     end
 
-    # Watch, reserve, process and delete or bury or release jobs
+    # Watch, reserve, process and delete or bury or release jobs.
     #
-    # @param [Hash] options Settings for processing
-    # @option options [Integer] Delay in seconds before to make job ready again
+    # @param [Hash{String => Integer}] options Settings for processing
+    # @option options [Integer] release_delay Delay in seconds before to make job ready again
     #
     # @api public
     def process!(options={})

data/lib/beaneater/job/record.rb

@@ -3,19 +3,20 @@ module Beaneater
   class Job
 
     # @!attribute id
-    #   @return [Integer] returns Job id
+    #   @return [Integer] id for the job.
     # @!attribute body
-    #   @return [String] returns Job body
+    #   @return [String] the job's body.
     # @!attribute connection
-    #   @return [Beaneater::Connection] returns Connection which has retrieved job
+    #   @return [Beaneater::Connection] connection which has retrieved job.
     # @!attribute reserved
-    #   @return [Boolean] returns If job is being reserved
+    #   @return [Boolean] whether the job has been reserved.
     attr_reader :id, :body, :connection, :reserved
 
 
-    # Initialize new connection
+    # Initializes a new job object.
+    #
+    # @param [Hash{Symbol => String,Number}] res Result from beanstalkd response
     #
-    # @param [Hash] res result from beanstalkd response
     def initialize(res)
       @id         = res[:id]
       @body       = res[:body]
@@ -23,9 +24,9 @@ module Beaneater
       @reserved   = res[:status] == 'RESERVED'
     end
 
-    # Send command to bury job
+    # Sends command to bury a reserved job.
     #
-    # @param [Hash] options Settings to bury job
+    # @param [Hash{Symbol => Integer}] options Settings to bury job
     # @option options [Integer] pri Assign new priority to job
     #
     # @example
@@ -39,12 +40,11 @@ module Beaneater
       end
     end
 
-    # Send command to release job
+    # Sends command to release a job back to ready state.
     #
-    # @param [Hash] options Settings to release job
+    # @param [Hash{String => Integer}] options Settings to release job
     # @option options [Integer] pri Assign new priority to job
-    # @option options [Integer] pri Assign new delay to job
-    #
+    # @option options [Integer] delay Assign new delay to job
     # @example
     #   @beaneater_connection.jobs.find(123).release(:pri => 10, :delay => 5)
     #
@@ -56,7 +56,7 @@ module Beaneater
       end
     end
 
-    # Send command to touch job
+    # Sends command to touch job which extends the ttr.
     #
     # @example
     #   @beaneater_connection.jobs.find(123).touch
@@ -66,7 +66,7 @@ module Beaneater
       with_reserved("touch #{id}")
     end
 
-    # Send command to delete job
+    # Sends command to delete a job.
     #
     # @example
     #   @beaneater_connection.jobs.find(123).delete
@@ -76,7 +76,7 @@ module Beaneater
       transmit("delete #{id}") { @reserved = false }
     end
 
-    # Send command to kick job
+    # Sends command to kick a buried job.
     #
     # @example
     #   @beaneater_connection.jobs.find(123).kick
@@ -86,10 +86,12 @@ module Beaneater
       transmit("kick-job #{id}")
     end
 
-    # Send command to get stats about job
+    # Sends command to get stats about job.
     #
+    # @return [Beaneater::StatStruct] struct filled with relevant job stats
     # @example
     #   @beaneater_connection.jobs.find(123).stats
+    #   @job.stats.tube # => "some-tube"
     #
     # @api public
     def stats
@@ -97,8 +99,9 @@ module Beaneater
       StatStruct.from_hash(res[:body])
     end
 
-    # Check if job is being reserved
+    # Check if job is currently in a reserved state.
     #
+    # @return [Boolean] Returns true if the job is in a reserved state
     # @example
     #   @beaneater_connection.jobs.find(123).reserved?
     #
@@ -107,35 +110,70 @@ module Beaneater
       @reserved || self.stats.state == "reserved"
     end
 
-    # Check if job exists
+    # Check if the job still exists.
     #
+    # @return [Boolean] Returns true if the job still exists
     # @example
     #   @beaneater_connection.jobs.find(123).exists?
     #
     # @api public
     def exists?
-      !!self.stats
+      !self.stats.nil?
     rescue Beaneater::NotFoundError
       false
     end
 
     # Returns the name of the tube this job is in
     #
+    # @return [String] The name of the tube for this job
     # @example
     #   @beaneater_connection.jobs.find(123).tube
+    #     # => "some-tube"
     #
-    # @api public
     def tube
       self.stats && self.stats.tube
     end
 
+    # Returns the ttr of this job
+    #
+    # @return [String] The ttr of this job
+    # @example
+    #   @beaneater_connection.jobs.find(123).ttr
+    #     # => 123
+    #
+    def ttr
+      self.stats && self.stats.ttr
+    end
+
+    # Returns the pri of this job
+    #
+    # @return [String] The pri of this job
+    # @example
+    #   @beaneater_connection.jobs.find(123).pri
+    #     # => 1
+    #
+    def pri
+      self.stats && self.stats.pri
+    end
+
+    # Returns the delay of this job
+    #
+    # @return [String] The delay of this job
+    # @example
+    #   @beaneater_connection.jobs.find(123).delay
+    #     # => 5
+    #
+    def delay
+      self.stats && self.stats.delay
+    end
+
     # Returns string representation of job
     #
+    # @return [String] string representation
     # @example
     #   @beaneater_connection.jobs.find(123).to_s
     #   @beaneater_connection.jobs.find(123).inspect
     #
-    # @api public
     def to_s
       "#<Beaneater::Job id=#{id} body=#{body.inspect}>"
     end
@@ -146,7 +184,7 @@ module Beaneater
     # Transmit command to beanstalkd instances and fetch response.
     #
     # @param [String] cmd Beanstalkd command to send.
-    # @return [Hash] Beanstalkd response for the command.
+    # @return [Hash{Symbol => String,Number}] Beanstalkd response for the command.
     # @example
     #  transmit('stats')
     #  transmit('stats') { 'success' }
@@ -160,7 +198,7 @@ module Beaneater
     # Transmits a command which requires the job to be reserved.
     #
     # @param [String] cmd Beanstalkd command to send.
-    # @return [Hash] Beanstalkd response for the command.
+    # @return [Hash{Symbol => String,Number}] Beanstalkd response for the command.
     # @raise [Beaneater::JobNotReserved] Command cannot execute since job is not reserved.
     # @example
     #   with_reserved("bury 26") { @reserved = false }

data/lib/beaneater/pool.rb

@@ -1,6 +1,6 @@
-# Simple ruby client for beanstalkd.
+# Simple ruby client for interacting with beanstalkd.
 module Beaneater
-  # Represents collection of connections.
+  # Represents collection of beanstalkd connections.
   class Pool
     # Default number of retries to send a command to a connection
     MAX_RETRIES = 3
@@ -11,8 +11,7 @@ module Beaneater
 
     # Initialize new connection
     #
-    # @param [Array] hosts Array of beanstalkd server host
-    #
+    # @param [Array<String>] addresses Array of beanstalkd server addresses
     # @example
     #   Beaneater::Pool.new(['localhost:11300', '127.0.0.1:11300'])
     #
@@ -20,54 +19,92 @@ module Beaneater
     #   @bp = Beaneater::Pool.new
     #   @bp.connections.first.host # => 'localhost'
     #   @bp.connections.last.host # => '127.0.0.1'
-    def initialize(hosts=nil)
-      hosts = hosts || host_from_env
-      @connections = Array(hosts).map { |h| Connection.new(h) }
+    #
+    def initialize(addresses=nil)
+      addresses = addresses || host_from_env
+      @connections = Array(addresses).map { |a| Connection.new(a) }
     end
 
-    # Returns Beaneater::Stats object
+    # Returns Beaneater::Stats object for accessing beanstalk stats.
     #
+    # @return [Beaneater::Stats] stats object
     # @api public
     def stats
       @stats ||= Stats.new(self)
     end
 
-    # Returns Beaneater::Jobs object
+    # Returns Beaneater::Jobs object for accessing job related functions.
     #
+    # @return [Beaneater::Jobs] jobs object
     # @api public
     def jobs
       @jobs ||= Jobs.new(self)
     end
 
-    # Returns Beaneater::Tubes object
+    # Returns Beaneater::Tubes object for accessing tube related functions.
     #
+    # @return [Beaneater::Tubes] tubes object
     # @api public
     def tubes
       @tubes ||= Tubes.new(self)
     end
 
-    # Send command to every beanstalkd servers set in pool
+    # Sends command to every beanstalkd server set in the pool.
     #
     # @param [String] command Beanstalkd command
-    # @param [Hash] options telnet connections options
-    # @param [Proc] block Block passed in telnet connection object
-    #
+    # @param [Hash{String => String, Boolean}] options telnet connections options
+    # @param [Proc] block Block passed to telnet connection during transmit
+    # @return [Array<Hash{String => String, Number}>] Beanstalkd command response from each instance
     # @example
     #   @pool.transmit_to_all("stats")
+    #
     def transmit_to_all(command, options={}, &block)
-      connections.map do |conn|
-        safe_transmit { conn.transmit(command, options, &block) }
-      end
+      res_exception = nil
+      res = connections.map { |conn|
+        begin
+          safe_transmit { conn.transmit(command, options, &block) }
+        rescue UnexpectedResponse => ex # not the correct status
+          res_exception = ex
+          nil
+        end
+      }.compact
+      raise res_exception if res.none? && res_exception
+      res
     end
 
-    # Send command to a random beanstalkd servers set in pool
+    # Send command to each beanstalkd servers until getting response expected
     #
     # @param [String] command Beanstalkd command
-    # @param [Hash] options telnet connections options
+    # @param [Hash{String => String, Boolean}] options telnet connections options
     # @param [Proc] block Block passed in telnet connection object
+    # @return [Array<Hash{String => String, Number}>] Beanstalkd command response from the instance
+    # @example
+    #   @pool.transmit_until_res('peek-ready', :status => "FOUND", &block)
+    #
+    def transmit_until_res(command, options={}, &block)
+      status_expected  = options.delete(:status)
+      res_exception = nil
+      connections.each do |conn|
+        begin
+          res = safe_transmit { conn.transmit(command, options, &block) }
+          return res if res[:status] == status_expected
+        rescue UnexpectedResponse => ex # not the correct status
+          res_exception = ex
+          next
+        end
+      end
+      raise res_exception if res_exception
+    end
+
+    # Sends command to a random beanstalkd server in the pool.
     #
+    # @param [String] command Beanstalkd command
+    # @param [Hash{String => String,Boolean}] options telnet connections options
+    # @param [Proc] block Block passed in telnet connection object
+    # @return [Array<Hash{String => String, Number}>] Beanstalkd command response from the instance
     # @example
     #   @pool.transmit_to_rand("stats", :match => /\n/)
+    #
     def transmit_to_rand(command, options={}, &block)
       safe_transmit do
         conn = connections.respond_to?(:sample) ? connections.sample : connections.choice
@@ -75,23 +112,11 @@ module Beaneater
       end
     end
 
-    # Send command to each beanstalkd servers until getting response expected
-    #
-    # @param [String] command Beanstalkd command
-    # @param [Hash] options telnet connections options
-    # @param [Proc] block Block passed in telnet connection object
+    # Closes all connections within the pool.
     #
     # @example
-    #   @pool.transmit_until_res('peek-ready', :status => "FOUND", &block)
-    def transmit_until_res(command, options={}, &block)
-      status_expected  = options.delete(:status)
-      connections.each do |conn|
-        res = safe_transmit { conn.transmit(command, options, &block) }
-        return res if res[:status] == status_expected
-      end && nil
-    end
-
-    # Closes all connections within pool
+    #  @pool.close
+    #
     def close
       while @connections.any?
         conn = @connections.pop

data/lib/beaneater/pool_command.rb

@@ -14,20 +14,21 @@ module Beaneater
       @pool = pool
     end
 
-    # Delegate to Pool#transmit_to_all and if needed will merge responses from beanstalkd
+    # Delegate to Pool#transmit_to_all and if needed will merge responses from beanstalkd.
     #
     # @param [String] body Beanstalkd command
-    # @param [Hash] options telnet connections options
+    # @param [Hash{String => String, Boolean}] options telnet connections options
     # @option options [Boolean] merge Ask for merging responses or not
     # @param [Proc] block Block passed in telnet connection object
-    #
     # @example
     #   @pool.transmit_to_all("stats")
+    #
     def transmit_to_all(body, options={}, &block)
       merge = options.delete(:merge)
       res = pool.transmit_to_all(body, options, &block)
-      if merge
-        res = { :status => res.first[:status], :body => sum_hashes(res.map { |r| r[:body] }) }
+      first = res.find { |r| r && r[:status] }
+      if first && merge
+        res = { :status => first[:status], :body => sum_items(res.map { |r| r[:body] }) }
       end
       res
     end
@@ -44,17 +45,24 @@ module Beaneater
 
     protected
 
-    # Selects hashes from collection and then merges the individual key values
+    # Selects items from collection and then merges the individual values
+    # Supports array of hashes or array of arrays
     #
-    # @param [Array<Hash>] hs Collection of hash responses returned from beanstalkd
-    # @return [Hash] Merged responses combining values from all the hash bodies
+    # @param [Array<Hash, Array>] hs Collection of responses returned from beanstalkd
+    # @return [Hash{Symbol => String}] Merged responses combining values from all the hash bodies
     # @example
-    #  self.sum_hashes([{ :foo => 1, :bar => 5 }, { :foo => 2, :bar => 3 }])
+    #  self.sum_items([{ :foo => 1, :bar => 5 }, { :foo => 2, :bar => 3 }])
     #    => { :foo => 3, :bar => 8 }
+    #  self.sum_items([['foo', 'bar'], ['foo', 'bar', 'baz']])
+    #    => ['foo', 'bar', 'baz']
     #
-    def sum_hashes(hs)
-      hs.select { |h| h.is_a?(Hash) }.
-        inject({}) { |a,b| a.merge(b) { |k,o,n| combine_stats(k, o, n) } }
+    def sum_items(items)
+      if items.first.is_a?(Hash)
+        items.select { |h| h.is_a?(Hash) }.
+          inject({}) { |a,b| a.merge(b) { |k,o,n| combine_stats(k, o, n) } }
+      elsif items.first.is_a?(Array)
+        items.flatten.uniq
+      end
     end
 
     # Combine two values for given key

data/lib/beaneater/stats/stat_struct.rb

@@ -3,7 +3,7 @@ module Beaneater
   class StatStruct < FasterOpenStruct
     # Convert a stats hash into a struct.
     #
-    # @param [Hash(String => String)] hash Hash Stats hash to convert to struct
+    # @param [Hash{String => String}] hash Hash Stats hash to convert to struct
     # @return [Beaneater::StatStruct, nil] Stats struct from hash
     # @example
     #   s = StatStruct.from_hash(:foo => "bar")
@@ -18,7 +18,7 @@ module Beaneater
     # Access value for stat with specified key.
     #
     # @param [String] key Key to fetch from stats.
-    # @return [String,Integer] Value for specified stat key.
+    # @return [String, Integer] Value for specified stat key.
     # @example
     #  @stats['foo'] # => "bar"
     #

data/lib/beaneater/stats.rb

@@ -10,6 +10,7 @@ module Beaneater
     # @example
     #  @bp.stats.keys # => ["version", "total_connections"]
     #
+    # @api public
     def keys
       data.keys
     end

data/lib/beaneater/tube/collection.rb

@@ -22,6 +22,7 @@ module Beaneater
     #   @pool.tubes['tube2']
     #     # => <Beaneater::Tube name="tube2">
     #
+    # @api public
     def find(tube_name)
       Tube.new(self.pool, tube_name)
     end
@@ -37,6 +38,7 @@ module Beaneater
     #   @conn.tubes.reserve { |job| process(job) }
     #     # => <Beaneater::Job id=5 body="foo">
     #
+    # @api public
     def reserve(timeout=nil, &block)
       res = transmit_to_rand(timeout ? "reserve-with-timeout #{timeout}" : 'reserve')
       job = Job.new(res)
@@ -44,20 +46,6 @@ module Beaneater
       job
     end
 
-    # Set specified tube as used.
-    #
-    # @param [String] tube Tube to be used.
-    # @example
-    #  @conn.tubes.use("some-tube")
-    #
-    def use(tube)
-      return tube if @last_used == tube
-      res = transmit_to_all("use #{tube}")
-      @last_used = tube
-    rescue BadFormatError
-      raise InvalidTubeName, "Tube cannot be named '#{tube}'"
-    end
-
     # List of all known beanstalk tubes.
     #
     # @return [Array<Beaneater::Tube>] List of all beanstalk tubes.
@@ -65,8 +53,9 @@ module Beaneater
     #   @pool.tubes.all
     #     # => [<Beaneater::Tube name="tube2">, <Beaneater::Tube name="tube3">]
     #
+    # @api public
     def all
-      transmit_to_rand('list-tubes')[:body].map { |tube_name| Tube.new(self.pool, tube_name) }
+      transmit_to_all('list-tubes', :merge => true)[:body].map { |tube_name| Tube.new(self.pool, tube_name) }
     end
 
     # List of watched beanstalk tubes.
@@ -76,8 +65,9 @@ module Beaneater
     #   @pool.tubes.watched
     #     # => [<Beaneater::Tube name="tube2">, <Beaneater::Tube name="tube3">]
     #
+    # @api public
     def watched
-      transmit_to_rand('list-tubes-watched')[:body].map { |tube_name| Tube.new(self.pool, tube_name) }
+      transmit_to_all('list-tubes-watched', :merge => true)[:body].map { |tube_name| Tube.new(self.pool, tube_name) }
     end
 
     # Currently used beanstalk tube.
@@ -87,6 +77,7 @@ module Beaneater
     #   @pool.tubes.used
     #     # => <Beaneater::Tube name="tube2">
     #
+    # @api public
     def used
       Tube.new(self.pool, transmit_to_rand('list-tube-used')[:id])
     end
@@ -98,6 +89,7 @@ module Beaneater
     # @example
     #   @pool.tubes.watch('foo', 'bar')
     #
+    # @api public
     def watch(*names)
       names.each do |t|
         transmit_to_all "watch #{t}"
@@ -113,6 +105,7 @@ module Beaneater
     # @example
     #   @pool.tubes.watch!('foo', 'bar')
     #
+    # @api public
     def watch!(*names)
       old_tubes = watched.map(&:name) - names.map(&:to_s)
       watch(*names)
@@ -125,10 +118,25 @@ module Beaneater
     # @example
     #   @pool.tubes.ignore('foo', 'bar')
     #
+    # @api public
     def ignore(*names)
       names.each do |w|
         transmit_to_all "ignore #{w}"
       end
     end
+
+    # Set specified tube as used.
+    #
+    # @param [String] tube Tube to be used.
+    # @example
+    #  @conn.tubes.use("some-tube")
+    #
+    def use(tube)
+      return tube if @last_used == tube
+      res = transmit_to_all("use #{tube}")
+      @last_used = tube
+    rescue BadFormatError
+      raise InvalidTubeName, "Tube cannot be named '#{tube}'"
+    end
   end # Tubes
 end # Beaneater

data/lib/beaneater/tube/record.rb

@@ -28,11 +28,11 @@ module Beaneater
     # Inserts job with specified body onto tube.
     #
     # @param [String] body The data to store with this job.
-    # @param [Hash] options The settings associated with this job.
+    # @param [Hash{String => Integer}] options The settings associated with this job.
     # @option options [Integer] pri priority for this job
     # @option options [Integer] ttr time to respond for this job
     # @option options [Integer] delay delay for this job
-    # @return [Hash] beanstalkd command response
+    # @return [Hash{String => String, Number}] beanstalkd command response
     # @example
     #   @tube.put "data", :pri => 1000, :ttr => 10, :delay => 5
     #
@@ -71,6 +71,7 @@ module Beaneater
     # @example
     #  @tube.reserve # => <Beaneater::Job id=5 body=foo>
     #
+    # @api public
     def reserve(timeout=nil, &block)
       pool.tubes.watch!(self.name)
       pool.tubes.reserve(timeout, &block)
@@ -79,10 +80,11 @@ module Beaneater
     # Kick specified number of jobs from buried to ready state.
     #
     # @param [Integer] bounds The number of jobs to kick.
-    # @return [Hash] Beanstalkd command response
+    # @return [Hash{String => String, Number}] Beanstalkd command response
     # @example
     #   @tube.kick(5)
     #
+    # @api public
     def kick(bounds=1)
       safe_use { transmit_to_rand("kick #{bounds}") }
     end
@@ -93,6 +95,7 @@ module Beaneater
     # @example
     #  @tube.stats.delayed # => 24
     #
+    # @api public
     def stats
       res = transmit_to_all("stats-tube #{name}", :merge => true)
       StatStruct.from_hash(res[:body])
@@ -101,10 +104,11 @@ module Beaneater
     # Pause the execution of this tube for specified `delay`.
     #
     # @param [Integer] delay Number of seconds to delay tube execution
-    # @return [Hash] Beanstalkd command response
+    # @return [Array<Hash{String => String, Number}>] Beanstalkd command response
     # @example
     #   @tube.pause(10)
     #
+    # @api public
     def pause(delay)
       transmit_to_all("pause-tube #{name} #{delay}")
     end

data/lib/beaneater/version.rb

@@ -1,4 +1,4 @@
 module Beaneater
   # Current version of gem.
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/beaneater.rb

@@ -4,7 +4,6 @@ require 'net/telnet'
   require "beaneater/#{f}"
 end
 
-# Simple ruby client for beanstalkd.
 module Beaneater
-
+  # Simple ruby client for beanstalkd.
 end

data/test/beaneater_test.rb

@@ -3,6 +3,7 @@ require File.expand_path('../test_helper', __FILE__)
 describe "beanstalk-client" do
   before do
     @beanstalk = Beaneater::Pool.new(['127.0.0.1:11300'])
+    # @beanstalk = Beaneater::Pool.new(['127.0.0.1:11300', '127.0.0.1:11301'])
     @tubes = ['one', 'two', 'three']
 
     # Put something on each tube so they exist

data/test/job_test.rb

@@ -207,6 +207,44 @@ describe Beaneater::Job do
     end
   end # tube
 
+  describe "for #pri" do
+    before do
+      @tube.put 'bar', :pri => 1
+      @job = @tube.peek(:ready)
+    end
+
+    it("should return pri") do
+      job = @tube.reserve
+      assert_equal 1, job.pri
+      job.release
+    end
+  end # tube
+
+
+  describe "for #ttr" do
+    before do
+      @tube.put 'bar', :ttr => 5
+      @job = @tube.peek(:ready)
+    end
+
+    it("should return ttr") do
+      job = @tube.reserve
+      assert_equal 5, job.ttr
+      job.release
+    end
+  end # tube
+
+  describe "for #delay" do
+    before do
+      @tube.put 'bar', :delay => 5
+      @job = @tube.peek(:delayed)
+    end
+
+    it("should return delay") do
+      assert_equal 5, @job.delay
+    end
+  end # tube
+
   after do
     cleanup_tubes!(['tube'])
   end

data/test/jobs_test.rb

@@ -33,6 +33,30 @@ describe Beaneater::Jobs do
     end
   end # find
 
+  describe "for #find_all" do
+    before do
+      @time = Time.now.to_i
+      @tube.put("foo find #{@time}")
+      @job = @tube.peek(:ready)
+    end
+
+      it "should return job from id" do
+        assert_equal "foo find #{@time}", @jobs.find_all(@job.id).first.body
+      end
+
+      it "should return job using peek" do
+        assert_equal "foo find #{@time}", @jobs.find_all(@job.id).first.body
+      end
+
+      it "should return job using hash syntax" do
+        assert_equal "foo find #{@time}", @jobs.find_all(@job.id).first.body
+      end
+
+      it "should return nil for invalid id" do
+        assert_equal [], @jobs.find_all(-1)
+      end
+  end # find_all
+
   describe "for #register!" do
     before do
       $foo = 0

data/test/pool_command_test.rb

@@ -18,27 +18,49 @@ describe Beaneater::PoolCommand do
   describe 'for #transmit_to_all' do
     describe 'for regular command' do
       before do
-        @pool = stub(:transmit_to_all => "OK")
+        @pool = stub(:transmit_to_all => [{ :body => "foo", :status => "OK" }])
         @command = Beaneater::PoolCommand.new(@pool)
       end
 
       it "can run regular command" do
-        assert_equal "OK", @command.transmit_to_all("foo")
+        res = @command.transmit_to_all("foo")
+        assert_equal "OK", res[0][:status]
+        assert_equal "foo", res[0][:body]
       end
     end # regular command
 
-    describe 'for merged command' do
+    describe 'for merge command with hashes' do
       before do
-        @pool = stub(:transmit_to_all => [{ :body => { 'x' => 1, 'version' => 1.1 }}, {:body => { 'x' => 3,'version' => 1.2 }}])
+        @pool = stub(:transmit_to_all => [
+          { :body => { 'x' => 1, 'version' => 1.1 }, :status => "OK"},
+          { :body => { 'x' => 3,'version' => 1.2 }, :status => "OK" }
+        ])
         @command = Beaneater::PoolCommand.new(@pool)
       end
 
-      it "can run merge command" do
+      it "can run merge command " do
         cmd = @command.transmit_to_all("bar", :merge => true)
+        assert_equal "OK", cmd[:status]
         assert_equal 4, cmd[:body]['x']
         assert_equal Set[1.1, 1.2], cmd[:body]['version']
       end
     end # merged command
+
+    describe 'for merge command with arrays' do
+      before do
+        @pool = stub(:transmit_to_all => [
+          { :body => ['foo', 'bar'], :status => "OK"},
+          { :body => ['foo', 'bar', 'baz'], :status => "OK" }
+        ])
+        @command = Beaneater::PoolCommand.new(@pool)
+      end
+
+      it "can run merge command " do
+        cmd = @command.transmit_to_all("bar", :merge => true)
+        assert_equal "OK", cmd[:status]
+        assert_equal ['foo', 'bar', 'baz'].sort, cmd[:body].sort
+      end
+    end # merged command
   end # transmit_to_all
 
   describe 'for #method_missing' do

data/test/stats_test.rb

@@ -4,7 +4,8 @@ require File.expand_path('../test_helper', __FILE__)
 
 describe Beaneater::Stats do
   before do
-    @pool =  stub(:transmit_to_all => [{ :body => { 'uptime' => 1, 'cmd-use' => 2 }}, {:body => { 'uptime' => 3,'cmd-use' => 4 }}])
+    @pool =  stub(:transmit_to_all => [{ :body => { 'uptime' => 1, 'cmd-use' => 2 }, :status => "OK"},
+      {:body => { 'uptime' => 3,'cmd-use' => 4 }, :status => "OK" }])
     @stats = Beaneater::Stats.new(@pool)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: beaneater
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-02 00:00:00.000000000 Z
+date: 2012-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -100,10 +100,10 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .yardopts
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
-- REF
 - Rakefile
 - TODO
 - beaneater.gemspec
@@ -147,18 +147,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -2674763772608009517
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -2674763772608009517
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24

data/REF

@@ -1,23 +0,0 @@
-# Summary of what this does
-#
-# @!attribute [r] count
-# @param [type] Name description
-# @option name [Types] option_key (default_value) description
-# @yield [a, b, c] Gives 3 random numbers to the block
-# @return [type] description
-# @raise [Types] description
-# @example
-#  something.foo # => "test"
-#
-
-
-# Summary of what this does
-#
-# @param [type] Name description
-# @option name [Types] option_key (default_value) description
-# @yield [a, b, c] Gives 3 random numbers to the block
-# @return [type] description
-# @raise [Types] description
-# @example
-#  something.foo # => "test"
-#