right_agent 0.17.2 → 1.0.1

data/lib/right_agent.rb

@@ -26,7 +26,6 @@ require File.expand_path(File.join(File.dirname(__FILE__), 'right_agent', 'minim
 require 'json'
 require 'openssl'
 require 'right_amqp'
-require 'right_support'
 
 require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'monkey_patches'))
 require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'payload_formatter'))

data/lib/right_agent/agent_config.rb

@@ -63,7 +63,7 @@ module RightScale
   module AgentConfig
 
     # Current agent protocol version
-    PROTOCOL_VERSION = 21
+    PROTOCOL_VERSION = 22
 
     # Current agent protocol version
     #

data/lib/right_agent/minimal.rb

@@ -23,13 +23,14 @@
 require 'rubygems'
 require 'eventmachine'
 require 'fileutils'
+require 'right_support'
 require 'yaml'
 
 # load definition for File.normalize_path, etc.
-require File.expand_path(File.join(File.dirname(__FILE__), 'platform'))
+require ::File.expand_path('../monkey_patches', __FILE__)
 
 unless defined?(RIGHT_AGENT_BASE_DIR)
-  RIGHT_AGENT_BASE_DIR = File.normalize_path(File.dirname(__FILE__))
+  RIGHT_AGENT_BASE_DIR = ::File.normalize_path('..', __FILE__)
 end
 
 # require minimal gems needed to create a CommandClient and send a command.
@@ -37,8 +38,8 @@ end
 # FIX: agent_controller is currently the only minimal-load use case so these
 # requires are oriented toward that. any additional use cases may require a
 # rethink of minimal loading.
-require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'agent_config'))
-require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'command'))
-require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'log'))
-require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'pid_file'))
-require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'serialize', 'serializable'))
+require ::File.normalize_path('agent_config', RIGHT_AGENT_BASE_DIR)
+require ::File.normalize_path('command', RIGHT_AGENT_BASE_DIR)
+require ::File.normalize_path('log', RIGHT_AGENT_BASE_DIR)
+require ::File.normalize_path('pid_file', RIGHT_AGENT_BASE_DIR)
+require ::File.normalize_path('serialize/serializable', RIGHT_AGENT_BASE_DIR)

data/lib/right_agent/monkey_patches.rb

@@ -23,6 +23,8 @@
 require 'rubygems'
 require 'rbconfig'
 
-MONKEY_PATCHES_BASE_DIR = File.join(File.dirname(__FILE__), 'monkey_patches')
+unless defined?(RIGHT_AGENT_MONKEY_PATCHES_BASE_DIR)
+  require ::File.expand_path('../monkey_patches/ruby_patch', __FILE__)
 
-require File.normalize_path(File.join(MONKEY_PATCHES_BASE_DIR, 'ruby_patch'))
+  RIGHT_AGENT_MONKEY_PATCHES_BASE_DIR = ::File.normalize_path('../monkey_patches', __FILE__)
+end

data/lib/right_agent/monkey_patches/ruby_patch.rb

@@ -32,24 +32,24 @@ require 'socket'
 # using short path. Since this is where we define the File.normalize_path
 # method to alleviate this issue, we have a chicken & egg problem. So detect if
 # we already required this file and skip the rest if that was the case.
-unless defined?(RUBY_PATCH_BASE_DIR)
+unless defined?(RIGHT_AGENT_RUBY_PATCH_BASE_DIR)
 
 # Load platform-specific patches before any other patches (in order to define
 # File.normalize_path, etc.)
-case (family = RbConfig::CONFIG['host_os'])
+case ::RbConfig::CONFIG['host_os']
 when /mswin|win32|dos|mingw|cygwin/i
-  require File.expand_path(File.join(File.dirname(__FILE__), 'ruby_patch', 'windows_patch'))
+  require ::File.expand_path('../ruby_patch/windows_patch', __FILE__)
 when /linux/i
-  require File.expand_path(File.join(File.dirname(__FILE__), 'ruby_patch', 'linux_patch'))
+  require ::File.expand_path('../ruby_patch/linux_patch', __FILE__)
 when /darwin/i
-  require File.expand_path(File.join(File.dirname(__FILE__), 'ruby_patch', 'darwin_patch'))
+  require ::File.expand_path('../ruby_patch/darwin_patch', __FILE__)
 else
-  raise LoadError, "Unsupported platform: #{family}"
+  raise LoadError, "Unsupported platform: #{::RbConfig::CONFIG['host_os']}"
 end
 
-RUBY_PATCH_BASE_DIR = File.join(File.dirname(__FILE__), 'ruby_patch')
+RIGHT_AGENT_RUBY_PATCH_BASE_DIR = ::File.normalize_path('../ruby_patch', __FILE__)
 
-require File.normalize_path(File.join(RUBY_PATCH_BASE_DIR, 'array_patch'))
-require File.normalize_path(File.join(RUBY_PATCH_BASE_DIR, 'object_patch'))
+require File.join(RIGHT_AGENT_RUBY_PATCH_BASE_DIR, 'array_patch')
+require File.join(RIGHT_AGENT_RUBY_PATCH_BASE_DIR, 'object_patch')
 
 end # Unless already defined

