spectate 0.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,6 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+*.tmproj

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Stephen Eley
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,7 @@
+= spectate
+
+
+
+== Copyright
+
+Copyright (c) 2009 Stephen Eley. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "spectate"
+    gem.summary = %Q{General event framework for testing and monitoring}
+    gem.email = "sfeley@gmail.com"
+    gem.homepage = "http://github.com/SFEley/spectate"
+    gem.authors = ["Stephen Eley"]
+    gem.rubyforge_project = "spectate"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    
+    # ADDED BY SFE 
+    gem.requirements << "Tokyo Cabinet (easily installed from apt, MacPorts, etc.)"
+    gem.add_development_dependency "rspec", ">= 1.2.6"
+    gem.add_development_dependency "mocha", ">= 0.9.5"
+    gem.add_runtime_dependency "rufus-tokyo", ">=0.1.12"
+  end
+
+  Jeweler::RubyforgeTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  task :features do
+    abort "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+  end
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "spectate #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/api.mdown

@@ -0,0 +1,58 @@
+The Spectate Model
+==================
+
+The Spectate server follows a consistent tree-based model for storing the status of...well, whatever.  File changes.  Unit test results.  Git commits.  We don't care.  It's optimized for rapid and systematic notification of changes.  There are three interesting types of applications in the Spectate system:
+
+1. The **Spectate server** provides REST-based access to the data store and notifies spectators when data changes. The reference implementation is written in Sinatra, with a Tokyo Cabinet B+ tree for a data store. Individual nodes or arbitrarily deep collections can be retrieved quickly and with the same mechanics.
+2. **Agents** run on the client side and make updates to the server when something interesting happens. 
+3. **Spectators** are Web hooks which register themselves to the server on one or more nodes, and are notified of changes to those nodes or any of their children.
+
+There's also a command line client to add and remove services, but it's not as interesting.
+
+The rest of this document deals with the Spectate server, its data hierarchy and event model, and the API for communicating with it.  The architecture of agents and spectators left for service implementers.
+
+Anatomy of a Node
+-----------------
+The Spectate data store is a key-value store in which the keys compose a tree structure consisting of _nodes_ and _properties._ These types differ only slightly in their key declaration and are consistent with URI standards, allowing for a flat and simple implementation.
+
+* **Nodes** represent objects of any sort -- directories and files, tasks, unit tests, anything that can be graphed hierarchically. The _node key_ is the node's full URI for server retrieval: e.g., `http://localhost:20574/projects/spectate/doc/api.mdown`.  Any node can have any number of child nodes and properties.  _System nodes_ are ordinary nodes with a base name beginning with an underscore '\_'; this convention denotes data for Spectate's internal use, and is not ordinarily shown in query results.
+* **Properties** are attributes of nodes, and are denoted by a URI fragment identifier (aka a hash sign, aka '#'). The _property key_ is the property's full URI for server retrieval: e.g., `http://localhost:20574/projects/spectate/doc/api.mdown#last_modified`. Properties may not contain children, but may have multiple values, i.e. an array. 
+
+
+### (Stopped rewriting here.)
+You can also define any other properties or behavior you wish in subclasses.  You can make an property _persistent_ by using the **spectates** declaration:
+
+		class NiftySpectator < Spectate::Spectator
+			spectates :niftiness, 
+								:coolness
+			spectates :hipness, :quiet => true
+		end
+	
+Internally, persistent properties are just standalone key/value pairs; the key is the concatenation of the spectator's path, the URI _fragment_ identifier (i.e. the hash symbol, '#') and the property's name.  (E.g. `/niftyThings/NiftyExample1#coolness`.)  The _quiet_ option prevents hooks from running when the property is updated.  
+
+Ordinarily, every property update is saved immediately, and each hook is notified upon each update.  If you're assigning several properties at once or performing operations on a chain of spectators, you should use the **update** method:
+
+		spectator.update do |s|
+			s.niftiness = :very
+			s.coolness = -40
+			s.hipness = "tragic"
+		end
+	
+**update** offers simple transaction behavior: it defers saving and hook announcement _for all spectators_ until the block is completed.  This is useful for changes that trickle down to a spectator's children.  If an exception is raised out of the block, all changes are canceled and nothing is saved or announced.
+
+If you want to defer saving and announcement _globally_, there is also a class method version (**Spectate::Spectator.update**) which supplies no parameters, but otherwise offers the same behavior as calling the instance method on the tree's root node.
+
+Sociology of Spectators
+-----------------------
+[describe the tree]
+
+The following read-only attributes are available for convenience:
+
+* **path** is the URI path used to uniquely locate this spectator in REST requests.  It also indicates the spectator's position in the storage tree, and is (not coincidentally) the key value used for hash storage.  The path is the concatenation of the parent's path and a URI-safe version of the spectator's name.  All of the following relationship attributes are based on transformations of the path.
+* **parent** is the parent spectator.
+* **children** is an array of all spectators immediately descended from this one.  
+* **descendants** is an array of the spectator's children, all of _their_ children, and so on, in breadth-first order.
+* **siblings** is an array of all of the parent's children, excluding the current spectator.
+
+
+

