legs 0.6.2

data/README.rdoc

@@ -0,0 +1,62 @@
+= About Legs
+
+This is Legs, the little networking doodad somewhat inspired by Camping but not all that much really. It uses a lot of ruby trickery to give you one class, Legs, which can act as a server, a client, or a peer depending on how you use it. Oh, and the protocol it uses is {JSON-RPC 1.0}[http://json-rpc.org/wiki/specification], so quite platform and language agnostic. :)
+
+If you give Legs some methods, then anyone you connect to will be able to make calls back to those methods to notify you of things. Otherwise, your instance of legs will only be able to connect out to a legs server and call methods in that server, but not the other way around. If that's all you need, learning Camping[http://github.com/why/camping/tree/master] and using http might be a better way to go, as http is a more popular and more standard protocol. :)
+
+== To connect to a Legs server running on your own computer
+
+  server = Legs.new
+   - OR -
+  server = Legs.new('localhost')
+
+== To connect to a remote server
+
+  server = Legs.new('web.address.to.server')
+
+== To connect to a server on port 1234
+
+  server = Legs.new('web.address', 1234)
+
+== To create a legs server
+
+  Legs.start do
+    def callable_method(a, b, c = 'default')
+      return "You called with params #{a}, #{b}, and #{c}"
+    end
+  end
+  
+  sleep # Stops ruby from closing as soon as Legs starts.
+  # don't put sleep if you're embedding the server in a shoes UI or something.
+
+== To add methods to legs, without creating a server
+
+  Legs.start(false) do
+    def callable_method(a, b, c = 'default')
+      return "You called with params #{a}, #{b}, and #{c}"
+    end
+  end
+
+You should do this before creating instances of Legs with Legs.new. Adding methods like this is useful, because the "TCP" network connections Legs makes work in both directions, so if you have some methods, server's you connect to will be able to call your methods to notify you of events and stuff. If you don't give it +false+ on that first line, it will start up a server as well, so other instances of Legs can connect in to you, deliciously peery. It's important to know, though, that the <tt>Legs.users</tt> only includes connections who connected to you, not outgoing connections you make with Legs.new syntax. You could make your own array of outgoing connections to keep track ot them if you want. :)
+
+Inside of your Legs.start block, there are two magic methods you can use in your code, these are +server+ and +caller+. +server+ references the Legs server object, which has methods like +users+ and some other stuff you can use to your advantage. The +caller+ method gives you the Legs instance representing that network connection (doesn't matter if they connected to you or vice versa).
+
+Legs instances, like the one you get from +caller+, and the array of them you get from <tt>server.users</tt> have a useful method called +meta+ which gives you a hash you can store whatever you like inside of. Things you might put in there include the user's name, or if they have any special powers, so you can control which methods they can use and what they can do. Here's an example: :)
+
+  Legs.start do
+    def count
+      caller.meta[:counter] ||= 0
+      caller.meta[:counter] += 1
+    end
+  end
+  
+  sleep
+
+When you connect to this server, you can call the +count+ method. Each time you call it, it will give you a number, starting with 1 and growing higher each time. Because it stores the 'counter' in the caller's meta hash, if another person connects, they will start out with the number 1 as well. You could connect to this with :)
+
+  server = Legs.new('localhost')
+  puts "#{server.count}, #{server.count}, #{server.count}"
+
+And if you run that script, you should see in your terminal: "1, 2, 3". That's pretty much how Legs works. An instance of legs has a few of it's own special methods: <tt>close!</tt>, <tt>notify!</tt>, <tt>send!</tt>, <tt>send_async!</tt>, <tt>connected?</tt>, +socket+, +parent+, +meta+, and <tt>send_data!</tt>. If you need to actually run a method on your server with one of these names, do: <tt>server.send!(:connected?, a_param, another_param)</tt> or whatever, and it'll run that method on the server for you. If you want to let the server know something, but don't care about the method's response, or any errors, you can do the same thing with <tt>legs.notify!</tt>, which will make your program run faster, especially if it's running through the web. :)
+
+Finally, if you're making a program for running over the internet, and want to make your app more responsive, you can call methods asyncronously. What this means is that the method won't return immidiately, but instead will send the request out to your network, and your program will continue to run, and then when the server responds, a block you provide will be run. The block is passed an object, call that object's +result+ or +value+ method to get the server response, or it will raise an error if the server had an error, so you can use it as though it were a syncronous response. Error is only raised the first time you call it. To do this, just give the thing a block like this: <tt>server.some_method { |result| ... do stuff with result.value ... }</tt>.

