bean_counter 0.0.1

data/lib/bean_counter.rb

@@ -0,0 +1,8 @@
+require 'forwardable'
+require 'beaneater'
+require 'bean_counter/version'
+require 'bean_counter/core'
+require 'bean_counter/strategy'
+require 'bean_counter/strategies/stalk_climber_strategy'
+require 'bean_counter/enqueued_expectation'
+require 'bean_counter/tube_expectation'

data/lib/bean_counter/core.rb

@@ -0,0 +1,115 @@
+module BeanCounter
+
+  # Use StalkClimberStrategy by default because it works with standard Beanstalkd
+  DEFAULT_STRATEGY = :'BeanCounter::Strategy::StalkClimberStrategy'
+
+  class << self
+    # Beanstalkd server urls to be used by BeanCounter
+    attr_writer :beanstalkd_url
+  end
+
+  # :call-seq:
+  #   beanstalkd_url() => Array[String]
+  #
+  # Returns an array of parsed beanstalkd urls.
+  # Server urls provided via the environment variable +BEANSTALKD_URL+ are given
+  # precedence. When setting beanstalkd_url from the environment, urls are
+  # expected in a comma separated list. If ENV['BEANSTALKD_URL'] is not set
+  # BeanCounter::beanstalkd_url is checked and parsed next. Finally, if
+  # BeanCounter::beanstalkd_url has not been set, the configuration for Beaneater is
+  # checked and parsed. If no beanstalkd_url can be determined a RuntimeError is raised.
+  # URLs can be provided in any of three supported formats:
+  # * localhost (host only)
+  # * 192.168.1.100:11300 (host and port)
+  # * beanstalk://127.0.0.1:11300 (host and port prefixed by beanstalk scheme)
+  #
+  # In short, a host is the only required component. If no port is provided, the default
+  # beanstalkd port of 11300 is assumed. If a scheme other than beanstalk is provided
+  # a StalkClimber::ConnectionPool::InvalidURIScheme error is raised.
+  #
+  #   $ BEANSTALKD_URL='127.0.0.1,beanstalk://localhost:11300,localhost:11301' rake test
+  #   BeanCounter.beanstalkd_url
+  #     #=> ['127.0.0.1', 'beanstalk://localhost:11300', 'localhost:11301']
+  #
+  #   BeanCounter.beanstalkd_url = 'beanstalk://localhost'
+  #   BeanCounter.beanstalkd_url
+  #     #=> 'beanstalk://localhost'
+  #
+  #   Beaneater.configure do |config|
+  #     config.beanstalkd_url = ['localhost', 'localhost:11301']
+  #   end
+  #
+  #   BeanCounter.beanstalkd_url
+  #     #=> ['localhost', 'localhost:11301']
+  def self.beanstalkd_url
+    @hosts_from_env = ENV['BEANSTALKD_URL']
+    @hosts_from_env = @hosts_from_env.split(',').map!(&:strip) unless @hosts_from_env.nil?
+    beanstalkd_url = @hosts_from_env || @beanstalkd_url || Beaneater.configuration.beanstalkd_url
+    raise 'Could not determine beanstalkd url' if beanstalkd_url.to_s == ''
+    return beanstalkd_url
+  end
+
+
+  # :call-seq:
+  #   default_strategy() => subclass of BeanCounter::Strategy
+  #
+  # Return a previously materialized default strategy or materialize a new default
+  # strategy for use. See BeanCounter::Strategy::materialize_strategy for more
+  # information on the materialization process.
+  def self.default_strategy
+    return @default_strategy ||= BeanCounter::Strategy.materialize_strategy(DEFAULT_STRATEGY)
+  end
+
+
+  # :call-seq:
+  #   reset!(tube_name = nil) => Boolean
+  # Uses the strategy to delete all jobs from the +tube_name+ tube. If +tube_name+
+  # is not provided, all jobs on the beanstalkd server are deleted.
+  #
+  # It should be noted that jobs that are reserved can only be deleted by the
+  # reserving connection and thus cannot be deleted via this method. As such,
+  # care may need to be taken to ensure that jobs are not left in a reserved
+  # state.
+  #
+  # Returns true if all encountered jobs were deleted successfully. Returns
+  # false if any of the jobs enumerated could not be deleted.
+  def self.reset!(tube_name = nil)
+    partial_failure = false
+    strategy.jobs.each do |job|
+      success = strategy.delete_job(job) if tube_name.nil? || strategy.job_matches?(job, :tube => tube_name)
+      partial_failure ||= success
+    end
+    return !partial_failure
+  end
+
+
+  # Returns a list of known subclasses of BeanCounter::Strategy.
+  # Typically this list represents the strategies available for interacting
+  # with beanstalkd.
+  def self.strategies
+    return BeanCounter::Strategy.strategies
+  end
+
+
+  # Sets the strategy that BeanCounter should use when interacting with
+  # beanstalkd. The value provided for +strategy_identifier+ will be used to
+  # materialize an instance of the matching strategy class. If the provided
+  # +strategy_identifier+ is nil, any existing strategy will be cleared and
+  # the next call to BeanCounter::strategy will use the default strategy.
+  def self.strategy=(strategy_identifier)
+    if strategy_identifier.nil?
+      @strategy = nil
+    else
+      @strategy = BeanCounter::Strategy.materialize_strategy(strategy_identifier).new
+    end
+  end
+
+
+  # Returns a previously materialized strategy if one exists. If no previous
+  # strategy exists, a new instance of the default strategy is instantiated
+  # and returned.
+  def self.strategy
+    return @strategy ||= default_strategy.new
+  end
+
+end