data/bin/spectate

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(File.expand_path(File.join(File.dirname(__FILE__), "..", "lib")))
+
+require 'spectate/command'
+exit Spectate::Command.run

data/features/command.feature

@@ -0,0 +1,16 @@
+Feature: Command line utility
+  In order to easily control everything about Spectate
+  As a user
+  I want to call "spectate" from the command line
+
+  Scenario: Usage help
+    When I execute "spectate --help"
+    Then I should see "Usage:"
+
+	Scenario: Basic startup
+		Given no Spectate is running
+		When I execute "spectate"
+		Then I should see "Starting Spectate"
+		 And Spectate should be running
+
+	

data/features/step_definitions/command_steps.rb

@@ -0,0 +1,7 @@
+When /^I execute "([^\"]*)"$/ do |command|
+  @output = `#{command}`
+end
+
+Then /^I should see "([^\"]*)"$/ do |text|
+  @output.should =~ /#{text}/m
+end

data/features/step_definitions/spectate_steps.rb

@@ -0,0 +1,7 @@
+Given /^no Spectate is running$/ do
+  true
+end
+
+Then /^Spectate should be running$/ do
+  Spectate.ping.should be_true
+end

data/features/support/env.rb

@@ -0,0 +1,24 @@
+BASEDIR = File.expand_path(File.join(File.dirname(__FILE__), '..', '..'))
+
+$LOAD_PATH.unshift(BASEDIR + '/lib')
+
+# Make sure the binary is in our path
+ENV['PATH'] = BASEDIR + '/bin:' + ENV['PATH']
+
+require 'spectate'
+
+require 'spec/expectations'
+
+require File.join(BASEDIR, 'spec', 'helpers', 'config_helpers')
+World(Spectate::Spec::ConfigHelpers)
+
+# Set up a config file that makes sense for us
+Before do
+  create_config
+end
+
+After do
+  remove_config
+end
+  
+  

data/generators/config.ru

@@ -0,0 +1,19 @@
+# Spectate lives wherever this config.ru file lives.
+module Spectate
+  ROOT_DIR = File.expand_path(File.dirname(__FILE__))
+end
+
+# If you're developing or customizing Spectate, you can create a 'src'
+# directory and it'll load Spectate from here instead of the gem. If you want to
+# use your own projects directory instead, make a symlink. (If you don't know
+# how to do THAT, you probably shouldn't be developing or customizing Spectate.)
+if File.exists?(File.join(Spectate::ROOT_DIR, 'src'))
+  SOURCE_DIR = File.join(Spectate::ROOT_DIR, 'src')
+  require File.join(SOURCE_DIR, 'lib', 'spectate')
+else
+  require 'rubygems'
+  require 'spectate'  
+end
+
+# Make the magic happen
+run Spectate::Server

data/lib/spectate.rb

