arborist 0.0.1.pre20160106113421

data/lib/arborist/manager/event_publisher.rb

@@ -0,0 +1,97 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'msgpack'
+require 'loggability'
+require 'rbczmq'
+require 'arborist/manager' unless defined?( Arborist::Manager )
+
+
+class Arborist::Manager::EventPublisher < ZMQ::Handler
+	extend Loggability,
+	       Arborist::MethodUtilities
+
+	# Loggability API -- log to arborist's logger
+	log_to :arborist
+
+
+	### Create a new EventPublish that will publish events emitted by
+	### emitters on the specified +manager+ on the given +pollable+.
+	def initialize( pollitem, manager, reactor )
+		self.log.debug "Setting up a %p for %p (socket %p)" %
+			[ self.class, pollitem, pollitem.pollable ]
+		@pollable    = pollitem.pollable
+		@pollitem    = pollitem
+		@manager     = manager
+		@reactor     = reactor
+		@registered  = true
+		@event_queue = []
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# True if the publisher is currently registered with the reactor (i.e., waiting
+	# to write published events).
+	attr_predicate :registered
+
+
+	### Publish the specified +event+.
+	def publish( identifier, event )
+		@event_queue << [ identifier, MessagePack.pack(event.to_hash) ]
+		self.register
+		return self
+	end
+
+
+	### ZMQ::Handler API -- write events to the socket as it becomes writable.
+	def on_writable
+		unless @event_queue.empty?
+			tuple = @event_queue.shift
+			identifier, payload = *tuple
+
+			pollsocket = self.pollitem.pollable
+			pollsocket.sendm( identifier )
+			pollsocket.send( payload )
+		end
+		self.unregister if @event_queue.empty?
+		return true
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Register the publisher with the reactor if it's not already.
+	def register
+		count ||= 0
+		@reactor.register( self.pollitem ) unless @registered
+		@registered = true
+	rescue => err
+		# :TODO:
+		# This is to work around a weird error that happens sometimes when registering:
+		#   Sys error location: loop.c:424
+		# which then raises a RuntimeError with "Socket operation on non-socket". This is
+		# probably due to a race somewhere, but we can't find it. So this works (at least
+		# for the specs) in the meantime.
+		raise unless err.message.include?( "Socket operation on non-socket" )
+		count += 1
+		raise "Gave up trying to register %p with the reactor" % [ self.pollitem ] if count > 5
+		warn "Retrying registration!"
+		retry
+	end
+
+
+	### Unregister the publisher from the reactor if it's registered.
+	def unregister
+		@reactor.remove( self.pollitem ) if @registered
+		@registered = false
+	end
+
+
+end # class Arborist::Manager::EventPublisher
+

data/lib/arborist/manager/tree_api.rb

