sanford 0.10.1 → 0.11.0

data/Gemfile

@@ -3,6 +3,6 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rake'
-gem 'pry'
+gem 'pry', "~> 0.9.0"
 
 gem 'bson_ext'

data/README.md

@@ -1,28 +1,28 @@
 # Sanford
 
-Sanford TCP protocol server for hosting services.  Define hosts for versioned services.  Setup handlers for the services.  Run the host as a daemon.
+Sanford TCP protocol server for hosting services. Define servers for services. Setup handlers for the services. Run the server as a daemon.
 
 Sanford uses [Sanford::Protocol](https://github.com/redding/sanford-protocol) to communicate with clients.  Check out [AndSon](https://github.com/redding/and-son) for a Ruby Sanford protocol client.
 
 ## Usage
 
 ```ruby
-# define a host
-class MyHost
-  include Sanford::Host
+# define a server
+class MyServer
+  include Sanford::Server
 
   port 8000
-  pid_file '/path/to/host.pid'
+  pid_file '/path/to/server.pid'
 
   # define some services
-  version 'v1' do
-    service 'get_user', 'MyHost::V1Services::GetUser'
+  router do
+    service 'get_user', 'MyServer::GetUser'
   end
 
 end
 
 # define handlers for the services
-class MyHost::V1Services::GetUser
+class MyServer::GetUser
   include Sanford::ServiceHandler
 
   def run!
@@ -33,47 +33,43 @@ end
 
 ```
 
-## Hosts
+## Servers
 
-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:
+To define a Sanford server, include the mixin `Sanford::Server` on a class and use the DSL to configure it. A few options can be set:
 
+* `name` - (string) A name for the server, this is used to set the process name
+and in logging.
 * `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_file` - (string) Path to where you want the pid file to be written.
 * `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
+class MyServer
+  include Sanford::Server
 
-  version 'v1' do
-    service 'get_user', 'MyHost::ServicesV1::GetUser'
+  router do
+    service 'get_user', 'MyServer::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.
+Services are defined on servers via a router block.  Each named service maps to a 'service handler' class.  The service name is 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
+class MyServer
+  include Sanford::Server
 
-  version 'v1' do
-    service_handler_ns 'MyHost::ServicesV1'
+  router do
+    service_handler_ns 'MyServer'
 
     service 'get_user',     'GetUser'
     service 'get_article',  'GetArticle'
-    service 'get_comments', '::MyHost::OtherServices::GetComments'
+    service 'get_comments', '::OtherServices::GetComments'
   end
 end
 ```
@@ -83,7 +79,7 @@ end
 Define handlers by mixing in `Sanford::ServiceHandler` on a class and defining a `run!` method:
 
 ```ruby
-class MyHost::Services::GetUser
+class MyServer::GetUser
   include Sanford::ServiceHandler
 
   def run!
@@ -103,7 +99,7 @@ In addition to these, there are some helpers methods that can be used in your `r
 * `halt`: stop processing and return response data with a status code and message
 
 ```ruby
-class MyHost::Services::GetUser
+class MyServer::GetUser
   include Sanford::ServiceHandler
 
   def run!
@@ -116,43 +112,32 @@ class MyHost::Services::GetUser
 end
 ```
 
-## Running Host Daemons
-
-Sanford comes with a CLI for running hosts:
+## Running Servers
 
-* `sanford start` - spin up a background process running the host daemon.
-* `sanford stop` - shutdown the background process running the host gracefully.
-* `sanford restart` - "hot restart" the process running the host.
-* `sanford run` - starts the server, but doesn't daemonize it (runs in the current ruby process). Convenient when using the server in a development environment.
+To run a server, Sanford needs a config file to be defined:
 
-The basic commands 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
-sanford start # starts the first defined host
-SANFORD_HOST=AnotherHost SANFORD_PORT=13001 sanford start # choose a specific host and port to run on with ENV vars
+```ruby
+require 'my_server'
+run MyServer.new
 ```
 
-The CLI allow using environment variables for specifying which host to run the command against and for overriding the host's configuration. They recognize the a number of environment variables, but the main ones are: `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 CLI.  If no name is set, Sanford will use the host's class name.
+This file works like a rackup file. You require in your server and call `run`
+passing an instance of the server. To use these files, Sanford comes with a CLI:
 
-Alternatively, the CLI supports passing switches to override the host's configuration as well. Use `sanford --help` to see the options that are available.
+* `sanford CONFIG_FILE start` - spin up a background process running the server.
+* `sanford CONFIG_FILE stop` - shutdown the background process running the server gracefully.
+* `sanford CONFIG_FILE restart` - "hot restart" the process running the server.
+* `sanford CONFIG_FILE run` - starts the server, but doesn't daemonize it (runs in the current ruby process). Convenient when using the server in a development environment.
 
-### Loading An Application
+Sanford will use the configuration of your server to either start a process or manage an existing one. A servers ip and port can be overwritten using environment variables:
 
-Typically, a Sanford host is part of a larger application and parts of the application need to be initialized or loaded when you start your Sanford server. To support this, Sanford provides an `init` hook for hosts. The proc that is defined will be called before the Sanford server is started, properly running the server in your application's environment:
-
-```ruby
-class MyHost
-  include Sanford::Host
-
-  init do
-    require File.expand_path("../config/environment", __FILE__)
-  end
-
-end
+```bash
+sanford my_server.sanford start # starts a process for `MyServer`
+SANFORD_IP="1.2.3.4" SANFORD_PORT=13001 sanford my_server.sanford start # run the same server on a custom ip and port
 ```
 
+This allows running multiple instances of the same server on ips and ports that are different than its configuration if needed.
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,2 +1 @@
 require "bundler/gem_tasks"
-require 'bench/tasks'

data/bench/client.rb

@@ -10,11 +10,16 @@ module Bench
       @host, @port = [ host, port ]
     end
 
-    def call(version, name, params)
+    # TCP_NODELAY is set to disable buffering. In the case of Sanford
+    # communication, we have all the information we need to send up front and
+    # are closing the connection, so it doesn't need to buffer.
+    # See http://linux.die.net/man/7/tcp
+
+    def call(name, params)
       socket = TCPSocket.open(@host, @port)
-      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true) # TODO - explain
+      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true)
       connection = Sanford::Protocol::Connection.new(socket)
-      request = Sanford::Protocol::Request.new(version, name, params)
+      request = Sanford::Protocol::Request.new(name, params)
       connection.write(request.to_hash)
       connection.close_write
       if IO.select([ socket ], nil, nil, 10)

data/bench/{services.rb → config.sanford}

@@ -1,13 +1,16 @@
-class BenchHost
-  include Sanford::Host
+class BenchServer
+  include Sanford::Server
 
+  name     'bench'
   port     59284
-  pid_file File.expand_path("../../tmp/bench_host.pid", __FILE__)
+  pid_file File.expand_path("../../tmp/bench_server.pid", __FILE__)
 
-  logger           Logger.new(STDOUT)
-  verbose_logging  false
+  logger          Logger.new(STDOUT)
+  verbose_logging false
 
-  service 'simple', 'BenchHost::Simple'
+  router do
+    service 'simple', 'BenchServer::Simple'
+  end
 
   class Simple
     include Sanford::ServiceHandler
@@ -22,3 +25,5 @@ class BenchHost
   end
 
 end
+
+run BenchServer.new

data/bench/{runner.rb → report.rb}

@@ -1,6 +1,4 @@
-Bundler.setup(:benchmark)
 require 'benchmark'
-
 require 'bench/client'
 
 module Bench
@@ -222,3 +220,5 @@ module Bench
   end
 
 end
+
+Bench::Runner.new.build_report

data/bench/report.txt

@@ -2,40 +2,40 @@ Running benchmark report...
 
 Hitting "simple" service with {}, 10000 times
 ....................................................................................................
-Total Time:   8970.7162ms
-Average Time:    0.8970ms
-Min Time:        0.5419ms
-Max Time:      108.7779ms
+Total Time:   5192.7267ms
+Average Time:    0.5192ms
+Min Time:        0.3479ms
+Max Time:       56.1919ms
 
 Distribution (number of requests):
-  0ms: 9634
-    0.5ms: 2063
-    0.6ms: 5113
-    0.7ms: 1448
-    0.8ms: 675
-    0.9ms: 335
-  1ms: 319
-    1.0ms: 129
-    1.1ms: 67
-    1.2ms: 44
-    1.3ms: 20
-    1.4ms: 23
-    1.5ms: 11
-    1.6ms: 13
-    1.7ms: 1
-    1.8ms: 6
-    1.9ms: 5
-  2ms: 11
-  3ms: 9
-  4ms: 4
+  0ms: 9929
+    0.3ms: 6583
+    0.4ms: 2845
+    0.5ms: 289
+    0.6ms: 130
+    0.7ms: 47
+    0.8ms: 23
+    0.9ms: 12
+  1ms: 31
+    1.0ms: 10
+    1.1ms: 6
+    1.2ms: 5
+    1.3ms: 5
+    1.4ms: 1
+    1.5ms: 2
+    1.8ms: 2
+  2ms: 1
   5ms: 1
-  21ms: 1
-  87ms: 1
-  90ms: 1
-  97ms: 5
-  98ms: 9
-  99ms: 2
-  100ms: 2
-  108ms: 1
+  7ms: 1
+  16ms: 1
+  24ms: 1
+  28ms: 5
+  29ms: 13
+  30ms: 4
+  31ms: 2
+  32ms: 5
+  33ms: 4
+  34ms: 1
+  56ms: 1
 
 Done running benchmark report

data/lib/sanford/cli.rb

@@ -1,51 +1,65 @@
 require 'sanford'
+require 'sanford/config_file'
+require 'sanford/process'
+require 'sanford/process_signal'
 require 'sanford/version'
 
 module Sanford
 
   class CLI
 
-    def self.run(*args)
+    def self.run(args)
       self.new.run(*args)
     end
 
-    def initialize
-      @cli = CLIRB.new do
-        option :host,   "Name of the Host configuration",     :value => String
-        option :ip,     "IP address to bind to",              :value => String
-        option :port,   "Port number to bind to",             :value => Integer
-        option :config, "File defining the configured Hosts", :value => String
-      end
+    def initialize(kernel = nil)
+      @kernel = kernel || Kernel
+      @cli = CLIRB.new
     end
 
     def run(*args)
       begin
-        @cli.parse!(*args)
-        @command = @cli.args.first || 'run'
-        Sanford.config.services_file = @cli.opts['config'] if @cli.opts['config']
-        Sanford.init
-        require 'sanford/manager'
-        Sanford::Manager.call(@command, @cli.opts)
+        run!(*args)
       rescue CLIRB::HelpExit
-        puts help
+        @kernel.puts help
       rescue CLIRB::VersionExit
-        puts Sanford::VERSION
-      rescue CLIRB::Error => exception
-        puts "#{exception.message}\n\n"
-        puts help
-        exit(1)
-      rescue SystemExit
-      rescue Exception => exception
-        puts "#{exception.class}: #{exception.message}"
-        puts exception.backtrace.join("\n") if ENV['DEBUG']
-        exit(1)
+        @kernel.puts "sanford #{Sanford::VERSION}"
+      rescue CLIRB::Error, Sanford::ConfigFile::InvalidError => exception
+        @kernel.puts "#{exception.message}\n\n"
+        @kernel.puts help
+        @kernel.exit 1
+      rescue StandardError => exception
+        @kernel.puts "#{exception.class}: #{exception.message}"
+        @kernel.puts exception.backtrace.join("\n")
+        @kernel.exit 1
+      end
+      @kernel.exit 0
+    end
+
+    private
+
+    def run!(*args)
+      @cli.parse!(args)
+      command          = @cli.args.pop || 'run'
+      config_file_path = @cli.args.pop || 'config.sanford'
+      server = Sanford::ConfigFile.new(config_file_path).server
+      case(command)
+      when 'run'
+        Sanford::Process.new(server, :daemonize => false).run
+      when 'start'
+        Sanford::Process.new(server, :daemonize => true).run
+      when 'stop'
+        Sanford::ProcessSignal.new(server, 'TERM').send
+      when 'restart'
+        Sanford::ProcessSignal.new(server, 'USR2').send
+      else
+        raise CLIRB::Error, "#{command.inspect} is not a valid command"
       end
-      exit(0)
     end
 
     def help
-      "Usage: sanford <command> <options> \n" \
-      "Commands: run, start, stop, restart \n" \
+      "Usage: sanford [CONFIG_FILE] [COMMAND]\n" \
+      "Commands: run, start, stop, restart" \
       "#{@cli}"
     end
 

data/lib/sanford/config_file.rb

@@ -0,0 +1,79 @@
+require 'sanford/server'
+
+module Sanford
+
+  class ConfigFile
+
+    attr_reader :server
+
+    def initialize(file_path)
+      @file_path = build_file_path(file_path)
+      @server = nil
+      evaluate_file(@file_path)
+      validate!
+    end
+
+    def run(server)
+      @server = server
+    end
+
+    private
+
+    def validate!
+      if !@server.kind_of?(Sanford::Server)
+        raise NoServerError.new(@server, @file_path)
+      end
+    end
+
+    def build_file_path(path)
+      full_path = File.expand_path(path)
+      raise NoConfigFileError.new(full_path) unless File.exists?(full_path)
+      full_path
+    rescue NoConfigFileError
+      full_path_with_sanford = "#{full_path}.sanford"
+      raise unless File.exists?(full_path_with_sanford)
+      full_path_with_sanford
+    end
+
+    # This evaluates the file and creates a proc using it's contents. This is
+    # a trick borrowed from Rack. It is essentially converting a file into a
+    # proc and then instance eval'ing it. This has a couple benefits:
+    # * The obvious benefit is the file is evaluated in the context of this
+    #   class. This allows the file to call `run`, setting the server that
+    #   will be used.
+    # * The other benefit is that the file's contents behave like they were a
+    #   proc defined by the user. Instance eval'ing the file directly, makes
+    #   any constants (modules/classes) defined in it namespaced by the
+    #   instance of the config (not namespaced by `Sanford::ConfigFile`,
+    #   they are actually namespaced by an instance of this class, its like
+    #   accessing it via `ConfigFile.new::MyServer`), which is very confusing.
+    #   Thus, the proc is created and eval'd using the `TOPLEVEL_BINDING`,
+    #   which defines the constants at the top-level, as would be expected.
+    def evaluate_file(file_path)
+      config_file_code = "proc{ #{File.read(file_path)} }"
+      config_file_proc = eval(config_file_code, TOPLEVEL_BINDING, file_path, 0)
+      self.instance_eval(&config_file_proc)
+    end
+
+    InvalidError = Class.new(StandardError)
+
+    class NoConfigFileError < InvalidError
+      def initialize(path)
+        super "A configuration file couldn't be found at: #{path.to_s.inspect}"
+      end
+    end
+
+    class NoServerError < InvalidError
+      def initialize(server, path)
+        prefix = "Configuration file #{path.to_s.inspect}"
+        if server
+          super "#{prefix} called `run` without a Sanford::Server"
+        else
+          super "#{prefix} didn't call `run` with a Sanford::Server"
+        end
+      end
+    end
+
+  end
+
+end

data/lib/sanford/{worker.rb → connection_handler.rb}

@@ -1,24 +1,27 @@
 require 'benchmark'
 require 'sanford-protocol'
-
 require 'sanford/error_handler'
 require 'sanford/logger'
 require 'sanford/runner'
 
 module Sanford
 
-  class Worker
+  class ConnectionHandler
 
-    ProcessedService = Struct.new(*[
+    ProcessedService = Struct.new(
       :request, :handler_class, :response, :exception, :time_taken
-    ])
+    )
 
+    attr_reader :server_data, :connection
     attr_reader :logger
 
-    def initialize(host_data, connection)
-      @host_data, @connection = host_data, connection
-
-      @logger = Sanford::Logger.new(@host_data.logger, @host_data.verbose)
+    def initialize(server_data, connection)
+      @server_data = server_data
+      @connection = connection
+      @logger = Sanford::Logger.new(
+        @server_data.logger,
+        @server_data.verbose_logging
+      )
     end
 
     def run
@@ -42,14 +45,14 @@ module Sanford
         self.log_request(request)
         service.request = request
 
-        handler_class = @host_data.handler_class_for(request.name)
-        self.log_handler_class(handler_class)
-        service.handler_class = handler_class
+        route = @server_data.route_for(request.name)
+        self.log_handler_class(route.handler_class)
+        service.handler_class = route.handler_class
 
-        response = @host_data.run(handler_class, request)
+        response = route.run(request, @server_data)
         service.response = response
-      rescue Exception => exception
-        self.handle_exception(service, exception, @host_data)
+      rescue StandardError => exception
+        self.handle_exception(service, exception, @server_data)
       ensure
         self.write_response(service)
       end
@@ -59,7 +62,7 @@ module Sanford
     def write_response(service)
       begin
         @connection.write_data service.response.to_hash
-      rescue Exception => exception
+      rescue StandardError => exception
         service = self.handle_exception(service, exception)
         @connection.write_data service.response.to_hash
       end
@@ -67,8 +70,12 @@ module Sanford
       service
     end
 
-    def handle_exception(service, exception, host_data = nil)
-      error_handler = Sanford::ErrorHandler.new(exception, host_data, service.request)
+    def handle_exception(service, exception, server_data = nil)
+      error_handler = Sanford::ErrorHandler.new(
+        exception,
+        server_data,
+        service.request
+      )
       service.response  = error_handler.run
       service.exception = error_handler.exception
       self.log_exception(service.exception)
@@ -110,8 +117,9 @@ module Sanford
     end
 
     def log_exception(exception)
-      log_verbose("#{exception.class}: #{exception.message}", :error)
-      log_verbose(exception.backtrace.join("\n"), :error)
+      backtrace = exception.backtrace.join("\n")
+      message = "#{exception.class}: #{exception.message}\n#{backtrace}"
+      log_verbose(message, :error)
     end
 
     def log_verbose(message, level = :info)
@@ -132,7 +140,7 @@ module Sanford
 
     module SummaryLine
       def self.new(line_attrs)
-        attr_keys = %w{time status handler version service params}
+        attr_keys = %w{time status handler service params}
         attr_keys.map{ |k| "#{k}=#{line_attrs[k].inspect}" }.join(' ')
       end
     end

data/lib/sanford/error_handler.rb

@@ -5,12 +5,12 @@ module Sanford
 
   class ErrorHandler
 
-    attr_reader :exception, :host_data, :request
+    attr_reader :exception, :server_data, :request
+    attr_reader :error_procs
 
-    def initialize(exception, host_data = nil, request = nil)
-      @exception, @host_data, @request = exception, host_data, request
-      @keep_alive  = @host_data ? @host_data.keep_alive : false
-      @error_procs = @host_data ? @host_data.error_procs.reverse : []
+    def initialize(exception, server_data = nil, request = nil)
+      @exception, @server_data, @request = exception, server_data, request
+      @error_procs = @server_data ? @server_data.error_procs.reverse : []
     end
 
     # The exception that we are generating a response for can change in the case
@@ -24,8 +24,8 @@ module Sanford
       @error_procs.each do |error_proc|
         result = nil
         begin
-          result = error_proc.call(@exception, @host_data, @request)
-        rescue Exception => proc_exception
+          result = error_proc.call(@exception, @server_data, @request)
+        rescue StandardError => proc_exception
           @exception = proc_exception
         end
         response ||= self.response_from_proc(result)

data/lib/sanford/pid_file.rb

@@ -0,0 +1,42 @@
+require 'fileutils'
+
+module Sanford
+
+  class PIDFile
+    attr_reader :path
+
+    def initialize(path)
+      @path = (path || '/dev/null').to_s
+    end
+
+    def pid
+      pid = File.read(@path).strip
+      pid && !pid.empty? ? pid.to_i : raise('no pid in file')
+    rescue StandardError => exception
+      error = InvalidError.new("A PID couldn't be read from #{@path.inspect}")
+      error.set_backtrace(exception.backtrace)
+      raise error
+    end
+
+    def write
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.open(@path, 'w'){ |f| f.puts ::Process.pid }
+    rescue StandardError => exception
+      error = InvalidError.new("Can't write pid to file #{@path.inspect}")
+      error.set_backtrace(exception.backtrace)
+      raise error
+    end
+
+    def remove
+      FileUtils.rm_f(@path)
+    end
+
+    def to_s
+      @path
+    end
+
+    InvalidError = Class.new(RuntimeError)
+
+  end
+
+end