scout_agent 3.0.6 → 3.0.7

data/lib/scout_agent/assignment/test.rb

@@ -0,0 +1,366 @@
+#!/usr/bin/env ruby -wKU
+# encoding: UTF-8
+
+# require standard libraries
+require "open-uri"
+require "yaml"
+require "io/wait"
+
+# load agent extensions
+require "scout_agent/mission"
+
+# shut off SSL verification by open-uri
+module OpenSSL::SSL
+  remove_const(:VERIFY_PEER)
+  VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE
+end
+
+module ScoutAgent
+  class Assignment
+    #
+    # Invoke with:
+    # 
+    #   scout_agent test [once] path/to/plugin.rb [<<< '{"options": "in JSON"}']
+    # 
+    # This command is a test mode for plugin developers.  It allows you to run a
+    # plugin and see what that code generates.
+    # 
+    # The only required argument is a path to the plugin you wish to test.  That
+    # path can be a file path or a URL to load the code from.
+    # 
+    # By default, URL's will just be run once and files will be run in a loop
+    # that watches the code for changes and reruns until you control-c the
+    # process.  You can add the once parameter to have a file treated as a URL.
+    # 
+    # Default options will be read from a matching .yml file at the same path,
+    # if available.  You can also provide option settings on <tt>$stdin</tt>
+    # which will override the defaults.
+    # 
+    # If you need to test a plugin that expects queued messages, pass a
+    # <tt>"__queue__"</tt> option that's an Array of messages.
+    # They will be delivered to your plugin.
+    # 
+    class Test < Assignment
+      # Runs the test command.
+      def execute
+        install_interrupt_handler
+        prepare_log
+        parse_options
+        prepare_mission
+        load_code
+        load_options
+        test_mission
+      end
+      
+      #######
+      private
+      #######
+      
+      ############
+      ### Test ###
+      ############
+      
+      # Install a nice shutdown that doesn't include an Exception backtrace.
+      def install_interrupt_handler
+        trap("INT") do
+          Thread.new do
+            @log.info("Stopping.") if @log
+            exit
+          end
+        end
+      end
+      
+      # Builds a simple log to <tt>$stdout</tt> that shows all messages.
+      def prepare_log
+        @log          = WireTap.new($stdout)
+        @log.progname = :test
+      end
+      
+      # Pulls out the optional run-once and the required path options.
+      def parse_options
+        args = Array(other_args)
+        
+        # check for once option
+        @once     = false
+        @url_mode = false
+        if args.first == "once"
+          @log.info("Starting single plugin run.")
+          @once = args.shift
+        elsif args.first.to_s =~ %r{\A[A-Za-z][-A-Za-z0-9+.]*://}
+          @log.info("Testing plugin from a URL.")
+          @once = @url_mode = true
+        else
+          @log.info( "Starting plugin development mode.  " +
+                     "Watching code for changes." )
+        end
+        
+        # get the code path
+        unless @mission_path = args.shift
+          abort_with_missing_path
+        end
+      end
+      
+      # 
+      # Build the mission details that would normally have come from the
+      # database.
+      # 
+      def prepare_mission
+        @mission = { :id          => :testing,
+                     :name        => File.basename(@mission_path, ".rb"),
+                     :last_run_at => nil,
+                     :memory      => Hash.new,
+                     :options     => Hash.new }
+      end
+      
+      # Reads the code from disk or URL, loading it into the mission details.
+      def load_code
+        if @url_mode or ( File.exist?(@mission_path) and
+                          File.file?(@mission_path)  and
+                          File.readable?(@mission_path) )
+          begin
+            @mission[:code] = read_file_or_url(@mission_path)
+          rescue Exception  # reading error
+            abort_with_unreadable(@mission_path)
+          end
+        else
+          abort_with_unreadable(@mission_path)
+        end
+      end
+      
+      # 
+      # Reads the options first from the defaults file and then as overrides
+      # from <tt>$stdin</tt>.
+      # 
+      def load_options
+        # look for default options in the standard place
+        @options_path = @mission_path.sub(/\.rb/i, ".yml")
+        if @url_mode or ( File.exist?(@options_path) and
+                          File.file?(@options_path)  and
+                          File.readable?(@options_path) )
+          @log.info("Loading default options from '#{@options_path}'.")
+          begin
+            defaults = YAML.load(read_file_or_url(@options_path))
+          rescue Exception => error
+            if @url_mode
+              @log.warn("Options not found at '#{@options_path}'.")
+            else
+              case error
+              when ArgumentError  # invalid YAML
+                abort_with_bad_defaults
+              else                # reading error
+                abort_with_unreadable(@options_path)
+              end
+            end
+          end
+          if defaults.is_a?(Hash) and defaults["options"].is_a?(Hash)
+            defaults["options"].each do |name, details|
+              if details.is_a? Hash
+                @mission[:options].merge!(name => details["default"])
+              end
+            end
+          end
+        else
+          @log.warn("Options file '#{@options_path}' not found.")
+        end
+        
+        # also check for overrides
+        if defined?(@overrides) or $stdin.ready?
+          @log.info("Reading and setting option overrides.")
+          begin
+            @overrides ||= JSON.parse($stdin.read)
+          rescue JSON::ParserError
+            abort_with_bad_overrides
+          end
+          if @overrides.is_a? Hash
+            @mission[:options].merge!(@overrides)
+          end
+        end
+      end
+      
+      # 
+      # The main testing event loop for a plugin.  This controls execution,
+      # waiting through the run, updating time and memory, and waiting for
+      # code changes.
+      # 
+      def test_mission
+        unless @once
+          code_last_modified    = File.stat(@mission_path).mtime
+          options_last_modified = File.stat(@options_path).mtime rescue nil
+        end
+        loop do
+          # fork off the plugin process
+          @reader, @writer = IO.pipe
+          mission_pid = fork do
+            reset_environment
+            compile_mission
+            run_mission
+            complete_mission
+          end
+          
+          # ensure the child process exits in reasonable time
+          @writer.close
+          exit_status = nil
+          begin
+            Timeout.timeout(60) do
+              exit_status = Process.wait2(mission_pid).last
+            end
+          rescue Timeout::Error  # mission exceeded allowed execution
+            exit_status = Process.term_or_kill(mission_pid)
+            @log.error( "#{@mission[:name]} took too long to run:  " +
+                        "#{exit_status && exit_status.exitstatus}." )
+          end
+          
+          # stop there if this is a one shot
+          break if @once
+          
+          # update mission details
+          @mission[:last_run_at] = Time.now
+          if exit_status and exit_status.success?
+            begin
+              @mission[:memory]  = JSON.parse(@reader.read)
+              @log.debug("Plugin memory updated to %p." % @mission[:memory])
+            rescue Exception  # bad memory transfer
+              @log.error("Memory could not be updated.")
+              # do nothng:  keeping old memory
+            end
+          end
+          
+          # reload the code when it changes
+          @log.info("Watching plugin code for changes.")
+          loop do
+            modified      = false
+            code_modified = File.stat(@mission_path).mtime
+            if code_modified > code_last_modified
+              code_last_modified = code_modified
+              load_code
+              modified = true
+            end
+            options_modified = File.stat(@options_path).mtime rescue nil
+            if (not options_last_modified and options_modified) or
+               ( options_last_modified and
+                 options_modified      and
+                 options_modified > options_last_modified )
+              options_last_modified = options_modified
+              load_options
+              modified = true
+            end
+            break if modified
+            sleep 1
+          end
+        end
+      end
+      
+      ###############
+      ### Helpers ###
+      ###############
+      
+      # Loads data from a file or URL +path+, without OpenSSL warnings.
+      def read_file_or_url(path)
+        no_warnings { open(path) { |data| data.read } }
+      end
+      
+      ###############
+      ### Mission ###
+      ###############
+      
+      # Resets the log process name and closes have of the memory transfer pipe.
+      def reset_environment
+        @log          = WireTap.new($stdout)
+        @log.progname = :mission
+        
+        @reader.close
+      end
+      
+      # Compiles the mission code without generating database errors.
+      def compile_mission
+        @log.info("Compiling #{@mission[:name]} mission.")
+        begin
+          eval(@mission[:code], TOPLEVEL_BINDING, @mission[:name])
+        rescue Exception => error       # any compile error
+          raise if $!.is_a? SystemExit  # don't catch exit() calls
+          @log.error( "#{@mission[:name]} could not be compiled:  " +
+                      "#{error.message} (#{error.class})." )
+          exit(2)  # warn parent that we failed to compile
+        end
+      end
+      
+      # Executes the mission without generating database errors.
+      def run_mission
+        @log.info("Preparing #{@mission[:name]} mission.")
+        if prepared = Mission.prepared
+          @log.info("Starting #{@mission[:name]} mission.")
+          @mission[:object] =
+            prepared.new( *( @mission.values_at( :id,
+                                                 :name,
+                                                 :last_run_at,
+                                                 :memory,
+                                                 :options ) + [@log] ) )
+          @mission[:object].run
+        else   # no mission loaded
+          @log.error("#{@mission[:name]} could not be prepared.")
+          exit(3)  # warn parent that we couldn't prpare mission
+        end
+      end
+      
+      # Transfers mission memory back to the testing process.
+      def complete_mission
+        @log.info("#{@mission[:name]} mission complete.")
+        @writer.puts @mission[:object].data_for_server[:memory].to_json
+      end
+      
+      ##############
+      ### Errors ###
+      ##############
+      
+      # 
+      # Abort with an error message to the user that explains that the path or
+      # URL is a required argument.
+      # 
+      def abort_with_missing_path
+        abort <<-END_MISSING_PATH.trim
+        
+        You must provide a path to your code on the file system or a URL to
+        fetch it from:
+        
+          scout_agent test PATH_OR_URL
+          
+        END_MISSING_PATH
+      end
+      
+      # 
+      # Abort with an error message to the user that says we can't parse the
+      # provided JSON.
+      # 
+      def abort_with_unreadable(file)
+        abort "\nFailed to read from '#{file}'."
+      end
+      
+      # 
+      # Abort with an error message to the user that says we can't parse the
+      # default options YAML file.
+      # 
+      def abort_with_bad_defaults
+        abort <<-END_BAD_DEFAULTS.trim
+        
+        Failed to parse option defaults.  You must provide default options in
+        Scout's standard YAML format.
+        END_BAD_DEFAULTS
+      end
+      
+      # 
+      # Abort with an error message to the user that says we can't parse the
+      # provided JSON.
+      # 
+      def abort_with_bad_overrides
+        abort <<-END_BAD_OVERRIDES.trim
+        
+        Failed to parse option overrides.  You must provide options in valid
+        JSON.  For example:
+        
+          scout_agent test … <<< '{"field": "setting", "num": 42}'
+          
+        END_BAD_OVERRIDES
+      end
+    end
+  end
+end

data/lib/scout_agent/assignment/update.rb

@@ -3,7 +3,19 @@
 
 module ScoutAgent
   class Assignment
+    #
+    # Invoke with:
+    # 
+    #   sudo scout_agent update
+    # 
+    # This command rewrites the current configuration file.  As such, it has two
+    # main uses.  First, you can run this command to load the current file, pass
+    # some switches to change settings, and it will save the changes like a text
+    # editor would.  It's also useful when an updated version of the agent
+    # includes new options you would like to have added to your existing file.
+    # 
     class Update < Assignment
+      # Runs the update command.
       def execute
         begin
           Plan.config_file.unlink
@@ -22,6 +34,14 @@ module ScoutAgent
         end
       end
       
+      #######
+      private
+      #######
+      
+      # 
+      # Abort with an error message to the user that says we don't have enough
+      # permission to rewrite the configuration file.
+      # 
       def abort_with_sudo_required
         abort <<-END_SUDO_REQUIRED.trim
         I don't have enough privileges to update your identity and

data/lib/scout_agent/assignment/upload_log.rb

@@ -6,18 +6,34 @@ require "tempfile"
 
 module ScoutAgent
   class Assignment
+    #
+    # Invoke with:
+    # 
+    #   scout_agent upload_log [FILE_DATE]
+    # 
+    # This command can help us troubleshoot problems with your agent.  You can
+    # invoke this to pass a log file up to our servers, so we can look through
+    # it for problems.  Note that this is never done automatically. You must
+    # invoke this command manually.
+    # 
+    # The +FILE_DATE+ is just the date of the log file in the form YYYY-MM-DD.
+    # 
     class UploadLog < Assignment
+      # Runs the upload_log command.
       def execute
+        # build the log file name
         file_name = "#{ScoutAgent.agent_name}.log"
         if date = Array(other_args).shift
           file_name += ".#{date.delete('^0-9')}"
         end
         log_file = Plan.log_dir + file_name
         
+        # ensure it exists
         unless log_file.exist?
           abort_with_not_found(file_name)
         end
         
+        # copy the log to a zipped temporary file
         puts "Preparing file for the server.  This may take a moment..."
         begin
           upload_file = Tempfile.new("#{file_name}.gz")
@@ -32,7 +48,7 @@ module ScoutAgent
         end
         puts "Done."
         
-        
+        # upload the zipped temporary file to the server
         puts "Sending file to the server.  This may take a moment..."
         server = Server.new
         if server.post_log(upload_file)
@@ -42,18 +58,32 @@ module ScoutAgent
         end
       end
       
+      #######
       private
+      #######
       
+      # 
+      # Abort with an error message to the user that says we can't find the
+      # indicated or default log file.
+      # 
       def abort_with_not_found(log_file_name)
         abort "'#{log_file_name}' could not be found to upload."
       end
       
+      # 
+      # Abort with an error message to the user that says why we can't prepare
+      # the file for upload.
+      # 
       def abort_with_preparation_error(error)
         abort <<-END_PREPARATION_ERROR
         Could not prepare file for upload:  #{error.message} (#{error.class})
         END_PREPARATION_ERROR
       end
       
+      # 
+      # Abort with an error message to the user that says we received a server
+      # error when we attempted to upload.
+      # 
       def abort_with_server_error
         abort "A networking error prevented the file from being sent."
       end

data/lib/scout_agent/assignment.rb

@@ -2,19 +2,62 @@
 # encoding: UTF-8
 
 module ScoutAgent
+  #
+  # An Assignment is a command that can be given to the agent on the
+  # command-line.  This object encapsulates the series of steps needed to invoke
+  # a command and subclasses supply the specific behavior.
+  # 
   class Assignment
-    { :plan         => :file_and_switches,
-      :choose_user  => false,
-      :choose_group => false }.each do |name, default|
-      instance_eval <<-END_CONFIG
-      def #{name}(setting = nil)
-        @#{name} ||= #{default.inspect}  # default
-        @#{name} =   setting if setting  # writer
-        @#{name}                         # reader
+    #
+    # This method is a factory for one method class attributes supporting
+    # getting (with a default) and setting.
+    # 
+    def self.get_or_set(name, default, setting = nil)
+      var = "@#{name}"
+      if setting
+        instance_variable_set(var, setting)  # writer
+      elsif not instance_variable_defined? var
+        instance_variable_set(var, default)  # default
       end
-      END_CONFIG
+      instance_variable_get(var)             # reader
     end
+    private_class_method :get_or_set
     
+    #
+    # If the +setting+ of this attribute includes the word "file", the
+    # configuration file will be loaded before the command is invoked.
+    # Similarly, the word "switches" will cause the configuration to be updated
+    # using the provided command-line switches.  The default setting is
+    # <tt>:file_and_switches</tt>.
+    # 
+    def self.plan(setting = nil)
+      get_or_set(:plan, :file_and_switches, setting)
+    end
+    
+    #
+    # If +setting+ is +true+, a user to operate as will be selected based on the
+    # configuration.  Note that a user is just selected and it's up to the 
+    # command to make use of it.  That user is available to commands via the
+    # user() method.
+    # 
+    def self.choose_user(setting = nil)
+      get_or_set(:choose_user, false, setting)
+    end
+    
+    #
+    # If +setting+ is +true+, a group to operate as will be selected based on
+    # the configuration.  Note that a group is just selected and it's up to the
+    # command to make use of it.  That group is available to commands via the
+    # group() method.
+    # 
+    def self.choose_group(setting = nil)
+      get_or_set(:choose_group, false, setting)
+    end
+    
+    #
+    # Builds a new Assignment with the passed +switches+ and +other_args+.  The
+    # Dispatcher usess this to prepare a command for running.
+    # 
     def initialize(switches, other_args)
       @switches   = switches
       @other_args = other_args
@@ -24,16 +67,35 @@ module ScoutAgent
     
     include Tracked
     
-    attr_reader :switches, :other_args, :user, :group
+    # The command-line switches passed to the command.
+    attr_reader :switches
+    # Any non-switch arguments passed to the command.
+    attr_reader :other_args
+    # The user to operate as, if selected.  See choose_user() for details.
+    attr_reader :user
+    # The group to operate as, if selected.  See choose_group() for details.
+    attr_reader :group
     
+    # 
+    # Loads configuaration as directed by plan(), selects indentity as directed
+    # by choose_user() and choose_group(), then calls execute() for the command.
+    # Subclasses provide the execute() method to provide their specific
+    # behavior.  The Dispatcher calls this method to launch a command.
+    # 
     def prepare_and_execute
       read_the_plan
       choose_identity
       execute
     end
     
+    #######
     private
+    #######
     
+    # 
+    # Reads the configuration file and/or updates the plan from the provided
+    # command-line switches.  See the plan() method for details.
+    # 
     def read_the_plan
       if self.class.plan.to_s.include? "file"
         begin
@@ -47,6 +109,10 @@ module ScoutAgent
       end
     end
     
+    #
+    # Selects a user and/or group as dictated by choose_user() and
+    # choose_group().  See those methods for details.
+    # 
     def choose_identity
       [ %w[user  getpwnam],
         %w[group getgrnam] ].each do |type, interface|
@@ -69,20 +135,29 @@ module ScoutAgent
       end
     end
     
+    # 
+    # Attempts to fetch a plan from the server as a way to test connectivity and
+    # the agent settings.  A status line will be printed to <tt>$stdout</tt>
+    # unless +quiet+ is +true+.
+    # 
     def test_server_connection(quiet = false)
       unless quiet
-        print "Testing server connection:  "
+        $stdout.print "Testing server connection:  "
         $stdout.flush
       end
       if Server.new.get_plan
-        puts "success." unless quiet
+        $stdout.puts "success." unless quiet
         true
       else
-        puts "failed." unless quiet
+        $stdout.puts "failed." unless quiet
         false
       end
     end
     
+    # 
+    # Abort with an error message to the user that says we cannot load their
+    # configuration file.
+    # 
     def abort_with_missing_config
       abort <<-END_MISSING_CONFIG.trim
       Unable to load configuration file.  Please make sure you
@@ -93,6 +168,10 @@ module ScoutAgent
       END_MISSING_CONFIG
     end
     
+    # 
+    # Abort with an error message to the user that says we cannot select a
+    # suitable <tt>:user</tt> or <tt>:group</tt> to operate as, based on +type+.
+    # 
     def abort_with_not_found(type)
       choices = Plan.send("#{type}_choices")
       config  = "\n\n    config.#{type}_choices = %w[#{choices.join(" ")}]\n\n"

data/lib/scout_agent/core_extensions.rb

@@ -161,8 +161,8 @@ module ScoutAgent
         %w[TERM KILL].each { |signal|
           begin
             ::Process.kill(signal, child_pid)  # attempt to stop process
-          rescue Errno::ECHILD, Errno::ESRCH   # no such process
-            break  # the process is stopped
+          rescue Exception   # no such process
+            break            # the process is stopped
           end
           if signal == "TERM"
             # give them a chance to respond
@@ -170,7 +170,8 @@ module ScoutAgent
               Timeout.timeout(pause) {
                 begin
                   return ::Process.wait2(child_pid).last  # response to signal
-                rescue Errno::ECHILD  # no such child
+                rescue Exception => error                 # no such child
+                  raise if error.is_a? Timeout::Error     # reraise timeouts
                   return nil # we have already caught the child
                 end
               }
@@ -181,8 +182,8 @@ module ScoutAgent
         }
         begin
           ::Process.wait2(child_pid).last
-        rescue Errno::ECHILD  # no such child
-          nil # we have already caught the child
+        rescue Exception  # no such child
+          nil             # we have already caught the child
         end
       end
     end
@@ -271,6 +272,15 @@ module ScoutAgent
           ::Time.local(*str.to_s.scan(/\d+/))
         end
       end
+      
+      #
+      # Half of the support for the round-tripping of Time objects to and from
+      # JSON.  This method reconstructs a Time object from a raw JSON object
+      # representation built by our to_json() override.
+      # 
+      def json_create(object)
+        ::Time.local(*object["data"])
+      end
     end
 
     # Extensions for the Time class.
@@ -283,6 +293,15 @@ module ScoutAgent
       def to_db_s(trim_seconds = false)
         strftime("%Y-%m-%d %H:%M#{':%S' unless trim_seconds}")
       end
+      
+      #
+      # Half of the support for the round-tripping of Time objects to and from
+      # JSON.  This method builds a JSON object representation for Time objects
+      # compatible with the JSON library's Ruby conversion support.
+      # 
+      def to_json(*args)
+        {:json_class => self.class.name, :data => to_a}.to_json(*args)
+      end
     end
   end
 end