beaneater 0.1.0

data/REF

@@ -0,0 +1,23 @@
+# 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"
+#

data/Rakefile

@@ -0,0 +1,23 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+require 'yard'
+require 'redcarpet'
+
+Rake::TestTask.new do |t|
+  t.libs.push "lib"
+  t.test_files = FileList[File.expand_path('../test/**/*_test.rb', __FILE__)] -
+    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"
+  t.test_files = FileList[File.expand_path('../test/**/*_test.rb', __FILE__)]
+  t.verbose = true
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/beaneater/**/*.rb']
+  t.options = []
+end

data/TODO

@@ -0,0 +1,2 @@
+- 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/beaneater.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'beaneater/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "beaneater"
+  gem.version       = Beaneater::VERSION
+  gem.authors       = ["Nico Taing"]
+  gem.email         = ["nico.taing@gmail.com"]
+  gem.description   = %q{Simple beanstalkd client for ruby}
+  gem.summary       = %q{Simple beanstalkd client for ruby.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  gem.add_development_dependency 'minitest', "~> 4.1.0"
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'mocha'
+  gem.add_development_dependency 'fakeweb'
+  gem.add_development_dependency 'term-ansicolor'
+end

data/examples/demo.rb

@@ -0,0 +1,96 @@
+require 'term/ansicolor'
+class String; include Term::ANSIColor; end
+def step(msg); "\n[STEP] #{msg}...".yellow; end
+$:.unshift("../lib")
+require 'beaneater'
+
+# Establish a pool of beanstalks
+puts step("Connecting to Beanstalk")
+bc = Beaneater::Pool.new('localhost')
+# bc = Beaneater::Pool.new(['localhost', 'localhost:11301', 'localhost:11302'])
+puts bc
+
+# Print out key stats
+puts step("Print Stats")
+p bc.stats.keys
+p [bc.stats.total_connections, bc.stats[:total_connections], bc.stats['total_connections']]
+
+# find tube
+puts step("Find tube")
+tube = bc.tubes.find('tube2')
+puts tube
+
+# Put job onto tube
+puts step("Put job")
+response = tube.put "foo bar", :pri => 1000, :ttr => 10, :delay => 0
+puts response
+
+# peek tube
+puts step("Peek tube")
+p tube.peek :ready
+
+# watch tube
+bc.tubes.watch!('tube2')
+
+# Check tube stats
+puts step("Get tube stats")
+p tube.stats.keys
+p tube.stats.name
+p tube.stats.current_jobs_ready
+
+# Reserve job from tube
+puts step("Reserve job")
+p job = bc.tubes.reserve
+jid = job.id
+
+# pause tube
+puts step("Pause tube")
+p tube.pause(1)
+
+# Register jobs
+puts step("Register jobs for tubes")
+bc.jobs.register('tube_test', :retry_on => [Timeout::Error]) do |job|
+ p 'tube_test'
+ p job
+ raise Beaneater::AbortProcessingError
+end
+
+bc.jobs.register('tube_test2', :retry_on => [Timeout::Error]) do |job|
+ p 'tube_test2'
+ p job
+ raise Beaneater::AbortProcessingError
+end
+
+p bc.jobs.processors
+
+response = bc.tubes.find('tube_test').put "foo register", :pri => 1000, :ttr => 10, :delay => 0
+response = bc.tubes.find('tube_test2').put "foo baz", :pri => 1000, :ttr => 10, :delay => 0
+
+# Process jobs
+puts step("Process jobs")
+2.times { bc.jobs.process! }
+
+# Get job from id (peek job)
+puts step("Get job from id")
+p bc.jobs.find(jid)
+p bc.jobs.peek(jid)
+
+# Check job stats
+puts step("Get job stats")
+p job.stats.keys
+p job.stats.tube
+p job.stats.state
+
+# bury job
+puts step("Bury job")
+p job.bury
+
+# delete job
+puts step("Delete job")
+p job.delete
+
+# list tubes
+puts step("List tubes")
+p bc.tubes.watched
+p bc.tubes.used
+p bc.tubes.all

data/lib/beaneater.rb

@@ -0,0 +1,10 @@
+require 'net/telnet'
+
+%w(version errors pool_command pool connection stats tube job).each do |f|
+  require "beaneater/#{f}"
+end
+
+# Simple ruby client for beanstalkd.
+module Beaneater
+
+end

data/lib/beaneater/connection.rb

@@ -0,0 +1,110 @@
+require 'yaml'
+
+module Beaneater
+  # Represents a connection to beanstalkd server
+  class Connection
+
+    # @!attribute telnet_connection
+    #   @return [Net::Telnet] returns Telnet connection object
+    # @!attribute address
+    #   @return [String] returns Beanstalkd server address
+    # @!attribute host
+    #   @return [String] returns Beanstalkd server host
+    # @!attribute port
+    #  @return [Integer] returns Beanstalkd server port
+    attr_reader :telnet_connection, :address, :host, :port
+
+    # Default port value
+    DEFAULT_PORT = 11300
+
+    # Initialize new connection
+    #
+    # @param [String] address beanstalkd 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
+    #
+    # @param [String] command Beanstalkd command
+    # @param [Hash] options Settings for telnet
+    # @option options [Boolean] FailEOF raises EOF Exeception
+    #
+    # @example
+    #   @beaneater_connection.transmit('bury 123')
+    def transmit(command, options={}, &block)
+      @mutex.lock
+      if telnet_connection
+        options.merge!("String" => command, "FailEOF" => true)
+        parse_response(command, telnet_connection.cmd(options, &block))
+      else # no telnet_connection
+        raise NotConnected, "Connection to beanstalk '#{@host}:#{@port}' is closed!" unless telnet_connection
+      end
+    ensure
+      @mutex.unlock
+    end
+
+    # Close connection with beanstalkd server
+    #
+    # @example
+    #  @beaneater_connection.close
+    def close
+      @telnet_connection.close
+      @telnet_connection = nil
+    end
+
+    # Returns string representation of job
+    #
+    # @example
+    #  @beaneater_connection.inspect
+    def to_s
+      "#<Beaneater::Connection host=#{host.inspect} port=#{port.inspect}>"
+    end
+    alias :inspect :to_s
+
+    protected
+
+    # Establish a telnet connection based on beanstalk address.
+    #
+    # @return [Net::Telnet] telnet connection for specified address.
+    # @raise [Beanstalk::NotConnected] Could not connect to specified beanstalkd instance.
+    # @example
+    #  establish_connection('localhost:3005')
+    #
+    def establish_connection
+      @match = address.split(':')
+      @host, @port = @match[0], Integer(@match[1] || DEFAULT_PORT)
+      Net::Telnet.new('Host' => @host, "Port" => @port, "Prompt" => /\n/)
+    rescue Errno::ECONNREFUSED => e
+      raise NotConnected, "Could not connect to '#{@host}:#{@port}'"
+    rescue Exception => ex
+      raise NotConnected, "#{ex.class}: #{ex}"
+    end
+
+    # Parses the telnet response and returns the useful beanstalk response.
+    #
+    # @param [String] cmd Beanstalk command transmitted
+    # @param [String] res Telnet command response
+    # @return [Hash] Beanstalk command 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")
+    #   # => { :body => "FOO", :status => "DELETED", :id => 56, :connection => <Connection>  }
+    #
+    def parse_response(cmd, res)
+      res_lines = res.split(/\r?\n/)
+      status = res_lines.first
+      status, id = status.scan(/\w+/)
+      raise UnexpectedResponse.from_status(status, cmd) if UnexpectedResponse::ERROR_STATES.include?(status)
+      response = { :status => status, :body => YAML.load(res_lines[1..-1].join("\n")) }
+      response[:id] = id if id
+      response[:connection] = self
+      response
+    end
+  end # Connection
+end # Beaneater

data/lib/beaneater/errors.rb

@@ -0,0 +1,73 @@
+module Beaneater
+  # Raises when the beanstalkd instance cannot be accessed
+  class NotConnected < RuntimeError; end
+  # Raises when the tube name specified is invalid.
+  class InvalidTubeName < RuntimeError; end
+  # Raises when a job has not been reserved properly.
+  class JobNotReserved < RuntimeError; end
+
+  # Abstract class for errors that occur when a command does not complete successfully.
+  class UnexpectedResponse < RuntimeError
+    # Set of status states that are considered errors
+    ERROR_STATES = %w(OUT_OF_MEMORY INTERNAL_ERROR
+      BAD_FORMAT UNKNOWN_COMMAND JOB_TOO_BIG DRAINING
+      TIMED_OUT DEADLINE_SOON NOT_FOUND NOT_IGNORED EXPECTED_CRLF)
+
+    # @!attribute status
+    #   @return [String] returns beanstalkd response status
+    # @!attribute cmd
+    #   @return [String] returns beanstalkd request command
+    attr_reader :status, :cmd
+
+    # Initialize unexpected response error
+    #
+    # @param [UnexpectedResponse] status Unexpected response object
+    # @param [String] cmd Beanstalkd request command
+    #
+    # @example
+    #   Beaneater::UnexpectedResponse.new(NotFoundError, 'bury 123')
+    #
+    def initialize(status, cmd)
+      @status, @cmd = status, cmd
+      super("Response failed with: #{status}")
+    end
+
+    # Translate beanstalkd error status to ruby Exeception
+    #
+    # @param [String] status Beanstalkd error status
+    # @param [String] cmd Beanstalkd request command
+    #
+    # @example
+    #   Beaneater::UnexpectedResponse.new('NOT_FOUND', 'bury 123')
+    #
+    def self.from_status(status, cmd)
+      error_klazz_name = status.split('_').map { |w| w.capitalize }.join
+      error_klazz_name << "Error" unless error_klazz_name =~ /Error$/
+      error_klazz = Beaneater.const_get(error_klazz_name)
+      error_klazz.new(status, cmd)
+    end
+  end
+
+  # Raises when the beanstalkd instance runs out of memory
+  class OutOfMemoryError < UnexpectedResponse; end
+  # Raises when the beanstalkd instance is draining and new jobs cannot be inserted
+  class DrainingError < UnexpectedResponse; end
+  # Raises when the job or tube cannot be found
+  class NotFoundError < UnexpectedResponse; end
+  # Raises when the job reserved is going to be released within a second.
+  class DeadlineSoonError < UnexpectedResponse; end
+  # Raises when a beanstalkd has an internal error.
+  class InternalError < UnexpectedResponse; end
+  # Raises when a command was not properly formatted.
+  class BadFormatError < UnexpectedResponse; end
+  # Raises when a command was sent that is unknown.
+  class UnknownCommandError < UnexpectedResponse; end
+  # Raises when command does not have proper CRLF suffix.
+  class ExpectedCRLFError < UnexpectedResponse; end
+  # Raises when the body of a job was too large.
+  class JobTooBigError < UnexpectedResponse; end
+  # Raises when a job was attempted to be reserved but the timeout occured.
+  class TimedOutError < UnexpectedResponse; end
+  # Raises when a tube could not be ignored because it is the last watched tube.
+  class NotIgnoredError < UnexpectedResponse; end
+end

data/lib/beaneater/job.rb

@@ -0,0 +1,2 @@
+require 'beaneater/job/record'
+require 'beaneater/job/collection'

data/lib/beaneater/job/collection.rb

@@ -0,0 +1,91 @@
+module Beaneater
+  # Exception to stop processing jobs
+  class AbortProcessingError < RuntimeError; end
+
+  # Represents collection of jobs 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
+    MAX_RETRIES = 3
+
+    # 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
+    #
+    # @example
+    #   @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)
+      res = transmit_until_res("peek #{id}", :status => "FOUND")
+      Job.new(res)
+    rescue Beaneater::NotFoundError => ex
+      nil
+    end
+    alias_method :peek, :find
+    alias_method :[], :find
+
+    # Add processor to handle beanstalkd job
+    #
+    # @param [String] tube_name Tube name
+    # @param [Hash] options settings for processor
+    # @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|
+    #     do_something(job)
+    #   end
+    #
+    #   @beanstalk.jobs.register('other-tube') do |job|
+    #     do_something_else(job)
+    #   end
+    #
+    # @api public
+    def register(tube_name, options={}, &block)
+      @processors ||= {}
+      max_retries = options[:max_retries] || MAX_RETRIES
+      retry_on = Array(options[:retry_on])
+      @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
+    #
+    # @param [Hash] options Settings for processing
+    # @option options [Integer] Delay in seconds before to make job ready again
+    #
+    # @api public
+    def process!(options={})
+      release_delay = options.delete(:release_delay) || RELEASE_DELAY
+      tubes.watch!(*processors.keys)
+      loop do
+        job = tubes.reserve
+        processor = processors[job.tube]
+        begin
+          processor[:block].call(job)
+          job.delete
+        rescue AbortProcessingError
+          break
+        rescue *processor[:retry_on]
+          job.release(:delay => release_delay) if job.stats.releases < processor[:max_retries]
+        rescue StandardError => e # handles unspecified errors
+          job.bury
+        ensure # bury if still reserved
+          job.bury if job.exists? && job.reserved?
+        end
+      end
+    end # process!
+  end # Jobs
+end # Beaneater