data/examples/chat-server.rb

@@ -0,0 +1,111 @@
+require '../lib/legs'
+
+# this is a work in progress, api's will change and break, one day there will be a functional matching
+# client in shoes or something
+
+Legs.start do
+  def initialize
+    @rooms = Hash.new { {'users' => [], 'messages' => [], 'topic' => 'No topic set'} }
+    @rooms['Lobby'] = {'topic' => 'General Chit Chat', 'messages' => [], 'users' => []}
+  end
+  
+  # returns a list of available rooms
+  def rooms
+    room_list = Hash.new
+    @rooms.keys.each { |rn| room_list[rn] = room_object rn, :remote, :topic, :users, :messages }
+    room_list
+  end
+  
+  # joins/creates a room
+  def join(room_name)
+    unless @rooms.keys.include?(room_name)
+      @rooms[room_name.to_s] = @rooms[room_name]
+      broadcast :room_created, room_name
+    end
+    
+#     room = room_object(room_name)
+#     
+#     unless room['users'].include?(caller)
+#       broadcast room['users'], 'user_joined', room_name, user_object(caller)
+#       room['users'].push(caller)
+#     end
+    
+    room_object room_name, :remote
+  end
+  
+  # leaves a room
+  def leave(room_name)
+    room = @rooms[room_name.to_s]
+    room['users'].delete(caller)
+    broadcast room['users'], 'user_left', room_name, user_object(caller)
+    true
+  end
+  
+  # sets the room topic message
+  def topic=(room, message)
+    room = @rooms[room.to_s]
+    room['topic'] = message.to_s
+    broadcast room['users'], 'room_changed', room_object(room, :remote, :name, :topic)
+  end
+  
+  # sets the user's name
+  def name=(name)
+    caller.meta[:name] = name.to_s
+    user_rooms(caller).each do |room_name|
+      broadcast @rooms[room_name]['users'], 'user_changed', user_object(caller)
+    end
+    true
+  end
+  
+  # returns information about ones self, clients thusly can find out their user 'id' number
+  def user(object_id = nil)
+    user = user_object( object_id.nil? ? caller : find_user_by_object_id(object_id) }.first )
+    user['rooms'] = user_rooms(user)
+    return user
+  end
+  
+  # posts a message to a room
+  def post_message(room_name, message)
+    room = room_object(room_name)
+    room['messages'].push(msg = {'user' => user_object(caller), 'time' => Time.now.to_i, 'message' => message.to_s} )
+    trim_messages room
+    broadcast room['users'], 'message', room_name.to_s, msg
+    return msg
+  end
+  
+  private
+  
+  # trims the message backlog
+  def trim_messages room
+    room = room_object(room) if room.is_a?(String)
+    while room['messages'].length > 250
+      room['messages'].shift
+    end
+  end
+  
+  # makes a user object suitable for sending back with meta info and stuff
+  def user_object user
+    object = {'id' => user.object_id}
+    user.meta.each_pair do |key, value|
+      object[key.to_s] = value
+    end
+    return object
+  end
+  
+  def room_object room_name, target = :local, *only
+    object = @rooms[room_name.to_s].dup
+    object['users'].delete_if {|user| user.connected? == false }
+    object['users'] = object['users'].map { |user| user_object(user) } if target == :remote
+    object['topic'] = 'No topic set' if object['topic'].nil? or object['topic'].empty?
+    object['name'] = room_name.to_s if target == :remote
+    object.delete_if { |key, value| only.include?(key.to_sym) == false } unless only.empty?
+    object
+  end
+  
+  # returns all the room names the user is in.
+  def user_rooms user
+    @rooms.values.select { |room| room['users'].include?(user) }.map { |room| @rooms.index(room) }
+  end
+end
+
+sleep

data/examples/echo-server.rb

@@ -0,0 +1,24 @@
+require '../lib/legs'
+
+# This is how simple a Legs server can look.
+
+Legs.start do
+  def echo(text)
+    return text
+  end
+end
+
+sleep
+
+# To test this server, first, run it in ruby, and then open another terminal, telnet localhost 30274
+# Then enter:
+#   {"method":"echo","params":["Hello World"],"id":1}
+# result should be:
+#   {"result":"Hello World","id":1}
+# however the properties may appear in a different order, this makes no difference.
+
+# Test to ensure there are no security flaws...
+# Try {"method":"object_id","params":[],"id":1}
+# Should return: {"error":"Cannot run 'object_id' because it is not defined in this server","id":1}
+# And try: {"method":"caller","params":[],"id":1}
+# Should recieve a similar error response. :)