@@ -0,0 +1,22 @@
+# Jump to the front of the line
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'rubygems'
+require 'spectate/config'
+require 'spectate/exceptions'
+
+module Spectate
+  autoload :Client, 'spectate/client'
+  autoload :Encode, 'spectate/encode'
+  autoload :Ping, 'spectate/ping'
+  autoload :Server, 'spectate/server'
+  autoload :Spectator, 'spectate/spectator'
+  autoload :Status, 'spectate/status'
+  autoload :Tree, 'spectate/tree'
+  # Set vital defaults
+  VERSION = File.read(File.join(File.dirname(__FILE__), '..', 'VERSION')).chomp
+  ROOT_DIR = File.expand_path(File.join('~','.spectate')) unless const_defined?(:ROOT_DIR)
+  # Config['basedir'] = ENV['SPECTATE_DIR'] || File.expand_path(File.join('~','.spectate'))
+end
+

data/lib/spectate/client.rb

@@ -0,0 +1,35 @@
+require 'spectate'
+require 'restclient'
+require 'json'
+
+module Spectate
+  class Client
+    attr_accessor :protocol, :host, :port, :accept
+    
+    def initialize(options = {})
+      Spectate::Config.load_configuration unless Spectate::Config.loaded?
+      @protocol = options[:protocol] || Spectate::Config['protocol'] || 'http'
+      @host = options[:host] || Spectate::Config['host'] || 'localhost'
+      @port = options[:port] || Spectate::Config['port'] || 0
+      @accept = options[:accept] || Spectate::Config['accept'] || 'application/json'
+      
+      @driver = RestClient::Resource.new(root, :accept => accept)
+    end
+
+    def root
+      protocol.tr(':/','') + 
+      '://' +
+      host + 
+      ((port.to_i > 0) ? ":#{port}" : '')
+    end
+    
+    def get
+      response = @driver.get
+      s = Spectate::Status.new(root,'/',JSON.parse(response)) if accept == 'application/json'
+    rescue RestClient::ResourceNotFound
+      nil
+    rescue Errno::ECONNREFUSED
+      nil
+    end
+  end
+end

data/lib/spectate/command.rb

@@ -0,0 +1,99 @@
+require 'optparse'
+require 'spectate'
+
+module Spectate
+  SERVER_TYPES = %w[passenger thin mongrel webrick]
+  
+  PASSENGER_DEFAULTS = {
+    'rackup' => false,
+    'server' => 'passenger',
+    'host'   => 'spectate.local'
+  }
+  
+  RACKUP_DEFAULTS = {
+    'rackup' => true,
+    'host'   => 'localhost',
+    'port'   => 20574
+  }
+  
+  # Drives the 'spectate' command line utility.
+  class Command
+    extend Spectate::Ping
+    
+    # The primary event called by the command line
+    def self.run
+      skip_server = false
+      only_setup = false
+      stop_server = false
+      unless ARGV.empty?
+        options = OptionParser.new
+        options.on("-d", "--directory", "=DIR", String, "Set base directory for support files (default is ~/.spectate)") do |val| 
+          Spectate::Config['basedir'] = val
+          puts "Directory set to #{Spectate::Config['basedir']}"
+        end
+        options.on("--setup", "=TYPE", SERVER_TYPES, "Create the base directory and initialize config.yml with the given server type (#{SERVER_TYPES.join(', ')})") do |type|
+          only_setup = true
+          Spectate::Config['server'] = type
+          case type
+          when 'passenger':
+            Spectate::Config.default(PASSENGER_DEFAULTS)
+          else
+            Spectate::Config.default(RACKUP_DEFAULTS)
+          end
+        end
+        options.on("--host", "-h", "=NAME", String, "Set hostname or IP address for server access") do |host|
+          Spectate::Config['host'] = host
+        end
+        options.on("--port", "-p", "=PORT", Integer, "Set port number for server access") do |port|
+          Spectate::Config['port'] = port
+        end
+        options.on("--help", "-?", "--usage", "Displays this help screen") {|o| puts options.to_s; skip_server = true}
+        options.on("--stop", "Stops the Spectate server if running") {stop_server = true}
+        unparsed = options.parse(ARGV)
+      end
+      
+      if only_setup
+        Spectate::Config.generate_configuration
+      else
+        Spectate::Config.load_configuration
+        if stop_server
+          self.kill_server
+        else
+          self.ensure_server unless skip_server
+        end
+      end
+      true
+    rescue OptionParser::ParseError
+      puts "Oops... #{$!}"
+      puts options
+      false
+    rescue StandardError
+      puts $!
+      puts options
+      false
+    end
+    
+  private
+    def self.ensure_server
+      if ping
+        puts "Spectate is already running!"
+      else
+        puts "Starting Spectate on #{Spectate::Config['host']}:#{Spectate::Config['port']}..."
+        Dir.chdir Spectate::Config.basedir do |dir|
+          system "rackup -D -o #{Spectate::Config['host']} -p #{Spectate::Config['port']} -P spectate.pid config.ru"
+        end
+      end
+    end
+    
+    def self.kill_server()
+      pidfile = File.join(Spectate::Config.basedir, 'spectate.pid')
+      pid = File.read(pidfile).to_i if File.exists?(pidfile)
+      if pid and `ps x #{pid}` =~ /rackup.*-p #{Spectate::Config['port']}/
+        Process.kill("KILL",pid) and puts "Spectate stopped."
+        File.delete(pidfile)
+      else
+        puts "Spectate wasn't running! (Or you're using Passenger, or your PID file is incorrect,\n  or it's on a different server.  In any case, you're on your own.)"
+      end
+    end
+  end
+end

