rightscale-nanite 0.4.1 → 0.4.1.1

data/lib/nanite/identity.rb

@@ -0,0 +1,16 @@
+module Nanite
+  module Identity
+    def self.generate
+      values = [
+        rand(0x0010000),
+        rand(0x0010000),
+        rand(0x0010000),
+        rand(0x0010000),
+        rand(0x0010000),
+        rand(0x1000000),
+        rand(0x1000000),
+      ]
+      "%04x%04x%04x%04x%04x%06x%06x" % values
+    end
+  end
+end

data/lib/nanite/job.rb

@@ -0,0 +1,104 @@
+module Nanite
+  class JobWarden
+    attr_reader :serializer, :jobs
+
+    def initialize(serializer)
+      @serializer = serializer
+      @jobs = {}
+    end
+
+    def new_job(request, targets, inthandler = nil, blk = nil)
+      job = Job.new(request, targets, inthandler, blk)
+      jobs[job.token] = job
+      job
+    end
+
+    def process(msg)
+      Nanite::Log.debug("processing message: #{msg.inspect}")
+
+      if job = jobs[msg.token]
+        job.process(msg)
+
+        if job.intermediate_handler && (job.pending_keys.size > 0)
+
+          unless job.pending_keys.size == 1
+            raise "IntermediateMessages are currently dispatched as they arrive, shouldn't have more than one key in pending_keys: #{job.pending_keys.inspect}"
+          end
+
+          key = job.pending_keys.first
+          handler = job.intermediate_handler_for_key(key)
+          if handler
+            case handler.arity
+            when 3
+              handler.call(key, msg.from, job.intermediate_state[msg.from][key].last)
+            when 4
+              handler.call(key, msg.from, job.intermediate_state[msg.from][key].last, job)
+            end
+          end
+
+          job.reset_pending_intermediate_state_keys
+        end
+
+        if job.completed?
+          jobs.delete(job.token)
+          if job.completed
+            case job.completed.arity
+            when 1
+              job.completed.call(job.results)
+            when 2
+              job.completed.call(job.results, job)
+            end
+          end
+        end
+      end
+    end
+  end # JobWarden
+
+  class Job
+    attr_reader :results, :request, :token, :completed, :intermediate_state, :pending_keys, :intermediate_handler
+    attr_accessor :targets # This can be updated when a request gets picked up from the offline queue
+
+    def initialize(request, targets, inthandler = nil, blk = nil)
+      @request = request
+      @targets = targets
+      @token = @request.token
+      @results = {}
+      @intermediate_handler = inthandler
+      @pending_keys = []
+      @completed = blk
+      @intermediate_state = {}
+    end
+
+    def process(msg)
+      case msg
+      when Result
+        results[msg.from] = msg.results
+        targets.delete(msg.from)
+      when IntermediateMessage
+        intermediate_state[msg.from] ||= {}
+        intermediate_state[msg.from][msg.messagekey] ||= []
+        intermediate_state[msg.from][msg.messagekey] << msg.message
+        @pending_keys << msg.messagekey
+      end
+    end
+
+    def intermediate_handler_for_key(key)
+      return nil unless @intermediate_handler
+      case @intermediate_handler
+      when Proc
+        @intermediate_handler
+      when Hash
+        @intermediate_handler[key] || @intermediate_handler['*']
+      end
+    end
+
+    def reset_pending_intermediate_state_keys
+      @pending_keys = []
+    end
+
+    def completed?
+      targets.empty?
+    end
+  end # Job
+
+end # Nanite

data/lib/nanite/local_state.rb

@@ -0,0 +1,34 @@
+module Nanite
+  class LocalState < ::Hash
+    def initialize(hsh={})
+      hsh.each do |k,v|
+        self[k] = v
+      end
+    end
+
+    def all_services
+      all(:services)
+    end
+
+    def all_tags
+      all(:tags)
+    end
+
+    def nanites_for(service, *tags)
+      tags = tags.dup.flatten
+      nanites = select { |name, state| state[:services].include?(service) }
+      unless tags.empty?
+        nanites.select { |a| !(a[1][:tags] & tags).empty? }
+      else
+        nanites
+      end
+    end
+
+    private
+
+    def all(key)
+      map { |n,s| s[key] }.flatten.uniq.compact
+    end
+
+  end # LocalState
+end # Nanite

data/lib/nanite/log.rb

