scout_agent 3.0.7 → 3.1.0

data/lib/scout_agent/mission.rb

@@ -2,20 +2,35 @@
 # encoding: UTF-8
 
 module ScoutAgent
+  #
+  # These objects are the data gathers periodically run by the agent.  To gather
+  # a new type of data, you inherit from this Class and provide a build_report()
+  # method that calls some combination of report(), alert(), and error() to send
+  # data to the Scout server.
+  # 
   class Mission
-    class << self
-      attr_reader :prepared
+    # 
+    # This method returns the last Mission subclass that was loaded.  The
+    # Mission runner uses this after compiling Mission code to get the newly
+    # loaded object.
+    # 
+    def self.prepared
+      @prepared ||= nil
     end
-
-    def self.inherited(new_plugin)
-      @prepared = new_plugin
+    
+    # 
+    # Hooks into Ruby's Class loading process so we can keep track of the last
+    # loaded subclass.
+    # 
+    def self.inherited(new_mission)
+      @prepared = new_mission
     end
     
     # 
-    # You can use this method to indicate one or more libraries your plugin
+    # You can use this method to indicate one or more libraries your Mission
     # requires:
     # 
-    #   class MyNeedyPlugin < Scout::Plugin
+    #   class MyNeedyPlugin < ScoutAgent::Mission
     #     needs "faster_csv", "elif"
     #     # ...
     #   end
@@ -25,13 +40,18 @@ module ScoutAgent
     # 
     def self.needs(*libraries)
       if libraries.empty?
-        @needs ||= [ ]
+        @needs ||= Array.new
       else
         needs.push(*libraries.flatten)
       end
     end
 
-    # Creates a new Scout Plugin to run.
+    # 
+    # Creates a new Scout Mission to run.  It requires the +id+ and +name+ for
+    # the Mission as well as the +last_run+ Time, +memory+, and +options+ from
+    # the Mission database.  You may optionally provide a +log+ for the Mission
+    # to write messages to.
+    # 
     def initialize(id, name, last_run, memory, options, log = WireTap.new(nil))
       @id             = id
       @name           = name
@@ -43,77 +63,145 @@ module ScoutAgent
       @queue_db       = !testing? && Database.load(:queue,       @log)
     end
     
+    # 
+    # The numerical ID this Mission is known by to the Scout server.  This is
+    # <tt>:testing</tt> for a Mission running in the agent's test mode.
+    # 
+    attr_reader :id
+    # The human readable name of this Mission.
+    attr_reader :name
+    # The last run Time for this Mission.  Can be +nil+ for new Missions.
     attr_reader :last_run
+    # The log file this Mission is allowed to append messages to.
     attr_reader :log
+    # A common alias used in Rails code.
     alias_method :logger, :log
     
+    # 
+    # Returns +true+ if this Mission is currently being run in the agent's test
+    # mode.
+    # 
     def testing?
       @id == :testing
     end
     
+    #
+    # Fetches an option passed to this Mission from the Web interface by +name+.
+    # If a direct lookup fails, it will be attempted again after converting a
+    # String +name+ to a Symbol or any other +name+ to a String.  This makes the
+    # lookups feel familiar to HashWithIndifferentAccess fans.
+    # 
     def option(name)
       @options[name] ||
       @options[name.is_a?(String) ? name.to_sym : String(name)]
     end
-
-    # Builds the data to send to the server.
+    
     #
-    # We programatically define several helper methods for creating this data.
+    # This method returns an Array of the reports that will be saved to the
+    # database at the end of this execution.  It can be used to edit reports
+    # you have already entered.
     # 
-    # Usage:
+    def reports
+      data_for_server[:reports]
+    end
+    
+    #
+    # This method adds a +new_report+ that will be saved to the database at the
+    # end of the current Mission run.  The passed +new_report+ should be a Hash
+    # of the data values you wish to track.
     # 
-    #   reports << {:data => "here"}
-    #   report(:data => "here")
-    #   add_report(:data => "here")
+    def report(new_report)
+      reports << new_report
+    end
+    # Another way to add reports.
+    alias_method :add_report, :report
+    
+    #
+    # This method returns an Array of the hints that will be saved to the
+    # database at the end of this execution.  It can be used to edit hints you
+    # have already entered.
     # 
