raad 0.4.1 → 0.5.0

data/CHANGELOG.md

@@ -14,6 +14,13 @@
 - tested on MRI 1.8.7 & 1.9.2, REE 1.8.7, JRuby 1.6.4 under OSX 10.6.8 and Linux Ubuntu 10.04
 
 # 0.4.1, 09-22-2011
-- allow arbitrary environment name
+- issue #1, allow arbitrary environment name, https://github.com/praized/raad/issues/1
+- issue #3, avoid calling stop multiple times,  https://github.com/praized/raad/issues/3
 - added Raad.stopped?
-- avoid calling stop multiple times, https://github.com/praized/raad/issues/3
+
+# 0.5.0, 10-12-2011
+- issue #4, allow logger usage in service initialize method, https://github.com/praized/raad/issues/4
+- issue #7, Raad.env not correct in service.initialize, https://github.com/praized/raad/issues/7
+- refactored Runner initialize/run/start_service methods
+- custom options now uses options_parser class method in the service
+- added examples/custom_options.rb

data/README.md

@@ -1,5 +1,4 @@
-# Raad v0.4.0
-
+# Raad v0.5.0
 Raad - Ruby as a daemon lightweight service wrapper.
 
 Raad is a non-intrusive, lightweight, simple Ruby daemon wrapper. Basically any class which implements
@@ -14,22 +13,20 @@ logging module and benefit easy log file output while daemonized.
 ## Installation
 
 ### Gem
-
 ``` sh
 $ gem install raad
 ```
 
 ### Bundler
-#### Latest from github
 
+#### Latest from github
 ``` sh
 gem "raad", :git => "git://github.com/praized/raad.git", :branch => "master"
 ```
 
 #### Released gem
-
 ``` bash
-gem "raad", "~> 0.4.0"
+gem "raad", "~> 0.5.0"
 ```
 
 ## Example
@@ -42,14 +39,15 @@ require 'raad'
 
 class SimpleDaemon
   def start
+    Raad::Logger.debug("SimpleDaemon start")
     while !Raad.stopped?
-      Raad::Logger.info("simple_daemon running")
+      Raad::Logger.info("SimpleDaemon running")
       sleep(1)
     end
   end
 
   def stop
-    Raad::Logger.info("simple_daemon stopped")
+    Raad::Logger.debug("SimpleDaemon stop")
   end
 end
 ```
@@ -87,7 +85,7 @@ There are two ways to know when your service has been instructed to stop:
 
 There are basically 3 ways to run execute your service:
 
- * start it in foreground console mode, useful for debugging, `^C` to execute the stop sequence
+ * start it in foreground console mode, useful for debugging, `^C` to trigger the stop sequence
 
 ``` sh
 $ ruby your_service.rb start
@@ -134,14 +132,103 @@ Raad has been tested on MRI 1.8.7, MRI 1.9.2, REE 1.8.7, JRuby 1.6.4 under OSX 1
         -h, --help                       display help message
 
 Note that the command line options will always override any config file settings if present.
-### Configuration and options
-tbd.
 