data/lib/bean_counter/enqueued_expectation.rb

@@ -0,0 +1,130 @@
+class BeanCounter::EnqueuedExpectation
+
+  extend Forwardable
+
+  def_delegators BeanCounter, :strategy
+
+  # The value that the expectation expects
+  attr_reader :expected
+
+  # The number of matching jobs the expectation expects
+  attr_reader :expected_count
+
+  # The jobs found by the expecation during matching
+  attr_reader :found
+
+
+  # Iterates over the provided collection searching for jobs matching the
+  # Hash of expected options provided at instantiation.
+  def collection_matcher(collection)
+    @found = collection.send(expected_count? ? :select : :detect) do |job|
+      strategy.job_matches?(job, expected)
+    end
+
+    @found = [@found] unless expected_count? || @found.nil?
+
+    expected_count? ? expected_count === found.to_a.length : !found.nil?
+  end
+
+
+  # Returns a Boolean indicating whether a specific number of jobs are expected.
+  def expected_count?
+    return !!expected_count
+  end
+
+
+  # Builds the failure message used in the event of a positive expectation
+  # failure
+  def failure_message
+    if found.nil?
+      found_count = 'none'
+      found_string = nil
+    else
+      found_count = "#{found.length}:"
+      found_string = found.map {|job| strategy.pretty_print_job(job) }.join("\n")
+    end
+    [
+      "expected #{expected_count || 'any number of'} jobs matching #{expected.to_s},",
+      "found #{found_count}",
+      found_string,
+    ].compact.join(' ')
+  end
+
+
+  # Create a new enqueued expectation. Uses the given +expected+ Hash to determine
+  # if any jobs are enqueued that match the expected options.
+  #
+  # Each _key_ in +expected+ is a String or a Symbol that identifies an attribute
+  # of a job that the corresponding _value_ should be compared against. All attribute
+  # comparisons are performed using the triple equal (===) operator/method of
+  # the given _value_.
+  #
+  # +expected+ may additionally include a _count_ key of 'count' or :count that
+  # can be used to specify that a particular number of matching jobs are found.
+  #
+  # See BeanCounter::TestAssertions and/or BeanCounter::SpecMatchers for more information.
+  def initialize(expected)
+    @expected = expected
+    @expected_count = [expected.delete(:count), expected.delete('count')].compact.first
+  end
+
+
+  # Checks the beanstalkd pool for jobs matching the Hash of expected options
+  # provided at instantiation.
+  #
+  # If no _count_ option is provided, the expectation succeeds if any job is found
+  # that matches all of the expected options. If no jobs are found that match the
+  # expected options, the expecation fails.
+  #
+  # If a _count_ option is provided the expectation only succeeds if the triple equal
+  # (===) operator/method of the value of _count_ evaluates to true when given the
+  # total number of matching jobs. Otherwise the expecation fails. The use of ===
+  # allows for more advanced comparisons using Procs, Ranges, Regexps, etc.
+  #
+  # See Strategy#job_matches? and/or the #job_matches? method of the strategy
+  # in use for more detailed information on how it is determined whether or not
+  # a job matches the options expected.
+  #
+  # See also BeanCounter::TestAssertions and/or BeanCounter::SpecMatchers for additional
+  # information.
+  def matches?(given = nil)
+    if given.kind_of?(Proc)
+      return proc_matcher(given)
+    else
+      return collection_matcher(strategy.jobs)
+    end
+  end
+
+
+  # Builds the failure message used in the event of a negative expectation
+  # failure
+  def negative_failure_message
+    return '' if found.nil? || found == []
+
+    found_count = found.length
+    found_string = found.map {|job| strategy.pretty_print_job(job) }.join("\n")
+    if expected_count?
+      job_count = expected_count
+      job_word = expected_count == 1 ? 'job' : 'jobs'
+    else
+      job_count = 'any'
+      job_word = 'jobs'
+    end
+    return [
+      "did not expect #{job_count} #{job_word} matching #{expected.to_s},",
+      "found #{found_count}:",
+       found_string,
+    ].join(' ')
+  end
+
+
+  # Monitors the beanstalkd pool for new jobs enqueued during the provided
+  # block than passes any collected jobs to the collection matcher to determine
+  # if any jobs were enqueued that match the expected options provided at
+  # instantiation
+  def proc_matcher(block)
+    new_jobs = strategy.collect_new_jobs(&block)
+    collection_matcher(new_jobs)
+  end
+
+end

