pokan 0.1.0rc1

data/lib/pokan/event_handler.rb

@@ -0,0 +1,113 @@
+# lib/pokan/event_handler.rb
+
+module Pokan
+
+  class NoBlockGivenError < StandardError #:nodoc:
+  end
+
+  # EventHandler is a class that associate blocks with events,
+  # making it possible to emit events and executing all the
+  # related callbacks (sequentially, in the order they were registered).
+  # 
+  # === Usage
+  #   e = EventHandler.new
+  #   e.register(:my_event) { puts 'oh my!' }
+  #   e.events                     #=> [:my_event]
+  #   e.subscribers(:my_event)     #=> Proc array with callbacks
+  #   e.emit(:my_event)            #=> 'oh my!' is printed
+  
+  class EventHandler
+
+    # creates a new instance of EventHandler, ready for event registrations
+    def initialize
+      @callbacks = {}
+    end
+
+    ##
+    # +register+ is the method used to associate a block with an event.
+    # The event name *must* be passed as a symbol, otherwise an exception is
+    # raised.
+    # You can call +register+ on the same event any number of times, but it is
+    # important to note that the blocks associated will be called in the same
+    # order they were registered.
+    #
+    #   e = EventHandler.new
+    #   e.register(:my_event) { puts 'my event' }.register(:my_event) { puts 'is cool!' }
+    def register(event, &block)
+      raise_unless_symbol(event)
+
+      raise NoBlockGivenError, 'must provide a block' unless block_given?
+
+      initialize_callbacks_for(event)
+      @callbacks[event] << block
+      self
+    end
+
+    ##
+    # Retrieves the names of all the events for which there is at least
+    # one associated callback
+    def events
+      @callbacks.keys
+    end
+
+    ##
+    # Returns an array with all the Proc objects for callbacks registered
+    # for the given _event_
+    def subscribers(event)
+      raise_unless_symbol(event)
+
+      @callbacks[event] || []
+    end
+
+    # Removes all the callbacks registered with _event_
+    def reset(event)
+      raise_unless_symbol(event)
+
+      @callbacks.delete(event)
+      self
+    end
+
+    ##
+    # Emits the given _event_, thus calling all the registered callbacks
+    # up to that point. If there are no registered callbacks for the 
+    # _event_ passed, nothing is done.
+    #
+    # If the registered callbacks expected parameters, pass them using the
+    # +with+ option
+    #
+    #   e = EventHandler.new
+    #   e.register(:awesome) { puts 'awesome!' }
+    #   e.register(:awesome) { puts 'not that awesome...' }
+    #   e.emit(:awesome)    #=> messages are print
+    #
+    #  Using the +with+ option:
+    #
+    #   e = EventHandler.new
+    #   e.register(:awesome) { |msg| puts msg }
+    #   e.emit(:awesome, :with => ['awesome!']) #=> 'awesome!' is print
+    def emit(event, options = {})
+      raise_unless_symbol(event)
+
+      args = options[:with] || []
+      
+      if @callbacks.has_key? event
+        @callbacks[event].each { |c| c.call(*args) }
+      end
+
+      self
+    end
+
+  private
+
+    # Raises an +ArgumentError+ if the given parameter is not a symbol
+    def raise_unless_symbol(event)
+      raise ArgumentError, 'event name must be passed as a symbol' unless event.is_a? Symbol
+    end
+
+    # If there hasn't been any callback registered to _event_, create a new list for it
+    def initialize_callbacks_for(event)
+      @callbacks[event] ||= []
+    end
+
+  end
+end

data/lib/pokan/network.rb

