arborist 0.0.1.pre20160128152542 → 0.0.1.pre20160606141735

data/lib/arborist/event.rb

@@ -1,6 +1,7 @@
 # -*- ruby -*-
 #encoding: utf-8
 
+require 'loggability'
 require 'pluggability'
 require 'arborist' unless defined?( Arborist )
 
@@ -9,12 +10,16 @@ require 'arborist' unless defined?( Arborist )
 # node state changes, when they're updated, and when various other operational
 # actions take place, e.g., the node tree gets reloaded.
 class Arborist::Event
-	extend Pluggability
+	extend Pluggability,
+	       Loggability
 
 
 	# Pluggability API -- look for events under the specified prefix
 	plugin_prefixes 'arborist/event'
 
+	# Loggability API -- log to the Arborist logger
+	log_to :arborist
+
 
 	### Create a new event with the specified +payload+ data.
 	def initialize( payload )
@@ -49,7 +54,7 @@ class Arborist::Event
 
 
 	### Return the event as a Hash.
-	def to_hash
+	def to_h
 		return {
 			'type' => self.type,
 			'data' => self.payload

data/lib/arborist/event/{node_matching.rb → node.rb}

@@ -4,9 +4,8 @@
 require 'arborist/event' unless defined?( Arborist::Event )
 
 
-# A mixin which adds common functionality to events which related to an
-# Arborist::Node.
-module Arborist::Event::NodeMatching
+# A base class for events which are related to an Arborist::Node.
+class Arborist::Event::Node < Arborist::Event
 
 	### Strip and save the node argument to the constructor.
 	def initialize( node, payload=nil )
@@ -26,12 +25,19 @@ module Arborist::Event::NodeMatching
 	### Returns +true+ if the specified +object+ matches this event.
 	def match( object )
 		return super &&
-			object.respond_to?( :criteria ) && self.node.matches?( object.criteria )
+			object.respond_to?( :criteria ) && self.node.matches?( object.criteria ) &&
+			( !object.respond_to?(:negative_criteria) || !self.node.matches?(object.negative_criteria) )
+	end
+
+
+	### Use the node data as this event's payload.
+	def payload
+		return self.node.to_h
 	end
 
 
 	### Inject the node identifier into the generated hash.
-	def to_hash
+	def to_h
 		return super.merge( identifier: self.node.identifier )
 	end
 

data/lib/arborist/event/node_acked.rb

@@ -2,17 +2,15 @@
 #encoding: utf-8
 
 require 'arborist/event' unless defined?( Arborist::Event )
-require 'arborist/event/node_matching'
+require 'arborist/event/node'
 
 
 # An event generated when a node is manually ACKed.
-class Arborist::Event::NodeAcked < Arborist::Event
-	include Arborist::Event::NodeMatching
+class Arborist::Event::NodeAcked < Arborist::Event::Node
 
-
-	### Create a new NodeAcked event for the specified +node+ and +ack_info+.
-	def initialize( node, ack_info )
-		super
+	### Create a new NodeAcked event for the specified +node+.
+	def initialize( node )
+		super( node, node.ack.to_h )
 	end
 
 end # class Arborist::Event::NodeAcked

data/lib/arborist/event/node_delta.rb

@@ -2,12 +2,13 @@
 #encoding: utf-8
 
 require 'arborist/event' unless defined?( Arborist::Event )
-require 'arborist/event/node_matching'
+require 'arborist/event/node'
+require 'arborist/mixins'
 
 
 # An event sent when one or more attributes of a node changes.
-class Arborist::Event::NodeDelta < Arborist::Event
-	include Arborist::Event::NodeMatching
+class Arborist::Event::NodeDelta < Arborist::Event::Node
+	include Arborist::HashUtilities
 
 
 	### Create a new NodeDelta event for the specified +node+. The +delta+
@@ -17,4 +18,30 @@ class Arborist::Event::NodeDelta < Arborist::Event
 		super # Overridden for the documentation
 	end
 
+
+	### Overridden so delta events only contain the diff of attributes that changed.
+	def payload
+		return @payload
+	end
+
+
+	### Returns +true+ if the specified +object+ matches this event.
+	def match( object )
+		return super &&
+			object.respond_to?( :criteria ) && self.delta_matches?( object.criteria )
+	end
+
+
+	### Returns +true+ if the 'delta' value of the specified +criteria+ (which
+	### must respond to .all?) matches the delta this event represents.
+	def delta_matches?( criteria )
+		delta_criteria = criteria['delta'] || {}
+		self.log.debug "Matching event against delta criteria: %p" % [ delta_criteria ]
+
+		return delta_criteria.all? do |key, val|
+			self.log.debug "  matching %p: %p against %p" % [ key, val, self.payload ]
+			hash_matches( self.payload, key, val )
+		end.tap {|match| self.log.debug "  event delta %s match." % [ match ? "DID" : "did not"] }
+	end
+
 end # class Arborist::Event::NodeDelta

data/lib/arborist/event/node_disabled.rb

@@ -0,0 +1,16 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist/event' unless defined?( Arborist::Event )
+require 'arborist/event/node'
+
+
+# An event generated when a node is manually disabled
+class Arborist::Event::NodeDisabled < Arborist::Event::Node
+
+	### Create a new NodeDisabled event for the specified +node+.
+	def initialize( node )
+		super( node, node.ack.to_h )
+	end
+
+end # class Arborist::Event::NodeDisabled

data/lib/arborist/event/node_down.rb

@@ -0,0 +1,10 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist/event' unless defined?( Arborist::Event )
+require 'arborist/event/node'
+
+
+# An event generated when a node goes down.
+class Arborist::Event::NodeDown < Arborist::Event::Node
+end # class Arborist::Event::NodeDown

data/lib/arborist/event/node_quieted.rb

@@ -0,0 +1,11 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist/event' unless defined?( Arborist::Event )
+require 'arborist/event/node'
+
+
+# An event generated when a node is quieted by one of its dependencies going
+# down.
+class Arborist::Event::NodeQuieted < Arborist::Event::Node
+end # class Arborist::Event::NodeQuieted

data/lib/arborist/event/node_unknown.rb

@@ -0,0 +1,10 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist/event' unless defined?( Arborist::Event )
+require 'arborist/event/node'
+
+
+# An event generated when a node transitions to an unknown state.
+class Arborist::Event::NodeUnknown < Arborist::Event::Node
+end # class Arborist::Event::NodeUnknown

data/lib/arborist/event/node_up.rb

@@ -0,0 +1,10 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist/event' unless defined?( Arborist::Event )
+require 'arborist/event/node'
+
+
+# An event generated when a node comes up.
+class Arborist::Event::NodeUp < Arborist::Event::Node
+end # class Arborist::Event::NodeUp

data/lib/arborist/event/node_update.rb

@@ -1,19 +1,10 @@
 #!/usr/bin/env ruby
 
 require 'arborist/event' unless defined?( Arborist::Event )
-require 'arborist/event/node_matching'
+require 'arborist/event/node'
 
 
 # An event sent on every node update, regardless of whether or not the update resulted in
 # any changes
-class Arborist::Event::NodeUpdate < Arborist::Event
-	include Arborist::Event::NodeMatching
-
-
-	### Use the node data as this event's payload.
-	def payload
-		return self.node.to_hash
-	end
-
-
+class Arborist::Event::NodeUpdate < Arborist::Event::Node
 end # class Arborist::Event::NodeUpdate

data/lib/arborist/event/sys_node_added.rb

@@ -0,0 +1,10 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist/event' unless defined?( Arborist::Event )
+require 'arborist/event/node'
+
+
+# A system event generated when a node is added to the tree.
+class Arborist::Event::SysNodeAdded < Arborist::Event::Node
+end # class Arborist::Event::SysNodeAdded

data/lib/arborist/event/sys_node_removed.rb

@@ -0,0 +1,10 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist/event' unless defined?( Arborist::Event )
+require 'arborist/event/node'
+
+
+# A system event generated when a node is removed from the tree.
+class Arborist::Event::SysNodeRemoved < Arborist::Event::Node
+end # class Arborist::Event::SysNodeRemoved

data/lib/arborist/exceptions.rb

@@ -17,5 +17,9 @@ module Arborist
 
 	class ServerError < RuntimeError; end
 
+	class NodeError < RuntimeError; end
+
+	class ConfigError < RuntimeError; end
+
 end # module Arborist
 

data/lib/arborist/manager.rb

@@ -2,6 +2,7 @@
 #encoding: utf-8
 
 require 'pathname'
+require 'tempfile'
 require 'configurability'
 require 'loggability'
 require 'rbczmq'
@@ -26,11 +27,44 @@ class Arborist::Manager
 	# The number of seconds to wait between checks for incoming signals
 	SIGNAL_INTERVAL = 0.5
 
+	# Configurability API -- set config defaults
+	CONFIG_DEFAULTS = {
+		state_file: nil,
+		checkpoint_frequency: 30
+	}
+
 
-	##
 	# Use the Arborist logger
 	log_to :arborist
 
+	# Configurability API -- use the 'arborist' section
+	config_key :arborist
+
+
+	##
+	# The Pathname of the file the manager's node tree state is saved to
+	singleton_attr_accessor :state_file
+
+	##
+	# The number of seconds between automatic state checkpoints
+	singleton_attr_accessor :checkpoint_frequency
+
+
+	### Configurability API -- configure the manager
+	def self::configure( config=nil )
+		config ||= {}
+		config = self.defaults.merge( config[:manager] || {} )
+
+		self.state_file = config[:state_file] && Pathname( config[:state_file] )
+
+		interval = config[:checkpoint_frequency].to_i
+		if interval && interval.nonzero?
+			self.checkpoint_frequency = interval
+		else
+			self.checkpoint_frequency = nil
+		end
+	end
+
 
 	#
 	# Instance methods
@@ -54,6 +88,7 @@ class Arborist::Manager
 
 		@api_handler = nil
 		@event_publisher = nil
+		@checkpoint_timer = nil
 	end
 
 
@@ -114,8 +149,11 @@ class Arborist::Manager
 			@tree_sock.pollable.close
 			@zmq_loop.remove( @event_sock )
 			@event_sock.pollable.close
+			@zmq_loop.cancel_timer( @checkpoint_timer ) if @checkpoint_timer
 		end
 
+		self.save_node_states
+
 		self.log.debug "Resetting ZMQ context"
 		Arborist.reset_zmq_context
 	end
@@ -141,6 +179,9 @@ class Arborist::Manager
 		@event_sock.handler = @event_publisher
 		@zmq_loop.register( @event_sock )
 
+		@checkpoint_timer = self.start_state_checkpointing
+		@zmq_loop.register_timer( @checkpoint_timer ) if @checkpoint_timer
+
 		self.setup_signal_timer
 		self.start_time = Time.now
 
@@ -194,6 +235,72 @@ class Arborist::Manager
 	end
 
 
+	#
+	# :section: Node state saving/reloading
+	#
+
+	### Write out the state of all the manager's nodes to the state_file if one is
+	### configured.
+	def save_node_states
+		path = self.class.state_file or return
+		self.log.info "Saving current node state to %s" % [ path ]
+		tmpfile = Tempfile.create(
+			[path.basename.to_s.sub(path.extname, ''), path.extname],
+			path.dirname.to_s,
+			encoding: 'binary'
+		)
+		Marshal.dump( self.nodes, tmpfile )
+		tmpfile.close
+
+		File.rename( tmpfile.path, path.to_s )
+
+	rescue SystemCallError => err
+		self.log.error "%p while saving node state: %s" % [ err.class, err.message ]
+
+	ensure
+		File.unlink( tmpfile.path ) if tmpfile && File.exist?( tmpfile.path )
+	end
+
+
+	### Attempt to restore the state of loaded node from the configured state file. Returns
+	### true if it succeeded, or false if a state file wasn't configured, doesn't
+	### exist, isn't readable, or couldn't be unmarshalled.
+	def restore_node_states
+		path = self.class.state_file or return false
+		return false unless path.readable?
+
+		self.log.info "Restoring node state from %s" % [ path ]
+		nodes = Marshal.load( path.open('r:binary') )
+
+		nodes.each do |identifier, saved_node|
+			self.log.debug "Loaded node: %p" % [ identifier ]
+			if (( current_node = self.nodes[ identifier ] ))
+				self.log.debug "Restoring state of the %p node." % [ identifier ]
+				current_node.restore( saved_node )
+			else
+				self.log.info "Not restoring state for the %s node: not present in the loaded tree." %
+					[ identifier ]
+			end
+		end
+
+		return true
+	end
+
+
+	### Start a timer that will save a snapshot of the node tree's state to the state
+	### file on a configured interval if it's configured.
+	def start_state_checkpointing
+		return nil unless self.class.state_file
+		interval = self.class.checkpoint_frequency or return nil
+
+		self.log.info "Setting up node state checkpoint every %ds" % [ interval ]
+		checkpoint_timer = ZMQ::Timer.new( interval, 0 ) do
+			self.save_node_states
+		end
+		return checkpoint_timer
+	end
+
+
 	#
 	# :section: Signal Handling
 	# These methods set up some behavior for starting, restarting, and stopping
@@ -292,6 +399,7 @@ class Arborist::Manager
 	### Handle a USR1 signal. Writes a message to the log.
 	def on_user1_signal( signo )
 		self.log.info "Checkpoint: User signal."
+		self.save_node_states
 	end
 
 
@@ -312,17 +420,27 @@ class Arborist::Manager
 	### Build the tree out of all the loaded nodes.
 	def build_tree
 		self.log.info "Building tree from %d loaded nodes." % [ self.nodes.length ]
-		self.nodes.each do |identifier, node|
+
+		# Build primary tree structure
+		self.nodes.each_value do |node|
 			next if node.operational?
 			self.link_node_to_parent( node )
 		end
 		self.tree_built = true
+
+		# Set up secondary dependencies
+		self.nodes.each_value do |node|
+			node.register_secondary_dependencies( self )
+		end
+
+		self.restore_node_states
 	end
 
 
 	### Link the specified +node+ to its parent. Raises an error if the specified +node+'s
 	### parent is not yet loaded.
 	def link_node_to_parent( node )
+		self.log.debug "Linking node %p to its parent" % [ node ]
 		parent_id = node.parent || '_'
 		parent_node = self.nodes[ parent_id ] or
 			raise "no parent '%s' node loaded for %p" % [ parent_id, node ]
@@ -336,13 +454,24 @@ class Arborist::Manager
 	def add_node( node )
 		identifier = node.identifier
 
-		unless self.nodes[identifier].equal?( node )
+		unless self.nodes[ identifier ].equal?( node )
 			self.remove_node( self.nodes[identifier] )
 			self.nodes[ identifier ] = node
 		end
 
-		self.log.debug "Linking node %p to its parent" % [ node ]
-		self.link_node_to_parent( node ) if self.tree_built?
+		if self.tree_built?
+			self.link_node( node )
+			node.handle_event( Arborist::Event.create(:sys_node_added, node) )
+		end
+	end
+
+
+	### Link the node to other nodes in the tree.
+	def link_node( node )
+		raise "Tree is not built yet" unless self.tree_built?
+
+		self.link_node_to_parent( node )
+		node.register_secondary_dependencies( self )
 	end
 
 
@@ -355,6 +484,7 @@ class Arborist::Manager
 		raise "Can't remove an operational node" if node.operational?
 
 		self.log.info "Removing node %p" % [ node ]
+		node.handle_event( Arborist::Event.create(:sys_node_removed, node) )
 		node.children.each do |identifier, child_node|
 			self.remove_node( child_node )
 		end
@@ -384,7 +514,7 @@ class Arborist::Manager
 	### match the given +filter+, skipping downed nodes and all their children
 	### unless +include_down+ is set. If +return_values+ is set to +nil+, then all
 	### values from the node will be returned.
-	def fetch_matching_node_states( filter, return_values, include_down=false )
+	def fetch_matching_node_states( filter, return_values, include_down=false, negative_filter={} )
 		nodes_iter = if include_down
 				self.all_nodes
 			else
@@ -393,6 +523,7 @@ class Arborist::Manager
 
 		states = nodes_iter.
 			select {|node| node.matches?(filter) }.
+			reject {|node| !negative_filter.empty? && node.matches?(negative_filter) }.
 			each_with_object( {} ) do |node, hash|
 				hash[ node.identifier ] = node.fetch_values( return_values )
 			end
@@ -437,14 +568,14 @@ class Arborist::Manager
 	### an Enumerator if no block is given.
 	def reachable_nodes( &block )
 		iter = self.enumerator_for( self.root ) do |node|
-			!(node.down? || node.disabled?)
+			!(node.down? || node.disabled? || node.quieted?)
 		end
 		return iter.each( &block ) if block
 		return iter
 	end
 
 
-	### Return an enumerator for the specified +node+.
+	### Return an enumerator for the specified +start_node+.
 	def enumerator_for( start_node, &filter )
 		return Enumerator.new do |yielder|
 			traverse = ->( node ) do
@@ -458,24 +589,64 @@ class Arborist::Manager
 	end
 
 
+	### Return a +depth+ limited enumerator for the specified +start_node+.
+	def depth_limited_enumerator_for( start_node, depth, &filter )
+		return Enumerator.new do |yielder|
+			traverse = ->( node, current_depth ) do
+				self.log.debug "Enumerating nodes from %s at depth: %p" %
+					[ node.identifier, current_depth ]
+
+				if !filter || filter.call( node )
+					yielder.yield( node )
+					node.each do |child|
+						traverse[ child, current_depth - 1 ]
+					end if current_depth > 0
+				end
+			end
+			traverse.call( start_node, depth )
+		end
+	end
+
+
+	### Return an Array of all nodes below the specified +node+.
+	def descendants_for( node )
+		return self.enumerator_for( node ).to_a
+	end
+
+
+	### Return the Array of all nodes above the specified +node+.
+	def ancestors_for( node )
+		parent_id = node.parent or return []
+		parent = self.nodes[ parent_id ]
+		return [ parent ] + self.ancestors_for( parent )
+	end
+
 
 	#
 	# Event API
 	#
 
-	### Create a subscription for the node with the specified +identifier+ and
-	### +event_pattern+, using the given +criteria+ when considering an event.
-	def create_subscription( identifier, event_pattern, criteria )
+	### Add the specified +subscription+ to the node corresponding with the given +identifier+.
+	def subscribe( identifier, subscription )
 		identifier ||= '_'
-
 		node = self.nodes[ identifier ] or raise ArgumentError, "no such node %p" % [ identifier ]
-		sub = Arborist::Subscription.new( self.event_publisher, event_pattern, criteria )
 
-		self.log.debug "Registering subscription %p" % [ sub ]
-		node.add_subscription( sub )
-		self.log.debug " adding '%s' to the subscriptions hash." % [ sub.id ]
-		self.subscriptions[ sub.id ] = node
+		self.log.debug "Registering subscription %p" % [ subscription ]
+		node.add_subscription( subscription )
+		self.log.debug " adding '%s' to the subscriptions hash." % [ subscription.id ]
+		self.subscriptions[ subscription.id ] = node
 		self.log.debug "  subscriptions hash: %#0x" % [ self.subscriptions.object_id ]
+	end
+
+
+	### Create a subscription that publishes to the Manager's event publisher for
+	### the node with the specified +identifier+ and +event_pattern+, using the
+	### given +criteria+ when considering an event.
+	def create_subscription( identifier, event_pattern, criteria )
+		sub = Arborist::Subscription.new( event_pattern, criteria ) do |*args|
+			self.event_publisher.publish( *args )
+		end
+		self.subscribe( identifier, sub )
 
 		return sub
 	end
@@ -492,7 +663,6 @@ class Arborist::Manager
 	### Propagate one or more +events+ to the specified +node+ and its ancestors in the tree,
 	### publishing them to matching subscriptions belonging to the nodes along the way.
 	def propagate_events( node, *events )
-		self.log.info "Propagating %d events to node %s" % [ events.length, node.identifier ]
 		node.publish_events( *events )
 
 		if node.parent