data/lib/right_agent/monkey_patches/ruby_patch/linux_patch/file_patch.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2011 RightScale Inc
+# Copyright (c) 2011-2013 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -24,7 +24,7 @@ class File
 
   # On *nix systems, resolves to File.expand_path
   def self.normalize_path(file_name, *dir_string)
-    File.expand_path(file_name, *dir_string)
+    self.expand_path(file_name, *dir_string)
   end
 
 end

data/lib/right_agent/monkey_patches/ruby_patch/windows_patch/file_patch.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2011 RightScale Inc
+# Copyright (c) 2011-2013 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -23,68 +23,38 @@
 require 'rubygems'
 
 begin
-  require 'windows/file'
+
+  # attempt to early-load basic Windows API gems so that we can rescue and
+  # switch to using the simple definition of File.normalize_path when these gems
+  # are unavailable.
+  require ::File.expand_path('../../../../platform', __FILE__)
 
   class File
 
-    # converts a long path to a short path. in windows terms, this means
-    # taking any file/folder name over 8 characters in length and truncating
-    # it to 6 characters with ~1..~n appended depending on how many similar
-    # names exist in the same directory. file extensions are simply chopped
-    # at three letters. the short name is equivalent for all API calls to
-    # the long path but requires no special quoting, etc. the path must
-    # exist at least partially for the API call to succeed.
+    # Expand the path then shorten the directory, if possible.
+    # Only shortens the parent directory and not the leaf (file or directory)
+    # name because 'gem' wants the file name to be long for require.
     #
-    # === Parameters
-    # long_path(String):: fully or partially existing long path to be
-    # converted to its short path equivalent.
+    # @param [String] file_name to normalize
+    # @param [String] dir_string as base directory path for relative file_name
+    #   or ignored when file_name is absolute (Default = working directory).
     #
-    # === Return
-    # short_path(String):: short path equivalent or same path if non-existent
-    def self.long_path_to_short_path(long_path)
-      if File.exists?(long_path)
-        length = 260
-        while true
-          buffer = 0.chr * length
-          length = ::Windows::File::GetShortPathName.call(long_path, buffer, buffer.length)
-          if length < buffer.length
-            break
-          end
-        end
-        return buffer.unpack('A*').first.gsub("\\", "/")
-      else
-        # must get short path for any existing ancestor since child doesn't
-        # (currently) exist.
-        child_name = File.basename(long_path)
-        long_parent_path = File.dirname(long_path)
-
-        # note that root dirname is root itself (at least in windows)
-        return long_path if long_path == long_parent_path
-
-        # recursion
-        short_parent_path = long_path_to_short_path(File.dirname(long_path))
-        return File.join(short_parent_path, child_name)
-      end
-    end
-
-    # First expand the path then shorten the directory.
-    # Only shorten the directory and not the file name because 'gem' wants
-    # long file names
+    # @return [String] normalized path
     def self.normalize_path(file_name, *dir_string)
-      path = File.expand_path(file_name, *dir_string)
-      dir = self.long_path_to_short_path(File.dirname(path))
-      File.join(dir, File.basename(path))
+      path = self.expand_path(file_name, *dir_string)
+      dir = ::RightScale::Platform.filesystem.long_path_to_short_path(self.dirname(path))
+      self.join(dir, self.basename(path))
     end
-
   end
 
 rescue LoadError
-  # use the simple definition of normalize_path to avoid breaking code which
-  # depends on having this definition.
+
+  # use the simple definition of normalize_path on load error. the purpose of
+  # normalize_path is to disambiguate load paths but it is possible to continue
+  # with ambiguity in most cases and any other Win32 API calls will fail.
   class File
     def self.normalize_path(file_name, *dir_string)
-      File.expand_path(file_name, *dir_string)
+      self.expand_path(file_name, *dir_string)
     end
   end
-
 end

data/lib/right_agent/packets.rb

@@ -24,6 +24,10 @@
 module JSON
   class << self
     def parse(source, opts = {})
+      # In gem version this options is set to true by default
+      # but in ruby native json library is set to false by default
+      # Explicitly set it to true so both json libraries act the same
+      opts[:create_additions] = true
       if source =~ /(.*)json_class":"Nanite::(.*)/
         JSON.parser.new( Regexp.last_match(1) + 'json_class":"RightScale::' + Regexp.last_match(2), opts).parse
       else
@@ -248,7 +252,7 @@ module RightScale
     def trace
       audit_id = self.respond_to?(:payload) && payload.is_a?(Hash) && (payload['audit_id'] || payload[:audit_id])
       tok = self.respond_to?(:token) && token
-      tr = "<#{audit_id || nil}> <#{tok}>" 
+      tr = "<#{audit_id || nil}> <#{tok}>"
     end
 
     # Retrieve protocol version of original creator of packet

data/lib/right_agent/platform.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2009-2011 RightScale Inc
+# Copyright (c) 2009-2013 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -26,317 +26,745 @@
 # we already required this file and skip the rest if that was the case.
 unless defined?(RightScale::Platform)
 