data/lib/bean_counter/mini_test.rb

@@ -0,0 +1,3 @@
+require 'bean_counter/test_assertions'
+
+MiniTest::Unit::TestCase.send(:include, BeanCounter::TestAssertions)

data/lib/bean_counter/spec.rb

@@ -0,0 +1,5 @@
+require 'bean_counter/spec_matchers'
+
+if defined?(RSpec)
+  RSpec.configuration.include(BeanCounter::SpecMatchers)
+end

data/lib/bean_counter/spec_matchers.rb

@@ -0,0 +1,25 @@
+module BeanCounter::SpecMatchers
+
+  # Creates a new BeanCounter::EnqueuedExpectation with +expected+ stored for
+  # later use when matching. Most of the time the value provided for +expected+
+  # will be ignored, the only exception is when +expected+ is given a block.
+  # When a block is provided for +expected+, only jobs enqueued during the
+  # execution of the block will be considered when matching.
+  #
+  # See BeanCounter::EnqueuedExpectation for additional information and usage
+  # patterns.
+  def have_enqueued(expected)
+    BeanCounter::EnqueuedExpectation.new(expected)
+  end
+
+  # Creates a new BeanCounter::TubeExpectation with +expected+ stored for
+  # later use when matching. However, +expected+ is never used when matching.
+  # Instead, all tubes are matched against until a match is found.
+  #
+  # See BeanCounter::TubeExpectation for additional information and usage
+  # patterns.
+  def have_tube(expected)
+    BeanCounter::TubeExpectation.new(expected)
+  end
+
+end

data/lib/bean_counter/strategies/stalk_climber_strategy.rb

