sanford 0.1.0

data/lib/sanford/host.rb

@@ -0,0 +1,162 @@
+# Sanford's Host mixin is used to define service hosts. When mixed into a class
+# it provides the interface for configuring the service host and for adding
+# versioned services. It also contains the logic for routing a request to a
+# a service handler.
+#
+# Options:
+# * `name`    - A string for naming this host. This can be used when specifying
+#               a host with the rake tasks and will be used to name the PID
+#               file. Defaults to the class's name.
+# * `ip`      - The string for the ip that the TCP Server should bind to. This
+#               defaults to '0.0.0.0'.
+# * `port`    - The integer for the port that the TCP Server should bind to.
+#               This isn't defaulted and must be provided.
+# * `pid_dir` - The directory to write the PID file to. This is defaulted to
+#               Dir.pwd.
+# * `logger`  - The logger to use if the Sanford server logs messages. This is
+#               defaulted to an instance of Ruby's Logger.
+#
+require 'logger'
+require 'ns-options'
+require 'pathname'
+
+require 'sanford/config'
+require 'sanford/exception_handler'
+require 'sanford/exceptions'
+require 'sanford/service_handler'
+
+module Sanford
+  module Host
+
+    # Notes:
+    # * When Host is included on a class, it needs to mixin NsOptions and define
+    #   the options directly on the class (instead of on the Host module).
+    #   Otherwise, NsOptions will not work correctly for the class.
+    def self.included(host_class)
+      host_class.class_eval do
+        include NsOptions
+        extend Sanford::Host::Interface
+
+        options :config do
+          option :name,     String,   :default => host_class.to_s
+          option :ip,       String,   :default => '0.0.0.0'
+          option :port,     Integer
+          option :pid_dir,  Pathname, :default => Dir.pwd
+          option :logger,             :default => proc{ Sanford::NullLogger.new }
+
+          option :exception_handler,        :default => Sanford::ExceptionHandler
+          option :versioned_services, Hash, :default => {}
+        end
+      end
+      Sanford.config.hosts.add(host_class)
+    end
+
+    INTERFACE_OPTIONS = [ :name, :ip, :port, :pid_dir, :logger, :exception_handler ]
+
+    # Notes:
+    # * The `initialize` takes the values configured on the class and merges
+    #   the passed in options. This is used to set the individual instance's
+    #   configuration (which allows overwriting options like the port).
+    def initialize(options = nil)
+      options = self.remove_nil_values(options)
+      config_options = self.class.config.to_hash.merge(options)
+      self.config.apply(config_options)
+      raise(Sanford::InvalidHostError.new(self.class)) if !self.port
+    end
+
+    INTERFACE_OPTIONS.each do |name|
+
+      define_method(name) do
+        self.config.send(name)
+      end
+
+    end
+
+    def run(request)
+      request_handler(request).run
+    end
+
+    def inspect
+      reference = '0x0%x' % (self.object_id << 1)
+      "#<#{self.class}:#{reference} ip=#{self.config.ip.inspect} " \
+      "port=#{self.config.port.inspect}>"
+    end
+
+    protected
+
+    def request_handler(request)
+      handler_class(get_handler_class_name(request)).new(self.logger, request)
+    end
+
+    def handler_class(class_name_str)
+      self.logger.info("  Handler: #{class_name_str.inspect}")
+      Sanford::ServiceHandler.constantize(class_name_str).tap do |handler_class|
+        raise Sanford::NoHandlerClassError.new(self, class_name_str) if !handler_class
+      end
+    end
+
+    def get_handler_class_name(request)
+      services = self.config.versioned_services[request.version] || {}
+      services[request.name].tap do |name|
+        raise Sanford::NotFoundError if !name
+      end
+    end
+
+    def remove_nil_values(options)
+      (options || {}).inject({}) do |hash, (k, v)|
+        hash.merge!({ k => v }) if !v.nil?
+        hash
+      end
+    end
+
+    module Interface
+
+      INTERFACE_OPTIONS.each do |name|
+
+        define_method(name) do |*args|
+          self.config.send("#{name}=", *args) if !args.empty?
+          self.config.send(name)
+        end
+
+        define_method("#{name}=") do |new_value|
+          self.config.send("#{name}=", new_value)
+        end
+
+      end
+
+      def version(name, &block)
+        version_group = Sanford::Host::VersionGroup.new(name, &block)
+        self.config.versioned_services.merge!(version_group.to_hash)
+      end
+
+    end
+
+    class VersionGroup
+      attr_reader :name, :services
+
+      def initialize(name, &definition_block)
+        @name = name
+        @services = {}
+        self.instance_eval(&definition_block)
+      end
+
+      def service_handler_ns(value = nil)
+        @service_handler_ns = value if value
+        @service_handler_ns
+      end
+
+      def service(service_name, handler_class_name)
+        if self.service_handler_ns && !(handler_class_name =~ /^::/)
+          handler_class_name = "#{self.service_handler_ns}::#{handler_class_name}"
+        end
+        @services[service_name] = handler_class_name
+      end
+
+      def to_hash
+        { self.name => self.services }
+      end
+
+    end
+
+  end
+end