@@ -0,0 +1,207 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'msgpack'
+require 'loggability'
+require 'rbczmq'
+require 'arborist/manager' unless defined?( Arborist::Manager )
+
+
+class Arborist::Manager::TreeAPI < ZMQ::Handler
+	extend Loggability
+
+
+	# Loggability API -- log to the arborist logger
+	log_to :arborist
+
+
+	### Create the TreeAPI handler that will read requests from the specified +pollable+
+	### and call into the +manager+ to respond to them.
+	def initialize( pollable, manager )
+		self.log.debug "Setting up a %p" % [ self.class ]
+		@pollitem = pollable
+		@manager  = manager
+	end
+
+
+	### ZMQ::Handler API -- Read and handle an incoming request.
+	def on_readable
+		request = self.recv
+		response = self.handle_request( request )
+		self.send( response )
+	end
+
+
+	### Handle the specified +raw_request+ and return a response.
+	def handle_request( raw_request )
+		self.log.debug "Handling request: %p" % [ raw_request ]
+
+		header, body = self.parse_request( raw_request )
+		return self.dispatch_request( header, body )
+
+	rescue => err
+		self.log.error "%p: %s" % [ err.class, err.message ]
+		err.backtrace.each {|frame| self.log.debug "  #{frame}" }
+
+		errtype = err.is_a?( Arborist::RequestError ) ? 'client' : 'server'
+		return self.error_response( errtype, err.message )
+	end
+
+
+	### Attempt to dispatch a request given its +header+ and +body+, and return the
+	### serialized response.
+	def dispatch_request( header, body )
+		self.log.debug "Dispatching request %p -> %p" % [ header, body ]
+		handler = self.lookup_request_action( header ) or
+			raise Arborist::RequestError, "No such action '%s'" % [ header['action'] ]
+
+		response = handler.call( header, body )
+
+		self.log.debug "Returning response: %p" % [ response ]
+		return response
+	end
+
+
+	### Given a request +header+, return a #call-able object that can handle the response.
+	def lookup_request_action( header )
+		raise Arborist::RequestError, "unsupported version %d" % [ header['version'] ] unless
+			header['version'] == 1
+
+		handler_name = "handle_%s_request" % [ header['action'] ]
+		return nil unless self.respond_to?( handler_name )
+
+		return self.method( handler_name )
+	end
+
+
+	### Build an error response message for the specified +category+ and +reason+.
+	def error_response( category, reason )
+		msg = [
+			{ category: category, reason: reason, success: false, version: 1 }
+		]
+		self.log.debug "Returning error response: %p" % [ msg ]
+		return MessagePack.pack( msg )
+	end
+
+
+	### Build a successful response with the specified +body+.
+	def successful_response( body )
+		msg = [
+			{ success: true, version: 1 },
+			body
+		]
+		self.log.debug "Returning successful response: %p" % [ msg ]
+		return MessagePack.pack( msg )
+	end
+
+
+	### Validate and return a parsed msgpack +raw_request+.
+	def parse_request( raw_request )
+		tuple = begin
+			MessagePack.unpack( raw_request )
+		rescue => err
+			raise Arborist::RequestError, err.message
+		end
+
+		self.log.debug "Parsed request: %p" % [ tuple ]
+
+		raise Arborist::RequestError, 'not a tuple' unless tuple.is_a?( Array )
+		raise Arborist::RequestError, 'incorrect length' if tuple.length.zero? || tuple.length > 2
+
+		header, body = *tuple
+		raise Arborist::RequestError, "header is not a Map" unless
+			header.is_a?( Hash )
+		raise Arborist::RequestError, "missing required header 'version'" unless
+			header.key?( 'version' )
+		raise Arborist::RequestError, "missing required header 'action'" unless
+			header.key?( 'action' )
+
+		raise Arborist::RequestError, "body must be a Map or Nil" unless
+			body.is_a?( Hash ) || body.nil?
+
+		return header, body
+	end
+
+
+	### Return a response to the `status` action.
+	def handle_status_request( header, body )
+		self.log.info "STATUS: %p" % [ header ]
+		return successful_response(
+			server_version: Arborist::VERSION,
+			state: @manager.running? ? 'running' : 'not running',
+			uptime: @manager.uptime,
+			nodecount: @manager.nodecount
+		)
+	end
+
+
+	### Return a response to the `subscribe` action.
+	def handle_subscribe_request( header, body )
+		self.log.info "SUBSCRIBE: %p" % [ header ]
+		event_type      = header[ 'event_type' ]
+		node_identifier = header[ 'identifier' ]
+		subscription    = @manager.create_subscription( node_identifier, event_type, body )
+
+		return successful_response([ subscription.id ])
+	end
+
+
+	### Return a response to the `unsubscribe` action.
+	def handle_unsubscribe_request( header, body )
+		self.log.info "UNSUBSCRIBE: %p" % [ header ]
+		subscription_id = header[ 'subscription_id' ] or
+			return error_response( 'client', 'No identifier specified for UNSUBSCRIBE.' )
+		subscription = @manager.remove_subscription( subscription_id ) or
+			return successful_response( nil )
+
+		return successful_response(
+			event_type: subscription.event_type,
+			criteria: subscription.criteria
+		)
+	end
+
+
+	### Return a repsonse to the `list` action.
+	def handle_list_request( header, body )
+		self.log.info "LIST: %p" % [ header ]
+		from = header['from'] || '_'
+
+		start_node = @manager.nodes[ from ]
+		self.log.debug "  Listing nodes under %p" % [ start_node ]
+		iter = @manager.enumerator_for( start_node )
+		data = iter.map( &:to_hash )
+		self.log.debug "  got data for %d nodes" % [ data.length ]
+
+		return successful_response( data )
+	end
+
+
+	### Return a response to the 'fetch' action.
+	def handle_fetch_request( header, body )
+		self.log.info "FETCH: %p" % [ header ]
+
+		include_down = header['include_down']
+		values = if header.key?( 'return' )
+				header['return'] || []
+			else
+				nil
+			end
+		states = @manager.fetch_matching_node_states( body, values, include_down )
+
+		return successful_response( states )
+	end
+
+
+	### Update nodes using the data from the update request's +body+.
+	def handle_update_request( header, body )
+		self.log.info "UPDATE: %p" % [ header ]
+
+		body.each do |identifier, properties|
+			@manager.update_node( identifier, properties )
+		end
+
+		return successful_response( nil )
+	end
+
+end # class Arborist::Manager::TreeAPI
+

