arborist 0.0.1.pre20160106113421

data/lib/arborist/node/host.rb

@@ -0,0 +1,87 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'etc'
+require 'ipaddr'
+
+require 'arborist/node'
+
+
+# A node type for Arborist trees that represent network-connected hosts.
+class Arborist::Node::Host < Arborist::Node
+
+	# A union of IPv4 and IPv6 regular expressions.
+	IPADDR_RE = Regexp.union(
+		IPAddr::RE_IPV4ADDRLIKE,
+		IPAddr::RE_IPV6ADDRLIKE_COMPRESSED,
+		IPAddr::RE_IPV6ADDRLIKE_FULL
+	)
+
+
+	### Create a new Host node.
+	def initialize( identifier, &block )
+		@addresses = []
+		super
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The network address(es) of this Host as an Array of IPAddr objects
+	attr_reader :addresses
+
+
+	### Return the host's operational attributes.
+	def operational_values
+		properties = super
+		return properties.merge( addresses: self.addresses.map(&:to_s) )
+	end
+
+
+	### Set an IP address of the host.
+	def address( new_address, options={} )
+		self.log.debug "Adding address %p to %p" % [ new_address, self ]
+		case new_address
+		when IPAddr
+			@addresses << new_address
+		when IPADDR_RE
+			@addresses << IPAddr.new( new_address )
+		when String
+			ip_addr = TCPSocket.gethostbyname( new_address )
+			@addresses << IPAddr.new( ip_addr[3] )
+			@addresses << IPAddr.new( ip_addr[4] ) if ip_addr[4]
+		else
+			raise "I don't know how to parse a %p host address (%p)" %
+				[ new_address.class, new_address ]
+		end
+	end
+
+
+	### Returns +true+ if the node matches the specified +key+ and +val+ criteria.
+	def match_criteria?( key, val )
+		return case key
+			when 'address'
+				search_addr = IPAddr.new( val )
+				@addresses.any? {|a| search_addr.include?(a) }
+			else
+				super
+			end
+	end
+
+
+	### Add a service to the host
+	def service( name, options={}, &block )
+		return Arborist::Node.create( :service, name, self, options, &block )
+	end
+
+
+	### Return host-node-specific information for #inspect.
+	def node_description
+		return "{no addresses}" if self.addresses.empty?
+		return "{addresses: %s}" % [ self.addresses.map(&:to_s).join(', ') ]
+	end
+
+end # class Arborist::Node::Host

data/lib/arborist/node/root.rb

@@ -0,0 +1,60 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist/node' unless defined?( Arborist::Node )
+require 'arborist/mixins'
+
+
+# The class of the root node of an Arborist tree. This class is a Singleton.
+class Arborist::Node::Root < Arborist::Node
+	extend Arborist::MethodUtilities
+
+
+	# The instance of the Root node.
+	@instance = nil
+
+	### Create the instance of the Root node (if necessary) and return it.
+	def self::new( * )
+		@instance ||= super
+		return @instance
+	end
+
+
+	### Override the default constructor to use the singleton ::instance instead.
+	def self::instance( * )
+		@instance ||= new
+		return @instance
+	end
+
+
+	### Reset the singleton instance; mainly used for testing.
+	def self::reset
+		@instance = nil
+	end
+
+
+	### Set up the root node.
+	def initialize( * )
+		super( '_' ) do
+			description "The root node."
+			source = URI( __FILE__ )
+		end
+
+		@status = 'up'
+		@status.freeze
+	end
+
+
+	### Ignore updates to the root node.
+	def update( properties )
+		self.log.warn "Update to the root node ignored."
+	end
+
+
+	### Override the reader mode of Node#parent for the root node, which never has
+	### a parent.
+	def parent( * )
+		return nil
+	end
+
+end # class Arborist::Node::Root

data/lib/arborist/node/service.rb