data/lib/spectate/config.rb

@@ -0,0 +1,71 @@
+require 'fileutils'
+require 'yaml'
+
+module Spectate
+  module Config
+    @config = Hash.new
+    @loaded = false
+    
+    def self.to_hash
+      @config
+    end
+      
+    def self.[](key)
+      @config[key]
+    end
+    
+    def self.[]=(key, val)
+      @config[key] = val
+    end
+    
+    def self.delete(key)
+      @config.delete(key)
+    end
+    
+    def self.clear!
+      @config = Hash.new
+      @loaded = false
+    end
+    
+    def self.default(hash)
+      @config = hash.merge(@config)
+    end
+    
+    def self.basedir
+      @basedir
+    end
+    
+    def self.loaded?
+      @loaded
+    end
+    
+    # Loads persistent values from the config.yml file in the base directory.
+    # Assumes that the basedir configuration variable has already been set before calling.
+    def self.load_configuration(confdir = nil)
+      @basedir = confdir || self['basedir'] || ENV['SPECTATE_DIR'] || ROOT_DIR
+      raise "Could not find a base directory!\nRun spectate --setup to initialize things or tell us your base directory\nwith the -d option." unless basedir
+      raise "Directory #{basedir} not found!\nRun spectate --setup to initialize things." unless File.directory?(basedir)
+      conffile = File.join(basedir, "config.yml")
+      raise "File #{conffile} not found!\nRun spectate --setup to initialize things." unless File.exists?(conffile)
+      @loaded = @config.merge!(YAML.load_file(conffile))
+    end
+
+    # Confirms that the config.yml file doesn't already exist, then creates one from passed parameters
+    def self.generate_configuration
+      configfile = File.join(self['basedir'], "config.yml")
+      raise "You already have a config.yml file!  We don't want to mess with a good thing.\n" +
+            "If you really want to start over, delete #{configfile} and run spectate --setup again." if File.exists?(configfile)
+      unless File.directory?(self['basedir'])
+        puts "Creating directory #{self['basedir']}"
+        FileUtils.makedirs self['basedir']
+      end
+      puts "Creating config.yml file"
+      File.open(configfile, 'w') {|config| YAML.dump(self.to_hash, config)}
+      puts "Creating rackup file"
+      FileUtils.copy File.join(File.dirname(__FILE__), '..', '..', 'generators', 'config.ru'), self['basedir']
+    end
+      
+        
+  end
+  
+end