data/examples/shoes-chat-client.rb

@@ -0,0 +1,159 @@
+# Shoes Chat Client is a generic irc-like chat system, made in Legs and Shoes, as a way to find
+# any troublesome parts in Legs and learn stuff about Shoes. :)
+
+#HOSTNAME = 'localhost'
+HOSTNAME = 'bluebie.creativepony.com'
+
+
+Shoes.setup do
+  gem 'json_pure >= 1.1.1'
+end
+
+require 'json/pure.rb'
+require '../lib/legs'
+
+# This add's some methods the server can call on to notify us of events like a new message
+Legs.start false do
+  attr_accessor :app, :rooms
+  
+  def user_left room_name, user
+    @rooms[room_name]['users'].delete_if { |u| u['id'] == user['id'] }
+  end
+  
+  def user_joined room_name, user
+    @rooms[room_name]['users'].push user unless @rooms[room_name]['users'].include?(user)
+  end
+  
+  def room_created room
+    @app.add_room room
+  end
+  
+  def room_changed room
+    @app.update_room room.delete('name'), room
+  end
+  
+  def user_changed user
+    @rooms.each do |room|
+      room['users'].map! do |room_user|
+        if user['id'] == room_user['id']
+          user
+        else
+          room_user
+        end
+      end
+    end
+    #@app.update_user_list
+  end
+  
+  def room_message room, message
+    @app.add_message message
+  end
+end
+
+
+class LegsChat < Shoes
+  url '/', :index
+  url '/room/(\w+)', :room
+  
+  Chat = Legs.new(HOSTNAME)
+  
+  def index
+    #Legs.server_object.app = self
+    #name = ask("What's your name?")
+    #Chat.notify! :set_name, name
+    
+    @@room_data = Chat.rooms
+    @@joined_rooms = []
+    @@available_rooms = @@room_data.keys
+    visit('/room/Lobby')
+  end
+  
+  def room name
+    unless @@joined_rooms.include? name
+      @@room_data[name] = Chat.join(name)
+      @@joined_rooms.push name
+    end
+    
+    @room = name
+    timer(0.5) { layout } # don't know why I need this, but layout goes all weird without delay
+  end
+  
+  def layout
+    clear do
+      background white
+      
+      @rooms_list = stack :width => 180, :height => 1.0
+      stack do
+        @log = stack :width => -360, :height => -30, :scroll => true, :margin_right => gutter
+        
+        flow :margin_right => gutter, :height => 30 do
+          @msg_input = edit_line(:width => -100)
+          
+          submit = Proc.new do
+            add_message @room, Chat.post_message(@room, @msg_input.text)
+            @msg_input.text = ''
+          end
+          
+          button("Send", :width => 100, &submit)
+        end
+
+      end
+      @users_list = stack :width => 180, :height => 1.0
+    end
+    
+    @@available_rooms.each { |r| add_room r }
+    @@room_data[@room]['messages'].each { |m| add_message @room, m }
+  end
+  
+  
+  # adds a message to the display
+  def add_message room_name, message
+    unless @@room_data[room_name]['messages'].include? message
+      messages = @@room_data[room_name]['messages']
+      messages.push message
+      @@room_data[room_name]['messages'] = messages[-500,500] if messages.length > 500
+    end
+    
+    return if room_name != @room
+    scroll_down = @log.scroll_top >= @log.scroll_max - 10
+    @log.append do
+      flow do
+        para strong(message['user']['name'] || message ['user']['id']), ':  ', message['message']
+      end
+    end
+    
+    while @log.contents.length > 500
+      @log.contents.first.remove
+    end
+    
+    @log.scroll_top = @log.scroll_max
+  end
+  
+  
+  # adds a room to the sidebar
+  def add_room room_name
+    @@available_rooms.push room_name unless @@available_rooms.include? room_name
+    @rooms_list.append do
+      flow :margin => 5 do
+        # _why assures me the :checked style will work in the next release
+        joined = check :checked => @@joined_rooms.include?(room_name) do |chk|
+          @@joined_rooms.push(room_name) and @@room_data[room_name].merge! Chat.join(room_name) if chk.checked?
+          Chat.leave(room_name) and @@joined_rooms.delete(room_name) unless chk.checked?
+        end
+        
+        para room_name, :underline => (@room == room_name ? :one : false)
+        
+        click do
+          visit("/room/#{room_name}")
+        end unless @room == room_name
+      end
+    end
+  end
+  
+  def update_room room_name, data
+    @@room_data[room_name].merge! data
+  end
+end
+
+Shoes.app(:title => "Legs Chat", :width => 700, :height => 350)
+