@@ -0,0 +1,150 @@
+require 'stalk_climber'
+
+class BeanCounter::Strategy::StalkClimberStrategy < BeanCounter::Strategy
+
+  extend Forwardable
+
+  # Index of what method should be called to retrieve each stat
+  STATS_METHOD_NAMES = begin
+    attrs = (
+      BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES +
+      BeanCounter::Strategy::MATCHABLE_TUBE_ATTRIBUTES
+    ).map!(&:to_sym).uniq.sort
+    method_names = attrs.map {|method| method.to_s.gsub(/-/, '_').to_sym }
+    attr_methods = Hash[attrs.zip(method_names)]
+    attr_methods[:pause] = :pause_time
+    attr_methods
+  end
+
+  # Default tube used by StalkClimber when probing the beanstalkd pool
+  TEST_TUBE = 'bean_counter_stalk_climber_test'
+
+  # The tube that will be used by StalkClimber when probing the beanstalkd pool.
+  # Uses TEST_TUBE if no value provided.
+  attr_writer :test_tube
+
+  def_delegators :climber, :jobs, :tubes
+
+
+  # :call-seq:
+  #   collect_new_jobs { block } => Array[StalkClimber::Job]
+  #
+  # Collects all jobs enqueued during the execution of the provided +block+.
+  # Returns an Array of StalkClimber::Job.
+  #
+  # Fulfills Strategy#collect_new_jobs contract. See Strategy#collect_new_jobs
+  # for more information.
+  def collect_new_jobs
+    raise ArgumentError, 'Block required' unless block_given?
+
+    min_ids = climber.max_job_ids
+    yield
+    max_ids = climber.max_job_ids
+    new_jobs = []
+    min_ids.each do |connection, min_id|
+      testable_ids = (min_id..max_ids[connection]).to_a
+      new_jobs.concat(connection.fetch_jobs(testable_ids).compact)
+    end
+    return new_jobs
+  end
+
+
+  # :call-seq:
+  #   delete_job(job) => Boolean
+  #
+  # Attempts to delete the given StalkClimber::Job +job+. Returns true if
+  # deletion succeeds or if +job+ does not exist. Returns false if +job+ could
+  # not be deleted (typically due to it being reserved by another connection).
+  #
+  # Fulfills Strategy#delete_job contract. See Strategy#delete_job for more
+  # information.
+  def delete_job(job)
+    job.delete
+    return true
+  rescue Beaneater::NotFoundError
+    return job.exists? ? false : true
+  end
+
+
+  # :call-seq:
+  #   job_matches?(job, options => {Symbol,String => Numeric,Proc,Range,Regexp,String}) => Boolean
+  #
+  # Returns a boolean indicating whether or not the provided StalkClimber::Job
+  # +job+ matches the given Hash of +options.
+  #
+  # Fulfills Strategy#job_matches? contract. See Strategy#job_matches? for more
+  # information.
+  def job_matches?(job, opts = {})
+    return matcher(MATCHABLE_JOB_ATTRIBUTES, job, opts)
+  end
+
+
+  # :call-seq:
+  #   pretty_print_job(job) => String
+  #
+  # Returns a String representation of the StalkClimber::Job +job+ in a pretty,
+  # human readable format.
+  #
+  # Fulfills Strategy#pretty_print_job contract. See Strategy#pretty_print_job
+  # for more information.
+  def pretty_print_job(job)
+    return job.to_h.to_s
+  end
+
+
+  # :call-seq:
+  #   pretty_print_tube(tube) => String
+  #
+  # Returns a String representation of +tube+ in a pretty, human readable format.
+  #
+  # Fulfills Strategy#pretty_print_tube contract. See Strategy#pretty_print_tube
+  # for more information.
+  def pretty_print_tube(tube)
+    return tube.to_h.to_s
+  end
+
+
+  # :call-seq:
+  #   tube_matches?(tube, options => {Symbol,String => Numeric,Proc,Range,Regexp,String}) => Boolean
+  #
+  # Returns a boolean indicating whether or not the provided StalkClimber +tube+
+  # matches the given Hash of +options.
+  #
+  # Fulfills Strategy#tube_matches? contract. See Strategy#tube_matches? for
+  # more information.
+  def tube_matches?(tube, opts = {})
+    return matcher(MATCHABLE_TUBE_ATTRIBUTES, tube, opts)
+  end
+
+  private
+
+  # StalkClimber instance used to climb/crawl beanstalkd pool
+  def climber
+    return @climber ||= StalkClimber::Climber.new(BeanCounter.beanstalkd_url, test_tube)
+  end
+
+
+  # Given the set of valid attributes, +valid_attributes+, determines if every
+  # _value_ of +opts+ evaluates to true when compared to the attribute of
+  # +matchable+ identified by the corresponding +opts+ _key_.
+  def matcher(valid_attributes, matchable, opts = {})
+    # Refresh state/stats before checking match
+    return false unless matchable.exists?
+    return (opts.keys & valid_attributes).all? do |key|
+      opts[key] === matchable.send(stats_method_name(key))
+    end
+  end
+
+
+  # Simplify lookup of what method to call to retrieve requested stat
+  def stats_method_name(stats_attr)
+    return STATS_METHOD_NAMES[stats_attr.to_sym]
+  end
+
+
+  # Accessor for test_tube that defaults to TEST_TUBE
+  def test_tube
+    return @test_tube ||= TEST_TUBE
+  end
+
+end

data/lib/bean_counter/strategy.rb

