noam_lemma 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 87f2a65c040cab0caea74d12a7e8d58d4ed36dd1
+  data.tar.gz: 0d9d0a71273809b6f28436a944fd69b2b9696c7e
+SHA512:
+  metadata.gz: 1883fc59b41232681372d16811a62d4d73d135aca9fba538f74f924b693d7d3b06a3df0b8452a0db50b35a5a56b1f85ebbabdfbde15aafc75e577c677d7636d1
+  data.tar.gz: 4933af13dc4c016f0f2038cff34c1bff9d9d6af4b83e027c6238cd52b3b71aaae389dddc58fee98f8154234e780e2285529c2a5e252d840b8d79e515a829580c

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+-r spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in noam_lemma.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 John Van Enk
+
+MIT License
+
+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,20 @@
+noam\_lemma
+===============
+
+A Noam Lemma implementation for Ruby.
+
+This library exposes the fundamental concepts in a Lemma to Ruby developers. It
+handles registration, subscription, and message processing. All one needs to do
+to create a new Lemma in a network is interact with the Noam::Lemma class. See
+the `example/` directory in the project for further details on usage.
+
+Build the ruby gem from noam lemma directory
+`gem build noam_lemma.gemspec`
+
+Install the gem
+`gem install noam_lemma-version.gem`
+
+Known Issues
+------------
+
+* Listening fails un-gracefully when the server goes down.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+require "./examples/lemma_verification"
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc "perform verification tests"
+task :verify do
+  Noam::LemmaVerification.run
+end

data/examples/free_guest_publisher.rb

@@ -0,0 +1,34 @@
+require 'noam_lemma'
+
+# This is an example of a Ruby Lemma that publishes message and *also* uses the
+# "Guest" model of connection. This Lemma will advertise that it's available on
+# the local network and only begin speaking messages once a server requests a
+# connection from the Lemma.
+
+publisher = Noam::Lemma.new('example-guest-publisher', [], ["e3"])
+
+# Using the `advertise` method asks the Lemma to announce it's presence and
+# wait for a message from a server that may want to connect to it.
+#
+# The "local-test" parameter is the room name. Servers with a room name that's
+# the same as the Lemma's advertised room name will connect automatically.
+publisher.advertise("")
+
+seq = 0
+e = "e3"
+loop do
+  # Construct a value to send with the event.
+  v = {"seq" => seq, "time" => Time.now.to_s}
+
+  # If `speak` returns false, we're unable to speak the message likely because
+  # the socket has closed. The connection would have to be restarted.
+  unless publisher.speak(e, v)
+    puts "Done"
+    break
+  end
+  puts "Wrote: #{e} -> #{v.inspect}"
+
+  seq += 1
+  # Sleep for a while so that we don't bog down the network.
+  sleep(1)
+end

data/examples/free_guest_subscriber.rb

@@ -0,0 +1,31 @@
+require 'noam_lemma'
+
+# This is an example of a Ruby Lemma that publishes message and *also* uses the
+# "Guest" model of connection. This Lemma will advertise that it's available on
+# the local network and only begin subscribing to messages once a server
+# requests a connection from the Lemma.
+
+subscriber = Noam::Lemma.new('example-guest-subscriber', ["e3"], [])
+
+# Using the `advertise` method asks the Lemma to announce it's presence and
+# wait for a message from a server that may want to connect to it.
+#
+# The "local-test" parameter is the room name. Servers with a room name that's
+# the same as the Lemma's advertised room name will connect automatically.
+subscriber.advertise("")
+
+loop do
+  # The `listen` method will return an Event object once one is received by the
+  # Lemma. Until an event is heard, the `listen` method blocks.
+  m = subscriber.listen
+
+  # There's one special value that's returned from `listen`: the `:cancelled`
+  # symbol. If this shows up, it means some one else has called the `stop`
+  # method on the Lemma.
+  if :cancelled == m
+    puts "Done"
+    break
+  else
+    puts "Read: #{m.event} -> #{m.value.inspect}"
+  end
+end

data/examples/lemma_verification.rb