@@ -0,0 +1,43 @@
+# lib/pokan/network.rb
+
+module Pokan
+
+  # Network is a helper class, used by the Pokan::Server class.
+  # Its main goal is to provide a higher abstraction for networking 
+  # methods provided by the Ruby core. It should not be used by
+  # user code.
+  class Network 
+
+    ##
+    # Sends _message_ to the given _host_ and _port_. As UDP is connectionless,
+    # there's no way to be sure wheter or not the message will reach its destination.
+    # UDP messages are used for communication of peers.
+    def self.udp(message, host, port)
+      @socket = UDPSocket.new
+      bytes = @socket.send(message, 0, host, port)
+
+      bytes > 0
+    end
+
+    ##
+    # Sends _message_ to the given _host_ and _port_. TCP is a connection-oriented
+    # protocol, so we need to have a server waiting for the message in the destination
+    # passed as parameters.
+    # If the connection cannot be established, this method returns +false+.
+    # TCP messages are used for communication with seeds, since we need to be
+    # sure the data really reaches its destination (for example, when someone finishes
+    # the gossip server manually, pokan sends a message to a seed, telling it is about
+    # to die.
+    def self.tcp(message, host, port)
+      begin
+        @socket = TCPSocket.open(host, port)
+        bytes = @socket.send(message, 0)
+
+        bytes  > 0
+      rescue
+        false
+      end
+    end
+
+  end
+end

data/lib/pokan/peer.rb

@@ -0,0 +1,136 @@
+# lib/pokan/peer.rb
+module Pokan
+
+  ##
+  # Peer is a Entity that takes care of the peer semantics.
+  # It controls the status, id and role attributes.
+  class Peer < Entity
+
+    def initialize
+      super
+      store(:role, 'peer', 0)
+      store(:status, 'alive', 0)
+    end
+
+    def address=(address)
+      @address = address
+      self.id = "#{@address}:#{@udp_port}"  if defined?(@address) && defined?(@udp_port)
+    end
+
+    def address
+      @address = id.split(':').first
+    end
+
+    def udp_port=(port)
+      @udp_port = port
+      self.id = "#{@address}:#{@udp_port}"  if defined?(@address) && defined?(@udp_port)
+    end
+
+    def udp_port
+      @udp_port = id.split(':')[1]
+    end
+
+    def tcp_port=(port)
+      store(:tcp_port, port)
+    end
+
+    def tcp_port
+      value(:tcp_port)
+    end
+
+    ##
+    # Stores the value and the timestamp for a given key.
+    # If the key, which must be a symbol, already exists, it will be updated if
+    # the timestamp is greater.
+    # The timestamp defaults to Time.now.
+    #
+    # If the key is ':role', the values have to be 'peer' or 'seed'. In the same
+    # way, if the key is ':status', the value have to be 'alive' or 'dead'.
+    # Otherwise, the value will not be set.
+    def store(key, value, timestamp = Time.now)
+      case key
+      when :role
+        super(:role, value, timestamp)  if ['peer', 'seed'].include?(value)
+      when :status
+        super(:status, value, timestamp)  if ['alive', 'dead'].include?(value)
+      else
+        super(key, value, timestamp)
+      end
+    end
+
+    ##
+    # Changes the role of the peer. The role must be peer or seed. Otherwise, the role will stay as it was and no exception will be thrown.
+    def role=(role)
+      store(:role, role)
+    end
+
+    def role
+      value(:role)
+    end
+
+    ##
+    # Turns the peer into a seed.
+    def act_as_seed
+      store(:role, 'seed')
+    end
+
+    def seed?
+      value(:role) == 'seed'
+    end
+
+    def peer?
+      value(:role) == 'peer'
+    end
+
+    ##
+    # Changes the status of the peer.
+    # The status must be alive or dead. Otherwise, the role will stay as it was and no exception will be thrown.
+    def status=(status)
+      store(:status, status)
+    end
+
+    def status
+      value(:status)
+    end
+
+    ##
+    # Revives the peer
+    def revive
+      store(:status, 'alive')
+    end
+
+    ##
+    # Kills the peer
+    def kill
+      store(:status, 'dead')
+      self
+    end
+
+    def alive?
+      status == 'alive'
+    end
+
+    def dead?
+      status == 'dead'
+    end
+
+    ##
+    # Gossips with the given seed and replicates its local storage.
+    #
+    # If the host or port is invalid, the local storage will continue empty.
+    # === Usage
+    #   peer = Pokan::Peer.new
+    #   peer.address = '127.0.0.2'
+    #   peer.port = '1234'
+    #   peer.value(:key_not_present) # => nil
+    #   peer.gossip_with('127.0.0.2', '8888')
+    #   peer.value(:key_not_present) # => 'the value of the key'
+    def sync_with(host, port)
+      db = Connection.redis
+      db.slaveof(host, port)
+      sleep(3) #while db.info['master_sync_in_progress'].to_i == 0
+      @seed = host
+      db.slaveof('no', 'one')
+    end
+  end
+end