data/legs.gemspec

@@ -0,0 +1,13 @@
+Gem::Specification.new do |s|
+  s.name = "legs"
+  s.version = "0.6.2"
+  s.date = "2008-07-17"
+  s.summary = "Simple fun open networking for newbies and quick hacks"
+  s.email = "a@creativepony.com"
+  s.homepage = "http://github.com/Bluebie/legs"
+  s.description = "Legs is a really simple fun networking library that uses 'json-rpc' formated messages over a tcp connection to really easily built peery or server-clienty sorts of apps, for ruby newbies and hackers to build fun little things."
+  s.has_rdoc = false
+  s.authors = ["Jenna Fox"]
+  s.files = ["README.rdoc", "legs.gemspec", "lib/legs.rb", "examples/echo-server.rb", "examples/chat-server.rb", "examples/shoes-chat-client.rb", "test/test_legs.rb"]
+  s.add_dependency("json_pure", ["> 1.1.0"])
+end

data/lib/legs.rb

@@ -0,0 +1,404 @@
+# Legs take you places, a networking companion
+['rubygems', 'socket', 'thread'].each { |i| require i }
+require 'json' unless self.class.const_defined? 'JSON'
+
+class Legs
+  # general getters
+  attr_reader :socket, :parent, :meta
+  def inspect; "<Legs:#{object_id} Meta: #{@meta.inspect}>"; end
+  
+  # Legs.new for a client, subclass to make a server, .new then makes server and client!
+  def initialize(host = 'localhost', port = 30274)
+    self.class.start(port) if self.class != Legs && !self.class.started?
+    ObjectSpace.define_finalizer(self) { self.close! }
+    @parent = false; @responses = Hash.new; @meta = {}; @disconnected = false
+    @responses_mutex = Mutex.new; @socket_mutex = Mutex.new
+    
+    if host.instance_of?(TCPSocket)
+      @socket = host
+      @parent = port unless port.instance_of?(Numeric)
+    elsif host.instance_of?(String)
+      @socket = TCPSocket.new(host, port)
+      self.class.outgoing_mutex.synchronize { self.class.outgoing.push self }
+    else
+      raise "First argument needs to be a hostname, ip, or socket"
+    end
+    
+    
+    @handle_data = Proc.new do |data|
+      data = json_restore(JSON.parse(data))
+      
+      if data['method']
+        (@parent || self.class).__data!(data, self)
+      elsif data['error'] and data['id'].nil?
+        raise data['error']
+      else
+        @responses_mutex.synchronize { @responses[data['id']] = data }
+      end
+    end
+    
+    @thread = Thread.new do
+      until @socket.closed?
+        begin
+          close! if @socket.eof?
+          data = nil
+          @socket_mutex.synchronize { data = @socket.gets(self.class.terminator) rescue nil }
+          if data.nil?
+            close!
+          else
+            @handle_data[data]
+          end
+        rescue JSON::ParserError => e
+          send_data!({"error" => "JSON provided is invalid. See http://json.org/ to see how to format correctly."})
+        rescue IOError => e
+          close!
+        end
+      end
+    end
+  end
+  
+  # I think you can guess this one
+  def connected?; self.class.connections.include?(self); end
+  
+  # closes the connection and the threads and stuff for this user
+  def close!
+    return if @disconnected == true
+    
+    @disconnected = true
+    puts "User #{inspect} disconnecting" if self.class.log?
+    
+    # notify the remote side
+    notify!('**remote__disconnecting**') rescue nil
+    
+    if @parent
+      @parent.event(:disconnect, self)
+      @parent.incoming_mutex.synchronize { @parent.incoming.delete(self) }
+    else
+      self.class.outgoing_mutex.synchronize { self.class.outgoing.delete(self) }
+    end
+    
+    Thread.new { sleep(1); @socket.close rescue nil }
+  end
+  
+  # send a notification to this user
+  def notify!(method, *args, &blk)
+    puts "Notify #{inspect}: #{method}(#{args.map(&:inspect).join(', ')})" if self.class.log?
+    send_data!({'method' => method.to_s, 'params' => args, 'id' => nil})
+  end
+  
+  # sends a normal RPC request that has a response
+  def send!(method, *args, &blk)
+    puts "Call #{inspect}: #{method}(#{args.map(&:inspect).join(', ')})" if self.class.log?
+    id = get_unique_number
+    send_data! 'method' => method.to_s, 'params' => args, 'id' => id
+    
+    worker = Proc.new do
+      sleep 0.1 until @responses_mutex.synchronize { @responses.keys.include?(id) }
+      
+      result = Legs::Result.new(@responses_mutex.synchronize { @responses.delete(id) })
+      puts ">> #{method} #=> #{result.data['result'].inspect}" if self.class.log?
+      result
+    end
+    
+    if blk.respond_to?(:call); Thread.new { blk[worker.call] }
+    else; worker.call.value; end
+  end
+  
+  # catch all the rogue calls and make them work niftily
+  alias_method :method_missing, :send!
+  
+  # sends raw object over the socket
+  def send_data!(data)
+    raise "Lost remote connection" unless connected?
+    raw = JSON.generate(json_marshal(data)) + self.class.terminator
+    @socket_mutex.synchronize { @socket.write(raw) }
+  end
+  
+  
+  private
+  
+  # takes a ruby object, and converts it if needed in to marshalled hashes
+  def json_marshal(object)
+    case object
+    when Bignum, Fixnum, Integer, Float, TrueClass, FalseClass, String, NilClass
+      return object
+    when Hash
+      out = Hash.new
+      object.each_pair { |k,v| out[k.to_s] = json_marshal(v) }
+      return out
+    when Array
+      return object.map { |v| json_marshal(v) }
+    when Symbol
+      return {'__jsonclass__' => ['Legs', '__make_symbol', object.to_s]}
+    when Exception
+      return {'__jsonclass__' => ['Legs::RemoteError', 'new', "<#{object.class.name}> #{object.message}", object.backtrace]}
+    else
+      return {'__jsonclass__' => [object.class.name, '_load', object._dump]} if object.respond_to?(:_dump)
+      
+      # the default marshalling behaviour
+      instance_vars = {}
+      object.instance_variables.each do |var_name|
+        instance_vars[var_name.to_s.sub(/@/, '')] = json_marshal(object.instance_variable_get(var_name))
+      end
+      
+      return {'__jsonclass__' => [object.class.name, 'new']}.merge(instance_vars)
+    end
+  end
+  
+  SAFE_CONSTRUCTORS = ['new', 'allocate', '_load']
+  
+  # takes an object from the network, and decodes any marshalled hashes back in to ruby objects
+  def json_restore(object)
+    case object
+    when Hash
+      if object.keys.include? '__jsonclass__'
+        constructor = object.delete('__jsonclass__')
+        class_name = constructor.shift.to_s
+        
+        # find the constant through the heirachy
+        object_class = Module
+        class_name.split(/::/).each { |piece_of_const| object_class = object_class.const_get(piece_of_const) } rescue false
+        
+        if object_class
+          unless constructor.empty?
+            raise "Unsafe marshaling constructor method: #{constructor.first}" unless (object_class == Legs and constructor.first =~ /^__make_/) or SAFE_CONSTRUCTORS.include?(constructor.first)
+            raise "#{class_name} doesn't support the #{constructor.first} constructor" unless object_class.respond_to?(constructor.first)
+            instance = object_class.__send__(*constructor)
+          else
+            instance = object_class.allocate
+          end
+          
+          object.each_pair do |key, value|
+            instance.instance_variable_set("@#{key}", json_restore(value))
+          end
+          return instance
+        else
+          raise "Response contains a #{class_name} but that class is not loaded locally, it needs to be."
+        end
+      else
+        hash = Hash.new
+        object.each_pair { |k,v| hash[k] = json_restore(v) }
+        return hash
+      end
+    when Array
+      return object.map { |i| json_restore(i) }
+    else
+      return object
+    end
+  end
+  
+  # gets a unique number that we can use to match requests to responses
+  def get_unique_number; @unique_id ||= 0; @unique_id += 1; end
+end
+
+# undef's the superclass's methods so they won't get in the way
+removal_list = Legs.instance_methods(true)
+removal_list -= %w{JSON new class object_id send __send__ __id__ < <= <=> => > == === yield raise}
+removal_list -= Legs.instance_methods(false)
+Legs.class_eval { removal_list.each { |m| undef_method m } }
+
+
+# the server is started by subclassing Legs, then SubclassName.start
+class << Legs
+  attr_accessor :terminator, :log
+  attr_reader :incoming, :outgoing, :server_object, :incoming_mutex, :outgoing_mutex, :messages_mutex
+  alias_method :log?, :log
+  alias_method :users, :incoming
+  def started?; @started; end
+  
+  def initializer
+    ObjectSpace.define_finalizer(self) { self.stop! }
+    @incoming = []; @outgoing = []; @messages = Queue.new; @terminator = "\n"; @log = false
+    @incoming_mutex = Mutex.new; @outgoing_mutex = Mutex.new; @started = false
+  end
+  
+  
+  # starts the server, pass nil for port to make a 'server' that doesn't actually accept connections
+  # This is useful for adding methods to Legs so that systems you connect to can call methods back on you
+  def start(port=30274, &blk)
+    return @server_class.module_eval(&blk) if started? and blk.respond_to? :call
+    @started = true
+    
+    # makes a nice clean class to hold all the server methods.
+    if @server_class.nil?
+      @server_class = Class.new
+      @server_class.module_eval do
+        private
+        attr_reader :server, :caller
+        
+        # sends a notification message to all connected clients
+        def broadcast(*args)
+          if args.first.is_a?(Array)
+            list = args.shift
+            method = args.shift
+          elsif args.first.is_a?(String) or args.first.is_a?(Symbol)
+            list = server.incoming
+            method = args.shift
+          else
+            raise "You need to specify a 'method' to broadcast out to"
+          end
+          
+          list.each { |user| user.notify!(method, *args) }
+        end
+        
+        # Finds a user by the value of a certain property... like find_user_by :object_id, 12345
+        def find_user_by_object_id value
+          server.incoming.find { |user| user.object_id == value }
+        end
+        
+        # finds user's with the specified meta keys matching the specified values, can use regexps and stuff, like a case block
+        def find_users_by_meta hash = nil
+          raise "You need to give find_users_by_meta a hash to check the user's meta hash against" if hash.nil?
+          server.incoming.select do |user|
+            hash.all? { |key, value| value === user.meta[key] }
+          end
+        end
+        
+        public # makes it public again for the user code
+      end
+    end
+    
+    @server_class.module_eval(&blk) if blk.respond_to?(:call)
+    
+    if @server_object.nil?
+      @server_object = @server_class.allocate
+      @server_object.instance_variable_set(:@server, self)
+      @server_object.instance_eval { initialize }
+    end
+  
+    @message_processor = Thread.new do
+      while started?
+        sleep 0.01 while @messages.empty?
+        data, from = @messages.deq
+        method = data['method']; params = data['params']
+        methods = @server_object.public_methods(false)
+        
+        # close dead connections
+        if data['method'] == '**remote__disconnecting**'
+          from.close!
+          next
+        else
+          begin
+            raise "Supplied method is not a String" unless method.is_a?(String)
+            raise "Supplied params object is not an Array" unless params.is_a?(Array)
+            raise "Cannot run '#{method}' because it is not defined in this server" unless methods.include?(method.to_s) or methods.include? :method_missing
+            
+            puts "Call #{method}(#{params.map(&:inspect).join(', ')})" if log?
+            
+            @server_object.instance_variable_set(:@caller, from)
+            
+            result = nil
+            
+            @incoming_mutex.synchronize do
+              if methods.include?(method.to_s)
+                result = @server_object.__send__(method.to_s, *params)
+              else
+                result = @server_object.method_missing(method.to_s, *params)
+              end
+            end
+            
+            puts ">> #{method} #=> #{result.inspect}" if log?
+            
+            from.send_data!({'id' => data['id'], 'result' => result}) unless data['id'].nil?
+            
+          rescue Exception => e
+            from.send_data!({'error' => e, 'id' => data['id']}) unless data['id'].nil?
+            puts "Error: #{e}\nBacktrace: " + e.backtrace.join("\n   ") if log?
+          end
+        end
+      end
+    end unless @message_processor and @message_processor.alive?
+    
+    if ( port.nil? or port == false ) == false and @listener.nil?
+      @listener = TCPServer.new(port)
+      
+      @acceptor_thread = Thread.new do
+        while started?
+          user = Legs.new(@listener.accept, self)
+          @incoming_mutex.synchronize { @incoming.push user }
+          puts "User #{user.object_id} connected, number of users: #{@incoming.length}" if log?
+          self.event :connect, user
+        end
+      end
+    end
+  end
+  
+  # stops the server, disconnects the clients
+  def stop
+    @started = false
+    @incoming.each { |user| user.close! }
+  end
+  
+  # returns an array of all connections
+  def connections
+    @incoming + @outgoing
+  end
+  
+  # add an event call to the server's message queue
+  def event(name, sender, *extras)
+    return unless @server_object.respond_to?("on_#{name}")
+    __data!({'method' => "on_#{name}", 'params' => extras.to_a, 'id' => nil}, sender)
+  end
+  
+  # gets called to handle all incoming messages (RPC requests)
+  def __data!(data, from)
+    @messages.enq [data, from]
+  end
+  
+  # People say this syntax is too funny not to have... whatever. Works like IO and File and what have you
+  def open(*args)
+    client = Legs.new(*args)
+    yield(client)
+    client.close!
+  end
+  
+  # add's a method to the 'server' class, bound in to that class
+  def define_method(name, &blk); @server_class.class_eval { define_method(name, &blk) }; end
+  
+  # add's a block to the 'server' class in a way that retains it's old bindings.
+  # the block will be passed the caller object, followed by the args.
+  def add_block(name, &block)
+    @server_class.class_eval do
+      define_method(name) do |*args|
+        block.call caller, *args
+      end
+    end
+  end
+  
+  # lets the marshaler transport symbols
+  def __make_symbol(name); name.to_sym; end
+  
+  # hooks up these methods so you can use them off the main object too!
+  [:broadcast, :find_user_by_object_id, :find_users_by_meta].each do |name|
+    define_method name do |*args|
+      @incoming_mutex.synchronize do; @outgoing_mutex.synchronize do
+        @server_object.__send__(name, *args)
+      end; end
+    end
+  end
+end
+
+Legs.initializer
+
+# represents the data response, handles throwing of errors and stuff
+class Legs::Result
+  attr_reader :data
+  def initialize(data); @data = data; end
+  def result
+    unless @data['error'].nil? or @errored
+      @errored = true
+      raise @data['error']
+    end
+    @data['result']
+  end
+  alias_method :value, :result
+end
+
+class Legs::StartBlockError < StandardError; end
+class Legs::RequestError < StandardError; end
+class Legs::RemoteError < StandardError
+  def initialize(msg, backtrace)
+    super(msg)
+    set_backtrace(backtrace)
+  end
+end

