br-nanite 0.3.0

data/lib/nanite/dispatcher.rb

@@ -0,0 +1,59 @@
+module Nanite
+  class Dispatcher
+    attr_reader :registry, :serializer, :identity, :log, :amq, :options
+
+    def initialize(amq, registry, serializer, identity, log, options)
+      @amq = amq
+      @registry = registry
+      @serializer = serializer
+      @identity = identity
+      @log = log
+      @options = options
+    end
+
+    def dispatch(deliverable)
+      result = begin
+        prefix, meth = deliverable.type.split('/')[1..-1]
+        actor = registry.actor_for(prefix)
+        actor.send(meth, deliverable.payload)
+      rescue Exception => e
+        handle_exception(actor, meth, deliverable, e)
+      end
+
+      if deliverable.kind_of?(Request)
+        result = Result.new(deliverable.token, deliverable.reply_to, result, identity)
+        amq.queue(deliverable.reply_to, :no_declare => options[:secure]).publish(serializer.dump(result))
+      end
+
+      result
+    end
+
+    private
+
+    def describe_error(e)
+      "#{e.class.name}: #{e.message}\n #{e.backtrace.join("\n  ")}"
+    end
+
+    def handle_exception(actor, meth, deliverable, e)
+      error = describe_error(e)
+      log.error(error)
+      begin
+        if actor.class.instance_exception_callback
+          case actor.class.instance_exception_callback
+          when Symbol, String
+            actor.send(actor.class.instance_exception_callback, meth.to_sym, deliverable, e)
+          when Proc
+            actor.instance_exec(meth.to_sym, deliverable, e, &actor.class.instance_exception_callback)
+          end
+        end
+        if Nanite::Actor.superclass_exception_callback
+          Nanite::Actor.superclass_exception_callback.call(actor, meth.to_sym, deliverable, e)
+        end
+      rescue Exception => e1
+        error = describe_error(e1)
+        log.error(error)
+      end
+      error
+    end
+  end
+end

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,50 @@
+module Nanite
+  class JobWarden
+    attr_reader :serializer, :jobs, :log
+
+    def initialize(serializer, log)
+      @serializer = serializer
+      @log = log
+      @jobs = {}
+    end
+
+    def new_job(request, targets, blk = nil)
+      job = Job.new(request, targets, blk)
+      jobs[job.token] = job
+      job
+    end
+
+    def process(msg)
+      msg = serializer.load(msg)
+      log.debug("processing message: #{msg.inspect}")
+      if job = jobs[msg.token]
+        job.process(msg)
+        if job.completed?
+          jobs.delete(job.token)
+          job.completed.call(job.results) if job.completed
+        end
+      end
+    end
+  end
+
+  class Job
+    attr_reader :results, :request, :token, :targets, :completed
+
+    def initialize(request, targets, blk)
+      @request = request
+      @targets = targets
+      @token = @request.token
+      @results = {}
+      @completed = blk
+    end
+
+    def process(msg)
+      results[msg.from] = msg.results
+      targets.delete(msg.from)
+    end
+
+    def completed?
+      targets.empty?
+    end
+  end
+end

data/lib/nanite/log.rb

@@ -0,0 +1,23 @@
+module Nanite
+  class Log
+    def initialize(options, identity)
+      @file = File.join((options[:log_dir] || options[:root] || Dir.pwd), "nanite.#{identity}.log")
+      @logger = Logger.new(file)
+      @logger.level = log_level(options[:log_level])
+    end
+
+    def file
+      @file
+    end
+
+    def method_missing(method, *args)
+      @logger.send(method, *args)
+    end
+
+    private
+
+    def log_level(level)
+      {'fatal' => Logger::FATAL, 'error' => Logger::ERROR, 'warn' => Logger::WARN, 'info' => Logger::INFO, 'debug' => Logger::DEBUG}[level] || Logger::INFO
+    end
+  end
+end

data/lib/nanite/mapper.rb

@@ -0,0 +1,214 @@
+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, :log, :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.
+    #               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.
+    #
+    # 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
+    #
+    # 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 = {})
+      new(options)
+    end
+
+    def initialize(options)
+      @options = DEFAULT_OPTIONS.merge(options)
+      @identity = "mapper-#{@options[:identity]}"
+      @log = Log.new(@options, @identity)
+      @serializer = Serializer.new(@options[:format])
+      daemonize if @options[:daemonize]
+      @amq =start_amqp(@options)
+      @cluster = Cluster.new(@amq, @options[:agent_timeout], @options[:identity], @log, @serializer)
+      @job_warden = JobWarden.new(@serializer, @log)
+      @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.
+    #
+    # ==== 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)
+      request.reply_to = identity
+      targets = cluster.targets_for(request)
+      if !targets.empty?
+        job = job_warden.new_job(request, targets, blk)
+        cluster.route(request, job.targets)
+        job
+      elsif opts.key?(:offline_failsafe) ? opts[:offline_failsafe] : options[:offline_failsafe]
+        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)
+            deliverable.reply_to = identity
+            job_warden.new_job(deliverable, targets)
+          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|
+        job_warden.process(msg)
+      end
+    end
+  end
+end
+

data/lib/nanite/packets.rb

