scout_agent 3.0.0

data/lib/scout_agent/mission.rb

@@ -0,0 +1,212 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  class Mission
+    class << self
+      attr_reader :prepared
+    end
+
+    def self.inherited(new_plugin)
+      @prepared = new_plugin
+    end
+    
+    # 
+    # You can use this method to indicate one or more libraries your plugin
+    # requires:
+    # 
+    #   class MyNeedyPlugin < Scout::Plugin
+    #     needs "faster_csv", "elif"
+    #     # ...
+    #   end
+    # 
+    # Your build_report() method will not be called if all libraries cannot
+    # be loaded.  RubyGems will be loaded if needed to find the libraries.
+    # 
+    def self.needs(*libraries)
+      if libraries.empty?
+        @needs ||= [ ]
+      else
+        needs.push(*libraries.flatten)
+      end
+    end
+
+    # Creates a new Scout Plugin to run.
+    def initialize(id, name, last_run, memory, options)
+      @id             = id
+      @name           = name
+      @last_run       = last_run
+      @memory         = memory
+      @options        = options
+      @mission_log_db = Database.load(:mission_log)
+      @queue_db       = Database.load(:queue)
+    end
+    
+    attr_reader :last_run
+    
+    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.
+    # 
+    # Usage:
+    # 
+    #   reports << {:data => "here"}
+    #   report(:data => "here")
+    #   add_report(:data => "here")
+    # 
+    #   alerts << {:subject => "subject", :body => "body"}
+    #   alert("subject", "body")
+    #   alert(:subject => "subject", :body => "body")
+    #   add_alert("subject", "body")
+    #   add_alert(:subject => "subject", :body => "body")
+    # 
+    #   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  => { } }
+    end
+    
+    %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
+    end
+    
+    #
+    # Usage:
+    # 
+    #   memory(:no_track)
+    #   memory.delete(:no_track)
+    #   memory.clear
+    # 
+    def memory(name = nil)
+      if name.nil?
+        data_for_server[:memory]
+      else
+        @memory[name] ||
+        @memory[name.is_a?(String) ? name.to_sym : String(name)]
+      end
+    end
+    
+    #
+    # Usage:
+    # 
+    #   remember(:name, value)
+    #   remember(:name1, value1, :name2, value2)
+    #   remember(:name => value)
+    #   remember(:name1 => value1, :name2 => value2)
+    #   remember(:name1, value1, :name2 => value2)
+    # 
+    def remember(*args)
+      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]) }
+    end
+    
+    def each_queued_message(&block)
+      while message = @queue_db.peek(@id)
+        if block.arity == 1
+          block[message[:fields]]
+        else
+          block[message[:fields], message[:created_at]]
+        end
+        @queue_db.dequeue(message[:id]) or return # prevent infinite loop
+      end
+    end
+    
+    #
+    # 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
+    # automatically be returned as the end result of the run.
+    # 
+    def run
+      # 
+      # run the plugin in a new Thread so signals will be handled in the main
+      # Thread and not accidentally caught by rescue clauses in the body of the
+      # mission
+      # 
+      Thread.new do
+        Thread.current.abort_on_exception = true
+        if self.class.needs.all? { |l| library_available?(l) }
+          begin
+            build_report
+          rescue Exception
+            raise if $!.is_a? SystemExit  # don't catch exit() calls
+            error "#{@name} run failed with an error", <<-END_ERROR.trim
+            Error:
+              #{$!.class}
+            Message:
+              #{$!.message}
+            Backtrace:
+            #{$!.backtrace.map { |line| "  #{line}\n" }.join}
+            END_ERROR
+          end
+        end
+      end.join  # wait for completion so we have reports to write
+      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.
+    # 
+    def library_available?(library)
+      begin
+        require library
+      rescue LoadError
+        begin
+          require "rubygems"
+          require library
+        rescue LoadError
+          error("Failed to load library", "Could not load #{library}")
+          return false
+        end
+      end
+      true
+    end
+    
+    def write_reports_and_update_memory
+      %w[report hint alert error].each do |type|
+        Array(send("#{type}s")).each do |fields|
+          @mission_log_db.write_report(@id, type, fields)
+        end
+      end
+      @mission_log_db.update_mission_memory(@id, data_for_server[:memory])
+    end
+  end
+  
+  # An external alias.
+  Plugin = Mission
+end

data/lib/scout_agent/order.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  class Order
+    ORDERS_DIR = LIB_DIR + "order"
+    
+    def self.log=(log)
+      @log = log
+    end
+    
+    def self.log
+      @log ||= WireTap.new(nil)
+    end
+    
+    def self.subclasses
+      @subclasses ||= Array.new
+    end
+    
+    def self.inherited(order)
+      subclasses << order
+    end
+
+    def self.load_all
+      ORDERS_DIR.each_entry do |order|
+        require ORDERS_DIR + order unless order.basename.to_s[0] == ?.
+      end
+      subclasses
+    end
+    
+    def self.can_handle?(message)
+      subclasses.each do |order|
+        if match_details = order.match?(message)
+          return order.new(message, match_details)
+        end
+      end
+    end
+    
+    def self.match?(message)
+      const_defined?(:MATCH_RE) and const_get(:MATCH_RE).match(message.body)
+    end
+    
+    def initialize(message, match_details)
+      @message       = message
+      @match_details = match_details
+    end
+    
+    attr_reader :message, :match_details
+    
+    def log
+      Order.log
+    end
+    
+    def execute
+      raise NotImplementedError,
+            "Subclasses must override ScoutAgent::Order#execute()."
+    end
+  end
+end

