lwes 0.1.0

data/lib/lwes/struct.rb

@@ -0,0 +1,116 @@
+module LWES
+  class Struct
+
+    # creates a new Struct-based class, takes the following
+    # options hash:
+    #
+    #   :db       - pre-created LWES::TypeDB object
+    #               this is required unless :file is given
+    #   :file     - pathname to the ESF file,
+    #               this is required unless :db is given
+    #   :class    - Ruby base class name, if the ESF file only has one
+    #               event defined (besides MetaEventInfo), then specifying
+    #               it is optional, otherwise it is required when multiple
+    #               events are defined in the same ESF :file given above
+    #   :parent   - parent class or module, the default is 'Object' putting
+    #               the new class in the global namespace.
+    #   :name     - event name if it differs from the Ruby base class name
+    #               given (or inferred) above.  For DRY-ness, you are
+    #               recommended to keep your event names and Ruby class
+    #               names in sync and not need this option.
+    #   :skip     - Array of field names to skip from the Event defininition
+    #               entirely, these could include fields that are only
+    #               implemented by the Listener.  This may also be a
+    #               regular expression.
+    #   :defaults - hash of default key -> value pairs to set at
+    #               creation time
+    #
+    def self.new(options, &block)
+      db = options[:db]
+      db ||= begin
+        file = options[:file] or
+          raise ArgumentError, "TypeDB :db or ESF :file missing"
+        test ?r, file or
+          raise ArgumentError, "file #{file.inspect} not readable"
+        TypeDB.new(file)
+      end
+      dump = db.to_hash
+      klass = options[:class] || begin
+        # make it easier to deal with single event files
+        events = (dump.keys -  [ :MetaEventInfo ])
+        events.size > 1 and
+            raise RuntimeError,
+                  "multiple event defs available: #{events.inspect}\n" \
+                  "pick one with :class"
+        events.first
+      end
+
+      name = options[:name] || klass
+      parent = options[:parent] || Object
+      event_def = dump[name.to_sym] or
+        raise RuntimeError, "#{name.inspect} not defined in #{file}"
+
+      # merge MetaEventInfo fields in
+      meta_event_info = dump[:MetaEventInfo]
+      alpha = proc { |a,b| a.first.to_s <=> b.first.to_s }
+      event_def = event_def.sort(&alpha)
+      if meta_event_info
+        seen = event_def.map { |(field, _)| field }
+        meta_event_info.sort(&alpha).each do |field_type|
+          seen.include?(field_type.first) or event_def << field_type
+        end
+      end
+
+      Array(options[:skip]).each do |x|
+        if Regexp === x
+          event_def.delete_if { |(f,_)| x =~ f.to_s }
+        else
+          if x.to_sym == :MetaEventInfo
+            meta_event_info.nil? and
+              raise RuntimeError, "MetaEventInfo not defined in #{file}"
+            meta_event_info.each do |(field,_)|
+              event_def.delete_if { |(f,_)| field == f }
+            end
+          else
+            event_def.delete_if { |(f,_)| f == x.to_sym }
+          end
+        end
+      end
+
+      tmp = ::Struct.new(*(event_def.map { |(field,_)| field }))
+      tmp = parent.const_set(klass, tmp)
+      tmp.const_set :TYPE_DB, db
+      tmp.const_set :NAME, name.to_s
+      ed = tmp.const_set :EVENT_DEF, {}
+      event_def.each { |(field,type)| ed[field] = type }
+      type_list = event_def.map { |(field,type)| [ field, field.to_s, type ] }
+      tmp.const_set :TYPE_LIST, type_list
+
+      defaults = options[:defaults] || {}
+      defaults = tmp.const_set :DEFAULTS, defaults.dup
+      tmp.class_eval(&block) if block_given?
+
+      # define a parent-level method, eval is faster than define_method
+      eval <<EOS
+class ::#{tmp.name}
+  class << self
+    alias _new new
+    undef_method :new
+    def new(*args)
+      if Hash === (init = args.first)
+        rv = _new()
+        DEFAULTS.merge(init).each_pair { |k,v| rv[k] = v }
+        rv
+      else
+        rv = _new(*args)
+        DEFAULTS.each_pair { |k,v| rv[k] ||= v }
+        rv
+      end
+    end
+  end
+end
+EOS
+    tmp
+    end
+  end
+end

