scout_agent 3.0.6 → 3.0.7

data/CHANGELOG

@@ -1,3 +1,21 @@
+== 3.0.7
+
+* Added a log() method (with a logger() alias) plugins can access to add
+  messages to the log as needed
+* Added JSON hooks for the Time class so they will be converted back to Ruby
+  objects when loaded
+* Added a `scout_agent test` command for plugin developers
+* Switched to the default URL of https://beta.scoutapp.com
+* Improved the error handling in the communications agent for connection failure
+  scenarios like blocked ports (fixes a CPU pegging bug)
+* Loosened error checking when killing processes to improve monitor stability
+* Loosened the check-in timeout a touch as the monitor seemed to kill off
+  processes a little too quickly
+* Enhanced the monitor to kill off mission processes after killing the mission
+  runner
+* Made the stop command hunt for stray processes after stopping the monitor
+  process
+
 == 3.0.6
 
 * The new `sudo scout_agent update` command can be used to update your

data/Rakefile

@@ -81,7 +81,7 @@ end
 
 Rake::RDocTask.new do |rdoc|
 	rdoc.main     = "README"
-	rdoc.rdoc_dir = "doc/html"
+	rdoc.rdoc_dir = "doc"
 	rdoc.title    = "Scout Agent Documentation"
 	rdoc.rdoc_files.include( *%w[ README  INSTALL TODO    CHANGELOG
 	                              AUTHORS COPYING LICENSE lib/ ] )

data/lib/scout_agent/agent/communication_agent.rb

@@ -18,6 +18,7 @@ module ScoutAgent
         @agent_jid       = nil
         @jabber          = nil
         @roster          = nil
+        @connecting      = false
         @shutdown_thread = nil
         @trusted         = Array(Plan.xmpp_trusted).map { |trusted|
           trusted_with_server = trusted.sub(/@\*\z/, "@#{jabber_server}")
@@ -36,6 +37,7 @@ module ScoutAgent
       end
       
       def finish
+        log.info("Shutting down.")
         if @shutdown_thread
           @shutdown_thread.run
         else
@@ -51,17 +53,19 @@ module ScoutAgent
         log.info("Connecting to XMPP:  #{@agent_jid}")
         @jabber    = Jabber::Client.new(@agent_jid)
         @jabber.on_exception do |error, stream, during|
-          try_connection
+          try_connection unless @connecting
         end
         try_connection
       end
       
       def try_connection
+        @connecting = true
         until connect_and_authenticate?
           log.info( "Waiting #{RECONNECT_WAIT} seconds before making another " +
                     "connection attempt." )
           sleep RECONNECT_WAIT
         end
+        @connecting = false
       end
       
       def connect_and_authenticate?

data/lib/scout_agent/agent/master_agent.rb

@@ -271,7 +271,7 @@ module ScoutAgent
         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})." )