data/lib/sanford/manager.rb

@@ -0,0 +1,58 @@
+# The Manager class is responsible for managing sanford's server process. Given
+# a host, it can start and stop the host's server process. This is done using
+# the Daemons gem and `run_proc`. The class provides a convenience method on the
+# class called `call`, which will find a host, build a new manager and call the
+# relevant action (this is what the rake tasks use).
+#
+require 'daemons'
+
+require 'sanford/config'
+require 'sanford/exceptions'
+require 'sanford/server'
+
+module Sanford
+
+  class Manager
+    attr_reader :host, :process_name
+
+    def self.call(action, options = nil)
+      options ||= {}
+      options[:host]  ||= ENV['SANFORD_HOST']
+      options[:ip]    ||= ENV['SANFORD_IP']
+      options[:port]  ||= ENV['SANFORD_PORT']
+
+      host_class = if (host_class_or_name = options.delete(:host))
+        Sanford.config.find_host(host_class_or_name)
+      else
+        Sanford.config.hosts.first
+      end
+      raise(Sanford::NoHostError.new(host_class_or_name)) if !host_class
+      self.new(host_class, options).call(action)
+    end
+
+    def initialize(host_class, options = {})
+      @host = host_class.new(options)
+      @process_name = [ self.host.ip, self.host.port, self.host.name ].join('_')
+    end
+
+    def call(action)
+      options = self.default_options.merge({ :ARGV => [ action.to_s ] })
+      FileUtils.mkdir_p(options[:dir])
+      ::Daemons.run_proc(self.process_name, options) do
+        server = Sanford::Server.new(self.host)
+        server.start
+        server.join_thread
+      end
+    end
+
+    protected
+
+    def default_options
+      { :dir_mode   => :normal,
+        :dir        => self.host.pid_dir
+      }
+    end
+
+  end
+
+end

data/lib/sanford/rake.rb

@@ -0,0 +1,45 @@
+module Sanford::Rake
+
+  class Tasks
+    extend ::Rake::DSL
+
+    def self.load
+      namespace :sanford do
+
+        # Overwrite this to load your application's environment so that it can
+        # be used with Sanford
+        task :setup
+
+        task :load_manager => :setup do
+          require 'sanford'
+          Sanford.init
+        end
+
+        desc "Start a Sanford server and daemonize the process"
+        task :start => :load_manager do
+          Sanford::Manager.call :start
+        end
+
+        desc "Stop a daemonized Sanford server process"
+        task :stop => :load_manager do
+          Sanford::Manager.call :stop
+        end
+
+        desc "Restart a daemonized Sanford server process"
+        task :restart => :load_manager do
+          Sanford::Manager.call :restart
+        end
+
+        desc "Run a Sanford server (not daemonized)"
+        task :run => :load_manager do
+          Sanford::Manager.call :run
+        end
+
+      end
+    end
+
+  end
+
+end
+
+Sanford::Rake::Tasks.load

data/lib/sanford/server.rb

@@ -0,0 +1,39 @@
+# Sanford's server uses DatTCP for a TCP Server. When a client connects, the
+# `serve` method is called. Sanford creates a new instance of a connection
+# handler and hands it the service host and client socket. This is because the
+# `serve` method can be accessed by multiple threads, so we essentially create a
+# new connection handler per thread.
+#
+require 'dat-tcp'
+
+require 'sanford/connection'
+
+module Sanford
+
+  class Server
+    include DatTCP::Server
+
+    attr_reader :service_host
+
+    def initialize(service_host, options = {})
+      @service_host = service_host
+      super(self.service_host.ip, self.service_host.port, options)
+    end
+
+    def name
+      self.service_host.name
+    end
+
+    def serve(socket)
+      connection = Sanford::Connection.new(self.service_host, socket)
+      connection.process
+    end
+
+    def inspect
+      reference = '0x0%x' % (self.object_id << 1)
+      "#<#{self.class}:#{reference} @service_host=#{self.service_host.inspect}>"
+    end
+
+  end
+
+end