data/lib/lwes/type_db.rb

@@ -0,0 +1,24 @@
+module LWES
+  class TypeDB
+
+    # create LWES::Struct-derived classes based on the contents
+    # of the TypeDB object.  It is possible to place all classes
+    # into a namespace by specifying the :parent option to point
+    # to a class or module:
+    #
+    #   module MyEvents; end
+    #
+    #   type_db = LWES::TypeDB.new("my_events.esf")
+    #   type_db.create_classes!(:parent => MyEvents)
+    #
+    # Assuming you had "Event1" and "Event2" defined in your "my_events.esf"
+    # file, then the classes MyEvents::Event1 and MyEvents::Event2 should
+    # now be accessible.
+    def create_classes!(options = {})
+      (to_hash.keys - [ :MetaEventInfo ]).map do |klass|
+        LWES::Struct.new({ :db => self, :class => klass }.merge(options))
+      end
+    end
+
+  end
+end

data/lwes.gemspec

@@ -0,0 +1,43 @@
+Gem::Specification.new do |s|
+  s.name = %q{lwes}
+  s.version = "0.1.0"
+  s.date = Time.now
+  s.authors = ["Erik S. Chang", "Frank Maritato"]
+  s.email = %q{lwes-devel@lists.sourceforge.net}
+  s.summary = %q{Ruby API for the Light Weight Event System}
+  s.homepage = %q{http://www.lwes.org/}
+  s.extensions = %w(ext/lwes/extconf.rb)
+  s.description = %q{
+The LWES Light-Weight Event System is a framework for allowing the exchange of
+information from many machines to many machines in a controlled, platform
+neutral, language neutral way.  The exchange of information is done in a
+connectless fashion using multicast or unicast UDP, and using self describing
+data so that any platform or language can translate it to it's local dialect.
+}.strip
+  s.files = %w(
+COPYING
+ChangeLog
+README
+Rakefile
+examples/demo.rb
+examples/my_events.esf
+ext/lwes/emitter.c
+ext/lwes/extconf.rb
+ext/lwes/lwes.c
+ext/lwes/lwes_ruby.h
+ext/lwes/numeric.c
+ext/lwes/type_db.c
+lib/lwes.rb
+lib/lwes/emitter.rb
+lib/lwes/struct.rb
+lib/lwes/type_db.rb
+lwes.gemspec
+test/test_helper.rb
+test/unit/test1.esf
+test/unit/test2.esf
+test/unit/test_emit_struct.rb
+test/unit/test_emitter.rb
+test/unit/test_struct.rb
+test/unit/test_type_db.rb
+)
+end

data/test/test_helper.rb

@@ -0,0 +1,45 @@
+require 'pp'
+require 'tempfile'
+require 'test/unit'
+require 'lwes'
+
+unless defined?(LISTENER_DEFAULTS)
+  BEFORE_DELAY = ENV['BEFORE_DELAY'] ? ENV['BEFORE_DELAY'].to_f : 0.5
+  AFTER_DELAY = ENV['AFTER_DELAY'] ? ENV['AFTER_DELAY'].to_f : 0.5
+  LISTENER_DEFAULTS = {
+    :address => ENV["LWES_TEST_ADDRESS"] || "127.0.0.1",
+    :iface => ENV["LWES_TEST_IFACE"] || "0.0.0.0",
+    :port => ENV["LWES_TEST_PORT"] ? ENV["LWES_TEST_PORT"].to_i : 12345,
+    :ttl => 60, # nil for no ttl)
+  }
+end
+
+def lwes_listener(&block)
+  cmd = "lwes-event-printing-listener" \
+        " -m #{@options[:address]}" \
+        " -i #{@options[:iface]}" \
+        " -p #{@options[:port]}"
+  out = Tempfile.new("out")
+  err = Tempfile.new("err")
+  $stdout.flush
+  $stderr.flush
+  pid = fork do
+    $stdout.reopen(out.path)
+    $stderr.reopen(err.path)
+    exec cmd
+  end
+  begin
+    # since everything executes asynchronously and our messaging,
+    # we need to ensure our listener is ready, then ensure our
+    # listener has printed something...
+    # XXX racy
+    sleep BEFORE_DELAY
+    yield
+    sleep AFTER_DELAY
+  ensure
+    Process.kill(:TERM, pid)
+    Process.waitpid2(pid)
+    assert_equal 0, err.size
+  end
+  out
+end

data/test/unit/test1.esf

@@ -0,0 +1,33 @@
+# MetaEventInfo fields are allowed to be set in all other events, this
+# can be though of as inheritance, in other words all other events in this
+# file can have the fields defined in the MetaEventInfo
+MetaEventInfo
+{
+  ip_addr SenderIP;    # sender_ip                    REQUIRED, CALCULATED
+                       # ip address of the sender of the event
+  uint16  SenderPort;  # sender_port                  REQUIRED, CALCULATED
+                       # port of the sender of the event
+  int64   ReceiptTime; # time_received                REQUIRED, CALCULATED
+                       # time the event was received by the listener/journaller
+  uint16  SiteID;      # receiver_id                  OPTIONAL, COMMAND_ARGS
+                       # id of the listener/journaller
+  int16   enc;         # encoding_type                REQUIRED, FUNCTION_ARGS
+                       # encoding type of strings in the event
+  string  st;          # sender_type                  OPTIONAL, FUNCTION_ARGS, 10
+                       # sender type, this should be a short string which
+                       # describes the sender type.  (ie. "java", or "perl")
+}
+
+Event1
+{
+  boolean t_bool;      # test_bool                    OPTIONAL, CALCULATED
+  int16   t_int16;     # test_int16                   OPTIONAL, CALCULATED
+  uint16  t_uint16;    # test_uint16                  OPTIONAL, CALCULATED
+  int32   t_int32;     # test_int32                   OPTIONAL, CALCULATED
+  uint32  t_uint32;    # test_uint32                  OPTIONAL, CALCULATED
+  int64   t_int64;     # test_int64                   OPTIONAL, CALCULATED
+  uint64  t_uint64;    # test_uint64                  OPTIONAL, CALCULATED
+  ip_addr t_ip_addr;   # test_ip_addr                 OPTIONAL, CALCULATED
+  string  t_string;    # test_string                  OPTIONAL, CALCULATED, 50
+}
+

data/test/unit/test2.esf

@@ -0,0 +1,14 @@
+MetaEventInfo
+{
+  ip_addr SenderIP;
+}
+
+EventBool
+{
+  boolean B;
+}
+
+EventString
+{
+  string S;
+}

data/test/unit/test_emit_struct.rb

@@ -0,0 +1,101 @@
+require "#{File.dirname(__FILE__)}/../test_helper"
+
+class TestEmitStruct < Test::Unit::TestCase
+
+  def setup
+    assert_kind_of Class, self.class.const_get(:Event1)
+    # assert self.class.const_get(:Event1).kind_of?(Struct)
+    @options = LISTENER_DEFAULTS.dup
+  end
+
+  def test_emit_struct_full
+    s = nil
+    out = lwes_listener do
+      assert_nothing_raised do
+        emitter = LWES::Emitter.new(@options)
+        s = Event1.new
+        s.t_bool = true
+        s.t_int16 = -1000
+        s.t_uint16 = 1000
+        s.t_int32 = -64444
+        s.t_uint32 = 64444
+        s.t_int64 = 10_000_000_000
+        s.t_uint64 = 10_000_000_000
+        s.t_ip_addr = '192.168.0.1'
+        s.t_string = "STRING"
+        emitter.emit(s)
+      end
+    end
+    out = out.readlines
+    s.members.each do |m|
+      value = s[m.to_sym] or next
+      regex = /\b#{m} = #{value};/
+      assert_equal 1, out.grep(regex).size,
+                   "#{regex.inspect} didn't match #{out.inspect}"
+    end
+  end
+
+  def test_emit_from_class
+    opt = {
+      :t_bool => true,
+      :t_int16 => -1000,
+      :t_uint16 => 1000,
+      :t_int32 => -64444,
+      :t_uint32 => 64444,
+      :t_int64 => 10_000_000_000,
+      :t_uint64 => 10_000_000_000,
+      :t_ip_addr => '192.168.0.1',
+      :t_string => "STRING",
+    }
+    out = lwes_listener do
+      assert_nothing_raised do
+        emitter = LWES::Emitter.new(@options)
+        emitter.emit(Event1, opt)
+      end
+    end
+    out = out.readlines
+    opt.each do |m, value|
+      regex = /\b#{m} = #{value};/
+      assert_equal 1, out.grep(regex).size,
+                   "#{regex.inspect} didn't match #{out.inspect}"
+    end
+  end
+
+  def test_emit_from_class_bad_type
+    out = lwes_listener do
+      e = assert_raises(TypeError) do
+        emitter = LWES::Emitter.new(@options)
+        opt = {
+          :t_int16 => -1000,
+          :t_uint16 => 1000,
+          :t_int32 => -64444,
+          :t_uint32 => 64444,
+          :t_int64 => 10_000_000_000,
+          :t_uint64 => 10_000_000_000,
+          :t_ip_addr => '192.168.0.1',
+          :t_string => true, #"STRING",
+        }
+        emitter.emit(Event1, opt)
+      end
+    end
+    assert out.readlines.empty?
+  end
+
+  def test_emit_alt_class_name
+    out = lwes_listener do
+      emitter = LWES::Emitter.new(@options)
+      emitter.emit(Event, :t_uint32 => 16384)
+    end
+    out = out.readlines
+    assert_match %r{^Event1\[\d+\]}, out.first
+  end
+
+end
+
+ESF_FILE = "#{File.dirname(__FILE__)}/test1.esf"
+LWES::Struct.new(:file=>ESF_FILE,
+                 :parent => TestEmitStruct)
+LWES::Struct.new(:file=>ESF_FILE,
+                 :parent => TestEmitStruct,
+                 :name => "Event1",
+                 :class => "Event")

data/test/unit/test_emitter.rb

@@ -0,0 +1,169 @@
+require "#{File.dirname(__FILE__)}/../test_helper"
+require 'ipaddr'
+
+class TestEmitter < Test::Unit::TestCase
+  def test_constants
+    assert_instance_of Module, LWES, "LWES is not a module"
+    assert_instance_of Class, LWES::Emitter, "LWES::Emitter is not a class"
+  end
+
+  def setup
+    @options = LISTENER_DEFAULTS.dup
+  end
+
+  def test_initialize
+    assert_instance_of LWES::Emitter, LWES::Emitter.new(@options)
+  end
+
+  def test_initialize_with_heartbeat
+    heartbeat = @options.merge(:heartbeat => 30)
+    assert_instance_of LWES::Emitter, LWES::Emitter.new(heartbeat)
+  end
+
+  def test_initialize_no_ttl
+    no_ttl = @options.dup
+    no_ttl.delete(:ttl)
+    assert_instance_of LWES::Emitter, LWES::Emitter.new(no_ttl)
+  end
+
+  def test_initialize_invalid
+    assert_raises(TypeError) {
+      LWES::Emitter.new(@options.merge(:address => nil))
+    }
+  end
+
+  def test_initialize_empty_options
+    assert_raises(TypeError) { LWES::Emitter.new({}) }
+  end
+
+  def test_emit_invalid
+    emitter = LWES::Emitter.new(@options)
+    assert_raises(TypeError) { emitter.emit "Invalid", nil }
+    assert_raises(ArgumentError) { emitter.emit nil, { :hello => "world" }}
+  end
+
+  def test_emit_empty_hash
+    emitter = LWES::Emitter.new(@options)
+    assert_nothing_raised { emitter.emit("Valid", Hash.new) }
+  end
+
+  def test_emit_non_empty_hashes
+    emitter = LWES::Emitter.new(@options)
+    out = lwes_listener do
+      assert_nothing_raised {
+        emitter.emit("ASDF", { :foo => "FOO", :nr => [ :int16, 50 ] })
+      }
+    end
+    lines = out.readlines
+    assert_match %r{\AASDF\b}, lines.first
+    assert ! lines.grep(/foo = FOO;/).empty?
+    assert ! lines.grep(/nr = 50;/).empty?
+  end
+
+  def test_emit_ip_addr_string
+    emitter = LWES::Emitter.new(@options)
+    event = { :string_ip => [ :ip_addr, "192.168.1.1" ] }
+    out = lwes_listener do
+      assert_nothing_raised { emitter.emit("STRING_IP", event) }
+    end
+    lines = out.readlines
+    assert_equal 1, lines.grep(/string_ip = 192.168.1.1/).size
+  end
+
+  def test_emit_ip_addr_int
+    emitter = LWES::Emitter.new(@options)
+    event = { :int_ip => [ :ip_addr, IPAddr.new("192.168.1.1").to_i ] }
+    out = lwes_listener do
+      assert_nothing_raised { emitter.emit("INT_IP", event) }
+    end
+    lines = out.readlines
+    assert_equal 1, lines.grep(/int_ip = 192.168.1.1/).size
+  end
+
+  def TODO_emit_ip_addr_object
+    emitter = LWES::Emitter.new(@options)
+    event = { :ip => IPAddr.new("192.168.1.1") }
+    out = lwes_listener do
+      assert_nothing_raised { emitter.emit("IP", event) }
+    end
+    lines = out.readlines
+    assert_equal 1, lines.grep(/\bip = 192.168.1.1/).size
+  end
+
+  def test_emit_invalid
+    emitter = LWES::Emitter.new(@options)
+    assert_raises(ArgumentError) { emitter.emit("JUNK", :junk => %r{junk}) }
+  end
+
+  def test_emit_booleans
+    emitter = LWES::Emitter.new(@options)
+    event = { :true => true, :false => false }
+    out = lwes_listener do
+      assert_nothing_raised { emitter.emit("BOOLS", event)
+      }
+    end
+    lines = out.readlines
+    assert_equal 1, lines.grep(/true = true;/).size
+    assert_equal 1, lines.grep(/false = false;/).size
+  end
+
+  def test_emit_numeric_ranges
+    check_min_max(:int16, -0x7fff - 1, 0x7fff)
+    check_min_max(:int32, -0x7fffffff - 1, 0x7fffffff)
+    check_min_max(:int64, -0x7fffffffffffffff - 1, 0x7fffffffffffffff)
+    check_min_max(:uint16, 0, 0xffff)
+    check_min_max(:uint32, 0, 0xffffffff)
+    check_min_max(:uint64, 0, 0xffffffffffffffff)
+    huge = 0xffffffffffffffffffffffffffffffff
+    tiny = -0xffffffffffffffffffffffffffffffff
+    [ :int16, :int32, :int64, :uint16, :uint32, :uint64 ].each do |type|
+      emitter = LWES::Emitter.new(@options)
+      assert_raises(RangeError) {
+        emitter.emit("way over", { type => [ type, huge ] })
+      }
+      assert_raises(RangeError) {
+        emitter.emit("way under", { type => [ type, tiny ] })
+      }
+    end
+  end
+
+  def check_min_max(type, min, max)
+    emitter = LWES::Emitter.new(@options)
+    out = lwes_listener do
+      assert_raises(RangeError) {
+        emitter.emit("over", { type => [ type, max + 1] })
+      }
+      assert_raises(RangeError, "type=#{type} min=#{min}") {
+        emitter.emit("under", { type => [ type, min - 1 ] })
+      }
+      assert_nothing_raised {
+        emitter.emit("zero", { type => [ type, 0 ] })
+      }
+      assert_nothing_raised {
+        emitter.emit("min", { type => [ type, min ] })
+      }
+      assert_nothing_raised {
+        emitter.emit("max", { type => [ type, max ] })
+      }
+    end
+    lines = out.readlines
+    assert lines.grep(/\Aover/).empty?
+    assert lines.grep(/\Aunder/).empty?
+    assert_equal 1, lines.grep(/\Amax/).size
+    assert_equal 1, lines.grep(/\Amin/).size
+    assert_equal 1, lines.grep(/\Azero/).size
+  end
+
+  def test_emit_uint64
+    emitter = LWES::Emitter.new(@options)
+    assert_nothing_raised {
+      emitter.emit("Foo", { :uint64 => [ :uint64, 10_000_000_000 ] })
+    }
+  end
+
+  def test_close
+    emitter = LWES::Emitter.new(@options)
+    assert_nil emitter.close
+  end
+
+end