jerbil 1.2.2

data/lib/jerbil/jerbil_service/config.md

@@ -0,0 +1,119 @@
+# JerbilService::Config Parameters
+
+The following parameters are defined in {JerbilService::Config} and should be used
+in a configuration file. A default config file can be generated using:
+
+    jeckyl config lib/jerbil/jerbil_service/config.rb
+
+## Parameters
+
+ * **environment**
+ 
+    Set the environment for the service to run in.
+    
+    Can be one of the following:
+      :prod - for productionised services in use across a network 
+      :test - for testing a release candidate, e.g. also across the network
+      :dev - for developing the next release
+    
+    Services can be running in all three environments at the same time. Clients
+    will need to use the appropriate config file to connect with each environment.
+
+    Default: :prod
+
+ * **key_dir**
+ 
+    a writable directory where Jerbil stores a private key for each service.
+    This key is used to authenticate systems operations, such as stopping the service.
+    It is not used for client interactions, which can require a separate service key.
+
+    Default: "/var/run/jerbil"
+
+ * **jerbil_env**
+ 
+    Set this only to use a Jerbil Server that is not running in the production environment
+
+    No default set
+
+ * **pid_dir**
+ 
+    A writable directory used to store the pid to assist in stopping reluctant servers
+
+    Default: "/var/run/jerbil"
+
+## Additional Parameters from Jellog::Config
+
+The following additional parameters are defined in Jellog::Config, which
+is an ancestor of this config class. See separate documentation for more details.
+
+### Parameters
+
+ * **disable_syslog**
+ 
+    Set to true to prevent system log calls from logging to syslog as well
+
+    Default: false
+
+ * **log_date_time_format**
+ 
+    Format string for time stamps. Needs to be a string that is recognised by String#strftime
+    Any characters not recognised by strftime will be printed verbatim, which may not be what you want
+
+    Default: "%Y-%m-%d %H:%M:%S"
+
+ * **log_rotation**
+ 
+    Number of log files to retain at any time, between 0 and 20
+
+    Default: 2
+
+ * **log_length**
+ 
+    Size of a log file (in MB) before switching to the next log, upto 20 MB
+
+    Default: 1
+
+ * **log_dir**
+ 
+    Path to a writeable directory where Jellog will save log files.
+
+    Default: "/var/log/jellog"
+
+ * **log_coloured**
+ 
+    Set to false to suppress colourful logging. Default colours can be changed by calling
+    #colours= method
+
+    Default: true
+
+ * **log_sync**
+ 
+    Setting to true (the default) will flush log messages immediately, which is useful if you
+    need to monitor logs dynamically
+
+    Default: true
+
+ * **log_level**
+ 
+    Controls the amount of logging done by Jellog
+    
+     * :system - standard message, plus log to syslog
+     * :verbose - more generous logging to help resolve problems
+     * :debug - usually used only for resolving problems during development
+    
+
+    Default: :system
+
+ * **log_reset**
+ 
+    Reset the logfile when starting logging by setting to true, otherwise append to
+    existing log
+
+    Default: false
+
+ * **log_mark**
+ 
+    Set the string to be used for marking the log with logger.mark
+
+    Default: "   ===== Mark ====="
+

data/lib/jerbil/jerbil_service/config.rb

