arborist 0.0.1.pre20160106113421

data/History.md

@@ -0,0 +1,4 @@
+# v0.0.1 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+
+Initial release.
+

data/LICENSE

@@ -0,0 +1,29 @@
+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/Manifest.txt

@@ -0,0 +1,72 @@
+.document
+.simplecov
+ChangeLog
+Events.md
+History.md
+LICENSE
+Manifest.txt
+Monitors.md
+Nodes.md
+Observers.md
+Protocol.md
+README.md
+Rakefile
+TODO.md
+bin/amanagerd
+bin/amonitord
+bin/aobserverd
+lib/arborist.rb
+lib/arborist/client.rb
+lib/arborist/event.rb
+lib/arborist/event/node_acked.rb
+lib/arborist/event/node_delta.rb
+lib/arborist/event/node_matching.rb
+lib/arborist/event/node_update.rb
+lib/arborist/event/sys_reloaded.rb
+lib/arborist/exceptions.rb
+lib/arborist/manager.rb
+lib/arborist/manager/event_publisher.rb
+lib/arborist/manager/tree_api.rb
+lib/arborist/mixins.rb
+lib/arborist/monitor.rb
+lib/arborist/monitor/socket.rb
+lib/arborist/monitor_runner.rb
+lib/arborist/node.rb
+lib/arborist/node/host.rb
+lib/arborist/node/root.rb
+lib/arborist/node/service.rb
+lib/arborist/observer.rb
+lib/arborist/observer/action.rb
+lib/arborist/observer/summarize.rb
+lib/arborist/observer_runner.rb
+lib/arborist/subscription.rb
+spec/arborist/client_spec.rb
+spec/arborist/event/node_update_spec.rb
+spec/arborist/event_spec.rb
+spec/arborist/manager/event_publisher_spec.rb
+spec/arborist/manager/tree_api_spec.rb
+spec/arborist/manager_spec.rb
+spec/arborist/mixins_spec.rb
+spec/arborist/monitor/socket_spec.rb
+spec/arborist/monitor_runner_spec.rb
+spec/arborist/monitor_spec.rb
+spec/arborist/node/host_spec.rb
+spec/arborist/node/root_spec.rb
+spec/arborist/node/service_spec.rb
+spec/arborist/node_spec.rb
+spec/arborist/observer/action_spec.rb
+spec/arborist/observer/summarize_spec.rb
+spec/arborist/observer_spec.rb
+spec/arborist/subscription_spec.rb
+spec/arborist_spec.rb
+spec/data/monitors/pings.rb
+spec/data/monitors/port_checks.rb
+spec/data/monitors/system_resources.rb
+spec/data/monitors/web_services.rb
+spec/data/nodes/duir.rb
+spec/data/nodes/localhost.rb
+spec/data/nodes/sidonie.rb
+spec/data/nodes/yevaud.rb
+spec/data/observers/auditor.rb
+spec/data/observers/webservices.rb
+spec/spec_helper.rb

data/Monitors.md