-    #   alerts << {:subject => "subject", :body => "body"}
-    #   alert("subject", "body")
-    #   alert(:subject => "subject", :body => "body")
-    #   add_alert("subject", "body")
-    #   add_alert(:subject => "subject", :body => "body")
+    def hints
+      data_for_server[:hints]
+    end
+    
+    #
+    # This method adds a +new_hint+ that will be saved to the database at the
+    # end of the current Mission run.  The passed +new_hint+ should be a Hash of
+    # the data values you wish to track.
     # 
-    #   errors << {:subject => "subject", :body => "body"}
-    #   error("subject", "body")
-    #   error(:subject => "subject", :body => "body")
-    #   add_error("subject", "body")
-    #   add_error(:subject => "subject", :body => "body")
-    #     
-    def data_for_server
-      @data_for_server ||= { :reports => [ ],
-                             :hints   => [ ],
-                             :alerts  => [ ],
-                             :errors  => [ ],
-                             :memory  => { } }
+    def hint(new_hint)
+      hints << new_hint
     end
+    # Another way to add hints.
+    alias_method :add_hint, :hint
     
-    %w[report hint alert error].each do |kind|
-      class_eval <<-END
-        def #{kind}s
-          data_for_server[:#{kind}s]
-        end
-        
-        if %w[report hint].include? "#{kind}"
-          def #{kind}(new_entry)
-            #{kind}s << new_entry
-          end
-        else
-          def #{kind}(*fields)
-            #{kind}s << ( fields.first.is_a?(Hash) ?
-                          fields.first :
-                          {:subject => fields.first, :body => fields.last} )
-          end
-        end
-        alias_method :add_#{kind}, :#{kind}
-      END
+    #
+    # This method returns an Array of the alerts that will be saved to the
+    # database at the end of this execution.  It can be used to edit alerts you
+    # have already entered.
+    # 
+    def alerts
+      data_for_server[:alerts]
     end
     
     #
-    # Usage:
+    # :call-seq:
+    #   alert(subject, body)
+    #   alert(new_alert)
     # 
-    #   memory(:no_track)
-    #   memory.delete(:no_track)
+    # This method adds an alert that will be saved to the database at the end of
+    # the current Mission run.  You can pass the +subject+ and +body+ of the
+    # generated alert separately, or a Hash containing <tt>:subject</tt> and
+    # <tt>:body</tt> values for the +new_alert+.
+    # 
+    def alert(*new_alert)
+      alerts << build_alert_or_error(new_alert)
+    end
+    # Another way to add alerts.
+    alias_method :add_alert, :alert
+    
+    #
+    # This method returns an Array of the errors that will be saved to the
+    # database at the end of this execution.  It can be used to edit errors you
+    # have already entered.
+    # 
+    def errors
+      data_for_server[:errors]
+    end
+    
+    #
+    # :call-seq:
+    #   error(subject, body)
+    #   error(new_error)
+    # 
+    # This method adds an error that will be saved to the database at the end of
+    # the current Mission run.  You can pass the +subject+ and +body+ of the
+    # generated error separately, or a Hash containing <tt>:subject</tt> and
+    # <tt>:body</tt> values for the +new_error+.
+    # 
+    def error(*new_error)
+      errors << build_alert_or_error(new_error)
+    end
+    # Another way to add errors.
+    alias_method :add_error, :error
+    
+    #
+    # :call-seq:
+    #   memory(name)
+    #   memory.delete(name)
     #   memory.clear
     # 
+    # The primary usage of this method is to fetch values saved into the Mission
+    # memory during a previous execution by +name+.  The +name+ lookup rules are
+    # The same as those decribed in the option() method, so you can use String
+    # and Symbol keys interchangeably.
+    # 
+    # When called without a +name+, this method returns a Hash of <b>the
+    # current</b> Mission memory (not the remembered values from the previous
+    # execution).  This is mainly helpful if you want to edit the values you
+    # have added to be saved during this run.
+    # 
     def memory(name = nil)
       if name.nil?
         data_for_server[:memory]
@@ -124,20 +212,46 @@ module ScoutAgent
     end
     
     #
