penctl-ruby 0.1.0

data/.gitignore

@@ -0,0 +1,2 @@
+rdoc
+pkg

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jannis Hermanns
+
+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.rdoc

@@ -0,0 +1,197 @@
+== Description
+
+penctl-ruby is a ruby implementation of penctl, a tool to control pen load
+balancers (a load balancer for "simple" tcp based protocols such as http or smtp): http://siag.nu/pen/
+
+With penctl-ruby you can add and remove servers to a pen server list and to change settings
+without the need to restart the pen balancer. Without the need for a penctl binary.
+
+While pen's regular balancing works fine, issuing commands through the control port 
+can be a bit flakey at times. That's why penctl-ruby has retries built in - it will
+try to issue your command up to five times. Important commands like add_server() and
+remove_server() make very sure pen has received them correctly and return true or false
+accordingly.
+
+keywords: balancer, pen, penctl, rails, gem
+
+== Documentation
+
+RDocs at http://rdoc.info/projects/jayniz/penctl-ruby
+
+== Installation
+
+Installing penctl-ruby is quite simple:
+
+    sudo gem install penctl-ruby -s http://gemcutter.org
+
+If you want it as plugin, just do:
+
+    script/plugin install git://github.com/jayniz/penctl-ruby.git
+
+== Basic Usage
+
+Let's say you started a pen balancer on some machine with some command
+like `pen -C 192.168.0.1:12000 192.168.0.1:12001`. You can then create a
+PenBalancer object to talk to a pen balancer running on a remote machine:
+
+    >> pen = PenBalancer.new '192.168.0.1:12000'
+    => #<PenBalancer:0x11eb74c @pen="192.168.0.1:12000">
+
+If you want to know which servers this pen is balancing requests to, you
+can issue the servers command:
+
+    >> pen.servers
+    => [{:conn=>0, :port=>12501, :hard=>0, :addr=>"127.0.0.1", :sx=>89116821, :slot=>0, :rx=>2891017284, :max=>0},
+        {:conn=>0, :port=>12101, :hard=>0, :addr=>"127.0.0.1", :sx=>3178050, :slot=>1, :rx=>46267355, :max=>0}, 
+        {:conn=>0, :port=>0, :hard=>0, :addr=>"0.0.0.0", :sx=>0, :slot=>2, :rx=>0, :max=>0}, 
+        {:conn=>0, :port=>0, :hard=>0, :addr=>"0.0.0.0", :sx=>0, :slot=>3, :rx=>0, :max=>0}]
+    
+As you can see, there are still two unused slots left. Let's make use of them!
+
+== Adding servers to the pool (or removing them)
+
+Let's add another server to the pool and check if it's there:
+
+    >> pen.add_server '127.0.0.1', 12301
+    => true
+    >> pen.servers
+    => [{:conn=>0, :port=>12501, :hard=>0, :addr=>"127.0.0.1", :sx=>89116821, :slot=>0, :rx=>2891017284, :max=>0}, 
+        {:conn=>0, :port=>12101, :hard=>0, :addr=>"127.0.0.1", :sx=>3178050, :slot=>1, :rx=>46267355, :max=>0}, 
+        {:conn=>0, :port=>12301, :hard=>0, :addr=>"127.0.0.1", :sx=>0, :slot=>2, :rx=>0, :max=>0}, 
+        {:conn=>0, :port=>0, :hard=>0, :addr=>"0.0.0.0", :sx=>0, :slot=>3, :rx=>0, :max=>0}]
+
+Actually you don't have to check if the new server is really there. After attempting to add the server
+to the pool, it retrieves the server list and makes sure the new server is really there and returns true.
+If you try to add a server to the pool that exists already, penctl-ruby will complain. Let's try
+to add the same server again
+
+    >> p.add_server '127.0.0.1', 12301
+    ArgumentError: Server is in the pool already
+      from ./lib/pen_balancer.rb:41:in `add_server'
+      from (irb):15
+
+To remove a server from the pool, you just call:
+
+    >> pen.remove_server '127.0.0.1', 12301
+    => true
+
+== Changing and reading runtime configuration
+
+There are a couple of readonly and also writeable runtime variables to pen. Most of them are also documented
+in `man penctl` (or online at http://linux.die.net/man/1/penctl). You can get/set numerical configuration 
+parameters of a remote pen balancer quite easily. 
+
+    >> pen.client_acl=3
+    => 3
+
+Fetching it goes like this:
+
+    >> pen.client_acl
+    => 3
+
+Accordingly, you can set booleans (please note that you cannot get the current value):
+    >> pen.stubborn=false
+    => false
+
+There are also values you can only read, but not write:
+
+    >> pen.conn_max
+    => 256
+
+Last but not least, you can issue some commands (telling the pen balancer to exit, if you started it
+with the -X flag, for example):
+
+    >> pen_without_x_flag.exit!
+    => ["Exit is not enabled; restart with -X flag"]
+    >> pen_with_x_flag.exit!
+    => []
+
+== Managing access control lists (ACLs)
+
+You can define 10 policies to be used for access control. They are organized in slots from
+0 to 9. To set the ACL in slot 2, you could issue:
+
+    >> pen.set_acl_entry(2, :policy => 'permit', :source_ip => '192.168.0.1', :netmask => '255.255.255.0')
+
+Now we could configure pen to use this policy for client connections:
+
+    >> p.client_acl=2
+    => 2
+    
+And to configure pen to use this policy for control port connections (don't lock yourself out :):
+
+    >> p.control_acl=2
+    => 2
+
+To remove a policy from the ACL, you would do (effectively allowing all connections):
+
+    >> p.remove_acl_entry 0
+    => []
+
+
+== API
+
+The most important functions are adding/removing and blacklisting/whitelisting servers along with
+ACL management (see above). The rest of the API is inspired by penctl's manpage:
+
+=== Boolean (you can only set, but not get, these)
+
+    pen.ascii=true            # Communication dumps in ascii format (cf option -a).
+    pen.ascii=false           # Communication dumps in hex format.
+    pen.block=true            # Do not make sockets nonblocking.
+    pen.block=false           # Make sockets nonblocking.
+    pen.delayed_forward=true  # Always wait for the next round of the main loop before 
+                              # forwarding data. Normally pen tries to do that immediately.
+    pen.delayed_forward=false # Try to forward data immediately, to avoid the overhead of
+                              # copying it to a temporary buffer and waiting for the next 
+                              # main loop round.
+    pen.hash=true             # Use a hash on the client IP address for initial server selection.
+    pen.hash=false            # Do not use a hash.
+    pen.http=true             # Add X-Forwarded-For headers to http requests.
+    pen.http=false            # Do not add X-Forwarded-For headers.
+    pen.roundrobin=true       # Use round-robin server selection without client tracking
+    pen.roundrobin=false      # Try to route the same client to the same server over time
+    pen.stubborn=true         # If the initial server selection is unavailable, close the 
+                              # client connection without trying another
+    pen.stubborn=false        # If one server does not work, use another
+    pen.weight=true           # Use weight for server selection.
+    pen.weight=false          # Do not use weight for server selection.
+
+=== Numeric (you can get and set these)
+
+    pen.blacklist=60   # Set blacklsit time to 60 seconds
+    pen.client_acl=5   # Check connecting clients against access list N (default 0).
+    pen.control_acl=3  # Check accesses to the control port against access list N (default 0).
+    pen.debug=3        # Set debug level to 3
+    pen.timeout=50     # Return current connect timeout in seconds.
+    pen.tracking=5     # Set tracking time, i.e. how long clients will be remembered. The 
+                       # default 0 will never expire clients based on time
+
+=== Readonly attributes
+    pen.clients_max  # Return max number of clients
+    pen.conn_max     # Return max number of simultaneous connections
+    pen.control      # Return (address and) port where pen listens for control connections
+    pen.listen       # Return (address and) port pen listens to for incoming client connections
+    pen.status       # Print status information in html format
+    pen.recent(5)    # Shows which clients have connected in the last N seconds (default 300)
+
+=== Commands
+    pen.exit!               # Exit. Only available if pen was started with the -X option
+    pen.include!(filename)  # Read commands from filename
+    pen.write!(filename)    # Write the current configuration into a file which can be used to
+                            # start pen. If FILE is omitted, the configuration is written into
+                            # pen's original configuration file
+
+== TODO
+
+The :log and :web_stat methods are not yet implemented
+
+== Bugs and Feedback
+
+If you discover any bugs or want to drop a line, feel free to email me: On gmail.com
+my name is jannis.
+
+penctl-ruby
+License: MIT
+Version: 0.1
+

data/Rakefile

@@ -0,0 +1,36 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "penctl-ruby"
+    gemspec.summary = "Ruby implementation of penctl"
+    gemspec.description = "With penctl-ruby you can add and remove servers to a pen server list and to change settings without the need to restart the pen balancer."
+    gemspec.email = "jannis@gmail.com"
+    gemspec.homepage = "http://github.com/jayniz/penctl-ruby"
+    gemspec.authors = ["Jannis Hermanns"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+desc 'Generate documentation for InheritedResources.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'InheritedResources'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('MIT-LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Run all specs for penctl-ruby"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+desc "Default runs specs"
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/pen_balancer.rb

@@ -0,0 +1,130 @@
+class PenBalancer
+  
+  # TODO: :log       has log, log=false and log=file
+  #       :web_stats
+  
+  BOOLEAN_ATTRIBS = [:ascii=, :block=, :control=, :delayed_forward=, :hash=, :http=, :roundrobin=, :stubborn=, :weight=]
+  GETTERS_SETTERS = [:blacklist, :client_acl, :control_acl, :debug, :tracking, :timeout]
+  GETTERS         = [:clients_max, :conn_max, :control, :listen, :status, :recent]
+  COMMANDS        = [:exit!, :include!, :write!]
+
+  #
+  #  Creates a new PenBalancer instance: If you have launched a local pen
+  #  instance with 8080 as the control port, you should use PenBalancer 
+  #  like this: PenBalancer.new 'localhost:8080'.
+  #  
+  #  Throws an exception when pen can't be reached.
+  #
+  def initialize( address )
+    @pen = address
+    raise "Can't find pen balancer at #{address}" unless Penctl.execute( @pen, "control")[0].match /#{address.split(':')[1]}/
+  end
+
+  #
+  #  Returns an array of servers pen currently knows
+  #
+  def servers
+    list = []
+    Penctl.execute(@pen, "servers", 5).each do |l| 
+      server = Penctl.parse_server_line(l)
+      list[server[:slot]] = server
+    end
+    list.compact
+  end
+
+  #
+  #  Adds a server to the pool or throws an exception when there is no free
+  #  slot left
+  #
+  def add_server( host, port )
+    raise ArgumentError.new("Server is in the pool already") if server_in_pool?( host, port)
+    free_slot = get_server( '0.0.0.0', 0 )
+    Penctl.update_server( @pen, free_slot[:slot], :address => host, :port => port)
+    server_in_pool? host, port
+  end
+  
+  #
+  #  Removes a server from the pool or throws an exception when the server
+  #  cannot be found in the pool
+  #
+  def remove_server( host, port )
+    server = get_server( host, port )
+    Penctl.update_server( @pen, server[:slot], :address => '0.0.0.0', :port => 0 )
+    !server_in_pool? host, port
+  end
+
+  #
+  #  Blacklists a server for the given amount of seconds or throws an
+  #  exception when the server cannot be found in the pool
+  #
+  def blacklist_server( host, port, blacklist_seconds = 3600)
+    server = get_server( host, port )
+    Penctl.update_server( @pen, server[:slot], :blacklist => blacklist_seconds)
+  end
+
+
+  #
+  #  A shortcut for blacklisting a server for 0 seconds.
+  #
+  def whitelist_server( host, port)
+    server = get_server( host, port )
+    Penctl.update_server( @pen, server[:slot], :blacklist => 0)
+  end
+
+  #
+  #  Updates an entry of the access control list. Params is a hash with
+  #  mandatory :policy => permit/deny and :source_ip. You can optionally
+  #  pass a :netmask.
+  #
+  def set_acl_entry( slot, params )
+    raise RangeError.new("slot #{slot} outside range 0-9")       unless (0..9).include?(slot)
+    raise ArgumentError.new("policy must be either permit or deny") unless ['permit', 'deny'].include? params[:policy]
+    Penctl.execute(@pen, "acl #{slot} #{params[:policy]} #{params[:source_ip]} #{params[:netmask]}".strip)
+  end
+  
+  #
+  #  Flushes the rules of an acl entry (==permit from all)
+  #
+  def remove_acl_entry( slot )
+    raise RangeError.new("slot #{slot} outside range 0-9") unless (0..9).include?(slot)
+    Penctl.execute(@pen, "no acl #{slot}")
+  end
+  
+  #
+  #  penctl has the following three patterns:
+  #    1) booleans (no getters): penctl localhost:8080 no ascii
+  #                              penctl localhost:8080 ascii
+  #    2) getters/setters:       penctl localhost:8080 debug 3
+  #                              penctl localhost:8080 debug
+  #    3) commands:              penctl localhost:8080 exit
+  #  The first two are turned into regular getters and setters and
+  #  the last into methods.
+  #
+  def method_missing(method, *args)
+    return Penctl.set_boolean_attribute(@pen, method, args[0])                if BOOLEAN_ATTRIBS.include? method
+    return Penctl.get_set_attribute(@pen, method, args[0])                    if GETTERS_SETTERS.include? method.to_s.chomp('=').to_sym
+    return Penctl.get_set_attribute(@pen, method, args[0])                    if GETTERS.include? method
+    return Penctl.execute(@pen, "#{method.to_s.chomp('!')} #{args[0]}".strip) if COMMANDS.include? method
+    raise "Missing method #{method}"
+  end
+  
+  protected 
+  
+  #
+  #  Fetches the list of servers currently known to pen and returns a hash with
+  #    :slot, :addr, :port, :conn, :max, :hard, :sx, :rx
+  #  Raises an exception when no server with the given address and port is in that list.
+  #
+  def get_server( host, port )
+    server_list = servers
+    server_list.select{ |s| s[:addr] == host and s[:port] == port.to_i}[0] or raise ArgumentError.new("Could not find #{host}:#{port} in #{server_list.inspect}")
+  end
+  
+  #
+  #  Checks if a given server is already in the pool
+  #
+  def server_in_pool?( host, port )
+    server_list = servers
+    !server_list.select{ |s| s[:addr] == host and s[:port] == port.to_i}.empty?
+  end
+end

data/lib/penctl.rb

@@ -0,0 +1,85 @@
+require 'socket'
+
+class Penctl
+  
+  #
+  #  Connects to pen's control port and issues a command. It will wait a moment and 
+  #  try to contact the pen server again, when it could not be reached (raising an
+  #  exception when it gives up).
+  #
+  def self.execute( server, cmd, tries_left = 5 )
+    raise StandardError.new("Error talking to pen, giving up.") unless tries_left > 0
+    shell_cmd = "penctl #{server} #{cmd}"
+    host, port = server.split ':'
+    begin
+      send_command( host, port, cmd )
+    rescue Errno::ECONNRESET, Errno::EPIPE
+      sleep 0.5
+      return Penctl.execute( server, cmd, tries_left.pred)
+    end
+  end
+
+  #
+  #  Opens a socket, sends a command to pen and returns the result
+  #
+  def self.send_command( host, port, cmd )
+    socket = TCPSocket.open( host, port.to_i )
+    socket.puts cmd
+    result = []
+    while line = socket.gets
+      result << line.chomp
+    end
+    socket.close
+    result
+  end
+
+  #
+  #  Sends a penctl server command to update a server's settings.
+  #
+  def self.update_server( server, slot, settings )
+    cmd = settings.to_a.sort_by{ |k,v| k.to_s }.flatten.join(' ')
+    Penctl.execute( server, "server #{slot} #{cmd}" )
+  end
+
+
+  #
+  #  Takes a line of the output of penctl's 'servers' command and turns it into
+  #  a hash with the keys :slot, :addr:, :port, :conn, :max, :hard, :sx, :rx
+  #
+  def self.parse_server_line( line )
+    keys = %w{ slot addr port conn max hard sx rx}
+    hash = Hash[*("slot #{line}".split)]
+    server = {}
+    keys.each { |k| server[k.to_sym] = (k == "addr") ? hash[k] : hash[k].to_i  }
+    return server
+  end
+
+  #
+  #  Takes an attribute name along with a boolean value and turns it into
+  #  a penctl command. Returns true on success, false on failure.
+  #
+  def self.set_boolean_attribute(pen, attribute, value)
+    cmd = attribute.to_s.chomp '='
+    cmd = value ? cmd : "no " + cmd
+    Penctl.execute(pen, cmd) == ["0"]
+  end
+  
+  #
+  #  Takes an attribute name along with a value and returns the value.
+  #
+  def self.get_set_attribute(pen, attribute, value = nil)
+    cmd   = attribute.to_s.chomp '='
+    value = value.to_s.empty? ? '' : " #{value}"
+    tidy_output(Penctl.execute(pen, "#{cmd}#{value}".chomp))
+  end
+  
+  protected
+  
+  def self.tidy_output( values )
+    if values.size == 1
+      values[0].match(/^[\d]+$/) ? values[0].to_i : values[0]
+    else
+      values
+    end
+  end
+end

data/penctl-ruby.gemspec

@@ -0,0 +1,52 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{penctl-ruby}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jannis Hermanns"]
+  s.date = %q{2009-09-28}
+  s.description = %q{With penctl-ruby you can add and remove servers to a pen server list and to change settings without the need to restart the pen balancer.}
+  s.email = %q{jannis@gmail.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/pen_balancer.rb",
+     "lib/penctl.rb",
+     "penctl-ruby.gemspec",
+     "rails/init.rb",
+     "spec/lib/pen_balancer_spec.rb",
+     "spec/lib/penctl_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/jayniz/penctl-ruby}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{Ruby implementation of penctl}
+  s.test_files = [
+    "spec/lib/pen_balancer_spec.rb",
+     "spec/lib/penctl_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/rails/init.rb

@@ -0,0 +1,2 @@
+require 'lib/pen_balancer'
+require 'lib/penctl'

data/spec/lib/pen_balancer_spec.rb

@@ -0,0 +1,152 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+require 'lib/pen_balancer'
+require 'lib/penctl'
+
+describe PenBalancer do
+
+  describe "methods implementing the commands from `man penctl` (except for acl and server)" do
+    
+    before(:each) do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", "control").and_return ["127.0.0.1:12000"]
+      @pen = PenBalancer.new '127.0.0.1:12000'
+    end
+    
+    it ":servers should return an array of hashes with the servers pen currently knows" do
+      servers_reply = ["0 addr 127.0.0.1 port 12101 conn 0 max 0 hard 0 sx 1054463671 rx 2586728338", "1 addr 127.0.0.1 port 12501 conn 1 max 0 hard 0 sx 1103014051 rx 2688785671"]
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", "servers", 5).and_return servers_reply
+
+      result = @pen.servers
+      result.should have(2).items
+      result[0].should be_a(Hash)
+      result[1].should be_a(Hash)
+    end
+    
+    it "should set boolean variables (e.g. pen.http=true)" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'http')
+      @pen.http = true
+    end
+    
+    it "should set boolean variables (e.g. pen.http=false)" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'no http')
+      @pen.http = false
+    end
+    
+    it "should set other variables (e.g. pen.debug=5)" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'debug 5').and_return ["5"]
+      @pen.debug = 5
+    end
+    
+    it "should get other variables (e.g. pen.debug)" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'debug').and_return ["5"]
+      @pen.debug.should == 5
+    end
+    
+    it "should get readonly variables (e.g. pen.status)" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'status').and_return ["lots", "of", "lines"]
+      @pen.status.should == ["lots", "of", "lines"]
+    end
+    
+    it "should get readonly variables with a parameter (e.g. pen.recent(5))" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'recent 5').and_return ["lots", "of", "lines"]
+      @pen.recent(5).should == ["lots", "of", "lines"]
+    end
+    
+    it "should issue commands (e.g. pen.exit!)" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'exit').and_return []
+      @pen.exit!
+    end
+    
+    it "should issue commands with parameters (e.g. pen.write! /etc/pen.conf)" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'write /etc/pen.conf').and_return []
+      @pen.write!('/etc/pen.conf').should be_true
+    end
+    
+    it "should return false when a command could not be issued" do
+      Penctl.should_receive(:execute).with("127.0.0.1:12000", 'exit').and_return ["Exit is not enabled; restart with -X flag"]
+      @pen.exit!
+    end
+    
+  end
+
+  describe "methods making the penctl commands [no] acl and server more convenient" do
+    
+    describe "adding or removing servers from the pool" do
+      
+      before(:each) do
+        Penctl.should_receive(:execute).with("127.0.0.1:12000", "control").and_return ["127.0.0.1:12000"]
+        @pen = PenBalancer.new '127.0.0.1:12000'
+        servers_reply = ["0 addr 127.0.0.1 port 100 conn 0 max 0 hard 0 sx 1054463671 rx 2586728338",
+                         "1 addr 127.0.0.1 port 101 conn 1 max 0 hard 0 sx 1103014051 rx 2688785671",
+                         "2 addr 0.0.0.0 port 0 conn 0 max 0 hard 0 sx 0 rx 0",
+                         "3 addr 0.0.0.0 port 0 conn 0 max 0 hard 0 sx 0 rx 0"]
+        Penctl.should_receive(:execute).with("127.0.0.1:12000", "servers", 5).at_least(1).and_return servers_reply
+      end
+      
+      it "should add a server into an empty slot" do
+        Penctl.should_receive(:update_server).with('127.0.0.1:12000', 2, :address => '127.0.0.1', :port => 102)
+        @pen.should_receive(:server_in_pool?).with('127.0.0.1', 102).and_return false
+        @pen.should_receive(:server_in_pool?).with('127.0.0.1', 102).and_return true
+        @pen.add_server('127.0.0.1', 102).should be_true
+      end
+      
+      it "should remove a server freeing a slot" do
+        Penctl.should_receive(:update_server).with('127.0.0.1:12000', 1, :address => '0.0.0.0', :port => 0)
+        @pen.should_receive(:server_in_pool?).with('127.0.0.1', 101).and_return false
+        @pen.remove_server('127.0.0.1', 101).should be_true
+      end
+      
+      it "should raise an exception when given server could not be found in the list" do
+        lambda {
+          @pen.remove_server('127.0.0.2', 100)
+        }.should raise_error(ArgumentError)
+      end
+      
+      it "should raise an exception when adding a server that is already in the list" do
+        lambda {
+          @pen.add_server('127.0.0.1', 100)
+        }.should raise_error(ArgumentError)
+      end
+      
+      it "should blacklist a server" do
+        Penctl.should_receive(:update_server).with('127.0.0.1:12000', 0, :blacklist => 999)
+        @pen.blacklist_server('127.0.0.1', 100, 999)
+      end
+
+      it "should whitelist a server" do
+        Penctl.should_receive(:update_server).with('127.0.0.1:12000', 0, :blacklist => 0)
+        @pen.whitelist_server('127.0.0.1', 100)
+      end
+
+    end
+  
+    
+    describe "managing access control lists" do
+      
+      before(:each) do
+        Penctl.should_receive(:execute).with("127.0.0.1:12000", "control").and_return ["127.0.0.1:12000"]
+        @pen = PenBalancer.new '127.0.0.1:12000'
+      end
+      
+      it ":set_acl_entry should set access control list with netmask" do
+        Penctl.should_receive(:execute).with("127.0.0.1:12000", "acl 2 permit 192.168.0.1 255.255.255.0")
+        @pen.set_acl_entry(2, :policy => 'permit', :source_ip => '192.168.0.1', :netmask => '255.255.255.0')
+      end
+      
+      it ":set_acl_entry should set access control list without netmask" do
+        Penctl.should_receive(:execute).with("127.0.0.1:12000", "acl 2 permit 192.168.0.1")
+        @pen.set_acl_entry(2, :policy => 'permit', :source_ip => '192.168.0.1')
+      end
+      
+      it ":set_acl_entry should remove access control (allow from all)" do
+        Penctl.should_receive(:execute).with("127.0.0.1:12000", "no acl 2")
+        @pen.remove_acl_entry(2)
+      end
+      
+      it ":set_acl_entry should raise an exception when given ACL list is out of range [0..9]" do
+        lambda {
+          @pen.set_acl_entry(10, :policy => 'deny', :source_ip => '127.0.0.1')
+        }.should raise_error(RangeError)
+      end
+    end
+  end
+end

data/spec/lib/penctl_spec.rb

@@ -0,0 +1,53 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+require 'lib/penctl'
+
+describe Penctl do
+  
+  it ":execute should call the penctl binary and contact the right pen" do
+    socket = mock("socket")
+    socket.should_receive(:puts).with "foo"
+    socket.should_receive(:gets).and_return "something"
+    socket.should_receive(:gets).and_return false
+    socket.should_receive(:close)
+    TCPSocket.should_receive(:open).with("127.0.0.1", 12000).and_return socket
+    Penctl.execute( "127.0.0.1:12000", "foo").should == ["something"]
+  end
+  
+  it ":parse_server_line should turn penctl servers output into a hash" do
+    line = "1 addr 127.0.0.1 port 12501 conn 2709 max 2212 hard 2 sx 1092895943 rx 2664422154"
+    expected = { :slot => 1,
+                 :addr => '127.0.0.1',
+                 :port => 12501,
+                 :conn => 2709,
+                 :max  => 2212,
+                 :hard => 2,
+                 :sx   => 1092895943,
+                 :rx   => 2664422154 }
+    Penctl.parse_server_line(line).should == expected
+  end
+  
+  it ":update_server should change server settings" do
+    Penctl.should_receive(:execute).with("127.0.0.1:12000", "server 1 address 127.0.0.1 port 88")
+    Penctl.update_server '127.0.0.1:12000', 1, :address => '127.0.0.1', :port => 88
+  end
+  
+  it ":set_boolean_attribute should turn true into the right penctl command" do
+    Penctl.should_receive(:execute).with("127.0.0.1:12000", "foo")
+    Penctl.set_boolean_attribute('127.0.0.1:12000', 'foo', true)
+  end
+  
+  it ":set_boolean_attribute should turn true into the right penctl command" do
+    Penctl.should_receive(:execute).with("127.0.0.1:12000", "no foo")
+    Penctl.set_boolean_attribute('127.0.0.1:12000', 'foo', false)
+  end
+
+  it ":get_set_attribute should set some attribute's value" do
+    Penctl.should_receive(:execute).with("127.0.0.1:12000", "foo bar").and_return ["0"]
+    Penctl.get_set_attribute('127.0.0.1:12000', 'foo=', 'bar')
+  end
+  
+  it ":get_set_attribute should get some attribute's value" do
+    Penctl.should_receive(:execute).with("127.0.0.1:12000", "foo").and_return ["0"]
+    Penctl.get_set_attribute('127.0.0.1:12000', 'foo')
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'spec' 
+RAILS_ENV="test"

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: penctl-ruby
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Jannis Hermanns
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-28 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: With penctl-ruby you can add and remove servers to a pen server list and to change settings without the need to restart the pen balancer.
+email: jannis@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/pen_balancer.rb
+- lib/penctl.rb
+- penctl-ruby.gemspec
+- rails/init.rb
+- spec/lib/pen_balancer_spec.rb
+- spec/lib/penctl_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/jayniz/penctl-ruby
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: Ruby implementation of penctl
+test_files: 
+- spec/lib/pen_balancer_spec.rb
+- spec/lib/penctl_spec.rb
+- spec/spec_helper.rb