@@ -0,0 +1,112 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'etc'
+require 'ipaddr'
+require 'socket'
+
+require 'arborist/node'
+
+
+# A node type for Arborist trees that represent services running on hosts.
+class Arborist::Node::Service < Arborist::Node
+
+	# The default transport layer protocol to use for services that don't specify
+	# one
+	DEFAULT_PROTOCOL = 'tcp'
+
+
+	### Create a new Service node.
+	def initialize( identifier, host, options={}, &block )
+		my_identifier = "%s-%s" % [ host.identifier, identifier ]
+		super( my_identifier )
+
+		@host = host
+		@parent = host.identifier
+		@app_protocol = options[:app_protocol] || identifier
+		@protocol = options[:protocol] || DEFAULT_PROTOCOL
+
+		service_port = options[:port] || default_port_for( @app_protocol, @protocol ) or
+			raise ArgumentError, "can't determine the port for %s/%s" % [ @app_protocol, @protocol ]
+		@port = Integer( service_port )
+
+		self.instance_eval( &block ) if block
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The network port the service uses
+	attr_reader :port
+
+	##
+	# The transport layer protocol the service uses
+	attr_reader :protocol
+
+	##
+	# The (layer 7) protocol used by the service
+	attr_reader :app_protocol
+
+
+	### Delegate the service's address to its host.
+	def addresses
+		return @host.addresses
+	end
+
+
+	### Returns +true+ if the node matches the specified +key+ and +val+ criteria.
+	def match_criteria?( key, val )
+		self.log.debug "Matching %p: %p against %p" % [ key, val, self ]
+		return case key
+			when 'port'
+				val = default_port_for( val, @protocol ) unless val.is_a?( Fixnum )
+				self.port == val.to_i
+			when 'address'
+				search_addr = IPAddr.new( val )
+				self.addresses.any? {|a| search_addr.include?(a) }
+			when 'protocol' then self.protocol == val.downcase
+			when 'app', 'app_protocol' then self.app_protocol == val
+			else
+				super
+			end
+	end
+
+
+	### Return a Hash of the operational values that are included with the node's
+	### monitor state.
+	def operational_values
+		return super.merge(
+			addresses: self.addresses.map( &:to_s ),
+			port: self.port,
+			protocol: self.protocol,
+			app_protocol: self.app_protocol,
+		)
+	end
+
+
+	### Return service-node-specific information for #inspect.
+	def node_description
+		return "{listening on %s port %d}" % [
+			self.protocol,
+			self.port,
+		]
+	end
+
+
+	#######
+	private
+	#######
+
+	### Try to default the appropriate port based on the node's +identifier+
+	### and +protocol+. Raises a SocketError if the service port can't be
+	### looked up.
+	def default_port_for( identifier, protocol )
+		return Socket.getservbyname( identifier, protocol )
+	rescue SocketError
+		return nil
+	end
+
+end # class Arborist::Node::Service

data/lib/arborist/observer.rb

@@ -0,0 +1,176 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist' unless defined?( Arborist )
+
+
+# The Arborist entity responsible for observing changes to the tree and
+# reporting on them.
+class Arborist::Observer
+	extend Loggability,
+	       Arborist::MethodUtilities
+
+	# Loggability API -- write logs to the Arborist log host
+	log_to :arborist
+
+
+	autoload :Action, 'arborist/observer/action'
+	autoload :Summarize, 'arborist/observer/summarize'
+
+
+	##
+	# The key for the thread local that is used to track instances as they're
+	# loaded.
+	LOADED_INSTANCE_KEY = :loaded_observer_instances
+
+	##
+	# The glob pattern to use for searching for observers
+	OBSERVER_FILE_PATTERN = '**/*.rb'
+
+
+	Arborist.add_dsl_constructor( :Observer ) do |description, &block|
+		Arborist::Observer.new( description, &block )
+	end
+
+
+
+	### Overridden to track instances of created nodes for the DSL.
+	def self::new( * )
+		new_instance = super
+		Arborist::Observer.add_loaded_instance( new_instance )
+		return new_instance
+	end
+
+
+	### Record a new loaded instance if the Thread-local variable is set up to track
+	### them.
+	def self::add_loaded_instance( new_instance )
+		instances = Thread.current[ LOADED_INSTANCE_KEY ] or return
+		instances << new_instance
+	end
+
+
+	### Load the specified +file+ and return any new Nodes created as a result.
+	def self::load( file )
+		self.log.info "Loading observer file %s..." % [ file ]
+		Thread.current[ LOADED_INSTANCE_KEY ] = []
+		Kernel.load( file )
+		return Thread.current[ LOADED_INSTANCE_KEY ]
+	ensure
+		Thread.current[ LOADED_INSTANCE_KEY ] = nil
+	end
+
+
+	### Return an iterator for all the observer files in the specified +directory+.
+	def self::each_in( directory )
+		path = Pathname( directory )
+		paths = if path.directory?
+				Pathname.glob( directory + OBSERVER_FILE_PATTERN )
+			else
+				[ path ]
+			end
+
+		return paths.flat_map do |file|
+			file_url = "file://%s" % [ file.expand_path ]
+			observers = self.load( file )
+			self.log.debug "Loaded observers %p..." % [ observers ]
+			observers.each do |observer|
+				observer.source = file_url
+			end
+			observers
+		end
+	end
+
+
+	### Create a new Observer with the specified +description+.
+	def initialize( description, &block )
+		@description = description
+		@subscriptions = []
+		@actions = []
+
+		self.instance_exec( &block ) if block
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The observer's description
+	attr_reader :description
+
+	##
+	# The observer's actions
+	attr_reader :actions
+
+	##
+	# The source file the observer was loaded from
+	attr_accessor :source
+
+
+	#
+	# DSL Methods
+	#
+
+	### Specify a pattern for events the observer is interested in. Options:
+	### to::
+	###   the name of the event; defaults to every event type
+	### where::
+	###   a Hash of criteria to match against event data
+	### on::
+	###   the identifier of the node to subscribe on, defaults to the root node
+	##    which receives all node events.
+	def subscribe( to: nil, where: {}, on: nil )
+		@subscriptions << { criteria: where, identifier: on, event_type: to }
+	end
+
+
+	### Register an action that will be taken when a subscribed event is received.
+	def action( options={}, &block )
+		@actions << Arborist::Observer::Action.new( options, &block )
+	end
+
+
+	### Register a summary action.
+	def summarize( options={}, &block )
+		@actions << Arborist::Observer::Summarize.new( options, &block )
+	end
+
+
+	#
+	# Observe Methods
+	#
+
+	### Fetch the descriptions of which events this Observer would like to receive. If no
+	### subscriptions have been specified, a subscription that will match any event is returned.
+	def subscriptions
+
+		# Subscribe to all events if there are no subscription criteria.
+		self.subscribe if @subscriptions.empty?
+
+		return @subscriptions
+	end
+
+
+	### Handle a published event.
+	def handle_event( uuid, event )
+		self.actions.each do |action|
+			action.handle_event( event )
+		end
+	end
+
+
+	### Return an Array of timer callbacks of the form:
+	###
+	###   [ interval_seconds, callable ]
+	###
+	def timers
+		return self.actions.map do |action|
+			next nil unless action.respond_to?( :on_timer ) &&
+				action.time_threshold.nonzero?
+			[ action.time_threshold, action.method(:on_timer) ]
+		end.compact
+	end
+
+end # class Arborist::Observer