-    # Usage:
+    # :call-seq:
+    #   remember(name, value)
+    #   remember(name1, value1, name2, value2, ...)
+    #   remember(name => value)
+    #   remember(name1 => value1, name2 => value2, ...)
+    #   remember(name1, value1, ..., name2 => value2, ...)
     # 
-    #   remember(:name, value)
-    #   remember(:name1, value1, :name2, value2)
-    #   remember(:name => value)
-    #   remember(:name1 => value1, :name2 => value2)
-    #   remember(:name1, value1, :name2 => value2)
+    # Adds all +name+ and +value+ pairs into the Mission memory that will be
+    # saved from the current execution.
+    # 
+    # It's important to note that Mission memory is not automatically copied
+    # from the previous executions, so you must call this method during each
+    # execution if you need to keep saving a value.
     # 
     def remember(*args)
+      # divide Hash and non-Hash arguments
       hashes, other = args.partition { |value| value.is_a? Hash }
-      hashes.each { |hash| memory.merge!(hash) }
-      (0...other.size).step(2) { |i| memory.merge!(other[i] => other[i + 1]) }
+      # merge all Hash arguments into the Mission memory
+      hashes.each do |hash|
+        memory.merge!(hash)
+      end
+      # merge all non-Hash arguments into the Mission memory
+      (0...other.size).step(2) do |i|
+        memory.merge!(other[i] => other[i + 1])
+      end
     end
     
+    #
+    # This method iterates over messages that have been queued from an external
+    # source for your Mission.  Each message (the restored Ruby representation
+    # of the JSON data passed to the queue command) will be passed into your 
+    # +block+ one by one.  If your block accepts more than one argument, you
+    # will also be passed queue Times with the messages.  The act of reading
+    # these messages removes them from the database so the current Mission
+    # should be used to pass them to the server as meaningful data or save them
+    # to Mission memory for later use.
+    # 
+    # When a Mission is running in test mode, queued messages are read from
+    # <tt>options(:\_\_queue\_\_)</tt> and queue Times are simply <tt>Time.now</tt>.
+    # 
     def each_queued_message(&block)
       if testing?
         Array(option(:__queue__)).each do |message|
@@ -160,6 +274,10 @@ module ScoutAgent
     end
     
     #
+    # This method is the wrapper over Scout's older interface for Mission (then
+    # called a Plugin) execution.  It hands off to the newer build_report(),
+    # then records the results of that run.
+    # 
     # Old plugins will work because they override this method.  New plugins can
     # now leave this method in place, add a build_report() method instead, and
     # use the new helper methods to build up content inside which will
@@ -192,13 +310,15 @@ module ScoutAgent
       write_reports_and_update_memory
     end
     
+    #######
     private
+    #######
     
     #
-    # Returns true is a library can be loaded.  A bare require is made as the
-    # first attempt.  If that fails, RubyGems is loaded and another attempt is
-    # made.  If the library cannot be loaded either way, an error() is generated
-    # and build_report() will not be called.
+    # Returns +true+ if a library can be loaded.  A bare require() is made as
+    # the first attempt.  If that fails, RubyGems is loaded and another attempt
+    # is made.  If the library cannot be loaded either way, an error() is
+    # generated and build_report() will not be called.
     # 
     def library_available?(library)
       begin
@@ -214,7 +334,40 @@ module ScoutAgent
       end
       true
     end
+
+    # 
+    # Builds the data to send to the server.  The public interface to this data
+    # lives in the helper methods:  reports(), report(), add_report(), hints(),
+    # hint(), add_hint(), alerts(), alert(), add_alert(), errors(), error(), and
+    # add_error().
+    #     
+    def data_for_server
+      @data_for_server ||= { :reports => Array.new,
+                             :hints   => Array.new,
+                             :alerts  => Array.new,
+                             :errors  => Array.new,
+                             :memory  => Hash.new }
+    end
     
