tuber 0.0.1 → 0.5.1

data/lib/tuber/tube/collection.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+class Tuber
+  # Represents collection of tube related commands.
+
+  class Tubes
+    include Enumerable
+
+    # @!attribute client
+    #   @return [Tuber] returns the client instance
+    attr_reader :client
+
+    # Creates new tubes instance.
+    #
+    # @param [Tuber] client The tuber client instance.
+    # @example
+    #  Tuber::Tubes.new(@client)
+    #
+    def initialize(client)
+      @client = client
+    end
+
+    def last_used
+      client.connection.tube_used
+    end
+
+    def last_used=(tube_name)
+      client.connection.tube_used = tube_name
+    end
+
+    # Delegates transmit to the connection object.
+    #
+    # @see Tuber::Connection#transmit
+    def transmit(command, **options)
+      # Empty **options must not be forwarded: on Ruby 2.7 it arrives as an
+      # extra positional {} at the receiver.
+      return client.connection.transmit(command) if options.empty?
+      client.connection.transmit(command, **options)
+    end
+
+    # Finds the specified beanstalk tube.
+    #
+    # @param [String] tube_name Name of the beanstalkd tube
+    # @return [Tuber::Tube] specified tube
+    # @example
+    #   @pool.tubes.find('tube2')
+    #   @pool.tubes['tube2']
+    #     # => <Tuber::Tube name="tube2">
+    #
+    # @api public
+    def find(tube_name)
+      Tube.new(client, tube_name)
+    end
+    alias_method :[], :find
+
+    # Reserves a ready job looking at all watched tubes.
+    #
+    # @param [Integer] timeout Number of seconds before timing out.
+    # @param [Proc] block Callback to perform on the reserved job.
+    # @yield [job] Reserved tuber job.
+    # @return [Tuber::Job] Reserved tuber job.
+    # @example
+    #   @client.tubes.reserve { |job| process(job) }
+    #     # => <Tuber::Job id=5 body="foo">
+    #
+    # @api public
+    def reserve(timeout=nil, &block)
+      res = transmit(
+        timeout ? "reserve-with-timeout #{timeout}" : 'reserve')
+      job = Job.new(client, res)
+      block.call(job) if block_given?
+      job
+    end
+
+    # Reserves a batch of ready jobs from watched tubes.
+    #
+    # Without a +timeout+ the call is non-blocking and may return an empty array.
+    # With a positive +timeout+ it long-polls, blocking up to +timeout+ seconds
+    # for the first job before draining whatever is ready, up to +count+.
+    #
+    # @param [Integer] count Maximum number of jobs to reserve
+    # @param [Integer] timeout Seconds to long-poll for the first job (nil = non-blocking)
+    # @return [Array<Tuber::Job>] Array of reserved jobs (empty if none available)
+    # @raise [Tuber::DeadlineSoonError] A reserved job's TTR is about to expire
+    # @example
+    #   @client.tubes.reserve_batch(10)       # non-blocking
+    #   @client.tubes.reserve_batch(10, 30)   # long-poll up to 30s
+    #     # => [<Tuber::Job id=1 body="foo">, ...]
+    #
+    # @api public
+    def reserve_batch(count, timeout = nil)
+      results = client.connection.reserve_batch(count, timeout)
+      results.map { |res| Job.new(client, res) }
+    end
+
+    # Sets the reserve mode for the connection.
+    #
+    # @param [String, Symbol] mode The reserve mode ('weighted' or 'fifo')
+    # @return [Hash] Response from beanstalkd
+    # @example
+    #   @client.tubes.reserve_mode(:weighted)
+    #   @client.tubes.reserve_mode(:fifo)
+    #
+    # @api public
+    def reserve_mode(mode)
+      transmit("reserve-mode #{mode}")
+    end
+
+    # Reserves a specific job by its ID.
+    #
+    # @param [Integer, String] id The job ID to reserve
+    # @return [Tuber::Job, nil] The reserved job, or nil if not found
+    # @example
+    #   @client.tubes.reserve_job(123)
+    #     # => <Tuber::Job id=123 body="foo">
+    #
+    # @api public
+    def reserve_job(id)
+      res = transmit("reserve-job #{id}")
+      Job.new(client, res)
+    rescue Tuber::NotFoundError
+      nil
+    end
+
+    # Returns stats for a job group.
+    #
+    # @param [String] group The group name
+    # @return [Tuber::StatStruct] Struct of group stats
+    # @example
+    #   @client.tubes.stats_group('batch-1')
+    #     # => #<StatStruct name="batch-1" ready=5 reserved=0 delayed=0 buried=0 waiting_jobs=0>
+    #
+    # @api public
+    def stats_group(group)
+      res = transmit("stats-group #{group}")
+      StatStruct.from_hash(res[:body])
+    end
+
+    # List of all known beanstalk tubes.
+    #
+    # @return [Array<Tuber::Tube>] List of all beanstalk tubes.
+    # @example
+    #   @client.tubes.all
+    #     # => [<Tuber::Tube name="tube2">, <Tuber::Tube name="tube3">]
+    #
+    # @api public
+    def all
+      transmit('list-tubes')[:body].map do |tube_name|
+        Tube.new(client, tube_name)
+      end
+    end
+
+    # Calls the given block once for each known beanstalk tube, passing that element as a parameter.
+    #
+    # @return An Enumerator is returned if no block is given.
+    # @example
+    #   @pool.tubes.each {|t| puts t.name}
+    #
+    # @api public
+    def each(&block)
+      all.each(&block)
+    end
+
+    # List of watched beanstalk tubes.
+    #
+    # @return [Array<Tuber::Tube>] List of watched beanstalk tubes.
+    # @example
+    #   @client.tubes.watched
+    #     # => [<Tuber::Tube name="tube2">, <Tuber::Tube name="tube3">]
+    #
+    # @api public
+    def watched
+      last_watched = transmit('list-tubes-watched')[:body]
+      client.connection.tubes_watched = last_watched.dup
+      last_watched.map do |tube_name|
+        Tube.new(client, tube_name)
+      end
+    end
+
+    # Currently used beanstalk tube.
+    #
+    # @return [Tuber::Tube] Currently used beanstalk tube.
+    # @example
+    #   @client.tubes.used
+    #     # => <Tuber::Tube name="tube2">
+    #
+    # @api public
+    def used
+      last_used = transmit('list-tube-used')[:id]
+      Tube.new(client, last_used)
+    end
+
+    # Add specified beanstalkd tubes as watched.
+    #
+    # @param [*String] names Name of tubes to watch
+    # @raise [Tuber::InvalidTubeName] Tube to watch was invalid.
+    # @example
+    #   @client.tubes.watch('foo', 'bar')
+    #
+    # @api public
+    def watch(*names, weight: nil)
+      names.each do |t|
+        cmd = weight ? "watch #{t} #{weight}" : "watch #{t}"
+        transmit cmd
+        client.connection.add_to_watched(t)
+      end
+    rescue BadFormatError => ex
+      raise InvalidTubeName, "Tube in '#{ex.cmd}' is invalid!"
+    end
+
+    # Add specified beanstalkd tubes as watched and ignores all other tubes.
+    #
+    # @param [*String] names Name of tubes to watch
+    # @raise [Tuber::InvalidTubeName] Tube to watch was invalid.
+    # @example
+    #   @client.tubes.watch!('foo', 'bar')
+    #
+    # @api public
+    def watch!(*names)
+      old_tubes = watched.map(&:name) - names.map(&:to_s)
+      watch(*names)
+      ignore(*old_tubes)
+    end
+
+    # Ignores specified beanstalkd tubes.
+    #
+    # @param [*String] names Name of tubes to ignore
+    # @example
+    #   @client.tubes.ignore('foo', 'bar')
+    #
+    # @api public
+    def ignore(*names)
+      names.each do |w|
+        transmit "ignore #{w}"
+        client.connection.remove_from_watched(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
+      transmit("use #{tube}")
+      self.last_used = tube
+    rescue BadFormatError
+      raise InvalidTubeName, "Tube cannot be named '#{tube}'"
+    end
+  end # Tubes
+end # Tuber

data/lib/tuber/tube/record.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+class Tuber
+  # Beanstalk tube which contains jobs which can be inserted, reserved, et al.
+  class Tube
+
+    # @!attribute name
+    #   @return [String] name of the tube
+    # @!attribute client
+    #   @return [Tuber] returns the client instance
+    attr_reader :name, :client
+
+    # Fetches the specified tube.
+    #
+    # @param [Tuber] client The tuber client instance.
+    # @param [String] name The name for this tube.
+    # @example
+    #  Tuber::Tube.new(@client, 'tube-name')
+    #
+    def initialize(client, name)
+      @client = client
+      @name = name.to_s
+      @mutex = Mutex.new
+    end
+
+    # Delegates transmit to the connection object.
+    #
+    # @see Tuber::Connection#transmit
+    def transmit(command, options={})
+      # Empty **options must not be forwarded: on Ruby 2.7 it arrives as an
+      # extra positional {} at the receiver.
+      return client.connection.transmit(command) if options.empty?
+      client.connection.transmit(command, **options)
+    end
+
+    # Inserts job with specified body onto tube.
+    #
+    # @param [String] body The data to store 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
+    # @option options [String, Array] idp idempotency key, or [key, ttl] pair
+    # @option options [String, Array] con concurrency key, or [key, limit] pair
+    # @option options [String] grp group key for this job
+    # @option options [String] aft after-group key (run after group completes)
+    # @return [Hash{String => String, Number}] beanstalkd command response
+    # @example
+    #   @tube.put "data", pri: 1000, ttr: 10, delay: 5
+    #   @tube.put "data", idp: "report", con: ["db", 3], grp: "batch-1", aft: "batch-0"
+    #
+    # @api public
+    def put(body, options={})
+      safe_use do
+        serialized_body = config.job_serializer.call(body)
+
+        options = {
+          :pri   => config.default_put_pri,
+          :delay => config.default_put_delay,
+          :ttr   => config.default_put_ttr
+        }.merge(options)
+
+        cmd_options = "#{options[:pri]} #{options[:delay]} #{options[:ttr]} #{serialized_body.bytesize}"
+
+        tags = []
+        if options[:idp]
+          tags << (options[:idp].is_a?(Array) ? "idp:#{options[:idp].join(':')}" : "idp:#{options[:idp]}")
+        end
+        if options[:con]
+          tags << (options[:con].is_a?(Array) ? "con:#{options[:con].join(':')}" : "con:#{options[:con]}")
+        end
+        tags << "grp:#{options[:grp]}" if options[:grp]
+        tags << "aft:#{options[:aft]}" if options[:aft]
+
+        cmd_options = "#{cmd_options} #{tags.join(' ')}" if tags.any?
+        transmit("put #{cmd_options}\r\n#{serialized_body}")
+      end
+    end
+
+    # Peek at next job within this tube in given `state`.
+    #
+    # @param [String] state The job state to peek at (`ready`, `buried`, `delayed`)
+    # @return [Tuber::Job] The next job within this tube.
+    # @example
+    #  @tube.peek(:ready) # => <Tuber::Job id=5 body=foo>
+    #
+    # @api public
+    def peek(state)
+      safe_use do
+        res = transmit("peek-#{state}")
+        Job.new(client, res)
+      end
+    rescue Tuber::NotFoundError
+      # Return nil if not found
+      nil
+    end
+
+    # Reserves the next job from tube.
+    #
+    # @param [Integer] timeout Number of seconds before timing out
+    # @param [Proc] block Callback to perform on reserved job
+    # @yield [job] Job that was reserved.
+    # @return [Tuber::Job] Job that was reserved.
+    # @example
+    #  @tube.reserve # => <Tuber::Job id=5 body=foo>
+    #
+    # @api public
+    def reserve(timeout=nil, &block)
+      client.tubes.watch!(self.name)
+      client.tubes.reserve(timeout, &block)
+    end
+
+    # Kick specified number of jobs from buried to ready state.
+    #
+    # @param [Integer] bounds The number of jobs to kick.
+    # @return [Hash{String => String, Number}] Beanstalkd command response
+    # @example
+    #   @tube.kick(5)
+    #
+    # @api public
+    def kick(bounds=1)
+      safe_use { transmit("kick #{bounds}") }
+    end
+
+    # Returns related stats for this tube.
+    #
+    # @return [Tuber::StatStruct] Struct of tube related values
+    # @example
+    #  @tube.stats.current_jobs_delayed # => 24
+    #
+    # @api public
+    def stats
+      res = transmit("stats-tube #{name}")
+      StatStruct.from_hash(res[:body])
+    end
+
+    # Pause the execution of this tube for specified `delay`.
+    #
+    # @param [Integer] delay Number of seconds to delay tube execution
+    # @return [Array<Hash{String => String, Number}>] Beanstalkd command response
+    # @example
+    #   @tube.pause(10)
+    #
+    # @api public
+    def pause(delay)
+      transmit("pause-tube #{name} #{delay}")
+    end
+
+    # Atomically deletes all jobs from the tube.
+    #
+    # @return [Integer] Number of jobs flushed
+    # @example
+    #   @tube.flush # => 5
+    #
+    # @api public
+    def flush
+      res = transmit("flush-tube #{name}")
+      res[:id].to_i
+    end
+
+    # Atomically deletes all buried jobs from the tube. Ready, delayed, and
+    # reserved jobs are left untouched. (Tuber only.)
+    #
+    # @return [Integer] Number of buried jobs flushed
+    # @example
+    #   @tube.flush_buried # => 3
+    #
+    # @api public
+    def flush_buried
+      res = transmit("flush-buried #{name}")
+      res[:id].to_i
+    end
+
+    # Clears all unreserved jobs in all states from the tube
+    #
+    # @example
+    #   @tube.clear
+    #
+    def clear
+      client.tubes.watch!(self.name)
+      %w(delayed buried ready).each do |state|
+        while job = self.peek(state.to_sym)
+          begin
+            job.delete
+          rescue Tuber::UnexpectedResponse, Tuber::NotFoundError
+            # swallow any issues
+          end
+        end
+      end
+      client.tubes.ignore(name)
+    rescue Tuber::NotIgnoredError
+      # swallow any issues
+    end
+
+    # String representation of tube.
+    #
+    # @return [String] Representation of tube including name.
+    # @example
+    #  @tube.to_s # => "#<Tuber::Tube name=foo>"
+    #
+    def to_s
+      "#<Tuber::Tube name=#{name.inspect}>"
+    end
+    alias :inspect :to_s
+
+    protected
+
+    # Transmits a beanstalk command that requires this tube to be set as used.
+    #
+    # @param [Proc] block Beanstalk command to transmit.
+    # @return [Object] Result of block passed
+    # @example
+    #  safe_use { transmit("kick 1") }
+    #    # => "Response to kick command"
+    #
+    def safe_use(&block)
+      @mutex.lock
+      client.tubes.use(self.name)
+      yield
+    ensure
+      @mutex.unlock
+    end
+
+    # Returns configuration options for tuber
+    #
+    # @return [Tuber::Configuration] configuration object
+    def config
+      Tuber.configuration
+    end
+  end # Tube
+end # Tuber

data/lib/tuber/tube.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'tuber/tube/record'
+require 'tuber/tube/collection'

data/lib/tuber/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class Tuber
+  # Current version of gem.
+  VERSION = "0.5.1"
+end

data/lib/tuber.rb

@@ -1,5 +1,107 @@
 # frozen_string_literal: true
 
-module Tuber
-  VERSION = "0.0.1"
+require 'thread' unless defined?(Mutex)
+
+%w(version configuration errors connection tube job stats).each do |f|
+  require "tuber/#{f}"
 end
+
+class Tuber
+
+  # @!attribute connection
+  #   @return <Tuber::Connection> returns the associated connection object
+  attr_reader :connection
+
+  # Initialize new instance of Tuber
+  #
+  # @param [String] address in the form "host:port"
+  # @example
+  #   Tuber.new('127.0.0.1:11300')
+  #
+  #   ENV['TUBER_URL'] = '127.0.0.1:11300'
+  #   @b = Tuber.new
+  #   @b.connection.host # => '127.0.0.1'
+  #   @b.connection.port # => '11300'
+  #
+  def initialize(address=nil)
+    @connection =  Connection.new(address)
+  end
+
+  # Returns Tuber::Tubes object for accessing tube related functions.
+  #
+  # @return [Tuber::Tubes] tubes object
+  # @api public
+  def tubes
+    @tubes ||= Tuber::Tubes.new(self)
+  end
+
+  # Returns Tuber::Jobs object for accessing job related functions.
+  #
+  # @return [Tuber::Jobs] jobs object
+  # @api public
+  def jobs
+    @jobs ||= Tuber::Jobs.new(self)
+  end
+
+  # Returns Tuber::Stats object for accessing beanstalk stats.
+  #
+  # @return [Tuber::Stats] stats object
+  # @api public
+  def stats
+    @stats ||= Stats.new(self)
+  end
+
+  # Puts the server into drain mode, rejecting new puts.
+  #
+  # @return [Hash] Response from beanstalkd
+  # @example
+  #  @tuber_instance.drain
+  #
+  def drain
+    connection.transmit("drain")
+  end
+
+  # Takes the server out of drain mode, allowing new puts.
+  #
+  # @return [Hash] Response from beanstalkd
+  # @example
+  #  @tuber_instance.undrain
+  #
+  def undrain
+    connection.transmit("undrain")
+  end
+
+  # Closes the related connection
+  #
+  # @example
+  #  @tuber_instance.close
+  #
+  def close
+    connection.close if connection
+  end
+
+  protected
+
+  class << self
+    # Yields a configuration block
+    #
+    # @example
+    #   Tuber.configure do |config|
+    #     config.job_parser = lamda { |body| Yaml.load(body)}
+    #   end
+    #
+    def configure(&block)
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Returns the configuration options set for Backburner
+    #
+    # @example
+    #   Tuber.configuration.default_put_ttr => 120
+    #
+    def configuration
+      @_configuration ||= Configuration.new
+    end
+  end
+end # Tuber