spread-client 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Tim Lossen
+
+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.md

@@ -0,0 +1,45 @@
+# spread_client
+
+portable ruby bindings for the [spread toolkit](http://www.spread.org), version 3.17.x
+
+## usage
+
+    sudo gem install spread-client -s http://gemcutter.org
+    
+then
+
+    require 'rubygems'
+    require 'spread_client'
+
+    c = SpreadClient::connect('bob')
+    c.join('chat')
+    c.multicast('chat', 'hello folks!')
+    c.leave('chat')
+    c.disconnect
+
+## setup instructions
+
+1. install the spread toolkit:
+
+        $ sudo port install spread
+        
+    or
+    
+        $ sudo apt-get install spread
+        
+    or see <http://www.spread.org> for instructions on how to install from source.
+
+2. create a simple `spread.conf`:
+
+        # one spread daemon running on port 4803 on localhost
+        Spread_Segment 127.0.0.255:4803 {
+        	localhost 127.0.0.1
+        }
+	
+3. start the spread daemon:
+
+        $ spread -n localhost -c spread.conf
+
+## Copyright
+
+Copyright (c) 2009 Tim Lossen. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "spread-client"
+    gem.summary = "ruby bindings for libspread (built with ffi)"
+    gem.description = "portable ruby bindings for libspread (built with ffi)."
+    gem.email = "tim@lossen.de"
+    gem.homepage = "http://github.com/tlossen/spread_client"
+    gem.authors = ["Tim Lossen"]
+    gem.files.include('lib/**/*.rb')
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "spread_client #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :test => :check_dependencies
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/example/demo.rb

@@ -0,0 +1,10 @@
+require File.join(File.dirname(__FILE__), '..', 'lib', 'spread_client')
+
+c = SpreadClient::connect('bob')
+c.join('chat')
+puts c.receive().inspect
+c.multicast('chat', 'hello folks!')
+puts c.receive().inspect
+c.leave('chat')
+puts c.receive().inspect
+c.disconnect

data/example/spread.conf

@@ -0,0 +1,4 @@
+# one spread daemon running on localhost:4803
+Spread_Segment 127.0.0.255:4803 {
+	localhost 127.0.0.1
+}

data/example/start.sh

@@ -0,0 +1 @@
+spread -n localhost -c spread.conf

data/lib/spread_client.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'ffi'
+
+require File.join(File.dirname(__FILE__), 'spread_client', 'ffi')
+require File.join(File.dirname(__FILE__), 'spread_client', 'connection')
+require File.join(File.dirname(__FILE__), 'spread_client', 'errors')
+require File.join(File.dirname(__FILE__), 'spread_client', 'messages')
+
+
+

data/lib/spread_client/connection.rb

@@ -0,0 +1,163 @@
+module SpreadClient
+  
+  class Connection
+    
+    UNRELIABLE_MESS      = 0x00000001
+    RELIABLE_MESS        = 0x00000002
+    FIFO_MESS            = 0x00000004
+    CAUSAL_MESS          = 0x00000008
+    AGREED_MESS          = 0x00000010
+    SAFE_MESS            = 0x00000020
+    REGULAR_MESS         = 0x0000003f
+                         
+    SELF_DISCARD		     = 0x00000040
+    DROP_RECV            = 0x01000000
+                         
+    REG_MEMB_MESS        = 0x00001000
+    TRANSITION_MESS      = 0x00002000
+    CAUSED_BY_JOIN		   = 0x00000100
+    CAUSED_BY_LEAVE		   = 0x00000200
+    CAUSED_BY_DISCONNECT = 0x00000400
+    CAUSED_BY_NETWORK	   = 0x00000800
+    MEMBERSHIP_MESS      = 0x00003f00
+                         
+    ENDIAN_RESERVED      = 0x80000080
+    RESERVED             = 0x003fc000
+    REJECT_MESS          = 0x00400000
+
+    SERVICE_TYPE = {
+      :unreliable => UNRELIABLE_MESS,
+      :reliable => RELIABLE_MESS,
+      :fifo => FIFO_MESS,
+      :causal => CAUSAL_MESS,
+      :agreed => AGREED_MESS,
+      :safe => SAFE_MESS
+    }
+    
+    DEFAULT_SERVER = 'localhost'
+    DEFAULT_PORT = 4803
+    DEFAULT_NOTIFY = true
+    DEFAULT_PRIORITY = 0
+    DEFAULT_SERVICE_TYPE = :safe
+    DEFAULT_SELF_DISCARD = false
+    DEFAULT_MESSAGE_TYPE = 0
+    
+    MAX_GROUPS = 16
+    MAX_GROUP_LENGTH = 32
+    MAX_MESSAGE_LENGTH = 512
+    
+    def initialize(name, options = {}) #:nodoc:
+      @mbox, @name = *connect(name, options)
+    end
+    
+    # the private group name of this connection.
+    def name
+      @name
+    end
+    
+    # disconnect from the spread server.
+    def disconnect
+      result = SpreadClient.SP_disconnect(@mbox)
+      raise SpreadClient.error_for(result) unless result == 0
+    end
+  
+    # join the given group.
+    def join(group)
+      result = SpreadClient.SP_join(@mbox, group)
+      raise SpreadClient.error_for(result) unless result == 0
+    end
+  
+    # leave the given group.
+    def leave(group)
+      result = SpreadClient.SP_leave(@mbox, group)
+      raise SpreadClient.error_for(result) unless result == 0
+    end
+  
+    # send a message to a group. 
+    #
+    # options:
+    # * :service_type -- can be one of
+    #   * :unreliable
+    #   * :reliable
+    #   * :fifo
+    #   * :causal
+    #   * :agreed
+    #   * :safe (default)
+    # * :self_discard -- set this to true if you do not want to receive your own message (default is false) 
+    def multicast(group, message, options = {})
+      options = { :service_type => DEFAULT_SERVICE_TYPE, :self_discard => DEFAULT_SELF_DISCARD }.merge(options)
+      service_type = SERVICE_TYPE[options[:service_type]] | (options[:self_discard] ? SELF_DISCARD : 0)
+      result = SpreadClient.SP_multicast(@mbox, service_type, group, DEFAULT_MESSAGE_TYPE, 
+        message.length, message)
+      raise SpreadClient.error_for(result) if result < 0
+    end
+  
+    # receive the next message or notification.
+    #
+    # this method blocks until a message is available.
+    def receive
+      service_type = FFI::MemoryPointer.new(:int)
+      sender = FFI::MemoryPointer.new(:char, MAX_GROUP_LENGTH)
+      num_groups = FFI::MemoryPointer.new(:int)
+      groups = FFI::MemoryPointer.new(:char, MAX_GROUPS * MAX_GROUP_LENGTH)
+      message_type = FFI::MemoryPointer.new(:int)
+      endian_mismatch = FFI::MemoryPointer.new(:int)
+      message = FFI::MemoryPointer.new(:char, MAX_MESSAGE_LENGTH)
+      result = SpreadClient.SP_receive(@mbox, service_type, sender, MAX_GROUPS, num_groups, groups, 
+        message_type, endian_mismatch, MAX_MESSAGE_LENGTH, message)
+      raise SpreadClient.error_for(result) if result < 0
+      service_type = service_type.read_int
+      sender = sender.read_string
+      num_groups = num_groups.read_int
+      groups = read_groups(groups, num_groups)
+      message = message.read_string
+      case
+        when regularMessage?(service_type)
+          Message.new(sender, message)
+        when membershipMessage?(service_type)
+          Notification.new(sender, groups, causedBy(service_type))
+      end
+    end
+
+  private
+  
+    def regularMessage?(type)         
+      (type & REGULAR_MESS > 0) && !(type & REJECT_MESS > 0)
+    end
+  
+    def membershipMessage?(type)
+      (type & MEMBERSHIP_MESS > 0) && !(type & REJECT_MESS > 0)
+    end
+  
+    def causedBy(type)
+      case
+        when type & CAUSED_BY_JOIN > 0 then :join
+        when type & CAUSED_BY_LEAVE > 0 && type & REG_MEMB_MESS == 0 then :self_leave
+        when type & CAUSED_BY_LEAVE > 0 then :leave
+        when type & CAUSED_BY_DISCONNECT > 0 then :disconnect
+        when type & CAUSED_BY_NETWORK > 0 then :network
+      end
+    end
+
+    def connect(name, options = {})
+      options = { :server => DEFAULT_SERVER, :port => DEFAULT_PORT, :notify => DEFAULT_NOTIFY }.merge(options)
+      spread_server = "#{options[:port]}@#{options[:server]}"
+      notify = options[:notify] ? 1 : 0
+      mbox = FFI::MemoryPointer.new(:int)
+      private_group = FFI::MemoryPointer.new(:char, MAX_GROUP_LENGTH)
+      result = SpreadClient.SP_connect(spread_server, name, DEFAULT_PRIORITY, notify, mbox, private_group)
+      raise SpreadClient.error_for(result) unless result == 1
+      [mbox.read_int, private_group.read_string]
+    end
+    
+    def read_groups(pointer, number)
+      groups = []
+      number.times do |i|
+        groups << pointer[i * MAX_GROUP_LENGTH].read_string
+      end
+      groups
+    end
+  
+  end
+
+end

data/lib/spread_client/errors.rb

@@ -0,0 +1,35 @@
+module SpreadClient
+
+  class Error < ::RuntimeError; end
+
+  class IllegalSpread < Error; end
+  class CouldNotConnect < Error; end
+  class RejectQuota < Error; end
+  class RejectNoName < Error; end
+  class RejectIllegalName < Error; end
+  class RejectNotUnique < Error; end
+  class RejectVersion < Error; end
+  class ConnectionClosed < Error; end
+  class RejectAuth < Error; end
+  
+  class IllegalSession < Error; end
+  class IllegalService < Error; end
+  class IllegalMessage < Error; end
+  class IllegalGroup < Error; end
+  class BufferTooShort < Error; end
+  class GroupsTooShort < Error; end
+  class MessageTooLong < Error; end
+
+private
+
+  def self.error_for(code)
+    errors = [nil, 
+      IllegalSpread, CouldNotConnect, RejectQuota, RejectNoName, RejectIllegalName, 
+      RejectNotUnique, RejectVersion, ConnectionClosed, RejectAuth, 
+      nil,
+      IllegalSession, IllegalService, IllegalMessage, IllegalGroup, BufferTooShort,
+      GroupsTooShort, MessageTooLong]
+    errors.at(code.abs) || Error
+  end
+
+end

data/lib/spread_client/ffi.rb

@@ -0,0 +1,41 @@
+module SpreadClient
+  extend FFI::Library
+  ffi_lib "libspread"
+
+  # open a connection to the given spread server.
+  #
+  # options:
+  # * :server (default is 'localhost')
+  # * :port (default is 4803)
+  # * :notify -- set this to false if you do not want to receive any group
+  #   membership notifications (default is true)
+  def self.connect(name, options = {})
+    Connection.new(name, options)
+  end
+
+private
+  
+  # int SP_connect(const char* spread name, const char* private name, int priority, int group_membership, 
+  #   mailbox* mbox, char* private group);
+  attach_function :SP_connect, [:string, :string, :int, :int, :pointer, :pointer], :int
+
+  # int SP_disconnect(mailbox mbox);
+  attach_function :SP_disconnect, [:int], :int
+
+  # int SP_join(mailbox mbox, const char* group);
+  attach_function :SP_join, [:int, :string], :int
+
+  # int SP_leave(mailbox mbox, const char* group);
+  attach_function :SP_leave, [:int, :string], :int
+  
+  # int SP_multicast(mailbox mbox,	service service_type,	const char* group, int16 mess_type, 
+  #  int mess_len, const char* mess);
+  attach_function :SP_multicast, [:int, :int, :string, :int16, :int, :string], :int
+
+  # int SP_receive(mailbox mbox,	service* service_type, char sender[MAX_GROUP_NAME],	int max_groups, 
+  #   int* num groups,	char groups[][MAX_GROUP_NAME], int16* mess_type, int* endian_mismatch,	
+  #   int max_mess_len, char* mess);
+  attach_function :SP_receive, [:int, :pointer, :pointer, :int, :pointer, :pointer, :pointer, :pointer, 
+    :int, :pointer], :int
+    
+end

data/lib/spread_client/messages.rb

@@ -0,0 +1,22 @@
+module SpreadClient
+
+  class Message
+    attr_reader :sender, :text
+    
+    def initialize(sender, text) #:nodoc:
+      @sender = sender
+      @text = text
+    end
+  end
+  
+  class Notification
+    attr_reader :group, :members, :cause
+    
+    def initialize(group, members, cause) #:nodoc:
+      @group = group
+      @members = members
+      @cause = cause
+    end
+  end
+  
+end

data/spread-client.gemspec

@@ -0,0 +1,62 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{spread-client}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tim Lossen"]
+  s.date = %q{2009-12-11}
+  s.description = %q{portable ruby bindings for libspread (built with ffi).}
+  s.email = %q{tim@lossen.de}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.md"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "example/demo.rb",
+     "example/spread.conf",
+     "example/start.sh",
+     "lib/spread_client.rb",
+     "lib/spread_client/connection.rb",
+     "lib/spread_client/errors.rb",
+     "lib/spread_client/ffi.rb",
+     "lib/spread_client/messages.rb",
+     "spread-client.gemspec",
+     "test/helper.rb",
+     "test/test_connection.rb",
+     "test/test_connection_no_notify.rb",
+     "test/test_errors.rb"
+  ]
+  s.homepage = %q{http://github.com/tlossen/spread_client}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{ruby bindings for libspread (built with ffi)}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_connection.rb",
+     "test/test_connection_no_notify.rb",
+     "test/test_errors.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/test/helper.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'test/unit'
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'spread_client')
+
+class Test::Unit::TestCase
+end