data/lib/pokan/query.rb

@@ -0,0 +1,39 @@
+# lib/pokan/query.rb
+
+module Pokan
+  ##
+  # The Query class is used to find Entities that obey restrictions.
+  # It is commonly used to get a Entity according with a id, get all dead Peers
+  # and so on.
+  class Query
+    def initialize(entity_class)
+      @entity_class = entity_class
+      @db = Connection.redis
+    end
+
+    ##
+    # Returns a array of entities respecting the given restrictions
+    # Structure: {id: '234', role: 'dead', status:['alive', 'dead'], random: true...}
+    def where(query)
+      result = []
+      candidates = @db.smembers('entities')
+
+      if query.has_key?(:id)
+        query[:id] = [query[:id]]  unless query[:id].is_a?(Array)
+        candidates = candidates & query[:id]
+      end
+      candidates = candidates - query[:not] if query.has_key?(:not)
+
+      candidates.each do |entity_id|
+        entity = @entity_class.new
+        entity.id = entity_id
+        entity.reload
+        result << entity  if entity.match?(query.reject {|k, v| k == :not || k == :random || k == :id})
+      end
+
+      result = [result.sample] if query[:random]
+
+      result
+    end
+  end
+end

data/lib/pokan/request_handler.rb

@@ -0,0 +1,90 @@
+# lib/pokan/gossiper.rb
+require 'json'
+require 'eventmachine'
+
+module Pokan
+
+  # Gossiper module is the implementation of the push-pull-gossip protocol.
+  class RequestHandler < EM::Connection
+    include Pokan::CollectivePeerOperations
+
+    class << self
+      attr_accessor :address, :port
+
+      alias_method :old_new, :new
+
+      def new(sig, *args)
+        rh = old_new(sig, *args)
+        rh.address = address
+        rh.port    = port
+
+        rh
+      end
+    end
+
+    attr_accessor :address, :port
+
+    ##
+    # Receives the gossip message and returns the apropriate message
+    # - digest message -> pull message
+    # - pull message -> push message and newer keys stored
+    # - push message -> newer keys stored
+    # - hello message -> peer created locally
+    # - goodbye message -> peer killed locally
+    def receive_data(json_data)
+      message = JSON.parse(json_data)
+      data = message['data']
+
+      puts 'RECV'
+      case message['action']
+      when 'digest'
+        puts "DIGEST from #{message['origin']}"
+        pull = pull_message(data)
+        send_datagram(pull, *message['origin'].split(':'))
+
+        pull
+      when 'pull'
+        puts "PULL from #{message['origin']}"
+        response = push_message(data['older'])
+        merge(data['newer'])
+        send_datagram(response, *message['origin'].split(':'))
+
+        response
+      when 'push'
+        puts "PUSH from #{message['origin']}"
+        merge(data)
+      when 'hello'
+        puts "HELLO from from #{message['origin']}"
+        peer = Peer.new
+        peer.id = message['origin']
+        # peer.store(:role, message['role'])
+        peer.save
+      when 'goodbye'
+        puts "GOODBYE from #{message['origin']}"
+        peer = Query.new(Peer).where(id: message['origin'])[0]
+        peer.store(:status, 'dead', message['timestamp'])
+        peer.save
+      end
+    end
+
+    ##
+    # Get a pull message containing all status and keys based on the given keys following the structure:
+    # Given structure: {id: [:key1, :key2, ...]}
+    def push_message(keys)
+      { action: 'push', data: retrieve(keys), origin:"#{address}:#{port}" }.to_json
+    end
+
+    ##
+    # Get a push message containing all status and keys based on the given keys following the structure:
+    # Given structure: {id: {key: timestamp, ...} ...}
+    def pull_message(keys)
+      { action: 'pull',
+        data: {
+          newer: newer(keys),
+          older: older(keys)
+        },
+        origin:"#{address}:#{port}" 
+      }.to_json
+    end
+  end
+end

