servitude 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0875adaf0bae960908e33467f31e8a15dc79bf5e
+  data.tar.gz: cbde282dc8d7eb9964168bfadcab4bc564d51ea2
+SHA512:
+  metadata.gz: ed319f26554dc51dc9bcdbe5db9e03db4c67fce36cab1fe85de5f8924f7b5102167532803781d608b9e2bb4b8b2cd1c727eeda4a8b754bd8f6430c427a318899
+  data.tar.gz: ed3c76b26403ed32f0eb10437c039b7e53b3625fbf2c8f57a99c0d0b4661e33c3c954151bfc8213d399ddf62e77a122d3c015699e7008946a12ac0bd99f79910

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.ruby-gemset

@@ -0,0 +1 @@
+servitude

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in servitude.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jason Harrelson
+
+MIT License
+
+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,229 @@
+# Servitude
+
+A set of tools for writing single or multi-threaded Ruby servers.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'servitude'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install servitude
+
+
+## Usage
+
+For executable examples see the [examples folder](https://github.com/midas/servitude/tree/master/examples).
+
+To build a server with Servitude only a couple of steps are required.
+
+* Include the Servitude::Base module in the base module of your server project.
+* Create a server class and include the Servitude::Server module (also include Servitude::ServerThreaded if you want multi-threaded server).
+* Create a CLI class and include the Servitude::Cli module.
+* If a single threaded server, implement your functionality in the Server#run method.
+* If a multi-threaded server, implement your functionality in a handler class that includes the Servitude::Actor module and call the handler from the Server#run method.
+
+For more details see the examples folder.
+
+The rest of this document will discuss the functionality each module provides.
+
+### Servitude::Actor
+
+In order to achieve well abstracted multi-threaded functionality Servitude employs the [Celluloid](https://github.com/celluloid/celluloid) gem.  The actor module simply
+abstracts some of the details of creating an actor away so you may concentrate on the functionality.  For example:
+
+    module AwesomeServer
+      class MessageHandler
+        include Servitude::Actor
+
+        def call( options )
+          # some neat functionality ...
+        end
+      end
+    end
+
+While the #call method is not a Celluloid concept, in order to integrate with the Servitude::Server's default implementation, the #call method is the 
+expected entry point to the actor.
+
+The [Celluloid wiki](https://github.com/celluloid/celluloid/wiki) does a very good job of explaining the actor pattern.  In summary, an actor is a concurrent object
+that runs in its own thread.
+
+### Servitude::Base
+
+The Base module provides core functionality for your Ruby server and should be inlcuded in the outermost namespace of your server project.  In addition to including
+the Base module, you must call the ::boot method and provide the required arguments to it.  Note, the arguments for ::boot are Ruby "required keyword arguments"
+and not a Hash.
+
+If you do not call ::boot, an error is raised before your server can be started.
+
+    module AwesomeServer
+      include Servitude::Base
+
+      boot host_namespace: AwesomeServer,
+           app_id: 'awesome-server',
+           app_name: 'Aswesome Server',
+           company: 'Awesome, Inc.',
+           default_config_path: "/etc/awesome/awesome-server.conf",
+           default_log_path: "/var/log/awesome/awesome-server.log",
+           default_pid_path: "/var/run/awesome/awesome-server.pid",
+           default_thread_count: 1,
+           version_copyright: "v#{VERSION} \u00A9#{Time.now.year} Awesome, Inc."
+    end
+
+### Servitude::Cli
+
+The Cli module provides the functionality of a Command Line Interface for your server.
+
+    module AwesomeServer
+      class Cli
+        include Servitude::Cli
+      end
+    end
+
+In your CLI file (bin/awesome-server):
+
+    #!/usr/bin/env ruby
+    require 'awesome_server'
+    AwesomeServer::Cli.new( ARGV ).run
+
+### Servitude::Configuration
+
+The Configuration module provides functionality for creating a configuration class.  You must call the ::configurations method and provide configuration
+attributes to it.  The Configuration module also provides a ::from_file method that allows a configuration to be read from a JSON config file.
+
+    module AwesomeServer
+      class Configuration
+        include Servitude::Configuration
+
+        configurations :some_config,            # attribute with no default
+                       [:another, 'some value'] # attribute with a default
+      end
+    end
+
+If you want to load your configuration from a JSON config file you may do so by registering a callback (most likely an after_initialize callback).  If the
+configuration file does not exist an error will be raised by Servitude.
+
+    module AwesomeServer
+      class Server
+        include Servitude::Server
+        
+        after_initialize do
+          Configuration.from_file( options[:config] )
+        end
+
+        # ...
+      end
+    end
+
+### Servitude::Server
+
+The Server module provides the base functionality for implementing a server, such as configuring the loggers, setting up Unix signal handling, outputting a 
+startup banner, etc.  You must override the #run method in order to implement your functionality
+
+    module AwesomeServer
+      class Server
+        include Servitude::Server
+
+        def run
+          info 'Running ...'
+        end
+      end
+    end
+
+#### Callbacks
+
+The Server module provides callbacks to utilize in your server implementation:
+
+* __before_initialize__: executes just before the initilaization of the server
+* __after_initialize__: executes immediately after initilaization of the server
+* __before_sleep__: executes just before the main thread sleeps to avoid exiting
+* __finalize__: executes before server exits
+
+You can provide one or more method names or procs to the callbacks to be executed.
+
+    module AwesomeServer
+      class Server
+        after_initialize :configure_server
+
+        finalize :cleanup
+
+        finalize do
+          info "Shutting down ..."
+        end
+
+      protected
+
+        def configure_server
+          # configuration code here ...
+        end
+
+        def cleanup
+          # cleanup code here ...
+        end
+      end
+    end
+
+You can also define callbacks on your server and use them.  The callback/hook functionality is provided by the [hooks gem](https://github.com/apotonick/hooks).
+
+    module AwesomeServer
+      class Server    
+        define_hook :before_run
+
+        before_run do
+          # do something ...
+        end
+
+        def run
+          run_hook :before_run
+          # do something ...
+        end
+      end
+    end
+
+### Servitude::ServerThreaded
+
+The ServerThreaded module extends server functionality to be multi-threaded, providing several convenience methods to abstract away correctly handling certain 
+situations Celluloid actors present.  The ServerThreaded module must be included after the Server module.
+
+    module AwesomeServer
+      class Server
+        include Servitude::Server
+        include Servitude::ServerThreaded
+      end
+    end
+
+The ServerThreaded module assumes you will use the Celluloid actor pattern to implement your functionality.  Al you must do to implement the threaded functionality 
+is override the #handler\_class method to specify the class that will act as your handler (actor) and utilize the #with_supervision block and 
+\#call_handler_respecting_thread_count method providing the options to pass to your handler's #call method.
+
+The #with_supervision block implements error handling/retry logic required to correctly interact with Celluloid supervision without bombing due to dead actor errors.
+
+    module AwesomeServer
+      class Server
+        include Servitude::Server
+        include Servitude::ServerThreaded
+
+        def run
+          some_event_generated_block do |event_args|
+            with_supervision do
+              call_handler_respecting_thread_count( info: event_args.info )
+            end
+          end
+        end
+
+        def handler_class
+          AwesomeServer::MessageHandler
+        end
+      end
+    end
+
+The #some_event_generated_block method call in the code block above represents some even that happend that needs to be processed.  All servers sleep until an event 
+happens and then do some work, respond and then go back to sleep.  Some good examples are receiving packets form a TCP/UDP socket or receiving a message from a 
+message queue.

data/Rakefile

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

data/examples/1_simple_server

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'servitude'
+
+# The simple server is as actually not a true server at all as it does nothing except for start and run (serving no
+# requests).  
+#
+# Use CTRL-c (INT signal) to stop the server. Additionally send the process an INT or TERM signal using the kill comand 
+# or your # OS's # process monitoring application.  All 3 strategies result in a graceful shutdown as displayed by the 
+# 'Shutting down ...' which occurs due to the finalize block.
+#
+# Usage:
+#   bundle exec examples/1_simple_server
+#
+module SimpleServer
+
+  include Servitude::Base
+
+  APP_FOLDER = 'simple-server'
+  VERSION    = '1.0.0'
+
+  boot host_namespace: SimpleServer,
+       app_id: 'simple-server',
+       app_name: 'Simple Server',
+       company: 'LFE',
+       default_config_path: "/usr/local/etc/#{APP_FOLDER}/#{APP_FOLDER}.conf",
+       default_log_path: "/usr/local/var/log/#{APP_FOLDER}/#{APP_FOLDER}.log",
+       default_pid_path: "/usr/local/var/run/#{APP_FOLDER}/#{APP_FOLDER}.pid",
+       default_thread_count: 1,
+       version_copyright: "v#{VERSION} \u00A9#{Time.now.year} LFE"
+
+  class Server
+
+    include Servitude::Server
+
+    finalize do
+      info 'Shutting down ...'
+    end
+
+    def run
+      info "Running ..."
+    end
+
+  end
+end
+
+SimpleServer::Server.new.start

data/examples/2_echo_server

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'servitude'
+require 'socket'
+require 'pry'
+
+# The echo server accepts a message and repeats it back.  It is the first real server in the examples.
+#
+# Note: Due to TcpServer#accept's implementation, the server is not currently gracefully shutting down as the trap of INT
+# appears to never happen.
+#
+# Usage:
+#   bundle exec examples/2_echo_server
+#
+#   Then use telent to exercise the server:
+#   $ telnet localhost 1234
+#   Hello World!
+#   You said: Hello World!
+#   Connection closed by foreign host.
+#
+module EchoServer
+
+  include Servitude::Base
+
+  APP_FOLDER = 'echo-server'
+  VERSION    = '1.0.0'
+
+  boot host_namespace: EchoServer,
+       app_id: 'echo-server',
+       app_name: 'Echo Server',
+       company: 'LFE',
+       default_config_path: "/usr/local/etc/#{APP_FOLDER}/#{APP_FOLDER}.conf",
+       default_log_path: "/usr/local/var/log/#{APP_FOLDER}/#{APP_FOLDER}.log",
+       default_pid_path: "/usr/local/var/run/#{APP_FOLDER}/#{APP_FOLDER}.pid",
+       default_thread_count: 1,
+       version_copyright: "v#{VERSION} \u00A9#{Time.now.year} LFE"
+
+  class Server
+
+    include Servitude::Server
+
+    after_initialize do
+      @tcp_server = TCPServer.open( 'localhost', '1234' )
+    end
+
+    finalize do
+      binding.pry
+      info 'Shutting down ...'
+    end
+
+    def run
+      while client = tcp_server.accept
+        line = client.gets
+        info "Received '#{line.strip}'"
+        response = "You said: #{line.strip}"
+        client.puts response 
+        info "Responded with '#{response}'"
+        info "Closing connection"
+        client.close
+      end
+    end
+
+  private
+
+    attr_reader :tcp_server
+
+  end
+end
+
+EchoServer::Server.new.start

data/lib/servitude/actor.rb

@@ -0,0 +1,13 @@
+require 'celluloid/autostart'
+
+module Servitude
+  module Actor
+
+    def self.included( base )
+      base.class_eval do
+        include Celluloid
+      end
+    end
+
+  end
+end

data/lib/servitude/base.rb

@@ -0,0 +1,54 @@
+require 'servitude'
+
+module Servitude
+  module Base
+
+    def self.included( base )
+      base.extend( ClassMethods )
+      base.class_eval do
+        class << self
+          attr_accessor :logger
+        end
+      end
+    end
+
+    module ClassMethods
+
+      def boot( host_namespace:,
+                app_id:,
+                app_name:,
+                company:,
+                default_config_path:,
+                default_log_path:,
+                default_pid_path:,
+                default_thread_count:,
+                version_copyright:)
+        Servitude::const_set :NS, host_namespace
+
+        const_set :APP_ID, app_id
+        const_set :APP_NAME, app_name
+        const_set :COMPANY, company
+        const_set :DEFAULT_CONFIG_PATH, default_config_path
+        const_set :DEFAULT_LOG_PATH, default_log_path
+        const_set :DEFAULT_PID_PATH, default_pid_path
+        const_set :DEFAULT_THREAD_COUNT, default_thread_count
+        const_set :VERSION_COPYRIGHT, version_copyright
+
+        Servitude::boot_called = true
+      end
+
+      def configuration
+        @configuration ||= Servitude::NS::Configuration.new
+      end
+
+      def configuration=( configuration )
+        @configuration = configuration
+      end
+
+      def configure
+        yield( configuration ) if block_given?
+      end
+
+    end
+  end
+end

data/lib/servitude/cli.rb

@@ -0,0 +1,136 @@
+require 'rubygems'
+require 'servitude'
+require 'trollop'
+require 'yell'
+
+module Servitude
+  module Cli
+
+    def self.included( base )
+      base.class_eval do
+        attr_reader :cmd,
+                    :options
+      end
+    end
+
+    SUB_COMMANDS = %w(
+      restart
+      start
+      status
+      stop
+    )
+
+    def initialize( args )
+      unless Servitude.boot_called
+        raise 'You must call boot before starting server'
+      end
+
+      Trollop::options do
+        version Servitude::NS::VERSION_COPYRIGHT
+        banner <<-EOS
+#{Servitude::NS::APP_NAME} #{Servitude::NS::VERSION_COPYRIGHT}
+
+Usage:
+  #{Servitude::NS::APP_ID} [command] [options]
+
+  commands:
+#{SUB_COMMANDS.map { |sub_cmd| "    #{sub_cmd}" }.join( "\n" )}
+
+  (For help with a command: #{Servitude::NS::APP_ID} [command] -h)
+
+options:
+      EOS
+        stop_on SUB_COMMANDS
+      end
+
+      # Get the sub-command and its options
+      #
+      @cmd = ARGV.shift || ''
+      @options = case( cmd )
+        when ''
+          Trollop::die 'No command provided'
+        when "restart"
+          Trollop::options do
+            opt :config, "The path for the config file", :type => String, :short => '-c', :default => Servitude::NS::DEFAULT_CONFIG_PATH
+            opt :log_level, "The log level", :type => String, :default => 'info', :short => '-o'
+            opt :log, "The path for the log file", :type => String, :short => '-l', :default => Servitude::NS::DEFAULT_LOG_PATH
+            opt :pid, "The path for the PID file", :type => String, :default => Servitude::NS::DEFAULT_PID_PATH
+            opt :threads, "The number of threads", :type => Integer, :default => Servitude::NS::DEFAULT_THREAD_COUNT, :short => '-t'
+          end
+        when "start"
+          Trollop::options do
+            opt :config, "The path for the config file", :type => String, :short => '-c', :default => Servitude::NS::DEFAULT_CONFIG_PATH
+            opt :interactive, "Execute the server in interactive mode", :short => '-i'
+            opt :log_level, "The log level", :type => String, :default => 'info', :short => '-o'
+            opt :log, "The path for the log file", :type => String, :short => '-l', :default => Servitude::NS::DEFAULT_LOG_PATH
+            opt :pid, "The path for the PID file", :type => String, :default => Servitude::NS::DEFAULT_PID_PATH
+            opt :threads, "The number of threads", :type => Integer, :default => Servitude::NS::DEFAULT_THREAD_COUNT, :short => '-t'
+          end
+        when "status"
+          Trollop::options do
+            opt :pid, "The path for the PID file", :type => String, :default => Servitude::NS::DEFAULT_PID_PATH
+          end
+        when "stop"
+          Trollop::options do
+            opt :pid, "The path for the PID file", :type => String, :default => Servitude::NS::DEFAULT_PID_PATH
+          end
+        else
+          Trollop::die "unknown command #{cmd.inspect}"
+        end
+
+      if cmd == 'start'
+        unless options[:interactive]
+          Trollop::die( :config, "is required when running as daemon" ) unless options[:config]
+          Trollop::die( :log, "is required when running as daemon" ) unless options[:log]
+          Trollop::die( :pid, "is required when running as daemon" ) unless options[:pid]
+        end
+      end
+
+      if %w(restart status stop).include?( cmd )
+        Trollop::die( :pid, "is required" ) unless options[:pid]
+      end
+    end
+
+    def self.commands( &block )
+    end
+
+    def run
+      send( cmd )
+    end
+
+  protected
+
+    def start
+      if options[:interactive]
+        start_interactive
+      else
+        start_daemon
+      end
+    end
+
+    def start_interactive
+      server = Servitude::NS::Server.new( options.merge( log: nil ))
+      server.start
+    end
+
+    def start_daemon
+      server = Servitude::Daemon.new( options )
+      server.start
+    end
+
+    def stop
+      server = Servitude::Daemon.new( options )
+      server.stop
+    end
+
+    def restart
+      stop
+      start_daemon
+    end
+
+    def status
+      Servitude::Daemon.new( options ).status
+    end
+
+  end
+end

data/lib/servitude/configuration.rb

@@ -0,0 +1,58 @@
+module Servitude
+  module Configuration
+
+    def self.included( base )
+      base.extend ClassMethods
+
+      base.class_eval do
+        class << self
+          attr_accessor :attributes,
+                        :configured
+        end
+      end
+    end
+
+    module ClassMethods
+
+      def configurations( *attrs )
+        raise 'Already configured: cannot call configurations more than once' if self.configured
+
+        self.attributes = attrs.map { |attr| Array( attr ).first.to_s }
+
+        class_eval do
+          attr_accessor( *self.attributes )
+        end
+
+        attrs.select { |attr| attr.is_a?( Array ) }.
+              each do |k, v|
+
+          define_method k do
+            instance_variable_get( "@#{k}" ) ||
+              instance_variable_set( "@#{k}", v )
+          end
+
+        end
+
+        self.configured = true
+      end
+
+      def from_file( file_path )
+        unless File.exists?( file_path )
+          raise "Configuration file #{file_path} does not exist"
+        end
+
+        options = Oj.load( File.read( file_path ))
+        Servitude::NS::configuration = Servitude::NS::Configuration.new
+
+        attributes.each do |c|
+          if options[c]
+            Servitude::NS::configuration.send( :"#{c}=", options[c] )
+          end
+        end
+
+        options[:config_loaded] = true
+      end
+
+    end
+  end
+end

data/lib/servitude/daemon.rb

@@ -0,0 +1,176 @@
+require 'rubygems'
+require 'fileutils'
+require 'timeout'
+
+module Servitude
+  class Daemon
+
+    attr_reader :name,
+                :options,
+                :pid,
+                :pid_path,
+                :script,
+                :timeout
+
+    def initialize( options )
+      @options  = options
+      @name     = options[:name] || Servitude::NS::APP_NAME
+      @pid_path = options[:pid] || '.'
+      @pid      = get_pid
+      @timeout  = options[:timeout] || 10
+    end
+
+    def start
+      abort "Process already running!" if process_exists?
+
+      pid = fork do
+        exit if fork
+        Process.setsid
+        exit if fork
+        store_pid( Process.pid )
+        File.umask 0000
+        redirect_output!
+        run
+      end
+
+      Process.waitpid( pid )
+    end
+
+    def run
+      Servitude::NS::Server.new( options ).start
+    end
+
+    def stop
+      case kill_process
+        when :success
+          remove_pid
+        when :failed_to_stop
+        when :does_not_exist
+          puts "#{Servitude::NS::APP_NAME} process is not running"
+          prompt_and_remove_pid_file if pid_file_exists?
+        else
+          raise 'Unknown return code from #kill_process'
+      end
+    end
+
+    def status
+      if process_exists?
+        puts "#{Servitude::NS::APP_NAME} process running with PID: #{pid}"
+      else
+        puts "#{Servitude::NS::APP_NAME} process does not exist"
+        prompt_and_remove_pid_file if pid_file_exists?
+      end
+    end
+
+  protected
+
+    def prompt_and_remove_pid_file
+      puts "PID file still exists at '#{pid_path}', would you like to remove it (y/n)?"
+      answer = $stdin.gets.strip
+      if answer == 'y'
+        remove_pid
+        puts "Removed PID file"
+      end
+    end
+
+    def remove_pid
+      FileUtils.rm( pid_path ) if File.exists?( pid_path )
+    end
+
+    def store_pid( pid )
+      File.open( pid_path, 'w' ) do |f|
+        f.puts pid
+      end
+    rescue => e
+      $stderr.puts "Unable to open #{pid_path} for writing:\n\t(#{e.class}) #{e.message}"
+      exit!
+    end
+
+    def get_pid
+      return nil unless File.exists?( pid_path )
+
+      pid = nil
+
+      File.open( @pid_path, 'r' ) do |f|
+        pid = f.readline.to_s.gsub( /[^0-9]/, '' )
+      end
+
+      pid.to_i
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def remove_pidfile
+      File.unlink( pid_path )
+    rescue => e
+      $stderr.puts "Unable to unlink #{pid_path}:\n\t(#{e.class}) #{e.message}"
+      exit
+    end
+
+    def kill_process
+      return :does_not_exist unless process_exists?
+
+      $stdout.write "Attempting to stop #{Servitude::NS::APP_NAME} process #{pid}..."
+      Process.kill INT, pid
+
+      iteration_num = 0
+      while process_exists? && iteration_num < 10
+        sleep 1
+        $stdout.write "."
+        iteration_num += 1
+      end
+
+      if process_exists?
+        $stderr.puts "\nFailed to stop #{Servitude::NS::APP_NAME} process #{pid}"
+        return :failed_to_stop
+      else
+        $stdout.puts "\nSuccessfuly stopped #{Servitude::NS::APP_NAME} process #{pid}"
+      end
+
+      return :success
+    rescue Errno::EPERM
+      $stderr.puts "No permission to query #{pid}!";
+    end
+
+    def pid_file_exists?
+      File.exists?( pid_path )
+    end
+
+    def process_exists?
+      return false unless pid
+      Process.kill( 0, pid )
+      true
+    rescue Errno::ESRCH, TypeError # "PID is NOT running or is zombied
+      false
+    rescue Errno::EPERM
+      $stderr.puts "No permission to query #{pid}!";
+      false
+    end
+
+    def redirect_output!
+      if log_path = options[:log]
+        #puts "redirecting to log"
+        # if the log directory doesn't exist, create it
+        FileUtils.mkdir_p( File.dirname( log_path ), :mode => 0755 )
+        # touch the log file to create it
+        FileUtils.touch( log_path )
+        # Set permissions on the log file
+        File.chmod( 0644, log_path )
+        # Reopen $stdout (NOT +STDOUT+) to start writing to the log file
+        $stdout.reopen( log_path, 'a' )
+        # Redirect $stderr to $stdout
+        $stderr.reopen $stdout
+        $stdout.sync = true
+      else
+        #puts "redirecting to /dev/null"
+        # We're not bothering to sync if we're dumping to /dev/null
+        # because /dev/null doesn't care about buffered output
+        $stdin.reopen '/dev/null'
+        $stdout.reopen '/dev/null', 'a'
+        $stderr.reopen $stdout
+      end
+      log_path = options[:log] ? options[:log] : '/dev/null'
+    end
+
+  end
+end

data/lib/servitude/logging.rb

@@ -0,0 +1,21 @@
+module Servitude
+  module Logging
+
+    %w(
+      debug
+      error
+      fatal
+      info
+      warn
+    ).each do |level|
+
+      define_method level do |*messages|
+        messages.each do |message|
+          Servitude::NS.logger.send level, message
+        end
+      end
+
+    end
+
+  end
+end

data/lib/servitude/server.rb

@@ -0,0 +1,62 @@
+require 'servitude'
+require 'hooks'
+
+module Servitude
+  module Server
+
+    def self.included( base )
+      base.class_eval do
+        include Logging
+        include ServerLogging
+        include Hooks
+
+        define_hook :after_initialize,
+                    :before_initialize,
+                    :before_sleep,
+                    :finalize
+
+        attr_reader :options
+      end
+    end
+
+    def initialize( options={} )
+      unless Servitude.boot_called
+        raise 'You must call boot before starting server'
+      end
+
+      @options = options
+
+      run_hook :before_initialize
+      initialize_loggers
+      run_hook :after_initialize
+    end
+
+    def start
+      log_startup
+      run
+
+      trap( INT )  { stop }
+      trap( TERM ) { stop }
+
+      run_hook :before_sleep
+      sleep
+    end
+
+  protected
+
+    def run
+      raise NotImplementedError
+    end
+
+  private
+
+    def finalize
+      run_hook :finalize
+    end
+
+    def stop
+      Thread.new { finalize; exit }.join
+    end
+
+  end
+end

data/lib/servitude/server_logging.rb

@@ -0,0 +1,80 @@
+require 'yell'
+
+# Provides logging services for the base server.
+#
+module Servitude
+  module ServerLogging
+
+  protected
+
+    def initialize_loggers
+      Servitude::NS.logger = Yell.new do |l|
+        l.level = log_level
+        l.adapter $stdout, :level => [:debug, :info, :warn]
+        l.adapter $stderr, :level => [:error, :fatal]
+      end
+
+      #Celluloid.logger = Yell.new do |l|
+        #l.level = :info
+        #l.adapter :file, File.join( File.dirname( options[:log] ), "#{APP_ID}-celluloid.log" )
+      #end
+    end
+
+    def log_startup
+      start_banner( options ).each do |line|
+        Servitude::NS.logger.info line
+      end
+    end
+
+    def start_banner( options )
+      configuration_attributes = Servitude::NS::Configuration.attributes rescue nil
+      [
+        "",
+        "***",
+        "* #{Servitude::NS::APP_NAME} started",
+        "*",
+        "* #{Servitude::NS::VERSION_COPYRIGHT}",
+        "*",
+        "* Configuration:",
+        (options[:config_loaded] ? "*   file: #{options[:config]}" : nil),
+        Array( configuration_attributes ).map { |a| "*   #{a}: #{config_value a}" },
+        "*",
+        "***",
+      ].flatten.reject( &:nil? )
+    end
+
+    def log_level
+      options.fetch( :log_level, :info ).to_sym
+    end
+
+
+    def config_value( key )
+      value = Servitude::NS.configuration.send( key )
+
+      return value unless value.is_a?( Hash )
+
+      return redacted_hash( value )
+    end
+
+    def redacted_hash( hash )
+      redacted_hash = {}
+
+      hash.keys.
+           collect( &:to_s ).
+           grep( /#{redacted_keys}/i ).
+           each do |blacklisted_key|
+        value = hash[blacklisted_key]
+        redacted_hash[blacklisted_key] = value.nil? ? nil : '[REDACTED]'
+      end
+
+      hash.merge( redacted_hash )
+    end
+
+    def redacted_keys
+      %w(
+        password
+      ).join( '|' )
+    end
+
+  end
+end

data/lib/servitude/server_threaded.rb

@@ -0,0 +1,62 @@
+module Servitude
+  module ServerThreaded
+
+    def self.included( base )
+      base.class_eval do
+        after_initialize :initialize_thread
+      end
+    end
+
+  protected
+
+    def with_supervision( &block )
+      begin
+        block.call
+      rescue Servitude::SupervisionError
+        # supervisor is restarting actor
+        #warn ANSI.cyan { "RETRYING due to waiting on supervisor to restart actor ..." }
+        retry
+      rescue Celluloid::DeadActorError
+        # supervisor has yet to begin restarting actor
+        #warn ANSI.blue { "RETRYING due to Celluloid::DeadActorError ..." }
+        retry
+      end
+    end
+
+    # Correctly calls a single supervised actor when the threads configuraiton is set
+    # to 1, or a pool of actors if threads configuration is > 1.  Also protects against
+    # a supervised actor from being nil if the supervisor is reinitializing when access
+    # is attempted.
+    #
+    def call_handler_respecting_thread_count( options )
+      if options[:threads] > 1
+        pool.async.call( options )
+      else
+        raise Servitude::SupervisionError unless handler
+        handler.call( options )
+      end
+    end
+
+    def handler_class
+      raise NotImplementedError
+    end
+
+    def run
+      raise NotImplementedError
+    end
+
+    def pool
+      @pool ||= handler_class.pool( size: options[:threads] )
+    end
+
+    def handler
+      Celluloid::Actor[:handler]
+    end
+
+    def initialize_thread
+      return unless options[:threads] == 1
+      handler_class.supervise_as :handler
+    end
+
+  end
+end

data/lib/servitude/supervision_error.rb

@@ -0,0 +1,5 @@
+module Servitude
+  class SupervisionError < RuntimeError
+
+  end
+end

data/lib/servitude/version.rb

@@ -0,0 +1,3 @@
+module Servitude
+  VERSION = "0.1.0"
+end

data/lib/servitude.rb

@@ -0,0 +1,24 @@
+require 'servitude/version'
+require 'rainbow'
+
+module Servitude
+
+  autoload :Actor,            'servitude/actor'
+  autoload :Base,             'servitude/base'
+  autoload :Cli,              'servitude/cli'
+  autoload :Configuration,    'servitude/configuration'
+  autoload :Daemon,           'servitude/daemon'
+  autoload :Logging,          'servitude/logging'
+  autoload :ServerLogging,    'servitude/server_logging'
+  autoload :Server,           'servitude/server'
+  autoload :ServerThreaded,   'servitude/server_threaded'
+  autoload :SupervisionError, 'servitude/supervision_error'
+
+  INT  = "INT"
+  TERM = "TERM"
+
+  class << self
+    attr_accessor :boot_called
+  end
+
+end

data/servitude.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'servitude/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "servitude"
+  spec.version       = Servitude::VERSION
+  spec.authors       = ["Jason Harrelson"]
+  spec.email         = ["jason@lookforwardenterprises.com"]
+  spec.summary       = %q{A set of utilities to aid in building multithreaded Ruby servers utilizing Celluloid.}
+  spec.description   = %q{A set of utilities to aid in building multithreaded Ruby servers utilizing Celluloid.  See README for more details.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "pry-debugger"
+  spec.add_development_dependency "rake"
+
+  spec.add_dependency "celluloid", "~> 0"
+  spec.add_dependency "hooks", "~> 0"
+  spec.add_dependency "oj", "~> 2"
+  spec.add_dependency "rainbow", "~> 2"
+  spec.add_dependency "trollop", "~> 2"
+  spec.add_dependency "yell", "~> 1"
+end

metadata

@@ -0,0 +1,194 @@
+--- !ruby/object:Gem::Specification
+name: servitude
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jason Harrelson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: pry-debugger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: celluloid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hooks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: trollop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: yell
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: A set of utilities to aid in building multithreaded Ruby servers utilizing
+  Celluloid.  See README for more details.
+email:
+- jason@lookforwardenterprises.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-gemset"
+- ".ruby-version"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/1_simple_server
+- examples/2_echo_server
+- lib/servitude.rb
+- lib/servitude/actor.rb
+- lib/servitude/base.rb
+- lib/servitude/cli.rb
+- lib/servitude/configuration.rb
+- lib/servitude/daemon.rb
+- lib/servitude/logging.rb
+- lib/servitude/server.rb
+- lib/servitude/server_logging.rb
+- lib/servitude/server_threaded.rb
+- lib/servitude/supervision_error.rb
+- lib/servitude/version.rb
+- servitude.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: A set of utilities to aid in building multithreaded Ruby servers utilizing
+  Celluloid.
+test_files: []