gearman_admin_client 0.0.1

data/README.markdown

@@ -0,0 +1,27 @@
+# GearmanAdminClient
+
+Connect and issue administrative commands to a [Gearman](http://gearman.org) server. `GearmanAdminClient`'s API follows the Administrative Protocol closely. You can read more about the Adminstrative Protocol under the "Administrative Protocol" section of the [Gearman protocol specification](http://gearman.org/protocol).
+
+## Usage
+
+```ruby
+client = GearmanAdminClient.new('localhost:4730')
+
+# list registered workers
+client.workers
+
+# list registered functions
+client.status
+
+# set the maximum queue size for a function
+client.max_queue_size('function_name', 1_000)
+
+# get the version of the server
+client.server_version
+
+# shutdown the server gracefully
+client.shutdown graceful: true
+
+# shutdown the server forcefully
+client.shutdown
+```

data/lib/gearman_admin_client.rb

@@ -0,0 +1,130 @@
+require 'socket'
+
+require_relative 'gearman_admin_client/worker'
+require_relative 'gearman_admin_client/registered_function'
+require_relative 'gearman_admin_client/connection'
+
+class GearmanAdminClient
+
+  DISCONNECTED = :DISCONNECTED unless defined? DISCONNECTED
+
+  class BadAddress < RuntimeError ; end
+
+  attr_reader :address
+
+  def initialize(address)
+    @address = address
+    @connection = DISCONNECTED
+  end
+
+  def workers
+    connect! do |connection|
+      connection.write('workers')
+      output = connection.drain.split("\n")
+
+      output.map! do |line|
+        segments = line.split(':')
+
+        function_names = segments.pop.strip.split(' ')
+
+        remainder = segments.join(':')
+
+        fd, ip_address, client_id = remainder.split(' ').map(&:strip)
+
+        unless function_names.include?('-')
+          Worker.new(
+            :file_descriptor => fd,
+            :ip_address => ip_address,
+            :client_id => client_id,
+            :function_names => function_names
+          )
+        end
+      end
+
+      output.compact!
+    end
+  end
+
+  def status
+    connect! do |connection|
+      connection.write('status')
+      output = connection.drain.split("\n")
+
+      output.map do |line|
+        function_name, total, running, workers = line.split("\t")
+
+        RegisteredFunction.new(
+          :name => function_name,
+          :jobs_in_queue => total,
+          :running_jobs => running,
+          :available_workers => workers
+        )
+      end
+    end
+  end
+
+  def server_version
+    connect! do |connection|
+      connection.write('version')
+      connection.read.strip
+    end
+  end
+
+  def shutdown(options = {})
+    connect! do |connection|
+      command = ['shutdown']
+
+      if options.fetch(:graceful, false)
+        command << 'graceful'
+      end
+
+      connection.write(command.join(' '))
+      connection.read.strip
+
+      connection.eof? && disconnect!
+    end
+
+    true
+  end
+
+  def max_queue_size(function_name, queue_size = nil)
+    connect! do |connection|
+      command = ['maxqueue', function_name, queue_size].compact
+
+      connection.write(command.join(' '))
+      connection.read.strip
+    end
+  end
+
+  def disconnected?
+    DISCONNECTED == @connection
+  end
+
+  private
+
+  def disconnect!
+    @connection.close
+    @connection = DISCONNECTED
+  end
+
+  def connect!(&and_then)
+    if disconnected?
+      just_open_a_socket do |socket|
+        @connection = Connection.new(socket)
+      end
+    end
+
+    and_then.call(@connection)
+  end
+
+  def just_open_a_socket
+    host, port = address.split(':')
+
+    if host && port
+      yield TCPSocket.new(host, port)
+    else
+      raise BadAddress, "expected address to look like HOST:PORT"
+    end
+  end
+
+end

data/lib/gearman_admin_client/connection.rb

@@ -0,0 +1,37 @@
+require 'forwardable'
+
+class GearmanAdminClient
+  class Connection
+    extend Forwardable
+
+    def_delegators :io, :close, :closed?, :eof?
+
+    attr_reader :io
+
+    def initialize(io)
+      @io = io
+    end
+
+    def write(command)
+      IO::select([], [io])
+      io.puts(command)
+    end
+
+    def read
+      IO::select([io])
+      io.gets
+    end
+
+    def drain
+      output = ''
+
+      while line = read
+        break if line.chop == '.'
+        output << line
+      end
+
+      output
+    end
+
+  end
+end

data/lib/gearman_admin_client/registered_function.rb

@@ -0,0 +1,13 @@
+require 'virtus'
+
+class GearmanAdminClient
+  class RegisteredFunction
+    include Virtus::ValueObject
+
+    attribute :name, String
+    attribute :jobs_in_queue, Integer
+    attribute :running_jobs, Integer
+    attribute :available_workers, Integer
+
+  end
+end

data/lib/gearman_admin_client/version.rb

@@ -0,0 +1,3 @@
+class GearmanAdminClient
+  VERSION = "0.0.1"
+end

data/lib/gearman_admin_client/worker.rb

@@ -0,0 +1,13 @@
+require 'virtus'
+
+class GearmanAdminClient
+  class Worker
+    include Virtus::ValueObject
+
+    attribute :file_descriptor, String
+    attribute :ip_address, String
+    attribute :client_id, String
+    attribute :function_names, Array[String]
+
+  end
+end

data/spec/gearman_admin_client_spec.rb

@@ -0,0 +1,161 @@
+require 'gearmand_control'
+require 'gearman_admin_client'
+
+require 'timeout'
+require 'securerandom'
+
+describe GearmanAdminClient do
+
+  before do
+    @sockets = []
+    @gearmand = GearmandControl.new(4730)
+    @gearmand.start
+    @gearmand.test!
+  end
+
+  after do
+    @sockets.each(&:close)
+    @gearmand.stop
+  end
+
+  def can_do(server_address, *function_names)
+    host, port = server_address.split(':')
+    socket = TCPSocket.new(host, port)
+
+    @sockets << socket
+
+    function_names.each do |function_name|
+      request(socket, 1, [function_name])
+    end
+  end
+
+  def submit_job_bg(server_address, *function_names)
+    host, port = server_address.split(':')
+    socket = TCPSocket.new(host, port)
+
+    @sockets << socket
+
+    function_names.each do |function_name|
+      id = SecureRandom.hex
+      request(socket, 18, [function_name, id, 'arg'])
+    end
+  end
+
+  def request(socket, type, arguments)
+    body = arguments.join("\0")
+    header = ["\0REQ", type, body.size].pack('a4NN')
+
+    IO::select([], [socket])
+    socket.write(header + body)
+
+    read_a_little_from(socket)
+  end
+
+  def read_a_little_from(socket)
+    begin
+      Timeout.timeout(1.0e-6, RuntimeError) do
+        IO::select([socket])
+        socket.read
+      end
+    rescue
+    end
+  end
+
+  it 'knows the server version' do
+    client = GearmanAdminClient.new(@gearmand.address)
+
+    expect(client.server_version).to match(/OK \d+\.?+/)
+  end
+
+  it 'can shutdown the server gracefully' do
+    client = GearmanAdminClient.new(@gearmand.address)
+
+    client.shutdown :graceful => true
+
+    expect do
+      @gearmand.test!
+    end.to raise_error(GearmandControl::TestFailed)
+  end
+
+  it 'can shutdown the server forcefully' do
+    client = GearmanAdminClient.new(@gearmand.address)
+
+    client.shutdown
+
+    expect do
+      @gearmand.test!
+    end.to raise_error(GearmandControl::TestFailed)
+  end
+
+  it 'can list registered workers' do
+    client = GearmanAdminClient.new(@gearmand.address)
+
+    expect(client.workers).to be_empty
+
+    can_do(@gearmand.address, 'function_1', 'function_2')
+    can_do(@gearmand.address, 'function_3')
+
+    functions = client.workers.
+      map { |worker| worker.function_names.sort }.
+      sort_by(&:size)
+
+    expect(functions).to eql([
+      ['function_3'],
+      ['function_1', 'function_2']
+    ])
+  end
+
+  it 'knows all registered functions' do
+    client = GearmanAdminClient.new(@gearmand.address)
+
+    expect(client.status).to be_empty
+
+    can_do(@gearmand.address, 'function_1', 'function_2')
+    can_do(@gearmand.address, 'function_3')
+    submit_job_bg(@gearmand.address, 'function_2', 'function_4')
+
+    expect(client.status.sort_by(&:name)).to eql([
+      { :name => 'function_1', :jobs_in_queue => 0, :running_jobs => 0,
+        :available_workers => 1 },
+      { :name => 'function_2', :jobs_in_queue => 1, :running_jobs => 0,
+        :available_workers => 1 },
+      { :name => 'function_3', :jobs_in_queue => 0, :running_jobs => 0,
+        :available_workers => 1 },
+      { :name => 'function_4', :jobs_in_queue => 1, :running_jobs => 0,
+        :available_workers => 0 }
+    ].map(&GearmanAdminClient::RegisteredFunction.method(:new)))
+  end
+
+  it 'can set the max queue size' do
+    client = GearmanAdminClient.new(@gearmand.address)
+
+    can_do(@gearmand.address, 'function_1')
+
+    client.max_queue_size('function_1', 1)
+
+    2.times do
+      submit_job_bg(@gearmand.address, 'function_1')
+    end
+
+    expect(client.status).to eql([GearmanAdminClient::RegisteredFunction.new(
+      :name => 'function_1',
+      :jobs_in_queue => 1,
+      :running_jobs => 0,
+      :available_workers => 1
+    )])
+
+    client.max_queue_size('function_1', 3)
+
+    2.times do
+      submit_job_bg(@gearmand.address, 'function_1')
+    end
+
+    expect(client.status).to eql([GearmanAdminClient::RegisteredFunction.new(
+      :name => 'function_1',
+      :jobs_in_queue => 3,
+      :running_jobs => 0,
+      :available_workers => 1
+    )])
+  end
+
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: gearman_admin_client
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Brian Cobb
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-02 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: '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: rspec
+  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: gearmand_control
+  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: virtus
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.0.beta0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.0.beta0
+description: A Ruby wrapper around the Gearman admin protocol
+email:
+- bcobb@uwalumni.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/gearman_admin_client/connection.rb
+- lib/gearman_admin_client/registered_function.rb
+- lib/gearman_admin_client/version.rb
+- lib/gearman_admin_client/worker.rb
+- lib/gearman_admin_client.rb
+- README.markdown
+- spec/gearman_admin_client_spec.rb
+homepage: http://github.com/bcobb/gearman_admin_client
+licenses: []
+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: Chat with a gearman server using its admin protocol
+test_files:
+- spec/gearman_admin_client_spec.rb