cwgem-selectserver 0.2.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in cwgem-selectserver.gemspec
+gemspec

data/README.markdown

@@ -0,0 +1,77 @@
+## Getting Started ##
+
+A basic select multiplexing based TCP server. Client connections are handled by a method handler or a block handler. The basic format for handlers is:
+
+```ruby
+def handler(server, client_socket)
+end
+
+server = Cwgem::SelectServer.new("localhost", 3555)
+server.setup_method_handler(method(:handler))
+server.start
+```
+
+Where server is the server object itself, and client socket is the socket of the client. The server is passed in so you can do things like shutding down the server based on a client command:
+
+```ruby
+def handler(server,client_socket)
+  command = client_socket.gets
+  server.shutdown if command.chomp! == "exit"
+end
+
+server = Cwgem::SelectServer.new("localhost", 3555)
+server.setup_method_handler(method(:handler))
+server.start
+```
+
+Blocks can also be used as client connection handlers:
+
+```ruby
+server = Cwgem::SelectServer.new("localhost", 3555)
+server.start do | server, client_socket |
+end
+```
+
+Note that either a method handler must be setup before calling server.start, or a block passed into it. Failure to do so will result in an ArgumentError:
+
+```ruby
+server = Cwgem::SelectServer.new("localhost", 3555)
+server.start # this will throw ArgumentError since no handler is setup
+```
+
+If you need to carry around extra metadata for client connections, the best method is to override the accept method and extend the socket through a module. In this example the client socket has a username attribute added to it by extending a ChatClient module.
+
+```ruby
+module ChatClient
+  attr_accessor :username
+end
+
+server = Cwgem::SelectServer.new("localhost", 3555)
+def server.accept
+  client = self.accept
+  client.extend(ChatClient)
+  @sockets << client
+end
+
+server.start do | server, socket |
+  1
+end
+```
+
+## Example ##
+
+This example is an embedded ruby script that can be run using `ruby -x Readme.markdown`. It binds to localhost on port 3555, and acts as a simple echo server. The simple server can be shutdown by sending the USR1 signal `kill -USR1 [processid]`.
+
+```ruby
+#! ruby
+
+require 'cwgem-selectserver'
+
+server = Cwgem::SelectServer.new("localhost", 3555)
+Signal.trap("USR1") { server.shutdown; server.shutdown_handler; exit }
+server.start do | server, socket |
+  data = socket.gets
+  socket.write data
+end
+__END__
+```

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/cwgem-selectserver.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cwgem-selectserver/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cwgem-selectserver"
+  s.version     = Cwgem::SelectServer::VERSION
+  s.authors     = ["Chris White"]
+  s.email       = ["cwprogram@live.com"]
+  s.homepage    = ""
+  s.summary     = %q{A basic TCP server that uses IO.select multiplexing}
+  s.description = %q{A basic TCP server that uses IO.select multiplexing}
+
+  s.rubyforge_project = "cwgem-selectserver"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/cwgem-selectserver/version.rb

@@ -0,0 +1,5 @@
+module Cwgem
+  class SelectServer
+    VERSION = "0.2.0"
+  end
+end

data/lib/cwgem-selectserver.rb

@@ -0,0 +1,97 @@
+require 'socket'
+
+module Cwgem
+  # @author Chris White
+  class SelectServer < ::TCPServer
+
+    # Setups up the server by binding to the host and port, adding the server
+    # socket to the list of sockets to check for, and initializing the
+    # client socket handler and server_active (used as a main loop check) variables
+    #
+    # @param [String] The host to bind to
+    # @param [Integer] The port to bind to
+    def initialize(host,port)
+      super
+      @sockets = [self]
+      @handler = nil
+      @server_active = true
+    end
+
+    # Sets a method based handler for the main server loop
+    # 
+    # @param [Object] Any object that can respond to .call
+    def setup_method_handler(method_handler)
+      @handler = method_handler
+    end
+
+    # The main server loop. ArgumentError is raised if a handler is not set.
+    #
+    # @param [Object] If a block is given, it will be called with the server and client socket as arguments
+    def start(&block)
+      raise ArgumentError, "method handler must be set or block must be given" if 
+        (!@handler or !@handler.respond_to?(:call)) and !block_given?
+
+      @handler = block if block_given?
+
+      while @server_active == true
+        readable_sockets,writable_sockets,exception_sockets = IO.select(@sockets,[], @sockets)
+
+        readable_sockets.each do | read_socket |
+          if read_socket == self
+            accept_client
+          else
+            begin
+              # Remove closed connections. An exception is raised
+              # if this is a dead socket, which we handle below
+              # by simply removing the socket.
+              if read_socket.closed? or read_socket.eof?
+                remove_client read_socket
+              else
+                @handler.call(self,read_socket)
+              end
+            rescue
+              remove_client read_socket
+            end
+          end
+        end
+
+        exception_sockets.each do | err_socket |
+          remove_client err_socket
+        end
+
+      end
+
+      shutdown_handler
+    end
+
+    # Accept a client socket and add it to the list of active
+    # sockets
+    def accept_client
+      client = self.accept
+      @sockets << client
+    end
+
+    # Remove a client socket from the list of active sockets
+    #
+    # @param [TCPSocket] The client socket to remove
+    def remove_client(client_socket)
+      @sockets.reject! { | socket | socket == client_socket }
+    end
+
+    # This sets a flag which will halt the main loop. The purpose of this method
+    # is to allow the main loop to finish its tasks before shutting everything
+    # down
+    def shutdown
+      @server_active = false
+    end
+
+    # Now that the server's main loop has finished processing, shutdown
+    # the server
+    def shutdown_handler
+      self.close unless self.closed?
+      @sockets = []
+    end
+
+  end #end class SelectServer
+
+end