@@ -0,0 +1,141 @@
+# Monitors
+
+Monitors are loaded in a fashion similar to the way nodes describing the network topology are
+loaded: you provide a Enumerator that yields Arborist::Monitor objects to the #load_monitors method
+of an Arborist::MonitorRunner object. The `Arborist::Monitor.each_in` method, given a path to a directory containing `.rb` files that declare one or more monitors, will return such an Enumerator, but you could also use this to load monitor descriptions from any source you prefer, e.g., LDAP, a RDBMS, etc.
+
+
+## Declaration DSL
+
+To facilitate describing monitors to run, Arborist::Monitor also provides a DSL-like syntax for constructing them. 
+
+For example, this would declare two monitors, one which pings every 'host' node except those tagged as laptops in the network every 20 seconds, and the other which pings 'host' nodes tagged as laptops every 5 minutes.
+
+    # monitors/pings.rb
+    require 'arborist/monitor'
+
+    Arborist::Monitor 'ping check' do
+    	every 20.seconds
+    	match type: 'host'
+    	exclude tag: :laptop
+    	use :address
+    	exec 'fping'
+    end
+
+    Arborist::Monitor 'transient host pings' do
+    	every 5.minutes
+    	match type: 'host', tag: 'laptop'
+        use :address
+    	exec 'fping'
+    end
+
+Each monitor is given a human-readable description for use in user interfaces, and one or more attributes that describe which nodes should be monitored, how they should be monitored, and how often the monitor should be run.
+
+### Monitor Attributes
+
+#### every( seconds )
+
+Declare the interval between runs of the monitor. The monitor will be skewed by a small amount from this value (unless you specify `splay 0`) to prevent many monitors from starting up simultaneously.
+
+#### splay( seconds )
+
+Manually set the amount of splay (random offset from the interval) the monitor should use. It defaults to `Math.logn( interval )`.
+
+#### exec( command )
+#### exec {|node_attributes| ... }
+#### exec( module )
+
+Specify what should be run to do the actual monitoring. The first form simply `spawn`s the specified command with its STDIN opened to a stream of serialized node data. 
+
+By default, the format of the serialized nodes is one node per line, and each line looks like this:
+
+    «identifier» «attribute1»=«attribute1 value» «attribute2»=«attribute2 value»
+
+Each line should use shell-escaping semantics, so that if an attribute value contains whitespace, it should be quoted, control characters need to be escaped, etc.
+
+For example, the ping checker might receive input like:
+
+    duir address=192.168.16.3
+    sidonie address="192.168.16.3"
+    yevaud address="192.168.16.10"
+
+If the command you are running doesn't support this format, you can override this in one of two ways.
+
+If your command expects the node data as command-line arguments, you can provide a custom `exec_arguments` block. It will receive an Array of Arborist::Node objects and it should generate an Array of arguments to append to the command before `spawn`ing it.
+
+    exec_arguments do |nodes|
+        # Build an address -> node mapping for pairing the updates back up by address
+        @node_map = nodes.each_with_object( {} ) do |node, hash|
+            address = node.address
+            hash[ address ] = node
+        end
+        
+        @node_map.keys
+    end
+
+If your command expects the node data via `STDIN`, but in a different format, you may declare an `exec_input` block. It will be called with the same node array, and additionally an IO open to the STDIN of the running command. This can be combined with the `exec_arguments` block, if you're dealing with something really weird.
+
+    exec_input do |nodes, writer|
+        # Build an address -> node mapping for pairing the updates back up by address
+        @node_map = nodes.each_with_object( {} ) do |node, hash|
+            address = node.address
+            hash[ address ] = node
+        end
+        
+        writer.puts( node_map.values )
+    end
+
+The monitor must write results for any of the listed identifiers that require update in the same format to its STDOUT. For the ping check above, the results might look like:
+
+    duir rtt=20ms
+    sidonie rtt=103ms
+    yevaud rtt= error=Host\ unreachable.
+
+If the program writes its output in some other format, you can provide a `handle_results` block. It will be called with the program's `STDOUT` if the block takes one argument, and if it takes an additional argument its `STDERR` as well. It should return a Hash of update Hashes, keyed by the node identifier it should be sent to.
+
+    handle_results do |pid, out, err|
+        updates = {}
+        
+        out.each_line do |line|
+            address, status = line.split( /\s+:\s+/, 2 )
+            
+            # Use the @node_map we created up in the exec_arguments to map the output
+            # back into identifiers. Error-checking omitted for brevity.
+            identifier = @node_map[ address ].identifier
+
+            # 127.0.0.1 is alive (0.12 ms)
+            # 8.8.8.8 is alive (61.6 ms)
+            # 192.168.16.16 is unreachable
+            if status =~ /is alive \((\d+\.\d+ ms)\)/i
+                updates[ identifier ] = { ping: { rtt: Float($1) } }
+            else
+                updates[ identifier ] = { error: status }
+            end
+        end
+
+        updates
+    end
+
+Unlisted attributes are unchanged.  A listed attribute with an empty value is explicitly cleared. An identifier that isn't listed in the results means no update is necessary for that node.
+
+If you find yourself wanting to repeat one or more of the exec callbacks, you can also wrap them in a module and call `exec_callbacks` with it.
+
+The second and third forms can be used to implement a monitor in Ruby. In the second, the block is called with the Hash of node data, keyed by identifier, and it must return a Hash of updates keyed by identifier. The third form expects any object that responds to `#run`, which will be invoked the same way as the block.
+
+
+#### use( *properties )
+
+Specify the list of properties to provide to the monitor for each node. If this is unspecified, the input to the monitor will be just the list of identifiers.
+
+
+
+    # Does everything in Ruby; gets the Array of Nodes as arguments to the block, expected to
+    # return a Hash of updates keyed by node identifier
+    exec do |nodes|
+        
+    end
+
+
+    # Runs an external
+	exec 'fping', '-e', '-t', '150'
+

data/Observers.md

