kinetic 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f720debb00d4ab62ce3b3e8d7e4f7eaf422be407
-  data.tar.gz: a01b254919820ca788f0aa9ee8d42c06a7a7ca06
+  metadata.gz: 0fdcf06cf8d1fc5fff905da13c55c97c5c30f6bc
+  data.tar.gz: ff4a1483557bb7abd8863a87000795b3648ad0db
 SHA512:
-  metadata.gz: 6243b0b4ae9062a16aeda4bf06626088fd0cfaf80ed2de1b4a385f827ff491c063a69e168ef90cd46d35ba8f6b0ca0a1909a261c99670dd38634b730ede822d2
-  data.tar.gz: be6f7059f4fb70d65e6d1cab62357d9f082f783a249e3e7e40694d93de2a7cf71b182795d26d184d26588ab524d93d2aab6b0c4535723013a095cfcf4fbae731
+  metadata.gz: 84695516ec05676070029529c68f77aaafd9a72204f329121cbf39eca176a6fe8546074b8b3072d867ce4820ed8bb6817360355e57eba23090e3a790c6906ea5
+  data.tar.gz: 40ad8453c43d7e53a00f0552dfb703329a946e41085211694cf1432a8f94b349d8545734ede32f73b1b9757af7b023169c3054c773b480617b965b89d57a81f7

data/.gitignore

