sanford 0.4.0 → 0.6.0

data/README.md

@@ -12,7 +12,7 @@ class MyHost
   include Sanford::Host
 
   port 8000
-  pid_dir '/path/to/pids'
+  pid_file '/path/to/host.pid'
 
   # define some services
   version 'v1' do
@@ -39,7 +39,7 @@ To define a Sanford host, include the mixin `Sanford::Host` on a class and use t
 
 * `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`.
+* `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:
@@ -118,39 +118,35 @@ end
 
 ## Running Host Daemons
 
-Sanford comes with rake tasks for running hosts:
+Sanford comes with a CLI 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.
+* `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.
 
-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.
+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
-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
+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
 ```
 
-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`.
+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.
 
-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.
+Alternatively, the CLI supports passing switches to override the host's configuration as well. Use `sanford --help` to see the options that are available.
 
 ### 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. to support this, Sanford provides a `setup` 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:
+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
 
-  setup do
+  init do
     require File.expand_path("../config/environment", __FILE__)
   end
 

data/Rakefile

@@ -1,7 +1,5 @@
 require "bundler/gem_tasks"
 
-ENV['SANFORD_SERVICES_FILE'] = 'bench/services'
-require 'sanford/rake'
 require 'bench/tasks'
 
 require "assert/rake_tasks"

data/bench/report.txt

@@ -2,39 +2,37 @@ Running benchmark report...
 
 Hitting "simple" service with {}, 10000 times
 ....................................................................................................
-Total Time:   10515.3759ms
-Average Time:     1.0515ms
-Min Time:         0.7140ms
-Max Time:       114.8610ms
+Total Time:   8960.5727ms
+Average Time:    0.8960ms
+Min Time:        0.5099ms
+Max Time:       87.5380ms
 
 Distribution (number of requests):
-  0ms: 8614
-    0.7ms: 4945
-    0.8ms: 2641
-    0.9ms: 1028
-  1ms: 1339
-    1.0ms: 612
-    1.1ms: 370
-    1.2ms: 172
-    1.3ms: 90
-    1.4ms: 39
-    1.5ms: 19
-    1.6ms: 16
-    1.7ms: 10
-    1.8ms: 7
-    1.9ms: 4
-  2ms: 15
-  3ms: 10
-  4ms: 1
-  66ms: 1
-  86ms: 3
-  87ms: 4
-  89ms: 2
-  90ms: 3
-  91ms: 2
-  92ms: 2
-  93ms: 1
-  94ms: 2
-  114ms: 1
+  0ms: 9775
+    0.5ms: 5723
+    0.6ms: 2810
+    0.7ms: 733
+    0.8ms: 364
+    0.9ms: 145
+  1ms: 153
+    1.0ms: 57
+    1.1ms: 18
+    1.2ms: 42
+    1.3ms: 13
+    1.4ms: 8
+    1.5ms: 7
+    1.6ms: 2
+    1.7ms: 3
+    1.8ms: 2
+    1.9ms: 1
+  2ms: 16
+  3ms: 1
+  22ms: 1
+  44ms: 10
+  45ms: 25
+  46ms: 9
+  47ms: 4
+  85ms: 3
+  87ms: 3
 
 Done running benchmark report

data/bench/runner.rb

@@ -7,10 +7,10 @@ module Bench
 
   class Runner
     # this should match up with bench/services host and port
-    HOST_AND_PORT = [ '127.0.0.1', 12000 ]
+    HOST_AND_PORT = [ '127.0.0.1', 59284 ]
 
     REQUESTS = [
-      [ 'v1', 'simple',       {}, 10000 ]
+      [ 'v1', 'simple', {}, 10000 ]
     ]
 
     TIME_MODIFIER = 10 ** 4 # 4 decimal places
@@ -36,7 +36,7 @@ module Bench
 
       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)
+        benchmark = self.hit_service(version, name, 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
@@ -72,13 +72,12 @@ module Bench
       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)
+          response = client.call(version, name, params)
           if show_result
             output "Got a response:"
             output "  #{response.status}"
@@ -91,6 +90,8 @@ module Bench
       end
     end
 