data/test/test_connection.rb

@@ -0,0 +1,51 @@
+require 'helper'
+
+class TestConnection < Test::Unit::TestCase
+
+  def setup
+    @c = SpreadClient::connect('bob')
+  rescue 
+    raise "this test expects a spread server running at localhost:4803"
+  end
+  
+  def teardown
+    @c.disconnect if @c
+  end
+  
+  def test_self_join_message
+    @c.join('chat')
+    message = @c.receive
+    assert_equal SpreadClient::Notification, message.class
+    assert_equal :join, message.cause
+  end
+  
+  def test_self_leave_message
+    @c.join('chat')
+    @c.receive
+    @c.leave('chat')
+    message = @c.receive
+    assert_equal SpreadClient::Notification, message.class
+    assert_equal :self_leave, message.cause
+  end
+  
+  def test_multicast
+    @c.join('chat')
+    @c.receive
+    @c.multicast('chat', 'hello folks!')
+    message = @c.receive
+    assert_equal SpreadClient::Message, message.class
+    assert_equal @c.name, message.sender
+    assert_equal 'hello folks!', message.text
+  end
+  
+  def test_multicast_with_self_discard
+    @c.join('chat')
+    @c.receive
+    @c.multicast('chat', 'one', :self_discard => true)
+    @c.multicast('chat', 'two')
+    message = @c.receive
+    assert_equal 'two', message.text
+  end
+  
+  
+end

