stalk_climber 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,19 @@
+language: ruby
+
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+
+before_install:
+  - sudo apt-get update -qq
+  - sudo apt-get install -qq beanstalkd
+  - sudo sed -i 's/#START=yes/START=yes/' /etc/default/beanstalkd
+  - sudo service beanstalkd start
+  - cat /etc/init.d/beanstalkd | sed 's/NAME=beanstalkd/NAME=beanstalkd2/' | sudo tee /etc/init.d/beanstalkd2 2>&1>/dev/null
+  - cat /etc/default/beanstalkd | sed 's/11300/11301/' | sudo tee /etc/default/beanstalkd2 2>&1>/dev/null
+  - sudo chmod +x /etc/init.d/beanstalkd2
+  - sudo service beanstalkd2 start
+
+env:
+  - BEANSTALK_ADDRESSES='beanstalk://localhost:11300,beanstalk://localhost:11301'

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'debugger', :group => [:development, :test]
+
+group :test do
+  gem 'coveralls', :require => false
+  gem 'mocha', :require => false
+end

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Freewrite.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,15 @@
+# StalkClimber
+[![Build Status](https://secure.travis-ci.org/freewrite/stalk_climber.png)](http://travis-ci.org/freewrite/stalk_climber)
+[![Dependency Status](https://gemnasium.com/freewrite/stalk_climber.png)](https://gemnasium.com/freewrite/stalk_climber)
+[![Coverage Status](https://coveralls.io/repos/freewrite/stalk_climber/badge.png?branch=master)](https://coveralls.io/r/freewrite/stalk_climber)
+[![Code Climate](https://codeclimate.com/github/freewrite/stalk_climber.png)](https://codeclimate.com/github/freewrite/stalk_climber)
+
+StalkClimber is a Ruby library allowing improved sequential access to Beanstalk via a job cache.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task :default => :test

data/lib/stalk_climber/climber.rb

@@ -0,0 +1,38 @@
+module StalkClimber
+  class Climber
+    include LazyEnumerable
+
+    attr_accessor :beanstalk_addresses, :test_tube
+    attr_reader :cache
+
+    # Returns or creates a ConnectionPool from beanstalk_addresses
+    def connection_pool
+      return @connection_pool unless @connection_pool.nil?
+      if self.beanstalk_addresses.nil?
+        raise RuntimeError, 'beanstalk_addresses must be set in order to establish a connection'
+      end
+      @connection_pool = ConnectionPool.new(self.beanstalk_addresses)
+    end
+
+
+    # Perform a threaded climb across all connections in the connection pool.
+    # An instance of Job is yielded to +block+
+    def climb(&block)
+      threads = []
+      self.connection_pool.connections.each do |connection|
+        threads << Thread.new { connection.each(&block) }
+      end
+      threads.each(&:join)
+      return
+    end
+    alias_method :each, :climb
+
+
+    # Creates a new Climber instance, optionally yielding the instance
+    # if a block is given
+    def initialize
+      yield(self) if block_given?
+    end
+
+  end
+end

data/lib/stalk_climber/connection.rb

@@ -0,0 +1,143 @@
+module StalkClimber
+  class Connection < Beaneater::Connection
+    include LazyEnumerable
+
+    DEFAULT_TUBE = 'stalk_climber'
+    PROBE_TRANSMISSION = "put 4294967295 0 300 2\r\n{}"
+
+    attr_accessor :test_tube
+    attr_reader :max_climbed_job_id, :min_climbed_job_id
+
+
+    # Returns or creates a Hash used for caching jobs by ID
+    def cache
+      return @cache ||= {}
+    end
+
+
+    # Resets the job cache and reinitializes the min and max climbed job ids
+    def clear_cache
+      @cache = nil
+      @min_climbed_job_id = Float::INFINITY
+      @max_climbed_job_id = 0
+    end
+
+
+    # Handles job enumeration in descending ID order, passing an instance of Job to +block+ for
+    # each existing job on the beanstalk server. Jobs are enumerated in three phases. Jobs between
+    # max_job_id and the max_climbed_job_id are pulled from beanstalk, cached, and given to
+    # +block+. Jobs that have already been cached are yielded to +block+ if they still exist,
+    # otherwise they are deleted from the cache. Finally, jobs between min_climbed_job_id and 1
+    # are pulled from beanstalk, cached, and given to +block+.
+    # Connection#each fulfills Enumberable contract, allowing connection to behave as an Enumerable.
+    def each(&block)
+      climb(&block)
+    end
+
+
+    # Initializes a new Connection to the beanstalk +address+ provided and
+    # configures the Connection to only use the configured test_tube for
+    # all transmissions.
+    # Optionally yields the instance if a block is given. The instance is yielded
+    # prior to test_tube configuration to allow the test_tube to be configured.
+    def initialize(address)
+      super
+      self.test_tube = DEFAULT_TUBE
+      clear_cache
+      yield(self) if block_given?
+      [
+        "use #{self.test_tube}",
+        "watch #{self.test_tube}",
+        'ignore default',
+      ].each do |transmission|
+        transmit(transmission)
+      end
+    end
+
+
+    # Determintes the max job ID of the connection by inserting a job into the test tube
+    # and immediately deleting it. Before returning the max ID, the max ID is used to
+    # update the max_climbed_job_id (if sequentual) and possibly invalidate the cache.
+    # The cache will be invalidated if the max ID is less than any known IDs since
+    # new job IDs should always increment unless there's been a change in server state.
+    def max_job_id
+      job = Job.new(transmit(PROBE_TRANSMISSION))
+      job.delete
+      update_climbed_job_ids_from_max_id(job.id)
+      return job.id
+    end
+
+
+    # Safe form of with_job!, yields a Job instance to +block+ for the specified +job_id+.
+    # If the job does not exist, the error is caught and nil is passed to +block+ instead.
+    def with_job(job_id, &block)
+      begin
+        with_job!(job_id, &block)
+      rescue Beaneater::NotFoundError
+        block.call(nil)
+      end
+    end
+
+
+    # Yields a Job instance to +block+ for the specified +job_id+.
+    # If the job does not exist, a Beaneater::NotFoundError will bubble up from Beaneater.
+    def with_job!(job_id, &block)
+      job = Job.new(transmit("peek #{job_id}"))
+      block.call(job)
+    end
+
+
+    protected
+
+    # Helper method, similar to with_job, that retrieves the job identified by
+    # +job_id+, caches it, and  updates counters before yielding the job.
+    # If the job does not exist, +block+ is not called and nothing is cached,
+    # however counters will be updated.
+    def cache_job_and_yield(job_id, &block)
+      with_job(job_id) do |job|
+        self.cache[job_id] = job unless job.nil?
+        @min_climbed_job_id = job_id if job_id < @min_climbed_job_id
+        @max_climbed_job_id = job_id if job_id > @max_climbed_job_id
+        yield(job) unless job.nil?
+      end
+    end
+
+
+    # Handles job enumeration. See Connection#each for more information.
+    def climb(&block)
+      max_id = max_job_id
+
+      initial_cached_jobs = cache.values_at(*cache.keys.sort.reverse)
+
+      max_id.downto(self.max_climbed_job_id + 1) do |job_id|
+        cache_job_and_yield(job_id, &block)
+      end
+
+      initial_cached_jobs.each do |job|
+        if job.exists?
+          yield job
+        else
+          self.cache.delete(job.id)
+        end
+      end
+
+      ([self.min_climbed_job_id - 1, max_id].min).downto(1) do |job_id|
+        cache_job_and_yield(job_id, &block)
+      end
+      return
+    end
+
+
+    # Uses +new_max_id+ to update the max_climbed_job_id (if sequentual) and possibly invalidate
+    # the cache. The cache will be invalidated if +new_max_id+ is less than any known IDs since
+    # new job IDs should always increment unless there's been a change in server state.
+    def update_climbed_job_ids_from_max_id(new_max_id)
+      if @max_climbed_job_id > 0 && @max_climbed_job_id == new_max_id - 1
+        @max_climbed_job_id = new_max_id
+      elsif new_max_id < @max_climbed_job_id
+        clear_cache
+      end
+    end
+
+  end
+end

data/lib/stalk_climber/connection_pool.rb

@@ -0,0 +1,30 @@
+module StalkClimber
+  class ConnectionPool < Beaneater::Pool
+
+    class InvalidURIScheme < RuntimeError; end
+
+    attr_reader :addresses
+
+    # Constructs a Beaneater::Pool from a less strict URL
+    # +url+ can be a string i.e 'localhost:11300' or an array of addresses.
+    def initialize(addresses = nil)
+      @addresses = Array(parse_addresses(addresses) || host_from_env || Beaneater.configuration.beanstalkd_url)
+      @connections = @addresses.map { |address| Connection.new(address) }
+    end
+
+
+    protected
+
+    # Parses the given url into a collection of beanstalk addresses
+    def parse_addresses(addresses)
+      return if addresses.empty?
+      uris = addresses.is_a?(Array) ? addresses.dup : addresses.split(/[\s,]+/)
+      uris.map! do |uri_string|
+        uri = URI.parse(uri_string)
+        raise(InvalidURIScheme, "Invalid beanstalk URI: #{uri_string}") unless uri.scheme == 'beanstalk'
+        "#{uri.host}:#{uri.port || 11300}"
+      end
+    end
+
+  end
+end

data/lib/stalk_climber/job.rb

@@ -0,0 +1,179 @@
+module StalkClimber
+  class Job
+
+    STATS_ATTRIBUTES = %w[age buries delay kicks pri releases reserves state time-left timeouts ttr tube]
+    attr_reader :id
+
+    STATS_ATTRIBUTES.each do |method_name|
+      define_method method_name do |force_refresh = false|
+        return stats(force_refresh)[method_name]
+      end
+    end
+
+
+    # Returns or fetches the body of the job obtained via the peek command
+    def body
+      return @body ||= connection.transmit("peek #{id}")[:body]
+    end
+
+
+    # Returns the connection provided by the job data given to the initialize method
+    def connection
+      return @connection
+    end
+
+
+    # Deletes the job from beanstalk. If the job is not found it is assumed that it
+    # has already been otherwise deleted.
+    def delete
+      begin
+        @connection.transmit("delete #{id}")
+      rescue Beaneater::NotFoundError
+      end
+      @status = 'DELETED'
+      @stats = nil
+      @body = nil
+      return true
+    end
+
+
+    # Determines if a job exists by retrieving stats for the job. If Beaneater can't find
+    # the jobm then it does not exist and false is returned. The stats command is used
+    # because it will return a response of a near constant size, whereas, depending on
+    # the job, the peek command could return a much larger response. Rather than waste
+    # the trip to the server, stats are updated each time the method is called.
+    def exists?
+      begin
+        stats(:force_refresh)
+        return true
+      rescue Beaneater::NotFoundError
+        return false
+      end
+    end
+
+
+    # Initializes a Job instance using +job_data+ which should be the Beaneater response to either
+    # a put, peek, or stats-job command. Other Beaneater responses are not supported.
+    #
+    # No single beanstalk command provides all the data an instance might need, so as more
+    # information is required, additional calls are made to beanstalk. For example, accessing both
+    # a job's tube and its body requires both a peek and stats-job call.
+    #
+    # Put provides only the ID of the job and as such yields the least informed instance. Both a
+    # peek and stats-job call may be required to retrieve anything but the ID of the instance
+    #
+    # Peek provides the ID and body of the job. A stats-job call may be required to access anything
+    # but the ID or body of the job.
+    #
+    # Stats-job provides the most information about the job, but lacks the crtical component of the
+    # job body. As such, a peek call would be required to access the body of the job.
+    def initialize(job_data)
+      case job_data[:status]
+      when 'INSERTED' # put
+        @id = job_data[:id].to_i
+        @body = @stats = nil
+      when 'FOUND' # peek
+        @id = job_data[:id].to_i
+        @body = job_data[:body]
+        @stats = nil
+      when 'OK' # stats-job
+        @body = nil
+        @stats = job_data.delete(:body)
+        @id = @stats.delete('id').to_i
+      else
+        raise RuntimeError, "Unexpected job status: #{job_data[:status]}"
+      end
+      @status = job_data[:status]
+      @connection = job_data[:connection]
+    end
+
+
+    # Returns or retrieves stats for the job. Optionally, a retrieve may be forced
+    # by passing a non-false value for +force_refresh+
+    def stats(force_refresh = false)
+      return @stats unless @stats.nil? || force_refresh
+      @stats = connection.transmit("stats-job #{id}")[:body]
+      @stats.delete('id')
+      return @stats
+    end
+
+
+    # :method: age
+    # Retrieves the age of the job from the job's stats. Passing a non-false value for
+    # +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   age(force_refresh = false)
+
+    # :method: buries
+    # Retrieves the number of times the job has been buried from the job's stats. Passing
+    # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   buries(force_refresh = false)
+
+    # :method: delay
+    # Retrieves the the remaining delay before the job is ready from the job's stats. Passing
+    # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   delay(force_refresh = false)
+
+    # :method: kicks
+    # Retrieves the number of times the job has been kicked from the job's stats. Passing
+    # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   kicks(force_refresh = false)
+
+    # :method: pri
+    # Retrieves the priority of the job from the job's stats. Passing a non-false value for
+    # +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   pri(force_refresh = false)
+
+    # :method: releases
+    # Retrieves the number of times the job has been released from the job's stats. Passing
+    # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   releases(force_refresh = false)
+
+    # :method: reserves
+    # Retrieves the number of times the job has been reserved from the job's stats. Passing
+    # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   reserves(force_refresh = false)
+
+    # :method: state
+    # Retrieves the state of the job from the job's stats. Value will be one of "ready",
+    # "delayed", "reserved", or "buried". Passing a non-false value for +force_refresh+
+    # will force retrieval of updated stats for the job
+    # :call-seq:
+    #   timeouts(force_refresh = false)
+
+    # :method: time-left
+    # Retrieves the number of seconds left until the server puts this job into the ready
+    # queue. This number is only meaningful if the job is reserved or delayed. If the job
+    # is reserved and this amount of time elapses before its state changes, it is considered
+    # to have timed out. Passing a non-false value for +force_refresh+ will force retrieval
+    # of updated stats for the job
+    # :call-seq:
+    #   timeouts(force_refresh = false)
+
+    # :method: timeouts
+    # Retrieves the number of times the job has timed out from the job's stats. Passing
+    # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   timeouts(force_refresh = false)
+
+    # :method: ttr
+    # Retrieves the time to run for the job, the number of seconds a worker is allowed to work
+    # to run the job. Passing a non-false value for +force_refresh+ will force retrieval of
+    # updated stats for the job
+    # :call-seq:
+    #   timeouts(force_refresh = false)
+
+    # :method: tube
+    # Retrieves the name of the tube that contains job. Passing a non-false value for
+    # +force_refresh+ will force retrieval of updated stats for the job
+    # :call-seq:
+    #   timeouts(force_refresh = false)
+
+  end
+end

data/lib/stalk_climber/lazy_enumerable.rb

@@ -0,0 +1,15 @@
+module StalkClimber
+  module LazyEnumerable
+    include Enumerable
+
+    def self.make_lazy(*methods)
+      methods.each do |method|
+        define_method method do |*args, &block|
+          lazy.public_send(method, *args, &block)
+        end
+      end
+    end
+
+    make_lazy(*(Enumerable.public_instance_methods - [:lazy]))
+  end
+end

data/lib/stalk_climber/version.rb

@@ -0,0 +1,3 @@
+module StalkClimber
+  VERSION = '0.0.1'
+end

data/lib/stalk_climber.rb

@@ -0,0 +1,9 @@
+module StalkClimber; end
+
+require 'beaneater'
+require 'stalk_climber/version'
+require 'stalk_climber/lazy_enumerable'
+require 'stalk_climber/connection'
+require 'stalk_climber/connection_pool'
+require 'stalk_climber/climber'
+require 'stalk_climber/job'

data/stalk_climber.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stalk_climber/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'stalk_climber'
+  spec.version       = StalkClimber::VERSION
+  spec.authors       = ['Freewrite.org']
+  spec.email         = ['dev@freewrite.org']
+  spec.description   = %q{Improved sequential access to Beanstalk}
+  spec.summary       = %q{StalkClimber is a Ruby library allowing improved sequential access to Beanstalk via a job cache.}
+  spec.homepage      = 'https://github.com/freewrite/stalk_climber'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^test/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+
+  spec.add_dependency 'beaneater'
+end

data/test/test_helper.rb

@@ -0,0 +1,24 @@
+require 'debugger'
+require 'coveralls'
+Coveralls.wear!
+
+lib = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'test/unit'
+require 'mocha/setup'
+
+require 'stalk_climber'
+
+BEANSTALK_ADDRESS = ENV['BEANSTALK_ADDRESS'] || 'beanstalk://localhost'
+BEANSTALK_ADDRESSES = ENV['BEANSTALK_ADDRESSES'] || BEANSTALK_ADDRESS
+
+class Test::Unit::TestCase
+
+  def seed_jobs(count = 5)
+    count.times.map do
+      StalkClimber::Job.new(@connection.transmit(StalkClimber::Connection::PROBE_TRANSMISSION))
+    end
+  end
+
+end

data/test/unit/climber_test.rb

@@ -0,0 +1,59 @@
+require 'test_helper'
+
+class ClimberTest < Test::Unit::TestCase
+
+  def test_climb_caches_jobs_for_later_use
+    climber = StalkClimber::Climber.new do |c|
+      c.beanstalk_addresses = BEANSTALK_ADDRESSES
+    end
+
+    test_jobs = {}
+    climber.connection_pool.connections.each do |connection|
+      test_jobs[connection.address] = []
+      5.times.to_a.map! do
+          test_jobs[connection.address] << StalkClimber::Job.new(connection.transmit(StalkClimber::Connection::PROBE_TRANSMISSION))
+      end
+    end
+
+    jobs = {}
+    climber.each do |job|
+      jobs[job.connection.address] ||= {}
+      jobs[job.connection.address][job.id] = job
+    end
+
+    climber.expects(:with_job).never
+    climber.each do |job|
+      assert_equal jobs[job.connection.address][job.id], job
+    end
+
+    climber.connection_pool.connections.each do |connection|
+      test_jobs[connection.address].map(&:delete)
+    end
+  end
+
+
+  def test_connection_pool_creates_a_connection_pool
+    climber = StalkClimber::Climber.new do |c|
+      c.beanstalk_addresses = 'beanstalk://localhost'
+    end
+    assert_kind_of StalkClimber::ConnectionPool, climber.connection_pool
+  end
+
+
+  def test_connection_pool_raises_an_error_without_beanstalk_addresses
+    climber = StalkClimber::Climber.new
+    assert_raise RuntimeError do
+      climber.connection_pool
+    end
+  end
+
+
+  def test_each_is_an_alias_for_climb
+    assert_equal(
+      StalkClimber::Climber.instance_method(:climb),
+      StalkClimber::Climber.instance_method(:each),
+      'Expected StalkClimber::Climber#each to be an alias for StalkClimber::Climber#climb'
+    )
+  end
+
+end

data/test/unit/connection_pool_test.rb

@@ -0,0 +1,49 @@
+# Tests adapted from Backburner::Connection tests
+# https://github.com/nesquena/backburner/blob/master/test/connection_test.rb
+
+require 'test_helper'
+
+class ConnectionPoolTest < Test::Unit::TestCase
+
+  def test_for_bad_url_it_should_raise_a_bad_url_error
+    assert_raises(StalkClimber::ConnectionPool::InvalidURIScheme) do
+      StalkClimber::ConnectionPool.new('fake://foo')
+    end
+  end
+
+
+  def test_for_delegated_methods_it_should_delegate_methods_to_beanstalk_connection
+    connection = StalkClimber::ConnectionPool.new('beanstalk://localhost')
+    assert_equal 'localhost', connection.connections.first.host
+  end
+
+
+  def test_with_multiple_urls_it_should_support_array_of_connections
+    connection = StalkClimber::ConnectionPool.new(['beanstalk://localhost:11300','beanstalk://localhost'])
+    connections = connection.connections
+    assert_equal 2, connection.connections.size
+    assert_equal ['localhost:11300','localhost:11300'], connections.map(&:address)
+  end
+
+
+  def test_with_multiple_urls_it_should_support_single_string_with_commas
+    connection = StalkClimber::ConnectionPool.new('beanstalk://localhost:11300,beanstalk://localhost')
+    connections = connection.connections
+    assert_equal 2, connections.size
+    assert_equal ['localhost:11300','localhost:11300'], connections.map(&:address)
+  end
+
+
+  def test_with_single_url_it_should_set_up_connection_pool
+    connection = StalkClimber::ConnectionPool.new('beanstalk://localhost')
+    assert_kind_of StalkClimber::ConnectionPool, connection
+    assert_kind_of Beaneater::Pool, connection
+  end
+
+
+  def test_with_a_single_url_it_should_convert_url_to_address_array
+    connection = StalkClimber::ConnectionPool.new('beanstalk://localhost')
+    assert_equal ['localhost:11300'], connection.addresses
+  end
+
+end

data/test/unit/connection_test.rb

@@ -0,0 +1,192 @@
+require 'test_helper'
+
+class ConnectionTest < Test::Unit::TestCase
+
+  def setup
+    @connection = StalkClimber::Connection.new('localhost:11300')
+  end
+
+
+  def test_cache_creates_and_returns_hash_instance_variable
+    refute @connection.instance_variable_get(:@cache)
+    assert_equal({}, @connection.cache)
+    assert_equal({}, @connection.instance_variable_get(:@cache))
+  end
+
+
+  def test_cache_is_reset_if_max_job_id_lower_than_max_climbed_job_id
+    seeds = seed_jobs
+    @connection.each {}
+    assert_not_equal({}, @connection.cache)
+    assert_not_equal(Float::INFINITY, @connection.min_climbed_job_id)
+    assert_not_equal(0, @connection.max_climbed_job_id)
+
+    @connection.send(:update_climbed_job_ids_from_max_id, 1)
+    assert_equal({}, @connection.cache)
+    assert_equal(Float::INFINITY, @connection.min_climbed_job_id)
+    assert_equal(0, @connection.max_climbed_job_id)
+    seeds.map(&:delete)
+  end
+
+
+  def test_connection_is_some_kind_of_enumerable
+    assert @connection.kind_of?(Enumerable)
+  end
+
+
+  def test_each_caches_jobs_for_later_use
+    seeds = seed_jobs
+
+    jobs = {}
+    @connection.each do |job|
+      jobs[job.id] = job
+    end
+
+    @connection.expects(:with_job).never
+    @connection.each do |job|
+      assert_equal jobs[job.id], job
+    end
+
+    seeds.map(&:delete)
+  end
+
+
+  def test_each_deletes_cached_jobs_that_no_longer_exist
+    seeds = seed_jobs
+
+    jobs = {}
+    @connection.each do |job|
+      jobs[job.id] = job
+    end
+
+    deleted_job = jobs[jobs.keys[2]]
+    deleted_job.delete
+
+    @connection.expects(:with_job).never
+    @connection.each do |job|
+      assert_equal jobs.delete(job.id), job
+    end
+
+    assert_equal 1, jobs.length
+    assert_equal deleted_job.id, jobs.values.first.id
+
+    seeds.map(&:delete)
+  end
+
+
+  def test_each_hits_jobs_below_climbed_range_that_have_not_been_hit
+    seeds = seed_jobs(10)
+
+    count = 0
+    @connection.each do |job|
+      count += 1
+      break if count == 5
+    end
+
+    initial_min_climbed_job_id = @connection.min_climbed_job_id
+
+    all_jobs = {}
+    @connection.each do |job|
+      all_jobs[job.id] = job
+    end
+
+    seeds.each do |job|
+      assert_equal all_jobs[job.id].body, job.body
+      assert_equal all_jobs[job.id].id, job.id
+      job.delete
+    end
+
+    assert @connection.min_climbed_job_id < initial_min_climbed_job_id
+  end
+
+
+  def test_each_only_hits_each_job_once
+    seeds = seed_jobs
+
+    jobs = {}
+    @connection.each do |job|
+      refute jobs[job.id]
+      jobs[job.id] = job
+    end
+
+    seeds.map(&:delete)
+  end
+
+
+  def test_each_calls_climb
+    @connection.expects(:climb)
+    @connection.each {}
+  end
+
+
+  def test_max_job_id_returns_expected_max_job_id
+    initial_max = @connection.max_job_id
+    seed_jobs(3).map(&:delete)
+    # 3 new jobs, +1 for the probe job
+    assert_equal initial_max + 4, @connection.max_job_id
+  end
+
+
+  def test_max_job_id_should_increment_max_climbed_id_if_successor
+    @connection.each {}
+    max = @connection.max_climbed_job_id
+    @connection.max_job_id
+    assert_equal max + 1, @connection.max_climbed_job_id
+  end
+
+
+  def test_max_job_id_should_not_increment_max_climbed_id_unless_successor
+    @connection.each {}
+    max = @connection.max_climbed_job_id
+    seed_jobs(1).map(&:delete)
+    @connection.max_job_id
+    assert_equal max, @connection.max_climbed_job_id
+  end
+
+
+  def test_each_sets_min_and_max_climbed_job_ids_appropriately
+    assert_equal Float::INFINITY, @connection.min_climbed_job_id
+    assert_equal 0, @connection.max_climbed_job_id
+
+    max_id = @connection.max_job_id
+    @connection.expects(:max_job_id).once.returns(max_id)
+    @connection.each {}
+
+    assert_equal 1, @connection.min_climbed_job_id
+    assert_equal max_id, @connection.max_climbed_job_id
+  end
+
+
+  def test_test_tube_is_initialized_but_configurable
+    assert_equal StalkClimber::Connection::DEFAULT_TUBE, @connection.test_tube
+    tube_name = 'test_tube'
+    @connection.test_tube = tube_name
+    assert_equal tube_name, @connection.test_tube
+  end
+
+
+  def test_with_job_yields_nil_or_the_requested_job_if_it_exists
+    assert_nothing_raised do
+      @connection.with_job(@connection.max_job_id) do |job|
+        assert_equal nil, job
+      end
+    end
+
+    probe = seed_jobs(1).first
+    @connection.with_job(probe.id) do |job|
+      assert_equal probe.id, job.id
+    end
+    probe.delete
+  end
+
+
+  def test_with_job_bang_does_not_execute_block_and_raises_error_if_job_does_not_exist
+    block = lambda {}
+    block.expects(:call).never
+    assert_raise Beaneater::NotFoundError do
+      Object.any_instance.expects(:yield).never
+      @connection.with_job!(@connection.max_job_id, &block)
+    end
+  end
+
+end

data/test/unit/job_test.rb

@@ -0,0 +1,166 @@
+require 'test_helper'
+
+class Job < Test::Unit::TestCase
+
+  def setup
+    @connection = StalkClimber::Connection.new('localhost:11300')
+    @job = seed_jobs(1).first
+  end
+
+
+  def test_body_retrives_performs_peek
+    body = {:test => true}
+
+    @job.connection.expects(:transmit).returns({
+      :body => body,
+    })
+    assert_equal body, @job.body
+
+    @job.connection.expects(:transmit).never
+    assert_equal body, @job.body
+  end
+
+
+  def test_connection_stored_with_instance
+    assert @job.instance_variable_get(:@connection)
+    assert @job.connection
+  end
+
+
+  def test_delete
+    assert @job.delete
+    assert_raise Beaneater::NotFoundError do
+      @connection.transmit("peek #{@job.id}")
+    end
+    refute @job.instance_variable_get(:@body)
+    refute @job.instance_variable_get(:@stats)
+    assert_equal 'DELETED', @job.instance_variable_get(:@status)
+  end
+
+
+  def test_exists?
+    assert @job.exists?
+
+    @job.delete
+    refute @job.exists?
+  end
+
+
+  def test_initialize_with_peek_response
+    job = StalkClimber::Job.new(@connection.transmit("peek #{@job.id}"))
+    @connection.expects(:transmit).never
+    assert_equal @connection, job.connection
+    assert_equal @job.id, job.id
+    assert_equal 'FOUND', job.instance_variable_get(:@status)
+    assert_equal '{}', job.body
+    refute job.instance_variable_get(:@stats)
+  end
+
+
+  def test_initialize_with_put_response
+    @connection.expects(:transmit).never
+    assert @job.id
+    assert_equal @connection, @job.connection
+    assert_equal 'INSERTED', @job.instance_variable_get(:@status)
+    refute @job.instance_variable_get(:@body)
+    refute @job.instance_variable_get(:@stats)
+  end
+
+
+  def test_initialize_with_stats_response
+    job = StalkClimber::Job.new(@connection.transmit("stats-job #{@job.id}"))
+    @connection.expects(:transmit).never
+    assert_equal @job.id, job.id
+    assert_equal @connection, job.connection
+    assert_equal 'OK', job.instance_variable_get(:@status)
+    assert job.stats
+    assert job.instance_variable_get(:@stats)
+    refute job.instance_variable_get(:@body)
+    StalkClimber::Job::STATS_ATTRIBUTES.each do |method_name|
+      assert job.send(method_name)
+    end
+  end
+
+
+  def test_initialize_with_stats_attribute_methods_return_correct_values
+    body = {
+      'age'=>3,
+      'buries'=>0,
+      'delay'=>0,
+      'id' => 4412,
+      'kicks'=>0,
+      'pri'=>4294967295,
+      'releases'=>0,
+      'reserves'=>0,
+      'state'=>'ready',
+      'time-left'=>0,
+      'timeouts'=>0,
+      'ttr'=>300,
+      'tube'=>'default',
+    }
+    stats = {
+      :body => body,
+      :connection => @connection,
+      :id => 149,
+      :status => 'OK',
+    }
+    @connection.expects(:transmit).returns(stats)
+    job = StalkClimber::Job.new(@connection.transmit("stats-job #{@job.id}"))
+    @connection.expects(:transmit).never
+    StalkClimber::Job::STATS_ATTRIBUTES.each do |method_name|
+      assert_equal body[method_name], job.send(method_name), "Expected #{body[method_name.to_sym]} for #{method_name}, got #{job.send(method_name)}"
+    end
+  end
+
+
+  def test_initialize_with_unknown_status_raises_error
+    assert_raise RuntimeError do
+      StalkClimber::Job.new({:status => 'DELETED'})
+    end
+  end
+
+
+  def test_stats_attribute_method_can_force_refresh
+    initial_value = @job.age
+    @connection.expects(:transmit).returns({:body => {'age' => initial_value + 100}})
+    assert_equal initial_value + 100, @job.age(true)
+  end
+
+
+  def test_stats_can_force_a_refresh
+    body = {
+      'age'=>3,
+      'buries'=>0,
+      'delay'=>0,
+      'kicks'=>0,
+      'id' => 4412,
+      'pri'=>4294967295,
+      'releases'=>0,
+      'reserves'=>0,
+      'state'=>'ready',
+      'time-left'=>0,
+      'timeouts'=>0,
+      'ttr'=>300,
+      'tube'=>'default',
+    }
+    stats_1 = {
+      :body => {},
+      :connection => @connection,
+      :id => 149,
+      :status => 'OK',
+    }
+    stats_2 = {
+      :body => body,
+      :connection => @connection,
+      :id => 149,
+      :status => 'OK',
+    }
+    @connection.expects(:transmit).twice.returns(stats_1, stats_2)
+    job = StalkClimber::Job.new(@connection.transmit("stats-job #{@job.id}"))
+    job.stats(:force_refresh)
+    StalkClimber::Job::STATS_ATTRIBUTES.each do |method_name|
+      assert_equal body[method_name], job.send(method_name), "Expected #{body[method_name.to_sym]} for #{method_name}, got #{job.send(method_name)}"
+    end
+  end
+
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: stalk_climber
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Freewrite.org
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: beaneater
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Improved sequential access to Beanstalk
+email:
+- dev@freewrite.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/stalk_climber.rb
+- lib/stalk_climber/climber.rb
+- lib/stalk_climber/connection.rb
+- lib/stalk_climber/connection_pool.rb
+- lib/stalk_climber/job.rb
+- lib/stalk_climber/lazy_enumerable.rb
+- lib/stalk_climber/version.rb
+- stalk_climber.gemspec
+- test/test_helper.rb
+- test/unit/climber_test.rb
+- test/unit/connection_pool_test.rb
+- test/unit/connection_test.rb
+- test/unit/job_test.rb
+homepage: https://github.com/freewrite/stalk_climber
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: StalkClimber is a Ruby library allowing improved sequential access to Beanstalk
+  via a job cache.
+test_files:
+- test/test_helper.rb
+- test/unit/climber_test.rb
+- test/unit/connection_pool_test.rb
+- test/unit/connection_test.rb
+- test/unit/job_test.rb