+    protected
+
     def output(message, puts = true)
       method = puts ? :puts : :print
       self.send(method, message)

data/bench/services.rb

@@ -1,8 +1,8 @@
 class BenchHost
   include Sanford::Host
 
-  port     12000
-  pid_dir  File.expand_path("../../tmp", __FILE__)
+  port     59284
+  pid_file File.expand_path("../../tmp/bench_host.pid", __FILE__)
 
   logger           Logger.new(STDOUT)
   verbose_logging  false

data/bench/tasks.rb

@@ -4,6 +4,29 @@ namespace :bench do
     require 'bench/runner'
   end
 
+  namespace :server do
+
+    task :load do
+      ENV['SANFORD_SERVICES_FILE'] = 'bench/services'
+    end
+
+    desc "Run the bench server"
+    task :run => :load do
+      Kernel.exec("bundle exec sanford run")
+    end
+
+    desc "Start a daemonized bench server"
+    task :start => :load do
+      Kernel.system("bundle exec sanford start")
+    end
+
+    desc "Stop the bench server"
+    task :stop => :load do
+      Kernel.system("bundle exec sanford stop")
+    end
+
+  end
+
   desc "Run a Benchmark report against the Benchmark server"
   task :report => :load do
     Bench::Runner.new.build_report

data/bin/sanford

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+#
+# Copyright (c) 2013 Collin Redding & Kelly Redding
+#
+
+require 'sanford/cli'
+Sanford::CLI.run ARGV

data/lib/sanford.rb

@@ -5,6 +5,7 @@ require 'pathname'
 require 'set'
 
 require 'sanford/host'
+require 'sanford/logger'
 require 'sanford/server'
 require 'sanford/service_handler'
 require 'sanford/version'
@@ -38,7 +39,7 @@ module Sanford
   module Config
     include NsOptions::Proxy
     option :services_file,  Pathname, :default => ENV['SANFORD_SERVICES_FILE']
-
+    option :logger,                   :default => Sanford::NullLogger.new
   end
 
   class Hosts

data/lib/sanford/cli.rb

