vanity-source 0.3

data/CHANGELOG

@@ -0,0 +1,16 @@
+2010-08-11 v0.3 Always be sending changes
+
+Changed: Collector update methods accepts inc and timestamp arguments (but set
+is gone).
+
+Fixed: Rubygems source captures most recent downloads count as meta-data,
+updates collector with change since last update.
+
+Fixed: Rubygems source can handle whatever name you throw at it and properly
+escapes it.
+
+2010-08-10 v0.2 Working Rubygems source
+
+Fixed: Rubygems source not updating meta data like authors, project info, URL.
+
+2010-08-09 v0.1 First release

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org/"
+
+group :development do
+  gem "rake"
+  gem "yard"
+end
+
+group :test do
+  gem "rack", "1.1.0"
+  gem "webmock"
+end

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2010 Assaf Arkin
+
+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/Rakefile

@@ -0,0 +1,28 @@
+require "rake/testtask"
+
+# -- Building stuff --
+
+spec = Gem::Specification.load(File.expand_path("vanity-source.gemspec", File.dirname(__FILE__)))
+
+desc "Build the Gem"
+task :build do
+  sh "gem build #{spec.name}.gemspec"
+end
+
+desc "Install #{spec.name} locally"
+task :install=>:build do
+  sudo = "sudo" unless File.writable?( Gem::ConfigMap[:bindir])
+  sh "#{sudo} gem install #{spec.name}-#{spec.version}.gem"
+end
+
+desc "Push new release to gemcutter and git tag"
+task :push=>["test", "build"] do
+  sh "git push"
+  puts "Tagging version #{spec.version} .."
+  sh "git tag v#{spec.version}"
+  sh "git push --tag"
+  puts "Building and pushing gem .."
+  sh "gem push #{spec.name}-#{spec.version}.gem"
+end
+
+task :test

data/lib/vanity/source.rb

@@ -0,0 +1,167 @@
+require "uri"
+require "net/http"
+
+module Vanity
+
+  # Each collector is tuned to use a given source with a given set of
+  # parameters. For example, a metric (collector) of Twitter followers would use
+  # the Twitter source and parameter telling it which Twitter account to watch.
+  #
+  #
+  # == Setup
+  #
+  # A collector is setup in four steps. First, the #display method returns an
+  # HTML form which will be displayed to the user. In fact, this method returns
+  # two values:
+  # * inputs -- HTML input controls for setting up a new controller.
+  # * notes -- Additional setup notes, e.g. other steps that need to be
+  #   followed, what values to supply, etc.
+  #
+  # Wrap input controls within the label and use the source[..param..] notation
+  # for the name attribute. For example, for our Twitter source:
+  #   <label>Screen name <input type="text" name="source[screen_name]" size="30"></label>
+  #
+  # When the form is filled, the #setup method is called with a context and
+  # values from the form fields. Since the source needs to store state
+  # information about the collector, it uses the context for that. The context
+  # is a Hash that can store basic Ruby values (nil, String, boolean, Numeric,
+  # Array and Hash).
+  #
+  # In particular, #setup must set two special values: name and columns. The
+  # first is the name for the collector, e.g. our Twitter source might produce
+  # the name "Twitter Mentions of @vanitydash". The second denotes all the
+  # columns that could be used in a metric. This value is an array, where each
+  # item describes a single column with a hash using the following keys:
+  # * id -- Column identifier (if missing, derived from column name)
+  # * name -- Column name (required)
+  #
+  # Shortly after #setup, the #validate method is called with the same context.
+  # If it raises any exception, the error is displayed to the user and the
+  # collector is discarded. Otherwise, #register is called with a Webhook URL.
+  # Some sources use that to register the Webhook with another service.
+  #
+  #
+  # == Updates
+  #
+  # Periodically, the source will be asked to update the collector by calling
+  # the #update method. This method is called with the same context and a block.
+  # If the source service passes data through the web hook, then #update is
+  # called with context, Request object and a block.
+  #
+  # The block passed to #update can be used to update the collector by yielding
+  # to it with a hash of named arguments. A single update may yield any number
+  # of times with any combination of arguments.
+  #
+  # The named arguments are:
+  # * inc -- Columns to increment (metric). Records a change in value which may
+  #   be positive or negative. This is a hash where the keys are column ids (or
+  #   indexes), the values are integers or floats.
+  # * timestamp -- The Time (if missing, uses the current system time).
+  #
+  # Occasionally, the #meta method is called. This method is used to display
+  # meta-data from the most recent state (i.e. last update). It returns an array
+  # of fields, each being a hash with the following values:
+  # * title -- Title for this field (not required)
+  # * text -- Text to show as value of the field
+  # * url -- Link (not required)
+  #
+  #
+  # == Teardown
+  #
+  # Eventually the collector is destroyed and the Webhook is unregistered by
+  # calling #unregister.
+  module Source
+
+    class << self
+      attr_accessor :logger
+
+      # Returns all available sources.
+      def all
+        @sources ||= {}
+      end
+
+      # Returns source by its identifier.
+      def find(id)
+        all[id]
+      end
+
+      # Loads all the sources from the given directory. The source identifier is
+      # derived from the filename (e.g. all/my_source.rb becomes "my_source"). The
+      # source class must map to the source identifier within the Source module,
+      # e.g. Vanity::Source::MySource).
+      def load_sources(path = File.dirname(__FILE__) + "/sources")
+        Dir["#{path}/*.rb"].each do |file|
+          id = File.basename(file, ".rb")
+          fail "Source #{id} already loaded" if all[id]
+          load file
+          klass = Source.const_get(id.camelize)
+          all[id] = klass.new
+          logger.info "Loaded source #{id}: #{klass}"
+        end
+      end
+    end
+
+    # Returns the display name for this source.
+    #
+    # Default implementation uses the class name, e.g Source::OneUp becomes "One
+    # Up".
+    def name
+      self.class.name.demodulize.titleize
+    end
+
+    # Returns additional information about this source.
+    #
+    # A good description helps the user find this source and decide whether or
+    # not to use it.
+    def description
+    end
+
+    # This method returns a hash with two values:
+    # * inputs -- HTML fragment for a setup form
+    # * notes -- HTML fragment for setup notes
+    def display
+      {}
+    end
+
+    # Called to setup a new collector with parameters from the HTML form (see
+    # #display). If there are any missing values, report them when #validate is
+    # called.
+    def setup(context, params)
+    end
+
+    # Called to validate the collector. If there are any error, raise an
+    # exception. A good error message will help the user understand which value
+    # is missing or invalid and how to correct that.
+    def validate(context)
+    end
+
+    # Called to register a Webhook (for sources that need it)
+    def register(context, url)
+    end
+
+    # Called to update the collector. This method will be called periodically
+    # with a context and a block. When triggered by a Webhook, it will be called
+    # with context, Request and a block. It can yield to the block any number of
+    # times with any combination of the supported named arguments for updating
+    # the collector.
+    def update(context, request, &block)
+    end
+
+    # Called to unregister a Webhook (for sources that don't need it).
+    def unregister(context, url)
+    end
+
+    # Returns meta-data to be displayed alongside any other data. This method
+    # should return an array of hashes, each with the keys title (optional),
+    # text and url (optional). Good meta-data provides timely and relevant
+    # information that is not available in the raw data.
+    def meta(context)
+      []
+    end
+
+    # Logger. Dump messages that can help with troubleshooting.
+    def logger
+      self.class.logger
+    end
+  end
+end

