powertrack 1.0.0

data/lib/powertrack/rules/rule.rb

@@ -0,0 +1,140 @@
+require 'multi_json'
+
+module PowerTrack
+  # A PowerTrack rule with its components and restrictions.
+  class Rule
+
+    # The maximum length of a rule tag.
+    MAX_TAG_LENGTH = 255
+
+    # The maximum lengh of the value of a standard rule
+    MAX_STD_RULE_VALUE_LENGTH = 1024
+
+    # The maximum lengh of the value of a long rule
+    MAX_LONG_RULE_VALUE_LENGTH = 2048
+
+    # The maximum number of positive terms in a single rule value
+    MAX_POSITIVE_TERMS = 30
+
+    # The maximum number of negative terms in a single rule value
+    MAX_NEGATIVE_TERMS = 50
+
+    attr_reader :value, :tag, :error
+
+    # Builds a new rule based on a value and an optional tag.
+    # By default, the constructor assesses if it's a long rule or not
+    # based on the length of the value. But the 'long' feature can be
+    # explicitly specified with the third parameter.
+    def initialize(value, tag=nil, long=nil)
+      @value = value || ''
+      @tag = tag
+      # check if long is a boolean
+      @long = long == !!long ? long : @value.size > MAX_STD_RULE_VALUE_LENGTH
+      @error = nil
+    end
+
+    # Returns true if the rule is long.
+    def long?
+      @long
+    end
+
+    # Returns true if the rule is valid, false otherwise. The validation error
+    # can be through the error method.
+    def valid?
+      # reset error
+      @error = nil
+
+      [ :too_long_value?,
+        :too_many_positive_terms?,
+        :too_many_negative_terms?,
+        :contains_empty_source?,
+        :contains_negated_or?,
+        :too_long_tag? ].each do |validator|
+
+        # stop when 1 validator fails
+        if self.send(validator)
+          @error = validator.to_s.gsub(/_/, ' ').gsub(/\?/, '').capitalize
+          return false
+        end
+      end
+
+      true
+    end
+
+    # Dumps the rule in a valid JSON format.
+    def to_json
+      MultiJson.encode(to_hash)
+    end
+
+    # Converts the rule in a Hash.
+    def to_hash
+      res = {:value => @value}
+      res[:tag] = @tag unless @tag.nil?
+      res
+    end
+
+    # Converts the rule in a string, the JSON representation of the rule actually.
+    def to_s
+      to_json
+    end
+
+    # Returns true when the rule is equal to the other rule provided.
+    def ==(other)
+      other.class == self.class &&
+        other.value == @value &&
+        other.tag == @tag &&
+        other.long? == self.long?
+    end
+
+    alias eql? ==
+
+    # Returns a hash for the rule based on its components. Useful for using
+    # rules as Hash keys.
+    def hash
+      # let's assume a nil value for @value or @tag is not different from the empty value
+      "v:#{@value},t:#{@tag},l:#{@long}".hash
+    end
+
+    # Returns the maximum length of the rule value according to the type of the
+    # rule (long or standard).
+    def max_value_length
+      long? ? MAX_LONG_RULE_VALUE_LENGTH : MAX_STD_RULE_VALUE_LENGTH
+    end
+
+    protected
+
+    # Is the rule value too long ?
+    def too_long_value?
+      @value.size > max_value_length
+    end
+
+    # Does the rule value contain a forbidden negated OR ?
+    def contains_negated_or?
+      !@value[/\-\w+ OR/].nil? || !@value[/OR \-\w+/].nil?
+    end
+
+    # Does the rule value contain too many positive terms ?
+    def too_many_positive_terms?
+      return false if long?
+      # negative look-behind; see http://www.rexegg.com/regex-disambiguation.html
+      # exclude the OR operator from the terms being counted
+      @value.scan(/(?<!-)(\b[\w:]+|\"[\-\s\w:]+\"\b)/).select { |match| match.first != 'OR' }.size > MAX_POSITIVE_TERMS
+    end
+
+    # Does the rule value contain too many negative terms ?
+    def too_many_negative_terms?
+      return false if long?
+      @value.scan(/(^| )\-(\w|\([^(]*\)|\"[^"]*\")/).size > MAX_NEGATIVE_TERMS
+    end
+
+    # Does the rule value contain an empty source ?
+    def contains_empty_source?
+      !@value[/source\:\s/].nil?
+    end
+
+    # Is the rule tag too long ?
+    def too_long_tag?
+      @tag && @tag.size > MAX_TAG_LENGTH
+    end
+  end
+end

data/lib/powertrack/rules/string_extension.rb

@@ -0,0 +1,9 @@
+require 'powertrack/rules/rule'
+
+# Extend core String class with a rule transformer
+class String
+  # Returns a PowerTrace::Rule instance based on the value of the string.
+  def to_pwtk_rule(tag=nil, long=nil)
+    PowerTrack::Rule.new(self, tag, long)
+  end
+end

data/lib/powertrack/streaming/api.rb

@@ -0,0 +1,64 @@
+module PowerTrack
+  module API
+    # Adds many rules to your PowerTrack stream’s ruleset.
+    #
+    # <tt>POST /rules</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#AddRules
+    def add_rules(*rules)
+      raise NotImplementedError
+    end
+
+    # Adds one rule to your PowerTrack stream’s ruleset.
+    #
+    # <tt>POST /rules</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#AddRules
+    def add_rule(rule)
+      add_rules(rule)
+    end
+
+    # Removes the specified rules from the stream.
+    #
+    # <tt>DELETE /rules</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#DeleteRules
+    def delete_rules(*rules)
+      raise NotImplementedError
+    end
+
+    # Removes the specified rule from the stream.
+    #
+    # <tt>DELETE /rules</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#DeleteRules
+    def delete_rule(rule)
+      delete_rules(rule)
+    end
+
+    # Retrieves all existing rules for a stream.
+    #
+    # <tt>GET /rules</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#ListRules
+    #
+    # Options:
+    # o compressed: [true|false] To demand gzip-compressed response from GNIP
+    #               true by default
+    # o objectify: [true|false] To demand PowerTrack::Rule object as results
+    #              instead of raw JSON. True by default.
+    def list_rules(options=nil)
+      raise NotImplementedError
+    end
+
+    # Establishes a persistent connection to the PowerTrack data stream,
+    # through which the social data will be delivered.
+    #
+    # <tt>GET /track/:stream</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#Stream
+    def track(options=nil)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/powertrack/streaming/data_buffer.rb

@@ -0,0 +1,36 @@
+module PowerTrack
+  # A buffer of data received from PowerTrack. Useful for managing the sequential
+  # chunk of bytes sent of the stream by GNIP and slice them into well-formatted
+  # messages.
+  class DataBuffer
+
+    # The pattern used by GNIP PowerTrack to delimitate a single message.
+    MESSAGE_PATTERN = /^([^\r]*)\r\n/m
+
+    # Builds a new data buffer.
+    def initialize
+      @buffer = ''
+    end
+
+    # Add a chunk of bytes to the buffer and pass the new message(s) extracted
+    # to the block provided.
+    def process(chunk, &block)
+      @buffer.concat(chunk)
+      @buffer.gsub!(MESSAGE_PATTERN) do |match|
+        yield($1.to_s) if block_given?
+        # erase the message
+        ''
+      end
+    end
+
+    # The current size of the buffer.
+    def size
+      @buffer.size
+    end
+
+    # Resets the buffer, therefore losing any bytes received from PowerTrack.
+    def reset!
+      @buffer = ''
+    end
+  end
+end

data/lib/powertrack/streaming/retrier.rb

@@ -0,0 +1,70 @@
+require 'exponential_backoff'
+
+module PowerTrack
+  # A utility class that manges an exponential backoff retry pattern.
+  # Additionally, this king of retrier can be reset or stopped by the code being
+  # retried.
+  class Retrier
+    attr_reader :retries, :max_retries
+
+    # the default minimum number of seconds b/w 2 attempts
+    DEFAULT_MIN_INTERVAL = 1.0
+    # the default maximum number of seconds to wait b/w 2 attempts
+    DEFAULT_MAX_ELAPSED_TIME = 30.0
+    # the default interval multiplier
+    DEFAULT_INTERVAL_MULTIPLIER = 1.5
+    # the default randomize factor
+    DEFAULT_RANDOMIZE_FACTOR = 0.25
+
+    # default options used by a retrier unless others specified at initialization
+    DEFAULT_OPTIONS = {
+      min_interval: DEFAULT_MIN_INTERVAL,
+      max_elapsed_time: DEFAULT_MAX_ELAPSED_TIME,
+      multiplier: DEFAULT_INTERVAL_MULTIPLIER,
+      randomize_factor: DEFAULT_RANDOMIZE_FACTOR
+    }
+
+    # Builds a retrier that will retry a maximum retries number of times.
+    def initialize(max_retries, options=nil)
+      options = DEFAULT_OPTIONS.merge(options || {})
+
+      @max_retries = max_retries
+      @retries = 0
+      @continue = true
+      @backoff = ExponentialBackoff.new(options[:min_interval], options[:max_elapsed_time])
+      @backoff.multiplier = options[:multiplier]
+      @backoff.randomize_factor = options[:randomize_factor]
+    end
+
+    # Resets the retrier.
+    def reset!
+      @retries = 0
+      @backoff.clear
+    end
+
+    # Returns true if the retrier is currently retrying.
+    def retrying?
+      @retries != 0
+    end
+
+    # Stops retrying even after a reset. To be used from the code being retried.
+    def stop
+      @continue = false
+    end
+
+    # Retries the block of code provided according to the configuration of the
+    # retrier.
+    def retry(&block)
+      # TODO: manage exceptions
+      while @continue && @retries < @max_retries
+        res = yield
+        if @continue
+          @retries += 1
+          sleep(@backoff.next_interval)
+        end
+      end
+
+      res
+    end
+  end
+end

data/lib/powertrack/streaming/stream.rb

@@ -0,0 +1,429 @@
+require 'eventmachine'
+require 'em-http-request'
+require 'multi_json'
+require 'void_logger'
+
+require 'powertrack/errors'
+require 'powertrack/streaming/api'
+require 'powertrack/streaming/data_buffer'
+require 'powertrack/streaming/retrier'
+
+module PowerTrack
+  # A PowerTrack stream to be used for both updating the rules and collecting
+  # new messages.
+  class Stream
+    # Includes the PowerTrack Stream API
+    include PowerTrack::API
+    # Includes a logger, void by default
+    include VoidLogger::LoggerMixin
+
+    # The format of the URLs to connect to the various stream services
+    FEATURE_URL_FORMAT = "https://%s:%s/accounts/%s/publishers/%s/streams/track/%s%s.json".freeze
+
+    # The default timeout on a connection to PowerTrack. Can be overriden per call.
+    DEFAULT_CONNECTION_TIMEOUT = 30
+
+    # The default timeout for inactivity on a connection to PowerTrack. Can be
+    # overriden per call.
+    DEFAULT_INACTIVITY_TIMEOUT = 50
+
+    # The default options for using the stream.
+    DEFAULT_STREAM_OPTIONS = {
+      connect_timeout: DEFAULT_CONNECTION_TIMEOUT,
+      inactivity_timeout: DEFAULT_INACTIVITY_TIMEOUT,
+      # use a client id if you want to leverage the Backfill feature
+      client_id: nil
+    }
+
+    DEFAULT_OK_RESPONSE_STATUS = 200
+
+    # the patterns used to identify the various types of message received from GNIP
+    # everything else is an activity
+    HEARTBEAT_MESSAGE_PATTERN = /\A\s*\z/
+    SYSTEM_MESSAGE_PATTERN = /\A\s*\{\s*"(info|warn|error)":/mi
+
+    attr_reader :username, :account_name, :data_source, :label
+
+    def initialize(username, password, account_name, data_source, label, options=nil)
+      @username = username
+      @password = password
+      @account_name = account_name
+      @data_source = data_source
+      @label = label
+      @options = DEFAULT_STREAM_OPTIONS.merge(options || {})
+      @client_id = @options[:client_id]
+    end
+
+    # Adds many rules to your PowerTrack stream’s ruleset.
+    #
+    # <tt>POST /rules</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#AddRules
+    def add_rules(*rules)
+      # flatten the rules in case it was provided as an array
+      make_rules_request(:post, body: MultiJson.encode('rules' => rules.flatten), ok: 201)
+    end
+
+    # Removes the specified rules from the stream.
+    #
+    # <tt>DELETE /rules</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#DeleteRules
+    def delete_rules(*rules)
+      # flatten the rules in case it was provided as an array
+      make_rules_request(:delete, body: MultiJson.encode('rules' => rules.flatten))
+    end
+
+    DEFAULT_LIST_RULES_OPTIONS = {
+      compressed: true,
+      objectify: true
+    }.freeze
+
+    # Retrieves all existing rules for a stream.
+    #
+    # Returns an array of PowerTrack::Rule objects when the response permits so.
+    #
+    # <tt>GET /rules</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#ListRules
+    def list_rules(options=nil)
+      options = DEFAULT_LIST_RULES_OPTIONS.merge(options || {})
+      res = make_rules_request(:get, headers: gzip_compressed_header(options[:compressed]))
+
+      # return Rule objects when required and feasible/appropriate
+      if options[:objectify] &&
+         res.is_a?(Hash) &&
+         (rules = res['rules']).is_a?(Array) &&
+         rules.all? { |rule| rule.is_a?(Hash) && rule.key?('value') }
+        rules.map { |rule| PowerTrack::Rule.new(rule['value'], rule['tag']) }
+      else
+        res
+      end
+    end
+
+    DEFAULT_TRACK_OPTIONS = {
+      # receive GZip-compressed payloads ?
+      compressed: true,
+      # max number of retries after a disconnection
+      max_retries: 3,
+      # advanced options to configure exponential backoff used for retries
+      backoff: nil,
+      # max number of seconds to wait for last message handlers to complete
+      stop_timeout: 10,
+      # pass message in raw form (JSON formatted string) instead of JSON-decoded
+      # Ruby objects to message handlers
+      raw: false,
+      # called for each message received, except heartbeats
+      on_message: nil,
+      # called for each activity received
+      on_activity: nil,
+      # called for each system message received
+      on_system: nil,
+      # called for each heartbeat received
+      on_heartbeat: nil,
+      # called periodically to detect if the tracked has to be closed
+      close_now: nil
+    }.freeze
+
+    # Establishes a persistent connection to the PowerTrack data stream,
+    # through which the social data will be delivered.
+    #
+    # <tt>GET /track/:stream</tt>
+    #
+    # See http://support.gnip.com/apis/powertrack/api_reference.html#Stream
+    def track(options=nil)
+      options = DEFAULT_TRACK_OPTIONS.merge(options || {})
+      retrier = PowerTrack::Retrier.new(options[:max_retries])
+      handle_api_response(*retrier.retry { track_once(options, retrier) })
+    end
+
+    private
+
+    # Returns the fully-qualified domain name of a GNIP PowerTrack server
+    # based on a hostname.
+    def gnip_server_name(hostname)
+      "%s.gnip.com" % [ hostname ]
+    end
+
+    # Returns the port used by GNIP PowerTrack servers.
+    def gnip_server_port
+      '443'
+    end
+
+    # Returns the URL of the stream for a given feature.
+    def feature_url(hostname, feature=nil)
+      feature = feature ? "/#{feature}" : ''
+      _url = FEATURE_URL_FORMAT %
+              [ gnip_server_name(hostname),
+                gnip_server_port,
+                @account_name,
+                @data_source,
+                @label,
+                feature ]
+
+      _url += "?client=#{@client_id}" if @client_id
+
+      _url
+    end
+
+    # Returns the HTTP header that turns on GZip-based compression if required.
+    # Each call returns a new hash which can be safely modified by the caller.
+    def gzip_compressed_header(compressed)
+      compressed ? { 'accept-encoding' => 'gzip, compressed' } : {}
+    end
+
+    # Returns the authorization header to join to the HTTP request.
+    def auth_header
+      { 'authorization' => [ @username, @password ] }
+    end
+
+    # Returns the HTTP headers common to each valid PowerTrack connection.
+    # Each call returns a new hash which can be safely modified by the caller.
+    def connection_headers
+      { connect_timeout: @options[:connect_timeout],
+        inactivity_timeout: @options[:inactivity_timeout] }
+    end
+
+    # Opens a new connection to GNIP PowerTrack.
+    def connect(hostname, feature=nil)
+      url = feature_url(hostname, feature)
+      EventMachine::HttpRequest.new(url, connection_headers)
+    end
+
+    # Returns the HTTP headers common to each valid PowerTrack request.
+    # Each call returns a new hash which can be safely modified by the caller.
+    def common_req_headers
+      { 'accept' => 'application/json',
+        'content-type' => 'application/json; charset=utf-8',
+        :redirects => 3 }.merge(auth_header)
+    end
+
+    # Returns the HTTP headers common to each valid /rules request.
+    # Each call returns a new hash which can be safely modified by the caller.
+    def rules_req_headers
+      common_req_headers
+    end
+
+    # Parses a JSON-formatted body received as the response of a PowerTrack API
+    # request.
+    #
+    # Returns nil when the body is empty, the Ruby object decoded from the
+    # JSON-formatted body otherwise.
+    #
+    # If the parsing fails, returns the value returned by the given block which
+    # is called with the textual body as a single argument. If no block id,
+    # return the textual body initially received.
+    def parse_json_body(body, &block)
+      body = (body || '').strip
+      begin
+        body == '' ? nil : MultiJson.load(body)
+      rescue
+        if block_given?
+          yield($!)
+        else
+          body
+        end
+      end
+    end
+
+    # Returns an appropriate return value or exception according to the response
+    # obtained on an API request.
+    def handle_api_response(status, error, body, ok=DEFAULT_OK_RESPONSE_STATUS)
+      case status
+      when nil
+        # connection issue
+        raise PowerTrack::ConnectionError.new(error)
+      when ok
+        # successful call: return the body unless there isn't any
+        return nil if body.nil?
+
+        parse_json_body(body) do |exception|
+          # invalid JSON response
+          raise PowerTrack::InvalidResponseError.new(ok, exception.message, body)
+        end
+      else
+        # specified response status
+        raise PowerTrack::WithStatusPowerTrackError.build(status, error, parse_json_body(body))
+      end
+    end
+
+    DEFAULT_RULES_REQUEST_OPTIONS = {
+      ok: DEFAULT_OK_RESPONSE_STATUS,
+      headers: {},
+      body: nil
+    }
+
+    # Makes a rules-related request with a specific HTTP verb and a few options.
+    # Returns the response if successful or an exception if the request failed.
+    def make_rules_request(verb, options=nil)
+      options = DEFAULT_RULES_REQUEST_OPTIONS.merge(options || {})
+      resp_status = nil
+      resp_error = nil
+      resp_body = nil
+
+      EM.run do
+        con = connect('api', 'rules')
+        http = con.setup_request(verb,
+                 head: rules_req_headers.merge(options[:headers]),
+                 body: options[:body])
+
+        http.errback do
+          resp_error = http.error
+          EM.stop
+        end
+
+        http.callback do
+          resp_status = http.response_header.status
+          resp_error = http.error
+          resp_body = http.response
+          EM.stop
+        end
+      end
+
+      handle_api_response(resp_status, resp_error, resp_body, options[:ok])
+    end
+
+    # Returns the type of message received on the stream, nil when the type
+    # cannot be identified.
+    def message_type(message)
+      case message
+      when HEARTBEAT_MESSAGE_PATTERN then :heartbeat
+      when SYSTEM_MESSAGE_PATTERN then :system
+      else
+        :activity
+      end
+    end
+
+    # Returns the HTTP headers for each valid /track request.
+    # Each call returns a new hash which can be safely modified by the caller.
+    def track_req_headers(compressed)
+      common_req_headers.merge('connection' => 'keep-alive')
+                        .merge(gzip_compressed_header(compressed))
+    end
+
+    # Connects to the /track endpoint and manages reconnections when being
+    # disconnected.
+    def track_once(options, retrier)
+      logger.info "Starting tracker for retry ##{retrier.retries}..."
+      stop_timeout = options[:stop_timeout]
+      on_heartbeat = options[:on_heartbeat]
+      on_message = options[:on_message]
+      on_activity = options[:on_activity]
+      close_now = options[:close_now] || lambda { false }
+
+      buffer = PowerTrack::DataBuffer.new
+      closed = false
+      disconnected = false
+      resp_status = DEFAULT_OK_RESPONSE_STATUS
+      resp_error = nil
+      resp_body = nil
+
+      EM.run do
+        logger.info "Starting the reactor..."
+        con = connect('stream')
+        http = con.get(head: track_req_headers(options[:compressed]))
+
+        # polls to see if the connection should be closed
+        close_watcher = EM.add_periodic_timer(1) do
+          # exit if required
+          if close_now.call
+            logger.info "Time to close the tracker"
+            closed = true
+            close_watcher.cancel
+            con.close
+          end
+        end
+
+        # simulate periodic disconnections
+        if options[:fake_disconnections]
+           EM.add_timer(rand(options[:fake_disconnections])) do
+             con.close
+           end
+        end
+
+        http.stream do |chunk|
+          # ignore data if already disconnected, thus avoiding synchronizing the
+          # buffer. Nevertheless, this should never happen...
+          # TODO: log a warning if it happens
+
+          if disconnected
+            logger.warn "Message received while already disconnected"
+            next
+          end
+
+          # reset retries when some (valid) data are received
+          if retrier.retrying?
+            logger.info "Resetting retries..."
+            retrier.reset!
+          end
+
+          # process the chunk
+          buffer.process(chunk) do |raw|
+            logger.debug "New message received"
+            EM.defer do
+              # select the right message handler(s) according to the message type
+              m_type = message_type(raw)
+
+              if m_type == :heartbeat
+                on_heartbeat.call if on_heartbeat
+              else
+                # JSON decoding if required
+                message = options[:raw] ? raw : MultiJson.decode(raw)
+
+                on_message.call(message) if on_message
+
+                case m_type
+                when :system then on_system.call(message) if on_system
+                when :activity then on_activity.call(message) if on_activity
+                end
+              end
+
+              # TODO: manage exceptions at this level
+            end
+          end
+        end
+
+        # reconnection on error
+        reconnect_cb = lambda do |http_client|
+          logger.info "Disconnected after #{retrier.retries} retries"
+          disconnected = true
+
+          if closed
+            # close immediately if required
+            wait_til_defers_finish_and_stop(stop_timeout)
+            # tell the retrier the tracking is over
+            retrier.stop
+          else
+            # cancel the periodic close watcher
+            close_watcher.cancel
+
+            resp_status = http_client.response_header.status || DEFAULT_OK_RESPONSE_STATUS
+            resp_error = http_client.error
+            resp_body = http_client.response
+            wait_til_defers_finish_and_stop(stop_timeout)
+          end
+        end
+
+        http.callback(&reconnect_cb)
+        http.errback(&reconnect_cb)
+      end
+
+      [ resp_status, resp_error, resp_body ]
+    end
+
+    # Waits for all the deferrable threads to complete, then stops the reactor.
+    def wait_til_defers_finish_and_stop(timeout)
+      # wait for defers to terminate but no more than timeout...
+      start = Time.now
+      defers_waiter = EM.add_periodic_timer(0.2) do
+        logger.info "Waiting for defers..."
+        if EM.defers_finished? || (Time.now - start) > timeout
+          defers_waiter.cancel
+        end
+      end
+    ensure
+      logger.info "Stopping the reactor..."
+      EM.stop
+    end
+  end
+end