@@ -0,0 +1,64 @@
+require 'nanite/config'
+require 'nanite/log/formatter'
+require 'logger'
+
+module Nanite
+  class Log
+  
+    @logger = nil
+    
+    class << self
+      attr_accessor :logger, :level, :file #:nodoc
+      
+      # Use Nanite::Logger.init when you want to set up the logger manually.
+      # If this method is called with no arguments, it will log to STDOUT at the :info level.
+      # It also configures the Logger instance it creates to use the custom Nanite::Log::Formatter class.
+      def init(identity, path = false)
+        if path
+          @file = File.join(path, "nanite.#{identity}.log")
+        else
+          @file = STDOUT
+        end
+        @logger = Logger.new(file)
+        @logger.formatter = Nanite::Log::Formatter.new
+        level = @log_level = :info
+      end
+      
+      # Sets the level for the Logger by symbol or by command line argument.
+      # Throws an ArgumentError if you feed it a bogus log level (that is not
+      # one of :debug, :info, :warn, :error, :fatal or the corresponding strings)
+      def level=(loglevel)
+        init() unless @logger
+        loglevel = loglevel.intern if loglevel.is_a?(String)
+        @logger.info("Setting log level to #{loglevel.to_s.upcase}")
+        case loglevel
+        when :debug
+          @logger.level = Logger::DEBUG
+        when :info
+          @logger.level = Logger::INFO
+        when :warn
+          @logger.level = Logger::WARN
+        when :error
+          @logger.level = Logger::ERROR
+        when :fatal
+          @logger.level = Logger::FATAL
+        else
+          raise ArgumentError, "Log level must be one of :debug, :info, :warn, :error, or :fatal"
+        end
+      end
+      
+      # Passes any other method calls on directly to the underlying Logger object created with init. If
+      # this method gets hit before a call to Nanite::Logger.init has been made, it will call 
+      # Nanite::Logger.init() with no arguments.
+      def method_missing(method_symbol, *args)
+        init(identity) unless @logger
+        if args.length > 0
+          @logger.send(method_symbol, *args)
+        else
+          @logger.send(method_symbol)
+        end
+      end
+      
+    end # class << self
+  end
+end

data/lib/nanite/log/formatter.rb

@@ -0,0 +1,39 @@
+require 'logger'
+require 'time'
+
+module Nanite
+  class Log
+    class Formatter < Logger::Formatter
+      @@show_time = true
+      
+      def self.show_time=(show=false)
+        @@show_time = show
+      end
+      
+      # Prints a log message as '[time] severity: message' if Nanite::Log::Formatter.show_time == true.
+      # Otherwise, doesn't print the time.
+      def call(severity, time, progname, msg)
+        if @@show_time
+          sprintf("[%s] %s: %s\n", time.rfc2822(), severity, msg2str(msg))
+        else
+          sprintf("%s: %s\n", severity, msg2str(msg))
+        end
+      end
+      
+      # Converts some argument to a Logger.severity() call to a string.  Regular strings pass through like
+      # normal, Exceptions get formatted as "message (class)\nbacktrace", and other random stuff gets 
+      # put through "object.inspect"
+      def msg2str(msg)
+        case msg
+        when ::String
+          msg
+        when ::Exception
+          "#{ msg.message } (#{ msg.class })\n" <<
+            (msg.backtrace || []).join("\n")
+        else
+          msg.inspect
+        end
+      end
+    end
+  end
+end

data/lib/nanite/mapper.rb