data/lib/vanity/sources/ruby_gems.rb

@@ -0,0 +1,62 @@
+
+module Vanity
+  module Source
+    # Track activity (downloads and releases) of a Ruby Gem from rubygems.org.
+    class RubyGems
+      include Vanity::Source
+
+      INPUTS = <<-HTML
+        <label>Gem name <input type="text" name="source[gem_name]" size="30"></label>
+      HTML
+
+      NOTES = <<-HTML
+        Gem names are case sensitive
+      HTML
+
+      def description
+        "Tracks activity (downloads and releases) of a Ruby Gem from rubygems.org"
+      end
+
+      def display
+        { :inputs=>INPUTS, :notes=>NOTES }
+      end
+
+      def setup(context, params)
+        gem_name = params["gem_name"].to_s.strip
+        context["name"] = "RubyGems: #{gem_name}"
+        context["columns"] = [{ id: "downloads", label: "Downloads" }]
+        context["gem_name"] = gem_name
+      end
+
+      def validate(context)
+        raise "Missing gem name" if context["gem_name"].blank?
+      end
+
+      def update(context, webhook)
+        uri = URI.parse("http://rubygems.org/api/v1/gems/#{URI.escape context["gem_name"]}.json")
+        response = Net::HTTP.get_response(uri)
+        case response
+        when Net::HTTPOK
+          json = JSON.parse(response.body)
+          context["version"] = json["version"]
+          context.update json.slice(*%w{homepage_uri project_uri info authors info})
+          current, previous = json["downloads"], context["downloads"] 
+          yield :inc=>{ :downloads=>(current - previous) } if previous && current > previous
+          context["downloads"] = current
+        when Net::HTTPNotFound
+          raise "Could not find the Gem \"#{context["gem_name"]}\""
+        end
+      end
+
+      def meta(context)
+        [ { title: "Project", text: context["gem_name"], url: context["homepage_uri"] || context["project_uri"] },
+          { text: context["info"] },
+          { title: "Version", text: context["version"] },
+          { title: "Authors", text: context["authors"] },
+          { title: "Downloads", text: context["downloads"] },
+          { title: "Source", text: "RubyGems", url: context["project_uri"] } ]
+      end
+
+    end
+  end
+end

data/vanity-source.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |spec|
+  spec.name           = "vanity-source"
+  spec.version        = "0.3"
+  spec.author         = "Assaf Arkin"
+  spec.email          = "assaf@labnotes.org"
+  spec.homepage       = "http://vanitydash.com"
+  spec.summary        = "Data sources for metrics and events"
+
+  spec.files          = Dir["{bin,lib,test}/**/*", "CHANGELOG", "MIT-LICENSE", "README.rdoc", "Rakefile", "Gemfile", "vanity-source.gemspec"]
+
+  spec.has_rdoc         = true
+  spec.extra_rdoc_files = "README.rdoc", "CHANGELOG"
+  spec.rdoc_options     = "--title", "Vanity::Source #{spec.version}", "--main", "README.rdoc",
+                          "--webcvs", "http://github.com/assaf/#{spec.name}"
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification 
+name: vanity-source
+version: !ruby/object:Gem::Version 
+  hash: 13
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  version: "0.3"
+platform: ruby
+authors: 
+- Assaf Arkin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-11 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: assaf@labnotes.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- CHANGELOG
+files: 
+- lib/vanity/source.rb
+- lib/vanity/sources/ruby_gems.rb
+- CHANGELOG
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- Gemfile
+- vanity-source.gemspec
+has_rdoc: true
+homepage: http://vanitydash.com
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --title
+- Vanity::Source 0.3
+- --main
+- README.rdoc
+- --webcvs
+- http://github.com/assaf/vanity-source
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Data sources for metrics and events
+test_files: []
+