right_agent 0.5.1

data/LICENSE

@@ -0,0 +1,20 @@
+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.

data/README.rdoc

@@ -0,0 +1,78 @@
+= RightAgent
+
+= DESCRIPTION
+
+== Synopsis
+
+RightAgent provides a foundation for running an agent on a server to interface
+in a secure fashion with other agents in the RightScale system. A RightAgent
+uses RabbitMQ as the message bus and the RightScale mapper as the routing node.
+Servers running a RightAgent establish a queue on startup for receiving packets
+routed to it via the mapper. The packets are structured to invoke services in
+the agent represented by actors and methods. The RightAgent may respond to these
+requests with a result packet that the mapper then routes to the originator.
+Similarly a RightAgent can also make requests of other RightAgents in the
+RightScale system.
+
+Refer to the wiki (https://github.com/rightscale/right_agent/wikis) for up-to-date
+documentation.
+
+Also use the built-in issues tracker (https://github.com/rightscale/right_agent/issues)
+to report issues.
+
+== Interface
+
+A RightAgent exposes its services via actors and methods that are invoked by requests
+packets it receives via its message queue. All RightAgents have a general purpose actor
+named agent_manager that provides the following services:
+
+* <b>agent_manager/ping</b>: Respond with basic status information to indicate that active
+* <b>agent_manager/stats</b>: Retrieve statistics about agent operation
+* <b>agent_manager/set_log_level</b>: Change log level of agent
+* <b>agent_manager/execute</b>: Eval code in context of agent
+* <b>agent_manager/connect</b>: Connect agent to additional broker or reconnect it to one
+* <b>agent_manager/disconnect</b>: Disconnect agent from broker
+
+RightAgent comes with several library modules for forming basic command line tools:
+
+* <b>agent_deployer</b>: Build a configuration file for running the agent (rad tool)
+* <b>agent_controller</b>: Manage an agent that has been configured (rnac tool)
+* <b>stats_manager</b>: Display operation statistics for an agent (rstat tool)
+* <b>log_level_manager</b>: Retrieve and set log level for an agent (rlog tool)
+
+== Supported Configuration
+
+RightAgent has been tested on EC2 instances running CentOS 5.2 and Ubuntu 8.10.
+
+== Work in Progress
+
+RightAgent is work in progress, expect more documentation and examples in the near future.
+
+= ADDITIONAL RESOURCES
+
+* [1] RabbitMQ is http://www.rabbitmq.com/documentation.html
+
+= LICENSE
+
+<b>RightAgent</b>
+
+Copyright:: Copyright (c) 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.

data/Rakefile

@@ -0,0 +1,86 @@
+#--  -*-ruby-*-
+# Copyright: Copyright (c) 2010 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.
+#++
+
+require 'rubygems'
+require 'bundler/setup'
+require 'fileutils'
+require 'rake'
+require 'rspec/core/rake_task'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/clean'
+
+task :default => 'spec'
+
+# == Gem packaging == #
+
+desc "Package gem"
+gemtask = Rake::GemPackageTask.new(Gem::Specification.load("right_agent.gemspec")) do |package|
+  package.package_dir = ENV['PACKAGE_DIR'] || 'pkg'
+  package.need_zip = true
+  package.need_tar = true
+end
+
+directory gemtask.package_dir
+
+CLEAN.include(gemtask.package_dir)
+
+# == Unit tests == #
+
+RSPEC_OPTS = ['--options', "\"#{File.dirname(__FILE__)}/spec/spec.opts\""]
+
+desc 'Run unit tests'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = RSPEC_OPTS
+end
+
+namespace :spec do
+  desc 'Run unit tests with RCov'
+  RSpec::Core::RakeTask.new(:rcov) do |t|
+    t.rspec_opts = RSPEC_OPTS
+    t.rcov = true
+    t.rcov_opts = %q[--exclude "spec"]
+  end
+
+  desc 'Print Specdoc for all unit tests'
+  RSpec::Core::RakeTask.new(:doc) do |t|
+    t.rspec_opts = ["--format", "documentation"]
+  end
+end
+
+# == Documentation == #
+
+desc 'Generate API documentation to doc/rdocs/index.html'
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'doc/rdocs'
+  rd.main = 'README.rdoc'
+  rd.rdoc_files.include 'README.rdoc', 'lib/**/*.rb'
+end
+CLEAN.include('doc/rdocs')
+
+# == Emacs integration ==
+
+desc 'Rebuild TAGS file for emacs'
+task :tags do
+  sh 'rtags -R lib spec'
+end

data/lib/right_agent.rb

@@ -0,0 +1,66 @@
+#
+# 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.
+
+require 'rubygems'
+require 'amqp'
+require 'mq'
+require 'json'
+require 'yaml'
+require 'openssl'
+
+# Cannot use File.normalize_path here because not defined until after this include
+require File.expand_path(File.join(File.dirname(__FILE__), 'right_agent', 'platform'))
+
+unless defined?(RIGHT_AGENT_BASE_DIR)
+  RIGHT_AGENT_BASE_DIR = File.normalize_path(File.join(File.dirname(__FILE__), 'right_agent'))
+end
+
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'monkey_patches'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'agent_config'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'payload_formatter'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'packets'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'enrollment_result'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'console'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'daemonize'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'pid_file'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'exceptions'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'multiplexer'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'log'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'tracer'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'audit_formatter'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'serialize'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'security'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'operation_result'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'subprocess'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'stats_helper'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'broker_client'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'ha_broker_client'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'command'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'agent_identity'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'agent_tags_manager'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'actor'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'actor_registry'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'dispatcher'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'sender'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'secure_identity'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'idempotent_request'))
+require File.normalize_path(File.join(RIGHT_AGENT_BASE_DIR, 'agent'))

