mingle_events 0.0.4

data/lib/mingle_events/feed/element_support.rb

@@ -0,0 +1,19 @@
+module MingleEvents
+  module Feed
+    
+    # Provides some helpers for pulling values from Nokogiri Elems
+    module ElementSupport
+    
+      def element_text(parent_element, element_name, optional = false)
+        element = parent_element.at(".//#{element_name}")
+        if optional && element.nil?
+          nil
+        else
+          element.inner_text
+        end
+      end
+    
+    end
+    
+  end
+end

data/lib/mingle_events/feed/entry.rb

@@ -0,0 +1,96 @@
+module MingleEvents
+  module Feed
+  
+    # A Ruby wrapper around an Atom entry, particularly an Atom entry
+    # representing an event in Mingle.
+    class Entry
+      
+      # Construct with the wrapped Nokogiri Elem for the entry
+      def initialize(entry_element)
+        @entry_element = entry_element
+      end
+  
+      # The raw entry XML from the Atom feed
+      def raw_xml
+        @raw_xml ||= @entry_element.to_s
+      end
+  
+      # The Atom entry's id value. This is the one true identifier for the entry,
+      # and therefore the event.
+      def entry_id
+        @entry_id ||= @entry_element.at('id').inner_text
+      end
+      alias :event_id :entry_id
+  
+      # The Atom entry's title
+      def title
+        @title ||= @entry_element.at('title').inner_text
+      end
+  
+      # The time at which entry was created, i.e., the event was triggered
+      def updated
+        @updated ||= Time.parse(@entry_element.at('updated').inner_text)
+      end
+  
+      # The user who created the entry (triggered the event), i.e., changed project data in Mingle
+      def author 
+        @author ||= Author.new(@entry_element.at('author'))
+      end
+    
+      # The set of Atom categoies describing the entry
+      def categories
+        @categories ||= @entry_element.search('category').map do |category_element|
+          Category.new(category_element.attribute('term').text, category_element.attribute('scheme').text)
+        end
+      end
+  
+      # Whether the entry/event was sourced by a Mingle card
+      def card?
+        categories.any?{|c| c == Category::CARD}
+      end
+  
+      # The number of the card that sourced this entry/event. If the entry is not a card event
+      # an error will be thrown. The source of this data is perhaps not so robust and we'll need
+      # to revisit this in the next release of Mingle.
+      def card_number
+        raise "You cannot get the card number for an event that is not sourced by a card!" unless card?
+        @card_number ||= parse_card_number
+      end
+      
+      # The version number of the card or page that was created by this event. (For now, only 
+      # working with cards.)
+      def version
+        @version ||= CGI.parse(URI.parse(card_version_resource_uri).query)['version'].first.to_i
+      end
+  
+      # The resource URI for the card version that was created by this event. Throws error if not card event.
+      def card_version_resource_uri
+        raise "You cannot get card version data for an event that is not sourced by a card!" unless card?      
+        @card_version_resource_uri ||= parse_card_version_resource_uri
+      end
+  
+      def to_s
+        "Entry[entry_id=#{entry_id}, updated=#{updated}]"
+      end
+  
+      private
+  
+      def parse_card_number
+        card_number_element = @entry_element.at(
+          "link[@rel='http://www.thoughtworks-studios.com/ns/mingle#event-source'][@type='application/vnd.mingle+xml']"
+        )
+        # TODO: improve this bit of parsing :)
+        card_number_element.attribute('href').text.split('/').last.split('.')[0..-2].join.to_i
+      end
+  
+      def parse_card_version_resource_uri
+        card_number_element = @entry_element.at(
+          "link[@rel='http://www.thoughtworks-studios.com/ns/mingle#version'][@type='application/vnd.mingle+xml']"
+        )
+        card_number_element.attribute('href').text
+      end
+  
+    end
+    
+  end
+end

data/lib/mingle_events/feed/page.rb

