right_agent 0.5.1

data/lib/right_agent/agent_config.rb

@@ -0,0 +1,403 @@
+#
+# Copyright (c) 2009-2011 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module RightScale
+
+  # Helper methods for accessing RightAgent files, directories, and processes.
+  # Values returned are driven by root_dir, cfg_dir, and pid_dir, which may be set
+  # but have defaults, and secondarily by the contents of the associated agent
+  # configuration file generated by the 'rad' tool.
+  #
+  # The root_dir may be specified to be a list of root directories to be searched
+  # when looking for agent files. It defaults to the current working directory.
+  # A root directory is assumed to contain some or all of the following directories:
+  #   init    - initialization code
+  #   actors  - actor code
+  #   certs   - security certificates and keys
+  #   lib     - additional agent code
+  #   scripts - tools code
+  #
+  # The init directory contains the following initialization code:
+  #   config.yml - static configuration settings for the agent
+  #   init.rb    - code that registers the agent's actors and performs any other
+  #                agent specific initialization such as initializing its
+  #                secure serializer and its command protocol server
+  #
+  # The certs directory contains the x.509 public certificate and keys needed
+  # to sign and encrypt all outgoing messages as well as to check the signature
+  # and decrypt any incoming messages. This directory should contain at least:
+  #   <agent name>.key  - agent's' private key
+  #   <agent name>.cert - agent's' public certificate
+  #   mapper.cert       - mapper's' public certificate
+  #
+  # The scripts directory at a minimum contains the following:
+  #   install.sh - script for installing standard and agent specific tools in /usr/bin
+  #
+  # The cfg_dir is the path to the directory containing a directory for each agent
+  # configured on the local machine (e.g., core, core_2, core_3). Each agent directory
+  # in turn contains a config.yml file generated to contain that agent's current
+  # configuration. The cfg_dir defaults to the platform specific cfg_dir.
+  #
+  # The pid_dir is the path to the directory where agent process id files are stored.
+  # These files are typically named <agent identity>.pid. The pid_dir defaults to the
+  # current to the platform specific pid_dir.
+  module AgentConfig
+
+    # Current agent protocol version
+    PROTOCOL_VERSION = 17
+
+    # Current agent protocol version
+    #
+    # === Return
+    # (Integer):: Protocol version
+    def self.protocol_version
+      PROTOCOL_VERSION
+    end
+
+    # Initialize path to root directory of agent
+    #
+    # === Parameters
+    # dir(String|Array):: Directory path or ordered list of directory paths to be searched
+    #
+    # === Return
+    # (String):: Ordered list of directory paths to be searched
+    def self.root_dir=(dir)
+      @root_dirs = array(dir)
+    end
+
+    # Initialize path to directory containing generated agent configuration files
+    #
+    # === Parameters
+    # dir(String):: Directory path
+    #
+    # === Return
+    # (String):: Directory path
+    def self.cfg_dir=(dir)
+      @cfg_dir = dir
+    end
+
+    # Initialize path to directory containing agent process id files
+    #
+    # === Parameters
+    # dir(String):: Directory path
+    #
+    # === Return
+    # (String):: Directory path
+    def self.pid_dir=(dir)
+      @pid_dir = dir
+    end
+
+    # Root directory path(s)
+    #
+    # === Return
+    # (String|Array):: Individual directory path if only one, otherwise array of paths
+    def self.root_dir
+      (d = root_dirs).size > 1 ? d : d.first
+    end
+
+    # Path to agent init.rb file containing code that registers the agent's actors
+    # and performs any other agent specific initialization such as initializing its
+    # secure serializer and its command protocol server
+    #
+    # === Return
+    # (String|nil):: File path name, or nil if file does not exist
+    def self.init_file
+      first_file(:init_dir, "init.rb")
+    end
+
+    # Path to agent config.yml file containing static configuration settings
+    #
+    # === Return
+    # (String|nil):: File path name, or nil if file does not exist
+    def self.init_cfg_file
+      first_file(:init_dir, "config.yml")
+    end
+
+    # Ordered list of directory path names for searching for actors:
+    #  - actors directory in each configured root directory
+    #  - other directories produced by other_actors_dirs method, e.g., in other associated gems
+    #  - actors directory in RightAgent gem
+    #
+    # === Return
+    # actors_dirs(Array):: List of directory path names
+    def self.actors_dirs
+      actors_dirs = all_dirs(:actors_dir)
+      actors_dirs += other_actors_dirs if self.respond_to?(:other_actors_dirs)
+      actors_dirs << File.normalize_path(File.join(File.dirname(__FILE__), 'actors'))
+      actors_dirs
+    end
+
+    # Path to directory containing certificates
+    #
+    # === Parameters
+    # root_dir(String|nil):: Specific root dir to use (must be in root_dirs),
+    #   if nil use first dir in root_dirs
+    #
+    # === Return
+    # (String|nil):: Path to certs directory, or nil if cannot determine root_dir
+    def self.certs_dir(root_dir = nil)
+      if root_dir
+        root_dir = nil unless @root_dirs && @root_dirs.include?(root_dir)
+      else
+        root_dir = @root_dirs.first if @root_dirs
+      end
+      File.normalize_path(File.join(root_dir, "certs")) if root_dir
+    end
+
+    # Path to security file containing X.509 data
+    #
+    # === Parameters
+    # name(String):: Security file name
+    #
+    # === Return
+    # file(String|nil):: File path name, or nil if file does not exist
+    def self.certs_file(name)
+      first_file(:certs_dir, name)
+    end
+
+    # All security files matching pattern
+    #
+    # === Parameters
+    # pattern(String):: Pattern for security files of interest, e.g., '*.cert'
+    #
+    # === Return
+    # files(Array):: Path name of files found
+    def self.certs_files(pattern)
+      files = []
+      names = []
+      all_dirs(:certs_dir).each do |d|
+        certs = Dir.glob(File.join(d, pattern)).each do |f|
+          unless names.include?(b = File.basename(f))
+            files << f
+            names << b
+          end
+        end
+      end
+      files
+    end
+
+    # Path to first agent lib directory
+    #
+    # === Return
+    # dir(String):: Directory path name
+    def self.lib_dir
+      all_dirs(:lib_dir2).first
+    end
+
+    # Path to first agent scripts directory
+    #
+    # === Return
+    # dir(String):: Directory path name
+    def self.scripts_dir
+      all_dirs(:scripts_dir2).first
+    end
+
+    # Path to directory containing a directory for each agent configured on the local machine
+    #
+    # === Return
+    # (String):: Directory path name
+    def self.cfg_dir
+      @cfg_dir ||= Platform.filesystem.cfg_dir
+    end
+
+    # Path to generated agent configuration file
+    #
+    # === Parameters
+    # agent_name(String):: Agent name
+    # exists(Boolean):: Whether to return nil if does not exist
+    #
+    # === Return
+    # (String):: Configuration file path name, or nil if file does not exist
+    def self.cfg_file(agent_name, exists = false)
+      file = File.normalize_path(File.join(cfg_dir, agent_name, "config.yml"))
+      file = nil unless !exists || File.exist?(file)
+      file
+    end
+
+    # Configuration file path names for all agents configured locally
+    #
+    # === Return
+    # (Array):: Agent configuration file path names
+    def self.cfg_files
+      Dir.glob(File.join(cfg_dir, "**", "*.yml"))
+    end
+
+    # Configured agents i.e. agents that have a configuration file
+    #
+    # === Return
+    # (Array):: Name of configured agents
+    def self.cfg_agents
+      cfg_files.map { |c| File.basename(File.dirname(c)) }
+    end
+
+    # Agent name associated with given agent identity
+    #
+    # === Parameters
+    # agent_id(String):: Serialized agent identity
+    #
+    # === Return
+    # (String|nil):: Agent name, or nil if agent not found
+    def self.agent_name(agent_id)
+      cfg_agents.each do |a|
+        if (options = agent_options(a)) && options[:identity] == agent_id
+          return a
+        end
+      end
+      nil
+    end
+
+    # Get options from agent's configuration file
+    #
+    # === Parameters
+    # agent_name(String):: Agent name
+    #
+    # === Return
+    # (Hash|nil):: Agent options with key names symbolized,
+    #   or nil if file not accessible or empty
+    def self.load_cfg(agent_name)
+      if (file = cfg_file(agent_name, exists = true)) && File.readable?(file) && (cfg = YAML.load(IO.read(file)))
+        SerializationHelper.symbolize_keys(cfg)
+      end
+    end
+
+    # Write agent's configuration to file
+    #
+    # === Parameters
+    # agent_name(String):: Agent name
+    # cfg(Hash):: Configuration options
+    #
+    # === Return
+    # file(String):: Configuration file path name
+    def self.store_cfg(agent_name, cfg)
+      file = cfg_file(agent_name)
+      FileUtils.mkdir_p(File.dirname(file))
+      File.delete(file) if File.exists?(file)
+      File.open(file, 'w') do |fd|
+        fd.puts "# Created at #{Time.now}"
+        fd.write(YAML.dump(cfg))
+      end
+      file
+    end
+
+    # Path to directory containing agent process id files
+    #
+    # === Return
+    # (String):: Directory path name
+    def self.pid_dir
+      @pid_dir ||= Platform.filesystem.pid_dir
+    end
+
+    # Retrieve agent process id file
+    #
+    # === Parameters
+    # agent_name(String):: Agent name
+    #
+    # === Return
+    # (PidFile|nil):: Process id file, or nil if there is no configuration file for agent
+    def self.pid_file(agent_name)
+      if options = load_cfg(agent_name)
+        PidFile.new(options[:identity], options[:pid_dir])
+      end
+    end
+
+    # Agent options from generated agent configuration file
+    # and agent process id file if they exist
+    # Reset root_dir and pid_dir to one found in agent configuration file
+    #
+    # === Parameters
+    # agent_name(String):: Agent name
+    #
+    # === Return
+    # options(Hash):: Agent options including
+    #   :identity(String):: Serialized agent identity
+    #   :log_path(String):: Path to directory for agent log file
+    #   :pid(Integer):: Agent process pid if available
+    #   :listen_port(Integer):: Agent command listen port if available
+    #   :cookie(String):: Agent command cookie if available
+    def self.agent_options(agent_name)
+      if options = load_cfg(agent_name)
+        @root_dirs = array(options[:root_dir])
+        @pid_dir = options[:pid_dir]
+        options[:log_path] = options[:log_dir] || Platform.filesystem.log_dir
+        pid_file = PidFile.new(options[:identity])
+        options.merge!(pid_file.read_pid) if pid_file.exists?
+      end
+      options || {}
+    end
+
+    protected
+
+    # Convert value to array if not an array, unless nil
+    def self.array(value)
+      (value.nil? || value.is_a?(Array)) ? value : [value]
+    end
+
+    # Ordered list of root directories
+    def self.root_dirs
+      @root_dirs || [Dir.pwd]
+    end
+
+    # Path to agent directory containing initialization files
+    def self.init_dir(root_dir)
+      File.normalize_path(File.join(root_dir, "init"))
+    end
+
+    # Path to directory containing actor source files
+    def self.actors_dir(root_dir)
+      File.normalize_path(File.join(root_dir, "actors"))
+    end
+
+    # Path to agent directory containing code
+    def self.lib_dir2(root_dir)
+      File.normalize_path(File.join(root_dir, "lib"))
+    end
+
+    # Path to agent directory containing scripts
+    def self.scripts_dir2(root_dir)
+      File.normalize_path(File.join(root_dir, "scripts"))
+    end
+
+    # All existing directories of given type
+    def self.all_dirs(type)
+      dirs = []
+      root_dirs.each do |d|
+        c = self.__send__(type, d)
+        dirs << c if File.directory?(c)
+      end
+      dirs
+    end
+
+    # Path name of first file found of given type and name, or nil if none found
+    def self.first_file(type, name)
+      file = nil
+      root_dirs.each do |d|
+        if File.exist?(f = File.join(self.__send__(type, d), name))
+          file = f
+          break
+        end
+      end
+      file
+    end
+
+  end # AgentConfig
+
+end # RightScale

