xap_ruby 0.1.0

data/lib/xap/xap_dev.rb

@@ -0,0 +1,76 @@
+# Base class for object model of an xAP device.
+# (C)2012 Mike Bourgeous
+
+module Xap
+	# Classes that want to receive filtered xAP events from the main event loop
+	# should inherit from this class and override receive_message.
+	class XapDevice
+		attr_accessor :address, :uid, :interval
+
+		# Initializes this superclass with the given address and base UID,
+		# which will be used as the source address and UID of messages
+		# generated by this device, and the given heartbeat interval.
+		#
+		# address - a non-wildcarded XapAddress that doesn't contain ':'.
+		# uid - eight hexadecimal digits, the first two of which must be FF,
+		# the last two 00, and the middle two neither FF nor 00.
+		# interval - the number of seconds between xAP heartbeats sent by this
+		# device model when added to an XapHandler event loop.
+		def initialize address, uid, interval
+			raise 'Heartbeat interval must be a Fixnum or nil' if interval && !interval.is_a?(Fixnum)
+			set_address address
+			self.uid = uid
+			@interval = interval
+		end
+
+		# Sets the XapHandler that manages messages to and from this device.
+		# This should typically be called by XapHandler itself.  Subclasses may
+		# override this method in order to send messages that are supposed to
+		# be sent on initialization, so long as they call this base
+		# implementation first.  XapHandler will call this method with nil if
+		# the device is removed from the handler or the xAP socket is closed.
+		def handler= handler
+			raise 'handler must be a XapHandler' unless handler.nil? || handler.is_a?(XapHandler)
+			@handler = handler
+		end
+
+		# Called whenever a matching message is received by the associated
+		# handler.
+		def receive_message msg
+			puts "XXX: You forgot to override receive_message in #{self}: #{msg.inspect.lines.to_a.join("\t")}"
+		end
+
+		# Returns a string description of this device.
+		def to_s
+			"<#{self.class.name}: #{@address} #{@uid}>"
+		end
+
+		protected
+		# Uses the associated XapHandler to send the given message.  Does
+		# nothing if there is no handler set.
+		def send_message message
+			@handler.send_message message if @handler
+		end
+
+		# TODO: Ability to request incoming messages matching a particular
+		# source address, using add_receiver/remove_receiver
+
+		# Changes the address used by this device.  Subclasses should call this
+		# if, for example, the user-assigned name of the device is changed.
+		def set_address address
+			if !address.is_a?(XapAddress) || address.wildcard? || address.endpoint
+				raise 'address must be a non-wildcarded XapAddress without ":"'
+			end
+			@address = address
+		end
+
+		# Changes the UID used by this device.  Subclasses should call this if
+		# the four-digit reassignable component of the UID is changed.
+		def uid= uid
+			unless uid =~ /^FF[0-9A-Z]{4}00$/i && !(uid.slice(2, 4) =~ /(?:^(?:00|FF)|(?:00|FF)$)/i)
+				raise "uid must be eight hex digits of the form FF(01..FE)(01..FE)00, not #{uid}."
+			end
+			@uid = uid
+		end
+	end
+end

data/lib/xap/xap_handler.rb

