sanford 0.1.0

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sanford.gemspec
+gemspec
+
+gem 'bson_ext'
+gem 'rake',     '~>0.9.2'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 jcredding
+
+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,164 @@
+# Sanford
+
+Sanford: simple hosts for Sanford services.  Define hosts for versioned services.  Setup handlers for the services.  Run the host as a daemon.
+
+Sanford uses [Sanford::Protocol](https://github.com/redding/sanford-protocol) to communicate with clients.
+
+## Usage
+
+```ruby
+# define a host
+class MyHost
+  include Sanford::Host
+
+  port 8000
+  pid_dir '/path/to/pids'
+
+  # define some services
+  version 'v1' do
+    service 'get_user', 'MyHost::V1Services::GetUser'
+  end
+
+end
+
+# define handlers for the services
+class MyHost::V1Services::GetUser
+  include Sanford::ServiceHandler
+
+  def run!
+    # process the service call and build a response
+    # the return value of this method will be used as the response data
+  end
+end
+
+```
+
+## Hosts
+
+To define a Sanford host, include the mixin `Sanford::Host` on a class and use the DSL to configure it. A few options can be set:
+
+* `ip` - (string) A hostname or IP address for the server to bind to; default: `'0.0.0.0'`.
+* `port` - (integer) The port number for the server to bind to.
+* `pid_dir` - (string) Path to the directory where you want the pid file to be written; default: `Dir.pwd`.
+* `logger`- (logger) A logger for Sanford to use when handling requests; default: `Logger.new`.
+
+Any values specified using the DSL act as defaults for instances of the host. You can overwritten when creating new instances:
+
+```ruby
+host = MyHost.new({ :port => 12000 })
+```
+
+## Services
+
+```ruby
+class MyHost
+  include Sanford::Host
+
+  version 'v1' do
+    service 'get_user', 'MyHost::ServicesV1::GetUser'
+  end
+end
+```
+
+Services are defined on hosts by version.  Each named service maps to a 'service handler' class.  The version and service name are used to 'route' requests to handler classes.
+
+When defining services handlers, it's typical to organize them all under a common namespace. Use `service_handler_ns` to define a default namespace for all handler classes under the version:
+
+```ruby
+class MyHost
+  include Sanford::Host
+
+  version 'v1' do
+    service_handler_ns 'MyHost::ServicesV1'
+
+    service 'get_user',     'GetUser'
+    service 'get_article',  'GetArticle'
+    service 'get_comments', '::MyHost::OtherServices::GetComments'
+  end
+end
+```
+
+## Service Handlers
+
+Define handlers by mixing in `Sanford::ServiceHandler` on a class and defining a `run!` method:
+
+```ruby
+class MyHost::Services::GetUser
+  include Sanford::ServiceHandler
+
+  def run!
+    # process the service call and generate a response
+    # the return value of this method will be used as
+    # the response data returned to the client
+  end
+end
+```
+
+This is the most basic way to define a service handler. In addition to this, the `init!` method can be overwritten. This will be called after an instance of the service handler is created. The `init!` method is intended as a hook to add constructor logic. The `initialize` method should not be overwritten.
+
+In addition to these, there are some helpers methods that can be used in your `run!` method:
+
+* `request`: returns the request object the host received
+* `params`: returns the params payload from the request object
+* `halt`: stop processing and return response data with a status code and message
+
+```ruby
+class MyHost::Services::GetUser
+  include Sanford::ServiceHandler
+
+  def run!
+    User.find(params['user_id']).attributes
+  rescue NotFoundException => e
+    halt :not_found, :message => e.message, :data => request.params
+  rescue Exception => e
+    halt :error, :message => e.message
+  end
+end
+```
+
+## Running Host Daemons
+
+Sanford comes with rake tasks for running hosts:
+
+* `rake sanford:start` - spin up a background process running the host daemon.
+* `rake sanford:stop` - shutdown the background process running the host gracefully.
+* `rake sanford:restart` - runs the stop and then the start tasks.
+* `rake sanford:run` - starts the server, but don't daemonize it (runs in the current ruby process). Convenient when using the server in a development environment.
+
+These can be installed by requiring it's rake tasks in your `Rakefile`:
+
+```ruby
+require 'sanford/rake'
+```
+
+The basic rake tasks are useful if your application only has one host defined and if you only want to run the host on a single port. In the case you have multiple hosts defined or you want to run a single host on multiple ports, use environment variables to set custom configurations.
+
+```bash
+rake sanford:start   # starts the first defined host
+SANFORD_HOST=AnotherHost SANFORD_PORT=13001 rake sanford:start # choose a specific host and port to run on with ENV vars
+```
+
+The rake tasks allow using environment variables for specifying which host to run the command against and for overriding the host's configuration. They recognize the following environment variables: `SANFORD_HOST`, `SANFORD_IP`, and `SANFORD_PORT`.
+
+Define a `name` on a Host to set a string name for your host that can be used to reference a host when using the rake tasks.  If no name is set, Sanford will use the host's class name.
+
+### Loading An Application
+
+Typically, a Sanford host is part of a larger application and parts of the application need to be setup or loaded when you start your Sanford server. The task `sanford:setup` is called before running any start, stop, or restart task; override it to hook in your application setup code:
+
+```ruby
+# In your Rakefile
+namespace :sanford do
+  task :setup do
+    require 'config/environment'
+  end
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+ENV['SANFORD_SERVICES_CONFIG'] = 'bench/services'
+require 'sanford/rake'
+require 'bench/tasks'
+
+require "assert/rake_tasks"
+Assert::RakeTasks.install

data/bench/client.rb

@@ -0,0 +1,30 @@
+require 'socket'
+
+require 'sanford-protocol'
+
+module Bench
+
+  class Client
+
+    def initialize(host, port)
+      @host, @port = [ host, port ]
+    end
+
+    def call(version, name, params)
+      socket = TCPSocket.open(@host, @port)
+      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true) # TODO - explain
+      connection = Sanford::Protocol::Connection.new(socket)
+      request = Sanford::Protocol::Request.new(version, name, params)
+      connection.write(request.to_hash)
+      if IO.select([ socket ], nil, nil, 10)
+        Sanford::Protocol::Response.parse(connection.read)
+      else
+        raise "Timed out!"
+      end
+    ensure
+      socket.close rescue false
+    end
+
+  end
+
+end

data/bench/report.txt

@@ -0,0 +1,10 @@
+Running benchmark report...
+
+Hitting "simple" service with {}, 10000 times
+....................................................................................................
+Total Time:   15768.8473ms
+Average Time:     1.5768ms
+Min Time:         0.9949ms
+Max Time:       102.2670ms
+
+Done running benchmark report

data/bench/runner.rb

@@ -0,0 +1,102 @@
+Bundler.setup(:benchmark)
+require 'benchmark'
+
+require 'bench/client'
+
+module Bench
+
+  class Runner
+    # this should match up with bench/services host and port
+    HOST_AND_PORT = [ '127.0.0.1', 12000 ]
+
+    REQUESTS = [
+      [ 'v1', 'simple',       {}, 10000 ]
+    ]
+
+    TIME_MODIFIER = 10 ** 4 # 4 decimal places
+
+    def initialize(options = {})
+      options[:output] ||= File.expand_path("../report.txt", __FILE__)
+
+      @file = File.open(options[:output], "w")
+    end
+
+    def build_report
+      output "Running benchmark report..."
+
+      REQUESTS.each do |version, name, params, times|
+        self.benchmark_service(version, name, params, times, false)
+      end
+
+      output "Done running benchmark report"
+    end
+
+    def benchmark_service(version, name, params, times, show_result = false)
+      benchmarks = []
+
+      output "\nHitting #{name.inspect} service with #{params.inspect}, #{times} times"
+      [*(1..times.to_i)].each do |index|
+        benchmark = self.hit_service(name, version, params.merge({ :request_number => index }), show_result)
+        benchmarks << self.round_time(benchmark.real * 1000.to_f)
+        output('.', false) if ((index - 1) % 100 == 0) && !show_result
+      end
+      output("\n", false)
+
+      total_time = benchmarks.inject(0){|s, n| s + n }
+      data = {
+        :number_of_requests => times,
+        :total_time_taken   => self.round_and_display(total_time),
+        :average_time_taken => self.round_and_display(total_time / benchmarks.size),
+        :min_time_taken     => self.round_and_display(benchmarks.min),
+        :max_time_taken     => self.round_and_display(benchmarks.max)
+      }
+      size = data.values.map(&:size).max
+      output "Total Time:   #{data[:total_time_taken].rjust(size)}ms"
+      output "Average Time: #{data[:average_time_taken].rjust(size)}ms"
+      output "Min Time:     #{data[:min_time_taken].rjust(size)}ms"
+      output "Max Time:     #{data[:max_time_taken].rjust(size)}ms"
+      output "\n"
+    end
+
+    protected
+
+    def hit_service(version, name, params, show_result)
+      Benchmark.measure do
+        begin
+          client = Bench::Client.new(*HOST_AND_PORT)
+          response = client.call(name, version, params)
+          if show_result
+            output "Got a response:"
+            output "  #{response.status}"
+            output "  #{response.data.inspect}"
+          end
+        rescue Exception => exception
+          puts "FAILED -> #{exception.class}: #{exception.message}"
+          puts exception.backtrace.join("\n")
+        end
+      end
+    end
+
+    def output(message, puts = true)
+      method = puts ? :puts : :print
+      self.send(method, message)
+      @file.send(method, message)
+      STDOUT.flush if method == :print
+    end
+
+    def round_and_display(time_in_ms)
+      self.display_time(self.round_time(time_in_ms))
+    end
+
+    def round_time(time_in_ms)
+      (time_in_ms * TIME_MODIFIER).to_i / TIME_MODIFIER.to_f
+    end
+
+    def display_time(time)
+      integer, fractional = time.to_s.split('.')
+      [ integer, fractional.ljust(4, '0') ].join('.')
+    end
+
+  end
+
+end

data/bench/services.rb

@@ -0,0 +1,23 @@
+class BenchHost
+  include Sanford::Host
+
+  self.port     = 12000
+  self.pid_dir  = File.expand_path("../../tmp", __FILE__)
+
+  version 'v1' do
+    service 'simple', 'BenchHost::Simple'
+  end
+
+  class Simple
+    include Sanford::ServiceHandler
+
+    def run!
+      { :string => 'test', :int => 1, :float => 2.1, :boolean => true,
+        :hash => { :something => 'else' }, :array => [ 1, 2, 3 ],
+        :request_number => self.request.params['request_number']
+      }
+    end
+
+  end
+
+end

data/bench/tasks.rb

@@ -0,0 +1,18 @@
+namespace :bench do
+
+  task :load do
+    require 'bench/runner'
+  end
+
+  desc "Run a Benchmark report against the Benchmark server"
+  task :report => :load do
+    Bench::Runner.new.build_report
+  end
+
+  desc "Run Benchmark requests against the 'simple' service"
+  task :simple, [ :times ] => :load do |t, args|
+    runner = Bench::Runner.new(:output => '/dev/null')
+    runner.benchmark_service('v1', 'simple', {}, args[:times] || 1, true)
+  end
+
+end

data/lib/sanford/config.rb

@@ -0,0 +1,33 @@
+require 'ns-options'
+require 'pathname'
+require 'set'
+
+ENV['SANFORD_SERVICES_CONFIG'] ||= 'config/services'
+
+module Sanford
+
+  module Config
+    include NsOptions::Proxy
+
+    option :hosts,            Set,      :default => []
+    option :services_config,  Pathname, :default => ENV['SANFORD_SERVICES_CONFIG']
+
+    # We want class names to take precedence over a configured name, so that if
+    # a user specifies a specific class, they always get it
+    def self.find_host(name)
+      self.find_host_by_class_name(name) || self.find_host_by_name(name)
+    end
+
+    protected
+
+    def self.find_host_by_class_name(class_name)
+      self.hosts.detect{|host_class| host_class.to_s == class_name.to_s }
+    end
+
+    def self.find_host_by_name(name)
+      self.hosts.detect{|host_class| host_class.name == name.to_s }
+    end
+
+  end
+
+end

data/lib/sanford/connection.rb

@@ -0,0 +1,70 @@
+# Sanford's connection class is an extesion of the connection class provided by
+# Sanford-Protocol. It provides the main process of reading a request, routing
+# it and writing a response. All requests are benchmarked and logged. The
+# connection's `process` method should always try to return a response, so that
+# clients do not have to timeout.
+#
+# Notes:
+# * This class is separated from `Sanford::Server` to help with thread safety.
+#   The server creates a new instance of this class per connection, which means
+#   there is a separate connection per thread.
+#
+require 'benchmark'
+require 'sanford-protocol'
+
+require 'sanford/exceptions'
+
+module Sanford
+
+  class Connection < Sanford::Protocol::Connection
+
+    DEFAULT_TIMEOUT = 1
+
+    attr_reader :service_host, :logger, :exception_handler, :timeout
+
+    def initialize(service_host, client_socket)
+      @service_host = service_host
+      @exception_handler  = self.service_host.exception_handler
+      @logger             = self.service_host.logger
+      @timeout            = (ENV['SANFORD_TIMEOUT'] || DEFAULT_TIMEOUT).to_f
+      super(client_socket)
+    end
+
+    def process
+      response = nil
+      self.logger.info("Received request")
+      benchmark = Benchmark.measure do
+        begin
+          request = Sanford::Protocol::Request.parse(self.read(self.timeout))
+          self.log_request(request)
+          response = Sanford::Protocol::Response.new(*self.run(request))
+        rescue Exception => exception
+          handler = self.exception_handler.new(exception, self.logger)
+          response = handler.response
+        ensure
+          self.write(response.to_hash)
+        end
+      end
+      time_taken = self.round_time(benchmark.real)
+      self.logger.info("Completed in #{time_taken}ms #{response.status}\n")
+    end
+
+    protected
+
+    def run(request)
+      self.service_host.run(request)
+    end
+
+    def log_request(request)
+      self.logger.info("  Version: #{request.version.inspect}")
+      self.logger.info("  Service: #{request.name.inspect}")
+      self.logger.info("  Parameters: #{request.params.inspect}")
+    end
+
+    def round_time(time_in_seconds)
+      ((time_in_seconds * 1000.to_f) + 0.5).to_i
+    end
+
+  end
+
+end

data/lib/sanford/exception_handler.rb

@@ -0,0 +1,43 @@
+# Sanford's exception handler class takes an exception and builds a valid
+# response. For certain exceptions, Sanford will use special response codes and
+# for all others it will classify them as generic error requests.
+#
+require 'sanford-protocol'
+
+require 'sanford/exceptions'
+
+module Sanford
+
+  class ExceptionHandler
+    attr_reader :exception, :logger
+
+    def initialize(exception, logger)
+      @exception = exception
+      @logger = logger
+    end
+
+    def response
+      self.logger.error("#{exception.class}: #{exception.message}")
+      self.logger.error(exception.backtrace.join("\n"))
+      status = Sanford::Protocol::ResponseStatus.new(*self.determine_code_and_message)
+      Sanford::Protocol::Response.new(status)
+    end
+
+    protected
+
+    def determine_code_and_message
+      case(self.exception)
+      when Sanford::Protocol::BadMessageError, Sanford::Protocol::BadRequestError
+        [ :bad_request, self.exception.message ]
+      when Sanford::NotFoundError
+        [ :not_found ]
+      when Sanford::Protocol::TimeoutError
+        [ :timeout ]
+      when Exception
+        [ :error, "An unexpected error occurred." ]
+      end
+    end
+
+  end
+
+end

data/lib/sanford/exceptions.rb

@@ -0,0 +1,37 @@
+module Sanford
+
+  class BaseError < RuntimeError; end
+
+  class NotFoundError < BaseError; end
+
+  class NoHostError < BaseError
+    attr_reader :message
+
+    def initialize(host_name)
+      @message = if Sanford.config.hosts.empty?
+        "No hosts have been defined. " \
+        "Please define a host before trying to run Sanford."
+      else
+        "A host couldn't be found with the name #{host_name.inspect}. "
+      end
+    end
+  end
+
+  class InvalidHostError < BaseError
+    attr_reader :message
+
+    def initialize(host)
+      @message = "A port must be configured or provided to build an instance of '#{host}'"
+    end
+  end
+
+  class NoHandlerClassError < BaseError
+    attr_reader :message
+
+    def initialize(host, handler_class_name)
+      @message = "Sanford couldn't find the service handler '#{handler_class_name}'." \
+        "It doesn't exist or hasn't been required in yet."
+    end
+  end
+
+end