servitude 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0875adaf0bae960908e33467f31e8a15dc79bf5e
-  data.tar.gz: cbde282dc8d7eb9964168bfadcab4bc564d51ea2
+  metadata.gz: 11b7ea1e73f25eb1270966889eb4341dd269657a
+  data.tar.gz: ab47729667a4604e5fb23bd1976b160d96d7b6e8
 SHA512:
-  metadata.gz: ed319f26554dc51dc9bcdbe5db9e03db4c67fce36cab1fe85de5f8924f7b5102167532803781d608b9e2bb4b8b2cd1c727eeda4a8b754bd8f6430c427a318899
-  data.tar.gz: ed3c76b26403ed32f0eb10437c039b7e53b3625fbf2c8f57a99c0d0b4661e33c3c954151bfc8213d399ddf62e77a122d3c015699e7008946a12ac0bd99f79910
+  metadata.gz: c13a26dda70ac70166e95038910e07692809df93cd82ec8b348b863a5fff729acdc5c8df004ed922f7c7f234b93779b7b58aff0de6e750125e480519bd0b0589
+  data.tar.gz: f7cb8d3b33788691a07f726db705d15a18adb5699ce545e9803e72af6210131be950f579f4a586dd2faf1bbef7f776684e92368373354dbd8d098ea0132281cc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/README.md

@@ -95,33 +95,148 @@ In your CLI file (bin/awesome-server):
 
 ### 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.
+All Servitude servers automatically have a configuration instantiated for them (although it may be empty).  The default class for the configuration is
+Servitude::Configuration.  In order to define a custom configuration, define a custom configuraiton class (which may inherit from Servitude::Configuration)
+and simply override the Servitude::Server#configuration method in your Server class.  Be sure the custom configuration calss accepts the command line
+options and passes them to the super class's initializer or configuration will be completely broken.
 
     module AwesomeServer
-      class Configuration
-        include Servitude::Configuration
+      class Configuration < Servitude::Configuration
+        def initialize( cli_options )
+          super( cli_options )
+          # possibly do something else ...
+        end
+      end
+
+      class Server
+        include Servitude::Server
 
-        configurations :some_config,            # attribute with no default
-                       [:another, 'some value'] # attribute with a default
+        def configuration_class
+          AwesomeServer::Configuration
+        end
       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.
