scout_agent 3.0.0

data/lib/scout_agent/database/statuses.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  class Database
+    class Statuses < Database
+      def update_schema(version = schema_version)
+        case version
+        when 0
+          <<-END_INITIAL_SCHEMA.trim
+          CREATE TABLE statuses (
+            name            TEXT NOT NULL PRIMARY KEY
+              CHECK( name IN ( 'lifeline',      'master', 'mission',
+                               'communication', 'queue',  'snapshot' ) ),
+            pid             INTEGER NOT NULL,
+            status          REQUIRED_TEXT_TYPE,
+            last_updated_at DATETIME_TYPE
+          );
+          DEFAULT_LOCALTIME_TRIGGER statuses last_updated_at
+          END_INITIAL_SCHEMA
+        end
+      end
+      
+      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)
+          INSERT OR REPLACE INTO statuses(name, pid, status, last_updated_at)
+                                 VALUES(     ?,   ?,      ?,            null)
+          END_UPDATE_STATUS
+        end
+      rescue Amalgalite::SQLite3::Error => error  # failed to update status
+        # do nothing:  try again later
+        log.error("Database status update error:  #{error.message}.")
+      end
+      
+      def clear_status(name = IDCard.me && IDCard.me.process_name)
+        write_to_sqlite do |sqlite|
+          sqlite.execute("DELETE FROM statuses WHERE name = ?", name)
+        end
+      rescue Amalgalite::SQLite3::Error => error  # failed to delete status
+        # do nothing:  new process will replace
+        log.error("Database status clearing error:  #{error.message}.")
+      end
+      
+      def current_statuses
+        query(<<-END_FIND_STATUSES.trim)
+        SELECT name, pid, status, last_updated_at FROM statuses ORDER BY ROWID
+        END_FIND_STATUSES
+      rescue Amalgalite::SQLite3::Error => error  # failed to find statuses
+        log.error("Database statuses error:  #{error.message}.")
+        Array.new  # return empty results
+      end
+      
+      def current_status(name = IDCard.me && IDCard.me.process_name)
+        read_from_sqlite { |sqlite|
+          sqlite.first_value_from(<<-END_FIND_STATUS, name)
+          SELECT status FROM statuses WHERE name = ?
+          END_FIND_STATUS
+        }
+      rescue Amalgalite::SQLite3::Error => error  # failed to find status
+        log.error("Database current status error:  #{error.message}.")
+        nil  # return no results
+      end
+    end
+  end
+end