data/lib/pokan/server.rb

@@ -0,0 +1,230 @@
+# lib/pokan/server.rb
+
+require 'eventmachine'
+
+module Pokan
+
+  ##
+  # Gossip server class, using the Pokan::Peer class. This is the main class
+  # instantied by user code.
+  #
+  # When a server class is created, the user should set:
+  # * the gossip interval
+  # * actual data to be stored, and possibly shared with other servers
+  #   accross the network
+  # * The server behavior on a defined set of events, declared in an
+  #   event driven syntax.
+  #
+  # The user can also use epoll[http://linux.die.net/man/4/epoll]
+  # for faster I/O notification, if the server is running on a Linux system.
+  #
+  # Sample usage is shown below:
+  #
+  #   s = Pokan::Server.new
+  #   s.gossip_every(1) #=> tells the server to gossip every second
+  #   s.use_epoll #=> I'm in a Linux system
+  #
+  #   s.store 'k', 'v'
+  #
+  #   e.on :new_key do |key, value|
+  #     puts "What a great key I just got: #{key}!"
+  #   end
+  #
+  #   # more event related code... 
+  #
+  #   e.start #=> last command, blocks execution
+  class Server < Peer
+
+    attr_reader :gossip_interval
+    alias_method :port, :udp_port
+
+    include ServerMessages
+
+    ON_EVENTS     = [:new_key, :key_changed, :key_removed]
+    BEFORE_EVENTS = [:gossip, :sync]
+    AFTER_EVENTS  = [:gossip, :sync]
+
+    # Creates a new gossip server. You must pass the machine's IP address in 
+    # the network. This information will be used when changing information
+    # with other peers running Pokan.
+    # This also set some defaults, namely:
+    # * server will bind TCP and UDP port number 5555. If you have something else
+    #   running, you must set them like:
+    #     server.tcp_port = 9876
+    #     server.udp_port = 9989
+    #
+    # * +epoll+ will not be used (you might want to set it if you are in a
+    #   Linux system. See Pokan::Server#use_epoll
+    #
+    # * The server will comunicate with other peers _every second_
+    #
+    # Of course, all of these are customizable to your particular needs.
+    def initialize(address)
+      @event_handler = EventHandler.new
+      self.address = address
+      self.udp_port = 5555
+      super()
+      initialize_ivs
+    end
+
+    # Call this method if you want to use epoll in your Linux system.
+    # *Warning*: this will not throw an exception nor will warn you
+    # if you use this method in a non-Linux machine. You might face
+    # errors when you try to start the server, though.
+    def use_epoll
+      @epoll = true
+    end
+
+    def using_epoll?
+      @epoll
+    end
+
+    # Use this method to specify the time interval you wish to use for
+    # changing gossip messages among peers. Default is 1 second.
+    def gossip_every(seconds)
+      @gossip_interval = seconds
+    end
+
+    # Stores a key, value pair that will be shared among all the peers in
+    # the network.
+    def store(key, value, timestamp=Time.now)
+      super
+      save
+      @event_handler.emit :new_key, :with => [key, value]
+    end
+
+    # Defines the behaviour you want the server to have on different events.
+    # For now, you can define your behaviour for the following events:
+    # * +:new_key+ - This will be called whenever a new_key is inserted
+    #   (and there was no previous value for that)
+    #
+    # * +:key_changed+ - This is called when a value for a certain key is
+    #   updated (a value with greater timestamp)
+    #
+    # * +:key_removed+ - The name speaks for itself
+    #
+    # For all the events, both the key and the value are passed to the
+    # block.
+    #
+    # Example:
+    #
+    #   server = Pokan::Server.new('10.10.10.8')
+    #   server.on :new_key do |key, value|
+    #     puts "New key #{key} was inserted with value #{value}!"
+    #   end
+    def on(event, &block)
+      register_event(event, &block) if ON_EVENTS.include? event
+    end
+
+    # Adds behaviour before a given event occurs. For now, the only event
+    # supported is +:gossip+. Use this method if you want some code to run
+    # every time before the server gossips with a random peer.
+    def before(event, &block)
+      event_name = prepend('before_', event)
+      register_event(event_name, &block) if BEFORE_EVENTS.include? event
+    end
+
+    # Same as the Pokan::Server#before, but it also supports the +:sync+ event.
+    # Use this method to run some code after the server gossips with a random
+    # peer or after it syncs with a seed (if you passed one on initialization.
+    # See Pokan::Server#start).
+    def after(event, &block)
+      event_name = prepend('after_', event)
+      register_event(event_name, &block) if AFTER_EVENTS.include? event
+    end
+
+    # This method starts the server, which will bind specified TCP and UDP
+    # ports (or 5555 by default). Optionally, you can pass the address of
+    # another pokan instance (a seed), and the server will automatically
+    # send a message to the seed and update its data. If no seed information
+    # is passed, the server will start with no data and assume it is 
+    # a seed.
+    #
+    # Example:
+    #
+    #   server = Pokan::Server.new('10.10.10.8')
+    #   server.start :gossip_with => '10.10.10.9:5555'
+    #
+    # In the example above, the server will try to contact (via TCP) a pokan
+    # server running on +10.10.10.9+, port +5555+, and update its data
+    # accordingly.
+    def start(options = {})
+      seed = options[:gossip_with]
+
+      if seed.nil?
+        act_as_seed
+      else
+        @seed_address, @seed_port = parse_host_and_port(seed)
+        say_hello(@seed_address, @seed_port)
+
+        sync_with(@seed_address, options[:redis])
+        @event_handler.emit :after_sync
+      end
+
+      start_event_loop
+    end
+
+    # Finishes the server
+    def stop
+      kill
+      EventMachine.stop
+    end
+
+  private
+
+    # Sets default variables, such as:
+    # * TCP and UDP ports: 5555
+    # * do _not_ use epoll
+    # * gossip every second
+    def initialize_ivs
+      self.tcp_port     = 5555
+      @epoll            = false
+      @gossip_interval  = 1
+    end
+
+    def register_event(event, &block)
+      @event_handler.register(event, &block)
+    end
+
+    def parse_host_and_port(address)
+      address.split ':'
+    end
+
+    def prepend(string, event)
+      event_str = string + event.to_s
+      event_str.to_sym
+    end
+
+    def start_event_loop
+      EventMachine.run {
+        gossip
+ 
+        RequestHandler.address = address
+        RequestHandler.port    = udp_port
+
+        EventMachine.open_datagram_socket address, udp_port, RequestHandler
+        EventMachine.start_server address, tcp_port, RequestHandler
+      }
+    end
+
+    def say_hello(address, port)
+      Network.tcp(hello_message, address, port)
+    end
+
+    def gossip
+      EventMachine.add_periodic_timer(@gossip_interval) {
+        query = Query.new(Peer)
+        peer = query.where(:random => true, :role => ['seed', 'peer'], :not => [id],
+                           :status => 'alive').first
+
+        unless peer.nil?
+          @event_handler.emit :before_gossip
+          Network.udp(digest_message, peer.address, peer.udp_port)
+          @event_handler.emit :after_gossip, :with => [peer.address, peer.udp_port]
+        end
+      }
+    end
+
+  end
+
+end