agentdispatcher 0.7.0

data/README

@@ -0,0 +1,72 @@
+=AgentDispatcher (solid infrastructure fundamentals for script based agents)
+v0.7.0
+
+A non-intrusive application micro-framework that turns your plain ruby objects into configurable, reactive, and easily operable agents.  They will react on commands; combine behaviors using dynamic configurations;  multiply instances, play nice with with *nix infrastructure. In other words, object-oriented, shell-script-enabled approach towards agents modelling.
+
+There are two types of dispatchers (mixins) available:
+- SimpleDispatcher - reacts on commands, runs with pid, commandline invocation, concept of instance id. (obsolete)
+- AgentDispatcher - additionally to SimpleDispather it adds configurations, command-line configuration, constructor/destructors, logging
+
+The main mixin is AgentDispatcher. See datailed description and examples in docs of the each class.
+
+==Features
+- dispatching of commands with arguments. Handled by <tt>on_#{command}</tt> callback methods.
+- static definition of acceptable commands (<tt>@AllowedCommands</tt>)
+- PORO (Plain Old Ruby Objects) - the behavior can be applied (mixed-in) to any class not interfering
+  - own methods, own constructor
+- chain of inheritable custom constructor and destructor methods  (<tt>upMethod</tt>, <tt>downMethod</tt>)
+- hierarchical (layered) configuration (code-provided defaults < config files < manual parameters on invocation)
+- configurations by absolute path, or config file name
+- class defined configuration defaults (<tt>@DefaultCfg</tt>)
+- configuration overlays (something like multiple class inheritance) (<tt>@cfg</tt>)
+- sensible default behaviors (id, command, config do not have to be provided)
+- identity (agent instance id) (<tt>@id</tt>)
+- pid file management
+- customizable ROOT path (where resources are found, logs, pids written) (<tt>AGENTS_ROOT</tt>)
+- logging per instance (can be overriden) (<tt>@log</tt>)
+
+Options:
+  --config=A,B,C - cofiguration files
+  --log_path         - custom log path
+  --pid_path         - custom pid path
+  --nopid              - dont mess with pid files, neither write, nor consider pid file
+  --forcepid          - starts even if pid file exists
+  --quiet               - no output
+  
+  
+Instance variables:
+  @id, @log, @cfg
+  
+Run <tt>rake rdoc</tt> for documentation and examples.
+See examples
+
+==Instalation
+World-wide installation:
+ - Available as gem: <tt>gem install agentdispatcher</tt>
+ - Project homepage http://rubyagent.rubyforge.org/
+ - Project development page, downloads, forum, svn: http://rubyforge.org/projects/rubyagent/
+
+Local gem creation:
+    rake gem
+    rake test  #to run all testcases
+    sudo gem install pkg/agentdispatcher-x.y.z.gem  --local
+ 
+==Author
+Copyright (C) 2008  Viktor Zigo, http://alephzarro.com
+
+This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+You should have received a copy of the GNU General Public License along with this program (LICENSE file); if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Sponsored by: http://7inf.com
+
+==TODO: 
+HighPri:
+ - adjust to support agent caching (reuse)
+ 
+LowPri:
+ - help (for simple dispatcher)
+ - not existing runtime - try to create it
+ - validate input/cfg (just by exposing a method, subclassing DynParser)
+ - adjust simpleDispatcher to compatible behavior with agentDispatcher (constructor)
+----

data/lib/agentdispatcher.rb