+                     "#{error.message} (#{error.class})." )
           reported = @db.write_report(
             mission[:id],
             :error,
@@ -287,11 +287,11 @@ module ScoutAgent
         if prepared = Mission.prepared
           log.info("Starting #{mission[:name]} mission.")
           status("Running")
-          prepared.new( *mission.values_at( :id,
-                                            :name,
-                                            :last_run_at,
-                                            :memory,
-                                            :options ) ).run
+          prepared.new( *( mission.values_at( :id,
+                                              :name,
+                                              :last_run_at,
+                                              :memory,
+                                              :options ) + [@log] ) ).run
         else   # no mission loaded
           log.error("#{mission[:name]} could not be prepared.")
           reported = @db.write_report(

data/lib/scout_agent/agent.rb

@@ -2,9 +2,17 @@
 # encoding: UTF-8
 
 module ScoutAgent
+  #
+  # An Agent is a subprocess launched at startup and kept running by a Lifeline
+  # monitor.  These subprocesses manage the major functions of the platform.
+  # 
   class Agent
     include Tracked
     
+    # 
+    # Prepares a new agent instance by building a log() and setting a
+    # <tt>"Loading"</tt> status message.
+    # 
     def initialize
       @log = ScoutAgent.prepare_wire_tap(file_name)
       log.info("Loading.")
@@ -15,27 +23,40 @@ module ScoutAgent
       end
     end
     
+    # The log file this agent will report to.
     attr_reader :log
     
+    # Ensure we are the only process with this name running.
     def authorize
       IDCard.new(file_name).authorize
     end
     
-    def run
-      raise NotImplementedError,
-            "Subclasses must override ScoutAgent::Agent#run()."
-    end
-    
+    #
+    # This method will be called when the agent process receives an +ALRM+
+    # signal.  By default, this method is a no-op, but subclasses can overrided
+    # it to add behavior.
+    # 
     def notice_changes
       # do nothing:  specific agents can override for their purposes
     end
     
+    # 
+    # This method will be called when the agent receives a +TERM+ signal.  The
+    # default behavior is to exit(), but subclasses can override it to add more
+    # specific behavior.
+    # 
     def finish
       exit
     end
     
+    #######
     private
+    #######
     
+    # 
+    # Returns the file name to be used for this agent's PID files and status
+    # entries.
+    # 
     def file_name
       self.class.short_name.sub(/Agent\z/, "").snake_case
     end

data/lib/scout_agent/api.rb

@@ -18,8 +18,8 @@ end
 module ScoutAgent
   # 
   # This module contains methods used to communicate with the agent
-  # programmatically.  These methods can be used to send data to the agent or
-  # to make requests that the agent perform certain actions for you.
+  # programmatically.  These methods can be used to send data to the agent or to
+  # make requests that the agent perform certain actions for you.
   # 
   module API
     #
@@ -29,6 +29,11 @@ module ScoutAgent
     # or failure of your requests.
     # 
     class Command
+      # 
+      # Prepares and runs an API command by shelling out to +name+, optionally
+      # with +args+ or +input+.  You can also set +options+ for the run, like
+      # <tt>:background => true</tt>.
+      # 
       def initialize(name, args, input, options)  # :nodoc:
         @name          = name
         @args          = args
@@ -68,20 +73,26 @@ module ScoutAgent
         @finished
       end
       
+      #######
       private
+      #######
       
+      # 
+      # Runs the prepared command, setting +exit_status+, +error_message+, and
+      # +finished+ on completion with the results of the run.
+      # 
       def run
         command        = [ API.path_to_ruby, API.path_to_agent,
                            @name,            *Array(@args) ].
                          map { |s| "'#{API.shell_escape(s)}'" }.join(" ")
         begin
-          response     = open("| #{command} 2>&1", "r+") do |agent|
+          response     = open("| #{command} 2>&1", "r+") { |agent|
             agent.puts @input.to_json if @input
             agent.close_write
             agent.read
-          end
+          }
         rescue Exception => error  # we cannot shell out to the agent
-          @exit_status   = ($? && $?.exitstatus) || -1
+          @exit_status   = ($? && $?.exitstatus) || 1
           @error_message = "#{error.message} (#{error.class})"
           @finished      = true
           return
@@ -91,19 +102,37 @@ module ScoutAgent
         @finished      = true
       end
       
+      # Wraps run() in a background Thread.
       def run_in_background
-        Thread.new { run }
+        Thread.new do
+          run
+        end
       end
     end
     
+    #
+    # This is a private specialization of Command that adds some validation for
+    # queue commands in order to fail faster during API calls.
+    # 
     class QueueCommand < Command  # :nodoc:
+      # 
+      # Simplifies the needed parameters to be specific to queue commands. 
+      # Validation is also invoked here before the command is run.
+      # 
       def initialize(mission_id_or_report_type, fields, options)
         validate(mission_id_or_report_type, fields)
         super(:queue, [mission_id_or_report_type], fields, options)
       end
       
+      #######
       private
+      #######
       
+      # 
+      # Duplicates some error checking done by the queue command, so that
+      # bad calls can fail before we pay the penalty of shelling out to the
+      # agent.
+      # 
       def validate(mission_id_or_report_type, fields)
         unless mission_id_or_report_type.to_s =~
                /\A(?:report|hint|alert|error|\d*[1-9])\z/
@@ -125,7 +154,13 @@ module ScoutAgent
       end
     end
     
+    ###############
     module_function
+    ###############
+    
+    ###############
+    ### Helpers ###
+    ###############
     
     # 
     # This convience method will escape a single _word_ for use in a shell
@@ -161,6 +196,10 @@ module ScoutAgent
                                                   *%w[.. .. bin scout_agent] ) )
     end
     
+    ###############
+    ### Queuing ###
+    ###############
+    
     #
     # Use this method to queue a +message+ for a mission to receive on it's next
     # run.
@@ -177,7 +216,7 @@ module ScoutAgent
     #   end
     # 
     # If you don't wish to wait, you can request that the send take place in the
-    # background.  You can still use the command objects to check the status of
+    # background.  You can still use the Command object to check the status of
     # these requests, but you must first wait for them to be finished?().  Do
     # not trust any other methods, like success?(), until finished?() returns
     # +true+.
@@ -242,6 +281,10 @@ module ScoutAgent
       QueueCommand.new(:error, fields, options)
     end
     
+    #################
+    ### Snapshots ###
+    #################
+    
     # 
     # :call-seq:
     #   take_snapshot(options = { })
@@ -253,16 +296,13 @@ module ScoutAgent
     # during the next checkin.  The returned object and background processing
     # rules are the same as those described in queue_for_mission().
     # 
-    # Passing a `true` value in `force` clears the command times before running,
+    # Passing a +true+ value in +force+ clears the command times before running,
     # forcing a full snapshot to be taken.
     # 
     def take_snapshot(*args)
-      started = Time.now
       force   = args.shift ? %w[force] : nil unless args.first.is_a? Hash
-      options = args.shift || { }
+      options = args.shift || Hash.new
       Command.new(:snapshot, force, nil, options)
-    ensure
-      p Time.now - started
     end
   end
 end

data/lib/scout_agent/assignment/configuration.rb

@@ -3,7 +3,18 @@
 
 module ScoutAgent
   class Assignment
+    #
+    # Invoke with:
+    # 
+    #   scout_agent config
+    # 
+    # This command shows the current configuration of the agent mainly
+    # determined by reading the configuration file.  However, you can pass
+    # command-line switches when running this command to see how they change
+    # things and help you find a good setup for other commands.
+    # 
     class Configuration < Assignment
+      # Runs the configuration command.
       def execute
         puts "Configuration"
         puts "============="

data/lib/scout_agent/assignment/identify.rb

@@ -3,15 +3,27 @@
 
 module ScoutAgent
   class Assignment
+    #
+    # Invoke with:
+    # 
+    #   sudo scout_agent id
+    # 
+    # This command prepares the agent for use by recording your key and settings
+    # into a configuration file.  This file is then loaded by all other commands
+    # to configure the agent for use.  Have a look at <tt>scout_agent -h</tt>
+    # for other options you may wish to set, like +proxy+.
+    # 
     class Identify < Assignment
       plan         :switches_only
       choose_group true
       
+      # Runs the identify command.
       def execute
         puts "Identifying Your Agent"
         puts "======================"
         puts
         
+        # make sure we can access the needed directories
         %w[config_file db_dir log_dir].each do |path|
           full = dir = Plan.send(path)
           loop do
@@ -23,6 +35,7 @@ module ScoutAgent
           end
         end
         
+        # get a key and test the server connection with that key
         unless Plan.config_file.exist?
           print <<-END_KEY_DESCRIPTION.trim.to_question
           I need your Agent Key displayed in the Agent Settings tab
@@ -42,6 +55,7 @@ module ScoutAgent
           end
         end
         
+        # write the configuration file
         puts "Saving identification..."
         if Plan.write_default_config_file
           puts "Identification file '#{Plan.config_file}' created."
@@ -52,6 +66,7 @@ module ScoutAgent
             abort_with_insufficient_permissions(Plan.config_file)
           end
         end
+        # create directories and global databases
         %w[db_dir log_dir].each do |path|
           dir = Plan.send(path)
           if dir.exist?
@@ -77,6 +92,7 @@ module ScoutAgent
         puts "Done."
         puts
         
+        # show next steps
         puts <<-END_START_INSTRUCTIONS.trim
         You are now identified.  You can start the agent with:
         
@@ -85,8 +101,14 @@ module ScoutAgent
         END_START_INSTRUCTIONS
       end
       
+      #######
       private
+      #######
       
+      # 
+      # Abort with an error message to the user that says we lack the
+      # permissions to configure their agent.
+      # 
       def abort_with_insufficient_permissions(path)
         abort <<-END_PRIVILEGES.trim
         I don't have enough privileges to create '#{path}'.
@@ -97,6 +119,10 @@ module ScoutAgent
         END_PRIVILEGES
       end
       
+      # 
+      # Abort with an error message to the user that says tells them their key
+      # is probably not valid.
+      # 
       def abort_with_bad_key
         abort <<-END_BAD_KEY.trim
         Could not contact server.  The key may be incorrect.

data/lib/scout_agent/assignment/queue.rb

@@ -6,7 +6,27 @@ require "io/wait"
 
 module ScoutAgent
   class Assignment
+    #
+    # Invoke with:
+    # 
+    #   scout_agent q ID_OR_TYPE <<< '{"fields": "in JSON"}'
+    # 
+    # This command queues some data from an external source for a plugin.  The
+    # plugin to receive the message is given by ID in +ID_OR_TYPE+.  That plugin
+    # will be able to collect this data during its next run.
+    # 
+    # Alternately, this command can be used to send a complete report, alert,
+    # error, or hint directly to the server (with the next check-in).  When
+    # using as such, +ID_OR_TYPE+ must be one of those types and the fields must
+    # be a Hash (object in JSON terminology) that includes the key "plugin_id"
+    # associated with an ID value for the reporting plugin.
+    # 
     class Queue < Assignment
+      # 
+      # A list of errors that can be sent to the user when attempting to queue a
+      # message.  The index of the message plus one is also the exit status for
+      # that error.
+      # 
       ERRORS = [ [ :missing_db,
                    "Queue database could not be loaded." ],
                  [ :missing_id,
@@ -27,19 +47,24 @@ module ScoutAgent
                  [ :failed_to_queue_message,
                    "Your message could not be queued at this time." ] ]
       
+      # Runs the queue command.
       def execute
+        # prepare the log
         log = ScoutAgent.prepare_wire_tap(:queue, :skip_stdout)
 
+        # record our status and set removal at_exit()
         status_database(log)
         status("Queuing message", :queue)
         at_my_exit do
           clear_status(:queue)
         end
         
+        # load the queue database
         unless db = Database.load(:queue, log)
           abort_with_error(:missing_db)
         end
         
+        # ensure id or type is valid
         log.info("Validating message for queuing.")
         unless id = Array(other_args).shift
           abort_with_error(:missing_id)
@@ -48,6 +73,7 @@ module ScoutAgent
           abort_with_error(:invalid_id)
         end
         
+        # read field data and parse JSON
         fields = ARGF.read unless ARGV.empty? and not $stdin.ready?
         if fields.nil? or fields.empty?
           abort_with_error(:missing_fields)
@@ -59,6 +85,7 @@ module ScoutAgent
           abort_with_error(:invalid_fields)
         end
         
+        # ensure we have a valid plugin_id, if needed
         if %w[report hint alert error].include? id
           unless fields.is_a? Hash
             abort_with_error(:invalid_report_fields)
@@ -74,18 +101,26 @@ module ScoutAgent
           log.info("Message is valid (#{bytes} bytes).")
         end
         
+        # queue the message
         log.info("Queuing message.")
         unless db.enqueue(id, fields)
           abort_with_error(:failed_to_queue_message)
         end
         
+        # maintain the queue database
         db.maintain
         
         log.info("Messages queued successfully.")
       end
       
+      #######
       private
+      #######
       
+      # 
+      # Abort with an error message and exit status that tells the user which
+      # part of the process failed.
+      # 
       def abort_with_error(error_name)
         error = ERRORS.assoc(error_name)
         warn error.last

data/lib/scout_agent/assignment/reset.rb

@@ -3,8 +3,20 @@
 
 module ScoutAgent
   class Assignment
+    #
+    # Invoke with:
+    # 
+    #   sudo scout_agent reset
+    # 
+    # This command removes all saved configuration and data from the agent.
+    # After this is run it's basically like the agent has been reset to the way
+    # it was after being intalled.  This is a dangerous command that destroys
+    # data and cannot be undone.
+    # 
     class Reset < Assignment
+      # Runs the reset command.
       def execute
+        # make sure the agent isn't running
         agent = IDCard.new(:lifeline)
         if agent.pid_file.exist?
           abort_with_agent_running
@@ -14,6 +26,7 @@ module ScoutAgent
         puts "================"
         puts
         
+        # get confirmation from the user
         print <<-END_WARNING.trim.to_question
         This is a dangerous operation that will remove configuration
         and data files.  Are you absolutely sure you wish to remove
@@ -25,6 +38,7 @@ module ScoutAgent
         
         puts
         puts "Resetting..."
+        # remove configuration file
         if not Plan.config_file.exist?
           puts <<-END_CONFIG_FILE
           Identification file '#{Plan.config_file}' doesn't exist.  Skipped.
@@ -37,6 +51,7 @@ module ScoutAgent
             abort_with_insufficient_permissions(Plan.config_file)
           end
         end
+        # remove directories and the data they contain
         %w[db_dir pid_dir log_dir].each do |path|
           dir = Plan.send(path)
           if not dir.exist?
@@ -53,6 +68,7 @@ module ScoutAgent
         puts "Done."
         puts
         
+        # show next steps
         puts <<-END_START_INSTRUCTIONS.trim
         This agent is reset.  You can prepare it for use again
         at anytime with:
@@ -62,8 +78,14 @@ module ScoutAgent
         END_START_INSTRUCTIONS
       end
       
+      #######
       private
+      #######
       
+      # 
+      # Abort with an error message to the user that says we with a warning that
+      # the agent cannot be reset when it is running.
+      # 
       def abort_with_agent_running
         abort <<-END_AGENT_RUNNING.trim
         You cannot reset while the agent is running.  Please stop
@@ -74,10 +96,18 @@ module ScoutAgent
         END_AGENT_RUNNING
       end
       
+      # 
+      # Abort with an error message to the user that confirms their
+      # cancellation of the reset.
+      # 
       def abort_with_cancel
         abort "Reset cancelled.  No data was removed."
       end
       
+      # 
+      # Abort with an error message to the user that says we don't have
+      # permission to remove some configuration.
+      # 
       def abort_with_insufficient_permissions(path)
         abort <<-END_PRIVILEGES.trim
         I don't have enough privileges to remove '#{path}'.