-# Note that the platform-specific submodules will be loaded on demand to resolve
-# some install-time gem dependency issues.
-
-require 'rbconfig'
-require 'right_support'
-
-
-# Load ruby interpreter monkey-patches first (to ensure File.normalize_path is defined, etc.).
-require File.expand_path(File.join(File.dirname(__FILE__), 'monkey_patches', 'ruby_patch'))
-
-module RightScale
-  # Throw when the current platform is not supported for some reason
-  class PlatformNotSupported < Exception; end
-
-  # A utility class that provides information about the platform on which the RightAgent is running
-  # Available information includes:
-  #  - which flavor cloud (EC2, Rackspace, Eucalyptus, ..)
-  #  - which flavor operating system (Linux, Windows or Mac)
-  #  - which OS release (a numeric value that is specific to the OS)
-  #  - directories in which various bits of RightScale state may be found
-  #  - platform-specific information such as Linux flavor or release
-  #
-  # For platform information only used in specific contexts, the dispatch method may be used
-  #
-  # This is a summary of the information you can query by calling Platform's instance methods:
-  #  - .flavor
-  #  - .release
-  #  - .linux?
-  #  - .darwin?
-  #  - .windows?
-  #  - .ec2?
-  #  - .rackspace?
-  #  - .eucalyptus?
-  #  - .filesystem
-  #     - right_scale_state_dir
-  #     - spool_dir
-  #     - cache_dir
-  #  - .linux (only available under Linux)
-  #     - ubuntu?
-  #     - centos?
-  #     - suse?
-  class Platform
-
-    include RightSupport::Ruby::EasySingleton
-
-    # Generic platform family
-    #
-    # === Return
-    # family(Symbol):: One of :linux, :windows or :darwin
-    def family
-      @family ||= case RbConfig::CONFIG['host_os']
-                  when /mswin|win32|dos|mingw|cygwin/i then :windows
-                  when /darwin/i then :darwin
-                  when /linux/i then :linux
-                  end
-    end
-
-    # Is current platform linux?
-    #
-    # === Return
-    # true:: If current platform is linux
-    # false:: Otherwise
-    def linux?
-      return family == :linux
-    end
-
-    # Is current platform darwin?
-    #
-    # === Return
-    # true:: If current platform is darwin
-    # false:: Otherwise
-    def darwin?
-      return family == :darwin
-    end
-    # Is current platform windows?
-    #
-    # === Return
-    # true:: If current platform is Windows
-    # false:: Otherwise
-    def windows?
-      return family == :windows
-    end
-
-    # Call platform specific implementation of method whose symbol is returned
-    # by the passed in block. Arguments are passed through.
-    # e.g.
-    #
-    #   Platform.dispatch(2) { :echo }
-    #
-    # will result in 'echo_linux(2)' being executed in self if running on linux,
-    # 'echo_windows(2)' if running on Windows and 'echo_darwin(2)' if on Mac OS X.
-    # Note that the method is run in the instance of the caller.
-    #
-    # === Parameters
-    # args:: Pass-through arguments
-    #
-    # === Block
-    # Given block should not take any argument and return a symbol for the
-    # method that should be called
-    #
-    # === Return
-    # res(Object):: Result returned by platform specific implementation
-    def dispatch(*args, &blk)
-      raise "Platform.dispatch requires a block" unless blk
-      binding = blk.binding.eval('self')
-      meth = blk.call
-      target = dispatch_candidates(meth).detect do |candidate|
-        binding.respond_to?(candidate)
-      end
-      raise "No platform dispatch target found in #{binding.class} for " +
-            "'#{meth.inspect}', tried " + dispatch_candidates(meth).join(', ') unless target
-      binding.__send__(target, *args)
-    end
-
-    # Load platform specific implementation
-    #
-    # === Return
-    # true:: Always return true
-    def load_platform_specific
-      if linux?
-        require_linux
-      elsif darwin?
-        require_darwin
-      elsif windows?
-        require_windows
-      else
-        raise PlatformError.new('Unknown platform')
-      end
-    end
-
-    # Are we in an EC2 cloud?
-    #
-    # === Return
-    # true:: If machine is located in an EC2 cloud
-    # false:: Otherwise
-    def ec2?
-      resolve_cloud_type if @ec2.nil?
-      @ec2
-    end
-
-    # Are we in a Rackspace cloud?
-    #
-    # === Return
-    # true:: If machine is located in an Rackspace cloud
-    # false:: Otherwise
-    def rackspace?
-      resolve_cloud_type if @rackspace.nil?
-      @rackspace
-    end
-
-    # Are we in a Eucalyptus cloud?
+  # Note that the platform-specific submodules will be loaded on demand to resolve
+  # some install-time gem dependency issues.
+  require 'rubygems'
+  require 'rbconfig'
+  require 'right_support'
+
+  require ::File.expand_path('../exceptions', __FILE__)
+
+  module RightScale
+
+    # A utility class that provides information about the platform on which the
+    # RightAgent is running.
     #
-    # === Return
-    # true:: If machine is located in an Eucalyptus cloud
-    # false:: Otherwise
-    def eucalyptus?
-      resolve_cloud_type if @eucalyptus.nil?
-      @eucalyptus
-    end
-
-    # Controller object
+    # Available information includes:
+    #  - which flavor cloud (EC2, Rackspace, Eucalyptus, ..)
+    #  - which flavor operating system (Linux, Windows or Mac)
+    #  - which OS release (a numeric value that is specific to the OS)
+    #  - directories in which various bits of RightScale state may be found
+    #  - platform-specific information such as Linux flavor or release
     #