@@ -0,0 +1,43 @@
+require "noam_lemma"
+
+class Noam::LemmaVerification
+  def self.run
+    echo
+    plus_one
+    sum
+    name
+  end
+
+  def self.echo
+    lemma = Noam::Lemma.new("verification", ["Echo"], ["EchoVerify"])
+    lemma.advertise("lemma_verification")
+    event = lemma.listen
+    lemma.speak("EchoVerify", event.value)
+    lemma.stop
+  end
+
+  def self.plus_one
+    lemma = Noam::Lemma.new("verification", ["PlusOne"], ["PlusOneVerify"])
+    lemma.advertise("lemma_verification")
+    event = lemma.listen
+    lemma.speak("PlusOneVerify", event.value + 1)
+    lemma.stop
+  end
+
+  def self.sum
+    lemma = Noam::Lemma.new("verification", ["Sum"], ["SumVerify"])
+    lemma.advertise("lemma_verification")
+    event = lemma.listen
+    lemma.speak("SumVerify", event.value.inject {|sum, v| sum + v})
+    lemma.stop
+  end
+
+  def self.name
+    lemma = Noam::Lemma.new("verification", ["Name"], ["NameVerify"])
+    lemma.advertise("lemma_verification")
+    event = lemma.listen
+    fullname = "#{event.value["firstName"]} #{event.value["lastName"]}"
+    lemma.speak("NameVerify", {fullName: fullname})
+    lemma.stop
+  end
+end

data/examples/publisher.rb

@@ -0,0 +1,47 @@
+require 'noam_lemma'
+
+# This is an example of a Ruby Lemma that publishes messages. It expects a Noam
+# server to be running. It also expects that the noam-lemma.rb file is in the
+# search path. If you run this example from the project root, the following
+# command should work:
+#
+#   ruby -Ilib example/publisher.rb
+#
+# This example _will not_ work on the same machine running the Noam server as
+# both programs need to bind to UDP port 1030.
+
+publisher = Noam::Lemma.new('example-publisher', [], ["e1", "e2"])
+
+# Using the `discover` method asks the Lemma to proactively try and discover a
+# server to connect to on the local network. Once the server is discovered, it
+# will connect and send a Noam 'register' message. When `discover` returns, the
+# Lemma is ready to send events.
+publisher.discover
+
+seq = 0
+loop do
+  # This method block picks an event to send. It's randomized a bit so that we
+  # can see things change over time.
+  e = if 0.5 < rand()
+        "e1"
+      else
+        "e2"
+      end
+
+  # Next, package the event sequence and the current time into a value.
+  v = {"seq" => seq, "time" => Time.now.to_s}
+
+  # Attempt to speak the chosen event with the value. Note, the event is either
+  # "e1" or "e2" based on how rand() returned.
+  unless publisher.speak(e, v)
+    # If `speak` returns false, we're unable to speak the message likely because
+    # the socket has closed. The connection would have to be restarted.
+    puts "Done"
+    break
+  end
+  puts "Wrote: #{e} -> #{v.inspect}"
+
+  seq += 1
+  # Sleep for a while so that we don't bog down the network.
+  sleep(1)
+end

data/examples/subscriber.rb

@@ -0,0 +1,35 @@
+require 'noam_lemma'
+
+# This is an example of a Ruby Lemma that subscribes to messages. It expects a
+# Noam server to be running. It also expects that the noam-lemma.rb file is in
+# the search path. If you run this example from the project root, the following
+# command should work:
+#
+#   ruby -Ilib example/subscriber.rb
+#
+# This example _will not_ work on the same machine running the Noam server as
+# both programs need to bind to UDP port 1030.
+
+subscriber = Noam::Lemma.new('example-subscriber', ["e1", "e2"], [])
+
+# Using the `discover` method asks the Lemma to proactively try and discover a
+# server to connect to on the local network. Once the server is discovered, it
+# will connect and send a Noam 'register' message. When `discover` returns, the
+# Lemma is ready to receive events.
+subscriber.discover
+
+loop do
+  # The `listen` method will return an Event object once one is received by the
+  # Lemma. Until an event is heard, the `listen` method blocks.
+  m = subscriber.listen
+
+  # There's one special value that's returned from `listen`: the `:cancelled`
+  # symbol. If this shows up, it means some one else has called the `stop`
+  # method on the Lemma.
+  if :cancelled == m
+    puts "Done"
+    break
+  else
+    puts "Read: #{m.event} -> #{m.value.inspect}"
+  end
+end

data/lib/noam_lemma/beacon.rb

