arborist 0.0.1.pre20160106113421

data/README.md

@@ -0,0 +1,75 @@
+# Arborist
+
+home :: http://deveiate.org/projects/Arborist  
+code :: http://bitbucket.org/ged/Arborist  
+github :: https://github.com/ged/arborist  
+docs :: http://deveiate.org/code/arborist  
+
+
+## Description
+
+Arborist is a monitoring framework that follows the UNIX philosophy
+of small parts and loose coupling for stability, reliability, and
+customizability.
+
+
+## Prerequisites
+
+* Ruby 2.2 or better
+
+
+## Installation
+
+    $ gem install arborist
+
+
+## Further Reading
+
+You'll likely want to start with [the Tutorial](Tutorial.html).
+
+
+## Contributing
+
+You can check out the current development source with Mercurial via its
+[project page](http://bitbucket.org/ged/Arborist). Or if you prefer Git, via 
+[its Github mirror](https://github.com/ged/arborist).
+
+After checking out the source, run:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the API documentation.
+
+
+## License
+
+Copyright (c) 2015, Michael Granger and Mahlon E. Smith
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+

data/Rakefile

@@ -0,0 +1,81 @@
+#!/usr/bin/env rake
+
+begin
+	require 'hoe'
+rescue LoadError
+	abort "This Rakefile requires hoe (gem install hoe)"
+end
+
+GEMSPEC = 'arborist.gemspec'
+
+
+Hoe.plugin :mercurial
+Hoe.plugin :signing
+Hoe.plugin :deveiate
+
+Hoe.plugins.delete :rubyforge
+Hoe.plugins.delete :gemcutter
+
+hoespec = Hoe.spec 'arborist' do |spec|
+	spec.readme_file = 'README.md'
+	spec.history_file = 'History.md'
+	spec.extra_rdoc_files = FileList[ '*.rdoc', '*.md' ]
+	self.license 'BSD-3-Clause'
+	spec.urls = {
+		home:   'http://deveiate.org/projects/arborist',
+		code:   'http://bitbucket.org/ged/arborist',
+		docs:   'http://deveiate.org/code/arborist',
+		github: 'http://github.com/ged/arborist',
+	}
+
+	spec.developer 'Michael Granger', 'ged@FaerieMUD.org'
+	spec.developer 'Mahlon E. Smith', 'mahlon@martini.nu'
+
+	spec.dependency 'schedulability', '~> 0.1'
+	spec.dependency 'loggability', '~> 0.11'
+	spec.dependency 'configurability', '~> 2.2'
+	spec.dependency 'pluggability', '~> 0.4'
+	spec.dependency 'state_machines', '~> 0.2'
+	spec.dependency 'msgpack', '~> 0.6'
+	spec.dependency 'rbczmq', '~> 1.7'
+
+	spec.dependency 'rspec', '~> 3.2', :developer
+	spec.dependency 'simplecov', '~> 0.9', :developer
+	spec.dependency 'timecop', '~> 0.7', :developer
+
+	spec.require_ruby_version( '>=2.2.0' )
+	spec.hg_sign_tags = true if spec.respond_to?( :hg_sign_tags= )
+
+	self.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
+end
+
+
+ENV['VERSION'] ||= hoespec.spec.version.to_s
+
+# Run the tests before checking in
+task 'hg:precheckin' => [ :check_history, :check_manifest, :gemspec, :spec ]
+
+# Rebuild the ChangeLog immediately before release
+task :prerelease => 'ChangeLog'
+CLOBBER.include( 'ChangeLog' )
+
+desc "Build a coverage report"
+task :coverage do
+	ENV["COVERAGE"] = 'yes'
+	Rake::Task[:spec].invoke
+end
+
+
+task :gemspec => GEMSPEC
+file GEMSPEC => __FILE__ do |task|
+	spec = $hoespec.spec
+	spec.files.delete( '.gemtest' )
+	spec.signing_key = nil
+	spec.version = "#{spec.version}.pre#{Time.now.strftime("%Y%m%d%H%M%S")}"
+	File.open( task.name, 'w' ) do |fh|
+		fh.write( spec.to_ruby )
+	end
+end
+
+task :default => :gemspec
+

data/TODO.md

@@ -0,0 +1,24 @@
+# To-Do
+
+## Manager
+
+* Serialize nodes on shutdown
+* Include a node's subscriptions in its serialized data
+* Implement loading/reloading nodes. 
+
+## Tree API
+
+* Add "grafting": node add/removal
+
+## Observers
+
+* Scheduling time periods for action/summarizing
+* Summarizing and Actions should be 1st order objects
+* Unsubscribe from Arborist and ZMQ subscriptions on shutdown
+* Figure out how to match on delta events: the criteria
+  for matching nodes has to be separated from that which matches
+  the delta pairs.
+
+## Node
+
+* Add a 'disabled' state, can be set on 'up' nodes by acking them.

data/bin/amanagerd

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+require 'arborist'
+require 'arborist/manager'
+
+$0 = "Arborist::Manager"
+
+Arborist.load_config( ARGV.pop )
+mgr = Arborist.manager_for( ARGV.shift )
+mgr.run

data/bin/amonitord

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'arborist'
+require 'arborist/monitor_runner'
+
+monitors_path = ARGV.shift or raise "No monitor file specified."
+
+Arborist.load_config( ARGV.shift )
+Arborist.load_all
+
+runner = Arborist.monitor_runner_for( monitors_path )
+runner.run

data/bin/aobserverd

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'arborist'
+require 'arborist/observer_runner'
+
+observers_path = ARGV.shift or raise "No observer file specified."
+
+Arborist.load_config( ARGV.shift )
+Arborist.load_all
+
+runner = Arborist.observer_runner_for( observers_path )
+runner.run

data/lib/arborist.rb

@@ -0,0 +1,182 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'rbczmq'
+
+require 'pathname'
+require 'configurability'
+require 'loggability'
+
+
+# Arborist namespace
+module Arborist
+	extend Loggability,
+	       Configurability
+
+	# Package version
+	VERSION = '0.0.1'
+
+	# Version control revision
+	REVISION = %q$Revision: fddcbace9b6d $
+
+
+	# The name of the environment variable which can be used to set the config path
+	CONFIG_ENV = 'ARBORIST_CONFIG'
+
+	# The name of the config file for local overrides.
+	LOCAL_CONFIG_FILE = Pathname( '~/.arborist.yml' ).expand_path
+
+	# The name of the config file that's loaded if none is specified.
+	DEFAULT_CONFIG_FILE = Pathname( 'arborist.yml' ).expand_path
+
+	# Configurability API -- default configuration values
+	CONFIG_DEFAULTS = {
+		tree_api_url:  'ipc:///tmp/arborist_tree.sock',
+		event_api_url: 'ipc:///tmp/arborist_events.sock'
+	}
+
+
+	##
+	# Set up a logger for the Arborist namespace
+	log_as :arborist
+
+	# Configurability API -- use the 'arborist'
+	config_key :arborist
+
+
+	require 'arborist/mixins'
+	extend Arborist::MethodUtilities
+
+
+	##
+	# The ZMQ REP socket for the API for accessing the node tree.
+	singleton_attr_accessor :tree_api_url
+	@tree_api_url = CONFIG_DEFAULTS[ :tree_api_url ]
+
+	##
+	# The ZMQ PUB socket for published events
+	singleton_attr_accessor :event_api_url
+	@event_api_url = CONFIG_DEFAULTS[ :event_api_url ]
+
+
+	#
+	# :section: Configuration API
+	#
+
+	### Configurability API.
+	def self::configure( config=nil )
+		config = self.defaults.merge( config || {} )
+
+		self.tree_api_url  = config[ :tree_api_url ]
+		self.event_api_url = config[ :event_api_url ]
+	end
+
+
+	### Get the loaded config (a Configurability::Config object)
+	def self::config
+		Configurability.loaded_config
+	end
+
+
+	### Returns +true+ if the configuration has been loaded at least once.
+	def self::config_loaded?
+		return self.config ? true : false
+	end
+
+
+	### Load the specified +config_file+, install the config in all objects with
+	### Configurability, and call any callbacks registered via #after_configure.
+	def self::load_config( config_file=nil, defaults=nil )
+		config_file ||= ENV[ CONFIG_ENV ]
+		config_file ||= LOCAL_CONFIG_FILE if LOCAL_CONFIG_FILE.exist?
+		config_file ||= DEFAULT_CONFIG_FILE
+
+		defaults    ||= Configurability.gather_defaults
+
+		self.log.info "Loading config from %p with defaults for sections: %p." %
+			[ config_file, defaults.keys ]
+		config = Configurability::Config.load( config_file, defaults )
+
+		config.install
+	end
+
+
+	### Add a constructor function to the Arborist namespace called +name+
+	### with the specified +method_body+.
+	def self::add_dsl_constructor( name, &method_body )
+		self.log.debug "Adding constructor for %p: %p" % [ name, method_body ]
+		singleton_class.instance_exec( name, method_body ) do |name, body|
+			define_method( name, &body )
+		end
+	end
+
+
+	### Return a new Arborist::Manager for the nodes described in files under
+	### the specified +directory+.
+	def self::manager_for( directory )
+		self.load_all
+		nodes = Arborist::Node.each_in( directory )
+		manager = Arborist::Manager.new
+		manager.load_tree( nodes )
+
+		return manager
+	end
+
+
+	### Return a new Arborist::MonitorRunner for the monitors described in files under
+	### the specified +directory+.
+	def self::monitor_runner_for( directory )
+		self.load_all
+		monitors = Arborist::Monitor.each_in( directory )
+		runner = Arborist::MonitorRunner.new
+		runner.load_monitors( monitors )
+
+		return runner
+	end
+
+
+	### Return a new Arborist::ObserverRunner for the observers described in files under
+	### the specified +directory+.
+	def self::observer_runner_for( directory )
+		self.load_all
+		observers = Arborist::Observer.each_in( directory )
+		runner = Arborist::ObserverRunner.new
+		runner.load_observers( observers )
+
+		return runner
+	end
+
+
+	### Load all node and event types
+	def self::load_all
+		Arborist::Node.load_all
+	end
+
+
+	### Destroy any existing ZMQ state.
+	def self::reset_zmq_context
+		@zmq_context.destroy if @zmq_context.respond_to?( :destroy )
+		@zmq_context = nil
+	end
+
+
+	### Fetch the ZMQ context for Arborist.
+	def self::zmq_context
+		return @zmq_context ||= ZMQ::Context.new
+	end
+
+
+	require 'arborist/exceptions'
+	require 'arborist/mixins'
+
+	autoload :Client, 'arborist/client'
+	autoload :Event, 'arborist/event'
+	autoload :Manager, 'arborist/manager'
+	autoload :Monitor, 'arborist/monitor'
+	autoload :MonitorRunner, 'arborist/monitor_runner'
+	autoload :Node, 'arborist/node'
+	autoload :Observer, 'arborist/observer'
+	autoload :Subscription, 'arborist/subscription'
+
+end # module Arborist
+

data/lib/arborist/client.rb

@@ -0,0 +1,191 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'arborist' unless defined?( Arborist )
+require 'msgpack'
+
+
+# Unified Arborist Manager client for both the Tree and Event APIs
+class Arborist::Client
+	extend Loggability
+
+	# The version of the client.
+	API_VERSION = 1
+
+	# Loggability API -- log to the Arborist log host
+	log_to :arborist
+
+
+	### Create a new Client with the given API socket URIs.
+	def initialize( tree_api_url: nil, event_api_url: nil )
+		@tree_api_url  = tree_api_url  || Arborist.tree_api_url
+		@event_api_url = event_api_url || Arborist.event_api_url
+
+		@request_queue = nil
+		@event_subscriptions = nil
+	end
+
+
+	######
+	public
+	######
+
+	# The ZMQ URI required to speak to the Arborist tree API.
+	attr_accessor :tree_api_url
+
+	# The ZMQ URI required to speak to the Arborist event API.
+	attr_accessor :event_api_url
+
+
+	### Return the manager's current status as a hash.
+	def status
+		request = self.make_status_request
+		return self.send_tree_api_request( request )
+	end
+
+
+	### Return the manager's current status as a hash.
+	def make_status_request
+		return self.pack_message( :status )
+	end
+
+
+	### Return the manager's current node tree.
+	def list( *args )
+		request = self.make_list_request( *args )
+		return self.send_tree_api_request( request )
+	end
+
+
+	### Return the manager's current node tree.
+	def make_list_request( from: nil )
+		header = {}
+		self.log.debug "From is: %p" % [ from ]
+		header[:from] = from if from
+
+		return self.pack_message( :list, header )
+	end
+
+
+	### Return the manager's current node tree.
+	def fetch( criteria={}, *args )
+		request = self.make_fetch_request( criteria, *args )
+		return self.send_tree_api_request( request )
+	end
+
+
+	### Return the manager's current node tree.
+	def make_fetch_request( criteria, include_down: false, properties: :all )
+		header = {}
+		header[ :include_down ] = true if include_down
+		header[ :return ] = properties if properties != :all
+
+		return self.pack_message( :fetch, header, criteria )
+	end
+
+
+	### Update the identified nodes in the manager with the specified data.
+	def update( *args )
+		request = self.make_update_request( *args )
+		return self.send_tree_api_request( request )
+	end
+
+
+	### Update the identified nodes in the manager with the specified data.
+	def make_update_request( data )
+		return self.pack_message( :update, nil, data )
+	end
+
+
+	### Add a subscription
+	def subscribe( *args )
+		request = self.make_subscribe_request( *args )
+		response = self.send_tree_api_request( request )
+		return response.first
+	end
+
+
+	### Make a subscription request for the specified +criteria+, +identifier+, and +event_type+.
+	def make_subscribe_request( criteria: {}, identifier: nil, event_type: nil )
+		self.log.debug "Making subscription request for identifier: %p, event_type: %p, criteria: %p" %
+			[ identifier, event_type, criteria ]
+		header = {}
+		header[ :identifier ] = identifier if identifier
+		header[ :event_type ] = event_type
+
+		return self.pack_message( :subscribe, header, criteria )
+	end
+
+
+	### Send the packed +request+ via the Tree API socket, raise an error on
+	### unsuccessful response, and return the response body.
+	def send_tree_api_request( request )
+		self.log.debug "Sending request: %p" % [ request ]
+		self.tree_api.send( request )
+
+		res = self.tree_api.recv
+		self.log.debug "Received response: %p" % [ res ]
+
+		header, body = self.unpack_message( res )
+		unless header[ 'success' ]
+			raise "Arborist manager said: %s" % [ header['reason'] ]
+		end
+
+		return body
+	end
+
+
+
+	### Format ruby +data+ for communicating with the Arborist manager.
+	def pack_message( verb, *data )
+		header = data.shift || {}
+		body   = data.shift
+
+		header.merge!( action: verb, version: API_VERSION )
+
+		self.log.debug "Packing message; header: %p, body: %p" % [ header, body ]
+
+		return MessagePack.pack([ header, body ])
+	end
+
+
+	### De-serialize an Arborist manager response.
+	def unpack_message( msg )
+		return MessagePack.unpack( msg )
+	end
+
+
+	### Return a ZMQ REQ socket connected to the manager's tree API, instantiating
+	### it if necessary.
+	def tree_api
+		return @tree_api ||= self.make_tree_api_socket
+	end
+
+
+	### Create a new ZMQ REQ socket connected to the manager's tree API.
+	def make_tree_api_socket
+		self.log.info "Connecting to the tree socket %p" % [ self.tree_api_url ]
+		sock = Arborist.zmq_context.socket( :REQ )
+		sock.connect( self.tree_api_url )
+
+		return sock
+	end
+
+
+	### Return a ZMQ SUB socket connected to the manager's event API, instantiating
+	### it if necessary.
+	def event_api
+		return @event_api ||= self.make_event_api_socket
+	end
+
+
+	### Create a new ZMQ SUB socket connected to the manager's event API.
+	def make_event_api_socket
+		self.log.info "Connecting to the event socket %p" % [ self.event_api_url ]
+		sock = Arborist.zmq_context.socket( :SUB )
+		sock.connect( self.event_api_url )
+
+		return sock
+	end
+
+end # class Arborist::Client