-    # === Return
-    # (Controller):: Platform-specific controller object
-    def controller
-      platform_service(:controller)
-    end
+    # For platform information only used in specific contexts, the dispatch
+    # method may be used.
+    class Platform
 
-    # Filesystem config object
-    #
-    # === Return
-    # (Filesystem):: Platform-specific filesystem config object
-    def filesystem
-      platform_service(:filesystem)
-    end
+      include RightSupport::Ruby::EasySingleton
 
-    # VolumeManager config object
-    #
-    # === Return
-    # (VolumeManager):: Platform-specific volume manager config object
-    def volume_manager
-      platform_service(:volume_manager)
-    end
+      # exceptions
+      class CommandError < RightScale::Exceptions::PlatformError
+        attr_accessor :command
+        attr_accessor :status
+        attr_accessor :output_text
+      end
 
-    # Shell information object
-    #
-    # === Return
-    # (Object):: Platform-specific shell information object
-    def shell
-      platform_service(:shell)
-    end
+      attr_reader :flavor, :release, :codename
+
+      # Generic platform family
+      #
+      # @deprecated family is a legacy definition, see genus/species for a more
+      #   granular definition.
+      #
+      # @return [Symbol] result as one of :linux, :windows or :darwin
+      def family
+        warn "#{self.class.name}#family is deprecated, use genus or species instead.\n#{caller[0,2].join("\n")}"
+        (genus == :unix) ? species : genus
+      end
 
-    # SSH information object
-    #
-    # === Return
-    # (Object):: Platform-specific ssh object
-    def ssh
-      platform_service(:ssh)
-    end
+      # @return [Symbol] platform genus
+      def genus
+        resolve_taxonomy unless @genus
+        @genus
+      end
 
-    # Platform random number generator (RNG) facilities.
-    #
-    # === Return
-    # (Object):: Platform-specific RNG object
-    def rng
-      platform_service(:rng)
-    end
+      # @return [Symbol] platform species
+      def species
+        resolve_taxonomy unless @species
+        @species
+      end
 