@@ -19,3 +19,4 @@ tmp
 *.iml
 doc/**
 *.pid
+*.log

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p353

data/README.md

@@ -1,8 +1,7 @@
 # Kinetic
 
 [<img src="https://secure.travis-ci.org/fugufish/kinetic.png">](http://travis-ci.org/fugufish/kinetic)
-[![Code Climate](https://codeclimate.com/repos/52b06fa413d637197401ebb7/badges/c71d7f47797b4caec5ae/gpa.png)](https://codeclimate.com/repos/52b06fa413d637197401ebb7/feed)
-
+[<img src="https://codeclimate.com/repos/52b06fa413d637197401ebb7/badges/c71d7f47797b4caec5ae/gpa.png">](https://codeclimate.com/repos/52b06fa413d637197401ebb7/feed)
 
 Kinetic is an AMQP worker framework designed in vein of microframeworks such as sinatra. Its goal is to provide an
  easy way to configure and run AMQP consumers in order to reduce developer overhead when working with AMQP. Kinetic
@@ -32,34 +31,72 @@ the routing key 'message'. By default the message is expected to be in JSON form
 serializers may be available.
 
 ## Configuration
-Kinetic configuration follows a similar DSL to that of sinatra. Configuration can be set by calling the `set` method,
-and can be retrieved by referencing the `config` variable or the `get` or `get!` methods.
+Kinetic configuration follows a similar DSL to that of sinatra in that it allows the use of the {Kinetic::DSL#set set}
+method to set configuration. It also allows a configuration file to be loaded by using
+{Kinetic::DSL#config_file config_file}.
+
+### Using {Kinetic::DSL#set set}
 
-### set
-To set a configuration value use set:
+Simply pass in the key and value to the {Kinetic::DSL#set set} method.
 
 ```ruby
-set :host, 'localhost'
+require 'kinetic'
 
-on 'message' do |message|
-    puts "Received #{message}"
-end
+set host: 'localhost'
+set port: 5672
+```
+
+### Using {Kinetic::DSL#config_file config_file}
+
+You can add support to your Kinetic app for file based configuration by defining a Yaml based config file. Note that
+the {Kinetic::DSL#config_file config_file} directive accepts any path. Relative paths will be relative to the
+application file's root directory.
+
+```ruby
+require 'kinetic'
+
+config_file 'config/config.yml'
 ```
 
 ### Defaults
-[Kinetic::Configuration](http://rdoc.info/github/fugufish/kinetic/master/Kinetic/Configuration)
 
+```ruby
+{
+  name:       File.basename($0),         # name of the application. This also translates to the name of the AMQP exchange
+  root:       File.dirname($0),          # the application root directory
+  app_file:   $0,                        # the application file
+  workers:    1,                         # the number of worker processes to run
+  log_file:   'kinetic.log',             # the path of the log file to be used
+  host:       'localhost',               # the AMQP host
+  port:       5672,                      # the AMQP port
+  serializer: :JSON,                     # the message serializer to use
+  timeout:    1,                         # the time (in seconds) to wait for various operations
+  pid:        "#{File.basename($0)}.pid" # the process pid file
+}
+```
+
+### Accessing
 
+Accessing configuration values by their method accessors will raise {Kinetic::Errors::MissingConfigurationValue}
+error. This can be used to ensure that specific values are set at runtime. To access a value without raising an
+exception use the hash key instead.
+
+```ruby
+config.host   # raises an error if the config host value is not set
+config[:host] # returns nil if the host value is not set
+```
 
 ## Changelog
 
+### 0.0.4
+* removed `get` and `get!` methods as they are no longer needed.
+* added ability to correctly daemonize process
+
 ### 0.0.3
 * Fix bug where process shut down does not kill children
 * Add ability to set process name for master and workers
 * Add after fork block capability allowing code to be written to run after the worker forks
 
-### 0.0.1
-* Initial release
 
 
 

data/lib/kinetic/cli.rb

@@ -1,4 +1,4 @@
-require 'kinetic/base'
+require 'optparse'
 module Kinetic
   module CLI
 
@@ -8,24 +8,20 @@ module Kinetic
       opts.banner = "Usage #{File.basename($0)} (#{COMMANDS.join('|')}) [options]"
     end
 
-    def self.parse
-      command = nil
-      if ARGV.empty? || (ARGV[0] && COMMANDS.include?(ARGV[0]))
-        command = ARGV.shift
-      else
-        puts PARSER.banner
-        exit! 1
-      end
-      command || 'run'
-    end
-
   end
 
-  class Application < Base
-  end
+  if ARGV.empty? || (ARGV[0] && CLI::COMMANDS.include?(ARGV[0]))
+    require 'kinetic/version'
+    require 'kinetic/base'
 
+    class Application < Base
+    end
 
-  at_exit { Master.new(Application.new).send(CLI.parse) if $!.nil? }
+    at_exit { Master.new(Application.new).send(ARGV[0] || 'run') if $!.nil? }
+  else
+    puts CLI::PARSER.banner
+    exit(1)
+  end
 
 end
 

data/lib/kinetic/configuration.rb

@@ -1,16 +1,35 @@
 module Kinetic
+
+  # Configuration can be set either by passing the {Kinetic::DSL#set set} method and or by using the
+  # {Kinetic::DSL#config_file config_file} method.
+  #
+  # @example
+  #  require 'kinetic'
+  #
+  #  config_file 'config.yml' # loads the values in config_file into configuration
+  #  set :host,  'localhost'  # sets config.host to 'localhost'
+  #
+  # Accessing configuration values by their method accessors will raise {Kinetic::Errors::MissingConfigurationValue}
+  # error. This can be used to ensure that specific values are set at runtime. To access a value without raising an
+  # exception use the hash key instead.
+  #
+  # @example
+  #  config.host   # raises an error if the config host value is not set
+  #  config[:host] # returns nil if the host value is not set
   class Configuration < Confstruct::Configuration
 
+    # Default configuration values.
     DEFAULTS = {
-      name:     File.basename($0),
-      root:     File.dirname($0),
-      app_file: $0,
-      workers:  1,
-      log_file: STDOUT,
-      host: 'localhost',
-      port: 5672,
-      serializer: :JSON,
-      timeout: 1
+      name:       File.basename($0),         # name of the application. This also translates to the name of the AMQP exchange
+      root:       File.dirname($0),          # the application root directory
+      app_file:   $0,                        # the application file
+      workers:    1,                         # the number of worker processes to run
+      log_file:   'kinetic.log',             # the path of the log file to be used
+      host:       'localhost',               # the AMQP host
+      port:       5672,                      # the AMQP port
+      serializer: :JSON,                     # the message serializer to use
+      timeout:    1,                         # the time (in seconds) to wait for various operations
+      pid:        "#{File.basename($0)}.pid" # the process pid file
     }
 
     def initialize
@@ -18,5 +37,14 @@ module Kinetic
       self.deep_merge!(DEFAULTS)
     end
 
+
+    private
+
+    def method_missing(meth, *args, &block)
+      value = super
+      raise Kinetic::Errors::MissingConfigurationValue.new("Configuration is missing value for #{meth}") unless value
+      value
+    end
+
   end
 end

data/lib/kinetic/dsl.rb

@@ -1,52 +1,16 @@
+require_relative 'dsl/configuration'
 module Kinetic
 
   module DSL
 
+    include Configuration
+
     def after_fork(&block)
       raise Kinetic::Errors::BlockMissing unless block_given?
       after_fork_procs << block
     end
 
-    # Sets a configuration value
-    #
-    # @param [Symbol] key the configuration key to set
-    # @param [Symbol] value the configuration value
-    #
-    # @return [Boolean] returns true
-    def set(key, value)
-      logger.debug "Setting '#{key}' to '#{value}'"
-      config[key.to_sym] = value
-      true
-    end
 
-    # Set configuration file.
-    #
-    # @param [String] path to configuration file
-    def config_file(file)
-      set :config_file, File.expand_path(file)
-      config.configure(YAML.load(File.new(get!(:config_file), 'r')))
-    end
-
-    # Gets a configuration value
-    #
-    # @param [Symbol] key the key of the value to get
-    #
-    # @return [Object, nil] returns the requested configuration value or nil if the value does not exist
-    def get(key)
-      config[key.to_sym]
-    end
-
-    # Gets a configuration value and returns an exception if the value is not present
-    #
-    # @param [Symbol] key the key of the value to get
-    #
-    # @return [Object]
-    #
-    # @raise [Kinetic::Errors::MissingConfigurationValue] if the value does not exist
-    def get!(key)
-      raise Kinetic::Errors::MissingConfigurationValue.new(key) unless (value = get(key))
-      value
-    end
 
     # Defines a direct queue subscription. Direct queues do not allow fuzzy matching so all messages sent to this queue
     # must exactly match the key.
@@ -68,17 +32,13 @@ module Kinetic
 
     # @return [Logger] returns the application logger instance
     def logger
-      @logger ||= reopen_logger
-    end
-
-    def config
-      @config ||= Kinetic::Configuration.new
+      @logger ||= config[:logging] ? reopen_logger : Logger.new('/dev/null')
     end
 
     protected
 
     def reopen_logger
-      @logger = Logger.new(config.log_file)
+      @logger = Logger.new(config[:daemonize] ? config.log_file : STDOUT)
     end
 
 

data/lib/kinetic/dsl/configuration.rb

@@ -0,0 +1,36 @@
+require 'yaml'
+module Kinetic
+  module DSL
+    module Configuration
+
+      # Sets a configuration value
+      #
+      # @param [Symbol] key the configuration key to set
+      # @param [Symbol] value the configuration value
+      #
+      # @return [Boolean] returns true
+      def set(key, value)
+        logger.debug "Setting '#{key}' to '#{value}'"
+        config[key.to_sym] = value
+        true
+      end
+
+      # Set configuration file.
+      #
+      # @param [String] path to configuration file
+      #
+      # @return [Boolean] returns true
+      def config_file(file)
+        set :config_file, File.expand_path(file)
+        config.configure(YAML.load(File.new(config.config_file, 'r')))
+        true
+      end
+
+      def config
+        @config ||= Kinetic::Configuration.new
+      end
+
+
+    end
+  end
+end

data/lib/kinetic/errors.rb

@@ -7,6 +7,15 @@ module Kinetic
     class NoSubscriberBlock < BlockMissing; end
     class KeyMustBeString   < KineticError; end
 
+    # Raised when a configuration value is accessed via accessor when it is not set.
+    #
+    # @example
+    #  require 'kinetic'
+    #
+    #  set host: 'localhost'
+    #  set port: 5674
+    #
+    #  puts config.unset_configuration_value # raises MissingConfigurationValue
     class MissingConfigurationValue < KineticError
 
       def initialize(key)

data/lib/kinetic/master.rb

@@ -7,8 +7,7 @@ module Kinetic
     WORKERS    = {}
     SIG_QUEUE  = []
 
-    delegate :logger, :get, :get!, :set, :after_fork_procs, to: :app
-
+    delegate :logger, :config, :set, :after_fork_procs, to: :app
 
     attr_reader :app, :reexecpid
 
@@ -16,16 +15,25 @@ module Kinetic
       @app = app
     end
 
+    # Starts and daemonizes the master process
+    def start
+      if File.exists?(config.pid)
+        puts "Unable to start master process, a process with the pidfile #{config.pid} already exists." +
+          'If you wish to run another instance of this application please pass --pid to set a new pid file.'
+        exit(1)
+      end
+      config.daemonize = true
+      run
+    end
+
     # Starts and initializes the master process.
-    #
-    # @return [Kinetic::Master] the master process
     def run
       begin
-        logger.info "Starting Kinetic #{Kinetic::VERSION} with PID #{Process.pid}"
+        daemonize if config[:daemonize]
+        enable_logging!
         logger.debug 'Configuration:'
         logger.ap    app.class.send(:config).to_hash
         proc_name 'master'
-        write_pidfile!
         initialize_self_pipe!
         initialize_signal_traps!
         spawn_missing_workers
@@ -39,8 +47,29 @@ module Kinetic
       end
     end
 
+    def stop
+      unless File.exists?(File.join(config.root, config.pid))
+        puts "Unable to stop process, a process with the pidfile #{config.pid} could not be found" +
+               'If you have started this app with another pid file location pass --pid to set the pid file.'
+        exit(1)
+      end
+      pid = File.open(File.join(config.root, config.pid), 'r') { |f| f.read }.to_i
+      Process.kill(:QUIT, pid)
+    end
+
     private
 
+    def enable_logging!
+      config.logging = true
+      app.class.instance_variable_set(:@logger, nil)
+    end
+
+    def daemonize
+      logger.info 'Daemonizing process'
+      Process.daemon true, false
+      write_pidfile!
+    end
+
     def master_sleep(time)
       IO.select([ SELF_PIPE[0] ], nil, nil, time) or return
       SELF_PIPE[0].kgio_tryread(11)
@@ -50,9 +79,10 @@ module Kinetic
       logger.debug 'Joining thread'
       case SIG_QUEUE.shift
       when :QUIT
+        stop_all(true)
         break
       when :TERM, :INT
-        stop(false)
+        stop_all(false)
         break
       else
         master_sleep(0.5)
@@ -76,20 +106,20 @@ module Kinetic
     end
 
     def write_pidfile!
-      set(:pid, File.join(get!(:root), "#{get!(:name)}.pid"))
-      logger.info "Writing PID file to #{get!(:pid)}"
-      File.open(get!(:pid), 'w') { |f| f.write(Process.pid) }
+      set(:pid, File.join(config.root, "#{config.name}.pid"))
+      logger.info "Writing PID file to #{config.pid}"
+      File.open(config.pid, 'w') { |f| f.write(Process.pid) }
     end
 
     def call_on_exit_callbacks
     ensure
-      FileUtils.rm(get(:pid)) if get(:pid)
+      FileUtils.rm(config[:pid]) if config[:pid] && config[:daemonize]
     end
 
     def spawn_missing_workers
       logger.debug 'Spawning missing workers'
       worker_nr = -1
-      until (worker_nr += 1) == get!(:workers)
+      until (worker_nr += 1) == config.workers
         WORKERS.value?(worker_nr) and next
         #noinspection RubyArgCount
         worker = Worker.new(worker_nr, @app)
@@ -136,9 +166,9 @@ module Kinetic
     end
 
     # Terminates all workers, but does not exit master process
-    def stop(graceful = true)
+    def stop_all(graceful = true)
       logger.warn graceful ? 'Process is shutting down gracefully' : 'Process is shutting down immediately!'
-      limit = Time.now + get!(:timeout)
+      limit = Time.now + config.timeout
       until WORKERS.empty? || Time.now > limit
         if graceful
           soft_kill_each_worker(:QUIT)
@@ -163,6 +193,11 @@ module Kinetic
       worker = WORKERS.delete(wpid) and worker.close rescue nil
     end
 
+    def soft_kill_each_worker(signal)
+      WORKERS.each_value { |worker| worker.soft_kill(signal) }
+    end
+
+
     # reaps all unreaped workers
     def reap_all_workers
 
@@ -185,7 +220,7 @@ module Kinetic
     end
 
     def proc_name(tag)
-      $0 = "#{get!(:name)} [#{tag}]"
+      $0 = "#{config.name} [#{tag}]"
     end
 
   end

data/lib/kinetic/version.rb

@@ -1,3 +1,3 @@
 module Kinetic
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

data/lib/kinetic/worker.rb

@@ -1,7 +1,7 @@
 module Kinetic
   class Worker
 
-    delegate :logger, :get, :get!, :set, :deserialize, to: :app
+    delegate :logger, :config, :set, :deserialize, to: :app
 
     attr_reader :id, :app, :channel, :exchanges
 
@@ -23,8 +23,8 @@ module Kinetic
     end
 
     def run
-      logger.debug "Establishing connection host: '#{get!(:host)}', port: '#{get!(:port)}'"
-      AMQP.start(host: get!(:host), port: get!(:port)) do |connection|
+      logger.debug "Establishing connection host: '#{config.host}', port: '#{config.port}'"
+      AMQP.start(host: config.host, port: config.port) do |connection|
         logger.debug "AMQP started with conneciton #{connection}"
         initialize_channel!(connection)
         initialize_exchanges!
@@ -32,6 +32,22 @@ module Kinetic
       end
     end
 
+    # master sends fake signals to children
+    def soft_kill(sig) # :nodoc:
+      case sig
+      when Integer
+        signum = sig
+      else
+        signum = Signal.list[sig.to_s] or
+          raise ArgumentError, "BUG: bad signal: #{sig.inspect}"
+      end
+      # writing and reading 4 bytes on a pipe is atomic on all POSIX platforms
+      # Do not care in the odd case the buffer is full, here.
+      @master.kgio_trywrite([signum].pack('l'))
+    rescue Errno::EPIPE
+      # worker will be reaped soon
+    end
+
 
     private
 
@@ -43,7 +59,7 @@ module Kinetic
     def initialize_exchanges!
       logger.debug 'Initializing exchanges'
       @exchanges = {}
-      prefix = get!(:name)
+      prefix = config.name
       app.exchanges.each_key do |name|
         logger.debug "   Initializing #{name} exchange"
         @exchanges[name] = channel.send(name, "#{prefix}.#{name}")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kinetic
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Jarod Reid
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-16 00:00:00.000000000 Z
+date: 2014-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: confstruct
@@ -172,6 +172,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .ruby-version
 - .travis.yml
 - Gemfile
 - LICENSE.txt
@@ -184,6 +185,7 @@ files:
 - lib/kinetic/cli.rb
 - lib/kinetic/configuration.rb
 - lib/kinetic/dsl.rb
+- lib/kinetic/dsl/configuration.rb
 - lib/kinetic/errors.rb
 - lib/kinetic/master.rb
 - lib/kinetic/publisher.rb
@@ -221,4 +223,3 @@ test_files:
 - spec/base_spec.rb
 - spec/dsl_spec.rb
 - spec/spec_helper.rb
-has_rdoc: