scout_agent 3.0.3 → 3.0.4

data/CHANGELOG

@@ -1,3 +1,13 @@
+== 3.0.4
+
+* Upgraded to Arrayfields 4.7.3 to silence a warning on Ruby 1.9
+* Added HTTP proxy support
+* Added replies to acknowledge received messages from XMPP when a message ID is
+  included in the command
+* Turned XMPP on and aimed it at the real Scout server
+* Greatly improved error handling for the XMPP process
+* Added logging and status tracking for the XMPP operations
+
 == 3.0.3
 
 * Upgraded to JSON 1.1.4 for Ruby 1.9 compatibility

data/Rakefile

@@ -34,7 +34,7 @@ SA_SPEC = Gem::Specification.new do |spec|
 
 	spec.require_path = "lib"
 	
-  spec.add_dependency("arrayfields", "=4.7.2")  # fix Amalgalite's results
+  spec.add_dependency("arrayfields", "=4.7.3")  # fix Amalgalite's results
   spec.add_dependency("amalgalite",  "=0.9.0")
   spec.add_dependency("rest-client", "=0.9.2")
   spec.add_dependency("json",        "=1.1.4")

data/lib/scout_agent.rb

@@ -65,7 +65,7 @@ module ScoutAgent
   end
 
   # The version of this agent.
-  VERSION = "3.0.3".freeze
+  VERSION = "3.0.4".freeze
   # A Pathname reference to the agent code directory, used in dynamic loading.
   LIB_DIR = Pathname.new(File.dirname(__FILE__)) + agent_name
 end

data/lib/scout_agent/agent/communication_agent.rb

@@ -8,6 +8,8 @@ require "scout_agent/order"
 module ScoutAgent
   class Agent
     class CommunicationAgent < Agent
+      RECONNECT_WAIT = 60
+      
       def initialize
         super  # setup our log and status
 
@@ -21,16 +23,13 @@ module ScoutAgent
       end
       
       def run
-        if Plan.test_mode?
-          login
-          update_status("Online since #{Time.now.utc.to_db_s}")
-          fetch_roster
-          install_subscriptions_callback
-          install_messages_callback
-          listen
-        else
-          loop { sleep 60 }
-        end
+        login
+        update_status("Online since #{Time.now.utc.to_db_s}")
+        fetch_roster
+        install_subscriptions_callback
+        install_messages_callback
+        listen
+        close_connection
       end
       
       def finish
@@ -46,40 +45,117 @@ module ScoutAgent
       def login
         Thread.abort_on_exception = true  # make XMPP4R fail fast
         @agent_jid = Jabber::JID.new("#{agent_key}@#{jabber_server}/agent")
+        log.info("Connecting to XMPP:  #{@agent_jid}")
         @jabber    = Jabber::Client.new(@agent_jid)
-        no_warnings { @jabber.connect }
-        @jabber.auth(agent_key)
+        @jabber.on_exception do |error, stream, during|
+          try_connection
+        end
+        try_connection
+      end
+      
+      def try_connection
+        until connect_and_authenticate?
+          log.info( "Waiting #{RECONNECT_WAIT} seconds before making another " +
+                    "connection attempt." )
+          sleep RECONNECT_WAIT
+        end
+      end
+      
+      def connect_and_authenticate?
+        status("Connecting")
+        close_connection
+        begin
+          no_warnings { @jabber.connect }
+        rescue Exception => error  # connection failure
+          log.error("Failed to connect (#{error.class}:  #{error.message}).")
+          return false
+        end
+        begin
+          @jabber.auth(agent_key)
+        rescue Jabber::ClientAuthenticationFailure  # authentication failure
+          log.error("Authentication rejected.")
+          close_connection
+          return false
+        end
+        true
       end
       
       def update_status(message, status = nil)
+        status("Queuing status change")
         presence        = Jabber::Presence.new
         presence.status = message
         presence.show   = status
-        @jabber.send(presence)
+        # xmpp4r requires sending in a different Thread from the callbacks
+        Thread.new do
+          log.info("Setting status:  #{message}")
+          begin
+            @jabber.send(presence)
+          rescue Exception  # failure to update status
+            # do nothing:  server will still see us online
+            log.error("Unable to update status.")
+          end
+        end
       end
       
       def fetch_roster
+        status("Preparing connection")
         @roster = Jabber::Roster::Helper.new(@jabber)
       end
       
       def install_subscriptions_callback
         @roster.add_subscription_request_callback do |_, presence|
+          log.info("Accepting subscription:  #{presence.from}")
           @roster.accept_subscription(presence.from)
         end
       end
       
       def install_messages_callback
         @jabber.add_message_callback do |message|
-          if order = Order.can_handle?(message)
+          log.info("Received message from #{message.from}:  #{message.body}")
+          status("Parsing command")
+          modified_body = nil
+          if message.body =~ /\A\s*\[\s*(\d+)\s*\]\s*(.*)/
+            modified_body = $2
+            send_chat_message(message.from, "received #{$1}")
+          end
+          if order = Order.can_handle?(message, modified_body)
+            status("Processing command")
             order.execute
+          else
+            log.warn("Unrecognized message format, ingoring.")
+          end
+          status("Listening for commands")
+        end
+      end
+      
+      def send_chat_message(who, body)
+        status("Queuing message")
+        message      = Jabber::Message.new(who, body)
+        message.type = :chat
+        # xmpp4r requires sending in a different Thread from the callbacks
+        Thread.new do
+          log.info("Sending message to #{who}:  #{body}")
+          begin
+            @jabber.send(message)
+          rescue Exception  # failure to send message
+            # do nothing:  unable to reach the server
+            log.error("Unable to send message.")
           end
         end
       end
       
       def listen
+        log.info("Listening for commands.")
+        status("Listening for commands")
         @shutdown_thread = Thread.current
         Thread.stop
-        @jabber.close
+      end
+      
+      def close_connection
+        @jabber.close! if @jabber.is_connected?
+      rescue Exception  # connection already closed
+        # do nothing:  our connection is gone
+        log.warn("Failed to close connection.")
       end
       
       def agent_key
@@ -89,7 +165,8 @@ module ScoutAgent
       end
       
       def jabber_server
-        @jabber_server ||= Plan.test_mode? ? "jabber.org" : "FIXME"
+        @jabber_server ||= Plan.test_mode? ? "jabber.org" :
+                                             URI.parse(Plan.server_url).host
       end
     end
   end

data/lib/scout_agent/database/mission_log.rb

@@ -3,6 +3,12 @@
 
 module ScoutAgent
   class Database
+    #
+    # This database encapsulates the main function of the Scout agent:  running
+    # missions.  Details of the current plan and the missions of that plan are
+    # stored in these tables.  As missions are executed, they build up reports
+    # which are also held here until they can be pushed to the Scout server.
+    # 
     class MissionLog < Database
       # 
       # A default number of seconds a mission is allowed to run before it is
@@ -14,6 +20,10 @@ module ScoutAgent
       # A size limit for the reports table to prevent data from building up.
       REPORTS_LIMIT    = 3000
       
+      # 
+      # Build a schema for storing plans, missions, and reports.  The reports
+      # table is size controlled by trigger to prevent infinite data growth.
+      # 
       def update_schema(version = schema_version)
         case version
         when 0
@@ -50,6 +60,14 @@ module ScoutAgent
         end
       end
       
+      ################
+      ### The Plan ###
+      ################
+      
+      # 
+      # Returns the last known plan (+id+ and +last_modified+ date) or +nil+
+      # if none exists.
+      # 
       def current_plan
         plan = read_from_sqlite { |sqlite|
           sqlite.first_row_from(<<-END_FIND_PLAN.trim)
@@ -65,6 +83,13 @@ module ScoutAgent
         nil  # not found
       end
       
+      # 
+      # Given a new +last_modified+ date (as a String) and an Array of
+      # +missions+, this method attemps and all-or-nothing update of the current
+      # plan and missions.  The plan and any missions that were already present
+      # are simply updated.  New missions are added and missions no longer in
+      # the list are removed.  New missions receive a +next_run_at+ Time of now.
+      # 
       def update_plan(last_modified, missions)
         write_to_sqlite do |sqlite|
           begin
@@ -127,6 +152,16 @@ module ScoutAgent
         log.error("Database mission update locking error:  #{error.message}.")
       end
       
+      ################
+      ### Missions ###
+      ################
+      
+      # 
+      # Returns the current mission (+id+, +timeout+, +interval+, +last_run_at+,
+      # +name+, +code+, +options+, and +memory+) that should be run.  The
+      # +options+ and +memory+ fields are JSON parsed when possible.  If there
+      # are no missions scheduled to run at this time, +nil+ is returned.
+      # 
       def current_mission
         mission = read_from_sqlite { |sqlite|
           return nil unless plan = current_plan
@@ -159,6 +194,10 @@ module ScoutAgent
         nil  # not found
       end
       
+      # 
+      # Given a +mission_id+ and a +memory+ Hash, this method updates a
+      # mission's stored memory.
+      # 
       def update_mission_memory(mission_id, memory)
         write_to_sqlite do |sqlite|
           sqlite.execute(<<-END_UPDATE_MISSION.trim, memory.to_json, mission_id)
@@ -170,6 +209,10 @@ module ScoutAgent
         log.error("Database memory update error:  #{error.message}.")
       end
       
+      # 
+      # Marks +mission+ as complete in the database by recording its
+      # +last_run_at+ Time and setting a +next_run_at+ Time.
+      # 
       def complete_mission(mission)
         write_to_sqlite do |sqlite|
           run_time = Time.now
@@ -187,7 +230,12 @@ module ScoutAgent
         false  # warn the caller that the mission will still match
       end
       
+      # 
+      # All passed mission +ids+ are reset so they will be run again at the
+      # first available opportunity.
+      # 
       def reset_missions(*ids)
+        return if ids.empty?
         write_to_sqlite do |sqlite|
           sqlite.execute(<<-END_RESET_MISSIONS.trim, *ids)
           UPDATE missions
@@ -200,6 +248,38 @@ module ScoutAgent
         log.error("Database mission reset error:  #{error.message}.")
       end
       
+      # 
+      # Returns the number of seconds until another mission will be ready for
+      # running.  If the count would be zero or less seconds, the
+      # +DEFAULT_INTERVAL+ is returned (in seconds) to prevent the agent from
+      # entering a busy loop.
+      # 
+      def seconds_to_next_mission
+        default     = DEFAULT_INTERVAL * 60
+        next_run_at = read_from_sqlite { |sqlite|
+          sqlite.first_value_from(<<-END_FIND_MISSION.trim)
+          SELECT next_run_at FROM missions ORDER BY next_run_at LIMIT 1
+          END_FIND_MISSION
+        }
+        if next_run = Time.from_db_s(next_run_at)
+          seconds = next_run - Time.now
+          seconds > 0 ? seconds : default
+        else
+          default
+        end
+      rescue Amalgalite::SQLite3::Error => error  # failed to locate last run
+        log.error("Database next mission error:  #{error.message}.")
+        default  # use default
+      end
+      
+      ###############
+      ### Reports ###
+      ###############
+      
+      #
+      # Adds a report for +mission_id+ of +type+ with +fields+ to the database.
+      # Returns +true+ if the write succeeded, or +false+ if it did not.
+      # 
       def write_report(mission_id, type, fields)
         write_to_sqlite do |sqlite|
           params = [mission_id, type, fields.to_json]
@@ -213,8 +293,24 @@ module ScoutAgent
         false  # couldn't be written
       end
       
+      #
+      # This method returns an Array of all reports (+type+, +fields+,
+      # +created_at+, and +plugin_id+) that should be submitted to the Scout
+      # server.  The report +fields+ will be JSON parsed when possible and
+      # +created_at+ is converted to a proper Time object.
+      # 
+      # The act of reading these reports also triggers their removal from the
+      # database so we avoid sending duplicates to the server.  This does mean
+      # that we lose data if anything goes wrong in the sending process.  This
+      # is considered an acceptable risk, because even a
+      # delete-after-a-successful-send stragety is subject to duplication
+      # (the request might timeout but eventually complete on the server,
+      # for example).  If anything goes wrong with the reading or deletion,
+      # the entire process is canceled and an empty Array is returned.
+      # 
       def current_reports
         write_to_sqlite { |sqlite|
+          # read the current reports
           begin
             report_ids = Array.new
             reports    = query(<<-END_FIND_REPORTS.trim) { |row|
@@ -243,6 +339,7 @@ module ScoutAgent
             return Array.new  # return empty results
           end
           return reports if reports.empty?
+          # delete the reports we read
           begin
               sqlite.execute(<<-END_DELETE_REPORTS.trim, *report_ids)
               DELETE FROM reports
@@ -260,24 +357,6 @@ module ScoutAgent
         # try again to read reports later
         log.error("Database reports locking error:  #{error.message}.")
       end
-      
-      def seconds_to_next_mission
-        default     = DEFAULT_INTERVAL * 60
-        next_run_at = read_from_sqlite { |sqlite|
-          sqlite.first_value_from(<<-END_FIND_MISSION.trim)
-          SELECT next_run_at FROM missions ORDER BY next_run_at LIMIT 1
-          END_FIND_MISSION
-        }
-        if next_run = Time.from_db_s(next_run_at)
-          seconds = next_run - Time.now
-          seconds > 0 ? seconds : default
-        else
-          default
-        end
-      rescue Amalgalite::SQLite3::Error => error  # failed to locate last run
-        log.error("Database next mission error:  #{error.message}.")
-        default  # use default
-      end
     end
   end
 end

data/lib/scout_agent/database/queue.rb

@@ -3,10 +3,19 @@
 
 module ScoutAgent
   class Database
+    # 
+    # This database is used to stored messages queued from external processes.
+    # Such messages can be data for missions or full reports ready for
+    # submission to the Scout server.
+    # 
     class Queue < Database
       # A size limit for the queue to prevent data from building up.
       QUEUE_LIMIT = 3000
       
+      # 
+      # Builds a schema for the queue table.  This table is size controlled by a
+      # trigger to prevent infinite data growth.
+      # 
       def update_schema(version = schema_version)
         case version
         when 0
@@ -24,6 +33,14 @@ module ScoutAgent
         end
       end
       
+      #
+      # Adds a message to the queue.  The passed +mission_id+ needs to be an
+      # Integer ID for a mission or one of the Strings <tt>'report'</tt>,
+      # <tt>'hint'</tt>, <tt>'alert'</tt>, or <tt>'error'</tt> for a full
+      # report.  The +fields+ parameter is expected to be a Hash of fields and
+      # should include a <tt>'plugin_id'</tt> key identifying what the data is
+      # for when the message is a report for the server.
+      # 
       def enqueue(mission_id, fields)
         write_to_sqlite do |sqlite|
           sqlite.execute(<<-END_ENQUEUE.trim, mission_id, fields.to_json)
@@ -36,6 +53,12 @@ module ScoutAgent
         false  # reject bad message
       end
       
+      # 
+      # Returns a message (+id+, +fields+, and +created_at+) queued for
+      # +mission_id+.  The +fields+ are JSON parsed if possible and +created_at+
+      # is converted to a Time object.  This method will return +nil+ if no
+      # messages are queued for +mission_id+.
+      # 
       def peek(mission_id)
         queued = read_from_sqlite { |sqlite|
           sqlite.first_row_from(<<-END_FIND_QUEUED.trim, mission_id.to_s)
@@ -63,8 +86,16 @@ module ScoutAgent
         nil  # not found
       end
       
+      # 
+      # This method returns queued reports intended for the Scout server.
+      # 
+      # The process is pretty much identical to how mission generated reports
+      # are pulled.  See ScoutAgent::Database::MissionLog#current_reports() for
+      # details.
+      # 
       def queued_reports
         write_to_sqlite { |sqlite|
+          # read the current reports
           begin
             report_ids = Array.new
             reports    = query(<<-END_FIND_REPORTS.trim) { |row|
@@ -95,6 +126,7 @@ module ScoutAgent
             return Array.new  # return empty results
           end
           return reports if reports.empty?
+          # delete the reports we read
           unless dequeue(*report_ids)
             # cancel sending this batch
             sqlite.rollback   # we can't submit unless we're sure they are gone
@@ -107,7 +139,12 @@ module ScoutAgent
         log.error("Database queued reports locking error:  #{error.message}.")
       end
       
+      #
+      # Removes queued messages from the database by their +ids+.  Returns
+      # +true+ if the removal succeeded, or +false+ otherwise.
+      # 
       def dequeue(*ids)
+        return true if ids.empty?
         write_to_sqlite do |sqlite|
           sqlite.execute(<<-END_DELETE_QUEUED.trim, *ids)
           DELETE FROM queue WHERE ROWID IN (#{(['?'] * ids.size).join(', ')})

data/lib/scout_agent/database/snapshots.rb

@@ -3,6 +3,12 @@
 
 module ScoutAgent
   class Database
+    # 
+    # This database holds snapshot commands and results.  These commands are
+    # used as a way of recording the current state of the box the agent runs on.
+    # The results of these commands may help identify causes of problems
+    # reported by missions the agent runs.
+    # 
     class Snapshots < Database
       # A maximum time in seconds after which a command run is halted.
       DEFAULT_TIMEOUT  = 60
@@ -14,6 +20,11 @@ module ScoutAgent
       # A size limit for the runs table to prevent data from building up.
       RUNS_LIMIT       = 3000
       
+      # 
+      # Builds a schema for tables holding commands and the runs of those
+      # commands.  The runs table is size controlled via a trigger to prevent
+      # infinite data growth.
+      # 
       def update_schema(version = schema_version)
         case version
         when 0
@@ -39,7 +50,12 @@ module ScoutAgent
           END_INITIAL_SCHEMA
         end
       end
-
+      
+      #
+      # Updates the list of snapshot +commands+ in the database.  Existing
+      # commands are updated, new commands are added, and commands no longer in
+      # the list are deleted.
+      # 
       def update_commands(commands)
         write_to_sqlite do |sqlite|
           codes = commands.map { |m| m["code"] }
@@ -83,6 +99,11 @@ module ScoutAgent
         log.error("Database command update locking error:  #{error.message}.")
       end
       
+      #
+      # Returns all current commands (+id+, +timeout+, +interval+,
+      # +last_run_at+, and +code+) that should be executed as part of the
+      # current snapshot.  An empty Array is returned if no commands are found.
+      # 
       def current_commands
         query(<<-END_FIND_COMMANDS.trim, Time.now.to_db_s) { |row|
         SELECT   ROWID AS id, timeout, interval, last_run_at, code
@@ -96,6 +117,11 @@ module ScoutAgent
         Array.new  # return empty results
       end
       
+      # 
+      # Returns +true+ or +false+ to indicate if any commands are stored in the
+      # snapshot database.  If the database is inaccessible and the answer
+      # cannot be determined, +nil+ is returned.
+      # 
       def have_commands?
         read_from_sqlite { |sqlite|
           !!sqlite.first_value_from("SELECT ROWID FROM commands LIMIT 1")
@@ -105,8 +131,14 @@ module ScoutAgent
         nil  # commands not found
       end
       
+      # 
+      # Marks +command+ as just having run in the database and updates its
+      # +next_run_at+ Time.  A run is also created for the +command+ documenting
+      # its +output+, +exit_status+, +snapshot_at+ Time, and +run_time+.
+      # 
       def complete_run(command, output, exit_status, snapshot_at, run_time)
         write_to_sqlite do |sqlite|
+          # record run
           params = [ command[:code],
                      output,
                      exit_status,
@@ -123,6 +155,7 @@ module ScoutAgent
             log.error( "Database bad command run (#{command[:code]}) error:  " +
                        "#{error.message}." )
           end
+          # update command
           run_time = Time.now
           params   = [ run_time.to_db_s,
                        ( run_time +
@@ -143,8 +176,15 @@ module ScoutAgent
         log.error("Database complete command locking error:  #{error.message}.")
       end
       
+      # 
+      # This method returns command runs intended for the Scout server.
+      # 
+      # The process is very similar to how mission generated reports are pulled.
+      # See ScoutAgent::Database::MissionLog#current_reports() for details.
+      # 
       def current_runs
         write_to_sqlite { |sqlite|
+          # read the current runs
           begin
             run_ids = Array.new
             runs    = query(<<-END_FIND_RUNS.trim) { |row|
@@ -166,6 +206,7 @@ module ScoutAgent
             return Array.new  # return empty results
           end
           return runs if runs.empty?
+          # delete the runs we read
           begin
             sqlite.execute(<<-END_DELETE_RUNS.trim, *run_ids)
             DELETE FROM runs

data/lib/scout_agent/database/statuses.rb

@@ -3,7 +3,13 @@
 
 module ScoutAgent
   class Database
+    # 
+    # This small database keeps track of the current status of all running
+    # processes withing the agent.  This allows tracking of process function
+    # (represented as the process name), ID, and current task.
+    # 
     class Statuses < Database
+      # Builds a schema for the process statuses table.
       def update_schema(version = schema_version)
         case version
         when 0
@@ -21,6 +27,11 @@ module ScoutAgent
         end
       end
       
+      # 
+      # Record the current +status+ for the calling process.  The process ID is
+      # determined with <tt>Process::pid()</tt> and +name+ is pulled from
+      # <tt>IDCard::me()#process_name()</tt> when available.
+      # 
       def update_status(status, name = IDCard.me && IDCard.me.process_name)
         write_to_sqlite do |sqlite|
           sqlite.execute(<<-END_UPDATE_STATUS.trim, name, Process.pid, status)
@@ -33,6 +44,11 @@ module ScoutAgent
         log.error("Database status update error:  #{error.message}.")
       end
       
+      #
+      # Removes the status record for +name+ (pulled from
+      # <tt>IDCard::me()#process_name()</tt> by default).  This is generally
+      # done by processes in an <tt>at_exit()</tt> block.
+      # 
       def clear_status(name = IDCard.me && IDCard.me.process_name)
         write_to_sqlite do |sqlite|
           sqlite.execute("DELETE FROM statuses WHERE name = ?", name)
@@ -42,6 +58,11 @@ module ScoutAgent
         log.error("Database status clearing error:  #{error.message}.")
       end
       
+      # 
+      # Returns the current statuses (+name+, +pid+, +status+,
+      # and +last_updated_at+) for all known processes.  An empty Array is
+      # returned if no processes are currently active.
+      # 
       def current_statuses
         query(<<-END_FIND_STATUSES.trim)
         SELECT name, pid, status, last_updated_at FROM statuses ORDER BY ROWID
@@ -51,6 +72,10 @@ module ScoutAgent
         Array.new  # return empty results
       end
       
+      # 
+      # Returns the current +status+ message for +name+ (pulled from
+      # <tt>IDCard::me()#process_name()</tt> by default).
+      # 
       def current_status(name = IDCard.me && IDCard.me.process_name)
         read_from_sqlite { |sqlite|
           sqlite.first_value_from(<<-END_FIND_STATUS, name)

data/lib/scout_agent/dispatcher.rb

@@ -32,6 +32,10 @@ module ScoutAgent
                  "The URL for the server to report to." ) do |url|
           switches[:server_url] = url
         end
+        opts.on( "-p", "--proxy URL", String,
+                 "A proxy URL to pass HTTP requests through." ) do |url|
+          switches[:proxy_url] = url
+        end
         opts.on( "-d", "--[no-]daemon",
                  "Run in the background as a daemon." ) do |boolean|
           switches[:run_as_daemon] = boolean

data/lib/scout_agent/id_card.rb

@@ -41,16 +41,17 @@ module ScoutAgent
       Plan.pid_dir + "#{@process_name}.pid"
     end
     
-    # Returns the PID for the named process, or +nil+ if it cannot be read.
+    # Returns the PID for the named process or +nil+ if it cannot be read.
     def pid
       pid_file.read.to_i
-    rescue Exception
+    rescue Exception  # cannot read file
       nil
     end
     
     # 
     # Tries to send +message+ as a signal to the process represented by this
-    # instance.  You can pass any message Process.kill() would understand.
+    # instance.  You can pass any message <tt>Process.kill()</tt> would
+    # understand.
     # 
     # Returns +true+ if the signal was sent, or +false+ if the PID file could
     # not be read.  Any Exception raised during the send, such as Errno::ESRCH
@@ -71,9 +72,9 @@ module ScoutAgent
     # stale claims are ignored and replaced, if possible.
     # 
     # This method returns +true+ in the claim succeeded and +false+ if it could
-    # not happen for any reason.  A return of +true+ indicates that me() has
-    # been updated and an exit handle has been installed to revoke() this claim
-    # as the process ends.
+    # not happen for any reason.  A return of +true+ indicates that
+    # <tt>IDCard::me()</tt> has been updated and an exit handle has been
+    # installed to revoke() this claim as the process ends.
     # 
     def authorize
       File.open(pid_file, File::CREAT | File::EXCL | File::WRONLY) do |pid|
@@ -91,9 +92,7 @@ module ScoutAgent
       self.class.me = self
       
       at_my_exit do
-        unless revoke
-          # log.error "Unable to unlink pid file:  #{$!.message}" if log
-        end
+        revoke
       end
       true
     rescue Errno::EEXIST  # pid_file already exists
@@ -101,32 +100,24 @@ module ScoutAgent
         if pid.flock(File::LOCK_EX | File::LOCK_NB)
           if pid.read =~ /\A\d+/
             begin
-              unless signal(0)
-                # log.warn "Could not create or read PID file.  "                +
-                #          "You may need to the path to the config directory.  " +
-                #          "See:  http://scoutapp.com/help#data_file" if log
-              end
+              signal(0)  # check for the existing process
             rescue Errno::ESRCH  # no such process
-              # log.info "Stale PID file found.  Clearing it and reloading..." if log
+              # stale PID file found, clearing it and reloading
               if revoke
                 pid.flock(File::LOCK_UN)  # release the lock before we recurse
                 return authorize          # try again
-              else
-                # log.info "Failed to clear PID." if log
               end
             rescue Errno::EACCES  # don't have permission
               # nothing we can do so give up
             end
-          else
-            # nothing we can do so give up
           end
           pid.flock(File::LOCK_UN)  # release the lock
         else
-          # log.info "Couldn't grab a file lock to verify existing PID file." if log
+          # couldn't grab a file lock to verify existing PID file
           return false
         end
       end
-      # log.warn "Process #{pid} was already running" if log
+      # process was already running
       false
     end
     

data/lib/scout_agent/order.rb

@@ -28,16 +28,22 @@ module ScoutAgent
       subclasses
     end
     
-    def self.can_handle?(message)
+    def self.can_handle?(message, modified_body = nil)
       subclasses.each do |order|
-        if match_details = order.match?(message)
+        if match_details = order.match?(message, modified_body)
           return order.new(message, match_details)
         end
       end
+      nil
     end
     
-    def self.match?(message)
-      const_defined?(:MATCH_RE) and const_get(:MATCH_RE).match(message.body)
+    def self.match?(message, modified_body = nil)
+      const_defined?(:MATCH_RE) and
+      const_get(:MATCH_RE).match(modified_body || message.body)
+    end
+      
+    def self.master_agent
+      @master_agent ||= IDCard.new(:master)
     end
     
     def initialize(message, match_details)
@@ -55,5 +61,12 @@ module ScoutAgent
       raise NotImplementedError,
             "Subclasses must override ScoutAgent::Order#execute()."
     end
+    
+    def notify_master
+      self.class.master_agent.signal("ALRM")
+    rescue Exception  # unable to signal process
+      # do nothing:  process will catch up when it restarts
+      log.warn("Unable to signal master process.")
+    end
   end
 end

data/lib/scout_agent/order/check_in_order.rb

@@ -15,19 +15,23 @@ module ScoutAgent
         @mission_log = db
       end
       
-      def self.master_agent
-        @master_agent ||= IDCard.new(:master)
-      end
-      
       def execute
         if id_str = match_details.captures.first
           ids = id_str.scan(/\d+/).map { |n| n.to_i }
           unless ids.empty?
-            self.class.mission_log.reset_missions(ids)
+            s       = ids.size == 1 ? "" : "s"
+            ids_str = case ids.size
+                      when 1 then ids.first.to_s
+                      when 2 then ids.join(" and ")
+                      else        ids[0..-2].join(", ") + ", and #{ids.last}"
+                      end
+            log.info("Clearing wait time#{s} for mission#{s} (#{ids_str}).")
+            self.class.mission_log.reset_missions(*ids)
           end
         end
-        self.class.master_agent.signal("ALRM")
+        log.info("Requesting an immediate check-in.")
+        notify_master
       end
     end
   end
-end
+end

data/lib/scout_agent/order/snapshot_order.rb

@@ -4,30 +4,12 @@
 module ScoutAgent
   class Order
     class SnapshotOrder < Order
-      MATCH_RE = /\A\s*snap[-_]?shot(?:\s+(.+?))?\s*\z/
-      
-      def self.snapshots
-        return @snapshots if defined? @snapshots
-        unless db = Database.load(:snapshots, log)
-          log.fatal("Could not load snapshots database.")
-          exit
-        end
-        @snapshots = db
-      end
-      
-      def self.master_agent
-        @master_agent ||= IDCard.new(:master)
-      end
+      MATCH_RE = /\A\s*snap[-_]?shot\s*\z/
       
       def execute
-        # if id_str = match_details.captures.first
-        #   ids = id_str.scan(/\d+/).map { |n| n.to_i }
-        #   unless ids.empty?
-        #     self.class.mission_log.reset_missions(ids)
-        #   end
-        # end
+        log.info("Requesting that a snapshot be taken.")
         API.take_snapshot
-        self.class.master_agent.signal("ALRM")
+        notify_master
       end
     end
   end

data/lib/scout_agent/plan.rb

@@ -18,6 +18,7 @@ module ScoutAgent
     # The default configuration for this agent.
     def defaults
       [ [:server_url,     "http://beta.scoutapp.com:3000"],
+        [:proxy_url,      nil],
         [:run_as_daemon,  true],
         [:logging_level,  "INFO"],
         [:test_mode,      false],
@@ -37,7 +38,9 @@ module ScoutAgent
     
     # This method is used to set or reset the default configuration.
     def set_defaults
-      defaults.each { |name, value| send("#{name}=", value) }
+      defaults.each do |name, value|
+        send("#{name}=", value)
+      end
     end
     alias_method :reset_defaults, :set_defaults
     
@@ -74,6 +77,7 @@ module ScoutAgent
       config_file.open(File::CREAT|File::EXCL|File::WRONLY) do |pid|
         pid.puts <<-END_DEFAULT_CONFIG.trim
         #!/usr/bin/env ruby -wKU
+        # encoding: UTF-8
 
         # 
         # This file configures #{ScoutAgent.proper_agent_name}.  The settings in
@@ -92,6 +96,12 @@ module ScoutAgent
         
         # The following is the URL used to reach the server:
         config.server_url = #{server_url.inspect}
+        # 
+        # Set the following if your HTTP requests need to go through a proxy.
+        # All non-XMPP requests between the agent and the server will go through
+        # this URL.
+        # 
+        config.proxy_url = #{proxy_url.inspect}
         
         # 
         # When the following is true, the agent will disconnect from the
@@ -139,8 +149,8 @@ module ScoutAgent
         # Note:  to have the prefix effect the location of this file or
         # to set your OS's configuration path, you will need to use 
         # command-line switches (--prefix and --os-config-path respectively).
-        # It wouldn't help to have those settings in this file, for obvious
-        # reasons.
+        # It wouldn't help to have those settings in this file as they are
+        # needed before this file is loaded.
         # 
         config.prefix_path = #{prefix_path.to_s.inspect}
         
@@ -161,11 +171,11 @@ module ScoutAgent
         # try to switch to.  Choices are tried from left to right, so by
         # default the "daemon" user is used but the agent will try
         # "nobody" if daemon is not available.  These are standard users
-        # and groups for processes like this that run on Unix.
+        # and groups for long running processes on Unix.
         # 
         # If you wish to improve security even more, we recommend creating
         # a user and group called "#{ScoutAgent.agent_name}" and replacing these 
-        # defaults with what you created.  This puts you full control
+        # defaults with what you created.  This puts you in full control
         # of what the agent will have access to on your system and makes
         # it easier to track what the agent is doing.
         # 
@@ -193,7 +203,9 @@ module ScoutAgent
     
     # This method allows mass update through a +hash+ of settings.
     def update_from_switches(hash)
-      hash.each { |name, value| send("#{name}=", value) }
+      hash.each do |name, value|
+        send("#{name}=", value)
+      end
     end
     alias_method :update_from_hash, :update_from_switches
     
@@ -211,9 +223,9 @@ module ScoutAgent
     # These paths prefix all of the specific application paths.
     # 
     %w[os_config_path os_db_path os_pid_path os_log_path].each do |path|
-      define_method(path) do
+      define_method(path) {
         prefix_path + super()
-      end
+      }
     end
     
     # 
@@ -230,9 +242,9 @@ module ScoutAgent
     # are named after the agent.
     # 
     %w[db pid log].each do |path|
-      define_method("#{path}_dir") do
+      define_method("#{path}_dir") {
         send("os_#{path}_path") + (super() || ScoutAgent.agent_name)
-      end
+      }
     end
     
     # 
@@ -243,7 +255,7 @@ module ScoutAgent
     { :db_dir  => 0777,
       :pid_dir => 0775,
       :log_dir => 0777 }.each do |path, permissions|
-      define_method("build_#{path}") do |group_id|
+      define_method("build_#{path}") { |group_id|
         begin
           send(path).mkpath
           send(path).chown(nil, group_id)
@@ -252,13 +264,17 @@ module ScoutAgent
         rescue Errno::EACCES, Errno::EPERM   # don't have permission
           false
         end
-      end
+      }
     end
     
     #############
     ### URL's ###
     #############
     
+    #
+    # Returns the full URL for check-ins by this agent.  This is the
+    # +server_url+ plus the agent path and the key specific to this agent.
+    # 
     def agent_url
       URI.join(server_url, "clients/#{agent_key}")
     end
@@ -267,6 +283,12 @@ module ScoutAgent
     ### Databases ###
     #################
     
+    #
+    # This method is used to prepare a database that can be accessed by any
+    # process.  The database is first loaded by +name+.  Then the permissions
+    # on that database are changed to allow all processes to read and write to
+    # the created database.
+    # 
     def prepare_global_database(name)
       db = Database.load(name) or return false
       db.path.chmod(0777)

data/lib/scout_agent/server.rb

@@ -18,6 +18,8 @@ module ScoutAgent
         :headers => { :client_version   => ScoutAgent::VERSION,
                       :accept_encoding  => "gzip" }
       )
+      # make sure proxy is set, if needed
+      RestClient.proxy = Plan.proxy_url
     end
     
     # The log connection notes will be written to.
@@ -40,13 +42,8 @@ module ScoutAgent
       log.warn("Plan was malformed zipped data.")
       ""  # replace bad plan with empty plan
     rescue RestClient::RequestFailed => error  # RestClient bug workaround
-      # all success codes are OK, but other codes are not
-      if error.http_code.between? 200, 299
-        error.response.body  # the returned plan
-      else
-        log.warn("Plan was returned as a failure code:  #{error.http_code}.")
-        nil  # failed to retrieve plan
-      end
+      log.warn("Plan was returned as a failure code:  #{error.http_code}.")
+      nil  # failed to retrieve plan
     rescue RestClient::NotModified
       log.info("Plan was not modified.")
       ""  # empty plan
@@ -61,7 +58,7 @@ module ScoutAgent
     # as much as possible.
     # 
     # If the ckeck-in succeeds, +true+ is returned.  However, +false+ doesn't
-    # ensure that we failed.  RestClient may time out a long connection attempt,
+    # ensure that we failed.  RestClient may timeout a long connection attempt,
     # but the server may still complete it eventually.
     # 
     def post_checkin(data)

data/lib/scout_agent/tracked.rb

@@ -38,7 +38,7 @@ module ScoutAgent
     #   status(status, name = IDCard.me && IDCard.me.process_name)
     # 
     # Sets the +status+ of this process.  You can pass +name+ explicitly if it
-    # cannot be properly determined from <tt>IDCard.me()</tt>.
+    # cannot be properly determined from <tt>IDCard::me()#process_name()</tt>.
     # 
     def status(*args)
       status_database.update_status(*args) if status_database
@@ -51,7 +51,7 @@ module ScoutAgent
     # Clears any status currently set for this process.  This should be called
     # for any process setting status messages <tt>at_exit()</tt>.  You can pass
     # +name+ explicitly if it cannot be properly determined from
-    # <tt>IDCard.me()</tt>.
+    # <tt>IDCard::me()#process_name()</tt>.
     # 
     def clear_status(*args)
       status_database.clear_status(*args) if status_database

data/test/tc_plan.rb

@@ -99,7 +99,7 @@ class TestPlan < Test::Unit::TestCase
   end
   
   def test_server_url_is_set
-    assert_match(%r{\Ahttps://}, plan.server_url)
+    assert_match(%r{\Ahttps?://}, plan.server_url)
   end
   
   def test_run_as_daemon_is_set

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: scout_agent
 version: !ruby/object:Gem::Version 
-  version: 3.0.3
+  version: 3.0.4
 platform: ruby
 authors: 
 - James Edward Gray II
@@ -12,7 +12,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-06 00:00:00 -05:00
+date: 2009-04-13 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -23,7 +23,7 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        version: 4.7.2
+        version: 4.7.3
     version: 
 - !ruby/object:Gem::Dependency 
   name: amalgalite