journeta 0.0.2

data/History.txt

@@ -0,0 +1,11 @@
+== 0.0.2 2008-08-19
+
+* First working RubyForge release:
+  * See README.txt for general info.
+  * Adding functional chat room example. (See examples/)
+
+== 0.0.1 2007-07-25
+
+* Initial release:
+  * Basic port from original Java code.
+  * NOT YET FUNCTIONAL!

data/License.txt

@@ -0,0 +1,11 @@
+Copyright (c) 2007, OpenRain, LLC. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+-Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+-Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+-Neither the name of the OpenRain, LLC nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Manifest.txt

@@ -0,0 +1,27 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/journeta.rb
+examples/instant_messenger.rb
+lib/journeta/logger.rb
+lib/journeta/version.rb
+lib/journeta/asynchronous.rb
+lib/journeta/session_listener.rb
+lib/journeta/session_handler.rb
+lib/journeta/event_broadcaster.rb
+lib/journeta/event_listener.rb
+lib/journeta/presence_message.rb
+lib/journeta/peer_registry.rb
+lib/journeta/peer_connection.rb
+lib/journeta/journeta_engine.rb
+scripts/txt2html
+setup.rb
+test/test_journeta.rb
+test/test_helper.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.rhtml

data/README.txt

@@ -0,0 +1,41 @@
+= Journeta
+
+== About
+
+
+Journeta is a dirt simple peer discovery and message passing library for processes on the same LAN,
+requiring no advanced networking knowledge to use.
+
+Only core Ruby libraries are required, making the library fairly light. As all data is sent accross
+the wire in YAML form, any arbitrary Ruby object can be sent to peers, provided they..
+
+ * Are running a compatible Journeta version, and
+ * Have access to the same class definitions if you are sending your own custom objects.
+ * Do not have a firewall preventing
+
+Journeta uses Ruby threading to manage the asynchonous nature of peer-to-peer I/O.
+For insight into events internal to the library, start ruby with the `--debug` options.
+
+
+== Use
+
+
+ examples/instant_messenger.rb
+ 
+    A completely distributed, zero-configuration-required chat room script.
+    Fire up several instances in separate terminals. Multiple instances on the same machine is ok.
+    Everything you type will automatically be sent to all other instances on the LAN!
+    Use `ruby --debug examples/instant_messenger.rb` for detailed internal event details.
+
+
+== Author
+
+Preston Lee <preston.lee at openrain d0t com>
+http://www.prestonlee.com
+http://www.openrain.com
+
+
+== Links
+
+How Journeta discovers peers using UDP multicasting..
+http://onestepback.org/index.cgi/Tech/Ruby/MulticastingInRuby.red

data/Rakefile