-    # Platform process facilities.
-    #
-    # === Return
-    # (Object):: Platform-specific process facilities object
-    def process
-      platform_service(:process)
-    end
-    
-    # Installer information object
-    #
-    # === Return
-    # (Object):: Platform-specific installer information object
-    def installer
-      platform_service(:installer)
-    end
-
-    # Determines which cloud we're on by the cheap but simple expedient of
-    # reading the RightScale cloud file
-    def resolve_cloud_type
-      cloud_type = read_cloud_file
-      @ec2 = false
-      @rackspace = false
-      @eucalyptus = false
-      case cloud_type
-        when 'ec2' then @ec2 = true
-        when 'rackspace' then @rackspace = true
-        when 'eucalyptus' then @eucalyptus = true
-      end
-    end
-
-    private
-
-    # Load platform specific implementation
-    def initialize
-      require File.expand_path(File.join(File.dirname(__FILE__), 'platform', family.to_s))
-      @filesystem = nil
-      @shell      = nil
-      @ssh        = nil
-      @controller = nil
-      @installer  = nil
-
-      @ec2        = nil
-      @rackspace  = nil
-      @eucalyptus = nil
-
-      init
-      
-      # Note that we must defer any use of filesystem until requested because
-      # Windows setup scripts attempt to use Platform before installing some
-      # of the required gems. Don't attempt to call code that requires gems in
-      # initialize().
-    end
-
-    def require_linux
-      require File.expand_path(File.join(File.dirname(__FILE__), 'platform', 'linux'))
-    end
-
-    def require_darwin
-      require File.expand_path(File.join(File.dirname(__FILE__), 'platform', 'darwin'))
-    end
-
-    def require_windows
-      require File.expand_path(File.join(File.dirname(__FILE__), 'platform', 'windows'))
-    end
-
-    # Reads the RightScale cloud file and returns its contents
-    def read_cloud_file
-      File.read(File.join(self.filesystem.right_scale_state_dir, 'cloud')) rescue nil
-    end
-
-    # Retrieve platform specific service implementation
-    #
-    # === Parameters
-    # name(Symbol):: Service name, one of :filesystem, :shell, :ssh, :controller, :installer
-    #
-    # === Return
-    # res(Object):: Service instance
-    #
-    # === Raise
-    # RightScale::Exceptions::PlatformError:: If the service is not known
-    def platform_service(name)
-      instance_var = "@#{name.to_s}".to_sym
-      const_name = name.to_s.camelize
+      # Is current platform in the Unix genus?
+      #
+      # @return [TrueClass|FalseClass] true if Unix
+      def unix?
+        genus == :unix
+      end
+
+      # Is current platform Linux?
+      #
+      # @return [TrueClass|FalseClass] true if Linux
+      def linux?
+        species == :linux
+      end
+
+      # Is current platform Darwin?
+      #
+      # @return [TrueClass|FalseClass] true if Darwin
+      def darwin?
+        species == :darwin
+      end
+
+      # Is current platform Windows?
+      #
+      # @return [TrueClass|FalseClass] true if Windows
+      def windows?
+        genus == :windows
+      end
+
+      # Are we on an EC2 cloud instance?
+      #
+      # @deprecated use right_link cloud libraries instead.
+      #
+      # @return [TrueClass|FalseClass] true if EC2
+      def ec2?
+        warn "#{self.class.name}#ec2? is deprecated, use right_link cloud libraries instead.\n#{caller[0,2].join("\n")}"
+        resolve_cloud_type unless @cloud_type
+        @cloud_type == 'ec2'
+      end
+
+      # Are we on an Rackspace cloud instance?
+      #
+      # @deprecated use right_link cloud libraries instead.
+      #
+      # @return [TrueClass|FalseClass] true if Rackspace
+      def rackspace?
+        warn "#{self.class.name}#rackspace? is deprecated, use right_link cloud libraries instead.\n#{caller[0,2].join("\n")}"
+        resolve_cloud_type unless @cloud_type
+        @cloud_type == 'rackspace'
+      end
+
+      # Are we on an Eucalyptus cloud instance?
+      #
+      # @deprecated use right_link cloud libraries instead.
+      #
+      # @return [TrueClass|FalseClass] true if Eucalyptus
+      def eucalyptus?
+        warn "#{self.class.name}#eucalyptus? is deprecated, use right_link cloud libraries instead.\n#{caller[0,2].join("\n")}"
+        resolve_cloud_type unless @cloud_type
+        @cloud_type == 'eucalyptus'
+      end
+
+      # Call platform specific implementation of method whose symbol is returned
+      # by the passed in block. Arguments are passed through.
+      # e.g.
+      #
+      #   Platform.dispatch(2) { :echo }
+      #
+      # will result in 'echo_linux(2)' being executed in self if running on
+      # linux, 'echo_windows(2)' if running on Windows and 'echo_darwin(2)' if
+      # on Mac OS X. Note that the method is run in the instance of the caller.
+      #
+      # @param [Array] args as pass-through arguments
+      #
+      # @yield [] given block should not take any argument and return a symbol
+      #  for the method that should be called.
+      #
+      # @return [Object] result of Platform-specific implementation
+      def dispatch(*args, &blk)
+        raise 'Platform.dispatch requires a block' unless blk
+        binding = blk.binding.eval('self')
+        meth = blk.call
+        target = dispatch_candidates(meth).detect do |candidate|
+          binding.respond_to?(candidate)
+        end
+        raise "No platform dispatch target found in #{binding.class} for " +
+              "'#{meth.inspect}', tried " + dispatch_candidates(meth).join(', ') unless target
+        binding.__send__(target, *args)
+      end
+
+      # @return [Controller] Platform-specific controller object
+      def controller
+        platform_service(:controller)
+      end
+
+      # @return [Filesystem] Platform-specific filesystem config object
+      def filesystem
+        platform_service(:filesystem)
+      end
+
+      # @return [VolumeManager] Platform-specific volume manager config object
+      def volume_manager
+        platform_service(:volume_manager)
+      end
+
+      # @return [Shell] Platform-specific shell information object
+      def shell
+        platform_service(:shell)
+      end
+
+      # @return [Rng] Platform-specific RNG object
+      def rng
+        platform_service(:rng)
+      end
+
+      # @return [Process] Platform-specific process facilities object
+      def process
+        platform_service(:process)
+      end
+
+      # @return [Installer] Platform-specific installer information object
+      def installer
+        platform_service(:installer)
+      end
+
+      # Blocking call to invoke a command line tool used to perform platform-
+      # specific tasks.
+      #
+      # Also provides a consistent interface for mocking command output during
+      # spec testing. Implementations should use this method instead of
+      # embedding popen/backtick calls to assist with testing.
+      #
+      # @param [String] command to run
+      # @param [Hash] options for execution
+      # @option options [TrueClass|FalseClass] :raise_on_failure true to raise on command failure (Default)
+      #
+      # @return [String] output from command or empty
+      #
+      # @raise [CommandError] on failure (by default)
+      def execute(command, options = {})
+        options = { :raise_on_failure => true }.merge(options)
+        raise_on_failure = options[:raise_on_failure]
+        output_text = ''
+        begin
+          output_text = `#{command}`
+          if !$?.success? && options[:raise_on_failure]
+            message = []
+            message << "Command failed with exit code = #{$?.exitstatus}:"
+            message << "> #{command}"
+            error_output_text = output_text.strip
+            message << error_output_text unless error_output_text.empty?
+            e = CommandError.new(message.join("\n"))
+            e.command = command
+            e.status = $?
+            e.output_text = output_text
+            raise e
+          end
+        rescue Errno::ENOENT => e
+          if raise_on_failure
+            raise CommandError, "Command failed: #{e.message}"
+          end
+        end
+        output_text
+      end
+
+      # Base class for platform helpers.
+      class PlatformHelperBase
+
+        private
+
+        # Convenience method for declaring must-be-overridden interfaces.
+        #
+        # @raise [NotImplementedError] always unless overridden
+        def must_be_overridden
+          raise ::NotImplementedError, 'Must be overridden'
+        end
+
+        # Convenience method for executing a command via platform.
+        #
+        # See Platform#execute
+        def execute(cmd, options = {})
+          ::RightScale::Platform.execute(cmd, options)
+        end
+      end
+
+      # Declares various file system APIs.
+      class Filesystem < PlatformHelperBase
+
+        # Is given command available in the PATH?
+        #
+        # @param [String] command_name to be tested
+        #
+        # @return [TrueClass|FalseClass] true if command is in path
+        def has_executable_in_path(command_name)
+          return !!find_executable_in_path(command_name)
+        end
+
+        # Finds the given command name in the PATH. this emulates the 'which'
+        # command from linux (without the terminating newline).
+        #
+        # @param [String] command_name to be tested
+        #
+        # @return [String] path to first matching executable file in PATH or nil
+        def find_executable_in_path(command_name)
+          must_be_overridden
+        end
+
+        # @return [String] directory containing generated agent configuration files
+        def right_agent_cfg_dir
+          must_be_overridden
+        end
+
+        # @return [String] static (time-invariant) state that is common to all RightScale apps/agents
+        def right_scale_static_state_dir
+          must_be_overridden
+        end
+
+        # @return [String] static (time-invariant) state that is specific to RightLink
+        def right_link_static_state_dir
+          must_be_overridden
+        end
+
+        # @return [String] dynamic, persistent runtime state that is specific to RightLink
+        def right_link_dynamic_state_dir
+          must_be_overridden
+        end
+
+        # @return [String] data which is awaiting some kind of later processing
+        def spool_dir
+          must_be_overridden
+        end
+
+        # TEAL TODO description
+        def ssh_cfg_dir
+          must_be_overridden
+        end
+
+        # Cached data from applications. Such data is locally generated as a
+        # result of time-consuming I/O or calculation. The application must
+        # be able to regenerate or restore the data.
+        #
+        # @return [String] cache directory
+        def cache_dir
+          must_be_overridden
+        end
+
+        # @return [String] system logs
+        def log_dir
+          must_be_overridden
+        end
 