@@ -0,0 +1,197 @@
+# EventMachine packet transmission and receipt handler for the xAP protocol.
+# (C)2012 Mike Bourgeous
+
+module Xap
+	XAP_PORT=3639
+	BCAST_ADDR='255.255.255.255'
+
+	class XapHandler < EM::Connection
+		@@instance = nil
+
+		def self.instance
+			@@instance
+		end
+
+		def initialize servername
+			@@instance = self
+			@servername = servername
+			@devices = []
+			@receivers = []
+			@timers = {}
+		end
+
+		def unbind
+			@@instance = nil if @@instance == self
+
+			@devices.each do |d|
+				d.handler = nil
+			end
+		end
+
+		def receive_data d
+			handled = false
+			begin
+				msg = XapMessage.parse(d)
+			rescue Exception => e
+				Xap.log "Error parsing incoming message: #{e}\n\t#{e.backtrace.join("\n\t")}"
+				Xap.log "receive_data(#{d.length}) invalid: #{d.inspect}"
+				return
+			end
+
+			if msg.target_addr
+				@devices.each do |d|
+					begin
+						if msg.target_addr.base =~ d.address
+							d.receive_message msg
+							handled = true
+						end
+					rescue RuntimeError => e
+						Xap.log "Error processing message with device #{d}: #{e}\n\t#{e.backtrace.join("\n\t")}"
+					end
+				end
+			end
+
+			@receivers.each do |rcv|
+				if rcv[0] =~ msg.src_addr
+					rcv[1].call msg
+				end
+			end
+
+			if !handled && $DEBUG
+				Xap.log "Received a #{msg.class.name} message (#{msg.src_addr.inspect} => #{msg.target_addr.inspect})"
+			end
+		end
+
+		# Adds a device object to the list of devices.  The device will be
+		# notified about incoming messages with a target matching the device's
+		# address.  If the device's heartbeat interval is non-nil and greater
+		# than 0 then a periodic heartbeat will automatically be transmitted
+		# for the device,
+		def add_device device
+			raise 'device must be an XapDevice' unless device.is_a? XapDevice
+			raise 'device is already in this XapHandler' if @devices.include? device
+
+			@devices << device
+			if device.interval && device.interval > 0
+				@timers[device] = EM.add_periodic_timer(device.interval) {
+					send_heartbeat device.address, device.uid, device.interval
+				}
+			end
+
+			device.handler = self
+		end
+
+		# Removes the given device from message notifications.  Cancels its
+		# heartbeat timer if it has one.
+		def remove_device device
+			@devices.delete device
+			timer = @timers.delete device
+			timer.cancel if timer
+			device.handler = nil
+		end
+
+		# Adds a callback to be called with the XapMessage when a message is
+		# received from the given source address (src_addr may be wildcarded).
+		def add_receiver src_addr, callback
+			raise 'src_addr must be an XapAddress' unless src_addr.is_a? XapAddress
+			raise 'callback must be callable' unless callback.respond_to? :call
+			@receivers << [src_addr, callback]
+			self
+		end
+
+		# Removes an address/callback pair from the list of callbacks called
+		# when a matching message is received.
+		def remove_receiver src_addr, callback
+			@receivers.delete_if { |rcv|
+				rcv[0] == src_addr && rcv[1] == callback
+			}
+			nil
+		end
+
+		# Sends an XapMessage to the network.
+		def send_message message
+			raise 'message must be an XapMessage' unless message.is_a? XapMessage
+			send_datagram(message.to_s, BCAST_ADDR, XAP_PORT)
+		end
+
+		# Broadcasts an xAP heartbeat from the given address and UID.
+		#
+		# src_addr and src_uid should be convertible to the exact strings that
+		# should go into the packet.  interval is how often other devices
+		# should expect the heartbeat, in seconds.
+		#
+		# http://www.xapautomation.org/index.php?title=Protocol_definition#Device_Monitoring_-_Heartbeats
+		#
+		# The resulting packet will look like this:
+		# xap-hbeat
+		# {
+		# v=12
+		# hop=1
+		# uid=[src_uid]
+		# class=xap-hbeat.alive
+		# source=[src_addr]
+		# interval=[interval]
+		# }
+		def send_heartbeat src_addr, src_uid, interval = 60
+			msg = "xap-hbeat\n" +
+				"{\n" +
+				"v=12\n" +
+				"hop=1\n" +
+				"uid=#{src_uid}\n" +
+			"class=xap-hbeat.alive\n" +
+				"source=#{src_addr}\n" +
+			"interval=#{interval}\n" +
+			"}\n"
+
+			send_datagram(msg, BCAST_ADDR, XAP_PORT)
+		end
+	end
+
+        @@connection = nil
+
+        # Opens a UDP socket for sending and receiving xAP messages.  The
+        # EventMachine event loop must be running.
+        def self.start_xap
+          # EventMachine doesn't seem to support using '::' for IP address
+          @@connection ||= EM.open_datagram_socket '0.0.0.0', XAP_PORT, XapHandler, "xAP Server" unless @@connection
+          @@connection
+
+          # TODO: xAP hub support
+        end
+
+        # Closes the xAP server UDP socket, if one exists.
+        def self.stop_xap
+          @@connection.close_connection_after_writing if @@connection
+          @@connection = nil
+        end
+
+        # Returns true if the xAP handler is connected to its UDP socket, false
+        # otherwise.
+        def self.xap_running?
+          !!XapHandler.instance
+        end
+
+        # Adds the given XapDevice to the current xAP socket server.
+        def self.add_device device
+          raise 'The xAP server is not running.  Call start_xap first.' unless @@connection
+          XapHandler.instance.add_device device
+        end
+
+        # Removes the given XapDevice from the current xAP socket server.
+        def self.remove_device device
+          raise 'The xAP server is not running.  Call start_xap first.' unless @@connection
+          XapHandler.instance.remove_device device
+        end
+
+        # Adds a message receiver to the current xAP socket server.
+        def self.add_receiver src_addr, callback
+          raise 'The xAP server is not running.  Call start_xap first.' unless @@connection
+          XapHandler.instance.add_receiver src_addr, callback
+        end
+
+        # Removes a message receiver from the current xAP socket server.
+        def self.remove_receiver src_addr, callback
+          raise 'The xAP server is not running.  Call start_xap first.' unless @@connection
+          XapHandler.instance.remove_receiver src_addr, callback
+        end
+end

