leech 0.1.0

data/.document

@@ -0,0 +1,8 @@
+README.md
+CHANGELOG.md
+TODO.md
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE
+VERSION

data/.gitignore

@@ -0,0 +1,24 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+*.gem
+.yardoc
+doc

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog 
+
+## Jul.29.2010
+
+*by Kriss Kowalik*
+
+Released 0.1.0 experimental version for testing. For now it provides only server.
+
+## Jul.28.2010
+
+*by Kriss Kowalik*
+
+### Misc 
+
+* Created github repository
+* Writen specs for server, handler and auth handler
+* Writen server, base handler and auth handler
+* Documentation
+* Writen README.md 
+* Created TODO.md
+* Rakefile (prepared for YARD)
+
+### Created files
+
+lib/leech.rb, lib/leech/server.rb, lib/leech/handler.rb, lib/leach/client.rb, 
+lib/handlers/auth_spec.rb, spec/spec_helper.rb, spec/spec.opts, spec/server_spec.rb, 
+spec/handler_spec.rb, spec/handlers/auth_spec.rb, LICENSE, CHANGELOG.md, VERSION, 
+README.md, Rakefile    
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Kriss Kowalik
+
+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.md

@@ -0,0 +1,132 @@
+# Leech 
+
+Leech is simple TCP client/server framework. Server is similar to rack, 
+but is designed for asynchronously handling a short text commands. It can
+be used for some monitoring purposes or simple communication between few 
+machines. 
+
+## Installation
+
+You can install Leach directly from rubygems:
+
+    gem install leach 
+    
+## Gettings started
+
+Leech is using simple TCP client/server architecture. It's a simple processor
+for text commands passed through TCP socket. 
+
+### Server
+
+Server can be created in two ways: 
+
+    server = Leech::Server.new :port => 666
+    server.use :auth
+    server.run
+
+...or using block style:
+  
+    Leech::Server.new do 
+      port 666
+      use :auth
+      run
+    end
+    
+#### Server configuration
+
+You can pass frew configuration options when you are creating new server, eg:
+
+    Leech::Server.new(port => 666, :host => 'myhost.com', :timeout => 60)
+    
+For more information about allowed parameters visit 
+[This doc page](http://yardoc.org/doc/Leech/Server.html#initialize-instance_method).
+
+#### Handlers
+
+Handlers are extending functionality of server by defining custom 
+command handling callbacks or server instance methods. 
+
+For simple commands handling you can use inline handler, which is automatically 
+used by server, eg. 
+
+    Leech::Server.new do 
+      handle(/^PRINT) (.*)$/ {|env,params| print params[0]}
+      handle(/^DELETE FILE (.*)$/) {|env,params| File.delete(params[0])}
+    end 
+
+For advanced tasks, you can write own handler, which will add new functionality
+to server instance. 
+
+    class CustomHandler < Leech::Handler
+      # This method is automaticaaly called when server will use this handler
+      def self.used(server)
+        server.instance_eval { extend ServerMethods }
+      end
+      
+      module ServerMethods
+        def say_hello
+          answer("Hello!")
+        end
+      end
+  
+      handle /^Hello server!$/, :say_hello
+      handle /^Bye!$/ do |env,params|
+        env.answer("Take care!")
+      end
+    end
+    
+To enable this handler in the server you can simply type: 
+
+    Leech::Server.new do 
+      use CustomHandler
+    end
+    
+You should notice that block-style callbacks are passing two arguments: 
+**env** - instance of server which is using this handler for processing, 
+and **params** - array of strings fetched from matched command. 
+    
+#### Answering
+
+For sending answers to clients server have the `#answer` method. It can be used
+like here: 
+
+    Leech::Server.new do
+      handle /^HELLO$/ do |env,params| env.answer("HELLO MY FRIEND!\n")
+    end 
+    
+#### Running / Listening
+
+Server is partialy acting as `Thread`. You can join it's instance so application
+will be waiting to interrupt or some unhandled server error: 
+
+    server = Leech::Server.new
+    server.run
+    server.join # on server.acceptor.join
+    
+You can also simple use:
+    
+    server.run.join
+    
+### Client
+
+Client will be implemented in 0.2.0 version. 
+
+## Links
+
+* [Author blog](http://neverendingcoding.com/)
+* [YARD documentation](http://yardoc.org/doc/Leech)
+* [Changelog](http://yardoc.org/doc/file:CHANGELOG.md)
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Kriss Kowalik. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "leech"
+    gem.summary = %Q{Simple TCP client/server framework with commands handling}
+    gem.description = %Q{Leech is simple TCP client/server framework. Server is
+    similar to rack. It allows to define own handlers for received text commands. }
+    gem.email = "kriss.kowalik@gmail.com"
+    gem.homepage = "http://github.com/kriss/leech"
+    gem.authors = ["Kriss Kowalik"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    version   = File.exist?('VERSION') ? File.read('VERSION') : ""
+    title     = "Leech #{version}"
+    t.files   = ['lib/**/*.rb', 'README*']
+    t.options = ['--title', title, '--markup', 'markdown', '--files', 'CHANGELOG.md,TODO.md']
+  end
+rescue LoadError
+  task :yard do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/TODO.md

@@ -0,0 +1,8 @@
+# TODO
+
+## 0.2.0
+
+* Client specs and implementation, 
+* Assume client helpers,
+* Client auth helpers,
+* Documentation for client.

data/VERSION

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

data/lib/leech.rb

@@ -0,0 +1,19 @@
+require 'socket'
+require 'logger'
+require 'timeout'
+require 'thread'
+
+begin
+  require 'fastthread' 
+rescue LoadError
+  $stderr.puts("The fastthread gem not found. Using standard ruby threads.")
+end
+
+# Leech is simple TCP client/server framework. Server is similar to rack, 
+# but is designed for asynchronously handling a short text commands. It can
+# be used for some monitoring purposes or simple communication between few 
+# machines. 
+module Leech
+  # Namespace for handlers. 
+  module Handlers; end
+end # Leech

data/lib/leech/client.rb

@@ -0,0 +1,7 @@
+require 'leech'
+
+module Leech
+  class Client
+    
+  end # Client
+end # Leech

data/lib/leech/handler.rb

@@ -0,0 +1,120 @@
+module Leech
+  # Handlers are extending functionality of server by defining custom 
+  # command handling callbacks or server instance methods. 
+  #
+  # @example Writing own handler
+  #     class CustomHandler < Leech::Handler
+  #       def self.used(server)
+  #         server.instance_eval { extend ServerMethods }
+  #       end
+  #     
+  #       module ServerMethods
+  #         def say_hello
+  #           answer("Hello!")
+  #         end
+  #       end
+  #
+  #       handle /^Hello server!$/, :say_hello
+  #       handle /^Bye!$/ do |env,params|
+  #         env.answer("Take care!")
+  #       end
+  #     end
+  # 
+  # @example Enabling handlers by server
+  #   Leech::Server.new { use CustomHandler }
+  #
+  # @abstract
+  class Handler
+    # Default handler error
+    class Error < StandardError; end
+     
+    # List of declared matchers
+    def self.matchers
+      @matchers ||= {}
+    end
+    
+    # It defines matching pattern and callback related with. When specified
+    # command will match this pattern then callback will be called. 
+    #
+    # @param [Regexp] patern 
+    #   Block will be executed for passed command will be maching it. 
+    # @param [Symbol, nil] method
+    #   Name of server method, which should be called when pattern will 
+    #   match with command
+    # 
+    # @example
+    #     handle(/^PRINT) (.*)$/ {|env,params| print params[0]}
+    #     handle(/^DELETE FILE (.*)$/) {|env,params| File.delete(params[0])}
+    #     handle(/^HELLO$/, :say_hello)
+    #
+    # @raise [Leech::Error]
+    #   When specified callback is not valid method name or Proc.
+    def self.handle(pattern, method=nil, &block)
+      if block_given?
+        method = block
+      end
+      if method.is_a?(Proc) || method.is_a?(Symbol)
+        self.matchers[pattern] = method
+      else
+        raise Error, "Invalid handler callback"
+      end
+    end
+    
+    # You should implement this method in your handler eg. if you would like
+    # to modify server class. 
+    def self.used(server)
+      # nothing...
+    end
+    
+    # @return [Leecher::Server]
+    #   Passed server instance
+    attr_reader :env 
+    
+    # @return [Array<String>]
+    #   Parameters matched in passed command
+    attr_reader :params
+    
+    # Constructor. 
+    #
+    # @param [Leech::Server]
+    #   Server instance
+    def initialize(env)
+      @env = env
+    end
+    
+    # Compare specified command with declared patterns.
+    #
+    # @param [String] command
+    #   Command to handle.
+    # 
+    # @return [Leech::Handler,nil] 
+    #   When command match one of declared patterns then it returns itself, 
+    #   otherwise it returns nil. 
+    def match(command)
+      self.class.matchers.each_pair do |p,m|
+        if @params = p.match(command)
+          @matcher = m
+          return self
+        end
+      end
+      nil
+    end
+    
+    # This method can be called only after #match. It executes callback 
+    # related with matched pattern. 
+    #
+    # @raise [Leech::Error] 
+    #   When @matcher is not defined, which means that #match method wasn't 
+    #   called before. 
+    def call
+      case @matcher
+      when Proc
+        @matcher.call(env, params)
+      when String, Symbol 
+        env.send(@matcher.to_sym, params)
+      else
+        raise Error, "Can not call unmatched command"
+      end
+    end
+  end # Handler
+end # Leech

data/lib/leech/handlers/auth.rb

@@ -0,0 +1,51 @@
+module Leech
+  module Handlers
+    # Simple authorization handler. It uses password string (passcode) for 
+    # authorize client session.  
+    #
+    # ### Usage
+    #     Leech::Server.new { use :auth }
+    #
+    # ### Supported commands
+    #     AUTHORIZE passcode
+    #
+    # ### Possible Answers
+    #     UNAUTHORIZED   
+    #     AUTHORIZED 
+    class Auth < Handler
+      def self.used(server)
+        server.instance_eval do 
+          extend ServerMethods
+        end
+      end
+      
+      module ServerMethods
+        # Authorize client session using simple passcode. 
+        #
+        # @param [String] passcode 
+        #   Password sent by client
+        def authorize(passcode)
+          if options[:passcode].to_s.strip == passcode.to_s.strip
+            Thread.current[:authorized] = true
+            answer("AUTHORIZED\n")
+            logger.info("Client #{info[:uri]} authorized")
+          else
+            Thread.current[:authorized] = false
+            answer("UNAUTHORIZED\n")
+            logger.info("Client #{info[:uri]} unauthorized: invalid passcode")
+          end
+        end
+        
+        # @return [Boolean] 
+        #   Is client session authorized?
+        def authorized?
+          !!Thread.current[:authorized]
+        end
+      end # ServerMethods
+      
+      # Available commands
+      
+      handle(/^AUTHORIZE[\s+]?(.*)?$/m) {|env,params| env.authorize(params[1])}
+    end # AuthHandler
+  end # Handlers
+end # Leech

data/lib/leech/server.rb

@@ -0,0 +1,370 @@
+require 'leech'
+require 'leech/handler'
+
+module Leech 
+  # This is simple TCP server similar to rack, but designed for asynchronously 
+  # handling a short text commands. It can be used for some monitoring purposes
+  # or simple communication between few machines. 
+  # 
+  # ### Creating server instance
+  #
+  # Server can be created in two ways: 
+  #
+  #     server = Leech::Server.new :port => 666
+  #     server.use :auth
+  #     server.run
+  #
+  # ...or using block style:
+  #   
+  #     Leech::Server.new do 
+  #       port 666
+  #       use :auth
+  #       run
+  #     end
+  #
+  # ### Complete server example
+  #
+  # Simple server with authorization and few commands handling can be configured 
+  # such like this one: 
+  #
+  #     server = Leech::Server.new do 
+  #       # simple authorization handler, see Leech::AuthHandler for 
+  #       # more informations. 
+  #       use :auth 
+  #     
+  #       host 'localhost'
+  #       port 666
+  #       max_workers 100
+  #       timeout 30
+  #       logger Logger.new('/var/logs/leech/server.log')
+  #     
+  #       handle /^SHOW FILE (.*)$/ do |env,params| 
+  #         if File.exists?(param[1])
+  #           answer(File.open(params[0]).read)
+  #         else
+  #           answer('NOT FOUND')
+  #         end
+  #       end
+  #       handle /^DELETE FILE (.*)$/ do |env,params| 
+  #         answer(File.delete(params[1]))
+  #       end
+  #
+  #       run
+  #     end
+  #
+  #     # Now we have to join server thread with main thread. 
+  #     server.join
+  class Server
+    # Default server error
+    class Error < StandardError; end
+    
+    # Used to stop server via Thread#raise
+    class StopServer < Error; end
+    
+    # Thrown at a thread when it is timed out.
+    class TimeoutError < Timeout::Error; end
+    
+    # Server main thread
+    #
+    # @return [Thread]
+    attr_reader :acceptor
+    
+    # Server configuration
+    #
+    # @return [Hash]
+    attr_reader :options 
+    
+    # Server will bind to this host
+    #
+    # @return [String]
+    attr_reader :host
+    
+    # Server will be listening on this port
+    #
+    # @return [Int]
+    attr_reader :port
+    
+    # Logging object
+    #
+    # @return [Logger]
+    attr_reader :logger
+    
+    # The maximum number of concurrent processors to accept, anything over 
+    # this is closed immediately to maintain server processing performance.  
+    # This may seem mean but it is the most efficient way to deal with overload.  
+    # Other schemes involve still parsing the client's request wchich defeats 
+    # the point of an overload handling system.
+    #
+    # @return [Int,Float]
+    attr_reader :max_workers
+    
+    # Maximum idle time 
+    #
+    # @return [Int,Float] 
+    attr_reader :timeout
+    
+    # A sleep timeout (in hundredths of a second) that is placed between 
+    # socket.accept calls in order to give the server a cheap throttle time.  
+    # It defaults to 0 and actually if it is 0 then the sleep is not done 
+    # at all.
+    #
+    # @return [Int,Float]
+    attr_reader :throttle
+    
+    # Here we have to define block-style setters for each startup parameter. 
+    %w{host port logger throttle timeout max_workers}.each do |meth|
+      eval <<-EVAL
+        def #{meth}(*args)
+          @#{meth} = args.first if args.size > 0
+          @#{meth}
+        end
+      EVAL
+    end
+    
+    # Creates a working server on host:port. Use #run to start the server 
+    # and `acceptor.join` to join the thread that's processing incoming requests 
+    # on the socket.
+    #   
+    # @param [Hash] opts see #options
+    # @option opts [String] :host ('localhost') see #host 
+    # @option opts [Int] :port (9933) see #port 
+    # @option opts [Logger] :logger (Logger.new(STDOUT)) see #logger
+    # @option opts [Int] :max_workers (100) see #max_workers
+    # @option opts [Int,Float] :timeout (30) see #timeout 
+    # @option opts [Int,Float] :throttle (0) see #throttle 
+    #
+    # @see Leech::Server#run
+    def initialize(opts={}, &block)
+      @handlers    = []
+      @workers     = ThreadGroup.new
+      @acceptor    = nil
+      @mutex       = Mutex.new
+      
+      @options     = opts
+      @host        = opts[:host] || 'localhost'
+      @port        = opts[:port] || 9933
+      @logger      = opts[:logger] || Logger.new(STDOUT)
+      @max_workers = opts[:max_workers] || 100
+      @timeout     = opts[:timeout] || 30
+      @throttle    = opts[:throttle].to_i / 100.0
+      
+      @inline_handler = Class.new(Leech::Handler)
+      instance_eval(&block) if block_given? 
+    end
+    
+    # Port to acceptor thread #join method.
+    #
+    # @see Thread#join
+    def join
+      @acceptor.join if @acceptor
+    end
+    
+    # It registers specified handler for using in this server instance. 
+    # Handlers are extending functionality of server by defining custom 
+    # command handling callbacks or server instance methods. 
+    #
+    # @param [Leech::Handler, Symbol] handler 
+    #   Handler class or name
+    #
+    # @raise [Leech::Server::Error,Leech::Handler::Error]
+    #   When specified adapter was not found or handler is invalid
+    #
+    # @see Leech::Handler
+    def use(handler)
+      case handler
+      when Class
+        @handlers << handler
+        handler.used(self)
+      when Symbol, String
+        begin
+          require "leech/handlers/#{handler.to_s}"
+          klass = handler.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+          use(eval("Leech::Handlers::#{klass}"))
+        rescue LoadError
+          raise Error, "Could not find #{handler} handler"
+        end
+      else
+        raise Leech::Handler::Error, "Invalid handler #{handler}"
+      end
+    end
+    
+    # It defines matching pattern in @inline_handler. It is similar to 
+    # `Leech::Handler#handle` but can be used only in block-style. 
+    #
+    # @param [Regexp] patern 
+    #   Block will be executed for passed command will be maching it. 
+    # 
+    # @example
+    #     Leech::Server.new do 
+    #       handle(/^PRINT) (.*)$/ {|env,params| print params[0]}
+    #       handle(/^DELETE FILE (.*)$/) {|env,params| File.delete(params[0])}
+    #     end
+    #  
+    # @see Leech::Handler#handle
+    def handle(pattern, &block)
+      @inline_handler.handle(pattern, &block)
+    end
+    
+    # Used internally to kill off any worker threads that have taken too long
+    # to complete processing. Only called if there are too many processors
+    # currently servicing. It returns the count of workers still active
+    # after the reap is done. It only runs if there are workers to reap.
+    #
+    # @param [String] reason 
+    #   Reason why method was executed
+    #
+    # @return  [Array<Thread>] 
+    #   List of still active workers threads. 
+    def reap_dead_workers(reason='unknown')
+      if @workers.list.length > 0
+        logger.error  "#{Time.now}: Reaping #{@workers.list.length} threads for slow workers because of '#{reason}'"
+        error_msg = "Leech timed out this thread: #{reason}"
+        mark = Time.now
+        @workers.list.each do |worker|
+          worker[:started_on] = Time.now if not worker[:started_on]
+          if mark - worker[:started_on] > @timeout + @throttle
+            logger.error "Thread #{worker.inspect} is too old, killing."
+            worker.raise(TimeoutError.new(error_msg))
+          end
+        end
+      end
+      return @workers.list.length
+    end
+    
+    # Performs a wait on all the currently running threads and kills any that take
+    # too long. It waits by `@timeout seconds`, which can be set in `#initialize`.
+    # The `@throttle` setting does extend this waiting period by that much longer.
+    def graceful_shutdown
+      while reap_dead_workers("shutdown") > 0
+        logger.error "Waiting for #{@workers.list.length} requests to finish, could take #{@timeout + @throttle} seconds."
+        sleep @timeout / 10
+      end
+    end
+    
+    # Stops the acceptor thread and then causes the worker threads to finish
+    # off the request queue before finally exiting. It's also reseting freezed 
+    # settings.
+    def stop
+      if running?
+        @acceptor.raise(StopServer.new)
+        @handlers = Array.new(@handlers)
+        @options = Hash.new(@options)
+        sleep(0.5) while @acceptor.alive?
+      end
+    end    
+    
+    # Starts serving TCP listener on host and port declared in options. 
+    # It returns the thread used so you can join it. Each client connection 
+    # will be processed in separated thread.    
+    #
+    # @return [Thread] 
+    #   Main thread for this server instance.  
+    def run
+      use(@inline_handler)
+      @socket = TCPServer.new(@host, @port)
+      @handlers = @handlers.uniq.freeze
+      @options = @options.freeze
+      @acceptor = Thread.new do 
+        begin
+          logger.debug "Starting leech server on tcp://#{@host}:#{@port}"
+          loop do 
+            begin
+              client = @socket.accept 
+              worker_list = @workers.list
+              
+              if worker_list.length >= @max_workers
+                logger.error "Server overloaded with #{worker_list.length} workers (#@max_workers max). Dropping connection."
+                client.close rescue nil
+                reap_dead_workers("max processors")
+              else
+                thread = Thread.new(client) {|c| process_client(c) }
+                thread[:started_on] = Time.now
+                @workers.add(thread)
+                sleep @throttle if @throttle > 0
+              end
+            rescue StopServer
+              break
+            rescue Errno::EMFILE
+              reap_dead_workers("too many open files")
+              sleep 0.5
+            rescue Errno::ECONNABORTED
+              client.close rescue nil
+            rescue Object => e
+              logger.error  "#{Time.now}: Unhandled listen loop exception #{e.inspect}."
+              logger.error  e.backtrace.join("\n")
+            end
+          end
+          graceful_shutdown
+        ensure
+          @socket.close  
+          logger.debug "Closing leech server on tcp://#{@host}:#{@port}"
+        end
+      end
+      
+      return @acceptor
+    end
+    
+    # It is getting information about client connection and starts conversation
+    # with him. Received commands are passed to declared handlers, where will
+    # be processed. 
+    #
+    # @param [TCPSocket] c 
+    #   Client socket
+    def process_client(c)
+      Thread.current[:client] = c
+      Thread.current[:info] = {
+        :port => client.peeraddr[1],
+        :host => client.peeraddr[2],
+        :addr => client.peeraddr[3],
+        }
+      info[:uri] = [info[:host], info[:port]].join(':')
+      logger.debug "Processing client from #{info[:uri]}"
+      while line = client.gets
+        line = line.chomp.strip
+        logger.info "Dispatching command (#{info[:uri]}): #{line}"
+        @handlers.each do |handler|
+          if handler = handler.new(self).match(line.chomp.strip)
+            handler.call
+            next
+          end
+        end
+      end
+    end
+    
+    # Sends answer to current connected socket. Method should be called only 
+    # in worker thread.
+    # 
+    # @param [String] msg 
+    #   Text to send
+    def answer(msg)
+      logger.debug("Answering to (#{info[:uri]}): #{msg.chomp.strip}")
+      client.puts(msg)
+    end
+    alias_method :say, :answer
+        
+    # @return [Boolean] 
+    #   Actual server state. Returns `true` server acceptor thread is alive.
+    def running?
+      @acceptor && @acceptor.alive?
+    end
+    
+    private
+    
+    # Informations about connected client. Method should be called only in 
+    # woker thread.
+    #
+    # @return [Hash] 
+    #   Client informations such as host, remote address and port 
+    def info
+      Thread.current[:info]
+    end
+    
+    # Client socket from. Method should be called only in woker thread.
+    #
+    # @return [TCPSocket] 
+    #   Client socket
+    def client
+      Thread.current[:client]
+    end
+  end # Server
+end # Leech

data/spec/handler_spec.rb

@@ -0,0 +1,43 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+require 'socket'
+require 'leech/handler'
+
+describe "An Leech server handler" do 
+  before do 
+    @test_handler = Class.new(Leech::Handler)
+  end
+  
+  it "should receive #used method when it's used by server" do 
+    srv = Leech::Server.new
+    @test_handler.should_receive(:used).once.with(srv)
+    srv.use(@test_handler)
+  end
+  
+  it "saves custom matchers described in #handle method" do
+    @test_handler.class_eval do 
+      handle(/^TESTING$/, :test)
+      handle(/^ANOTHER$/) {|env,params|}
+    end
+    @test_handler.matchers.keys.size.should == 2
+  end  
+  
+  it "should dispatch command to valid matcher" do 
+    @test_handler.class_eval do
+      handle /^HELLO$/, :hello
+      handle /^SECOND (.*)$/ do |env,params| "Hello"  end
+    end
+    env = OpenStruct.new
+    env.class_eval { define_method(:hello) {|p| }}
+    th = @test_handler.new(env)
+    th.match('HELLO').should be_kind_of(Leech::Handler)
+    env.should_receive(:hello).once.with(an_instance_of(MatchData))
+    th.call
+    th = @test_handler.new(env)
+    @test_handler.matchers[/^SECOND (.*)$/].should_receive(:call).once.with(env, an_instance_of(MatchData))
+    th.match('SECOND yadayada')
+    th.call
+    th = @test_handler.new(env)
+    th.match('NOT EXIST').should == nil
+    lambda { th.call }.should raise_error(Leech::Handler::Error)
+  end
+end

data/spec/handlers/auth_spec.rb

@@ -0,0 +1,59 @@
+require File.join(File.dirname(__FILE__), '../spec_helper')
+require 'socket'
+require 'leech/server'
+require 'leech/handler'
+require 'leech/handlers/auth'
+
+describe "An Leech Auth handler" do 
+  before do 
+    @srv = Leech::Server.new(:logger => Logger.new(StringIO.new))
+    @srv.use :auth
+  end
+  
+  it "should append #authorize and #authorized? methods to server instance" do 
+    @srv.should respond_to :authorize
+    @srv.should respond_to :authorized?
+  end
+  
+  it "should define matcher for AUTHORIZE command" do 
+    Leech::Handlers::Auth.matchers.size.should == 1
+    pattern = Leech::Handlers::Auth.matchers.keys.first
+    'AUTHORIZE'.should =~ pattern
+    'AUTHORIZE passcode'.should =~ pattern
+  end
+  
+  context "powered server" do
+    it "should authorize client with empty passcode when options[:passcode] is not set" do 
+      @srv.run
+      sock = TCPSocket.new(@srv.host, @srv.port)
+      sleep 1
+      sock.puts("AUTHORIZE\n")
+      sock.gets.should == "AUTHORIZED\n"
+      sock.close
+    end
+    
+    it "should authorize client with valid passcode" do 
+      @srv.options[:passcode] = 'secret'
+      @srv.run
+      sock = TCPSocket.new(@srv.host, @srv.port)
+      sleep 1
+      sock.puts("AUTHORIZE secret\n")
+      sock.gets.should == "AUTHORIZED\n"
+      sock.close
+    end
+    
+    it "should not authorize client with invalid passcode" do 
+      @srv.options[:passcode] = 'secret'
+      @srv.run
+      sock = TCPSocket.new(@srv.host, @srv.port)
+      sleep 1
+      sock.puts("AUTHORIZE not-secret\n")
+      sock.gets.should == "UNAUTHORIZED\n"
+      sock.close
+    end
+    
+    after do 
+      @srv.stop
+    end
+  end
+end

data/spec/server_spec.rb

@@ -0,0 +1,178 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+require 'socket'
+require 'leech/server'
+
+NULL_LOGGER = Logger.new(StringIO.new)
+
+describe "An new Leech server" do
+  it "should properly store passed arguments" do 
+    srv = Leech::Server.new(:host => "host", :port => 111, 1 => 2)
+    srv.host.should == "host"
+    srv.port.should == 111
+    srv.options[1] = 2
+  end
+  
+  it "should recognize max_workers option in passed arguments" do 
+    srv = Leech::Server.new(:host => "host.com", :port => 111, :max_workers => 10)
+    srv.max_workers.should == 10
+  end
+  
+  it "should recognize timeout option in passed arguments" do 
+    srv = Leech::Server.new(:host => "host.com", :port => 111, :timeout => 100)
+    srv.timeout.should == 100
+  end
+  
+  it "should recognize max_workers option in passed arguments" do 
+    srv = Leech::Server.new(:host => "host.com", :port => 111, :max_workers => 10)
+    srv.max_workers.should == 10
+  end
+  
+  it "should recognize logger option in passed arguments" do 
+    srv = Leech::Server.new(:host => "host.com", :port => 111, :logger => "logger")
+    srv.logger.should == "logger"
+  end
+  
+  it "should recognize throttle option in passed arguments" do 
+    srv = Leech::Server.new(:host => "host.com", :port => 111, :throttle => 10)
+    srv.throttle.should == 10 / 100.0
+  end
+  
+  it "should allow to pass arguments in block" do
+    srv = Leech::Server.new do 
+      use(Leech::Handler)
+      host 'myhost.com'
+      port 12345
+    end
+    srv.host.should == 'myhost.com'
+    srv.port.should == 12345
+  end 
+end
+
+describe "An instnace of Leech server" do 
+  before do
+    @srv = Leech::Server.new(:port => 'localhost', :port => 1234, :timeout => 3, 
+      :max_workers => 5, :logger => NULL_LOGGER)
+  end
+
+  it "should allow to use additional handlers" do 
+    @srv.use(handler = Class.new(Leech::Handler))
+    @srv.instance_variable_get('@handlers').should include(handler)
+  end
+  
+  it "should provide inline handler" do 
+    @srv.handle(/^TEST$/) {|env,params| }
+    inline_handler = @srv.instance_variable_get('@inline_handler')
+    inline_handler.matchers.keys.size.should == 1
+    inline_handler.matchers.should have_key(/^TEST$/)
+  end
+  
+  context "on run" do
+    before do
+      @srv.run
+    end
+  
+    it "should freeze handlers list" do 
+      @srv.instance_variable_get('@handlers').frozen?.should == true
+    end
+    
+    it "should change it's running state" do 
+      @srv.running?.should == true
+    end
+    
+    after do 
+      @srv.stop
+    end
+  end
+  
+  context "on stop" do 
+    before do 
+      @srv.run
+    end
+    
+    it "should change it's running state" do 
+      @srv.stop
+      @srv.running?.should == false
+    end
+    
+    it "should unfreeze handlers list" do
+      frozen = @srv.instance_variable_get('@handlers')
+      @srv.stop if @srv.running?
+      unfrozen = @srv.instance_variable_get('@handlers')
+      unfrozen.frozen?.should == false
+      unfrozen.should == frozen
+    end
+  end
+  
+  context "on client connection" do  
+    before do
+      @srv.handle(/^TEST MESSAGE$/) {|env,params| env.answer("HELLO\n") }
+      @srv.run
+      @sock = TCPSocket.new(@srv.host, @srv.port)
+    end
+    
+    it "should create new worker for it" do 
+      sleep 1
+      @srv.instance_variable_get('@workers').list.size.should == 1
+    end
+    
+    it "should get client informations" do 
+      sleep 1
+      info = @srv.instance_variable_get('@workers').list.first[:info]
+      info.should be_kind_of(Hash)
+      info.should have_key(:host)
+      info.should have_key(:port)
+      info.should have_key(:addr)
+      info.should have_key(:uri)
+    end
+    
+    context "when command is received" do
+      it "should handle it by matching handler" do 
+        @sock.puts("TEST MESSAGE\n")
+        answer = @sock.gets
+        answer.should == "HELLO\n"
+      end
+    end
+    
+    after do 
+      @sock.close
+      @srv.stop
+    end
+  end
+  
+  it "should handle multiple connections" do 
+    @srv.handle(/^MESSAGE FROM (.*)$/) {|env,params| env.answer("HELLO #{params[1]}\n") }
+    @srv.run
+    sock1 = TCPSocket.new(@srv.host, @srv.port)
+    sock2 = TCPSocket.new(@srv.host, @srv.port)
+    sock3 = TCPSocket.new(@srv.host, @srv.port)
+    sleep 1
+    @srv.instance_variable_get('@workers').list.size.should == 3
+    sock1.close
+    sock2.close
+    sock3.close
+    @srv.stop
+  end
+  
+  it "should handle multiple connections" do 
+    @srv.run
+    sock1 = TCPSocket.new(@srv.host, @srv.port)
+    sock2 = TCPSocket.new(@srv.host, @srv.port)
+    sock3 = TCPSocket.new(@srv.host, @srv.port)
+    sleep 1
+    @srv.instance_variable_get('@workers').list.size.should == 3
+    sock1.close
+    sock2.close
+    sock3.close
+    @srv.stop
+  end
+  
+  it "should respect :max_workers option" do 
+    @srv.run
+    sockets = []
+    8.times { sockets << TCPSocket.new(@srv.host, @srv.port) }
+    sleep 1
+    @srv.instance_variable_get('@workers').list.size.should == 5
+    sockets.each {|s| s.close }
+    @srv.stop
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rubygems'
+require 'leech'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification 
+name: leech
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Kriss Kowalik
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-28 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id001
+description: "Leech is simple TCP client/server framework. Server is\n    similar to rack. It allows to define own handlers for received text commands. "
+email: kriss.kowalik@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- .document
+- .gitignore
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- TODO.md
+- VERSION
+- lib/leech.rb
+- lib/leech/client.rb
+- lib/leech/handler.rb
+- lib/leech/handlers/auth.rb
+- lib/leech/server.rb
+- spec/handler_spec.rb
+- spec/handlers/auth_spec.rb
+- spec/server_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/kriss/leech
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Simple TCP client/server framework with commands handling
+test_files: 
+- spec/handler_spec.rb
+- spec/server_spec.rb
+- spec/spec_helper.rb
+- spec/handlers/auth_spec.rb