+    #
+    # Builds a new alert or error Hash either by passing a Hash directly through
+    # or by grabbing a subject and body out of an Array of arguments.
+    # 
+    def build_alert_or_error(new_alert_or_error)
+      if new_alert_or_error.first.is_a? Hash
+        new_alert_or_error
+      else
+        {:subject => new_alert_or_error.first, :body => new_alert_or_error.last}
+      end
+    end
+    
+    #
+    # Writes generated reports and such to both the Mission database and the
+    # log().  The Mission memory will also be updated with the values stored
+    # from the execution that has just finished.
+    # 
+    # Both database writes are skipped when running in the agent's test mode.
+    # 
     def write_reports_and_update_memory
       %w[report hint alert error].each do |type|
         Array(send("#{type}s")).each do |fields|
@@ -228,6 +381,6 @@ module ScoutAgent
     end
   end
   
-  # An external alias.
+  # An alias to support older plugins.
   Plugin = Mission
 end

data/lib/scout_agent/order.rb

@@ -32,8 +32,8 @@ module ScoutAgent
     end
     
     # 
-    # Hooks into Ruby's class load process so we can notice subclasses as they
-    # are loaded.
+    # Hooks into Ruby's Class loading process so we can notice subclasses as
+    # they are loaded.
     # 
     def self.inherited(order)
       subclasses << order

data/lib/scout_agent/plan.rb

@@ -3,14 +3,17 @@
 
 module ScoutAgent
   #
-  # This constant holds all global configuration for the agent.  There's only
-  # this one instance of this data and all systems share it.  This data is
-  # configured at startup and should never again change without a restart.
+  # These extra methods are mixed into the OpenStruct stored in
+  # ScoutAgent::Plan.  They add support for defaults, some interface
+  # improvements, support for configuration files and command-line switches,
+  # plus validation.
   # 
-  # Users are free to add to this configuration as need (via their configuration
-  # file) and make use of those new values in their plugins.
+  # To see the options stored in the plan and their current values, use the
+  # following command:
   # 
-  class << Plan = OpenStruct.new
+  #   scout_agent config
+  # 
+  module Planned
     ################
     ### Defaults ###
     ################
@@ -39,31 +42,44 @@ module ScoutAgent
         [:log_dir,            nil] ]
     end
     
-    # This method is used to set or reset the default configuration.
+    # 
+    # This method is used to set or reset the default configuration.  It returns
+    # +self+ to support method chaining.
+    # 
     def set_defaults
       defaults.each do |name, value|
         send("#{name}=", value)
       end
+      self  # for chaining
     end
     alias_method :reset_defaults, :set_defaults
     
-    # Provide a more natural interface for a boolean flag.
-    def run_as_daemon?  # can't use alias_method() because it's not defined
+    #
+    # --
+    # 
+    # The following interface enhancements cannot use alias_method() because the
+    # underlying method are not defined in OpenStruct until their first use.
+    # 
+    # ++
+    # 
+    
+    # Provide a more natural interface for ScoutAgent::Plan#run_as_daemon.
+    def run_as_daemon?
       run_as_daemon
     end
     
-    # Provide a more natural interface for a boolean flag.
-    def test_mode?  # can't use alias_method() because it's not defined
+    # Provide a more natural interface for ScoutAgent::Plan#test_mode.
+    def test_mode?
       test_mode
     end
     
-    # Provide a more natural interface for a boolean flag.
-    def enable_xmpp?  # can't use alias_method() because it's not defined
+    # Provide a more natural interface for ScoutAgent::Plan#enable_xmpp.
+    def enable_xmpp?
       enable_xmpp
     end
     
-    # Provide a more natural interface for a boolean flag.
-    def periodic_snapshots?  # can't use alias_method() because it's not defined
+    # Provide a more natural interface for ScoutAgent::Plan#periodic_snapshots.
+    def periodic_snapshots?
       periodic_snapshots
     end
     
@@ -386,9 +402,13 @@ module ScoutAgent
     end
   end
   
+  #
+  # This constant holds all global configuration for the agent.  There's only
+  # this one instance of this data and all systems share it.  This data is
+  # configured at startup and should never again change without a restart.
   # 
-  # Set the defaults after we have overriden some accessors, to keep OpenStruct
-  # from replacing them.
+  # Users are free to add to this configuration as need (via their configuration
+  # file) and make use of those new values in their plugins.
   # 
-  Plan.set_defaults
+  Plan = OpenStruct.new.extend(Planned).set_defaults
 end