arborist 0.2.0.pre20170519125456 → 0.2.0

data/lib/arborist/dependency.rb

@@ -221,10 +221,22 @@ class Arborist::Dependency
 	### Return an English description of why this dependency is not met. If it is
 	### met, returns +nil+.
 	def down_reason
-		ids = self.down_identifiers
-		subdeps = self.down_subdeps
+		parts = [
+			self.down_primary_reasons,
+			self.down_secondary_reasons
+		].compact
+
+		return nil if parts.empty?
+
+		return parts.join( '; ' )
+	end
 
-		return nil if ids.empty? && subdeps.empty?
+
+	### Return an English description of why any first tier dependencies are not met,
+	### or +nil+ if there are none.
+	def down_primary_reasons
+		ids = self.down_identifiers
+		return nil if ids.empty?
 
 		msg = nil
 		case self.behavior
@@ -245,8 +257,16 @@ class Arborist::Dependency
 		else
 			raise "Don't know how to build a description of down behavior for %p" % [ self.behavior ]
 		end
+	end
+
+
+	### Return an English description of why any subdependencies are not met,
+	### or +nil+ if there are none.
+	def down_secondary_reasons
+		subdeps = self.down_subdeps
+		return nil if subdeps.empty?
 
-		return msg
+		return subdeps.map( &:down_reason ).join( ' and ' )
 	end
 
 

data/lib/arborist/event.rb

@@ -58,11 +58,27 @@ class Arborist::Event
 	### Return the event as a Hash.
 	def to_h
 		return {
-			'type' => self.type,
-			'data' => self.payload
+			type: self.type,
+			data: self.payload
 		}
 	end
 
+
+	### Return a string representation of the object suitable for debugging.
+	def inspect
+		return "#<%p:%#016x %s>" % [
+			self.class,
+			self.object_id * 2,
+			self.inspect_details,
+		]
+	end
+
+
+	### Return the detail portion of the #inspect string appropriate for this event type.
+	def inspect_details
+		return self.payload.inspect
+	end
+
 end # class Arborist::Event
 
 

data/lib/arborist/event/node.rb

@@ -38,9 +38,13 @@ class Arborist::Event::Node < Arborist::Event
 	end
 
 
-	### Inject the node identifier into the generated hash.
+	### Inject useful node metadata into the generated hash.
 	def to_h
-		return super.merge( identifier: self.node.identifier )
+		return super.merge(
+			identifier: self.node.identifier,
+			parent:     self.node.parent,
+			nodetype:   self.node.type
+		)
 	end
 
 end # module Arborist::Event::NodeMatching

data/lib/arborist/event/node_warn.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 monitor adds the first warning to a node.
+class Arborist::Event::NodeWarn < Arborist::Event::Node
+
+	### Create a new NodeWarn event for the specified +node+.
+	def initialize( node )
+		super( node, node.warnings.to_h )
+	end
+
+end # class Arborist::Event::NodeWarn

data/lib/arborist/manager.rb

@@ -22,7 +22,8 @@ class Arborist::Manager
 	extend Configurability,
 		   Loggability,
 	       Arborist::MethodUtilities
-	include CZTop::Reactor::SignalHandling
+	include CZTop::Reactor::SignalHandling,
+	        Arborist::HashUtilities
 
 
 	# Signals the manager responds to
@@ -31,6 +32,22 @@ class Arborist::Manager
 		# :TODO: :QUIT, :WINCH, :USR2, :TTIN, :TTOU
 	] & Signal.list.keys.map( &:to_sym )
 
+	# Array of actions supported by the Tree API
+	VALID_TREEAPI_ACTIONS = %w[
+		ack
+		deps
+		fetch
+		graft
+		modify
+		prune
+		search
+		status
+		subscribe
+		unack
+		unsubscribe
+		update
+	]
+
 
 	# Use the Arborist logger
 	log_to :arborist
@@ -169,7 +186,6 @@ class Arborist::Manager
 	def run
 		self.log.info "Getting ready to start the manager."
 		self.setup_sockets
-		self.publish_system_event( 'startup', start_time: Time.now.to_s, version: Arborist::VERSION )
 		self.register_timers
 		self.with_signal_handler( reactor, *QUEUE_SIGS ) do
 			self.start_accepting_requests
@@ -244,6 +260,17 @@ class Arborist::Manager
 	end
 
 