-      unless res = self.instance_variable_get(instance_var)
+        # For Unix compatibility; has no significance in Windows
+        #
+        # @return [String] source code directory, for reference purposes and for development
+        def source_code_dir
+          must_be_overridden
+        end
+
+        # @return [String] temporary files.
+        def temp_dir
+          must_be_overridden
+        end
+
+        # @return [String] path to place pid files
+        def pid_dir
+          must_be_overridden
+        end
+
+        # @return [String] installed home (parent of) right_link directory path
+        def right_link_home_dir
+          must_be_overridden
+        end
+
+        # @return [String] path to right link configuration and internal usage scripts
+        def private_bin_dir
+          must_be_overridden
+        end
+
+        # TEAL TODO description
+        def sandbox_dir
+          must_be_overridden
+        end
+
+        # Converts a long path (e.g. "C:/Program Files") to a short path
+        # (e.g. "C:/PROGRA~1") if necessary. See implementation for notes.
+        #
+        # For Windows compatibility; has no significance in Linux
+        #
+        # @param [String] long_path to convert
+        #
+        # @return [String] short path
+        def long_path_to_short_path(long_path)
+          must_be_overridden
+        end
+
+        # Converts slashes in a path to a consistent style.
+        #
+        # For Windows compatibility; has no significance in Linux
+        #
+        # @param [String] path to make pretty
+        # @param [String] native_fs_flag as true if path is pretty for native
+        #   file system (i.e. file system calls more likely to succeed), false
+        #   if pretty for Ruby interpreter (default).
+        #
+        # @return [String] pretty path
+        def pretty_path(path, native_fs_flag = false)
+          must_be_overridden
+        end
+
+        # Ensures a local drive location for the file or folder given by path
+        # by copying to a local temp directory given by name only if the item
+        # does not appear on the home drive. This method is useful because
+        # secure applications refuse to run scripts from network locations, etc.
+        # Replaces any similar files in given temp dir to ensure latest updates.
+        #
+        # For Windows compatibility; has no significance in Linux
+        #
+        # @param [String] path to file or directory to be placed locally
+        # @param [String] temp_dir_name relative to user temp_dir to use only if the file or folder is not on a local drive
+        #
+        # @return [String] local drive path
+        def ensure_local_drive_path(path, temp_dir_name)
+          must_be_overridden
+        end
+
+        # Creates a symlink (if supported by platform).
+        #
+        # @param [String] from_path the path to the real file/directory
+        # @param [String] to_path the path to the symlink to be created
+        #
+        # @return [Fixnum] always 0 as does File.symlink under Linux
+        #
+        # @raise [RightScale::Exceptions::PlatformError] on failure
+        def create_symlink(from_path, to_path)
+          must_be_overridden
+        end
+      end
+
+      # Provides utilities for managing volumes (disks).
+      class VolumeManager < PlatformHelperBase
+
+        # exceptions
+        class ParserError < ::RightScale::Exceptions::PlatformError; end
+        class VolumeError < ::RightScale::Exceptions::PlatformError; end
+
+        # Gets a list of currently visible volumes in the form:
+        # [{:device, :label, :uuid, :type, :filesystem}]
+        #
+        # @param [Hash] conditions to match, if any (Default = no conditions)
+        #
+        # @return [Array] volume info as an array of hashes or empty
+        #
+        # @raise [ParserError] on failure to parse volume list
+        # @raise [VolumeError] on failure to execute `blkid` to obtain raw output
+        def volumes(conditions = nil)
+          must_be_overridden
+        end
+      end # VolumeManager
+
+      # Declares various command shell APIs.
+      class Shell < PlatformHelperBase
+
+        # @return [String] name or path of file reserved for null output redirection
+        def null_output_name
+          must_be_overridden
+        end
+
+        # Fully qualifies a partial script file path to ensure it is executable on
+        # the current platform.
+        #
+        # For Windows compatibility; has no significance in Linux
+        #
+        # @param [String] partial_script_file_path to format
+        # @param [String] default_extension to use if no extension (Default = platform specific)
+        #
+        # @return [String] full script path
+        def format_script_file_name(partial_script_file_path, default_extension = nil)
+          must_be_overridden
+        end
+
+        # Formats an executable command by quoting any of the arguments as needed
+        # and building an executable command string.
+        #
+        # @param [String] executable_file_path full or partial
+        # @param [Array] arguments for executable, if any
+        #
+        # @return [String] executable command string
+        def format_executable_command(executable_file_path, *arguments)
+          must_be_overridden
+        end
+
+        # Formats a shell command using the given script path and arguments.
+        # Provides the path to the executable for the script as needed for the
+        # current platform.
+        #
+        # @param [String] shell_script_file_path shell script file path
+        # @param [Array] arguments for executable, if any
+        #
+        # @return [String] executable command string
+        def format_shell_command(shell_script_file_path, *arguments)
+          must_be_overridden
+        end
+
+        # Formats a ruby command using the given script path and arguments and
+        # the sandbox ruby path.
+        #
+        # @param [String] shell_script_file_path for formatting
+        # @param [Array] arguments for command or empty
+        #
+        # @return [String] executable command string
+        def format_ruby_command(shell_script_file_path, *arguments)
+          return format_executable_command(sandbox_ruby, [shell_script_file_path, arguments])
+        end
+
+        # Appends STDOUT redirection to the given shell command.
+        #
+        # @param [String] cmd to format
+        # @param [String] redirection target (Default = null output)
+        #
+        # @return [String] formatted for redirection
+        def format_redirect_stdout(cmd, target = nil)
+          target ||= null_output_name
+          return cmd + " 1>#{target}"
+        end
+
+        # Appends STDERR redirection to the given shell command.
+        #
+        # @param [String] cmd to format
+        # @param [String] redirection target (Default = null output)
+        #
+        # @return [String] formatted for redirection
+        def format_redirect_stderr(cmd, target = nil)
+          target ||= null_output_name
+          return cmd + " 2>#{target}"
+        end
+
+        # Appends STDERR redirection to the given shell command.
+        #
+        # @param [String] cmd to format
+        # @param [String] redirection target (Default = null output)
+        #
+        # @return [String] formatted for redirection
+        def format_redirect_both(cmd, target = nil)
+          target ||= null_output_name
+          return cmd + " 1>#{target} 2>&1"
+        end
+
+        # @return [String] full path to the RightScale sandboxed ruby executable
+        def sandbox_ruby
+          must_be_overridden
+        end
+
+        # Gets the current system uptime.
+        #
+        # @return [Float] time the machine has been up, in seconds, or 0.0
+        def uptime
+          must_be_overridden
+        end
+
+        # Gets the time at which the system was booted.
+        #
+        # @return [Integer] the UTC timestamp at which the system was booted or nil on failure
+        def booted_at
+          must_be_overridden
+        end
+      end
+
+      # System controller APIs.
+      class Controller < PlatformHelperBase
+
+        # Reboot machine now.
+        #
+        # @return [TrueClass] always true
+        def reboot
+          must_be_overridden
+        end
+
+        # Shutdown machine now.
+        #
+        # @return [TrueClass] always true
+        def shutdown
+          must_be_overridden
+        end
+      end
+
+      # Randomizer APIs.
+      class Rng < PlatformHelperBase
+
+        # Generates a pseudo-random byte string.
+        #
+        # @param [Fixnum] count of bytes
+        #
+        # @return [String] bytes
+        def pseudorandom_bytes(count)
+          must_be_overridden
+        end
+      end
+
+      # Process APIs.
+      class Process < PlatformHelperBase
+
+        # Queries resident/working set size (total memory used by process) for
+        # the process given by identifier (PID).
+        #
+        # @param [Fixnum] pid for query (Default = current process)
+        #
+        # @return [Integer] current set size in KB
+        def resident_set_size(pid = nil)
+          must_be_overridden
+        end
+      end
+
+      # Package installation APIs.
+      class Installer < PlatformHelperBase
+
+        # exceptions
+        class PackageNotFound < ::RightScale::Exceptions::PlatformError; end
+        class PackageManagerNotFound < ::RightScale::Exceptions::PlatformError; end
+
+        # @return [String] installer output or nil
+        attr_accessor :output
+
+        def initialize
+          @output = nil
+        end
+
+        # Install packages based on installed package manager.
+        #
+        # For Unix compatibility; has no significance in Windows
+        #
+        # @param [Array] packages to be installed
+        #
+        # @return [TrueClass] always true
+        #
+        # @raise [RightScale::Exceptions::PlatformError] if not supported by platform
+        # @raise [PackageNotFound] if package is not found
+        # @raise [PackageManagerNotFound] if package manager is not available
+        # @raise [CommandError] on any other command failure
+        def install(packages)
+          must_be_overridden
+        end
+      end
+
+      private
+
+      # Load platform specific implementation
+      def initialize
+        @genus      = nil
+        @species    = nil
+        @filesystem = nil
+        @shell      = nil
+        @ssh        = nil
+        @controller = nil
+        @installer  = nil
+        @flavor     = nil
+        @release    = nil
+        @codename   = nil
+
+        initialize_platform_specific
+      end
+
+      # First-initialization tasks. Also convenient for overriding during
+      # testing on platforms that differ from current platform.
+      def initialize_platform_specific
         load_platform_specific