@@ -0,0 +1,61 @@
+module MingleEvents
+  module Feed
+  
+    # A page of Atom events. I.e., *not* a Mingle page. Most users of this library
+    # will not use this class to access the Mingle Atom feed, but will use the 
+    # ProjectFeed class which handles paging transparently.
+    class Page
+  
+      attr_accessor :url
+    
+      def initialize(url, mingle_access)
+        @url = url
+        @mingle_access = mingle_access
+      end
+  
+      def entries
+        @entries ||= page_as_document.search('feed/entry').map do |entry_element|
+          Entry.new(entry_element)
+        end
+      end
+  
+      def next
+        next_url_element = page_as_document.at("feed/link[@rel='next']")
+        if next_url_element.nil?
+          nil
+        else
+          Page.new(next_url_element.attribute('href').text, @mingle_access)
+        end
+      end
+    
+      def previous
+        previous_url_element = page_as_document.at("feed/link[@rel='previous']")
+        if previous_url_element.nil?
+          nil
+        else
+          Page.new(previous_url_element.attribute('href').text, @mingle_access)
+        end
+      end
+    
+      def archived?
+        URI.parse(url).query && url == page_as_document.at("feed/link[@rel='self']").attribute('href').text
+      end
+    
+      def closest_archived_page
+        if archived? 
+          self
+        else
+          self.next
+        end
+      end
+  
+      private    
+  
+      def page_as_document
+        @page_as_document ||= Nokogiri::XML(@mingle_access.fetch_page(@url))
+      end
+    
+    end
+    
+  end
+end

data/lib/mingle_events/http_error.rb

@@ -0,0 +1,26 @@
+module MingleEvents
+  
+  class HttpError < StandardError
+    
+    attr_reader :response, :requested_location, :additional_context
+    
+    def initialize(response, requested_location, additional_context = nil)
+      super(%{
+        Unable to retrieve 200 response from URI: <#{requested_location}>!
+        HTTP Code: #{response.code}
+        Body: #{response.body}
+        #{additional_context.nil? ? "" : additional_context}
+      })
+      @response = response
+      @requested_location = requested_location
+      @additional_context = additional_context
+    end
+    
+    def not_found?
+      # has to be a better way to do this!!
+      response.class == Net::HTTPNotFound
+    end
+    
+  end
+
+end

data/lib/mingle_events/mingle_basic_auth_access.rb