data/lib/arborist/observer/action.rb

@@ -0,0 +1,125 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'schedulability'
+require 'loggability'
+
+require 'arborist/observer' unless defined?( Arborist::Observer )
+
+
+# An action taken by an Observer.
+class Arborist::Observer::Action
+	extend Loggability
+
+
+	# Loggability API -- log to the Arborist logger
+	log_to :arborist
+
+
+	### Create a new Action that will call the specified +block+ +during+ the given schedule,
+	### but only +after+ the specified number of events have arrived +within+ the given
+	### time threshold.
+	def initialize( within: 0, after: 1, during: nil, &block )
+		raise ArgumentError, "Action requires a block" unless block
+
+		@block           = block
+		@time_threshold  = within
+		@schedule        = Schedulability::Schedule.parse( during ) if during
+
+		if within.zero?
+			@count_threshold = after
+		else
+			# It should always be 2 or more if there is a time threshold
+			@count_threshold = [ after, 2 ].max
+		end
+
+		@event_history = {}
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The object to #call when the action is triggered.
+	attr_reader :block
+
+	##
+	# The maximum number of seconds between events that cause the action to be called
+	attr_reader :time_threshold
+
+	##
+	# The minimum number of events that cause the action to be called when the #time_threshold
+	# is met.
+	attr_reader :count_threshold
+
+	##
+	# The schedule that applies to this action.
+	attr_reader	:schedule
+
+	##
+	# The Hash of recent events, keyed by their arrival time.
+	attr_reader :event_history
+
+
+	### Call the action for the specified +event+.
+	def handle_event( event )
+		self.record_event( event )
+		self.call_block( event ) if self.should_run?
+	end
+
+
+	### Execute the action block with the specified +event+.
+	###
+	def call_block( event )
+		if self.block.arity >= 2 || self.block.arity < 0
+			self.block.call( event.dup, self.event_history.dup )
+		else
+			self.block.call( event.dup )
+		end
+	ensure
+		self.event_history.clear
+	end
+
+
+	### Record the specified +event+ in the event history if within the scheduled period(s).
+	def record_event( event )
+		return if self.schedule && !self.schedule.now?
+		self.event_history[ Time.now ] = event
+		self.event_history.keys.sort.each do |event_time|
+			break if self.event_history.size <= self.count_threshold
+			self.event_history.delete( event_time )
+		end
+	end
+
+
+	### Returns +true+ if the threshold is exceeded and the current time is within the
+	### action's schedule.
+	def should_run?
+		return self.time_threshold_exceeded? && self.count_threshold_exceeded?
+	end
+
+
+	### Returns +true+ if the time between the first and last event in the #event_history is
+	### less than the #time_threshold.
+	def time_threshold_exceeded?
+		return true if self.time_threshold.zero?
+		return false unless self.count_threshold_exceeded?
+
+		first = self.event_history.keys.min
+		last = self.event_history.keys.max
+
+		self.log.debug "Time between the %d events in the record (%p): %0.5fs" %
+			[ self.event_history.size, self.event_history, last - first ]
+		return last - first <= self.time_threshold
+	end
+
+
+	### Returns +true+ if the number of events in the event history meet or exceed the
+	### #count_threshold.
+	def count_threshold_exceeded?
+		return self.event_history.size >= self.count_threshold
+	end
+
+end # class Arborist::Observer::Action