@@ -0,0 +1,356 @@
+# = Complex command dispatcher mixin / Application micro-framework
+#
+# Simplifies creation of configurable objects which can react on messages/events while using OO approach. They can be easily executed from command line.
+# The micro-framework has lots of features. Therefore an example first:
+# ==Example Usage
+# agent.rb:
+#       class Agent
+#            include AgentDispatcher
+#            @AllowedCommands = %w(start stop)
+#            def on_run *args 
+#                # do some job
+#            end
+#            def on_stop *args 
+#                # do some job
+#            end
+#            ...
+#       end
+#
+#       class AgentB < Agent
+#            @DefaultCfg = {:log_path=>'/tmp'}
+#            @AllowedCommands = %w(start run stop)
+#            upMethod :initBussines
+#            def initBussines
+#                puts "post creation placeholder"
+#            end
+#            downMethod :closeBussines
+#            def closeBussines
+#                puts "pre-shutdown placeholder"
+#            end
+#            def on_run *args 
+#                # do some job
+#            end
+#            ...
+#       end
+#       if __FILE__ == $0
+#           AgentB::Dispatch *ARGV
+#       end
+#
+# There are several options how to dispatch events to the 'agent' (programatically)
+#        Agent::Dispatch *ARGV
+#        AgentB::Dispatch 'agent1', 'run', 'param1', 'param2'
+#        Agent::Dispatch 'start'
+#        Agent::DispatchString '--config cfgfile1,cfgfile2 agentID start'
+#        Agent.new(...).dispatch *ARGV
+#
+# The purpose of ARGV variants is of course to call the 'agent' right away from the command line, e.g.:
+#       agent.rb --config cfgfile1,cfgfile2 agentID start
+#       agent.rb --help
+#
+# = Feature Documentation
+# - dispatching commands (+id, arguments, configuration)
+# - defintion of accepted commands <tt>@AllowedCommands = %w(start stop)</tt>
+# - command handler method in format <tt>on_#{command in lowercase}<tt> (e.g. <tt>run</tt> -> <tt>on_run<tt>)
+# - dispatching from: command-line string, ARGV, Hash
+# - the agents object can used conventional inheritance to override/add new behavior.
+# - objects may have their own constructors (the class method Dispatch uses default constructor)
+# - injection of business constructors/desctructors 
+#   - <tt>upMethod <em>aMethodName</em></tt>
+#   - <tt>downMethod <em>aMethodName</em></tt>
+# - autogeneration of command-line help
+# - (TODO: in future support for any methods by injections)
+# Configuration 
+# - hierarchical configuration (the final configuration is constructed by overlaying several sources)
+# - default config can be defined in class variable <tt>@DefaultCfg = {:log_path=>'/tmp'}</tt>
+# - loaded from file; specified in option :config either by path (ends with  .yml) or by name (the file is loaded from <tt>#{AGENTS_ROOT}/config/#{name}.yml)</tt>
+# - multiple configuration files can be passed <tt>:config=>'cfg1,cfg2'</tt>, precedence in the given order
+# - the configuration can be given by arguments 
+# - precedence of configuration overlaying defaut < files < arguments
+# Logging
+# - <tt>@log</tt> instance variable is created, can be overriden in object constructor
+# - default path is <tt>#{AGENTS_ROOT}/tmp/log/#{@id}.log</tt>
+# - the path can be modified by setting <tt>:log_path</tt> option
+# Process Management
+# - a PID file is generated while the script is running
+# - generated in <tt>#{AGENTS_ROOT}/var/run/#{@id}.pid</tt>
+# - the path can be modified by setting <tt>:pid_path</tt> option
+# - passing <tt>:nopid</tt> option supresses genereation of pid file
+# - process does not start if a pid file already exists. Force execution by passing <tt>:forcepid</tt> option
+# Comandline format
+# Usage: #{@agentClass} [CONFIG] [ID] [COMMAND] [ARGS]
+#    CONFIG     Any application specific configuration flags in the format --NAME VALUE[,VALUE]*
+#               Special flags: {help, id, config=[A,B,...],log_path, nopid, pid_path, quiet, cmd}
+#    ID         Instance id of the agent (default: 'id-fied classname')
+#    COMMAND    Command to execute [aplication soec. commands] (default: 'run')
+#    ARGS       Space separated arguments (default:none)
+# - Passing <tt>:help</tt> option makes the script to generate help intructions to the STDOUT
+# 
+# ==Author
+# Viktor Zigo, http://alephzarro.com, All rights reserved. Distributed under GNU GPL License (see LICENSE).
+#
+# sponsored by http://7inf.com
+module AgentDispatcher
+    @VERSION='0.7.0'
+    PID_PATH = 'var/run'
+    LOG_PATH = 'tmp/log'
+    
+    $:.unshift File.join(File.dirname(__FILE__))
+    require 'logger'
+    require 'opts.rb'
+    require 'proctools.rb'
+    
+    AGENTS_ROOT =  (ENV['AGENTS_ROOT'] ||  '.' )
+##    @DefaultCfg = {}
+##    @AllowedCommands = []
+
+    def dispatchString aString
+        dispatch *aString.split
+    end
+
+    def dispatch *argv
+##        puts "AGENTS_ROOT: #{AGENTS_ROOT}, agentClass: #{self.class} allowedCmds: #{self.class.AllowedCommands}"
+        #make validation customizable
+        cfg = AgentUtils::ConfFactory.new(self.class).createFromArgv *argv
+        id = cfg[:id]
+        #TODO: forcepid
+    
+        #generate pid
+        cfg[:pid_path] = File.join( AGENTS_ROOT, PID_PATH, "#{id}.pid") unless cfg[:pid_path]
+        ProcTools::withPidFile(cfg[:pid_path], cfg) do
+            initializeAgent cfg
+            cmd = cfg[:cmd]
+            if self.class.AllowedCommands().include? cmd 
+                executeInjections :postInit
+                begin
+                    self.send "on_#{cmd.downcase}", *cfg[:args]
+                ensure
+                    executeInjections :preExit
+                end
+            else
+                raise "Unknown command '#{cmd}', allowed commands are {#{self.class.AllowedCommands.join(',')}}"
+            end    
+        end
+    end
+
+    def executeInjections aType
+        typedInjections = self.class.__injections__.select { |m, d| d[0]==aType}
+        typedInjections = typedInjections.map {|m,d| [m, d[1]] }
+        typedInjections.sort! {|a,b| -1*(a[1]<=>b[1])}
+        #@log.debug "excuting #{aType} injections: #{typedInjections.join(',')}"
+        @log.debug("executing #{aType} injections: #{typedInjections.join(',')}") if @log
+        typedInjections.each { |m,d|  self.send m}
+    end
+
+    def initializeAgent aConf
+        @cfg = aConf
+        @id = @cfg[:id]  unless @id #do not override if already exists
+        #config
+        fileCfg = AgentUtils::ConfFactory.new(self.class).loadConfigs @cfg[:config], self.class.DefaultCfg
+        @cfg = fileCfg.merge @cfg #cmdLine config overwrites fileCfg
+        #logging
+        unless @log  # don't do anything with logging as long as it's already defined
+            @cfg[:log_path] = File.join( AGENTS_ROOT, LOG_PATH, "#{@id}.log" ) unless @cfg[:log_path]
+            if ProcTools::existsPath?(@cfg[:log_path])
+                @log =  Logger.new(@cfg[:log_path], shift_age = 7, shift_size = 1048576)
+                puts "See logs in: #{@cfg[:log_path]}" unless @cfg[:quiet]
+            else
+                @log =  Logger.new(STDERR)
+                @log.error "log_path #{@cfg[:log_path]} does not exit. Logging to STDERR"
+            end
+        end
+        @log.debug @cfg.inspect
+    end
+    private :executeInjections, :initializeAgent
+end
+
+
+
+class << AgentDispatcher
+    module AgentDispatcherClassMethods
+        #inherit by merging
+        def __injections__
+            injs = @__injections__ || {}
+            injs = (superclass.__injections__.merge injs) if self.superclass.respond_to? :__injections__
+            injs
+        end
+    
+        #inherit by merging
+        def DefaultCfg
+            hash = @DefaultCfg || {}
+            hash = (superclass.DefaultCfg.merge hash) if self.superclass.respond_to? :DefaultCfg
+            hash
+        end
+    
+        #inherit by replacing
+        def AllowedCommands
+            @AllowedCommands ||  (superclass.AllowedCommands() if self.superclass.respond_to? :AllowedCommands) || []
+        end     
+    
+        def upMethod aMethod, aPriority = 0 
+            @__injections__ = {} unless @__injections__
+            @__injections__[aMethod.to_sym]=[:postInit, aPriority]
+        end
+        def downMethod aMethod, aPriority = 0 
+            @__injections__[aMethod.to_sym]=[:preExit, aPriority]
+        end
+    
+        def Dispatch *argv
+            instance = self.new
+            instance.dispatch *argv
+            instance
+        end
+    
+        def DispatchString aString
+            Dispatch *aString.split
+        end    
+    end
+
+private                                                                                                           
+    # add class methods
+    def included(klass)                                                                                               
+        super                                                                                                           
+        klass.extend AgentDispatcherClassMethods                                                                              
+    end
+
+    def append_features(mod)                                                                                          
+        #  help out people counting on transitive mixins                                                                
+        unless mod.instance_of?(Class)                                                                                  
+            raise TypeError, "Inclusion of the AgentDispatcher module in module #{mod}"                                      
+        end                                                                                                             
+        super                                                                                                           
+    end 
+
+    #extending an object with AgentDispatcher is a bad idea                                                               
+    undef_method :extend_object
+end
+
+module AgentUtils
+    
+    # A simple example agent
+    class AgentBase
+        include AgentDispatcher
+        @AllowedCommands = %w(run)
+
+        upMethod :initBussines
+        def initBussines
+        end
+
+        downMethod :closeBussines
+        def closeBussines
+        end
+
+        def onRun *args
+        end        
+    end
+
+    # Handles args parsing, configuration management
+    class ConfFactory
+        RESERVED_OPTS = [:id, :cmd, :args, :config]
+        AGENTS_ROOT =  (ENV['AGENTS_ROOT'] ||  '.' )
+        
+        def initialize anAgentClass = nil 
+            @agentClass = anAgentClass || AgentBase
+            @allowed_cmds =  @agentClass.AllowedCommands 
+        end
+
+        # genarates a help message
+        def dumpHelp
+            puts %Q{Usage: #{@agentClass} [CONFIG] [ID] [COMMAND] [ARGUMENTS]
+    CONFIG\tAny application specific configuration flags in the format --NAME VALUE[,VALUE]*
+          \tSpecial flags: {help, id, config=[A,B,...],log_path, nopid, forcepid, pid_path, quiet, cmd}
+    ID     \tInstance id of the agent (default: '#{class_to_id(@agentClass)}')
+    COMMAND\tCommand to execute [#{@allowed_cmds.join(',')}] (default: 'run')
+    ARGUMENTS\tSpace separated arguments (default:none)
+}
+        end
+    
+        # creates the config from a string (like what you type on command-line)
+        def createFromLine aString
+            createFromArgv *fromLine(aString)
+        end
+
+        # create confign from parsed arguments
+        # [CONFIG] [agentID command] [arguments]
+        # [CONFG]  [command] [arguments]  - > agentID=class name
+        # [CONFIG]   - > agentID=class name, command='run', no args
+        def createFromArgv *argv
+            createFromMethod *parseArgv( *argv)
+        end    
+
+        # create config by explicitely giving it the required componnents
+        def createFromMethod  anAgentID = nil, aCmd = nil, anArgs = [], aConf = {}
+            createFromOpts semantize(anAgentID, aCmd, anArgs, aConf)
+        end
+        
+        #create config from options (Hash)
+        def createFromOpts aConf
+            #puts "Class: #{@agentClass.name}, File: #{__FILE__}, execFile: #{$0}"
+            raise "agentID, command, and args need to be defined" unless [:id, :cmd,:args].all? {|c| aConf.include? c}
+            #puts "Execution --- conf:#{aConf.inspect}"
+            @conf = aConf
+        end
+
+        attr_reader :conf
+
+        def [] aSelector
+            @conf[aSelector.to_sym]
+        end
+
+        # Load a yaml config file and merge it with defaults
+        # The aPathOrName can be a path (if it ends with .yml) or just a configuration file name (to be looked up in 'runtime' path, see AGENTS_ROOT)
+        # return the merged hash - all keys are symbolized
+        def loadConfig aPathOrName, aDefaults={}
+            return aDefaults unless aPathOrName
+            require 'yaml'
+            aPathOrName = File.join(AGENTS_ROOT , "config", "#{aPathOrName}.yml") unless aPathOrName=~/\.yml$/
+            cfg = YAML.load_file aPathOrName
+            cfg = ProcTools.Intern cfg
+            return cfg ?  (aDefaults.merge cfg)  : aDefaults
+        end
+
+        # loads chain of configuration files
+        def loadConfigs aPathsOrNames, aDefaults={}
+            aPathsOrNames = [aPathsOrNames] unless aPathsOrNames.kind_of? Array
+            aPathsOrNames.each {|pathOrName|
+                aDefaults = loadConfig pathOrName, aDefaults
+            }
+            aDefaults
+        end
+
+    private
+        def fromLine aString
+            aString.split
+        end
+        
+        def parseArgv *argv
+            opts = DynamicCmdParse.new.parse! argv
+            dumpHelp if opts[:help]
+            id, cmd = nil, nil
+            if argv.length==0
+            elsif @allowed_cmds.include? argv.first
+                # without  instance id
+                cmd = argv.shift
+            else 
+                # with instance id
+                id = argv.shift
+                cmd = argv.shift if  argv.length > 0
+            end
+            [id, cmd, argv, opts]
+        end
+            
+        # verifies which options are set, how
+        def semantize anAgentID = nil, aCmd = nil, anArgs = [], aConf = {}
+            # real values or default values?
+            conf = aConf.clone
+            conf[:id] = (anAgentID ? anAgentID.to_s : class_to_id(@agentClass) )
+            conf[:cmd] = (aCmd ? aCmd.to_s : 'run')
+            conf[:args] = anArgs
+            conf
+        end
+
+        # used by pid files
+        def class_to_id aClass
+            aClass.name.gsub('::',"-").downcase
+        end
+    end
+end

data/lib/opts.rb

@@ -0,0 +1,86 @@
+
+class StaticCmdParser
+    require 'optparse'
+
+    # destructively parses the ARGV for statically declared config options by addOpts method and valided by validateOpts method
+    # return opts {symbol=>string}, the ARGV contains the remaining content
+    def parse! aDefaults ={}, allowedCommands = ["run"]
+        cmds = allowedCommands.join('|')
+        cmds = "<#{cmds}>" if allowedCommands.length>1
+        opts = aDefaults
+        parser = OptionParser.new do |p|
+            p.banner = "Usage: #{$0} [options] #{cmds}"
+            p.separator ""
+            p.separator "Options:"        
+            addOpts p, opts                
+        end
+##        opts = parser.parse!
+        parser.parse!
+        #opts[:cmd] = *ARGV[-1]
+        #raise OptionParser::MissingArgument, "lang" if opts[:lang].nil? and opts[:config_file].nil?
+        validateOpts opts, ARGV
+        opts
+    end
+
+    #for adding options in subclass
+    def addOpts aParser, opts
+        #p.on("-c", "--config YMLFILE", "Configuration file, can be overriden by cmdline opts") { |file| opts[:config] = file }
+        #p.on( "--forcepid", "XXX") { |v| opts[:pid]= v }
+        opts
+    end
+    #for validating parsed options
+    def validateOpts opts, argv
+        #raise OptionParser::MissingArgument, "lang" if opts[:lang].nil?
+    end
+end
+
+
+class DynamicCmdParse
+    
+    # destructively parses the ARGV for any dash-starting options without any or with one argument. The options can be validated by validateOpts method.
+    # return opts {symbol=>string}, the ARGV contains the remaining (and unparsed) content
+    def parse! argv = nil, aDefaults = {}
+        argv = ARGV unless argv
+        key = nil
+        rest = []
+        opts = aDefaults
+        while (argv.length>0 or key) do
+            tmp = argv.shift
+            new_key = tmp ? tmp.scan(/-+([\w\d\-\_]+)/).flatten.first : nil
+            if new_key
+                opts[key.intern] = true if key 
+                key=new_key
+            else
+                if key
+                    values = true
+                    #are there any values?
+                    if tmp
+                        #is it a list?
+                        values = tmp.split ','
+                        values = (values.length>1 ? values : values.first )
+                    end
+                    opts[key.intern] = values
+                    key = nil
+                else
+                    rest << tmp
+                end
+            end
+        end
+        argv.replace rest
+        validateOpts opts, argv
+        opts
+    end
+
+    #for adding options in subclass
+    def validateOpts opts, argv
+        #raise OptionParser::MissingArgument, "lang" if opts[:lang].nil?
+    end
+end
+
+
+if __FILE__ == $0
+    ##ARGV.replace ["--forcepid", "--config", "aaa", "-c", "Big test", "anID", "start"]
+    p "Inpput: #{ARGV}"
+    opts = DynamicCmdParse.new.parse!
+    p "Output: #{opts.inspect}, ARGV = #{ARGV.inspect}"
+end

data/lib/proctools.rb

@@ -0,0 +1,110 @@
+# =ProcTools - Utilities for process management
+#
+# == Usage
+#    ProcTools::withPidFile('test.pid') do
+#       exitcode = ProcTools::execSync 'echo 123 l sleep 5', 10
+#   end
+#
+# ==Author
+# Viktor Zigo, http://alephzarro.com, All rights reserved. Distributed under GNU GPL License (see LICENSE).
+#
+# sponsored by http://7inf.com
+# ==History
+# version: 0.2
+# * 0.2 - added Intern; p->puts
+#
+# ==TODO  tests
+# * process cannot be started
+# * process runs a finishes in time
+# * process timesout
+# *error codes returned
+
+
+module ProcTools
+    require 'timeout'
+
+    #TODO:  tests
+    #   process cannot be started
+    #   process runs a finishes in time
+    #   process timesout
+    #  error codes returned
+
+    # Executes an external command
+    def self.execSync aCmd, aTimeout = 0, doKill = true
+        puts "Spawning process #{aCmd}"
+        pid = fork {
+            exec aCmd
+        }
+        puts "Waiting on process pid=#{pid} timeout = #{aTimeout}..."
+        exitcode = nil
+        if aTimeout>0
+            begin
+                timeout(aTimeout){
+                    return_pid, exitcode = Process.wait2
+                    puts "Process #{pid} finished exitcode: #{exitcode}, cmd: #{aCmd}"
+                }
+            rescue Timeout::Error
+                puts "Process #{pid} timeuot"
+                if doKill
+                    puts "Killing-9 the process #{pid}  - #{aCmd}"
+                    Process.kill 9, pid
+                end
+            end
+        else
+            return_pid, exitcode  = Process.wait2
+            puts "Process #{pid} finished exitcode: #{exitcode}, cmd: #{aCmd}"
+            STDOUT.flush
+        end
+        exitcode
+    end
+
+    # Creates a pid file while running a block
+    # Pid file name is teken from ENV['PID_FILE'] or aFilename
+    def self.withPidFile aFilename = nil, opts={}, &code
+        # should we use pid file at all?
+        if opts[:nopid]
+            yield
+        else
+            pid_file = ENV['PID_FILE'] ||   aFilename
+            raise "Process may already run PID-file exists (#{pid_file}). Use :forcepid to run anyway" if File.exist?(pid_file) and not opts[:forcepid]
+            File.open(pid_file, 'w') {|f| f.puts $$}
+            begin            
+                yield
+            rescue StandardError=>e
+                #rethrow
+                raise e
+                #puts e, e.backtrace
+            ensure
+                File.delete(pid_file) if pid_file
+            end            
+        end
+    end
+
+    def self.existsPath? aPath
+        File.exist? File.dirname(aPath)
+    end
+
+    def self.Intern(aHash)
+        return {} unless aHash
+        
+        hash={}
+        aHash.each_pair do
+            |n,v| 
+            v=Intern(v) if v.kind_of? Hash
+            hash[n.to_sym]=v
+        end
+        hash
+    end
+end
+
+
+if __FILE__ == $0
+    ProcTools::withPidFile('proc.pid') do
+        puts 'starting'
+        exitcode = ProcTools::execSync './test1.sh'
+        puts "returned, exit code #{exitcode}"
+        puts "waiting to give the child chance to to st"
+        #sleep 10
+        puts 'done'
+    end
+end

data/lib/simpledispatcher.rb

@@ -0,0 +1,110 @@
+# =Command dispatcher mixin 
+#
+# Simplifies creation of objects which can react on messages/events while using OO approach. 
+# For more complex behavior see AgentDispatcher module.
+#
+# ==Usage
+#       class Agent
+#            include Dispatcher
+#            @AllowedCommands = %w(start stop run)
+#            def initialize anId = nil;  @id = anId ; end 
+#            def on_run *args 
+#                # do some job
+#            end
+#            def on_start *args 
+#                # do some job
+#            end
+#            ...
+#       end
+#
+# Several options how events to the 'agent' can be dispatched
+#        Agent::Dispatch *ARGV
+#        Agent::Dispatch 'agent1', 'run', 'param1', 'param2'
+#        Agent::Dispatch 'start'
+#        Agent.new('agent0').dispatch *ARGV
+#        Agent.DispatchOpts :cmd=>'start', :whatever=>'echo 42'
+# 
+# The ARGV variants of dispatching allows to call the 'agent' right away from command line, e.g.:
+#       ./agent.rb agent1 run
+#
+# Another types of agents can inherit from <tt>Agent</tt> and override/add only new behavior.
+#
+# ==Author
+# Viktor Zigo, http://7inf.com, All rights reserved. Distributed under GNU GPL License (see LICENSE).
+# Sponsored by: 7inf.com
+# ==History
+# version: 0.5
+module SimpleDispatcher
+    def dispatch *args
+        cmd = args.shift
+        # do not allow no commands - leads to user mistakes
+        # cmd = self.class.AllowedCommands().first unless cmd 
+        if self.class.AllowedCommands().include? cmd 
+            self.send "on_#{cmd.downcase}", args
+        else
+            raise "Unknown command '#{cmd}', allowed commands are {#{self.class.AllowedCommands.join(',')}}"
+        end
+    end
+
+    
+    def dispatchOpts opts
+        cmd = opts[:cmd]
+        if self.class.AllowedCommands().include? cmd 
+            self.send "on_#{cmd.downcase}", opts
+        else
+            raise "Unknown command '#{cmd}', allowed commands are {#{self.class.AllowedCommands.join(',')}}"
+        end
+    end
+    alias :dispatch2 :dispatchOpts
+end
+
+class << SimpleDispatcher
+    module SimpleDispatcherClassMethods
+        #override
+        #@AllowedCommands = []
+        #inherit by replacing
+        def AllowedCommands
+            @AllowedCommands ||  (superclass.AllowedCommands() if self.superclass.respond_to? :AllowedCommands) || []
+        end   
+    
+        def Dispatch *args
+            if self.AllowedCommands.include? args.first
+                # without  instance id (use lowcase classname)
+                inst = self.new self.name.gsub('::',"-").downcase
+            else 
+                # with instance id
+                inst = self.new args.shift
+            end
+            inst.dispatch *args
+            inst
+        end
+    
+        # opts   :id, :cmd
+        def DispatchOpts opts = {}
+            id = opts[:id]
+            id = self.name.gsub('::',"-").downcase unless id and id.length>0
+            inst = self.new id
+            inst.dispatchOpts opts
+            inst
+        end
+    
+    end
+
+private                                                                                                           
+    # add class methods
+    def included(klass)                                                                                               
+        super                                                                                                           
+        klass.extend SimpleDispatcherClassMethods                                                                              
+    end
+
+    def append_features(mod)                                                                                          
+        #  help out people counting on transitive mixins                                                                
+        unless mod.instance_of?(Class)                                                                                  
+            raise TypeError, "Inclusion of the Dispatcher module in module #{mod}"                                      
+        end                                                                                                             
+        super                                                                                                           
+    end 
+
+    #extending an object with Dispatcher is a bad idea                                                               
+    undef_method :extend_object
+end

data/test/runtime/config/config1.yml

@@ -0,0 +1,2 @@
+butcher: true
+shared: 123

data/test/runtime/config/config2.yml

@@ -0,0 +1,2 @@
+milkman: true
+shared: 456

data/test/test_agent_lowlevel.rb

@@ -0,0 +1,30 @@
+#Viktor Zigo, http://alephzarro.com, All rights reserved.
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'test/unit'
+
+ENV['AGENTS_ROOT']=File.join(File.dirname(__FILE__), 'runtime') unless ENV['AGENTS_ROOT']
+require 'agentdispatcher.rb'
+
+class AgentDispatcherLowTest< Test::Unit::TestCase
+    def test_confFactory1
+        cmdLine = "--config qwe.yml agent1 start 12:00"
+        cfg = AgentUtils::ConfFactory.new.createFromLine cmdLine
+        assert_equal( {:config=>'qwe.yml', :id=>'agent1', :cmd=>'start',:args=>['12:00']}, cfg )
+    end
+
+    def test_confFactory2
+        ARGV.replace ["--forcepid", "--config", "file.yml", "-c", "Big test", "agent1", "start"]
+        cfg = AgentUtils::ConfFactory.new.createFromArgv *ARGV
+        assert_equal( {:config=>'file.yml', :c=>'Big test', :id=>'agent1', :cmd=>'start',:args=>[], :forcepid=>true}, cfg )
+    end
+
+    def test_confFactoryEmptyLine
+        cfg = AgentUtils::ConfFactory.new.createFromLine ""
+        assert_equal( { :id=>'agentutils-agentbase', :cmd=>'run',:args=>[]}, cfg )
+    end
+
+    def test_confFactoryOnlyCommand
+        cfg = AgentUtils::ConfFactory.new.createFromLine "run arg1 arg2"
+        assert_equal( { :id=>'agentutils-agentbase', :cmd=>'run',:args=>['arg1', 'arg2']}, cfg )
+    end
+end

data/test/test_agentdispatcher.rb

@@ -0,0 +1,165 @@
+#Viktor Zigo, http://alephzarro.com, All rights reserved.
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'test/unit'
+
+ENV['AGENTS_ROOT']=File.join(File.dirname(__FILE__), 'runtime') unless ENV['AGENTS_ROOT']
+require 'agentdispatcher.rb'
+
+#* *************** Test agents **************
+
+class Agent
+    
+    include AgentDispatcher
+    @DefaultCfg = {:shared=>0}
+    @AllowedCommands = %w(run)
+
+    attr_reader :cfg, :id
+
+    def initialize
+        @trace = ["myinit"]
+    end
+
+    def trace
+        @trace.join(',')
+    end
+
+    upMethod :initBussines
+    def initBussines
+        @trace<<'initbussines'
+    end
+
+    downMethod :closeBussines
+    def closeBussines
+        @trace<<'closebussines'
+    end
+
+    def on_run *args
+        @trace<<"#{@id}.run(#{args})"
+    end
+end
+
+
+class AgentChild < Agent
+    @AllowedCommands = %w(start stop run)
+    
+    upMethod :specialInit
+    def specialInit
+        @trace<<"specialInit"
+    end
+
+    def on_start *args
+        @trace<<"#{@id}.start(#{args})"
+    end
+
+    def on_stop *args
+        @trace<<"#{@id}.stop(#{args})"
+    end
+
+    def on_run *args
+        @trace<<"#{@id}.run2(#{args})"
+    end
+end
+
+class AgentChildB < Agent
+    def initialize myOwnConstructor
+        super()
+        @trace<<"ownConstructor:#{myOwnConstructor}"
+    end
+end
+
+class AgentChildForced < Agent
+    def initialize
+        super()
+        @id = "myOwn"
+        @log = Logger.new(STDOUT)
+    end
+end
+
+#* ***************  Test-cases *********************
+
+class AgentDispatcherTest< Test::Unit::TestCase
+    def test_basic
+        d = Agent::DispatchString "agent0 run arg1 arg2"
+        assert_equal 'myinit,initbussines,agent0.run(arg1arg2),closebussines', d.trace
+    
+        d = Agent::Dispatch "agent0", "run", "args"
+        assert_equal 'myinit,initbussines,agent0.run(args),closebussines', d.trace
+    
+        #no id
+        d=Agent::DispatchString "run"
+        assert_equal 'myinit,initbussines,agent.run(),closebussines', d.trace
+        
+        #no command 
+        d = Agent::Dispatch()        
+        assert_equal 'myinit,initbussines,agent.run(),closebussines', d.trace
+    
+        
+        # Agent::DispatchOpts()     TODO
+    end
+
+    def test_childA
+        d = AgentChild::DispatchString "agent0 run arg1 arg2"
+        assert_equal 'myinit,initbussines,specialInit,agent0.run2(arg1arg2),closebussines', d.trace
+
+        d = AgentChild::DispatchString "agent0 start"
+        assert_equal 'myinit,initbussines,specialInit,agent0.start(),closebussines', d.trace    
+    end
+
+    def test_childB
+        d = AgentChildB.new 'xxx'
+        d.dispatchString "agent1 run args"
+        assert_equal 'myinit,ownConstructor:xxx,initbussines,agent1.run(args),closebussines', d.trace    
+    end
+
+    def test_badcommand
+        assert_raises (RuntimeError) {
+            d = Agent::Dispatch 'agent3', 'nocmd', 'xxx'
+        }
+    end
+
+    def test_config
+        #default config - root
+        d = Agent::DispatchString "agent1 run"
+        assert_equal( {:shared=>0}, hashStrip(d.cfg), 'config')
+
+        #default config - inherited
+        d = AgentChild::DispatchString "agent0 run"
+        assert_equal( {:shared=>0}, hashStrip(d.cfg), 'config')
+
+        root = ENV['AGENTS_ROOT']
+        #config with path and with filename
+        d = AgentChild::DispatchString "--config #{File.join(root,'config/config1.yml')} agent0 run"
+        assert_equal( {:shared=>123, :butcher=>true}, hashStrip(d.cfg), 'config')
+
+        #config with config name
+        d = AgentChild::DispatchString "--config config2 agent0 run"
+        assert_equal( {:shared=>456, :milkman=>true}, hashStrip(d.cfg), 'config')
+
+        #mutliple configs
+        d = AgentChild::DispatchString "--config config1,config2 agent0 run"
+        assert_equal( {:shared=>456, :butcher=>true, :milkman=>true}, hashStrip(d.cfg), 'config')
+
+        # with command line overwriting
+        d = AgentChild::DispatchString "--config config1,config2 --shared 999 agent0 run"
+        assert_equal( {:shared=>'999', :butcher=>true, :milkman=>true}, hashStrip(d.cfg), 'config')
+    end
+
+
+    #test with overriding @log and @id in constructor
+    def test_forcedProperties
+        d = AgentChildForced::DispatchString "agentForce run"
+        assert_equal 'myOwn', d.id, 'custom id'
+    end
+
+    def test_nopid
+    end
+
+    def test_noruntime
+    end
+private
+    def hashStrip sup
+        ex = [:log_path,  :pid_path, :id, :cmd, :args, :config]
+        sup.reject {|k,v| ex.include? k}
+    end
+
+end

data/test/test_opts.rb

@@ -0,0 +1,64 @@
+#Viktor Zigo, http://alephzarro.com, All rights reserved.
+require 'test/unit'
+thispath=File.dirname(__FILE__)
+require File.join(thispath, '../lib', 'opts.rb')
+
+class OptsTest< Test::Unit::TestCase
+    def test_dynamic1
+        ARGV.replace ["--forcepid", "--config", "file.cfg", "-c", "Big test", "anID", "start"]
+        p "Input: #{ARGV.inspect}"
+        opts = DynamicCmdParse .new.parse!
+        p "Output: #{opts.inspect}, ARGV = #{ARGV.inspect}"
+        assert_equal( {:forcepid=>true, :config=>'file.cfg', :c=>'Big test'}, opts, "parsed opts")
+        assert_equal( ['anID', 'start'], ARGV, "rest of argv")
+    end
+
+    def test_dynamic2
+        ARGV.replace ["tooearly", "--c-1", "val1", "-c_2", "val2", "toolate"]
+        p "Input: #{ARGV.inspect}"
+        opts = DynamicCmdParse.new.parse!
+        p "Output: #{opts.inspect}, ARGV = #{ARGV.inspect}"
+        assert_equal( {:'c-1'=>'val1', :c_2=>'val2'}, opts, "parsed opts")
+        assert_equal( ['tooearly', 'toolate'], ARGV, "rest of argv")
+    end
+
+    def test_dynamic3
+        #only one flag
+        ARGV.replace ["--help"]
+        p "Input: #{ARGV.inspect}"
+        opts = DynamicCmdParse .new.parse!
+        p "Output: #{opts.inspect}, ARGV = #{ARGV.inspect}"
+        assert_equal( {:help=>true}, opts, "parsed opts")
+    end
+
+    def test_dynamicArray
+        ARGV.replace ["-array","1,a_3,fero"]
+        p "Input: #{ARGV.inspect}"
+        opts = DynamicCmdParse.new.parse!
+        p "Output: #{opts.inspect}, ARGV = #{ARGV.inspect}"
+        assert_equal( {:array=>['1','a_3','fero']}, opts, "parsed opts")
+        assert_equal( [], ARGV, "rest of argv")
+    end
+
+    class TestCmdParse < StaticCmdParser
+        def addOpts aParser, opts
+            aParser.on("-c", "--config YMLFILE", "Configuration file, can be overriden by cmdline opts") { |file| opts[:config] = file }
+            aParser.on( "-f", "--forcepid", "Forces execution without pid") { |v| opts[:pid]= v }
+            opts
+        end
+        def validateOpts opts, argv
+            #puts "XXXXXXXXX: #{opts.inspect}"
+            raise OptionParser::MissingArgument, "config" unless opts[:config]
+        end        
+    end
+
+    def test_static1
+        ARGV.replace ["-c", "file.yml", "--forcepid", "rest1", "rest2"]
+        p "Input: #{ARGV.inspect}"
+        opts = TestCmdParse.new.parse!
+        p "Output: #{opts.inspect}, ARGV = #{ARGV.inspect}" 
+         assert_equal( {:config=>"file.yml", :pid=>true}, opts, "opts" )
+        assert_equal( ["rest1", "rest2"], ARGV, "rest" )
+    end
+
+end

data/test/test_simpledispather.rb

@@ -0,0 +1,74 @@
+#Viktor Zigo, http://alephzarro.com, All rights reserved. Distributed under GNU GPL License
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'test/unit'
+require 'simpledispatcher.rb'
+
+class SimpleAgent
+    include SimpleDispatcher
+    @AllowedCommands = %w(start stop)
+
+    def initialize id = nil
+        puts "initializing #{self.class}, id=#{id}"
+        @trace = ["init:#{id}"]
+    end
+
+    def on_start *args
+        @trace<< "start:#{args}"
+    end
+
+    def on_stop *args
+        @trace<< "stop:#{args}"
+    end
+    attr_reader :trace
+end
+
+class SimpleAgentChild < SimpleAgent
+    @AllowedCommands = %w(start stop run)
+
+    def on_run *args
+        @trace<< "run2:#{args}"
+    end
+end
+
+class SimpleDispatcherTest< Test::Unit::TestCase
+
+    def test_basic
+        d = SimpleAgent::Dispatch 'agent0', 'start', 'echo 42'
+        assert_equal "init:agent0,start:echo 42", d.trace.join(',')
+    
+        #instance
+        d=SimpleAgent.new('agent0')
+        d.dispatch 'start', 'echo 42'
+        assert_equal "init:agent0,start:echo 42", d.trace.join(',')
+    end
+
+    def test_badcommand
+        assert_raises (RuntimeError) {
+            d = SimpleAgent::Dispatch 'agent3', 'run', 'xxx'
+        }
+    end
+
+    def test_lessParams
+        #no id
+        d = SimpleAgent::Dispatch 'start', 'echo 42'
+        assert_equal "init:simpleagent,start:echo 42", d.trace.join(',')
+        #nothing
+        d = SimpleAgent.Dispatch 'start'
+        assert_equal "init:simpleagent,start:", d.trace.join(',')
+    end
+
+    def test_basicOpts
+        d = SimpleAgent::DispatchOpts :id=>'agent0', :cmd=>'start', :whatever=>'echo 42'
+        #assert_equal "init:agent0,start:cmdstartidagent0whateverecho 42", d.trace.join(',')
+    
+        #instance
+        d = SimpleAgent::DispatchOpts :cmd=>'start', :whatever=>'echo 42'
+        #assert_equal "init:simpleagent,start:cmdstartwhateverecho 42", d.trace.join(',')
+    end
+
+
+    def test_basicchild
+        d = SimpleAgentChild::Dispatch 'agent1', 'run', 'echo 42'
+        assert_equal "init:agent1,run2:echo 42", d.trace.join(',')
+    end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: agentdispatcher
+version: !ruby/object:Gem::Version 
+  version: 0.7.0
+platform: ruby
+authors: 
+- Viktor Zigo
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-04-05 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: 
+email: viz@alephzarro.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/agentdispatcher.rb
+- lib/opts.rb
+- lib/proctools.rb
+- lib/simpledispatcher.rb
+- test/runtime
+- test/runtime/var
+- test/runtime/var/run
+- test/runtime/config
+- test/runtime/config/config1.yml
+- test/runtime/config/config2.yml
+- test/runtime/tmp
+- test/runtime/tmp/log
+- test/test_opts.rb
+- test/test_agentdispatcher.rb
+- test/test_simpledispather.rb
+- test/test_agent_lowlevel.rb
+- README
+has_rdoc: true
+homepage: http://rubyagent.rubyforge.org/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: rubyagent
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: Solid infrastructure roots for script based agents
+test_files: 
+- test/test_opts.rb
+- test/test_agentdispatcher.rb
+- test/test_simpledispather.rb
+- test/test_agent_lowlevel.rb