data/lib/arborist/mixins.rb

@@ -0,0 +1,363 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+# A collection of generically-useful mixins
+module Arborist
+
+	# A collection of methods for declaring other methods.
+	#
+	#   class MyClass
+	#       extend Arborist::MethodUtilities
+	#
+	#       singleton_attr_accessor :types
+	#       singleton_method_alias :kinds, :types
+	#   end
+	#
+	#   MyClass.types = [ :pheno, :proto, :stereo ]
+	#   MyClass.kinds # => [:pheno, :proto, :stereo]
+	#
+	module MethodUtilities
+
+		### Creates instance variables and corresponding methods that return their
+		### values for each of the specified +symbols+ in the singleton of the
+		### declaring object (e.g., class instance variables and methods if declared
+		### in a Class).
+		def singleton_attr_reader( *symbols )
+			singleton_class.instance_exec( symbols ) do |attrs|
+				attr_reader( *attrs )
+			end
+		end
+
+		### Create instance variables and corresponding methods that return
+		### true or false values for each of the specified +symbols+ in the singleton
+		### of the declaring object.
+		def singleton_predicate_reader( *symbols )
+			singleton_class.extend( Arborist::MethodUtilities )
+			singleton_class.attr_predicate( *symbols )
+		end
+
+		### Creates methods that allow assignment to the attributes of the singleton
+		### of the declaring object that correspond to the specified +symbols+.
+		def singleton_attr_writer( *symbols )
+			singleton_class.instance_exec( symbols ) do |attrs|
+				attr_writer( *attrs )
+			end
+		end
+
+		### Creates readers and writers that allow assignment to the attributes of
+		### the singleton of the declaring object that correspond to the specified
+		### +symbols+.
+		def singleton_attr_accessor( *symbols )
+			symbols.each do |sym|
+				singleton_class.__send__( :attr_accessor, sym )
+			end
+		end
+
+		### Create predicate methods and writers that allow assignment to the attributes
+		### of the singleton of the declaring object that correspond to the specified
+		### +symbols+.
+		def singleton_predicate_accessor( *symbols )
+			singleton_class.extend( Arborist::MethodUtilities )
+			singleton_class.attr_predicate_accessor( *symbols )
+		end
+
+		### Creates an alias for the +original+ method named +newname+.
+		def singleton_method_alias( newname, original )
+			singleton_class.__send__( :alias_method, newname, original )
+		end
+
+
+		### Create a reader in the form of a predicate for the given +attrname+.
+		def attr_predicate( attrname )
+			attrname = attrname.to_s.chomp( '?' )
+			define_method( "#{attrname}?" ) do
+				instance_variable_get( "@#{attrname}" ) ? true : false
+			end
+		end
+
+
+		### Create a reader in the form of a predicate for the given +attrname+
+		### as well as a regular writer method.
+		def attr_predicate_accessor( attrname )
+			attrname = attrname.to_s.chomp( '?' )
+			attr_writer( attrname )
+			attr_predicate( attrname )
+		end
+
+	end # module MethodUtilities
+
+
+	# Functions for time calculations
+	module TimeFunctions
+
+		###############
+		module_function
+		###############
+
+		### Calculate the (approximate) number of seconds that are in +count+ of the
+		### given +unit+ of time.
+		###
+		def calculate_seconds( count, unit )
+			return case unit
+			when :seconds, :second
+				count
+			when :minutes, :minute
+				count * 60
+			when :hours, :hour
+				count * 3600
+			when :days, :day
+				count * 86400
+			when :weeks, :week
+				count * 604800
+			when :fortnights, :fortnight
+				count * 1209600
+			when :months, :month
+				count * 2592000
+			when :years, :year
+				count * 31557600
+			else
+				raise ArgumentError, "don't know how to calculate seconds in a %p" % [ unit ]
+			end
+		end
+	end # module TimeFunctions
+
+
+	# Refinements to Numeric and Time to add convenience methods
+	module TimeRefinements
+		refine Numeric do
+
+			### Number of seconds (returns receiver unmodified)
+			def seconds
+				return self
+			end
+			alias_method :second, :seconds
+
+			### Returns number of seconds in <receiver> minutes
+			def minutes
+				return TimeFunctions.calculate_seconds( self, :minutes )
+			end
+			alias_method :minute, :minutes
+
+			### Returns the number of seconds in <receiver> hours
+			def hours
+				return TimeFunctions.calculate_seconds( self, :hours )
+			end
+			alias_method :hour, :hours
+
+			### Returns the number of seconds in <receiver> days
+			def days
+				return TimeFunctions.calculate_seconds( self, :day )
+			end
+			alias_method :day, :days
+
+			### Return the number of seconds in <receiver> weeks
+			def weeks
+				return TimeFunctions.calculate_seconds( self, :weeks )
+			end
+			alias_method :week, :weeks
+
+			### Returns the number of seconds in <receiver> fortnights
+			def fortnights
+				return TimeFunctions.calculate_seconds( self, :fortnights )
+			end
+			alias_method :fortnight, :fortnights
+
+			### Returns the number of seconds in <receiver> months (approximate)
+			def months
+				return TimeFunctions.calculate_seconds( self, :months )
+			end
+			alias_method :month, :months
+
+			### Returns the number of seconds in <receiver> years (approximate)
+			def years
+				return TimeFunctions.calculate_seconds( self, :years )
+			end
+			alias_method :year, :years
+
+
+			### Returns the Time <receiver> number of seconds before the
+			### specified +time+. E.g., 2.hours.before( header.expiration )
+			def before( time )
+				return time - self
+			end
+
+
+			### Returns the Time <receiver> number of seconds ago. (e.g.,
+			### expiration > 2.hours.ago )
+			def ago
+				return self.before( ::Time.now )
+			end
+
+
+			### Returns the Time <receiver> number of seconds after the given +time+.
+			### E.g., 10.minutes.after( header.expiration )
+			def after( time )
+				return time + self
+			end
+
+
+			### Return a new Time <receiver> number of seconds from now.
+			def from_now
+				return self.after( ::Time.now )
+			end
+
+		end # refine Numeric
+
+
+		refine Time do
+
+			# Approximate Time Constants (in seconds)
+			MINUTES = 60
+			HOURS   = 60  * MINUTES
+			DAYS    = 24  * HOURS
+			WEEKS   = 7   * DAYS
+			MONTHS  = 30  * DAYS
+			YEARS   = 365.25 * DAYS
+
+
+			### Returns +true+ if the receiver is a Time in the future.
+			def future?
+				return self > Time.now
+			end
+
+
+			### Returns +true+ if the receiver is a Time in the past.
+			def past?
+				return self < Time.now
+			end
+
+
+			### Return a description of the receiving Time object in relation to the current
+			### time.
+			###
+			### Example:
+			###
+			###    "Saved %s ago." % object.updated_at.as_delta
+			def as_delta
+				now = Time.now
+				if now > self
+					seconds = now - self
+					return "%s ago" % [ timeperiod(seconds) ]
+				else
+					seconds = self - now
+					return "%s from now" % [ timeperiod(seconds) ]
+				end
+			end
+
+
+			### Return a description of +seconds+ as the nearest whole unit of time.
+			def timeperiod( seconds )
+				return case
+					when seconds < MINUTES - 5
+						'less than a minute'
+					when seconds < 50 * MINUTES
+						if seconds <= 89
+							"a minute"
+						else
+							"%d minutes" % [ (seconds.to_f / MINUTES).ceil ]
+						end
+					when seconds < 90 * MINUTES
+						'about an hour'
+					when seconds < 18 * HOURS
+						"%d hours" % [ (seconds.to_f / HOURS).ceil ]
+					when seconds < 30 * HOURS
+						'about a day'
+					when seconds < WEEKS
+						"%d days" % [ (seconds.to_f / DAYS).ceil ]
+					when seconds < 2 * WEEKS
+						'about a week'
+					when seconds < 3 * MONTHS
+						"%d weeks" % [ (seconds.to_f / WEEKS).round ]
+					when seconds < 18 * MONTHS
+						"%d months" % [ (seconds.to_f / MONTHS).ceil ]
+					else
+						"%d years" % [ (seconds.to_f / YEARS).ceil ]
+					end
+			end
+
+		end # refine Time
+
+	end # module TimeRefinements
+
+
+	### A collection of utilities for working with Hashes.
+	module HashUtilities
+
+		###############
+		module_function
+		###############
+
+		### Return a version of the given +hash+ with its keys transformed
+		### into Strings from whatever they were before.
+		def stringify_keys( hash )
+			newhash = {}
+
+			hash.each do |key,val|
+				if val.is_a?( Hash )
+					newhash[ key.to_s ] = stringify_keys( val )
+				else
+					newhash[ key.to_s ] = val
+				end
+			end
+
+			return newhash
+		end
+
+
+		### Return a duplicate of the given +hash+ with its identifier-like keys
+		### transformed into symbols from whatever they were before.
+		def symbolify_keys( hash )
+			newhash = {}
+
+			hash.each do |key,val|
+				keysym = key.to_s.dup.untaint.to_sym
+
+				if val.is_a?( Hash )
+					newhash[ keysym ] = symbolify_keys( val )
+				else
+					newhash[ keysym ] = val
+				end
+			end
+
+			return newhash
+		end
+		alias_method :internify_keys, :symbolify_keys
+
+
+		# Recursive hash-merge function
+		def merge_recursively( key, oldval, newval )
+			case oldval
+			when Hash
+				case newval
+				when Hash
+					oldval.merge( newval, &method(:merge_recursively) )
+				else
+					newval
+				end
+
+			when Array
+				case newval
+				when Array
+					oldval | newval
+				else
+					newval
+				end
+
+			else
+				newval
+			end
+		end
+
+
+		# Recursively remove hash pairs in place whose value is nil.
+		def compact_hash( hash )
+			hash.each_key do |k|
+				hash.delete( k ) if hash[ k ].nil?
+				compact_hash( hash[k] ) if hash[k].is_a?( Hash )
+			end
+		end
+
+
+	end # HashUtilities
+
+end # module Arborist