data/test/test_legs.rb

@@ -0,0 +1,206 @@
+# Makes use of ZenTest. Install the 'ZenTest' gem, then run this ruby script in a terminal to see the results!
+require 'test/unit' unless defined? $ZENTEST and $ZENTEST
+require '../lib/legs'
+
+# want to see errors, don't want to see excessively verbose logging normally
+Thread.abort_on_exception = true
+#Legs.log = true
+
+# class to test the marshaling
+class Marshal::TesterClass; attr_accessor :a, :b, :c; end
+
+# a simple server to test with
+Legs.start(6425) do
+  def echo(text)
+    return text
+  end
+  
+  def count
+    caller.meta[:counter] ||= 0
+    caller.meta[:counter] += 1
+  end
+  
+  def methods
+    'overridden'
+  end
+  
+  def error
+    raise "This is a fake error"
+  end
+  
+  def notified
+    $notified = true
+  end
+  
+  def marshal
+    obj = Marshal::TesterClass.new
+    obj.a = 1; obj.b = 2; obj.c = 3
+    return obj
+  end
+  
+  def on_connect
+    $server_instance = caller
+  end
+  
+  def on_some_event
+    $some_event_ran = true
+  end
+  
+  # tests that we can call stuff back over the caller's socket
+  def bidirectional; caller.notify!(:bidirectional_test_reciever); end
+  def bidirectional_test_reciever; $bidirectional_worked = true; end
+end
+
+Remote = Legs.new('localhost', 6425)
+
+
+class TestLegsObject < Test::Unit::TestCase
+  def test_class_broadcast
+    $notified = false
+    Legs.broadcast(:notified)
+    sleep 0.5
+    assert_equal(true, $notified)
+  end
+
+  def test_class_connections
+    assert_equal(2, Legs.connections.length)
+  end
+
+  def test_class_event
+    Legs.event :some_event, nil
+    sleep 0.1
+    assert_equal(true, $some_event_ran)
+  end
+
+  def test_class_find_user_by_object_id
+    assert_equal(Legs.incoming.first, Legs.find_user_by_object_id(Legs.incoming.first.object_id))
+  end
+
+  def test_class_find_users_by_meta
+    Legs.incoming.first.meta[:id] = 'This is the incoming legs instance'
+    assert_equal(true, Legs.find_users_by_meta(:id => /incoming legs/).include?(Legs.incoming.first))
+  end
+
+  def test_class_incoming
+    assert_equal(true, Legs.incoming.length > 0)
+  end
+
+  def test_class_outgoing
+    assert_equal(true, Legs.outgoing.is_a?(Array))
+    assert_equal(1, Legs.outgoing.length)
+  end
+  
+  def test_class_open
+    instance = nil
+    Legs.open('localhost', 6425) do |i|
+      instance = i
+    end
+    assert_equal(Legs, instance.class)
+  end
+
+  def test_class_started_eh
+    assert_equal(true, Legs.started?)
+  end
+
+  def test_connected_eh
+    assert_equal(true, Remote.connected?)
+  end
+
+  def test_close_bang
+    ii = Legs.new('localhost', 6425)
+    assert_equal(2, Legs.outgoing.length)
+    ii.close!
+    assert_equal(1, Legs.outgoing.length)
+  end
+
+  def test_meta
+    assert_equal(true, Remote.meta.is_a?(Hash))
+    Remote.meta[:yada] = 'Yada'
+    assert_equal('Yada', Remote.meta[:yada])
+  end
+
+  def test_notify_bang
+    $notified = false
+    Remote.notify! :notified
+    sleep(0.2)
+    assert_equal(true, $notified)
+  end
+
+  def test_parent
+    assert_equal(false, Remote.parent)
+    assert_equal(Legs, Legs.incoming.first.parent)
+  end
+
+  def test_send_bang
+    assert_equal(123, Remote.echo(123))
+    assert_equal(123, Remote.send!(:echo, 123))
+    
+    # check async
+    abc = 0
+    Remote.echo(123) { |r| abc = r.value }
+    sleep 0.2
+    assert_equal(123, abc)
+    
+    # check it catches ancestor method calls
+    assert_equal('overridden', Remote.methods)
+  end
+  
+  def test_symbol_marshaling
+    assert_equal(Symbol, Remote.echo(:test).class)
+  end
+
+  def test_socket
+    assert_equal(true, Remote.socket.is_a?(BasicSocket))
+  end
+  
+  def test_marshaling
+   object = Remote.marshal
+   assert_equal(1, object.a)
+   assert_equal(2, object.b)
+   assert_equal(3, object.c)
+  end
+  
+  def test_bidirectional
+   $bidirectional_worked = false; Remote.bidirectional; sleep 0.2
+   assert_equal(true, $bidirectional_worked)
+  end
+  
+  # makes sure the block adding thingos work
+  def test_adding_block
+    @bound_var = bound_var = 'Ladedadedah'
+    Legs.define_method(:defined_meth) { bound_var }
+    assert_equal(bound_var, Remote.defined_meth)
+    
+    Legs.add_block(:unbound_meth) { @bound_var }
+    assert_equal(bound_var, Remote.unbound_meth)
+  end
+  
+  # this is to make sure we can run the start method a ton of times without bad side effects
+  def test_start_again_and_again
+    Legs.start
+    Legs.start { def adding_another_method; true; end }
+    assert_equal(true, Remote.adding_another_method)
+  end
+end
+
+module TestLegs
+  class TestResult < Test::Unit::TestCase
+    def test_data
+      result = nil
+      Remote.echo(123) { |r| result = r }
+      sleep(0.2)
+      
+      assert_equal(123, result.data['result'])
+    end
+
+    def test_result
+      normal_result = Legs::Result.new({'id'=>1, 'result' => 'Hello World'})
+      error_result  = Legs::Result.new({'id'=>2, 'error' => 'Uh oh Spagetti-o\'s'})
+
+      assert_equal(normal_result.value, 'Hello World')
+      assert_equal(normal_result.result, 'Hello World')
+      assert_equal((error_result.value rescue :good), :good)
+    end
+  end
+end
+

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: legs
+version: !ruby/object:Gem::Version 
+  hash: 3
+  prerelease: 
+  segments: 
+  - 0
+  - 6
+  - 2
+  version: 0.6.2
+platform: ruby
+authors: 
+- Jenna Fox
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-07-17 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json_pure
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 1
+        - 1
+        - 0
+        version: 1.1.0
+  type: :runtime
+  version_requirements: *id001
+description: Legs is a really simple fun networking library that uses 'json-rpc' formated messages over a tcp connection to really easily built peery or server-clienty sorts of apps, for ruby newbies and hackers to build fun little things.
+email: a@creativepony.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- legs.gemspec
+- lib/legs.rb
+- examples/echo-server.rb
+- examples/chat-server.rb
+- examples/shoes-chat-client.rb
+- test/test_legs.rb
+homepage: http://github.com/Bluebie/legs
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Simple fun open networking for newbies and quick hacks
+test_files: []
+