data/lib/sanford/service_handler.rb

@@ -0,0 +1,93 @@
+require 'ostruct'
+require 'sanford-protocol'
+
+module Sanford
+
+  module ServiceHandler
+
+    def self.constantize(class_name)
+      names = class_name.to_s.split('::').reject{|name| name.empty? }
+      klass = names.inject(Object) do |constant, name|
+        constant.const_get(name)
+      end
+      klass == Object ? false : klass
+    rescue NameError
+      false
+    end
+
+    attr_reader :logger, :request
+
+    def initialize(logger, request)
+      @logger = logger
+      @request = request
+    end
+
+    def init
+      self.init!
+    end
+
+    def init!
+    end
+
+    # This method has very specific handling when before/after callbacks halt.
+    # It should always return a response tuple: `[ status, data ]`
+    # * If `before_run` halts, then the handler is not 'run' (it's `init` and
+    #   `run` methods are not called) and it's response tuple is returned.
+    # * If `after_run` halts, then it's response tuple is returned, even if
+    #   calling `before_run` or 'running' the handler generated a response
+    #   tuple.
+    # * If `before_run` and `after_run` do not halt, then the response tuple
+    #   from 'running' is used.
+    def run
+      response_tuple = self.run_callback 'before_run'
+      response_tuple ||= catch(:halt) do
+        self.init
+        data = self.run!
+        [ 200, data ]
+      end
+      after_response_tuple = self.run_callback 'after_run'
+      (response_tuple = after_response_tuple) if after_response_tuple
+      response_tuple
+    end
+
+    def run!
+      raise NotImplementedError
+    end
+
+    def before_run
+    end
+
+    def after_run
+    end
+
+    def params
+      self.request.params
+    end
+
+    def inspect
+      reference = '0x0%x' % (self.object_id << 1)
+      "#<#{self.class}:#{reference} @request=#{self.request.inspect}>"
+    end
+
+    protected
+
+    def halt(status, options = nil)
+      options = OpenStruct.new(options || {})
+      response_status = [ status, options.message ]
+      throw(:halt, [ response_status, options.data ])
+    end
+
+    # Notes:
+    # * Callbacks need to catch :halt incase the halt method is called. They
+    #   also need to be sure to return nil if nothing is thrown, so that it
+    #   is not considered as a response.
+    def run_callback(name)
+      catch(:halt) do
+        self.send(name.to_s)
+        nil
+      end
+    end
+
+  end
+
+end

data/lib/sanford/version.rb

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

data/lib/sanford.rb

@@ -0,0 +1,32 @@
+module Sanford; end
+
+require 'sanford/config'
+require 'sanford/manager'
+require 'sanford/host'
+require 'sanford/version'
+
+module Sanford
+
+  def self.config
+    Sanford::Config
+  end
+
+  def self.configure(&block)
+    self.config.define(&block)
+    self.config
+  end
+
+  def self.init
+    require self.config.services_config
+  end
+
+  class NullLogger
+    require 'logger'
+
+    Logger::Severity.constants.each do |name|
+      define_method(name.downcase){|*args| } # no-op
+    end
+
+  end
+
+end

data/sanford.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'sanford/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "sanford"
+  gem.version       = Sanford::VERSION
+  gem.authors       = ["Collin Redding", "Kelly Redding"]
+  gem.email         = ["collin.redding@me.com", "kelly@kellyredding.com"]
+  gem.description   = "Simple hosts for Sanford services."
+  gem.summary       = "Simple hosts for Sanford services."
+  gem.homepage      = "https://github.com/redding/sanford"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency("daemons",           ["~>1.1"])
+  gem.add_dependency("dat-tcp",           ["~>0.1"])
+  gem.add_dependency("ns-options",        ["~>1.0.0"])
+  gem.add_dependency("sanford-protocol",  ["~>0.5"])
+
+  gem.add_development_dependency("assert",        ["~>1.0"])
+  gem.add_development_dependency("assert-mocha",  ["~>1.0"])
+end

data/test/helper.rb

@@ -0,0 +1,20 @@
+ENV['SANFORD_PROTOCOL_DEBUG'] = 'yes'
+
+require 'ostruct'
+
+ROOT = File.expand_path('../..', __FILE__)
+
+require 'sanford'
+
+Sanford.configure do |config|
+  config.services_config = File.join(ROOT, 'test/support/services')
+end
+Sanford.init
+
+require 'test/support/service_handlers'
+require 'test/support/simple_client'
+require 'test/support/helpers'
+
+if defined?(Assert)
+  require 'assert-mocha'
+end