data/lib/scout_agent/order/check_in_order.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  class Order
+    class CheckInOrder < Order
+      MATCH_RE = /\A\s*check[-_]?in(?:\s+(.+?))?\s*\z/
+      
+      def self.mission_log
+        return @mission_log if defined? @mission_log
+        unless db = Database.load(:mission_log, log)
+          log.fatal("Could not load mission log database.")
+          exit
+        end
+        @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)
+          end
+        end
+        self.class.master_agent.signal("ALRM")
+      end
+    end
+  end
+end

data/lib/scout_agent/order/snapshot_order.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby -wKU
+
+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
+      
+      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
+        API.take_snapshot
+        self.class.master_agent.signal("ALRM")
+      end
+    end
+  end
+end

data/lib/scout_agent/plan.rb

@@ -0,0 +1,306 @@
+#!/usr/bin/env ruby -wKU
+
+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.
+  # 
+  # Users are free to add to this configuration as need (via their configuration
+  # file) and make use of those new values in their plugins.
+  # 
+  class << Plan = OpenStruct.new
+    ################
+    ### Defaults ###
+    ################
+    
+    # The default configuration for this agent.
+    def defaults
+      [ [:server_url,     "https://scoutapp.com"],
+        [:run_as_daemon,  true],
+        [:logging_level,  "INFO"],
+        [:test_mode,      false],
+
+        [:user_choices,   %w[daemon nobody]],
+        [:group_choices,  %w[daemon nogroup]],
+        [:prefix_path,    "/"],
+        [:os_config_path, "etc"],
+        [:os_db_path,     "var/db"],
+        [:os_pid_path,    "var/run"],
+        [:os_log_path,    "var/log"],
+        [:config_file,    nil],
+        [:db_dir,         nil],
+        [:pid_dir,        nil],
+        [:log_dir,        nil] ]
+    end
+    
+    # This method is used to set or reset the default configuration.
+    def set_defaults
+      defaults.each { |name, value| send("#{name}=", value) }
+    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 yet
+      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 yet
+      test_mode
+    end
+    
+    ###########################
+    ### Configuration Files ###
+    ###########################
+    
+    # This method loads configuration settings from a plain Ruby file.
+    def update_from_config_file(path = config_file)
+      eval <<-END_UPDATE
+      config = self
+      #{File.read(path)}
+      config
+      END_UPDATE
+    end
+    
+    #
+    # This method places the current configuration into a standard configuration
+    # file.  This makes it easy for users to edit this file and modify all
+    # future runs of the agent.
+    # 
+    def write_default_config_file
+      config_file.dirname.mkpath
+      config_file.open(File::CREAT|File::EXCL|File::WRONLY) do |pid|
+        pid.puts <<-END_DEFAULT_CONFIG.trim
+        #!/usr/bin/env ruby -wKU
+
+        # 
+        # This file configures #{ScoutAgent.proper_agent_name}.  The settings in
+        # here should get you started.  You can tweak these as the need arises.
+        # 
+        # Any Ruby code you would like run at start-up is a valid addition
+        # to this file.
+        # 
+        
+        ####################
+        ### Basic Config ###
+        ####################
+
+        # The key below is how the server identifies this machine:
+        config.agent_key = #{agent_key.inspect}
+        
+        # The following is the URL used to reach the server:
+        config.server_url = #{server_url.inspect}
+        
+        # 
+        # When the following is true, the agent will disconnect from the
+        # terminal that launches it and run in the background.  You can
+        # switch this to false to have the program stay connected and log
+        # to STDOUT.  This can be handy when debugging issues.
+        # 
+        # You can set this option to false for a single run with the
+        # command-line switch --no-daemon.
+        # 
+        config.run_as_daemon = #{run_as_daemon.inspect}
+        
+        # 
+        # The following sets your logging level for the agent.  This setting can
+        # be one of "DEBUG", "INFO", "WARN", "ERROR", or "FATAL".  Messages
+        # below the seleted level will not be written to the logs.  "DEBUG" is
+        # intended for the developers as it includes some very low level data,
+        # "INFO" (the default) is good general purpose logging that will what
+        # the agent does as it works, and "WARN" is a good choice if you want
+        # to minimize log space taken but still see problems.  Logs are rotated 
+        # daily and deleted after seven days though, so you shouldn't need to
+        # worry about the agent filling up your hard drive.
+        #
+        # This agent includes a command to upload logs to our server.  This is
+        # never done automatically or without your permission, but it can help
+        # us troubleshoot issues on your box.  We will give you the proper
+        # command for this during a support request if we think it would help.
+        # Rest assured that agent logs do not contain sensative data.
+        # 
+        config.logging_level = #{logging_level.inspect}
+        
+        #####################
+        ### Expert Config ###
+        #####################
+        
+        # 
+        # The agent will try to use standard Unix locations to store its
+        # data, but you are free to adjust these paths as needed.
+        # 
+        # The prefix is prepended to all other paths, so you can change
+        # just that to move all agent related storage.  The other three
+        # paths are specific locations where resources will be stored,
+        # so you can adjust those separately if needed.
+        # 
+        # 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.
+        # 
+        config.prefix_path = #{prefix_path.to_s.inspect}
+        
+        config.os_db_path  = #{os_db_path.
+                               relative_path_from(prefix_path).to_s.inspect}
+        config.os_pid_path = #{os_pid_path.
+                               relative_path_from(prefix_path).to_s.inspect}
+        config.os_log_path = #{os_log_path.
+                                  relative_path_from(prefix_path).to_s.inspect}
+        
+        #
+        # The agent must be started with super user privileges so it can
+        # prepare the environment for a long run.  However, it will abandon
+        # these privileges once setup is complete to better protect your
+        # security.
+        # 
+        # The following are the list of users and groups the agent will
+        # 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.
+        # 
+        # 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
+        # of what the agent will have access to on your system and makes
+        # it easier to track what the agent is doing.
+        # 
+        config.user_choices  = %w[#{user_choices.join(" ")}]
+        config.group_choices = %w[#{group_choices.join(" ")}]
+        
+        ############################
+        ### Your Personal Config ###
+        ############################
+
+        # Add any additional Ruby code you need to run at start-up below...
+        END_DEFAULT_CONFIG
+      end
+      config_file.chmod(0755)
+      true
+    rescue Errno::EEXIST  # file already exists
+      false
+    rescue Errno::EACCES  # don't have permission
+      false
+    end
+    
+    #############################
+    ### Command-line Switches ###
+    #############################
+    
+    # This method allows mass update through a +hash+ of settings.
+    def update_from_switches(hash)
+      hash.each { |name, value| send("#{name}=", value) }
+    end
+    alias_method :update_from_hash, :update_from_switches
+    
+    #############
+    ### Paths ###
+    #############
+    
+    # A prefix used in all configuration paths.
+    def prefix_path
+      Pathname.new(super)
+    end
+    
+    # 
+    # This code defines OS specific path accessors that honor the +prefix_path+.
+    # 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
+        prefix_path + super
+      end
+    end
+    
+    # 
+    # The full path to the loaded configuration file, prefixed by +prefix_path+
+    # and the +os_config_path+.  By default, this file is named after the agent.
+    # 
+    def config_file
+      os_config_path + (super || "#{ScoutAgent.agent_name}.rb")
+    end
+    
+    # 
+    # This code defines the application specific directory paths, prefixed by
+    # +prefix_path+ and the related OS directory.  By default, these directories
+    # are named after the agent.
+    # 
+    %w[db pid log].each do |path|
+      define_method("#{path}_dir") do
+        send("os_#{path}_path") + (super || ScoutAgent.agent_name)
+      end
+    end
+    
+    # 
+    # This code creates builders for the configuration directories.  These
+    # methods build the directories and set their group and permissons so
+    # they can be written to after the daemon surrenders super user privileges.
+    # 
+    { :db_dir  => 0777,
+      :pid_dir => 0775,
+      :log_dir => 0777 }.each do |path, permissions|
+      define_method("build_#{path}") do |group_id|
+        begin
+          send(path).mkpath
+          send(path).chown(nil, group_id)
+          send(path).chmod(permissions)
+          true
+        rescue Errno::EACCES, Errno::EPERM   # don't have permission
+          false
+        end
+      end
+    end
+    
+    #############
+    ### URL's ###
+    #############
+    
+    def agent_url
+      URI.join(server_url, "clients/#{agent_key}")
+    end
+    
+    #################
+    ### Databases ###
+    #################
+    
+    def prepare_global_database(name)
+      db = Database.load(name) or return false
+      db.path.chmod(0777)
+      true
+    rescue Errno::EPERM  # don't have permission
+      false
+    end
+    
+    ##################
+    ### Validation ###
+    ##################
+    
+    # Returns +true+ if all needed configuration paths exist.
+    def present?
+      %w[config_file db_dir log_dir].all? { |path| send(path).exist? } and
+      %w[queue snapshots].all?            { |db|   Database.path(db).exist? }
+    end
+
+    # 
+    # Returns +true+ if <tt>present?</tt> and all needed configuration paths
+    # have proper permisions as far as this current run is concerned.
+    # 
+    def valid?
+      present?                                                            and
+      %w[config_file db_dir log_dir].all? { |path| send(path).readable? } and
+      %w[db_dir log_dir].all?             { |path| send(path).writable? } and
+      %w[queue snapshots].map             { |db|   Database.path(db) }.
+                          all?            { |path| path.readable? and
+                                                   path.writable? }
+    end
+  end
+  
+  # 
+  # Set the defaults after we have overriden some accessors, to keep OpenStruct
+  # from replacing them.
+  # 
+  Plan.set_defaults
+end