@@ -0,0 +1,123 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'journeta', 'version')
+
+AUTHOR = 'Preston Lee'  # can also be an array of Authors
+EMAIL = "preston.lee@openrain.com"
+DESCRIPTION = "A zero-configuration-required peer-to-peer (P2P) discovery and communications library for closed networks."
+GEM_NAME = 'journeta' # what ppl will type to install your gem
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}"
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  @rubyforge_username ||= @config["username"]
+end
+
+RUBYFORGE_PROJECT = 'journeta' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+NAME = "journeta"
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = Journeta::VERSION::STRING + (REV ? ".#{REV}" : "")
+CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
+RDOC_OPTS = ['--quiet', '--title', 'journeta documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = []     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\n\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+
+desc 'Generate website files'
+task :website_generate do
+  Dir['website/**/*.txt'].each do |txt|
+    sh %{ ruby scripts/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
+  end
+end
+
+desc 'Upload website files to rubyforge'
+task :website_upload do
+  host = "#{rubyforge_username}@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/#{PATH}/"
+  local_dir = 'website'
+  sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+desc 'Generate and upload website files'
+task :website => [:website_generate, :website_upload, :publish_docs]
+
+desc 'Release the website and new gem version'
+task :deploy => [:check_version, :website, :release] do
+  puts "Remember to create SVN tag:"
+  puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
+    "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
+  puts "Suggested comment:"
+  puts "Tagging release #{CHANGES}"
+end
+
+desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
+task :local_deploy => [:website_generate, :install_gem]
+
+task :check_version do
+  unless ENV['VERSION']
+    puts 'Must pass a VERSION=x.y.z release version'
+    exit
+  end
+  unless ENV['VERSION'] == VERS
+    puts "Please update your version.rb to match the release version, currently #{VERS}"
+    exit
+  end
+end
+
+

data/examples/instant_messenger.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+current_dir = File.dirname(File.expand_path(__FILE__))
+lib_path = File.join(current_dir, '..', 'lib')
+$LOAD_PATH.unshift lib_path
+
+# Load up the library!
+require 'journeta'
+include Journeta
+
+
+# Any arbitrary object can be sent to peers as long as it's serializable to YAML.
+# We'll create an ordinary class with a couple typical-looking fields to send to our peers.
+class ExampleMessage
+  attr_accessor :name
+  attr_accessor :text
+end
+
+# A message handler will be called by the engine every time a message is received.
+# This code will be customized for your application-specific needs.
+class ExampleHandler < Journeta::DefaultSessionHandler
+  def handle(message)
+    puts "#{message.name.chop}: #{message.text}"
+  end
+end
+
+# Now we'll create an instance of the Journeta P2P engine.
+# We'll change the default incoming session port to a
+# pseudo-randomly generated number so multiple instances
+# may be started on the same machine.
+#
+# You'll need to find an unused port if..
+# (1) you intend to run multiple peers on the same machine, or
+# (2) the default port (Journeta::JournetaEngine::DEFAULT_SESSION_PORT)
+#     is otherwise already taken on your machine.
+session_port = (2048 + rand( 2 ** 8))
+journeta = Journeta::JournetaEngine.new(:session_port => session_port, :session_handler => ExampleHandler.new)
+
+
+# Let the magic begin!
+journeta.start
+
+puts "What's your name?"
+name = gets
+
+# The `known_peers` call allows you to access the registry of known available peers on the network.
+# The UUID associated which each peer will be unique accross the network.
+peers = journeta.known_peers
+if peers.size > 0
+  puts 'The following peers IDs are online..'
+  peers.each do |uuid, peer|
+    puts " #{uuid}; version #{peer.version}"
+  end
+else
+  puts 'No peers known. (Start another client!)'
+end
+
+
+# Sit around are watch events at the console until the user hits <enter>
+puts 'Text you enter here will automatically be shown on peers terminals.'
+begin
+   loop do
+      input = gets
+      m = ExampleMessage.new
+      m.name = name
+      m.text = input
+      journeta.send_to_known_peers(m)
+   end
+ensure
+end
+
+# Please stop the engine when shutting down. This broadcasts a message
+# stating you are going offline as a courtesy to your peers.
+journeta.stop
+
+# The engine can be restarted and stopped as many times as you'd like.
+journeta.start
+journeta.stop

data/lib/journeta.rb

@@ -0,0 +1,16 @@
+
+require 'yaml'
+
+
+require 'journeta/logger'
+require 'journeta/version'
+require 'journeta/asynchronous'
+
+require 'journeta/session_listener'
+require 'journeta/session_handler'
+require 'journeta/event_broadcaster'
+require 'journeta/event_listener'
+require 'journeta/presence_message'
+require 'journeta/peer_registry'
+require 'journeta/peer_connection'
+require 'journeta/journeta_engine'

data/lib/journeta/asynchronous.rb

@@ -0,0 +1,34 @@
+require 'journeta/logger'
+
+module Journeta
+
+   class Asynchronous
+      
+      include Logger
+      
+      attr_accessor :thread, :engine
+
+      def initialize(engine)
+         @engine = engine
+      end
+      
+      def start
+         putsd "Creating asynchronous thread for I/O: #{self.class.to_s}."
+         @thread = Thread.new {
+            go # @engine
+         }
+      end
+      	      
+      def stop
+         Thread.kill(@thread)
+         @thread.join
+         @thread = nil
+   	end
+   	
+   	def go #(engine)
+   	   raise NotImplementedException
+	   end
+	   
+	end
+	
+end

data/lib/journeta/event_broadcaster.rb

@@ -0,0 +1,36 @@
+#require 'yaml'
+
+require 'journeta/asynchronous'
+
+
+module Journeta
+   
+   class EventBroadcaster < Journeta::Asynchronous
+      
+      attr_accessor :thread
+
+     	def go #(engine)
+           address = @engine.configuration[:event_address]
+           port = @engine.configuration[:event_port]
+           delay = @engine.configuration[:event_period]
+           uuid = @engine.configuration[:uuid]
+           session_port = @engine.configuration[:session_port]
+           begin
+              socket = UDPSocket.open
+              socket.setsockopt(Socket::IPPROTO_IP, Socket::IP_TTL, [1].pack('i'))
+              loop do
+                 putsd "Sending presence event."
+                 note = PresenceMessage.new uuid, session_port
+                 socket.send(note.to_yaml, 0, address, port)
+                 sleep delay
+              end
+           ensure
+              putsd "Closing event broadcaster socket."
+              socket.close
+           end
+     	end
+
+   end
+   
+end
+

data/lib/journeta/event_listener.rb

@@ -0,0 +1,57 @@
+require 'yaml'
+require 'socket'
+require 'ipaddr'
+require 'journeta/asynchronous'
+require 'journeta/peer_connection'
+
+module Journeta
+  
+  # uses the fucked up socket api to listen for events broadcast from peers
+  class EventListener < Journeta::Asynchronous
+    
+    
+    def go #(engine)
+      event_address = @engine.configuration[:event_address]
+      port = @engine.configuration[:event_port]
+      addresses =  IPAddr.new(event_address).hton + IPAddr.new("0.0.0.0").hton
+      begin
+        socket = UDPSocket.new
+        # Remember how i said this was fucked up? yeaahhhhhh. i hope you like C.
+        # `man setsockopt` for details.
+        # SO_REUSEPORT is needed so multiple peers can be run on the same machine.
+        socket.setsockopt( Socket::SOL_SOCKET, Socket::SO_REUSEPORT, [1].pack("i_") )
+        # socket.setsockopt( Socket::SOL_SOCKET, Socket::SO_REUSEADDR, [1].pack("i_") )
+        socket.setsockopt(Socket::IPPROTO_IP, Socket::IP_ADD_MEMBERSHIP, addresses)
+        socket.bind(Socket::INADDR_ANY, port)
+        putsd "Waiting for presence events."
+        loop do
+          # Why 1024? umm.. because it's Thursday!
+          data, meta = socket.recvfrom 1024
+          Thread.new(data) {
+            event = YAML.load(data)
+            if event.uuid != @engine.configuration[:uuid]
+#              putsd "New Event: #{data} #{meta.inspect}"
+              # Update registry
+              m = YAML::load(data)
+              peer = PeerConnection.new
+#              require 'pp'
+#              pp m
+              # Why is this always [2]? Not sure.. they should have returned a hash instead.
+              peer.ip_address = meta[2]
+              peer.session_port = m.session_port
+              peer.uuid = m.uuid
+              peer.version = m.version
+              @engine.register_peer peer
+            end
+          }
+          # putsd "Event received!"
+        end
+      ensure
+        putsd "Closing event listener socket."
+        socket.close
+      end
+    end
+    
+  end
+  
+end

data/lib/journeta/journeta_engine.rb

@@ -0,0 +1,114 @@
+# Copyright © 2007 OpenRain, LLC. All rights reserved.
+#
+# Preston Lee <preston.lee@openrain.com>
+
+
+module Journeta
+  
+  class JournetaEngine
+    
+    include Logger
+
+    # Continuously sends out "i'm here" presence messages to the local network
+    attr_accessor :event_broadcaster
+    # continuously listens for "i'm here" presence messages from other peers
+    attr_accessor :event_listener
+
+    # Constantly listens for incoming peer sessions
+    attr_accessor :session_listener
+    # Application logic which processes session data.
+    attr_accessor :session_handler
+
+    # Authoritative peer availability database.
+    attr_accessor :peer_registry
+
+    # Instance-specific configuration which may be overriden at initialization time by the application
+    attr_reader :configuration
+
+    # The universally-unique ID of this instance.
+    attr_reader :uuid
+    
+    @@DEFAULT_SESSION_PORT = 31338
+    @@DEFAULT_EVENT_PORT = 31337
+    @@DEFAULT_SESSION_HANDLER = DefaultSessionHandler.new
+    
+    # Addresses 224.0.0.0 through 239.255.255.255 are reserved for multicast messages.
+    @@DEFAULT_EVENT_NETWORK = '224.220.221.222'
+    @@DEFAULT_EVENT_PERIOD = 4
+    
+    
+    def initialize(configuration ={})
+      putsd "CON: #{configuration}"
+      @configuration = Hash.new
+      
+      # A supposedly universally unique id for this instance. not technically gauranteed but close enough for now.
+      # TODO make guaranteed to be unique.
+      @configuration[:uuid] = configuration[:uuid] || rand(2 ** 31)
+      # the tcp port to use for direct peer connections
+      @configuration[:session_port] = configuration[:session_port] || @@DEFAULT_SESSION_PORT
+
+      @session_handler = configuration[:session_handler] || @@DEFAULT_SESSION_HANDLER
+      
+      # The UDP port for event broadcast messages.
+      @configuration[:event_port] = configuration[:event_port] || @@DEFAULT_EVENT_PORT
+
+      # The UDP network address used for broadcast messages.
+      @configuration[:event_address] = configuration[:event_address] || @@DEFAULT_EVENT_NETWORK
+
+      # The delay, in seconds, between presence notification broadcasts.
+      @configuration[:event_period] = configuration[:event_period] || @@DEFAULT_EVENT_PERIOD
+      
+      # Initialize sub-components.
+      @session_listener = Journeta::SessionListener.new self
+      @event_listener = EventListener.new self
+      @event_broadcaster = EventBroadcaster.new self
+      @peer_registry = PeerRegistry.new self
+    end
+    
+    def start
+      # start a session listener first so we don't risk missing a connection attempt
+      putsd "Starting #{@session_listener.class.to_s}"
+      @session_listener.start
+      
+      # start listening for peer events
+      putsd "Starting #{@event_listener.class.to_s}"
+      @event_listener.start
+      
+      # start sending our own events
+      putsd "Starting #{@event_broadcaster.class.to_s}"
+      @event_broadcaster.start
+    end
+    
+    def stop
+      # stop broadcasting events
+      @event_broadcaster.stop
+      # stop listener for events
+      @event_listener.stop
+      # stop listening for incoming peer sessions
+      @session_listener.stop
+    end
+    
+    def send_to_known_peers(payload)
+      # Delegate directly.
+      peer_registry.send_to_known_peers(payload)
+    end
+    
+    def send_to_peer(peer_uuid, payload)
+      # Delegate directly.
+      peer_registry.send_to_peer(peer_uuid, payload)
+    end
+    
+    # Returns metadata on all known peers in a hash, keyed by the uuid of each.
+    # A record corresponding to this peer is not included.
+    def known_peers()
+      peer_registry.peers # FIXME Returns objects outside of synchronized context.
+    end
+    
+    # Adds (or updates) the given +PeerConnection+.
+    def register_peer(peer)
+      peer_registry.add(peer)
+    end
+    
+  end
+  
+end