@@ -0,0 +1,250 @@
+class BeanCounter::Strategy
+
+  # Available job attributes. These attributes can be used by strategies
+  # to validate what attributes are used for matching jobs.
+  MATCHABLE_JOB_ATTRIBUTES = begin
+      attrs = [
+      :age, :body, :buries, :connection, :delay, :id, :kicks, :pri, :releases,
+      :reserves, :state, :'time-left', :timeouts, :ttr, :tube,
+    ]
+    attrs.concat(attrs.map(&:to_s))
+  end
+
+  # Available tube attributes. These attributes can be used by strategies
+  # to validate what attributes are used for matching tubes.
+  MATCHABLE_TUBE_ATTRIBUTES = begin
+    attrs = [
+      :'cmd-delete', :'cmd-pause-tube', :'current-jobs-buried',
+      :'current-jobs-delayed', :'current-jobs-ready', :'current-jobs-reserved',
+      :'current-jobs-urgent', :'current-using', :'current-waiting',
+      :'current-watching', :name, :pause, :'pause-time-left', :'total-jobs',
+    ]
+    attrs.concat(attrs.map(&:to_s))
+  end
+
+  @@strategies = {}
+
+
+  # Maintain an index of classes known to subclass Strategy.
+  def self.inherited(subclass)
+    identifier = subclass.name || subclass.to_s[8, subclass.to_s.length - 9]
+    @@strategies[identifier.to_sym] = subclass
+  end
+
+
+  # :call-seq:
+  #   known_strategy?(strategy_identifier) => Boolean
+  #
+  # Determines if the provided +strategy_identifer+ corresponds to a known
+  # subclass of strategy. The provided +strategy_identifer+ can be a class
+  # or any object that responds to :to_sym. Classes are compared directly.
+  # For non-class objects that respond to :to_sym, the symbolized form
+  # of +strategy_identifer+ is used as a key to attempt to retrieve a strategy
+  # from the strategies Hash.
+  #
+  # Returns true if +strategy_identifier+ isa known strategy or maps to a known
+  # strategy. Otherwise, false is returned.
+  #
+  #   BeanCounter::Strategy.known_strategy?(Object)
+  #     #=> false
+  #
+  #   BeanCounter::Strategy.known_strategy?(BeanCounter::Strategy)
+  #     #=> true
+  def self.known_strategy?(strategy_identifier)
+    return true if strategy_identifier.is_a?(Class) &&
+      strategy_identifier <= BeanCounter::Strategy
+    return true if strategy_identifier.respond_to?(:to_sym) &&
+      strategies.key?(strategy_identifier.to_sym)
+    return false
+  end
+
+
+  # :call-seq:
+  #   materialize_strategy(strategy_identifier) => subclass of Strategy
+  #
+  # Materialize the provided +strategy_identifier+ into a subclass of Strategy.
+  # If +strategy_identifer+ is already a subclass of Strategy,
+  # +strategy_identifier+ is returned. Otherwise, +strategy_identifer+ is
+  # converted into a Symbol and is used as a key to retrieve a strategy from
+  # the known subclasses of Strategy. If +strategy_identifier does not map to
+  # a known subclass of Strategy, an ArgumentError is raised.
+  #
+  #   BeanCounter::Strategy.materialize_strategy(:'BeanCounter::Strategy::StalkClimberStrategy')
+  #     #=> BeanCounter::Strategy::StalkClimberStrategy
+  def self.materialize_strategy(strategy_identifier)
+    unless BeanCounter::Strategy.known_strategy?(strategy_identifier)
+      raise(
+        ArgumentError,
+        "Could not find #{strategy_identifier} among known strategies: #{strategies.keys.to_s}"
+      )
+    end
+    return strategy_identifier.is_a?(Class) ? strategy_identifier : strategies[strategy_identifier.to_sym]
+  end
+
+
+  # :call-seq:
+  #   strategies() => Hash
+  #
+  # Returns a list of known classes that inherit from BeanCounter::Strategy.
+  # Typically this list represents the strategies available for interacting
+  # with beanstalkd.
+  def self.strategies
+    return @@strategies.dup
+  end
+
+
+  # :call-seq:
+  #   collect_new_jobs { block } => Array[Strategy Job]
+  #
+  # Provide a means of collecting jobs enqueued during the execution of the
+  # provided +block+. Returns an Array of Jobs as implemented by the Strategy.
+  #
+  # Used internally to reduce the set of jobs that must be examined to evaluate
+  # the truth of an assertion to only those enqueued during the evaluation of
+  # the given +block+.
+  #
+  #   new_jobs = strategy.collect_new_jobs do
+  #     ...
+  #   end
+  #     #=> [job_enqueued_during_block, job_enqueued_during_block]
+  def collect_new_jobs
+    raise NotImplementedError
+  end
+
+
+  # :call-seq:
+  #   delete_job(job) => Boolean
+  #
+  # Provide a means for deleting a job specific to the job interface used by
+  # the strategy. Should return true if the job was deleted successfully or
+  # no longer exists and false if the job could not be deleted.
+  #
+  # Used internally to delete a job, allowing the beanstalkd pool to be reset.
+  #
+  # strategy.delete_job(job)
+  #   #=> true
+  def delete_job
+    raise NotImplementedError
+  end
+
+
+  # :call-seq:
+  #   job_matches?(job, options => {Symbol,String => Numeric,Proc,Range,Regexp,String}) => Boolean
+  #
+  # Returns a boolean indicating whether or not the provided +job+ matches the
+  # given Hash of +options. Each _key_ in +options+ is a String or a Symbol that
+  # identifies an attribute of +job+ that the corresponding _value_ should be
+  # compared against. True is returned if every _value_ in +options+ evaluates to
+  # true when compared to the attribute of +job+ identified by the corresponding
+  # _key_. False is returned if any of the comparisons evaluates to false.
+  #
+  # If no options are given, returns true for any job that exists at the time of
+  # evaluation.
+  #
+  # Each attribute comparison is performed using the triple equal (===)
+  # operator/method of _value_ with the attribute of +job+ identified by _key_
+  # passed into the method. Use of === allows for more complex comparisons
+  # using Procs, Ranges, Regexps, etc.
+  #
+  # Consult MATCHABLE_JOB_ATTRIBUTES for a list of which attributes of +job+
+  # can be matched against.
+  #
+  # Used internally to evaluate if a job matches an assertion.
+  #
+  #   strategy.job_matches?(reserved_job, :state => 'reserved')
+  #     #=> true
+  #
+  #   strategy.job_matches(small_job, :body => lambda {|body| body.length > 50 })
+  #     #=> false
+  #
+  #   strategy.job_matches(unreliable_job, :buries => 6..100)
+  #     #=> true
+  def job_matches?
+    raise NotImplementedError
+  end
+
+
+  # :call-seq:
+  #   jobs() => Enumerator
+  #
+  # Returns an Enumerator providing a means to enumerate all jobs in the beanstalkd
+  # pool.
+  #
+  # Used internally to enumerate all jobs to find jobs matching an assertion.
+  def jobs
+    raise NotImplementedError
+  end
+
+
+  # :call-seq:
+  #   pretty_print_job(job) => String
+  #
+  # Returns a String representation of +job+ in a pretty, human readable
+  # format.
+  #
+  # Used internally to print a job when an assertion fails.
+  def pretty_print_job
+    raise NotImplementedError
+  end
+
+
+  # :call-seq:
+  #   pretty_print_tube(tube) => String
+  #
+  # Returns a String representation of the tube in a pretty, human readable
+  # format. Used internally to print a tube when an assertion fails.
+  #
+  # Used internally to print a tube when an assertion fails.
+  def pretty_print_tube
+    raise NotImplementedError
+  end
+
+
+  # :call-seq:
+  #   tube_matches?(tube, options => {Symbol,String => Numeric,Proc,Range,Regexp,String}) => Boolean
+  #
+  # Returns a boolean indicating whether or not the provided +tube+ matches the
+  # given Hash of +options. Each _key_ in +options+ is a String or a Symbol that
+  # identifies an attribute of +tube+ that the corresponding _value_ should be
+  # compared against. True is returned if every _value_ in +options+ evaluates to
+  # true when compared to the attribute of +tube+ identified by the corresponding
+  # _key_. False is returned if any of the comparisons evaluates to false.
+  #
+  # If no options are given, returns true for any tube that exists at the time of
+  # evaluation.
+  #
+  # Each attribute comparison is performed using the triple equal (===)
+  # operator/method of _value_ with the attribute of +job+ identified by _key_
+  # passed into the method. Use of === allows for more complex comparisons using
+  # Procs, Ranges, Regexps, etc.
+  #
+  # Consult MATCHABLE_TUBE_ATTRIBUTES for a list of which attributes of +tube+
+  # can be matched against.
+  #
+  # Used internally to evaluate if a tube matches an assertion.
+  #
+  #   strategy.tube_matches?(paused_tube, :state => 'paused')
+  #     #=> true
+  #
+  #   strategy.tube_matches(test_tube, :name => /test/)
+  #     #=> true
+  #
+  #   strategy.tube_matches(backed_up_tube, 'current-jobs-ready' => 50..100)
+  #     #=> true
+  def tube_matches?
+    raise NotImplementedError
+  end
+
+
+  # :call-seq:
+  #   tubes() => Enumerator
+  #
+  # Returns an Enumerator providing a means to enumerate all tubes in the beanstalkd
+  # pool.
+  #
+  # Used internally to enumerate all tubes to find tubes matching an assertion.
+  def tubes
+    raise NotImplementedError
+  end
+
+end