data/lib/xap/xap_msg.rb

@@ -0,0 +1,194 @@
+# xAP message base class definitions
+# (C)2012 Mike Bourgeous
+
+module Xap
+	# Base class for all xAP message types.  Registered subclasses must implement
+	# a parse method that accepts the message hash as its first parameter.
+	class XapMessage
+		@@msgtypes = {}
+
+		attr_accessor :src_addr, :target_addr, :version, :hop, :uid, :msgclass, :headername
+
+		# Parses the given data as an xAP message.  If the message type does
+		# not have a registered handler, an exception will be raised
+		def self.parse data
+			raise 'data must be (convertible to) a String' unless data.respond_to? :to_s
+
+			msghash = Xap::Parser::ParseXap.simple_parse data.to_s
+
+			headername = msghash.keys[0].downcase
+			raise "No handlers defined for #{headername} message headers." unless @@msgtypes[headername]
+
+			classname = msghash[headername]['class']
+			raise 'Message lacks a class field in its header.' unless classname || @@msgtypes[headername][nil]
+			classname.downcase!
+
+			handler = @@msgtypes[headername][classname] || @@msgtypes[headername][nil]
+			raise "No handler defined for #{headername}/#{classname} messages." unless handler
+
+			handler.parse msghash
+		end
+
+		# Registers the given klass as the handler for msgclass messages, with
+		# the header block called headername ('xap-header' by default).
+		#
+		# Specify nil for msgclass to register a fallback handler for messages
+		# with the given header name that don't have a specific class handler
+		# registered.
+		def self.register_class klass, msgclass, headername='xap-header'
+			unless klass.is_a?(Class) && klass < XapMessage
+				raise "klass must be a Class that inherits XapMessage, not #{klass.inspect}"
+			end
+			raise 'msgclass must be nil or a String' unless msgclass.nil? || msgclass.is_a?(String)
+
+			Xap.log "Registered support for #{headername}/#{msgclass} messages via #{klass.name}"
+
+			# TODO: Support regex for msgclass?
+			headername.downcase!
+			msgclass.downcase! if msgclass.is_a? String
+			@@msgtypes[headername] = @@msgtypes[headername] || {}
+			@@msgtypes[headername][msgclass] = klass
+		end
+
+		# msgclass - the message's class
+		# src_addr - the message's source address
+		# src_uid - the message's source UID (TODO: merge with XapAddress?)
+		# target_addr - the message's target address, or nil for no target
+		def initialize msgclass, src_addr, src_uid, target_addr = nil
+			raise 'Do not instantiate XapMessage directly (use a subclass)' if self.class == XapMessage
+			raise 'src_addr must be an XapAddress' unless src_addr.is_a? XapAddress
+			raise 'target_addr must be nil or an XapAddress' unless target_addr.nil? || target_addr.is_a?(XapAddress)
+
+			@src_addr = src_addr
+			@target_addr = target_addr
+			@version = 12
+			@hop = 1
+			@uid = src_uid
+			@msgclass = msgclass
+			@blocks = {}
+			@headers = {}
+		end
+
+		# Returns a string representation of the message suitable for
+		# transmission on the network.
+		def to_s
+			s = "#{headername}\n" +
+				"{\n" +
+				"v=#{@version}\n" +
+			"hop=#{@hop}\n" +
+			"uid=#{@uid}\n" +
+			"class=#{@msgclass}\n" +
+			"source=#{@src_addr}\n"
+
+			s << "target=#{@target_addr}\n" if @target_addr
+
+			if @headers
+				@headers.each do |k, v|
+					s << "#{k}=#{v}\n"
+				end
+			end
+
+			s << "}\n"
+
+			if @blocks
+				@blocks.each do |name, block|
+					s << "#{name}\n{\n"
+					block.each do |k, v|
+						s << "#{k}=#{v}\n"
+					end
+					s << "}\n"
+				end
+			end
+
+			s
+		end
+
+		# Returns the last two digits of the UID
+		def uid_endpoint
+			@uid[-2, 2]
+		end
+
+		# Parses standard xAP header information from the given header hash,
+		# such as protocol version, hop count, unique ID, message class,
+		# message source, and message target.
+		#
+		# Example usage: parse_header(message_hash['xap-header'])
+		protected
+		def parse_header header
+			# TODO: Mixed-case header field names?
+			@src_addr = XapAddress.parse header['source']
+			@target_addr = XapAddress.parse header['target']
+			@version = header['v']
+			@hop = header['hop']
+			@uid = header['uid'] # TODO: Parse/validate UID/add UID class/merge with Address?
+			@msgclass = header['class']
+		end
+
+		# Adds a custom field to the message header.
+		def add_header key, value
+			@headers ||= {}
+			@headers[key] = value
+		end
+
+		# Adds the given hash as a block under the given name (TODO: hexadecimal fields)
+		# FIXME: multiple blocks can have the same name in xAP according to
+		# http://www.xapautomation.org/index.php?title=Protocol_definition#Message_Grammar
+		# so the blocks hash and to_hash in the parser need to be replaced with
+		# arrays.
+		def add_block name, hash
+			@blocks ||= {}
+			@blocks[name] = hash
+		end
+
+		# Sets the block list to the given hash
+		def set_blocks hash
+			@blocks = hash
+		end
+	end
+
+	# A fallback class (or inheritable utility class) for messages not supported by
+	# a loaded schema.
+	class XapUnsupportedMessage < XapMessage
+		XapMessage.register_class self, nil
+
+		def self.parse hash
+			self.new hash, nil, nil
+		end
+
+		def initialize msgclass, src_addr, src_uid, target_addr = nil
+			@headername ||= 'xap-header'
+			if msgclass.is_a?(Hash)
+				parse_header msgclass[@headername]
+
+				blocks = msgclass.clone
+				blocks.delete @headername
+				set_blocks blocks
+			else
+				super msgclass, src_addr, src_uid, target_addr
+			end
+		end
+	end
+
+	# An xAP heartbeat message.
+	class XapHeartbeat < XapMessage
+		XapMessage.register_class self, 'xap-hbeat.alive', 'xap-hbeat'
+
+		attr_accessor :interval
+
+		def self.parse hash
+			self.new hash, nil
+		end
+
+		def initialize src_addr, src_uid, interval = 60
+			@headername = 'xap-hbeat'
+			if src_addr.is_a?(Hash)
+				parse_header src_addr[@headername]
+				interval = src_addr[@headername]['interval'] || interval
+			else
+				super 'xap-hbeat.alive', src_addr, src_uid
+			end
+			add_header 'interval', interval
+			@interval = interval
+		end
+	end
+end