@@ -0,0 +1,71 @@
+module MingleEvents 
+  
+  # Supports fetching of Mingle resources using HTTP basic auth.
+  # Please only use this class to access resources over HTTPS so
+  # as not to send credentials over plain-text connections.
+  class MingleBasicAuthAccess
+    
+    attr_reader :base_url
+        
+    BASIC_AUTH_HTTP_WARNING = %{     
+WARNING!!!
+It looks like you are using basic authentication over a plain-text HTTP connection. 
+We HIGHLY recommend AGAINST this practice. You should only use basic authentication over
+a secure HTTPS connection. Instructions for enabling HTTPS/SSL in Mingle can be found at
+<http://www.thoughtworks-studios.com/mingle/3.3/help/advanced_mingle_configuration.html>
+WARNING!!
+}
+
+    def initialize(base_url, username, password)
+      @base_url = base_url
+      @username = username
+      @password = password
+    end
+    
+    # Fetch the content at location via HTTP. Throws error if non-200 response.
+    def fetch_page(location) 
+      MingleEvents.log.info("About to fetch #{location}...")
+      rsp = fetch_page_response(location)    
+      case rsp
+      when Net::HTTPSuccess
+        rsp.body
+      when Net::HTTPUnauthorized
+        raise HttpError.new(rsp, location, %{
+If you think you are passing correct credentials, please check 
+that you have enabled Mingle for basic authentication. 
+See <http://www.thoughtworks-studios.com/mingle/3.3/help/configuring_mingle_authentication.html>.})
+      else
+        raise HttpError.new(rsp, location) 
+      end
+    end
+    
+    private
+    
+    def fetch_page_response(location)
+      location = @base_url + location if location[0..0] == '/' 
+            
+      uri = URI.parse(location)
+      http = Net::HTTP.new(uri.host, uri.port)
+      
+      if uri.scheme == 'https'
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      else
+        puts BASIC_AUTH_HTTP_WARNING
+      end
+
+      path = uri.path
+      path += "?#{uri.query}" if uri.query
+      puts "Fetching page at #{path}..."
+      
+      start = Time.now
+      req = Net::HTTP::Get.new(path)
+      req.basic_auth(@username, @password)
+      rsp = http.request(req)
+      puts "...#{Time.now - start}"
+
+      rsp
+    end
+
+  end
+end

data/lib/mingle_events/mingle_oauth_access.rb

@@ -0,0 +1,40 @@
+module MingleEvents 
+  
+  # Client for Mingle's experimental OAuth 2.0 support in 3.0
+  #--
+  # TODO: Update error handling and support of fetching response
+  # objects to that of MingleBasicAuthAccess
+  class MingleOauthAccess
+
+    def initialize(base_url, token)
+      @base_url = base_url
+      @token = token
+    end
+
+    def fetch_page(location)
+      location = @base_url + location if location[0..0] == '/' 
+      
+      uri = URI.parse(location)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      headers = {
+        'Authorization' => %{Token token="#{@token}"}
+      }
+
+      path = uri.path
+      path += "?#{uri.query}" if uri.query
+      puts "Fetching page at #{path}..."
+      
+      start = Time.now
+      response = http.get(path, headers)
+      puts "...#{Time.now - start}"
+
+      # todo: what's the right way to raise on non 200 ?
+      # raise StandardError.new(response.body) unless response == Net::HTTPSuccess
+      
+      response.body
+    end
+
+  end
+end

data/lib/mingle_events/poller.rb

@@ -0,0 +1,32 @@
+module MingleEvents
+  class Poller
+    
+    # Manages a full sweep of event processing across each processing pipeline
+    # configured for specified mingle projects. processors_by_project_identifier should
+    # be a hash where the keys are mingle project identifiers and the values are
+    # lists of event processors.
+    def initialize(mingle_access, processors_by_project_identifier)
+      @mingle_access = mingle_access
+      @processors_by_project_identifier = processors_by_project_identifier
+    end
+
+    # Run a single poll for each project configured with processor(s) and 
+    # broadcast each event to each processor.
+    def run_once(options={})
+      MingleEvents.log.info("MingleEvents::Poller about to poll once...")
+      @processors_by_project_identifier.each do |project_identifier, processors|
+        fetcher = ProjectEventFetcher.new(project_identifier, @mingle_access)
+        fetcher.reset if options[:clean]
+        info_file_for_new_event = fetcher.fetch_latest 
+        while info_file_for_new_event  
+          entry_info = YAML.load(File.new(info_file_for_new_event))
+          entry = Feed::Entry.new(Nokogiri::XML(entry_info[:entry_xml]).at('/entry'))
+          MingleEvents.log.info("About to process event #{entry.entry_id}...")
+          processors.each{|p| p.process_events([entry])}
+          info_file_for_new_event = entry_info[:next_entry_file_path]
+        end
+      end
+    end
+    
+  end
+end

data/lib/mingle_events/processors.rb

@@ -0,0 +1,10 @@
+require 'cgi'
+
+require File.expand_path(File.join(File.dirname(__FILE__), 'processors', 'card_data'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'processors', 'category_filter'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'processors', 'card_type_filter'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'processors', 'http_post_publisher'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'processors', 'pipeline'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'processors', 'puts_publisher'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'processors', 'author_filter'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'processors', 'custom_property_filter'))

data/lib/mingle_events/processors/author_filter.rb

@@ -0,0 +1,62 @@
+module MingleEvents
+  module Processors
+    
+    # Removes all events from stream not triggered by the specified author
+    class AuthorFilter
+    
+      def initialize(spec, mingle_access, project_identifier)
+        unless spec.size == 1
+          raise "Author spec must contain 1 and only 1 piece of criteria (the only legal criteria are each unique identifiers in and of themselves so multiple criteria is not needed.)"
+        end
+        
+        @author_spec = AuthorSpec.new(spec, mingle_access, project_identifier)
+      end
+    
+      def process_events(events)
+        events.select{|event| @author_spec.event_triggered_by?(event)}
+      end
+      
+      class AuthorSpec
+        
+        def initialize(spec, mingle_access, project_identifier)
+          @spec = spec
+          @mingle_access = mingle_access
+          @project_identifier = project_identifier
+        end
+        
+        def event_triggered_by?(event)
+          event.author.uri == author_uri
+        end
+        
+        private 
+        
+        def author_uri
+          lookup_author_uri
+        end
+        
+        def lookup_author_uri
+          team_resource = "/api/v2/projects/#{@project_identifier}/team.xml"
+          @raw_xml ||= @mingle_access.fetch_page(URI.escape(team_resource))
+          @doc ||= Nokogiri::XML(@raw_xml)
+
+          users = @doc.search('/projects_members/projects_member/user').map do |user|
+            {
+              :url => user.attribute('url').inner_text,
+              :login => user.at('login').inner_text,
+              :email => user.at('email').inner_text
+            }
+          end
+          
+          spec_user = users.find do |user|
+            # is this too hacky?
+            user.merge(@spec) == user
+          end
+          
+          spec_user.nil? ? nil : spec_user[:url]
+        end
+        
+      end
+    
+    end
+  end
+end

data/lib/mingle_events/processors/card_data.rb

@@ -0,0 +1,102 @@
+module MingleEvents
+  module Processors
+    
+    # Provides ability to lookup card data, e.g., card's type name, for any
+    # card serving as a source for the stream of events. Implements two interfaces:
+    # the standard event processing interface, handle_events, and also, for_card_event,
+    # which returns of has of card data for the given event. See the project README
+    # for additional information on using this class in a processing pipeline.
+    class CardData
+            
+      def initialize(mingle_access, project_identifier, custom_properties = ProjectCustomProperties.new(mingle_access, project_identifier))
+        @mingle_access = mingle_access
+        @project_identifier = project_identifier
+        @custom_properties = custom_properties
+        @card_data_by_number_and_version = nil
+      end
+      
+      # Capture which events are card events and might require data lookup. The
+      # actual data retrieval is lazy and will only occur as needed.
+      def process_events(events)
+        @card_events = events.select(&:card?)     
+        events      
+      end
+      
+      # Return a hash of data for the card that sourced the passed event. The data
+      # will be for the version of the card that was created by the event and not the 
+      # current state of the card. Currently supported data keys are: :number, :version,
+      # :card_type_name
+      def for_card_event(card_event)
+        if @card_data_by_number_and_version.nil?
+          load_bulk_card_data
+        end
+        key = data_key(card_event.card_number, card_event.version)
+        @card_data_by_number_and_version[key] ||= load_card_data_for_event(card_event)
+      end
+      
+      private
+      
+      def data_key(number, version)
+        "#{number}:#{version}"
+      end
+      
+      def load_bulk_card_data
+        @card_data_by_number_and_version = {}
+        
+        # TODO: figure out max number of card numbers before we have to chunk this up.  or does mingle
+        # figure out how to handle a too-large IN clause?
+        card_numbers = @card_events.map(&:card_number).uniq
+        path = "/api/v2/projects/#{@project_identifier}/cards/execute_mql.xml?mql=WHERE number IN (#{card_numbers.join(',')})"
+        
+        raw_xml = @mingle_access.fetch_page(URI.escape(path))
+        doc = Nokogiri::XML(raw_xml)
+        
+        doc.search('/results/result').map do |card_result|
+          card_number = card_result.at('number').inner_text.to_i
+          card_version = card_result.at('version').inner_text.to_i
+          custom_properties = {}
+          @card_data_by_number_and_version[data_key(card_number, card_version)] = {
+            :number => card_number,
+            :version => card_version,
+            :card_type_name => card_result.at('card_type_name').inner_text,
+            :custom_properties => custom_properties
+          }
+          card_result.children.each do |child|
+            if child.name.index("cp_") == 0
+              custom_properties[@custom_properties.property_name_for_column(child.name)] = 
+                nullable_value_from_element(child)
+            end
+          end
+        end
+      end
+    
+      def load_card_data_for_event(card_event)
+        begin
+          page_xml = @mingle_access.fetch_page(card_event.card_version_resource_uri)
+          doc = Nokogiri::XML(page_xml)
+          custom_properties = {}
+          result = {
+            :number => card_event.card_number,
+            :version => card_event.version,
+            :card_type_name => doc.at('/card/card_type/name').inner_text,
+            :custom_properties => custom_properties
+          }
+          doc.search('/card/properties/property').each do |property|
+            custom_properties[property.at('name').inner_text] = 
+              nullable_value_from_element(property.at('value'))
+          end
+          
+          result
+        rescue HttpError => httpError
+          raise httpError unless httpError.not_found?
+
+        end
+      end
+  
+      def nullable_value_from_element(element)
+        element['nil'] == 'true' ? nil : element.inner_text
+      end
+    end
+    
+  end
+end