data/lib/right_agent/actor.rb

@@ -0,0 +1,163 @@
+#
+# 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
+
+  # This mixin provides agent actor functionality.
+  #
+  # To use it simply include it your class containing the functionality to be exposed:
+  #
+  #   class Foo
+  #     include RightScale::Actor
+  #     expose :bar
+  #
+  #     def bar(payload)
+  #       # ...
+  #     end
+  #
+  #   end
+  module Actor
+
+    # Callback invoked whenever Actor is included in another module or class.
+    #
+    # === Parameters
+    # base(Module):: Module that included Actor module
+    #
+    # === Return
+    # true:: Always return true
+    def self.included(base)
+      base.send :include, InstanceMethods
+      base.extend(ClassMethods)
+    end
+    
+    module ClassMethods
+
+      # Construct default prefix by which actor is identified in requests
+      #
+      # === Return
+      # prefix(String):: Default prefix
+      def default_prefix
+        prefix = to_s.to_const_path
+      end
+
+      # Add methods to list of services supported by actor
+      #
+      # === Parameters
+      # meths(Array):: Symbol names for methods being exposed as actor services
+      #
+      # === Return
+      # @exposed(Array):: List of unique methods exposed
+      def expose(*meths)
+        @exposed ||= []
+        meths.each do |meth|
+          @exposed << meth unless @exposed.include?(meth)
+        end
+        @exposed
+      end
+
+      # Get /prefix/method paths that actor responds to
+      #
+      # === Parameters
+      # prefix(String):: Prefix by which actor is identified in requests
+      #
+      # === Return
+      # (Array):: /prefix/method strings
+      def provides_for(prefix)
+        return [] unless @exposed
+        @exposed.select do |meth|
+          if instance_methods.include?(meth.to_s) or instance_methods.include?(meth.to_sym)
+            true
+          else
+            Log.warning("Exposing non-existing method #{meth} in actor #{name}")
+            false
+          end
+        end.map {|meth| "/#{prefix}/#{meth}".squeeze('/')}
+      end
+
+      # Set method called when dispatching to this actor fails
+      #
+      # The callback method is required to accept the following parameters:
+      #   method(Symbol):: Actor method being dispatched to
+      #   deliverable(Packet):: Packet delivered to dispatcher
+      #   exception(Exception):: Exception raised
+      #
+      # === Parameters
+      # proc(Proc|Symbol|String):: Procedure to be called on exception
+      #
+      # === Block
+      # Block to be executed if no Proc provided
+      #
+      # === Return
+      # @exception_callback(Proc):: Callback procedure
+      def on_exception(proc = nil, &blk)
+        raise 'No callback provided for on_exception' unless proc || blk
+        @exception_callback = proc || blk
+      end
+
+      # Get exception callback procedure
+      #
+      # === Return
+      # @exception_callback(Proc):: Callback procedure
+      def exception_callback
+        @exception_callback
+      end
+      
+    end # ClassMethods     
+    
+    module InstanceMethods
+
+      # Agents using actors are required to define a Sender class providing linkage
+      # to a class that can perform the following send functions
+
+      # Helper method to send a request to one or more targets with no response expected
+      def send_push(*args)
+        Sender.instance.send_push(*args)
+      end
+
+      # Helper method to send a request to one or more targets with no response expected
+      # The request is persisted en route to reduce the chance of it being lost at the expense of some
+      # additional network overhead
+      def send_persistent_push(*args)
+        Sender.instance.send_persistent_push(*args)
+      end
+
+      # Helper method to send a request to a single target with a response expected
+      # The request is retried if the response is not received in a reasonable amount of time
+      # The request is timed out if not received in time, typically configured to 2 minutes
+      # The request is allowed to expire per the agent's configured time-to-live, typically 1 minute
+      def send_retryable_request(*args, &blk)
+        Sender.instance.send_retryable_request(*args, &blk)
+      end
+
+      # Helper method to send a request to a single target with a response expected
+      # The request is persisted en route to reduce the chance of it being lost at the expense of some
+      # additional network overhead
+      # The request is never retried if there is the possibility of it being duplicated
+      def send_persistent_request(*args, &blk)
+        Sender.instance.send_persistent_request(*args, &blk)
+      end
+
+    end # InstanceMethods
+    
+  end # Actor
+  
+end # RightScale