@@ -0,0 +1,364 @@
+require 'sanford'
+require 'sanford/host_data'
+require 'sanford/server'
+require 'sanford/version'
+
+module Sanford
+
+  class CLI
+
+    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
+    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
+        Sanford::Manager.call(@command, @cli.opts)
+      rescue CLIRB::HelpExit
+        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)
+      end
+      exit(0)
+    end
+
+    def help
+      "Usage: sanford <command> <options> \n" \
+      "Commands: run, start, stop, restart \n" \
+      "#{@cli}"
+    end
+
+  end
+
+  module Manager
+
+    def self.call(action, options = nil)
+      get_handler_class(action).new(options).tap{ |manager| manager.send(action) }
+    end
+
+    def self.get_handler_class(action)
+      case action.to_sym
+      when :start, :run
+        ServerHandler
+      when :stop, :restart
+        SignalHandler
+      end
+    end
+
+    class ServerHandler
+
+      def initialize(options = nil)
+        @config = Config.new(options)
+        raise Sanford::NoHostError.new(@config.host_name) if !@config.found_host?
+        raise Sanford::InvalidHostError.new(@config.host) if !@config.has_listen_args?
+        @host   = @config.host
+        @logger = @host.logger
+
+        @server_options = {}
+        # FUTURE allow passing through dat-tcp options (min/max workers)
+        # FUTURE merge in host options for verbose / keep_alive
+
+        @restart_cmd = RestartCmd.new(@config)
+      end
+
+      def run
+        self.run!
+      end
+
+      def start
+        self.run! true
+      end
+
+      protected
+
+      def run!(daemonize = false)
+        daemonize!(true) if daemonize
+        Sanford::Server.new(@host, @server_options).tap do |server|
+          log "Starting server for #{@host.name}"
+
+          server.listen(*@config.listen_args)
+          log "Listening on #{server.ip}:#{server.port}"
+          log "PID: #{Process.pid}"
+
+          $0 = ProcessName.new(@host.name, server.ip, server.port)
+          @config.pid_file.write
+
+          Signal.trap("TERM"){ self.stop!(server) }
+          Signal.trap("INT"){  self.halt!(server) }
+          Signal.trap("USR2"){ self.restart!(server) }
+
+          server.run(@config.client_file_descriptors).join
+        end
+      ensure
+        @config.pid_file.remove
+      end
+
+      def restart!(server)
+        log "Restarting the server..."
+        server.pause
+        log "server paused"
+
+        ENV['SANFORD_HOST']        = @host.name
+        ENV['SANFORD_SERVER_FD']   = server.file_descriptor.to_s
+        ENV['SANFORD_CLIENT_FDS']  = server.client_file_descriptors.join(',')
+
+        @logger.info "calling exec ..."
+        Dir.chdir @restart_cmd.dir
+        Kernel.exec(*@restart_cmd.argv)
+      end
+
+      def stop!(server)
+        log "Stopping the server..."
+        server.stop
+        log "Done"
+      end
+
+      def halt!(server)
+        log "Halting the server..."
+        server.halt false
+        log "Done"
+      end
+
+      # Full explanation: http://www.steve.org.uk/Reference/Unix/faq_2.html#SEC16
+      def daemonize!(no_chdir = false, no_close = false)
+        exit if fork
+        Process.setsid
+        exit if fork
+        Dir.chdir "/" unless no_chdir
+        if !no_close
+          null = File.open "/dev/null", 'w'
+          STDIN.reopen null
+          STDOUT.reopen null
+          STDERR.reopen null
+        end
+        return 0
+      end
+
+      def log(message)
+        @logger.info "[Sanford] #{message}"
+      end
+
+    end
+
+    class SignalHandler
+
+      def initialize(options = nil)
+        @config = Config.new(options)
+        raise Sanford::NoPIDError.new if !@config.pid
+      end
+
+      def stop
+        Process.kill("TERM", @config.pid)
+      end
+
+      def restart
+        Process.kill("USR2", @config.pid)
+      end
+
+    end
+
+    class Config
+      attr_reader :host_name, :host, :ip, :port, :file_descriptor
+      attr_reader :client_file_descriptors, :pid_file, :pid, :restart_dir
+
+      def initialize(opts = nil)
+        options = OpenStruct.new(opts || {})
+        @host_name = ENV['SANFORD_HOST'] || options.host
+
+        @host = @host_name ? Sanford.hosts.find(@host_name) : Sanford.hosts.first
+        @host ||= NullHost.new
+
+        @file_descriptor = ENV['SANFORD_SERVER_FD'] || options.file_descriptor
+        @file_descriptor = @file_descriptor.to_i if @file_descriptor
+        @ip   = ENV['SANFORD_IP']   || options.ip   || @host.ip
+        @port = ENV['SANFORD_PORT'] || options.port || @host.port
+        @port = @port.to_i if @port
+
+        client_fds_str = ENV['SANFORD_CLIENT_FDS'] || options.client_fds || ""
+        @client_file_descriptors = client_fds_str.split(',').map(&:to_i)
+
+        @pid_file = PIDFile.new(ENV['SANFORD_PID_FILE'] || options.pid_file || @host.pid_file)
+        @pid      = options.pid || @pid_file.pid
+
+        @restart_dir = ENV['SANFORD_RESTART_DIR'] || options.restart_dir
+      end
+
+      def listen_args
+        @file_descriptor ? [ @file_descriptor ] : [ @ip, @port ]
+      end
+
+      def has_listen_args?
+        !!@file_descriptor || !!(@ip && @port)
+      end
+
+      def found_host?
+        !@host.kind_of?(NullHost)
+      end
+
+    end
+
+    class NullHost
+      [ :ip, :port, :pid_file ].each do |method_name|
+        define_method(method_name){ }
+      end
+    end
+
+    class ProcessName < String
+      def initialize(name, ip, port)
+        super "#{[ name, ip, port ].join('_')}"
+      end
+    end
+
+    class PIDFile
+      def initialize(path)
+        @path = (path || '/dev/null').to_s
+      end
+
+      def pid
+        pid = File.read(@path).strip if File.exists?(@path)
+        pid.to_i if pid && !pid.empty?
+      end
+
+      def write
+        File.open(@path, 'w'){|f| f.puts Process.pid }
+      end
+
+      def remove
+        FileUtils.rm_f(@path)
+      end
+
+      def to_s
+        @path
+      end
+    end
+
+    class RestartCmd
+      attr_reader :argv, :dir
+
+      def initialize(config = nil)
+        require 'rubygems'
+        config ||= OpenStruct.new
+        @dir = config.restart_dir || get_pwd
+        @argv = [ Gem.ruby, $0, ARGV.dup ].flatten
+      end
+
+      protected
+
+      # Trick from puma/unicorn. Favor PWD because it contains an unresolved
+      # symlink. This is useful when restarting after deploying; the original
+      # directory may be removed, but the symlink is pointing to a new
+      # directory.
+      def get_pwd
+        env_stat = File.stat(ENV['PWD'])
+        pwd_stat = File.stat(Dir.pwd)
+        if env_stat.ino == pwd_stat.ino && env_stat.dev == pwd_stat.dev
+          ENV['PWD']
+        else
+          Dir.pwd
+        end
+      end
+
+    end
+  end
+
+  class CLIRB  # Version 1.0.0, https://github.com/redding/cli.rb
+    Error    = Class.new(RuntimeError);
+    HelpExit = Class.new(RuntimeError); VersionExit = Class.new(RuntimeError)
+    attr_reader :argv, :args, :opts, :data
+
+    def initialize(&block)
+      @options = []; instance_eval(&block) if block
+      require 'optparse'
+      @data, @args, @opts = [], [], {}; @parser = OptionParser.new do |p|
+        p.banner = ''; @options.each do |o|
+          @opts[o.name] = o.value; p.on(*o.parser_args){ |v| @opts[o.name] = v }
+        end
+        p.on_tail('--version', ''){ |v| raise VersionExit, v.to_s }
+        p.on_tail('--help',    ''){ |v| raise HelpExit,    v.to_s }
+      end
+    end
+
+    def option(*args); @options << Option.new(*args); end
+    def parse!(argv)
+      @args = (argv || []).dup.tap do |args_list|
+        begin; @parser.parse!(args_list)
+        rescue OptionParser::ParseError => err; raise Error, err.message; end
+      end; @data = @args + [@opts]
+    end
+    def to_s; @parser.to_s; end
+    def inspect
+      "#<#{self.class}:#{'0x0%x' % (object_id << 1)} @data=#{@data.inspect}>"
+    end
+
+    class Option
+      attr_reader :name, :opt_name, :desc, :abbrev, :value, :klass, :parser_args
+
+      def initialize(name, *args)
+        settings, @desc = args.last.kind_of?(::Hash) ? args.pop : {}, args.pop || ''
+        @name, @opt_name, @abbrev = parse_name_values(name, settings[:abbrev])
+        @value, @klass = gvalinfo(settings[:value])
+        @parser_args = if [TrueClass, FalseClass, NilClass].include?(@klass)
+          ["-#{@abbrev}", "--[no-]#{@opt_name}", @desc]
+        else
+          ["-#{@abbrev}", "--#{@opt_name} #{@opt_name.upcase}", @klass, @desc]
+        end
+      end
+
+      private
+
+      def parse_name_values(name, custom_abbrev)
+        [ (processed_name = name.to_s.strip.downcase), processed_name.gsub('_', '-'),
+          custom_abbrev || processed_name.gsub(/[^a-z]/, '').chars.first || 'a'
+        ]
+      end
+      def gvalinfo(v); v.kind_of?(Class) ? [nil,gklass(v)] : [v,gklass(v.class)]; end
+      def gklass(k); k == Fixnum ? Integer : k; end
+    end
+  end
+
+  class NoHostError < CLIRB::Error
+    def initialize(host_name)
+      message = if Sanford.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
+      super message
+    end
+  end
+
+  class InvalidHostError < CLIRB::Error
+    def initialize(host)
+      super "A port must be configured or provided to run a server for '#{host}'"
+    end
+  end
+
+  class NoPIDError < CLIRB::Error
+    def initialize
+      super "A PID or PID file is required"
+    end
+  end
+
+end