jerbil 1.2.2

data/lib/jerbil/config.md

@@ -0,0 +1,49 @@
+# Jerbil::Config Parameters
+
+The following parameters are defined in {Jerbil::Config} and should be used
+in a configuration file. A default config file can be generated using:
+
+    jeckyl config lib/jerbil/config.rb
+
+## Parameters
+
+ * **net_mask**
+ 
+    A valid netmask for the hosts to search using the above net address. This should be
+    between 24 (a class C network) and 30, beyound which its not much of a network. If you only have a few
+    hosts it will be easier to restrict them to a small subnet.
+    
+    To find out more about netmasks, go to [UnixWiz](http://www.unixwiz.net/techtips/netmask-ref.html).
+
+    Default: 26
+
+ * **scan_timeout**
+ 
+    Provide a timeout when searching for jerbil servers on the net during startup.
+    Depending on the size of the net mask this timeout may make the search long.
+    The default should work in most cases
+
+    Default: 0.1
+
+ * **net_address**
+ 
+    A valid IPv4 address for the LAN on which the servers will operate.
+    Note that the broker uses this address to search for all servers.
+    Therefore a large range will take a long time to search. Set the net_mask to limit this.
+
+    Default: "192.168.0.1"
+
+ * **secret**
+ 
+    A secret key available to all Jerbil Servers and used to authenticate the initial registration.
+    If security is an issue, ensure that this config file is readable only be trusted users
+
+    No default set
+
+
+## See Also
+
+There are also parameters in:
+
+ * {JerbilService::Config}
+ * Jelly::Options

data/lib/jerbil/config.rb

@@ -0,0 +1,67 @@
+#
+#
+# = Jerbil Config
+#
+# == Update to use Jeckyl::Service
+#
+# Author:: Robert Sharp
+# Copyright:: Copyright (c) 2012 Robert Sharp
+# License:: Open Software Licence v3.0
+#
+# This software is licensed for use under the Open Software Licence v. 3.0
+# The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+# and in the file copyright.txt. Under the terms of this licence, all derivative works
+# must themselves be licensed under the Open Software Licence v. 3.0
+#
+# 
+#
+
+require 'jerbil/jerbil_service/config'
+
+
+module Jerbil
+  
+  # Jeckyl config parameters for the Jerbil Server
+  #
+  # The config file will include all of the parameters defined in {JerbilService::Config}
+  # and its parents, such as key directories, logging parameters etc.
+  #
+  # @see file:lib/jerbil/config.md Jerbil Parameter Descriptions
+  # @see file:lib/jerbil/jerbil_service/config.md Jerbil Service Parameter Descriptions
+  class Config < JerbilService::Config
+    
+    def configure_net_address(naddr)
+      default '192.168.0.1'
+      comment "A valid IPv4 address for the LAN on which the servers will operate.",
+        "Note that the broker uses this address to search for all servers.",
+        "Therefore a large range will take a long time to search. Set the net_mask to limit this."
+      a_matching_string(naddr, /\A\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/)
+    end
+    
+    def configure_net_mask(nmask)
+      default 26
+      comment "A valid netmask for the hosts to search using the above net address. This should be",
+        "between 24 (a class C network) and 30, beyound which its not much of a network. If you only have a few",
+        "hosts it will be easier to restrict them to a small subnet.",
+        "",
+        "To find out more about netmasks, go to [UnixWiz](http://www.unixwiz.net/techtips/netmask-ref.html)."
+      in_range(nmask, 24, 30)
+    end
+    
+    def configure_scan_timeout(tim)
+      default 0.1
+      comment "Provide a timeout when searching for jerbil servers on the net during startup.",
+        "Depending on the size of the net mask this timeout may make the search long.",
+        "The default should work in most cases"
+        
+      a_type_of(tim, Numeric)
+    end
+    
+    def configure_secret(scrt)
+      comment "A secret key available to all Jerbil Servers and used to authenticate the initial registration.",
+       "If security is an issue, ensure that this config file is readable only be trusted users"
+      a_type_of(scrt, String)
+    end
+    
+  end
+end

data/lib/jerbil/errors.rb

@@ -0,0 +1,74 @@
+#
+# Description
+#
+# Author:: Robert Sharp
+# Copyright:: Copyright (c) 2010 Robert Sharp
+# License:: Open Software Licence v3.0
+#
+# This software is licensed for use under the Open Software Licence v. 3.0
+# The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+# and in the file copyright.txt. Under the terms of this licence, all derivative works
+# must themselves be licensed under the Open Software Licence v. 3.0
+# 
+# 
+
+module Jerbil
+
+  # general error type
+  class JerbilError < RuntimeError; end
+
+  # create a class for all service related errors
+  class JerbilServiceError < JerbilError; end
+
+  # error while trying to connect to a Jerbil-registered service
+  class ServiceConnectError < JerbilServiceError; end
+
+  # the service being registered is not in /etc/services
+  class InvalidService < JerbilServiceError; end
+
+  # the config file used by the service raised an error
+  class ServiceConfigError < JerbilServiceError; end
+
+  # the key used was not the key created for this service
+  class InvalidServiceKey < JerbilServiceError; end
+
+  # there is no callback defined where one should be
+  class ServiceCallbackMissing < JerbilServiceError; end
+
+  # there is already a service with these details registered with the Jerbil Server
+  class ServiceAlreadyRegistered < JerbilServiceError; end
+
+  # the service being registered is not local
+  class ServiceNotLocal < JerbilServiceError; end
+
+  # tried to do something to a service without access
+  class UnauthorizedMethod < JerbilServiceError; end
+
+  # there is no service
+  class ServiceNotFound < JerbilServiceError; end
+
+  # create a class for all server related errors
+  class JerbilServerError < JerbilError; end
+  
+  # authentication of a server etc failed
+  class JerbilAuthenticationError < JerbilError; end
+
+  # error in the jerbil config file
+  class JerbilConfigError < JerbilServerError; end
+  
+  # no jerbil service
+  class MissingJerbilService < JerbilServerError; end
+
+  # failed to find the server in the list of servers provided in config
+  class MissingServer < JerbilServerError; end
+
+  # error while trying to connect to a Jerbil Server
+  class ServerConnectError < JerbilServerError; end
+
+  # the server key provided for a remote operation does not match any known server
+  class InvalidServerKey < JerbilServerError; end
+
+  # the master key provided for a system operation does not match this master key
+  class InvalidPrivateKey < JerbilServerError; end
+
+end

data/lib/jerbil/jerbil_service/base.rb

@@ -0,0 +1,191 @@
+#
+# Description
+#
+# Author:: Robert Sharp
+# Copyright:: Copyright (c) 2010 Robert Sharp
+# License:: Open Software Licence v3.0
+#
+# This software is licensed for use under the Open Software Licence v. 3.0
+# The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+# and in the file copyright.txt. Under the terms of this licence, all derivative works
+# must themselves be licensed under the Open Software Licence v. 3.0
+# 
+#
+require 'jerbil/service'
+require 'jerbil/servers'
+require 'jerbil/errors'
+require 'jerbil/config'
+require 'jerbil/support'
+require 'jellog'
+require 'jellog/config'
+require 'socket'
+require 'drb'
+
+# == Jerbil Service
+#
+# Designed to help create ruby services easily, hiding all of the interactions with
+# Jerbil itself.
+#
+# To create a service, create a service module (e.g. RubyTest) and within that a
+# service class (e.g. RubyTest::Service) that whose parent is JerbilService::Base
+# You can add a config file by copying the jerbil_service/config template and changing
+# the module to your module (e.g. RubyTest::Config). Finally, use the jerbil_service/support
+# module to extend your base module to include the get_config method.
+#
+#   module RubyTest
+#
+#     extend JerbilService::Support
+#
+#     class Service < JerbilService::Base
+#
+#       def initialize(pkey, options)
+#
+#         super(:rubytest, pkey, options)
+#
+#       end
+#     end
+#   end
+#
+# See also the Client, MultiClient and SuperClient classes to assist with a complete solution.
+#
+#
+module JerbilService
+
+  # == JerbilService::Base
+  #
+  # Parent class to be used for all services. Manages all interactions with Jerbil
+  # and sets up a Jellog logger.
+  #
+  # In general, services using this class are intended to be started and stopped
+  # using {JerbilService::Supervisor} and clients are expected to interact with the
+  # service through {JerbilService::Client}.
+  #
+  # Further details can be found in {file:README_SERVICES.md Jerbil Service Readme}
+  #
+  class Base
+    
+    # create a Jerbil Service
+    #
+    # @param [String] name - symbol for the service needs to correspond with /etc/services
+    # @param [String] pkey - private key used for privileged methods
+    # @param [Hash] options for the service. The easiest way to generate this hash is to use
+    #   Jeckyl and inherit the {JerbilService::Config} class. See class description for details of
+    #   the options required by a service
+    def initialize(name, pkey, options)
+      @name = name.to_s.capitalize
+      @env = options[:environment]
+      @private_key = pkey
+      
+      # change the process name 
+      $0 = "#{@name.downcase}-#{@env}"
+      
+      # start up a logger
+      log_opts = Jellog::Config.intersection(options)
+      @logger = Jellog::Logger.new(@name, log_opts)
+      # @logger.log_level = options[:log_level]
+      
+      @exit = options[:exit_on_stop]
+
+      begin
+        @service = Jerbil::ServiceRecord.new(name, @env, :verify_callback, :stop_callback)
+
+        # register the service
+        # Note that if the options hash includes a :jerbil_env, then this
+        # will be passed to select a Jerbil system running at other than :prod, the default
+        # This is not documented above because it is for testing Jerbil only
+        @jerbil_server = Jerbil::Servers.get_local_server(options[:jerbil_env])
+
+        # now connect to it
+        jerbil = @jerbil_server.connect
+
+        # and register self
+        jerbil.register(@service)
+
+        # and start it - preventing anything nasty from coming over DRb
+        $SAFE = 1 unless options[:unsafe]
+        DRb.start_service(@service.drb_address, self)
+
+      rescue Jerbil::MissingServer
+        @logger.fatal("Cannot find a local Jerbil server")
+        raise
+      rescue Jerbil::JerbilConfigError => err
+        @logger.fatal("Error in Jerbil Config File: #{err.message}")
+        raise
+      rescue Jerbil::JerbilServiceError =>jerr
+        @logger.fatal("Error with Jerbil Service: #{jerr.message}")
+        raise
+      rescue Jerbil::ServerConnectError
+        @logger.fatal("Error connecting to Jerbil Server")
+        raise
+      rescue DRb::DRbConnError =>derr
+        @logger.fatal("Error setting up DRb Server: #{derr.message}")
+        raise Jerbil::ServerConnectError
+      end
+
+      @logger.system "Started service: #{@service.ident}"
+    end
+
+    # give access to {Jerbil::ServiceRecord} Record for this service
+    # @deprecated - unless I can find why I allowed it!
+    attr_reader :service
+
+    # return the DRb address for the service
+    # @deprecated - as above
+    def drb_address
+      @service.drb_address
+    end
+
+    # this is used by callers just to check that the service is running
+    # if caller is unaware of the key, this will fail
+    #
+    # @param [String] skey - private key given to the service when created
+    #
+    # This method is not intended to be called directly. It is usually
+    # called when connecting to the service (see {Jerbil::ServiceRecord#connect}).
+    #
+    def verify_callback(skey="")
+      check_key(skey, @service.key)
+      @logger.info "Verify called"
+      return true
+    end
+
+    # used to stop the service. Requires the private key
+    #
+    # @param [String] pkey - private key given when service is created
+    #
+    # This method is not intended to be called directly. To stop a service, the
+    # user should use the {JerbilService::Supervisor} class.
+    #
+    def stop_callback(pkey="")
+      check_key(pkey)
+      # deregister
+      jerbil = @jerbil_server.connect
+      jerbil.remove(@service)
+      @logger.system "Stopped service: #{@service.ident}"
+      @logger.close
+      # and stop the DRb service, to exit gracefully
+      DRb.stop_service
+    end
+
+    # wait for calls. This hides the DRb call to be made once the
+    # service is up and running. It is not intended to be called by
+    # anyone outside of {JerbilService::Supervisor}
+    #
+    def wait(pkey='')
+      check_key(pkey)
+      DRb.thread.join
+    end
+
+  protected
+
+    # convenience method to check that the given key is the object's private key
+    # and raise {Jerbil::InvalidServiceKey} if not
+    def check_key(key, my_key = @private_key)
+      if key != my_key then
+        @logger.debug "Key mismatch: given #{key} but need #{my_key}"
+        raise Jerbil::InvalidServiceKey, @logger.error("Call made with Invalid Service Key: #{key}")
+      end
+    end
+
+  end
+end

data/lib/jerbil/jerbil_service/client.rb

@@ -0,0 +1,325 @@
+#
+# == Jerbil Client Interface
+#
+# Author:: Robert Sharp
+# Copyright:: Copyright (c) 2011 Robert Sharp
+# License:: Open Software Licence v3.0
+#
+# This software is licensed for use under the Open Software Licence v. 3.0
+# The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+# and in the file copyright.txt. Under the terms of this licence, all derivative works
+# must themselves be licensed under the Open Software Licence v. 3.0
+# 
+#
+
+require 'jerbil/config'
+require 'jeckyl/errors'
+require 'jerbil/errors'
+require 'jerbil/servers'
+require 'jerbil/service'
+require 'socket'
+
+module JerbilService
+
+
+  #
+  # JerbilService::Client provides a wrapper around a {JerbilService::Base} type service that hides
+  # all interaction with Jerbil itself, enabling client interfaces with a service to be constructed
+  # quickly and painlessly
+  #
+  # To use, call the {JerbilService::Client.find_services} method, which yields a block for
+  # each matching service registered with the Jerbil Server. The service's methods can then 
+  # be called on the yielded object, which are then transparently passed back to the
+  # service itself. 
+  #
+  # It should always be remembered that these method calls will be mediated through Ruby's
+  # DRb mechanisms and therefore access to objects across this interface may not be
+  # the same as accessing them directly. See {file:README_SERVICES.md Services Readme} for
+  # more details
+  #
+  class Client
+
+    private_class_method :new
+
+    # return the server's config options for the given file, or the default if none given
+    # 
+    # @param [Object] modl must be the constant name of the service's module.
+    # @param [String] config_file is an optional path to a Jeckyl config file
+    #
+    # This method uses [Jeckyl]() to obtain the config parameters. The module name
+    # is expected to follow the guidelines for a JerbilService: create a module
+    # with the service's name (echoed in the gem name etc) and then a class
+    # called Service. The parameter passed in is the module name as a constant
+    #
+    #    config = JerbilService::Client.get_config(MyService)
+    #
+    def self.get_config(modl, config_file=nil)
+      modl.get_config(config_file)
+    end
+
+    # Connect to a one or more instances of a service using Jerbil
+    #
+    #
+    # The method will search the Jerbil Server for services of the given module, as
+    # defined by the what parameter:
+    # * :first, yields the block once with the first service regardless of how many services there are
+    #  and with no guarantee about which services this might be
+    # * :local, yields the service running on the same processor as the client
+    # * :all, yields the block for each service.
+    # Within the block, the user can call any of the service's methods, together with the
+    # instance methods of the client itself.
+    #
+    # For example, to find a service running on a particular host:
+    #
+    #    JerbilService::Client.find_services(:all, MyService, opts) do |service|
+    #      if service.host == 'a_server.network.com' then
+    #        # found the services I am looking for, now do something
+    #        ...
+    #      end
+    #    end
+    #
+    # To find a service running in a particular environment, you need to set the
+    # above option:
+    #    opts = {:environment => :dev}
+    #    JerbilService::Client.find_services(:all, MyService, opts) do ...
+    #
+    # If you want to use a config file to access this information, you can use
+    # {JerbilService::Client.get_config} and extract the env information:
+    #
+    #    config = JerbilService::Client.get_config(MyService)
+    #    opts[:environment] = config[:environment]
+    #    ...
+    #
+    # The connection to the service is closed when the block exits.
+    #
+    # @param [Symbol] what being one of :first, :all or :local
+    # @param [Object] modl - constant for the service module
+    # @param [Hash] options - hash of the following
+    # @option options [Boolean]  :quiet suppress messages on stdout (default: false)
+    # @option options [Boolean]   :local find only the local service (default: false)
+    # @option options [IO]    :output a file object or similar (not filename) to be used 
+    #   for output - defaults to $stderr. Is overridden with /dev/null if quiet.
+    # @option options [Boolean]   :welcome output additional messages to stdout suitable for standalone operation
+    # @option options [Symbol]    :environment being that which the service is operating in (:dev, :test, :prod)
+    # @yield [service] a client instance for each matching service registered with Jerbil
+    def self.find_services(what, modl, options={}, &block)
+
+      case what
+      when :first
+        select = :first
+      when :all
+        select = :all
+      when :local
+        select = :first
+        options[:local] = true
+      else
+        raise ArgumentError, "Find Services invalid search key: #{what}"
+      end
+
+      unless options[:environment]
+        # set the default environment if not already set
+        options[:environment] = :prod
+      end
+
+      new(modl, options) do |client|
+        client.connect(select, &block)
+      end
+    end
+
+    # backwards compatible method to connect to first service using environment
+    # defined in config_file which is read in from options[:config_file] or the default
+    # location (see get_config)
+    # 
+    # @deprecated Use {JerbilService::Client.find_services} instead
+    #
+    # @param (see find_services)
+    # @option (see find_services)
+    #
+    def self.connect(modl, options={}, &block) # :yields: client
+
+      config_file = options[:config_file]
+      config = modl.get_config(config_file)
+
+      options[:environment] ||= config[:environment]
+      options[:jerbil_env] ||= config[:jerbil_env]
+
+      self.find_services(:first, modl, options, &block)
+
+    end
+
+
+    # @private create a client instance and call the block. Should be used internally only
+    def initialize(modl, options, &block)
+
+      @klass = modl::Service
+      name = modl.to_s
+      name_symbol = name.downcase.to_sym
+
+      quiet = options[:quiet]
+      unless quiet
+        @output = options[:output] || $stderr
+      else
+        @output = File.open('/dev/null', 'w')
+      end
+      
+      @welcome = options[:welcome]
+
+      @output.puts "Welcome to #{name} (#{modl.ident})" if @welcome
+
+      unless quiet
+        @output.puts "Options:"
+        options.each {|key, val| @output.puts("  #{key}:#{val}") }
+      end
+
+      env = options[:environment]
+
+      service_opts = {:name=>name_symbol, :env=>env}
+      service_opts[:host] = Socket.gethostname if options[:local]
+
+      begin
+        # find jerbil
+        @jerbil_server = Jerbil::Servers.get_local_server(options[:jerbil_env])
+
+        # now connect to it
+        jerbil = @jerbil_server.connect
+
+        # and find all of the services
+        @services = []
+        @services = jerbil.find(service_opts)
+
+        if @services.length == 0 then
+          @output.puts "No services for #{name}[:#{env}] were found"
+          raise Jerbil::ServiceNotFound, "No services for #{name}[:#{env}] were found"
+        end
+
+        block.call(self)
+
+        @output.puts "Stopping the service" if @welcome
+        #output.close unless @output == $stderr
+
+        return nil # give the caller nothing back
+
+      rescue Jerbil::MissingServer
+        @output.puts("Cannot find a local Jerbil server")
+        raise
+      rescue Jerbil::JerbilConfigError => err
+        @output.puts("Error in Jerbil Config File: #{err.message}")
+        raise
+      rescue Jerbil::JerbilServiceError =>jerr
+        @output.puts("Error with Jerbil Service: #{jerr.message}")
+        raise
+      rescue Jerbil::ServerConnectError
+        @output.puts("Error connecting to Jerbil Server")
+        raise
+      rescue DRb::DRbConnError =>derr
+        @output.puts("Error setting up DRb Server: #{derr.message}")
+        raise Jerbil::ServerConnectError
+      end
+
+    end
+
+    #private
+
+    # @private connect to the client
+    def connect(index=:all, &block)
+
+      if index == :first then
+        @session = @services[0].connect
+        @service = @services[0]
+        block.call(self)
+
+        @session = nil
+      else
+        @services.each do |service|
+          @service = service
+          @session = service.connect
+          block.call(self)
+        end
+      end
+
+    end
+
+    # verify that the service is working
+    #
+    # This is really a no-op in that if the client has entered the block successfully, then
+    # the service that is passed to the block will be working and therefore this call
+    # will always return true. Consider it a placebo statement for a client interface
+    # that only wants to check the service is running!
+    #
+    # @return [Boolean] indicating if the services if running
+    #
+    def verify
+      @session != nil
+    end
+
+
+    # return the name of the host on which the service is running
+    #
+    # @return [String] FQDN of the host on which the service is running
+    def host
+      return @service.host
+    end
+
+    # return the service key for the given service, which can be used
+    # by the caller where a method requires. See {file:README_SERVICES.md Services Readme}
+    # for details about keys.
+    #
+    # @return [String] key to use to connect to service methods requiring it
+    def service_key
+      return @service.key
+    end
+
+    # @private allow client to pass on methods to the remote service
+    #
+    def method_missing(symb, *parameters)
+
+      # stop anyone from calling the stop method
+      raise Jerbil::UnauthorizedMethod if symb == :stop_callback
+
+      # make sure this is a valid method of the receiving instance
+      # This is needed cos sending an unknown method over DRb with $SAFE = 1
+      # raises a Security Error. Could catch this, but it might happen for
+      # different reasons so best not to.
+      
+      # need to fix symbols problem
+      if String.instance_methods.first.instance_of?(String) then
+        # < 1.9 Ruby
+        method_id = symb.to_s
+        @output.puts "Setting method id to a string: #{method_id}"
+      else
+        method_id = symb
+        @output.puts "Ensuring method id is a symbol: #{method_id}"
+      end
+      
+      unless @klass.instance_methods.include?(method_id)
+        @output.puts "Failed to find method id:"
+        @output.puts "#{@klass.instance_methods.inspect}"
+        raise NoMethodError, "Failed to find method: #{method_id}"
+      end
+
+      retries = 0
+      begin
+
+        @session.send(symb, *parameters)
+
+      rescue DRb::DRbConnError
+        # service did not respond nicely
+        @output.puts "Failed to connected to the service - checking its OK" 
+        jerbil = @jerbil_server.connect
+        if jerbil.service_missing?(@service) then
+          # something nasty has occurred
+          @output.puts "Jerbil confirms the service is missing"
+          raise Jerbil::ServiceConnectError, "Service is missing"
+        else
+          # seems jerbil thinks its ok, so try again
+          retries += 1
+          @output.puts "Jerbil thinks the service is OK, retrying"
+          retry unless retries > 2
+          @output.puts "Retried too many times, giving up"
+          raise Jerbil::ServiceConnectError, "Service is not responding"
+        end
+      end
+    end
+
+  end
+end