@@ -0,0 +1,36 @@
+module Noam
+  class Beacon
+    attr_reader :name, :host, :port
+
+    def initialize(name, host, port)
+      @name = name
+      @host = host
+      @port = port
+    end
+
+    def self.discover(net = "0.0.0.0")
+      socket = UDPSocket.new
+      begin
+        socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_BROADCAST, true)
+        socket.bind(net, Noam::BEACON_PORT)
+
+        raise "Didn't see beacon after #{WAIT_TIME} seconds." unless message_received?(socket)
+
+        data, addr = socket.recvfrom(MAX_RESPONSE_LENGTH)
+        parsed_data = JSON.parse(data)
+        Beacon.new(parsed_data[1], addr[2], parsed_data[2])
+      ensure
+        socket.close
+      end
+    end
+
+    private
+
+    MAX_RESPONSE_LENGTH = 1600
+    WAIT_TIME = 10.0
+
+    def self.message_received?(socket)
+      IO.select([socket], [], [], WAIT_TIME) != nil
+    end
+  end
+end

data/lib/noam_lemma/lemma.rb

@@ -0,0 +1,70 @@
+require "noam_lemma/message_filter"
+
+module Noam
+  class Lemma
+    attr_reader :name, :listener, :player, :speaks
+
+    def initialize(name, hears = [], speaks = [])
+      @name = name
+      @speaks = speaks
+      @player = nil
+      @listener = nil
+
+      initialize_message_filter(hears)
+    end
+
+    def discover(beacon = nil)
+      beacon ||= Beacon.discover
+      start(beacon.host, beacon.port)
+    end
+
+    def advertise(room_name)
+      marco = Noam::Message::Marco.new(room_name, @name)
+      polo = marco.start
+      start(polo.host, polo.port)
+    end
+
+    def speak(event, value)
+      if @player
+        @player.put(Noam::Message::Playable.new(@name, event, value))
+        true
+      else
+        false
+      end
+    end
+
+    def listen
+      @listener.take
+    end
+
+    def stop
+      @player.stop if @player
+      @listener.stop if @listener
+      @player = nil
+      @listener = nil
+    end
+
+    def hears
+      @message_filter.hears
+    end
+
+    def set_message_filter(message_filter)
+      @message_filter = message_filter
+    end
+
+    private
+
+    def start(host, port)
+      @listener = Listener.new
+      @player = Player.new(host, port)
+      @player.put(Message::Register.new(@name, @listener.port, @message_filter.hears, @speaks))
+    end
+
+    def initialize_message_filter(hears)
+      @message_filter = MessageFilter.new
+      hears.each do |event_name|
+        @message_filter.hear(event_name) {}
+      end
+    end
+  end
+end

data/lib/noam_lemma/listener.rb

@@ -0,0 +1,73 @@
+require 'thread' 
+
+module Noam
+  class Listener
+    attr_reader :port
+
+    def initialize
+      @queue = Queue.new
+      @server = TCPServer.new(0)
+      @port = @server.addr[1]
+
+      manage_queue_on_thread
+    end
+
+    def take
+      @queue.pop
+    end
+
+    def stop
+      @exit_requested = true
+      @thread.join
+    end
+
+    private
+
+    def manage_queue_on_thread
+      @thread = Thread.new do |t|
+        begin
+          loop_listen
+        ensure
+          @server.close
+        end
+      end
+    end
+
+    def loop_listen
+      loop do
+        if client = listen_for_connection
+          read_from_client(client)
+          client.close
+        end
+
+        if exiting?
+          @queue.push(:cancelled)
+          break
+        end
+      end
+    end
+
+    def listen_for_connection
+      timeout_sec = 0.1
+      available_ios = select([@server], nil, nil, timeout_sec)
+      @server.accept if available_ios
+    end
+
+    def read_from_client(client)
+      begin
+        loop do
+          message_length = client.read_nonblock(Message::MESSAGE_LENGTH_STRING_SIZE).to_i
+          message_content = client.read_nonblock(message_length)
+          @queue.push(Message::Heard.from_noam(message_content))
+          break if exiting?
+        end
+      rescue IO::WaitReadable
+        retry unless exiting?
+      end
+    end
+
+    def exiting?
+      return @exit_requested
+    end
+  end
+end

data/lib/noam_lemma/message/heard.rb