data/test/support/helpers.rb

@@ -0,0 +1,72 @@
+module Test
+
+  module Environment
+
+    def self.store_and_clear_hosts
+      @previous_hosts = Sanford.config.hosts.dup
+      Sanford.config.hosts.clear
+    end
+
+    def self.restore_hosts
+      Sanford.config.hosts = @previous_hosts
+      @previous_hosts = nil
+    end
+
+  end
+
+
+
+  module ForkServerHelper
+
+    def start_server(server, &block)
+      begin
+        pid = fork do
+          trap("TERM"){ server.stop }
+          server.start
+          server.join_thread
+        end
+        sleep 0.3 # Give time for the socket to start listening.
+        yield
+      ensure
+        if pid
+          Process.kill("TERM", pid)
+          Process.wait(pid)
+        end
+      end
+    end
+
+  end
+
+
+
+  module ForkManagerHelper
+
+    # start a Sanford server using Sanford's manager in a forked process
+    def call_sanford_manager(*args, &block)
+      pid = fork do
+        STDOUT.reopen('/dev/null')
+        trap("TERM"){ exit }
+        Sanford::Manager.call(*args)
+      end
+      sleep 1 # give time for the command to run
+      yield
+    ensure
+      if pid
+        Process.kill("TERM", pid)
+        Process.wait(pid)
+      end
+    end
+
+    def open_socket(host, port)
+      socket = TCPSocket.new(host, port)
+    ensure
+      socket.close rescue false
+    end
+
+    def expected_pid_file(host, ip, port)
+      host.config.pid_dir.join("#{ip}_#{port}_#{host}.pid")
+    end
+
+  end
+
+end

data/test/support/service_handlers.rb

@@ -0,0 +1,115 @@
+# A bunch of service handler examples. These are defined to implement certain
+# edge cases and are for specific tests within the test suite.
+#
+
+class StaticServiceHandler
+  include Sanford::ServiceHandler
+
+  # builds with the same request and logger always, just for convenience
+
+  def initialize(logger = nil, request = nil)
+    request ||= Sanford::Protocol::Request.new('v1', 'name', {})
+    super(logger || Sanford::NullLogger.new, request)
+  end
+
+end
+
+class ManualThrowServiceHandler < StaticServiceHandler
+
+  def run!
+    throw(:halt, 'halted!')
+  end
+
+end
+
+class HaltWithServiceHandler < StaticServiceHandler
+
+  def initialize(halt_with)
+    request = Sanford::Protocol::Request.new('v1', 'name', {
+      'halt_with' => halt_with.dup
+    })
+    super(Sanford::NullLogger.new, request)
+  end
+
+  def run!
+    params['halt_with'].tap do |halt_with|
+      halt(halt_with.delete('code'), halt_with)
+    end
+  end
+
+end
+
+class NoopServiceHandler < StaticServiceHandler
+
+  # simply overwrites the default `run!` so it doesn't error
+
+  def run!
+    # nothing!
+  end
+
+end
+
+class FlaggedServiceHandler < NoopServiceHandler
+
+  # flags a bunch of methods as they are run by setting instance variables
+
+  FLAGGED_METHODS = {
+    'init'        => :init_called,
+    'init!'       => :init_bang_called,
+    'run!'        => :run_bang_called,
+    'before_run'  => :before_run_called,
+    'after_run'   => :after_run_called
+  }
+  FLAGS = FLAGGED_METHODS.values
+
+  attr_reader *FLAGS
+
+  def initialize(*passed)
+    super
+    FLAGS.each{|name| self.instance_variable_set("@#{name}", false) }
+  end
+
+  FLAGGED_METHODS.each do |method_name, instance_variable_name|
+
+    # def before_run
+    #   super
+    #   @before_run_called = true
+    # end
+    define_method(method_name) do
+      super
+      self.instance_variable_set("@#{instance_variable_name}", true)
+    end
+
+  end
+
+end
+
+class ConfigurableServiceHandler < FlaggedServiceHandler
+
+  def initialize(options = {})
+    @options = options
+    super
+  end
+
+  def before_run
+    super
+    if @options[:before_run]
+      self.instance_eval(&@options[:before_run])
+    end
+  end
+
+  def run!
+    super
+    if @options[:run!]
+      self.instance_eval(&@options[:run!])
+    end
+  end
+
+  def after_run
+    super
+    if @options[:after_run]
+      self.instance_eval(&@options[:after_run])
+    end
+  end
+
+end