-        if linux?
-          res = Platform.const_get(const_name).new
-        elsif darwin?
-          res = Platform.const_get(const_name).new
-        elsif windows?
-          res = Platform.const_get(const_name).new
+        initialize_genus
+        initialize_species
+      end
+
+      # Load platform specific implementation
+      #
+      # @return [TrueClass|FalseClass] true if loaded first time, false if already loaded
+      def load_platform_specific
+        # TEAL NOTE the unusal thing about this singleton is that it is
+        # redefined incrementally by first loading the base then the genus then
+        # the species, all of which define parts of the whole.
+        result = require platform_genus_path
+        result = (require platform_species_path) && result
+        result
+      end
+
+      # Performs any platform genus-specific initialization. This method is
+      # invoked only after the current platform's specific implementation has
+      # been loaded.
+      #
+      # @return [TrueClass] always true
+      def initialize_genus
+        raise ::NotImplementedError, 'Must be overridden'
+      end
+
+      # Performs any platform species-specific initialization. This method is
+      # invoked only after the current platform's specific implementation has
+      # been loaded.
+      #
+      # @return [TrueClass] always true
+      def initialize_species
+        raise ::NotImplementedError, 'Must be overridden'
+      end
+
+      # Determines genus/species for current platform.
+      def resolve_taxonomy
+        case ::RbConfig::CONFIG['host_os']
+        when /darwin/i
+          @genus   = :unix
+          @species = :darwin
+        when /linux/i
+          @genus   = :unix
+          @species = :linux
+        when /mingw/i
+          @genus   = :windows
+          @species = :mingw
+        when /mswin/i
+          @genus   = :windows
+          @species = :mswin
+        when /windows|win32|dos|cygwin/i
+          raise ::RightScale::Exceptions::PlatformError,
+                'Unsupported Ruby-on-Windows variant'
+        else
+          raise ::RightScale::Exceptions::PlatformError, 'Unknown platform'
         end