@@ -0,0 +1,18 @@
+module Noam
+  module Message
+    class Heard
+      attr_reader :source, :event, :value
+
+      def initialize(source, event, value)
+        @source = source
+        @event = event
+        @value = value
+      end
+
+      def self.from_noam(noam)
+        _, source, event, value = JSON.parse(noam)
+        Heard.new(source, event, value)
+      end
+    end
+  end
+end

data/lib/noam_lemma/message/marco.rb

@@ -0,0 +1,57 @@
+require 'socket'
+require 'json'
+
+module Noam
+  module Message
+    class Marco
+      attr_reader :port
+
+      def initialize(room_name, lemma_name)
+        @room_name = room_name
+        @lemma_name = lemma_name
+      end
+
+      def start
+        bcast_socket = UDPSocket.new
+        reply_socket = UDPSocket.new
+        reply_socket.bind("0.0.0.0", 0)
+
+        begin
+          bcast_socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_BROADCAST, true)
+
+          loop do
+            bcast_socket.send(noam_encode, 0, "255.255.255.255", Noam::BEACON_PORT)
+            if message_received?(bcast_socket)
+              break
+            end
+          end
+
+          get_polo_response(bcast_socket)
+        ensure
+          reply_socket.close
+        end
+      end
+
+      def noam_encode
+        ["marco", @lemma_name, @room_name, Noam::DEVICE_TYPE, Noam::VERSION].to_json
+      end
+
+      private
+
+      MAX_RESPONSE_LENGTH = 1600
+      WAIT_TIME = 5.0
+
+      def message_received?(socket)
+        IO.select([socket], [], [], WAIT_TIME)
+      end
+
+      def get_polo_response(socket)
+        message, sockaddr = socket.recvfrom(MAX_RESPONSE_LENGTH)
+        _, _, noam_port = JSON.parse(message)
+        _, _, addr, _ = sockaddr
+
+        Polo.new(addr, noam_port)
+      end
+    end
+  end
+end

data/lib/noam_lemma/message/playable.rb

@@ -0,0 +1,16 @@
+module Noam
+  module Message
+    class Playable
+      def initialize(host_id, event, value)
+        @host_id = host_id
+        @event = event
+        @value = value
+      end
+
+      def noam_encode
+        j = ['event', @host_id, @event, @value].to_json
+        Noam::Message.encode_length(j.length) + j
+      end
+    end
+  end
+end

data/lib/noam_lemma/message/polo.rb

@@ -0,0 +1,15 @@
+module Noam
+  module Message
+    class Polo
+      attr_reader :host, :port
+
+      class InvalidHost < Exception; end
+      class InvalidPort < Exception; end
+
+      def initialize(host, port)
+        raise InvalidHost.new if (@host = host).nil?
+        raise InvalidPort.new if (@port = port).nil?
+      end
+    end
+  end
+end

data/lib/noam_lemma/message/register.rb

@@ -0,0 +1,17 @@
+module Noam
+  module Message
+    class Register
+      def initialize(device_id, port, hears, speaks)
+        @device_id = device_id
+        @port = port
+        @hears = hears
+        @speaks = speaks
+      end
+
+      def noam_encode
+        j = ["register", @device_id, @port.to_i, @hears, @speaks, Noam::DEVICE_TYPE, Noam::VERSION].to_json
+        Noam::Message.encode_length(j.length) + j
+      end
+    end
+  end
+end

data/lib/noam_lemma/message.rb

@@ -0,0 +1,15 @@
+module Noam
+  module Message
+    MESSAGE_LENGTH_STRING_SIZE = 6
+
+    def self.encode_length(l)
+      ("%06u" % l)
+    end
+  end
+end
+
+require 'noam_lemma/message/heard'
+require 'noam_lemma/message/marco'
+require 'noam_lemma/message/playable'
+require 'noam_lemma/message/polo'
+require 'noam_lemma/message/register'

data/lib/noam_lemma/message_filter.rb

@@ -0,0 +1,24 @@
+module Noam
+  class MessageFilter
+    def initialize
+      @hears = {}
+    end
+
+    def hear(event_name, &block)
+      @hears[event_name] ||= []
+      @hears[event_name] << block
+    end
+
+    def receive(message)
+      blocks = @hears[message.event] || []
+      blocks.each do |block|
+        block.call(message)
+      end
+      message
+    end
+
+    def hears
+      @hears.keys.uniq
+    end
+  end
+end