@@ -0,0 +1,277 @@
+module Nanite
+  # Mappers are control nodes in nanite clusters. Nanite clusters
+  # can follow peer-to-peer model of communication as well as client-server,
+  # and mappers are nodes that know who to send work requests to agents.
+  #
+  # Mappers can reside inside a front end web application written in Merb/Rails
+  # and distribute heavy lifting to actors that register with the mapper as soon
+  # as they go online.
+  #
+  # Each mapper tracks nanites registered with it. It periodically checks
+  # when the last time a certain nanite sent a heartbeat notification,
+  # and removes those that have timed out from the list of available workers.
+  # As soon as a worker goes back online again it re-registers itself
+  # and the mapper adds it to the list and makes it available to
+  # be called again.
+  #
+  # This makes Nanite clusters self-healing and immune to individual node
+  # failures.
+  class Mapper
+    include AMQPHelper
+    include ConsoleHelper
+    include DaemonizeHelper
+
+    attr_reader :cluster, :identity, :job_warden, :options, :serializer, :amq
+
+    DEFAULT_OPTIONS = COMMON_DEFAULT_OPTIONS.merge({:user => 'mapper', :identity => Identity.generate, :agent_timeout => 15,
+      :offline_redelivery_frequency => 10, :persistent => false, :offline_failsafe => false}) unless defined?(DEFAULT_OPTIONS)
+
+    # Initializes a new mapper and establishes
+    # AMQP connection. This must be used inside EM.run block or if EventMachine reactor
+    # is already started, for instance, by a Thin server that your Merb/Rails
+    # application runs on.
+    #
+    # Mapper options:
+    #
+    # identity    : identity of this mapper, may be any string
+    #
+    # format      : format to use for packets serialization. Can be :marshal, :json or :yaml or :secure.
+    #               Defaults to Ruby's Marshall format. For interoperability with
+    #               AMQP clients implemented in other languages, use JSON.
+    #
+    #               Note that Nanite uses JSON gem,
+    #               and ActiveSupport's JSON encoder may cause clashes
+    #               if ActiveSupport is loaded after JSON gem.
+    #
+    #               Also using the secure format requires prior initialization of the serializer, see
+    #               SecureSerializer.init
+    #
+    # log_level   : the verbosity of logging, can be debug, info, warn, error or fatal.
+    #
+    # agent_timeout   : how long to wait before an agent is considered to be offline
+    #                   and thus removed from the list of available agents.
+    #
+    # log_dir    : log file path, defaults to the current working directory.
+    #
+    # console     : true tells mapper to start interactive console
+    #
+    # daemonize   : true tells mapper to daemonize
+    #
+    # pid_dir     : path to the directory where the agent stores its pid file (only if daemonized)
+    #               defaults to the root or the current working directory.
+    #
+    # offline_redelivery_frequency : The frequency in seconds that messages stored in the offline queue will be retrieved
+    #                                for attempted redelivery to the nanites. Default is 10 seconds.
+    #
+    # persistent  : true instructs the AMQP broker to save messages to persistent storage so that they aren't lost when the
+    #               broker is restarted. Default is false. Can be overriden on a per-message basis using the request and push methods.
+    # 
+    # secure      : use Security features of rabbitmq to restrict nanites to themselves
+    #
+    # Connection options:
+    #
+    # vhost    : AMQP broker vhost that should be used
+    #
+    # user     : AMQP broker user
+    #
+    # pass     : AMQP broker password
+    #
+    # host     : host AMQP broker (or node of interest) runs on,
+    #            defaults to 0.0.0.0
+    #
+    # port     : port AMQP broker (or node of interest) runs on,
+    #            this defaults to 5672, port used by some widely
+    #            used AMQP brokers (RabbitMQ and ZeroMQ)
+    #
+    # @api :public:
+    def self.start(options = {})
+      mapper = new(options)
+      mapper.run
+      mapper
+    end
+
+    def initialize(options)
+      @options = DEFAULT_OPTIONS.clone.merge(options)
+      root = options[:root] || @options[:root]
+      custom_config = if root
+        file = File.expand_path(File.join(root, 'config.yml'))
+        File.exists?(file) ? (YAML.load(IO.read(file)) || {}) : {}
+      else
+        {}
+      end
+      options.delete(:identity) unless options[:identity]
+      @options.update(custom_config.merge(options))
+      @identity = "mapper-#{@options[:identity]}"
+      @options[:file_root] ||= File.join(@options[:root], 'files')
+      @options.freeze
+    end
+    
+    def run
+      log_path = false
+      if @options[:daemonize]
+        log_path = (@options[:log_dir] || @options[:root] || Dir.pwd)
+      end
+      Nanite::Log.init(@identity, log_path)
+      Nanite::Log.level = @options[:log_level] if @options[:log_level]
+      @serializer = Serializer.new(@options[:format])
+      pid_file = PidFile.new(@identity, @options)
+      pid_file.check
+      if @options[:daemonize]
+        daemonize
+        pid_file.write
+        at_exit { pid_file.remove }
+      end
+      @amq = start_amqp(@options)
+      @job_warden = JobWarden.new(@serializer)
+      @cluster = Cluster.new(@amq, @options[:agent_timeout], @options[:identity], @serializer, self, @options[:redis])
+      Nanite::Log.info('starting mapper')
+      setup_queues
+      start_console if @options[:console] && !@options[:daemonize]
+    end
+
+    # Make a nanite request which expects a response.
+    #
+    # ==== Parameters
+    # type<String>:: The dispatch route for the request
+    # payload<Object>:: Payload to send.  This will get marshalled en route
+    #
+    # ==== Options
+    # :selector<Symbol>:: Method for selecting an actor.  Default is :least_loaded.
+    #   :least_loaded:: Pick the nanite which has the lowest load.
+    #   :all:: Send the request to all nanites which respond to the service.
+    #   :random:: Randomly pick a nanite.
+    #   :rr: Select a nanite according to round robin ordering.
+    # :target<String>:: Select a specific nanite via identity, rather than using
+    #   a selector.
+    # :offline_failsafe<Boolean>:: Store messages in an offline queue when all
+    #   the nanites are offline. Messages will be redelivered when nanites come online.
+    #   Default is false unless the mapper was started with the --offline-failsafe flag.
+    # :persistent<Boolean>:: Instructs the AMQP broker to save the message to persistent
+    #   storage so that it isnt lost when the broker is restarted.
+    #   Default is false unless the mapper was started with the --persistent flag.
+    # :intermediate_handler:: Takes a lambda to call when an IntermediateMessage
+    #   event arrives from a nanite.  If passed a Hash, hash keys should correspond to
+    #   the IntermediateMessage keys provided by the nanite, and each should have a value
+    #   that is a lambda/proc taking the parameters specified here.  Can supply a key '*'
+    #   as a catch-all for unmatched keys.
+    #
+    # ==== Block Parameters for intermediate_handler
+    # key<String>:: array of unique keys for which intermediate state has been received
+    #   since the last call to this block.
+    # nanite<String>:: nanite which sent the message.
+    # state:: most recently delivered intermediate state for the key provided.
+    # job:: (optional) -- if provided, this parameter gets the whole job object, if there's
+    #   a reason to do more complex work with the job.
+    #
+    # ==== Block Parameters
+    # :results<Object>:: The returned value from the nanite actor.
+    #
+    # @api :public:
+    def request(type, payload = '', opts = {}, &blk)
+      request = build_deliverable(Request, type, payload, opts)
+      send_request(request, opts, &blk)
+    end
+
+    # Send request with pre-built request instance
+    def send_request(request, opts = {}, &blk)
+      request.reply_to = identity
+      intm_handler = opts.delete(:intermediate_handler)
+      targets = cluster.targets_for(request)
+      if !targets.empty?
+        job = job_warden.new_job(request, targets, intm_handler, blk)
+        cluster.route(request, job.targets)
+        job
+      elsif opts.key?(:offline_failsafe) ? opts[:offline_failsafe] : options[:offline_failsafe]
+        job_warden.new_job(request, [], intm_handler, blk)
+        cluster.publish(request, 'mapper-offline')
+        :offline
+      else
+        false
+      end
+    end
+      
+    # Make a nanite request which does not expect a response.
+    #
+    # ==== Parameters
+    # type<String>:: The dispatch route for the request
+    # payload<Object>:: Payload to send.  This will get marshalled en route
+    #
+    # ==== Options
+    # :selector<Symbol>:: Method for selecting an actor.  Default is :least_loaded.
+    #   :least_loaded:: Pick the nanite which has the lowest load.
+    #   :all:: Send the request to all nanites which respond to the service.
+    #   :random:: Randomly pick a nanite.
+    #   :rr: Select a nanite according to round robin ordering.
+    # :offline_failsafe<Boolean>:: Store messages in an offline queue when all
+    #   the nanites are offline. Messages will be redelivered when nanites come online.
+    #   Default is false unless the mapper was started with the --offline-failsafe flag.
+    # :persistent<Boolean>:: Instructs the AMQP broker to save the message to persistent
+    #   storage so that it isnt lost when the broker is restarted.
+    #   Default is false unless the mapper was started with the --persistent flag.
+    #
+    # @api :public:
+    def push(type, payload = '', opts = {})
+      push = build_deliverable(Push, type, payload, opts)
+      targets = cluster.targets_for(push)
+      if !targets.empty?
+        cluster.route(push, targets)
+        true
+      elsif opts.key?(:offline_failsafe) ? opts[:offline_failsafe] : options[:offline_failsafe]
+        cluster.publish(push, 'mapper-offline')
+        :offline
+      else
+        false
+      end
+    end
+
+    private
+
+    def build_deliverable(deliverable_type, type, payload, opts)
+      deliverable = deliverable_type.new(type, payload, opts)
+      deliverable.from = identity
+      deliverable.token = Identity.generate
+      deliverable.persistent = opts.key?(:persistent) ? opts[:persistent] : options[:persistent]
+      deliverable
+    end
+
+    def setup_queues
+      setup_offline_queue
+      setup_message_queue
+    end
+
+    def setup_offline_queue
+      offline_queue = amq.queue('mapper-offline', :durable => true)
+      offline_queue.subscribe(:ack => true) do |info, deliverable|
+        deliverable = serializer.load(deliverable)
+        targets = cluster.targets_for(deliverable)
+        unless targets.empty?
+          info.ack
+          if deliverable.kind_of?(Request)
+            if job = job_warden.jobs[deliverable.token]
+              job.targets = targets
+            else
+              deliverable.reply_to = identity
+              job_warden.new_job(deliverable, targets)
+            end
+          end
+          cluster.route(deliverable, targets)
+        end
+      end
+
+      EM.add_periodic_timer(options[:offline_redelivery_frequency]) { offline_queue.recover }
+    end
+
+    def setup_message_queue
+      amq.queue(identity, :exclusive => true).bind(amq.fanout(identity)).subscribe do |msg|
+        begin
+          msg = serializer.load(msg)
+          Nanite::Log.debug("got result from #{msg.from}: #{msg.results.inspect}")
+          job_warden.process(msg)
+        rescue Exception => e
+          Nanite::Log.error("Error handling result: #{e.message}")
+        end
+      end
+    end
+  end
+end
+