data/test/select_server_block_handler.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'cwgem-selectserver'
+
+port = ARGV[0].to_i
+server = Cwgem::SelectServer.new("localhost", port)
+Signal.trap("USR1") { server.shutdown; server.shutdown_handler; exit }
+server.start do | server, socket |
+  data = socket.gets
+  socket.write data
+  server.shutdown
+end

data/test/select_server_global_method_handler.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'cwgem-selectserver'
+
+def handle_client(server,socket)
+  data = socket.gets
+  socket.write data
+  server.shutdown
+end
+
+port = ARGV[0].to_i
+server = Cwgem::SelectServer.new("localhost", port)
+Signal.trap("USR1") { server.shutdown; server.shutdown_handler; exit }
+server.setup_method_handler(method(:handle_client))
+server.start

data/test/select_server_instance_method_handler.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require 'cwgem-selectserver'
+
+class ClientHandler
+  def handle_client(server,socket)
+    data = socket.gets
+    socket.write data
+    server.shutdown
+  end
+end
+
+port = ARGV[0].to_i
+server = Cwgem::SelectServer.new("localhost", port)
+Signal.trap("USR1") { server.shutdown; server.shutdown_handler; exit }
+server.setup_method_handler(ClientHandler.new.method(:handle_client))
+server.start

data/test/select_server_test.rb

@@ -0,0 +1,53 @@
+require 'test/unit'
+require 'socket'
+require 'cwgem-selectserver'
+
+class TestSelectServer < Test::Unit::TestCase
+
+  def test_bind_to_port
+    server = Cwgem::SelectServer.new("127.0.0.1", 8555)
+    assert_raise(Errno::EADDRINUSE) do
+        other_server = TCPServer.new "127.0.0.1", 8555
+    end
+    server.shutdown_handler
+  end
+
+  def test_no_handler
+    server = Cwgem::SelectServer.new("127.0.0.1", 8555)
+    assert_raise(ArgumentError) do
+      server.start
+    end
+    server.shutdown_handler
+  end
+
+  def test_instance_method_handler
+    check_server "select_server_instance_method_handler.rb", 8555
+  end
+
+  def test_global_method_handler
+    check_server "select_server_global_method_handler.rb", 8555
+  end
+
+  def test_block_handler
+    check_server "select_server_block_handler.rb", 8555
+  end
+
+  def check_server(server_filename, port)
+    server_cmd = File.dirname(File.expand_path(__FILE__)) << "/#{server_filename} #{port}"
+    pipe = IO.popen(server_cmd)
+    # Sleep for 2 seconds to let the server bind
+    sleep 2
+
+    client = TCPSocket.new("localhost", port)
+    client.puts "Client Data"
+    data = client.gets
+    assert_equal(data, "Client Data\n")
+    client.close
+    
+    ensure
+      # Be safe and send the server a shutdown signal
+      # in case the socket communication fails
+      Process.kill("USR1", pipe.pid)
+  end
+
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: cwgem-selectserver
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- Chris White
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-09-15 00:00:00.000000000 Z
+dependencies: []
+description: A basic TCP server that uses IO.select multiplexing
+email:
+- cwprogram@live.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.markdown
+- Rakefile
+- cwgem-selectserver.gemspec
+- lib/cwgem-selectserver.rb
+- lib/cwgem-selectserver/version.rb
+- test/select_server_block_handler.rb
+- test/select_server_global_method_handler.rb
+- test/select_server_instance_method_handler.rb
+- test/select_server_test.rb
+homepage: ''
+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: cwgem-selectserver
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A basic TCP server that uses IO.select multiplexing
+test_files:
+- test/select_server_block_handler.rb
+- test/select_server_global_method_handler.rb
+- test/select_server_instance_method_handler.rb
+- test/select_server_test.rb