-### Adding custom command line options
+#### -e, --environment NAME
+Raad provides a way to pass an **arbritary** environment name on the command line. This environment name can later be retrieved in your code using the following methods:
+
+ * `Raad.env` will return the **symbolized** environment name passed on the command line.
+ * `Raad.test?` will return `true` if the enviroment name passed on the command line was `test`.
+ * `Raad.development?` will return `true` if the enviroment name passed on the command line was `development` or `dev`.
+ * `Raad.stage?` will return `true` if the enviroment name passed on the command line was `stage` or `staging`.
+ * `Raad.production?` will return `true` if the enviroment name passed on the command line was `production` or `prod`.
+
+Example:
+
+``` sh
+$ ruby your_service.rb -e foobar start
+```
+
+``` ruby
+if Raad.env == :foobar
+  # do foobar stuff
+end
+
+if Raad.production?
+  # never get here
+end
+```
+
+### Custom command line options
+It is possible to add **custom** command line options to your service, in addition to Raad own command line options. To handle custom command line options simply define a `self.options_parser` **class method** in your service class. This method will be passed a [OptionParser](http://apidock.com/ruby/OptionParser) object into which you can add your rules plus also a Hash to set the parsed options values. The OptionParser object must be returned.
+
+Check complete example file [examples/custom_options.rb](https://github.com/praized/raad/blob/master/examples/custom_options.rb)
+
+Example:
+
+``` ruby
+# options_parser must be a class method 
+#
+# @param raad_parser [OptionParser] raad options parser to which custom options rules can be added
+# @param parsed_options [Hash] set parsing results into this hash. retrieve it later in your code using Raad.custom_options
+# @return [OptionParser] the modified options parser must be returned
+def  self.options_parser(raad_parser, parsed_options)
+  raad_parser.separator "Your service options:"
+
+  raad_parser.on('-a', '--aoption PARAM', "some a option parameter") { |val| parsed_options[:aoption] = val }
+  raad_parser.on('-b', '--boption PARAM', "some b option parameter") { |val| parsed_options[:boption] = val }
+
+  raad_parser
+end
+```
+
+The parsed options values can later be retrieved in your code using `Raad.custom_options` which will hold the Hash as set in your `options_parser` class method.
+
+``` ruby
+do_this if Raad.custom_options[:aoption] == 'a option parameter value'
+```
+
+``` sh
+$ ruby your_service.rb -h
+
+usage: ruby <service>.rb [options] start|stop
+
+Raad common options:
+    -e, --environment NAME           set the execution environment (default: development)
+    -l, --log FILE                   log to file (default: in console mode: no, daemonized: <service>.log)
+    -s, --stdout                     log to stdout (default: in console mode: true, daemonized: false)
+    -v, --verbose                    enable verbose logging (default: false)
+        --pattern PATTERN            log4r log formatter pattern
+    -c, --config FILE                config file (default: ./config/<service>.rb)
+    -d, --daemonize                  run daemonized in the background (default: false)
+    -P, --pid FILE                   pid file when daemonized (default: <service>.pid)
+    -r, --redirect FILE              redirect stdout to FILE when daemonized (default: no)
+    -n, --name NAME                  daemon process name (default: <service>)
+        --timeout SECONDS            seconds to wait before force stopping the service (default: 60)
+    -h, --help                       display help message
+
+Your service options:
+    -a, --aoption PARAM              some a option parameter
+    -b, --boption PARAM              some b option parameter
+```
+
+### Configuration and options
 tbd.
 
 ### Logging
-tbd.
+Raad uses Log4r for logging and provides hooks for logging in your service. Here's an example of how to use Raad logging:
+
+``` ruby
+  Raad::Logger.debug("this is a message with level DEBUG")
+  Raad::Logger.info("this is a message with level INFO")
+  Raad::Logger.warn("this is a message with level WARN")
+  Raad::Logger.error("this is a message with level ERROR")
+  Raad::Logger.fatal("this is a message with level FATAL")
+```
+
+ * By default, Raad will output log messages of level `INFO` **and higher**.
+ * If the `-v, --verbose` command line option is used, Raad will output **all** log messages (level `DEBUG` **and higher**).
+
+Alternatively, the log output level can be set in your service using the `Raad::Logger.level=` method. The valid levels parameter are `:debug`, `:info`, `:warn` and `:error`.
 
 ### Stop sequence details
 tbd.

data/lib/raad/bootstrap.rb

@@ -40,11 +40,8 @@ module Raad
     #
     # @return [Nil]
     def self.run!
-      file = File.basename(service_file, '.rb')
-      service = Object.module_eval(camel_case(file)).new
-
-      runner = Runner.new(ARGV, service)
-      runner.run
+      service_class = Object.module_eval(camel_case(File.basename(service_file, '.rb')))
+      Runner.new(ARGV, service_class).run
     end
 
     private

data/lib/raad/env.rb

@@ -4,6 +4,7 @@ require 'thread'
 module Raad
   
   @env = :development
+  @custom_options = {}
   @stopped = false
   @stop_lock = Mutex.new
 
@@ -83,6 +84,13 @@ module Raad
     @stop_lock.synchronize{@stopped = !!state}
   end
 
-  module_function :env, :env=, :production?, :development?, :stage?, :test?, :jruby?, :ruby_path, :stopped?, :stopped=
+  # returns the custom options hash set in the service options_parser class method
+  #
+  # @return [Hash] custom options hash
+  def custom_options
+    @custom_options
+  end
+
+  module_function :env, :env=, :production?, :development?, :stage?, :test?, :jruby?, :ruby_path, :stopped?, :stopped=, :custom_options
 
 end

data/lib/raad/logger.rb

@@ -38,7 +38,6 @@ module Raad
     #
     # @param log [Logger] The logger to add file logging too
     # @param log_format [Log4r::Formatter] The log format to use
-    # @return [Nil]
     def setup_file_logger(log, log_format, file)
       FileUtils.mkdir_p(File.dirname(file))
 
@@ -53,7 +52,6 @@ module Raad
     #
     # @param log [Logger] The logger to add stdout logging too
     # @param log_format [Log4r::Formatter] The log format to use
-    # @return [Nil]
     def setup_stdout_logger(log, log_format)
       @log.add(Log4r::StdoutOutputter.new('console', :formatter => log_format))
     end

data/lib/raad/runner.rb

@@ -9,56 +9,62 @@ module Raad
     SECOND = 1
     STOP_TIMEOUT = 60 * SECOND
 
-    attr_accessor :service, :pid_file, :options
+    attr_accessor :pid_file
 
     # Create a new Runner
     #
     # @param argv [Array] command line arguments
-    # @param service [Object] service to execute
-    def initialize(argv, service)
+    # @param service_class [Class] service class
+    def initialize(argv, service_class)
       @argv = argv.dup # lets keep a copy for jruby double-launch
-      create_options_parser(service).parse!(argv)
+      @service_class = service_class
+      @parsed_options = nil
 
-      # start/stop 
-      @options[:command] = argv[0].to_s.downcase
-      unless ['start', 'stop', 'post_fork'].include?(options[:command])
+      @stop_lock = Mutex.new
+      @stop_signaled = false
+
+      # parse command line options and set @parsed_options
+      options_parser = service_class.respond_to?(:options_parser) ? service_class.options_parser(create_options_parser, Raad.custom_options) : create_options_parser
+      begin
+        options_parser.parse!(argv)
+      rescue OptionParser::InvalidOption => e
+        puts(">> #{e.message}")
+        exit!(false)
+      end
+
+      # grab what's left after options, which should be the start/stop command
+      @parsed_options[:command] = argv[0].to_s.downcase
+      unless ['start', 'stop', 'post_fork'].include?(@parsed_options[:command])
         puts(">> start|stop command is required")
         exit!(false)
       end
 
-      @service = service
-      @service_name = nil
-      @logger_options = nil
-      @pid_file = nil
+      # load config if present
+      Configuration.load(@parsed_options[:config] || File.expand_path("./config/#{default_service_name(service_class)}.rb"))
 
-      @stop_lock = Mutex.new
-      @stop_signaled = false
-    end
+      # default service name 
+      @service_name = @parsed_options[:name] || Configuration.daemon_name || default_service_name(service_class)
 
-    def run
-      # first load config if present
-      Configuration.load(options[:config] || File.expand_path("./config/#{default_service_name}.rb"))
+      # @pid_file is required to become Daemonizable
+      @pid_file = @parsed_options.delete(:pid_file) || "./#{@service_name}.pid"
 
-      # settings which depends on configuration
-      @service_name = options[:name] || Configuration.daemon_name || default_service_name
+      # default stop timeout
+      @stop_timeout = (@parsed_options.delete(:stop_timeout) || Configuration.stop_timeout || STOP_TIMEOUT).to_i
 
-      unless options[:log_file]
-        options[:log_file] = (options[:daemonize] ? File.expand_path("#{@service_name}.log") : nil)
-      end
-      unless options[:log_stdout]
-        options[:log_stdout] = !options[:daemonize]
-      end
+      # logger options
+      @parsed_options[:log_file] = (@parsed_options[:daemonize] ? File.expand_path("#{@service_name}.log") : nil) unless @parsed_options[:log_file]
+      @parsed_options[:log_stdout] = !@parsed_options[:daemonize] unless @parsed_options[:log_stdout]
       @logger_options = {
-        :file => options.delete(:log_file) || Configuration.log_file,
-        :stdout => options.delete(:log_stdout) || Configuration.log_stdout,
-        :verbose => options.delete(:verbose) || Configuration.verbose,
-        :pattern => options.delete(:log_pattern) || Configuration.log_pattern,
+        :file => @parsed_options.delete(:log_file) || Configuration.log_file,
+        :stdout => @parsed_options.delete(:log_stdout) || Configuration.log_stdout,
+        :verbose => @parsed_options.delete(:verbose) || Configuration.verbose,
+        :pattern => @parsed_options.delete(:log_pattern) || Configuration.log_pattern,
       }
-      @pid_file = options.delete(:pid_file) || "./#{@service_name}.pid"
-      @stop_timeout = (options.delete(:stop_timeout) || Configuration.stop_timeout || STOP_TIMEOUT).to_i
+    end
 
+    def run
       # check for stop command, @pid_file must be set
-      if options[:command] == 'stop'
+      if @parsed_options[:command] == 'stop'
         puts(">> Raad service wrapper v#{VERSION} stopping")
         # first send the TERM signal which will invoke the daemon wait_or_will method which will timeout after @stop_timeout
         # if still not stopped afer @stop_timeout + 2 seconds, KILL -9 will be sent.
@@ -66,28 +72,31 @@ module Raad
         exit(success)
       end
 
-      # setup logging
-      Logger.setup(@logger_options)
-      Logger.level = Configuration.log_level if Configuration.log_level
-
       Dir.chdir(File.expand_path(File.dirname("./"))) unless Raad.test?
 
-      if options[:command] == 'post_fork'
+      if @parsed_options[:command] == 'post_fork'
         # we've been spawned and re executed, finish setup
-        post_fork_setup(@service_name, options[:redirect])
-        run_service
+        post_fork_setup(@service_name, @parsed_options[:redirect])
+        start_service
       else
         puts(">> Raad service wrapper v#{VERSION} starting")
-        options[:daemonize] ? daemonize(@argv, @service_name, options[:redirect]) {run_service} : run_service
+        @parsed_options[:daemonize] ? daemonize(@argv, @service_name, @parsed_options[:redirect]) {start_service} : start_service
       end
     end
 
     private
 
-    # Run the service
-    #
-    # @return nil
-    def run_service
+    def start_service
+      # setup logging
+      Logger.setup(@logger_options)
+      Logger.level = Configuration.log_level if Configuration.log_level
+
+      Logger.debug("initializing #{@service_name} service")
+
+      # create service instance
+      service = @service_class.new
+
+      # important to display this after service instantiation which can set Raad.env
       Logger.info("starting #{@service_name} service in #{Raad.env.to_s} mode")
 
       at_exit do
@@ -95,24 +104,24 @@ module Raad
       end
 
       # do not trap :QUIT because its not supported in jruby
-      [:INT, :TERM].each{|sig| SignalTrampoline.trap(sig) {stop_service}}
+      [:INT, :TERM].each{|sig| SignalTrampoline.trap(sig) {stop_service(service)}}
 
       # launch the service thread and call start. we expect start not to return
       # unless it is done or has been stopped.
       service_thread = Thread.new do
         Thread.current.abort_on_exception = true
         service.start
-        stop_service 
+        stop_service(service)
       end
 
       result = wait_or_kill(service_thread)
       # if not daemonized start a sentinel thread, if still alive after 2 seconds, do arakiri
-      Thread.new{sleep(2 * SECOND);  Process.kill(:KILL, Process.pid)} unless options[:daemonize]
+      Thread.new{sleep(2 * SECOND);  Process.kill(:KILL, Process.pid)} unless @parsed_options[:daemonize]
       # use exit and not exit! to make sure the at_exit hooks are called, like the pid cleanup, etc.
       exit(result)
     end
 
-    def stop_service
+    def stop_service(service)
       return if @stop_lock.synchronize{s = @stop_signaled; @stop_signaled = true; s}
       
       Logger.info("stopping #{@service_name} service")
@@ -150,15 +159,15 @@ module Raad
     # convert the service class name from CameCase to underscore
     #
     # @return [String] underscored service class name
-    def default_service_name
-      service.class.to_s.split('::').last.gsub(/(.)([A-Z])/,'\1_\2').downcase!
+    def default_service_name(clazz)
+      clazz.to_s.split('::').last.gsub(/(.)([A-Z])/,'\1_\2').downcase!
     end
 
     # Create the options parser
     #
     # @return [OptionParser] Creates the options parser for the runner with the default options
-    def create_options_parser(service)
-      @options ||= {
+    def create_options_parser
+      @parsed_options ||= {
         :daemonize => false,
         :verbose => false,
       }
@@ -171,21 +180,22 @@ module Raad
     
         opts.on('-e', '--environment NAME', "set the execution environment (default: #{Raad.env.to_s})") { |val| Raad.env = val }
 
-        opts.on('-l', '--log FILE', "log to file (default: in console mode: no, daemonized: <service>.log)") { |file| @options[:log_file] = file }
-        opts.on('-s', '--stdout', "log to stdout (default: in console mode: true, daemonized: false)") { |v| @options[:log_stdout] = v }
-        opts.on('-v', '--verbose', "enable verbose logging (default: #{@options[:verbose]})") { |v| @options[:verbose] = v }
-        opts.on('--pattern PATTERN', "log4r log formatter pattern") { |v| @options[:log_pattern] = v }
+        opts.on('-l', '--log FILE', "log to file (default: in console mode: no, daemonized: <service>.log)") { |file| @parsed_options[:log_file] = file }
+        opts.on('-s', '--stdout', "log to stdout (default: in console mode: true, daemonized: false)") { |v| @parsed_options[:log_stdout] = v }
+        opts.on('-v', '--verbose', "enable verbose logging (default: #{@parsed_options[:verbose]})") { |v| @parsed_options[:verbose] = v }
+        opts.on('--pattern PATTERN', "log4r log formatter pattern") { |v| @parsed_options[:log_pattern] = v }
 
-        opts.on('-c', '--config FILE', "config file (default: ./config/<service>.rb)") { |v| @options[:config] = v }
-        opts.on('-d', '--daemonize', "run daemonized in the background (default: #{@options[:daemonize]})") { |v| @options[:daemonize] = v }
-        opts.on('-P', '--pid FILE', "pid file when daemonized (default: <service>.pid)") { |file| @options[:pid_file] = file }
-        opts.on('-r', '--redirect FILE', "redirect stdout to FILE when daemonized (default: no)") { |v| @options[:redirect] = v }
-        opts.on('-n', '--name NAME', "daemon process name (default: <service>)") { |v| @options[:name] = v }
-        opts.on('--timeout SECONDS', "seconds to wait before force stopping the service (default: 60)") { |v| @options[:stop_timeout] = v }
+        opts.on('-c', '--config FILE', "config file (default: ./config/<service>.rb)") { |v| @parsed_options[:config] = v }
+        opts.on('-d', '--daemonize', "run daemonized in the background (default: #{@parsed_options[:daemonize]})") { |v| @parsed_options[:daemonize] = v }
+        opts.on('-P', '--pid FILE', "pid file when daemonized (default: <service>.pid)") { |file| @parsed_options[:pid_file] = file }
+        opts.on('-r', '--redirect FILE', "redirect stdout to FILE when daemonized (default: no)") { |v| @parsed_options[:redirect] = v }
+        opts.on('-n', '--name NAME', "daemon process name (default: <service>)") { |v| @parsed_options[:name] = v }
+        opts.on('--timeout SECONDS', "seconds to wait before force stopping the service (default: 60)") { |v| @parsed_options[:stop_timeout] = v }
 
-        opts.on('-h', '--help', 'display help message') { show_options(opts) }
+        opts.on('-h', '--help', 'display help message') { show_options(options_parser) }
       end
-      service.respond_to?(:options_parser) ? service.options_parser(options_parser) : options_parser
+
+      options_parser
     end
 
     # Output the servers options and exit Ruby

data/lib/raad/version.rb

@@ -1,3 +1,3 @@
 module Raad
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end unless defined?(Raad::VERSION)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raad
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-23 00:00:00.000000000Z
+date: 2011-10-12 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyforge
-  requirement: &2165092620 !ruby/object:Gem::Requirement
+  requirement: &2165354500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2165092620
+  version_requirements: *2165354500
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2165092060 !ruby/object:Gem::Requirement
+  requirement: &2165353940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *2165092060
+  version_requirements: *2165353940
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2165091540 !ruby/object:Gem::Requirement
+  requirement: &2165353420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 0.9.2
   type: :development
   prerelease: false
-  version_requirements: *2165091540
+  version_requirements: *2165353420
 - !ruby/object:Gem::Dependency
   name: log4r
-  requirement: &2165091060 !ruby/object:Gem::Requirement
+  requirement: &2165352940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,7 +54,7 @@ dependencies:
         version: 1.1.9
   type: :runtime
   prerelease: false
-  version_requirements: *2165091060
+  version_requirements: *2165352940
 description: Ruby as a Daemon lightweight service wrapper
 email:
 - colin.surprenant@gmail.com