+	### Return a human-readable representation of the Manager suitable for debugging.
+	def inspect
+		return "#<%p:%#x {runid: %s} %d nodes>" % [
+			self.class,
+			self.object_id * 2,
+			self.run_id,
+			self.nodes.length,
+		]
+	end
+
+
 	#
 	# :section: Node state saving/reloading
 	#
@@ -251,6 +278,7 @@ class Arborist::Manager
 	### Write out the state of all the manager's nodes to the state_file if one is
 	### configured.
 	def save_node_states
+		start_time = Time.now
 		path = self.class.state_file or return
 		self.log.info "Saving current node state to %s" % [ path ]
 		tmpfile = Tempfile.create(
@@ -262,6 +290,7 @@ class Arborist::Manager
 		tmpfile.close
 
 		File.rename( tmpfile.path, path.to_s )
+		self.log.debug "Saved state file in %0.1f seconds." % [ Time.now - start_time ]
 
 	rescue SystemCallError => err
 		self.log.error "%p while saving node state: %s" % [ err.class, err.message ]
@@ -323,8 +352,15 @@ class Arborist::Manager
 	### Register a periodic timer that will save a snapshot of the node tree's state to the state
 	### file on a configured interval if one is configured.
 	def register_checkpoint_timer
-		return nil unless self.class.state_file
-		interval = self.class.checkpoint_frequency or return nil
+		unless self.class.state_file
+			self.log.info "No state file configured; skipping checkpoint timer setup."
+			return nil
+		end
+		interval = self.class.checkpoint_frequency
+		unless interval && interval.nonzero?
+			self.log.info "Checkpoint frequency is %p; skipping checkpoint timer setup." % [ interval ]
+			return nil
+		end
 
 		self.log.info "Setting up node state checkpoint every %0.3fs" % [ interval ]
 		@checkpoint_timer = self.reactor.add_periodic_timer( interval ) do
@@ -446,10 +482,8 @@ class Arborist::Manager
 	def add_node( node )
 		identifier = node.identifier
 
-		unless self.nodes[ identifier ].equal?( node )
-			self.remove_node( self.nodes[identifier] )
-			self.nodes[ identifier ] = node
-		end
+		raise Arborist::NodeError, "Node %p already present." % [ identifier ] if self.nodes[ identifier ]
+		self.nodes[ identifier ] = node
 
 		if self.tree_built?
 			self.link_node( node )
@@ -491,26 +525,26 @@ class Arborist::Manager
 
 	### Update the node with the specified +identifier+ with the given +new_properties+
 	### and propagate any events generated by the update to the node and its ancestors.
-	def update_node( identifier, new_properties )
+	def update_node( identifier, new_properties, monitor_key='_' )
 		unless (( node = self.nodes[identifier] ))
 			self.log.warn "Update for non-existent node %p ignored." % [ identifier ]
 			return []
 		end
 
-		events = node.update( new_properties )
+		events = node.update( new_properties, monitor_key )
 		self.propagate_events( node, events )
 	end
 
 
-	### Traverse the node tree and fetch the specified +return_values+ from any nodes which
+	### Traverse the node tree and return the specified +return_values+ from any nodes which
 	### 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
+	### if +exclude_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, negative_filter={} )
-		nodes_iter = if include_down
-				self.all_nodes
-			else
+	def find_matching_node_states( filter, return_values, exclude_down=false, negative_filter={} )
+		nodes_iter = if exclude_down
 				self.reachable_nodes
+			else
+				self.all_nodes
 			end
 
 		states = nodes_iter.
@@ -551,7 +585,7 @@ class Arborist::Manager
 	### Set up the ZeroMQ REP socket for the Tree API.
 	def setup_tree_socket
 		@tree_socket = CZTop::Socket::REP.new
-		self.log.debug "  binding the tree API socket (%#0x) to %p" %
+		self.log.info "  binding the tree API socket (%#0x) to %p" %
 			[ @tree_socket.object_id * 2, Arborist.tree_api_url ]
 		@tree_socket.options.linger = 0
 		@tree_socket.bind( Arborist.tree_api_url )
@@ -569,7 +603,7 @@ class Arborist::Manager
 	def on_tree_socket_event( event )
 		if event.readable?
 			request = event.socket.receive
-			msg = self.handle_tree_request( request )
+			msg = self.dispatch_request( request )
 			event.socket << msg
 		else
 			raise "Unsupported event %p on tree API socket!" % [ event ]
@@ -578,14 +612,11 @@ class Arborist::Manager
 
 
 	### Handle the specified +raw_request+ and return a response.
-	def handle_tree_request( raw_request )
+	def dispatch_request( raw_request )
 		raise "Manager is shutting down" unless self.running?
 
 		header, body = Arborist::TreeAPI.decode( raw_request )
-		raise Arborist::MessageError, "missing required header 'action'" unless
-			header.key?( 'action' )
-		handler = self.lookup_tree_request_action( header ) or
-			raise Arborist::MessageError, "No such action '%s'" % [ header['action'] ]
+		handler = self.lookup_tree_request_action( header )
 
 		return handler.call( header, body )
 
@@ -611,16 +642,19 @@ class Arborist::Manager
 		raise Arborist::MessageError, "unsupported version %d" % [ header['version'] ] unless
 			header['version'] == 1
 
-		handler_name = "handle_%s_request" % [ header['action'] ]
-		return nil unless self.respond_to?( handler_name )
+		action = header['action'] or
+			raise Arborist::MessageError, "missing required header 'action'"
+		raise Arborist::MessageError, "No such action '%s'" % [ action ] unless
+			VALID_TREEAPI_ACTIONS.include?( action )
 
+		handler_name = "handle_%s_request" % [ action ]
 		return self.method( handler_name )
 	end
 
 
 	### Return a response to the `status` action.
 	def handle_status_request( header, body )
-		self.log.debug "STATUS: %p" % [ header ]
+		self.log.info "STATUS: %p" % [ header ]
 		return Arborist::TreeAPI.successful_response(
 			server_version: Arborist::VERSION,
 			state: self.running? ? 'running' : 'not running',
@@ -632,7 +666,7 @@ class Arborist::Manager
 
 	### Return a response to the `subscribe` action.
 	def handle_subscribe_request( header, body )
-		self.log.debug "SUBSCRIBE: %p" % [ header ]
+		self.log.info "SUBSCRIBE: %p" % [ header ]
 		event_type      = header[ 'event_type' ]
 		node_identifier = header[ 'identifier' ]
 
@@ -642,7 +676,7 @@ class Arborist::Manager
 
 		subscription = self.create_subscription( node_identifier, event_type, positive, negative )
 		self.log.info "Subscription to %s events at or under %s: %p" %
-			[ event_type, node_identifier || 'the root node', subscription ]
+			[ event_type || 'all', node_identifier || 'the root node', subscription ]
 
 		return Arborist::TreeAPI.successful_response( id: subscription.id )
 	end
@@ -650,7 +684,7 @@ class Arborist::Manager
 
 	### Return a response to the `unsubscribe` action.
 	def handle_unsubscribe_request( header, body )
-		self.log.debug "UNSUBSCRIBE: %p" % [ header ]
+		self.log.info "UNSUBSCRIBE: %p" % [ header ]
 		subscription_id = header[ 'subscription_id' ] or
 			return Arborist::TreeAPI.error_response( 'client', 'No identifier specified for UNSUBSCRIBE.' )
 		subscription = self.remove_subscription( subscription_id ) or
@@ -664,20 +698,25 @@ class Arborist::Manager
 	end
 
 
-	### Return a repsonse to the `list` action.
-	def handle_list_request( header, body )
-		self.log.debug "LIST: %p" % [ header ]
+	### Return a repsonse to the `fetch` action.
+	def handle_fetch_request( header, body )
+		self.log.info "FETCH: %p" % [ header ]
 		from  = header['from'] || '_'
 		depth = header['depth']
+		tree  = header['tree']
 
-		start_node = self.nodes[ from ]
+		start_node = self.nodes[ from ] or
+			return Arborist::TreeAPI.error_response( 'client', "No such node %s." % [from] )
 		self.log.debug "  Listing nodes under %p" % [ start_node ]
-		iter = if depth
+
+		if tree
+			iter = [ start_node.to_h(depth: (depth || -1)) ]
+		elsif depth
 			self.log.debug "    depth limited to %d" % [ depth ]
-			self.depth_limited_enumerator_for( start_node, depth )
+			iter = self.depth_limited_enumerator_for( start_node, depth )
 		else
 			self.log.debug "    no depth limit"
-			self.enumerator_for( start_node )
+			iter = self.enumerator_for( start_node )
 		end
 		data = iter.map( &:to_h )
 		self.log.debug "  got data for %d nodes" % [ data.length ]
@@ -686,11 +725,45 @@ class Arborist::Manager
 	end
 
 
-	### Return a response to the 'fetch' action.
-	def handle_fetch_request( header, body )
-		self.log.debug "FETCH: %p" % [ header ]
+	### Return a response to the `deps` action.
+	def handle_deps_request( header, body )
+		self.log.info "DEPS: %p" % [ header ]
+		from = header['from'] || '_'
+
+		deps = self.merge_dependencies_from( from )
+		deps.delete( from )
 
-		include_down = header['include_down']
+		return Arborist::TreeAPI.successful_response({ deps: deps.to_a })
+
+	rescue Arborist::ClientError => err
+		return Arborist::TreeAPI.error_response( 'client', err.message )
+	end
+
+
+	### Recurse into the children and secondary dependencies of the +from+ node and
+	### merge the identifiers of the traversed nodes into the +deps_set+.
+	def merge_dependencies_from( from, deps_set=Set.new )
+		return deps_set unless deps_set.add?( from )
+
+		start_node = self.nodes[ from ] or
+			raise Arborist::ClientError "No such node %s." % [ from ]
+
+		self.enumerator_for( start_node ).each do |subnode|
+			deps_set.add( subnode.identifier )
+			subnode.node_subscribers.each do |subdep|
+				self.merge_dependencies_from( subdep, deps_set )
+			end
+		end
+
+		return deps_set
+	end
+
+
+	### Return a response to the 'search' action.
+	def handle_search_request( header, body )
+		self.log.info "SEARCH: %p" % [ header ]
+
+		exclude_down = header['exclude_down']
 		values = if header.key?( 'return' )
 				header['return'] || []
 			else
@@ -700,7 +773,7 @@ class Arborist::Manager
 		body = [ body ] unless body.is_a?( Array )
 		positive = body.shift
 		negative = body.shift || {}
-		states = self.fetch_matching_node_states( positive, values, include_down, negative )
+		states = self.find_matching_node_states( positive, values, exclude_down, negative )
 
 		return Arborist::TreeAPI.successful_response( states )
 	end
@@ -708,14 +781,15 @@ class Arborist::Manager
 
 	### Update nodes using the data from the update request's +body+.
 	def handle_update_request( header, body )
-		self.log.debug "UPDATE: %p" % [ header ]
+		self.log.info "UPDATE: %p" % [ header ]
 
 		unless body.respond_to?( :each )
 			return Arborist::TreeAPI.error_response( 'client', 'Malformed update: body does not respond to #each' )
 		end
 
+		monitor_key = header['monitor_key']
 		body.each do |identifier, properties|
-			self.update_node( identifier, properties )
+			self.update_node( identifier, properties, monitor_key )
 		end
 
 		return Arborist::TreeAPI.successful_response( nil )
@@ -724,7 +798,7 @@ class Arborist::Manager
 
 	### Remove a node and its children.
 	def handle_prune_request( header, body )
-		self.log.debug "PRUNE: %p" % [ header ]
+		self.log.info "PRUNE: %p" % [ header ]
 
 		identifier = header[ 'identifier' ] or
 			return Arborist::TreeAPI.error_response( 'client', 'No identifier specified for PRUNE.' )
@@ -736,10 +810,15 @@ class Arborist::Manager
 
 	### Add a node
 	def handle_graft_request( header, body )
-		self.log.debug "GRAFT: %p" % [ header ]
+		self.log.info "GRAFT: %p" % [ header ]
 
 		identifier = header[ 'identifier' ] or
 			return Arborist::TreeAPI.error_response( 'client', 'No identifier specified for GRAFT.' )
+
+		if self.nodes[ identifier ]
+			return Arborist::TreeAPI.error_response( 'client', "Node %p already exists." % [identifier] )
+		end
+
 		type = header[ 'type' ] or
 			return Arborist::TreeAPI.error_response( 'client', 'No type specified for GRAFT.' )
 		parent = header[ 'parent' ] || '_'
@@ -765,7 +844,7 @@ class Arborist::Manager
 
 	### Modify a node's operational attributes
 	def handle_modify_request( header, body )
-		self.log.debug "MODIFY: %p" % [ header ]
+		self.log.info "MODIFY: %p" % [ header ]
 
 		identifier = header[ 'identifier' ] or
 			return Arborist::TreeAPI.error_response( 'client', 'No identifier specified for MODIFY.' )
@@ -775,12 +854,56 @@ class Arborist::Manager
 
 		self.log.debug "Modifying operational attributes of the %s node: %p" % [ identifier, body ]
 
+		if new_parent_identifier = body.delete( 'parent' )
+			old_parent = self.nodes[ node.parent ]
+			new_parent = self.nodes[ new_parent_identifier ] or
+				return Arborist::TreeAPI.error_response( 'client', "No such parent node: %p" % [new_parent_identifier] )
+			node.reparent( old_parent, new_parent )
+		end
+
 		node.modify( body )
 
 		return Arborist::TreeAPI.successful_response( nil )
 	end
 
 
+	### Acknowledge a node
+	def handle_ack_request( header, body )
+		self.log.info "ACK: %p" % [ header ]
+
+		identifier = header[ 'identifier' ] or
+			return Arborist::TreeAPI.error_response( 'client', 'No identifier specified for ACK.' )
+		node = self.nodes[ identifier ] or
+			return Arborist::TreeAPI.error_response( 'client', "No such node %p" % [identifier] )
+
+		self.log.debug "Acking the %s node: %p" % [ identifier, body ]
+
+		body = symbolify_keys( body )
+		events = node.acknowledge( **body )
+		self.propagate_events( node, events )
+
+		return Arborist::TreeAPI.successful_response( nil )
+	end
+
+
+	### Un-acknowledge a node
+	def handle_unack_request( header, body )
+		self.log.info "UNACK: %p" % [ header ]
+
+		identifier = header[ 'identifier' ] or
+			return Arborist::TreeAPI.error_response( 'client', 'No identifier specified for UNACK.' )
+		node = self.nodes[ identifier ] or
+			return Arborist::TreeAPI.error_response( 'client', "No such node %p" % [identifier] )
+
+		self.log.debug "Unacking the %s node: %p" % [ identifier, body ]
+
+		events = node.unacknowledge
+		self.propagate_events( node, events )
+
+		return Arborist::TreeAPI.successful_response( nil )
+	end
+
+
 	### Return the current root node.
 	def root_node
 		return self.nodes[ '_' ]
@@ -859,7 +982,7 @@ class Arborist::Manager
 	### Set up the ZMQ PUB socket for published events.
 	def setup_event_socket
 		@event_socket = CZTop::Socket::PUB.new
-		self.log.debug "  binding the event socket (%#0x) to %p" %
+		self.log.info "  binding the event socket (%#0x) to %p" %
 			[ @event_socket.object_id * 2, Arborist.event_api_url ]
 		@event_socket.options.linger = ( self.linger * 1000 ).ceil
 		@event_socket.bind( Arborist.event_api_url )
@@ -893,6 +1016,7 @@ class Arborist::Manager
 
 	### Register the publisher with the reactor if it's not already.
 	def register_event_socket
+		self.log.debug "Registering event socket for write events."
 		self.reactor.enable_events( self.event_socket, :write ) unless
 			self.reactor.event_enabled?( self.event_socket, :write )
 	end
@@ -900,6 +1024,7 @@ class Arborist::Manager
 
 	### Unregister the event publisher socket from the reactor if it's registered.
 	def unregister_event_socket
+		self.log.debug "Unregistering event socket for write events."
 		self.reactor.disable_events( self.event_socket, :write ) if
 			self.reactor.event_enabled?( self.event_socket, :write )
 	end
@@ -909,6 +1034,7 @@ class Arborist::Manager
 	def on_event_socket_event( event )
 		if event.writable?
 			if (( msg = self.event_queue.shift ))
+				# self.log.debug "Publishing event %p" % [ msg ]
 				event.socket << msg
 			end
 		else
@@ -921,7 +1047,12 @@ class Arborist::Manager
 
 	### Publish a system event that observers can watch for to detect restarts.
 	def publish_heartbeat_event
-		self.publish_system_event( 'heartbeat', run_id: self.run_id )
+		return unless self.start_time
+		self.publish_system_event( 'heartbeat',
+			run_id: self.run_id,
+			start_time: self.start_time.iso8601,
+			version: Arborist::VERSION
+		)
 	end