@@ -0,0 +1,72 @@
+#
+# Template for Jerbil Service Config
+#
+# 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
+#
+# Use this template to create a service config file by adapting a copy of the jeckly_generate_config
+# utility.
+# 
+require 'jellog/config'
+
+
+module JerbilService
+  
+  
+  # configuration options for a Jerbil Service, which includes the Jellog logger and therefore
+  # inherits Jellog's options first.
+  #
+  # @see file:lib/jerbil/jerbil_service/config.md Jerbil Service Parameter Descriptions
+  #
+  class Config < Jellog::Config
+
+    def configure_environment(env)
+
+      default :prod
+      comment "Set the environment for the service to run in.",
+        "",
+        "Can be one of the following:",
+        "  :prod - for productionised services in use across a network ",
+        "  :test - for testing a release candidate, e.g. also across the network",
+        "  :dev - for developing the next release",
+        "",
+        "Services can be running in all three environments at the same time. Clients",
+        "will need to use the appropriate config file to connect with each environment."
+
+      env_set = [:prod, :test, :dev]
+      a_member_of(env, env_set)
+      
+    end
+
+    def configure_key_dir(path)
+      default '/var/run/jerbil'
+      comment "a writable directory where Jerbil stores a private key for each service.",
+        "This key is used to authenticate systems operations, such as stopping the service.",
+        "It is not used for client interactions, which can require a separate service key."
+
+      a_writable_dir(path)
+    end
+
+    def configure_pid_dir(path)
+      default '/var/run/jerbil'
+      comment "A writable directory used to store the pid to assist in stopping reluctant servers"
+
+      a_writable_dir(path)
+    end
+        
+    def configure_jerbil_env(env)
+      comment "Set this only to use a Jerbil Server that is not running in the production environment"
+      env_set = [:prod, :test, :dev]
+      a_member_of(env, env_set)
+      
+    end
+
+  end
+
+end

data/lib/jerbil/jerbil_service/sclient.rb