data/test/test_connection_no_notify.rb

@@ -0,0 +1,22 @@
+require 'helper'
+
+class TestConnectionNoNotify < Test::Unit::TestCase
+
+  def setup
+    @c = SpreadClient::connect('bob', :notify => false)
+  rescue 
+    raise "this test expects a spread server running at localhost:4803"
+  end
+  
+  def teardown
+    @c.disconnect if @c
+  end
+    
+  def test_regular_message
+    @c.join('chat')
+    @c.multicast('chat', 'hello folks!')
+    message = @c.receive
+    assert_equal SpreadClient::Message, message.class
+  end
+  
+end

data/test/test_errors.rb

@@ -0,0 +1,31 @@
+require 'helper'
+
+class TestErrors < Test::Unit::TestCase
+  
+  def test_error_for
+    assert_equal SpreadClient::IllegalSpread, SpreadClient.error_for(-1)
+    assert_equal SpreadClient::CouldNotConnect, SpreadClient.error_for(-2)
+    assert_equal SpreadClient::RejectQuota, SpreadClient.error_for(-3)
+    assert_equal SpreadClient::RejectNoName, SpreadClient.error_for(-4)
+    assert_equal SpreadClient::RejectIllegalName, SpreadClient.error_for(-5)
+    assert_equal SpreadClient::RejectNotUnique, SpreadClient.error_for(-6)
+    assert_equal SpreadClient::RejectVersion, SpreadClient.error_for(-7)
+    assert_equal SpreadClient::ConnectionClosed, SpreadClient.error_for(-8)
+    assert_equal SpreadClient::RejectAuth, SpreadClient.error_for(-9)
+    
+    assert_equal SpreadClient::IllegalSession, SpreadClient.error_for(-11)
+    assert_equal SpreadClient::IllegalService, SpreadClient.error_for(-12)
+    assert_equal SpreadClient::IllegalMessage, SpreadClient.error_for(-13)
+    assert_equal SpreadClient::IllegalGroup, SpreadClient.error_for(-14)
+    assert_equal SpreadClient::BufferTooShort, SpreadClient.error_for(-15)
+    assert_equal SpreadClient::GroupsTooShort, SpreadClient.error_for(-16)
+    assert_equal SpreadClient::MessageTooLong, SpreadClient.error_for(-17)
+  end
+  
+  def test_error_for_fallback
+    assert_equal SpreadClient::Error, SpreadClient.error_for(0)
+    assert_equal SpreadClient::Error, SpreadClient.error_for(-10)
+    assert_equal SpreadClient::Error, SpreadClient.error_for(-100)
+  end
+  
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: spread-client
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Tim Lossen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-11 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: portable ruby bindings for libspread (built with ffi).
+email: tim@lossen.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- example/demo.rb
+- example/spread.conf
+- example/start.sh
+- lib/spread_client.rb
+- lib/spread_client/connection.rb
+- lib/spread_client/errors.rb
+- lib/spread_client/ffi.rb
+- lib/spread_client/messages.rb
+- spread-client.gemspec
+- test/helper.rb
+- test/test_connection.rb
+- test/test_connection_no_notify.rb
+- test/test_errors.rb
+has_rdoc: true
+homepage: http://github.com/tlossen/spread_client
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: ruby bindings for libspread (built with ffi)
+test_files: 
+- test/helper.rb
+- test/test_connection.rb
+- test/test_connection_no_notify.rb
+- test/test_errors.rb