data/lib/scout_agent/dispatcher.rb

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  module Dispatcher
+    module_function
+
+    def dispatch(args = ARGV)
+      switches   = parse_switches(args)
+      assignment = parse_assignment(args)
+      code       = load_assignment(assignment)
+      execute_assignment(assignment, code, switches, args)
+    end
+    
+    def parse_switches(args)
+      switches = { }
+
+      args.options do |opts|
+        opts.banner = <<-END_USAGE.trim
+        Usage:
+        
+          [sudo] #{ScoutAgent.agent_name} [OPTIONS] COMMAND
+        
+        Use the commands identify, start, and stop to prepare, launch, and
+        shutdown the agent respectively.  Those require super user privileges.
+        You can also use the status command to check in on a running agent.
+        
+        END_USAGE
+
+        opts.separator "Basic Options:"
+        opts.on( "-s", "--server URL", String,
+                 "The URL for the server to report to." ) do |url|
+          switches[:server_url] = url
+        end
+        opts.on( "-d", "--[no-]daemon",
+                 "Run in the background as a daemon." ) do |boolean|
+          switches[:run_as_daemon] = boolean
+        end
+        opts.on( "-l", "--logging-level LEVEL", %w[DEBUG INFO WARN ERROR FATAL],
+                 "The minimum level of log message to record." ) do |level|
+          switches[:logging_level] = level
+        end
+        opts.on( "-t", "--[no-]test-mode",
+                 "Used in agent development." ) do |boolean|
+          if switches[:test_mode]    = boolean
+            switches[:server_url]    = "http://localhost:4567"
+            switches[:run_as_daemon] = false
+          end
+        end
+
+        opts.separator "Expert Options:"
+        opts.on( "--users NAME1,NAME2,...", Array,
+                 "A list of users to try switching to." ) do |users|
+          switches[:user_choices] = users
+        end
+        opts.on( "--groups NAME1,NAME2,...", Array,
+                 "A list of groups to try switching to." ) do |groups|
+          switches[:group_choices] = groups
+        end
+        opts.on( "--prefix PATH", String,
+                 "A prefix path prepended to all other paths." ) do |path|
+          switches[:prefix_path] = path
+        end
+        [ %w[os_config_path configuration],
+          %w[os_db_path     databases],
+          %w[os_pid_path    PID\ files],
+          %w[os_log_path    log\ files] ].each do |name, used_for|
+          opts.on( "--#{name.tr('_', '-')} PATH", String,
+                   "The path your OS uses for #{used_for}." ) do |path|
+            switches[name.to_sym] = path
+          end
+        end
+
+        opts.separator "Application Options:"
+        opts.on( "-h", "--help",
+                 "Show this message." ) do
+          puts opts  # show usage
+          exit
+        end
+        opts.on( "-v", "--version",
+                 "Display the current version." ) do
+          puts "#{ScoutAgent.proper_agent_name} v#{ScoutAgent::VERSION}"
+          exit
+        end
+
+        begin
+          opts.parse!
+        rescue OptionParser::ParseError  # failed to parse options
+          puts opts  # show usage
+          exit
+        end
+      end
+      
+      # apply switches so paths will be set correctly for load checks
+      Plan.update_from_switches(switches)
+
+      switches
+    end
+    
+    def parse_assignment(args)
+      assignment = args.shift.to_s.downcase
+      if assignment.empty?
+        if Plan.present?
+          if IDCard.new(:lifeline).pid_file.exist?
+            return "status"
+          else
+            return "start"
+          end
+        else
+          return "identify"
+        end
+      end
+      unless assignment =~ /\A\w+\z/
+        abort_with_unknown_assignment(assignment)
+      end
+      assignment
+    end
+    
+    def load_assignment(assignment)
+      dir     = LIB_DIR + "assignment"
+      matches = dir.entries.grep(/#{Regexp.escape(assignment)}\w*\.rb\z/)
+      if matches.size > 1
+        abort_with_ambiguous_assignment(assignment, matches)
+      elsif matches.first and (code = dir + matches.first).exist?
+        return code
+      else
+        abort_with_unknown_assignment(assignment)
+      end
+    end
+    
+    def execute_assignment(assignment, code, switches, other_args)
+      require code
+      class_name = code.basename(".rb").to_s.CamelCase
+      begin
+        loaded = Assignment.const_get(class_name)
+      rescue NameError  # can't load module
+        abort_with_missing_code(class_name)
+      end
+      loaded.new(switches, other_args).prepare_and_execute
+    end
+    
+    def abort_with_ambiguous_assignment(assignment, matches)
+      choices         = matches.map { |m| "'#{m.basename('.rb')}'" }
+      choices[-2..-1] = choices[-2..-1].join(", or ")
+      abort <<-END_AMBIGUOUS
+      Ambiguous command '#{assignment}'.  Did you mean #{choices.join(', ')}?
+      END_AMBIGUOUS
+    end
+    
+    def abort_with_unknown_assignment(assignment)
+      abort "Unknown command '#{assignment}'."
+    end
+    
+    def abort_with_missing_code(class_name)
+      abort "Failed to load '#{class_name}'."
+    end
+  end
+end

data/lib/scout_agent/id_card.rb

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  #
+  # This class excapsulates a named process.  It is used to ensure exclusive
+  # execution and to signal other processes.
+  # 
+  class IDCard
+    class << self
+      # 
+      # This global attribute should contain the name of the current process.
+      # It is set during a successful authorization.
+      # 
+      # <b>Warning:</b>  Be sure to clear this attribute immediately after a
+      # fork() so you don't keep the parent's identity.
+      # 
+      attr_accessor :me
+    end
+    
+    # 
+    # Pass in the +process_name+ of the process you want to signal() or the
+    # +process_name+ you wish to authorize() for yourself.
+    #
+    def initialize(process_name)
+      @process_name = process_name
+    end
+    
+    attr_reader :process_name
+    
+    # A String representation of this process, with PID.
+    def to_s
+      "#{@process_name} (#{pid || 'unauthorized'})"
+    end
+    
+    # 
+    # Returns the path to the unique PID file for this process, based on the 
+    # current Plan.
+    # 
+    def pid_file
+      Plan.pid_dir + "#{@process_name}.pid"
+    end
+    
+    # Returns the PID for the named process, or +nil+ if it cannot be read.
+    def pid
+      pid_file.read.to_i
+    rescue Exception
+      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.
+    # 
+    # 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
+    # for a missing process, will bubble up to the calling code.
+    # 
+    def signal(message)
+      if id = pid
+        Process.kill(message, id)
+        true
+      else
+        false
+      end
+    end
+    
+    # 
+    # Claims this identity for this process.  This process is multiprocess-safe
+    # and will fail if another process has claimed this identity.  However,
+    # 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.
+    # 
+    def authorize
+      File.open(pid_file, File::CREAT | File::EXCL | File::WRONLY) do |pid|
+        pid.flock(File::LOCK_EX)
+        if not block_given? or yield  # allows for daemonization
+          pid.puts Process.pid
+        else
+          pid.flock(File::LOCK_UN)
+          revoke  # remove this file if anything went wrong
+          return false
+        end
+        pid.flock(File::LOCK_UN)
+      end
+      
+      self.class.me = self
+      
+      at_my_exit do
+        unless revoke
+          # log.error "Unable to unlink pid file:  #{$!.message}" if log
+        end
+      end
+      true
+    rescue Errno::EEXIST  # pid_file already exists
+      File.open(pid_file) do |pid|
+        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
+            rescue Errno::ESRCH  # no such process
+              # log.info "Stale PID file found.  Clearing it and reloading..." if log
+              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
+          return false
+        end
+      end
+      # log.warn "Process #{pid} was already running" if log
+      false
+    end
+    
+    # 
+    # Releases a held claim on a process name.  Returns +true+ if successful or
+    # +false+ if the PID file didn't exist or couldn't be destroyed.
+    # 
+    def revoke
+      pid_file.unlink
+      true
+    rescue Exception
+      false
+    end
+  end
+end

data/lib/scout_agent/lifeline.rb

@@ -0,0 +1,243 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  class Lifeline
+    NO_CONTACT_TIMEOUT   = 3
+    CHECK_IN_FREQUENCY   = 0.99  # gives us three check ins before a cutoff
+    TERM_TO_KILL_PAUSE   = 1
+    RELAUNCH_FREQUENCIES = [0, 1, 1, 2, 3, 5, 8, 13]
+    
+    #################
+    ### Interface ###
+    #################
+    
+    def initialize(agent, log = WireTap.new(nil))
+      @agent                       = agent
+      @log                         = log
+      @parent_pid                  = Process.pid
+      @child_pid                   = nil
+      @reader                      = nil
+      @writer                      = nil
+      @launch_and_monitor_thread   = nil
+      @check_in_with_parent_thread = nil
+      @code                        = nil
+      @last_launch                 = nil
+      @relaunch_index              = 0
+      
+      at_my_exit do
+        clear_status
+      end
+    end
+    
+    include Tracked
+    
+    attr_reader :log
+    
+    def launch_and_monitor
+      @launch_and_monitor_thread = Thread.new do
+        Thread.current.abort_on_exception = true
+        loop do
+          wait_for_launch
+          prepare_pipe
+          launch_child
+          close_writer
+          monitor_child
+          restart_child
+        end
+      end
+    end
+    
+    def terminate
+      if Process.pid == @parent_pid
+        # stop monitoring
+        log.info("Stopping the monitoring for '#{@agent}'.")
+        @launch_and_monitor_thread.exit if @launch_and_monitor_thread
+        # ask child process to exit
+        log.info("Asking '#{@agent}' to stop.")
+        IDCard.new(@agent).signal("TERM")
+      end
+    rescue Errno::ESRCH  # no such process
+      # if already exited, so we are fine
+    end
+    
+    def join
+      if Process.pid == @parent_pid and @launch_and_monitor_thread
+        @launch_and_monitor_thread.join
+      end
+    end
+    
+    #######
+    private
+    #######
+    
+    ##############
+    ### Parent ###
+    ##############
+    
+    def wait_for_launch
+      if @last_launch
+        seconds_ran   = Time.now - @last_launch
+        relaunch_wait = RELAUNCH_FREQUENCIES[@relaunch_index] * 60 - seconds_ran
+
+        if relaunch_wait > 0
+          log.info( "Waiting #{relaunch_wait} seconds before relaunching " +
+                    "'#{@agent}'." )
+          sleep relaunch_wait
+        elsif relaunch_wait.abs > ( RELAUNCH_FREQUENCIES[@relaunch_index + 1] ||
+                                    RELAUNCH_FREQUENCIES.last ) * 60
+          @relaunch_index = 0
+          return
+        end
+
+        unless @relaunch_index == RELAUNCH_FREQUENCIES.size - 1
+          @relaunch_index += 1
+        end
+      end
+    end
+    
+    def prepare_pipe
+      @reader, @writer = IO.pipe
+    end
+    
+    def launch_child
+      log.info("Launching '#{@agent}'.")
+      status(@agent)
+      @last_launch = Time.now
+      @child_pid   = fork do
+        reset_environment
+        close_reader
+        load_code
+        authorize_code
+        check_in_with_parent
+        run_code
+      end
+    end
+    
+    def close_writer
+      @writer.close
+    rescue IOError  # already closed
+      # it's closed so we're OK
+    rescue NoMethodError  # @writer is nil
+      # it wasn't set so there's nothing to close
+    end
+    
+    def monitor_child
+      loop do
+        check_in = nil
+        begin
+          Timeout.timeout(NO_CONTACT_TIMEOUT) { check_in = @reader.gets }
+          log.error("'#{@agent}' monitor channel has closed.") if check_in.nil?
+        rescue Timeout::Error
+          # check_in will stay nil
+          log.error("'#{@agent}' failed to check-in in time.")
+        end
+        unless check_in.to_s =~ 
+               /\A#{@child_pid}:  \d{4}-\d{2}-\d{2} \d{2}:\d{2}\Z/
+          log.error("'#{@agent}' check-in was malformed.") unless check_in.nil?
+          break
+        end
+      end
+    end
+    
+    def restart_child
+      log.info("Stopping '#{@agent}'.")
+      status(@agent, :restarting)
+      close_reader
+      Process.term_or_kill(@child_pid, TERM_TO_KILL_PAUSE)
+    end
+    
+    def status(process, restarting = false)
+      if db = status_database
+        db.write_to_sqlite do |sqlite|
+          old_status = db.current_status
+          if old_status =~ /\ARestarting (.+)\z/
+            processes = $1.split(" and ")
+            if restarting
+              processes << process unless processes.include? process
+              super("Restarting #{processes.join(' and ')}")
+            else
+              processes.delete(process)
+              if processes.empty?
+                super("Monitoring processes")
+              else
+                super("Restarting #{processes.join(' and ')}")
+              end
+            end
+          else
+            if restarting
+              super("Restarting #{process}")
+            else
+              super("Monitoring processes")
+            end
+          end
+        end
+      end
+    end
+    
+    #############
+    ### Child ###
+    #############
+    
+    def reset_environment
+      # swap out our parent's signal handlers
+      install_shutdown_handler { finish_code }
+      trap("ALRM")             { alert_code  }
+      
+      # clear the parent's identity
+      IDCard.me = nil
+    end
+    
+    def close_reader
+      @reader.close
+    rescue IOError  # already closed
+      # it's closed so we're OK
+    rescue NoMethodError  # @reader is nil
+      # it wasn't set so there's nothing to close
+    end
+    
+    def load_code
+      require LIB_DIR + "agent"
+      require LIB_DIR + "agent/#{@agent}_agent"
+      @code = ScoutAgent::Agent.const_get("#{@agent.CamelCase}Agent").new
+    end
+    
+    def authorize_code
+      @code.authorize
+    end
+    
+    def check_in_with_parent
+      @check_in_with_parent_thread = Thread.new do
+        Thread.current.abort_on_exception = true
+        loop do
+          begin
+            @writer.puts "#{Process.pid}:  " +
+                         Time.now.strftime('%Y-%m-%d %H:%M')
+          rescue Errno::EPIPE, IOError  # parent closed our pipe or exited
+            break finish_code
+          end
+          sleep CHECK_IN_FREQUENCY
+        end
+      end
+    end
+    
+    def run_code
+      @code.run
+    end
+    
+    def finish_code
+      close_writer
+
+      if @code
+        @code.finish
+      else
+        exit
+      end
+    end
+    
+    def alert_code
+      if @code
+        @code.notice_changes
+      end
+    end
+  end
+end