@@ -0,0 +1,192 @@
+module Nanite
+  # Base class for all Nanite packets,
+  # knows how to dump itself to JSON
+  class Packet
+    def initialize
+      raise NotImplementedError.new("#{self.class.name} is an abstract class.")
+    end
+    def to_json(*a)
+      {
+        'json_class'   => self.class.name,
+        'data'         => instance_variables.inject({}) {|m,ivar| m[ivar.sub(/@/,'')] = instance_variable_get(ivar); m }
+      }.to_json(*a)
+    end
+  end
+
+  # packet that means start of a file transfer
+  # operation
+  class FileStart < Packet
+    attr_accessor :filename, :token, :dest
+    def initialize(filename, dest, token)
+      @filename = filename
+      @dest = dest
+      @token = token
+    end
+
+    def self.json_create(o)
+      i = o['data']
+      new(i['filename'], i['dest'], i['token'])
+    end
+  end
+
+  # packet that means end of a file transfer
+  # operation
+  class FileEnd < Packet
+    attr_accessor :token, :meta
+    def initialize(token, meta)
+      @token = token
+      @meta  = meta
+    end
+
+    def self.json_create(o)
+      i = o['data']
+      new(i['token'], i['meta'])
+    end
+  end
+
+  # packet that carries data chunks during a file transfer
+  class FileChunk < Packet
+    attr_accessor :chunk, :token
+    def initialize(token, chunk=nil)
+      @chunk = chunk
+      @token = token
+    end
+    def self.json_create(o)
+      i = o['data']
+      new(i['token'], i['chunk'])
+    end
+  end
+
+  # packet that means a work request from mapper
+  # to actor node
+  #
+  # type     is a service name
+  # payload  is arbitrary data that is transferred from mapper to actor
+  #
+  # Options:
+  # from     is sender identity
+  # token    is a generated request id that mapper uses to identify replies
+  # reply_to is identity of the node actor replies to, usually a mapper itself
+  # selector is the selector used to route the request
+  # target   is the target nanite for the request
+  # persistent signifies if this request should be saved to persistent storage by the AMQP broker
+  class Request < Packet
+    attr_accessor :from, :payload, :type, :token, :reply_to, :selector, :target, :persistent
+    DEFAULT_OPTIONS = {:selector => :least_loaded}
+    def initialize(type, payload, opts={})
+      opts = DEFAULT_OPTIONS.merge(opts)
+      @type             = type
+      @payload          = payload
+      @from             = opts[:from]
+      @token            = opts[:token]
+      @reply_to         = opts[:reply_to]
+      @selector         = opts[:selector]
+      @target           = opts[:target]
+      @persistent       = opts[:persistent]
+    end
+    def self.json_create(o)
+      i = o['data']
+      new(i['type'], i['payload'], {:from => i['from'], :token => i['token'], :reply_to => i['reply_to'], :selector => i['selector'],
+        :target => i['target'], :persistent => i['persistent']})
+    end
+  end
+
+  # packet that means a work push from mapper
+  # to actor node
+  #
+  # type     is a service name
+  # payload  is arbitrary data that is transferred from mapper to actor
+  #
+  # Options:
+  # from     is sender identity
+  # token    is a generated request id that mapper uses to identify replies
+  # selector is the selector used to route the request
+  # target   is the target nanite for the request
+  # persistent signifies if this request should be saved to persistent storage by the AMQP broker
+  class Push < Packet
+    attr_accessor :from, :payload, :type, :token, :selector, :target, :persistent
+    DEFAULT_OPTIONS = {:selector => :least_loaded}
+    def initialize(type, payload, opts={})
+      opts = DEFAULT_OPTIONS.merge(opts)
+      @type             = type
+      @payload          = payload
+      @from             = opts[:from]
+      @token            = opts[:token]
+      @selector         = opts[:selector]
+      @target           = opts[:target]
+      @persistent       = opts[:persistent]
+    end
+    def self.json_create(o)
+      i = o['data']
+      new(i['type'], i['payload'], {:from => i['from'], :token => i['token'], :selector => i['selector'],
+        :target => i['target'], :persistent => i['persistent']})
+    end
+  end
+
+  # packet that means a work result notification sent from actor to mapper
+  #
+  # from     is sender identity
+  # results  is arbitrary data that is transferred from actor, a result of actor's work
+  # token    is a generated request id that mapper uses to identify replies
+  # to       is identity of the node result should be delivered to
+  class Result < Packet
+    attr_accessor :token, :results, :to, :from
+    def initialize(token, to, results, from)
+      @token = token
+      @to = to
+      @from = from
+      @results = results
+    end
+    def self.json_create(o)
+      i = o['data']
+      new(i['token'], i['to'], i['results'], i['from'])
+    end
+  end
+
+  # packet that means an availability notification sent from actor to mapper
+  #
+  # from     is sender identity
+  # services is a list of services provided by the node
+  # status   is a load of the node by default, but may be any criteria
+  #          agent may use to report it's availability, load, etc
+  class Register < Packet
+    attr_accessor :identity, :services, :status
+    def initialize(identity, services, status)
+      @status = status
+      @identity = identity
+      @services = services
+    end
+    def self.json_create(o)
+      i = o['data']
+      new(i['identity'], i['services'], i['status'])
+    end
+  end
+
+  # heartbeat packet
+  #
+  # identity is sender's identity
+  # status   is sender's status (see Register packet documentation)
+  class Ping < Packet
+    attr_accessor :identity, :status
+    def initialize(identity, status)
+      @status = status
+      @identity = identity
+    end
+    def self.json_create(o)
+      i = o['data']
+      new(i['identity'], i['status'])
+    end
+  end
+
+  # packet that is sent by workers to the mapper
+  # when worker initially comes online to advertise
+  # it's services
+  class Advertise < Packet
+    def initialize
+    end
+    def self.json_create(o)
+      new
+    end
+  end
+end
+