data/lib/right_agent/agent_identity.rb

@@ -0,0 +1,209 @@
+#
+# Copyright (c) 2009-2011 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module RightScale
+  
+  # Agent identity management
+  class AgentIdentity
+
+    # Cutover time at which agents began using new separator
+    SEPARATOR_EPOCH = Time.at(1256702400) unless defined?(SEPARATOR_EPOCH) # Tue Oct 27 21:00:00 -0700 2009
+
+    # Separator used to differentiate between identity components when serialized
+    ID_SEPARATOR = '-' unless defined?(ID_SEPARATOR)
+
+    # Separator used to differentiate between identity components prior to release 3.4
+    ID_SEPARATOR_OLD = '*' unless defined?(ID_SEPARATOR_OLD)
+
+    # Identity components
+    attr_reader :prefix, :agent_type, :token, :base_id
+
+    # Generate new id
+    #
+    # === Parameters
+    # prefix(String):: Prefix used to scope identity
+    # agent_type(String):: Agent type (e.g. 'core', 'instance')
+    # base_id(Integer):: Unique integer value
+    # token(String):: Unique identity token, will be generated randomly if not provided
+    # separator(String):: Character used to separate identity components, defaults to ID_SEPARATOR
+    #
+    # === Raise
+    # RightScale::Exceptions::Argument:: Invalid argument
+    def initialize(prefix, agent_type, base_id, token=nil, separator=nil)
+      err = "Prefix cannot contain '#{ID_SEPARATOR}'" if prefix && prefix.include?(ID_SEPARATOR)
+      err = "Prefix cannot contain '#{ID_SEPARATOR_OLD}'" if prefix && prefix.include?(ID_SEPARATOR_OLD)
+      err = "Agent type cannot contain '#{ID_SEPARATOR}'" if agent_type.include?(ID_SEPARATOR)
+      err = "Agent type cannot contain '#{ID_SEPARATOR_OLD}'" if agent_type.include?(ID_SEPARATOR_OLD)
+      err = "Agent type cannot be nil" if agent_type.nil?
+      err = "Agent type cannot be empty" if agent_type.size == 0
+      err = "Base ID must be a positive integer" unless base_id.kind_of?(Integer) && base_id >= 0
+      err = "Token cannot contain '#{ID_SEPARATOR}'" if token && token.include?(ID_SEPARATOR)
+      err = "Token cannot contain '#{ID_SEPARATOR_OLD}'" if token && token.include?(ID_SEPARATOR_OLD)
+      raise RightScale::Exceptions::Argument, err if err
+
+      @separator  = separator || ID_SEPARATOR
+      @prefix     = prefix
+      @agent_type = agent_type
+      @token      = token || self.class.generate
+      @base_id    = base_id
+    end
+
+    # Generate unique identity
+    #
+    # === Return
+    # id(String):: Random 128-bit hexadecimal string
+    def self.generate
+      bytes = Platform.rng.pseudorandom_bytes(16)
+      #Transform into hex string
+      id = bytes.unpack('H*')[0]
+    end
+
+    # Check validity of given serialized identity
+    #
+    # === Parameters
+    # serialized_id(String):: Serialized identity to be tested
+    #
+    # === Return
+    # (Boolean):: true if serialized identity is a valid, otherwise false
+    def self.valid?(serialized_id)
+      valid_parts?(self.compatible_serialized(serialized_id)) if serialized_id
+    end
+    
+    # Instantiate by parsing given token
+    #
+    # === Parameters
+    # serialized_id(String):: Valid serialized agent identity (use 'valid?' to check first)
+    #
+    # === Return
+    # (AgentIdentity):: Corresponding agent identity
+    #
+    # === Raise
+    # (RightScale::Exceptions::Argument):: Serialized agent identity is incorrect
+    def self.parse(serialized_id)
+      serialized_id = self.compatible_serialized(serialized_id)
+      prefix, agent_type, token, bid, separator = parts(serialized_id)
+      raise RightScale::Exceptions::Argument, "Invalid agent identity token" unless prefix && agent_type && token && bid
+      base_id = bid.to_i
+      raise RightScale::Exceptions::Argument, "Invalid agent identity token (Base ID)" unless base_id.to_s == bid
+
+      AgentIdentity.new(prefix, agent_type, base_id, token, separator)
+    end
+
+    # Convert serialized agent identity to format valid for given protocol version
+    # Ignore identity that is not in serialized AgentIdentity format
+    #
+    # === Parameters
+    # serialized_id(String):: Serialized agent identity to be converted
+    # version(Integer):: Target protocol version
+    #
+    # === Return
+    # serialized_id(String):: Compatible serialized agent identity
+    def self.compatible_serialized(serialized_id, version = 10)
+      if version < 10
+        serialized_id = "nanite-#{serialized_id}" if self.valid_parts?(serialized_id)
+      else
+        serialized_id = serialized_id[7..-1] if serialized_id =~ /^nanite-|^mapper-/
+      end
+      serialized_id
+    end
+
+    # Check whether identity corresponds to an instance agent
+    #
+    # === Return
+    # (Boolean):: true if id corresponds to an instance agent, otherwise false
+    def instance_agent?
+      agent_type == 'instance'
+    end
+
+    # Check whether identity corresponds to an instance agent
+    #
+    # === Parameters
+    # serialized_id(String):: Valid serialized agent identity (use 'valid?' to check first)
+    #
+    # === Return
+    # (Boolean):: true if id corresponds to an instance agent, otherwise false
+    def self.instance_agent?(serialized_id)
+      parts(serialized_id)[1] == 'instance'
+    end
+
+    # String representation of identity
+    #
+    # === Return
+    # (String):: Serialized identity
+    def to_s
+      "#{@prefix}#{@separator}#{@agent_type}#{@separator}#{@token}#{@separator}#{@base_id}"
+    end
+
+    # Comparison operator
+    #
+    # === Parameters
+    # other(AgentIdentity):: Other agent identity
+    #
+    # === Return
+    # (Boolean):: true if other is identical to self, otherwise false
+    def ==(other)
+      other.kind_of?(::RightScale::AgentIdentity) &&
+      prefix     == other.prefix     &&
+      agent_type == other.agent_type &&
+      token      == other.token      &&
+      base_id    == other.base_id
+    end
+
+    protected
+
+    # Split given serialized id into its parts
+    #
+    # === Parameters
+    # serialized_id(String):: Valid serialized agent identity (use 'valid?' to check first)
+    #
+    # === Return
+    # (Array):: Array of parts: prefix, agent type, token, base id and separator
+    def self.parts(serialized_id)
+      prefix = agent_type = token = bid = separator = nil
+      if serialized_id.include?(ID_SEPARATOR)
+        prefix, agent_type, token, bid = serialized_id.split(ID_SEPARATOR)
+        separator = ID_SEPARATOR
+      elsif serialized_id.include?(ID_SEPARATOR_OLD)
+        prefix, agent_type, token, bid = serialized_id.split(ID_SEPARATOR_OLD)
+        separator = ID_SEPARATOR_OLD
+      end
+      [ prefix, agent_type, token, bid, separator ]
+    end
+
+    # Check that given serialized identity has valid parts
+    #
+    # === Parameters
+    # serialized_id(String):: Serialized identity to be tested
+    #
+    # === Return
+    # (Boolean):: true if serialized identity is a valid identity token, otherwise false
+    def self.valid_parts?(serialized_id)
+      p = parts(serialized_id)
+      res = p.size == 5 &&
+            p[1] && p[1].size > 0 &&
+            p[2] && p[2].size > 0 &&
+            p[3] && p[3].to_i.to_s == p[3]
+    end
+
+  end # AgentIdentity
+
+end # RightScale