+The Servitude::Configuration class delegates to a [Hashie::Mash](https://github.com/intridea/hashie#mash) backend, which gives it great flexibiltiy.
+Any Hash or JSON like structure can be passed directly into the configuration and work.  Thus, one does not have to explicitly define the configuration 
+attributes as the configuration will represent exactly what is in the JSON config file.  In addition, the command line options are passed into the 
+configuration and merged to the configuration that came from a config file (if there is a config file).  The merge results in the command line options 
+overriding any matching file configurations.
+
+For example, given a config file:
+
+    {
+      "key1": "value1",
+      "log_level": "info",
+      "envs": {
+        "development": {
+          "key2": "value2",
+        },
+        "production": {
+          "key2": "value3",
+        }
+      }
+    }
+
+And command line options of:
+
+    $ awesome-server start --interactive --log_level debug
+
+The configuration result will be:
+
+    {
+      "key1": "value1",
+      "log_level": "debug",
+      "interactive": true,
+      "envs": {
+        "development": {
+          "key2": "value2",
+        },
+        "production": {
+          "key2": "value3",
+        }
+      }
+    }
+
+Notice the log_level has been overridden to the command line option value instead of the file value.  Because the command line options are an inherently
+flass structure, any config file options that should be overridden should be at the first level of the JSON structure.
+
+Because Hashie::Mash is the backend for the configuration values may be accessed using a hash notation or an object notation.
+
+    config['key1'] # => "value1"
+    config[:key1]  # => "value1"
+    config.key1    # => "value1"
+
+    config['development']['key2'] # => "value2"
+    config[:development][:key2]   # => "value2"
+    config.development.key2       # => "value2"
+
+The startup banner for a Servitude server automatically outputs the ocnfiguration options in a dot notation format.  Continuing our configuraiton example,
+the smart banner would look like:
+
+    ***
+    * Awesome Server started
+    *
+    * v1.0.0 ©2014 Awesome Company
+    *
+    * Configuration
+    *  config: /Users/cjharrelson/development/personal/gems/servitude/config/echo-server.conf
+    *  log_level: debug
+    *  log: STDOUT
+    *  pid: /Users/cjharrelson/development/personal/gems/servitude/tmp/echo-server.pid
+    *  threads: 1
+    *  key1: value1
+    *  envs.development.key2: value2
+    *  envs.production.key2: value3
+    *
+    ***
+
+You may notice the absence of the interactive value.  This is due to filtering built into the start banner output.  Several values are already in the 
+default_config_filters that are a result of the Trollop implementation of the command line option parsing.  If you would like to add additional keys 
+to be filterd, override the config_filters method in your server class and provide an array of keys (in dot notation) to filter.
 
     module AwesomeServer
       class Server
-        include Servitude::Server
-        
-        after_initialize do
-          Configuration.from_file( options[:config] )
+        ...
+        def config_filters
+          %w(
+            key1
+            envs.development.key2
+          )
         end
+        ...
+      end
+    end
+
+### Servitude::EnvironmentConfiguration
 
-        # ...
+Building upon Servitude::Configuration, the EnvironmentConfiguration adds the concept of environments to configuration.  In order to use 
+EnvironmentConfiguration override #configuration_class in your server class.
+
+    module AwesomeServer
+      class Server
+        include Servitude::Server
+
+        def configuration_class
+          Servitude::EnvironmentConfiguration
+        end
       end
     end
 
+The command line can except and --environment (-e) switch, although it is not required.  If using config file and environemnt, a best practice is to put
+the default environment in your config file so there is a default environment.
+
+    {
+      "environment": "development",
+      "development": {
+        ...
+      },
+      "production": {
+        ...
+      }
+    }
+
+
 ### 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 
@@ -143,6 +258,7 @@ 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_run: executes just before the run method is called
 * __before_sleep__: executes just before the main thread sleeps to avoid exiting
 * __finalize__: executes before server exits
 

data/config/4.conf

@@ -0,0 +1,6 @@
+{
+  "key1": "value1",
+  "key2": {
+    "key3": "value3"
+  }
+}

data/config/5.conf

@@ -0,0 +1,10 @@
+{
+  "key1": "value1",
+  "environment": "production",
+  "development": {
+    "key2": "value2"
+  },
+  "production": {
+    "key2": "value3"
+  }
+}

data/examples/1_simple_server

@@ -20,14 +20,17 @@ module SimpleServer
   APP_FOLDER = 'simple-server'
   VERSION    = '1.0.0'
 
+  PROJECT_ROOT = File.expand_path( '../..', __FILE__ )
+  
   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,
+       use_config: false,
+       default_config_path: nil,
+       default_log_path: nil,
+       default_pid_path: nil,
+       default_thread_count: nil,
        version_copyright: "v#{VERSION} \u00A9#{Time.now.year} LFE"
 
   class Server

data/examples/2_echo_server

@@ -26,14 +26,17 @@ module EchoServer
   APP_FOLDER = 'echo-server'
   VERSION    = '1.0.0'
 
+  PROJECT_ROOT = File.expand_path( '../..', __FILE__ )
+  
   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,
+       use_config: false,
+       default_config_path: nil,
+       default_log_path: nil,
+       default_pid_path: nil,
+       default_thread_count: nil,
        version_copyright: "v#{VERSION} \u00A9#{Time.now.year} LFE"
 
   class Server
@@ -45,7 +48,6 @@ module EchoServer
     end
 
     finalize do
-      binding.pry
       info 'Shutting down ...'
     end
 

data/examples/3_echo_server_with_cli_and_daemon

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'servitude'
+require 'socket'
+require 'trollop'
+require 'pry'
+
+# The echo server accepts with CLI builds on the 2_echo_server example, addiing a command line interface.
+#
+# Note: Due to TcpServer#accept's implementation, the server is not currently gracefully shutting down as the trap of INT
+# appears to never happen.
+#
+# The CLI has 4 sub-commands: start, stop, status and restart.
+#
+# Using the -i of --interactive switch on the start command will run the server attached in the terminal you execute the command
+# in.  Without the interactive switch, the server will run as a daemon.  The start, stop, and status commands are used to control
+# the daemonized process.  If run in daemon mode, you can tail the log:
+#
+# $ tail -f tmp/echo-server.log
+#
+# Usage:
+#   Help:
+#     bundle exec examples/3_echo_server_with_cli_and_daemon -h
+#
+#   Start (interactive):
+#     bundle exec examples/3_echo_server_with_cli_and_daemon start -i
+#
+#   Then use telnet 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'
+
+  PROJECT_ROOT = File.expand_path( '../..', __FILE__ )
+  
+  boot host_namespace: EchoServer,
+       app_id: 'echo-server-with-cli',
+       app_name: 'Echo Server With CLI',
+       company: 'LFE',
+       use_config: false,
+       default_config_path: "#{PROJECT_ROOT}}/config/#{APP_FOLDER}.conf",
+       default_log_path: "#{PROJECT_ROOT}/tmp/#{APP_FOLDER}.log",
+       default_pid_path: "#{PROJECT_ROOT}/tmp/#{APP_FOLDER}.pid",
+       default_thread_count: nil,
+       version_copyright: "v#{VERSION} \u00A9#{Time.now.year} LFE"
+
+  class Cli
+
+    include Servitude::Cli
+
+  end
+
+  class Server
+
+    include Servitude::Server
+
+    after_initialize do
+      @tcp_server = TCPServer.open( 'localhost', '1234' )
+    end
+
+    finalize do
+      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
+
+  protected
+
+    def config_filters
+      %w(threads)
+    end
+
+  private
+
+    attr_reader :tcp_server
+
+  end
+end
+
+EchoServer::Cli.new( ARGV ).run

data/examples/4_echo_server_with_cli_daemon_and_file_config

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'servitude'
+require 'socket'
+require 'trollop'
+require 'pry'
+
+# The echo server accepts with CLI builds on the 2_echo_server example, addiing a command line interface.
+#
+# Note: Due to TcpServer#accept's implementation, the server is not currently gracefully shutting down as the trap of INT
+# appears to never happen.
+#
+# The CLI has 4 sub-commands: start, stop, status and restart.
+#
+# Using the -i of --interactive switch on the start command will run the server attached in the terminal you execute the command
+# in.  Without the interactive switch, the server will run as a daemon.  The start, stop, and status commands are used to control
+# the daemonized process.  If run in daemon mode, you can tail the log:
+#
+# $ tail -f tmp/echo-server.log
+#
+# Usage:
+#   Help:
+#     bundle exec examples/4_echo_server_with_cli_daemon_and_config -h
+#
+#   Start (interactive):
+#     bundle exec examples/4_echo_server_with_cli_daemon_and_config start -i
+#
+#   Then use telnet 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'
+
+  PROJECT_ROOT = File.expand_path( '../..', __FILE__ )
+  
+  boot host_namespace: EchoServer,
+       app_id: 'echo-server-with-cli-and-file-config',
+       app_name: 'Echo Server With CLI And File Config',
+       company: 'LFE',
+       use_config: true,
+       default_config_path: "#{PROJECT_ROOT}/config/4.conf",
+       default_log_path: "#{PROJECT_ROOT}/tmp/#{APP_FOLDER}.log",
+       default_pid_path: "#{PROJECT_ROOT}/tmp/#{APP_FOLDER}.pid",
+       default_thread_count: nil,
+       version_copyright: "v#{VERSION} \u00A9#{Time.now.year} LFE"
+
+  class Cli
+
+    include Servitude::Cli
+
+  end
+
+  class Server
+
+    include Servitude::Server
+
+    after_initialize do
+      @tcp_server = TCPServer.open( 'localhost', '1234' )
+    end
+
+    finalize do
+      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
+
+  protected
+
+    def config_filters
+      %w(threads)
+    end
+
+  private
+
+    attr_reader :tcp_server
+
+  end
+end
+
+EchoServer::Cli.new( ARGV ).run