data/lib/right_agent/actor_registry.rb

@@ -0,0 +1,76 @@
+#
+# 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
+
+  class ActorRegistry
+
+    # (Hash) Actors that are registered; key is actor prefix and value is actor
+    attr_reader :actors
+
+    # Initialize registry
+    def initialize
+      @actors = {}
+    end
+
+    # Register as an actor
+    #
+    # === Parameters
+    # actor(Actor):: Actor to be registered
+    # prefix(String):: Prefix used in request to identify actor
+    #
+    # === Return
+    # (Actor):: Actor registered
+    #
+    # === Raises
+    # ArgumentError if actor is not an Actor
+    def register(actor, prefix)
+      raise ArgumentError, "#{actor.inspect} is not a RightScale::Actor subclass instance" unless RightScale::Actor === actor
+      log_msg = "[actor] #{actor.class.to_s}"
+      log_msg += ", prefix #{prefix}" if prefix && !prefix.empty?
+      Log.info(log_msg)
+      prefix ||= actor.class.default_prefix
+      actors[prefix.to_s] = actor
+    end
+
+    # Retrieve services provided by all of the registered actors
+    #
+    # === Return
+    # services(Array):: List of unique /prefix/method path strings
+    def services
+      actors.map {|prefix, actor| actor.class.provides_for(prefix) }.flatten.uniq
+    end
+
+    # Retrieve actor by prefix
+    #
+    # === Parameters
+    # prefix(String):: Prefix identifying actor
+    #
+    # === Return
+    # actor(Actor):: Retrieved actor, may be nil
+    def actor_for(prefix)
+      actor = actors[prefix]
+    end
+
+  end # ActorRegistry
+
+end # RightScale