@@ -0,0 +1,343 @@
+#
+# 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 'rubygems'
+require 'daemons'
+require 'drb'
+require 'socket'
+
+require 'jellog'
+require 'jerbil/support'
+require 'jerbil/servers'
+require 'jeckyl/errors'
+
+module JerbilService
+
+  # Supervisor (Supervisory Client) - a wrapper class for managing a Jerbil Service
+  #
+  # Can be used to create a daemon script for a service. First gather options
+  # from the command line using optparse and then call Supervisor.new. Within the block
+  # call the methods below in response to the options on the command line. When the
+  # block closes the service will be started and will wait for calls.
+  #
+  # All of this is already done for you by /usr/sbin/jserviced. 
+  # See {file:README_SERVICES.md Services Readme} for more details.
+  #
+  class Supervisor
+
+    # create and run a service daemon for the given class, which should be a JerbilService
+    # class. 
+    #
+    # The service called through this supervisor needs to comply with Jerbil naming
+    # conventions. This requires the service to be defined within a module with the
+    # name of the service, and having a class called Service within it. See 
+    # {file:README_SERVICES.md Service Readme} for more details.
+    #
+    # The method yields a block. Within the block, use the methods below to set parameters and the service
+    # will then be launched when the block returns:
+    #
+    #    JerbilService::Supervisor.new(MyService, opts) do |service|
+    #      service.no_daemon
+    #      service.quiet
+    #    end
+    #
+    # The supervisor will start the service when the block exits.
+    #
+    #
+    # @param [Module] klass is the service module (see above)
+    # @yield [service] instance of supervisor to config
+    def initialize(klass, &block)
+
+      @daemonize = true
+      @config_file = nil
+      @verbose = false
+      @quiet = false
+      @no_syslog = false
+      @output = $stderr
+      @logger = nil
+      @set_log_daemon = false # flag to log the daemon itself
+      @jerbil_env = nil
+      @klass = klass
+      @name = klass.to_s.downcase
+      @name_symbol = @name.to_sym
+
+      # only called without a block internally to effect the stop
+      # see below
+      if block_given? then
+        block.call(self)
+      else
+        return self # created for stop
+      end
+      
+      # only gets here for a start
+      self.start_service
+
+    end
+
+    # start the service without daemonising
+    def no_daemon
+      @daemonize = false
+    end
+
+    # output extra information about starting up the service. Ignored if quiet has been set
+    # Note this controls messages from the Supervisor about the startup process
+    # and is unrelated to the service's logger
+    def verbose
+      @verbose = true unless @quiet
+    end
+
+    # output absolutely nothing
+    def quiet
+      @quiet = true
+      @verbose = false
+      @output = File.open('/dev/null', 'w')
+    end
+
+    # ensure logging does not log to syslog
+    # see Jellog::Logger#disable_syslog for details
+    def no_syslog
+      @no_syslog = true
+    end
+
+    # set the config file for the service. Each service expects an options hash, which the supervisor
+    # will obtain from either this file, or the default, which is usually: /etc/jermine/<service>.rb
+    def config_file=(cfile)
+      @config_file = cfile
+    end
+
+    # set the supervisor output to a file
+    # @param [IO] ofile is a file object to output to
+    def output=(ofile)
+      @output = ofile unless @quiet
+    end
+    
+    # create a log file for the daemon task, the output of
+    # which is otherwise lost. This uses jellog and will write the log
+    # to a file in the log_dir (see {JerbilService::Config}) named after the service with _sd added.
+    # By default this would be /var/log/jermine/<service>_sd.log
+    #
+    # This logger takes over from the output file set in {JerbilService::Supervisor#output}, but only
+    # when the supervisor daemonises.
+    #
+    def log_daemon
+      @set_log_daemon = true
+    end
+    
+    # override the default jerbil config file, used only
+    # for testing new versions of jerbil
+    #
+    # @deprecated - jerbil_env is a standard config parameter now, although still only
+    #   intended for test purposes.
+    def jerbil_env=(env)
+      @jerbil_env = env
+    end
+
+
+    # this class method if called to create an instance of the supervisor to
+    # stop a Jerbil service. Use the methods above in the block to set
+    # parameters, although some of them have no meaning in this context.
+    #
+    # @param [Module] klass is the service module of the service to stop
+    # @yield [service] instance of supervisor to config
+    def self.stop(klass, &block)
+
+      # create an instance of this class without starting the service
+      # (no block)
+      sclient = self.new(klass)
+
+      block.call(sclient)
+
+      sclient.stop_service
+
+    end
+    
+
+    # @private
+    # this method is called by the initialize method to start a Jerbil Service
+    # messages are logged through @output, which is stderr by default or
+    # /dev/null if quiet was enabled, or a Jellog logger.
+    #
+    def start_service
+
+      @output.puts "Welcome to #{@klass.to_s} (#{@klass.ident})"
+      
+      # get the config options for this service
+      config = @klass.get_config(@config_file)
+                       
+      # create a hash for logger options
+      log_opts = {}
+      
+      # to test a new jerbil server, this needs to be set to the
+      # jerbil server's environment. Only needed for test purposes
+      if @jerbil_env then
+        config[:jerbil_env] = @jerbil_env
+      end
+
+      # create a Jellog logging object if requested
+      # if @set_log_daemon then
+      #   Jellog::Logger.disable_syslog if @no_syslog
+      #   log_opts = Jellog::Logger.get_options(config)
+      #   log_opts[:log_level] = :debug if @verbose
+      #   @logger = Jellog::Logger.new("#{@klass.to_s.downcase}_sd", log_opts)
+      #   @output.puts "Logging output to #{@logger.logfilename}"
+      #   @output.flush
+      #   @output = @logger
+      # end
+
+      # log the configuration options if requested
+      if @verbose then
+        @output.puts "Obtained configuration options"
+        config.each_pair do |key, value|
+          @output.puts "  :#{key} => #{value}"
+        end
+      end
+
+      @output.puts "Running Service in environment: #{config[:environment]}"
+      
+      # create a private key for the service
+      pkey = Jerbil::Support.create_private_key(@name_symbol, config[:environment], config[:key_dir])
+
+      @output.puts "Created a private key in: #{config[:key_dir]}" if @verbose
+
+      # the service will be daemonized so need to set up daemon parameters
+      if @daemonize then
+        @output.puts "About to demonize this service"
+        # cleanly close everything
+        #@output.close
+        
+        dopts = {:backtrace=>true,
+          :app_name=>@klass.to_s.downcase + "_daemon",
+          :log_dir=>config[:log_dir],
+          :log_output=>true,
+          :dir_mode=>:normal,
+          :dir=>config[:log_dir]}
+        Daemons.daemonize(dopts)
+        
+        # all those open files are closed?
+        # so open the logger again
+        if @set_log_daemon then
+          log_opts = Jellog::Config.intersection(config)
+          log_opts[:log_level] = :debug if @verbose
+          @output = Jellog::Logger.new("#{@klass.to_s.downcase}_sd", log_opts)
+        else
+          # no logger, so write any messages to /dev/null
+          @output = File.open('/dev/null', 'w')
+        end
+        
+      else
+        @output.puts "Service is running in the foreground"
+      end
+
+      if @no_syslog then
+        @output.puts "Disabling messages to syslog"
+        Jellog::Logger.disable_syslog
+      else
+        @output.puts "Sending messages to syslog"
+      end
+
+      # now create the pid file
+      Jerbil::Support.write_pid_file(@name_symbol, config[:environment], config[:pid_dir])
+
+      @output.puts "Created a pid file for process: #{Process.pid}"
+
+      @service = @klass::Service.new(pkey, config)
+
+      @output.puts "Registered Service with Jerbil"
+
+      @service.wait(pkey)
+
+      @output.puts "Service has stopped"
+      
+    rescue => err
+      puts "Error while starting service: #{err.class.to_s}, #{err.message}"
+      puts err.backtrace.join("\n") if @verbose
+    end
+
+    # @private stop a Jerbil Service
+    def stop_service
+
+      config = @klass.get_config(@config_file)
+      pid = 0
+      
+      # to test a new jerbil server, this needs to be set to the
+      # jerbil server's environment. Only needed for test purposes
+      if @jerbil_env then
+        config[:jerbil_env] = @jerbil_env
+      end
+
+      if @verbose then
+        @output.puts "Obtained configuration options"
+        config.each_pair do |key, value|
+          @output.puts "  :#{key} => #{value}"
+        end
+      end
+
+      @output.puts "Stopping Service #{@klass.to_s} in environment: #{config[:environment]}"
+      pkey = Jerbil::Support.get_key_and_delete_file(@name_symbol, config[:environment], config[:key_dir])
+      pid = Jerbil::Support.get_pid_and_delete_file(@name_symbol, config[:environment], config[:pid_dir])
+
+      service_opts = {:name=>@name_symbol, :env=>config[:environment]}
+      service_opts[:host] = Socket.gethostname
+
+      begin
+        # find jerbil
+        jerbil_server = Jerbil::Servers.get_local_server(config[:jerbil_env])
+
+        # now connect to it
+        jerbil = jerbil_server.connect
+
+        # and get service
+        my_service = jerbil.get(service_opts)
+
+        if my_service.nil? then
+          @output.puts "Cannot find service through Jerbil"
+        end
+
+        session = my_service.connect
+
+      rescue Jerbil::MissingServer
+        @output.puts("Cannot find a local Jerbil server")
+      rescue Jerbil::JerbilConfigError => err
+        @output.puts("Error in Jerbil Config File: #{err.message}")
+      rescue Jerbil::JerbilServiceError =>jerr
+        @output.puts("Error with Jerbil Service: #{jerr.message}")
+      rescue Jerbil::ServerConnectError
+        @output.puts("Error connecting to Jerbil Server")
+      end
+
+      # now to do the stopping
+      begin
+        session.stop_callback(pkey)
+        @output.puts "Stopped service successfully"
+      rescue DRb::DRbConnError
+        @ouput.puts "Service stopped, but not gracefully"
+        return nil
+      end
+
+    rescue Jeckyl::JeckylError => jerr
+      @output.puts "Error in Configuration file: #{jerr.message}"
+      # there is no pid, so just exit
+    rescue => err
+      @output.puts "Error while stopping service: #{err.message}"
+      @output.puts err.backtrace if @verbose
+      # it went wrong, so fall back on pid killing
+      if pid > 0 then
+        @output.puts "Killing the process: #{pid}"
+        Process.kill("SIGKILL", pid)
+      else
+        @output.puts "No pid available - nothing to kill"
+      end
+    end
+  end
+  
+end