-        self.instance_variable_set(instance_var, res)
+        true
+      end
+
+      # @return [String] path to platform-independent implementation.
+      def platform_base_path
+        ::File.expand_path('../platform', __FILE__)
+      end
+
+      # @return [String] path to platform-specific genus implementation.
+      def platform_genus_path
+        ::File.expand_path("#{genus}/platform", platform_base_path)
+      end
+
+      # @return [String] path to platform-specific species implementation.
+      def platform_species_path
+        ::File.expand_path("#{genus}/#{species}/platform", platform_base_path)
+      end
+
+      # Retrieve platform specific service implementation
+      #
+      # @param [Symbol] name of platform service
+      #
+      # @return [PlatformHelperBase] service instance
+      #
+      # @raise [RightScale::Exceptions::PlatformError] on unknown service
+      def platform_service(name)
+        instance_var = "@#{name.to_s}".to_sym
+        const_name = name.to_s.camelize
+
+        unless res = self.instance_variable_get(instance_var)
+          load_platform_specific
+          if clazz = Platform.const_get(const_name)
+            res = clazz.new
+            self.instance_variable_set(instance_var, res)
+          else
+            raise ::RightScale::Exceptions::PlatformError,
+                  "Unknown platform service: #{name}"
+          end
+        end
+        return res
+      end
+
+      # Determines which cloud we're on by the cheap but simple expedient of
+      # reading the RightScale cloud file.
+      #
+      # @deprecated leverage the right_link cloud libraries for any cloud-
+      #   specific behavior because the behavior of all possible clouds is
+      #   beyond the scope of hard-coded case statements.
+      #
+      # @return [String] cloud type or nil
+      def resolve_cloud_type
+        cloud_file_path = ::File.join(self.filesystem.right_scale_static_state_dir, 'cloud')
+        @cloud_type = ::File.read(cloud_file_path) rescue nil
+        @cloud_type
       end
-      return res
-    end
 
-  end # Platform
+    end # Platform
 
-end # RightScale
+  end # RightScale
 
-# Initialize for current platform
-RightScale::Platform.load_platform_specific
+  # Initialize for current platform and/or force singleton creation on current
+  # thread to avoid any weird threaded initialization issues.
+  ::RightScale::Platform.instance
 
-end # Unless already defined
+end # unless already defined