@@ -0,0 +1,72 @@
+# Observers
+
+subscription
+    * Event to subscribe to
+    * Node to attach subscription to.  No node means 'root', which sees all subnode events.
+    * One or more action blocks
+
+Actions have:
+    * a block to execute
+    * Zero or more time-periods, which are unioned together. No time periods means anytime.
+
+Pragmas:
+    * Summarize:
+      (send a single alert summarizing every event received over x period of time, or n events)
+    * Squelch:
+
+
+:MAHLON:
+    The manager should probably serialize subscriptions for its nodes. Otherwise the manager
+    can restart and any running observers will never again receive events because the
+    subscriptions will have disappeared.
+
+
+
+## Examples
+
+    # -*- ruby -*-
+    #encoding: utf-8
+    
+    require 'arborist'
+    
+    WORK_HOURS = 'hour {8am-6pm}'
+    OFF_HOURS =  'hour {6pm-8am}'
+    
+    Arborist::Observer "Webservers" do
+        subscribe to: 'node.delta',
+            where: {
+                type: 'service',
+                port: 80,
+                delta: { status: ['up', 'down'] }
+            }
+    
+        action( during: WORK_HOURS ) do |uuid, event|
+            $stderr.puts "Webserver %s is DOWN (%p)" % [ event['data']['identifier'], event['data'] ]
+        end
+        summarize( every: 5.minutes, count: 5, during: OFF_HOURS ) do |*tuples|
+            email to: 'ops@example.com', subject: ""
+        end
+    
+    end
+
+
+
+## Schedulability stuff
+
+schedule = Schedule.new
+schedule |= Period.time( '8AM' .. '8PM' )
+schedule |= Period.day( 'Mon' .. 'Fri' )
+
+
+# Thymelörde! - An Amazeballs Gem for Doing Stuff With Time™
+
+
+schedule = Thymelörde!.yes?( 'Tue-Thur {6am-9pm}' )
+schedule.ehh? #=> false
+schedule.yes? #=> false
+
+
+Legba -- the gatekeeper?
+
+
+

data/Protocol.md

@@ -0,0 +1,214 @@
+# Monitors
+
+## Protocol
+
+ZMQ REQ socket, msgpack message consisting of an Array of two elements:
+
+    [
+        header,
+        body
+    ]
+
+Header is a Map of the form:
+
+    {
+        action: «verb»,     # required
+        version: 1,         # required
+        [verb-specific attributes]
+    }
+
+Body is either Nil, a Map of key-value pairs, or an Array of Maps appropriate to the `action`.
+
+
+## status
+
+Fetch the status of the Manager.
+
+    {
+        action: status,
+        version: 1,
+    }
+
+Response:
+
+    {
+        success: true,
+        version: 1
+    },
+    {
+        server_version: 0.0.1,
+        state: 'running',
+        uptime: 17155,
+        nodecount: 342
+    }
+
+
+## list
+
+Request:
+
+    [
+        {
+            action: list,
+            version: 1
+            [from: «identifier»]
+        }
+    ]
+
+Successful response:
+
+    [
+        {
+            success: true,
+            version: 1
+        },
+        [
+            {
+                identifier: 'foo',
+                status: 'up',
+                parent: '_',
+                properties: {},
+            },
+            {
+                identifier: 'bar',
+                status: 'down',
+                parent: 'foo',
+                properties: {},
+            }
+        ]
+    ]
+
+failure example:
+
+    [
+        {
+            success: false,
+            reason: "human readable exception message or whatever",
+            category: either 'server' or 'client', meaning who is responsible for the error
+            version: 1
+        }
+    ]
+
+Fetch a data structure describing the node tree from the node with the specified
+`identifier`, or the root node if no `identifier` is specified.
+
+
+## fetch
+
+Fetch the `address`, `description`, and `status` of all nodes.
+
+    [
+        {
+            action: fetch,
+            version: 1,
+            include_down: true,
+            return: [address, description, status]
+        },
+        {
+            'theon' => {
+                address: '10.2.10.4',
+                description: 'no theon, reek',
+                status: down,
+            },
+            'thoros' => {
+                address: '10.2.10.4',
+                description: "The Red God's champion",
+                status: up,
+            }
+        ]
+    ]
+
+
+### return
+
+- not specified : returns everything.
+- `Nil` : returns just identifiers
+- array of fields : returns the values of those fields
+
+Search for nodes that match the filter given in the request body, returning a serialized map of node identifiers to requested state.
+
+
+## update
+
+    [
+        {
+            action: update,
+            version: 1
+        },
+        {
+            duir: {
+                pingtime: 0.02
+            },
+            sidonie: {
+                pingtime: 0.28
+            }
+        }
+    ]
+
+With a failure:
+
+    [
+        {
+            action: update,
+            version: 1
+        },
+        {
+            duir: {
+                pingtime: null,
+                error: "Host unreachable."
+            },
+            sidonie: {
+                pingtime: 0.28
+            }
+        }
+    ]
+
+
+## subscribe
+
+Get node change delta events for every 'host' type node.
+
+    {
+        action: subscribe,
+        version: 1,
+        event_type: node.delta
+    },
+    {
+        type: 'host',
+    }
+
+Get a snapshot of node state on every update for 'service' type nodes under
+the 'bennett' node.
+
+    {
+        action: subscribe,
+        version: 1,
+        event_type: node.update,
+        identifier: 'bennett'
+    },
+    {
+        type: 'service',
+    }
+
+Get events of state changes to services running on port 80.
+
+    {
+        action: subscribe,
+        version: 1,
+        event_type: node.delta
+    },
+    {
+        type: 'service',
+        port: 80
+    }
+
+Get notified of every system event (startup, shutdown, reload, etc.)
+
+    {
+        action: subscribe,
+        version: 1,
+        event_type: sys.*
+    },
+    Nil
+
+