birdgrinder 0.1.0.0

data/lib/bird_grinder/console.rb

@@ -0,0 +1,42 @@
+require 'readline'
+require 'irb'
+require 'irb/completion'
+
+module BirdGrinder
+  # A simple controller for bringing up an IRB instance with the birdgrinder
+  # environment pre-loaded.
+  class Console
+    
+    # Define code here that you want available at the IRB
+    # prompt automatically.
+    module BaseExtensions
+      include BirdGrinder::Loggable    
+    end
+    
+    def initialize
+      setup_irb
+    end
+    
+    # Include the base extensions in our top level binding
+    # so they can be accessed at the prompt.
+    def setup_irb
+      # This is a bit hacky, surely there is a better way?
+      # e.g. some way to specify which scope irb runs in.
+      eval("include BirdGrinder::Console::BaseExtensions", TOPLEVEL_BINDING)
+    end
+    
+    # Actually starts IRB
+    def run
+      puts "Loading BirdGrinder Console..."
+      # Trick IRB into thinking it has no arguments.
+      ARGV.replace []
+      IRB.start
+    end
+    
+    # Starts up a new IRB instance with access to birdgrinder features.
+    def self.run
+      self.new.run
+    end
+    
+  end
+end

data/lib/bird_grinder/exceptions.rb

@@ -0,0 +1,6 @@
+module BirdGrinder
+  # A generic error related to anything broken in BirdGrinder
+  class Error              < StandardError; end
+  # An error notifying you that username and password are missing from config/settings.yml
+  class MissingAuthDetails < Error; end
+end

data/lib/bird_grinder/loader.rb

@@ -0,0 +1,5 @@
+BirdGrinder::Loader.class_eval do
+  # Adds a hook so we can trigger events
+  # once the client is running.
+  define_hook :once_running
+end

data/lib/bird_grinder/queue_processor.rb

@@ -0,0 +1,86 @@
+require 'em-redis'
+
+module BirdGrinder
+  # When running, the queue processor makes it possible to
+  # use a redis queue queue up and dispatch tweets and direct
+  # messages from external processes. This is useful since
+  # it makes it easy to have 1 outgoing source of tweets,
+  # triggered from any external application. Included in
+  # examples/bird_grinder_client.rb is a simple example
+  # client which uses redis to queue tweets and dms.
+  class QueueProcessor
+    
+    cattr_accessor :polling_delay, :namespace, :action_whitelist
+    # 10 seconds if queue is empty.
+    self.polling_delay    = 10
+    self.namespace        = 'bg:messages'
+    self.action_whitelist = ["tweet", "dm"]
+    
+    is :loggable
+    
+    attr_accessor :tweeter
+    
+    # Initializes redis and our tweeter.
+    def initialize
+      @tweeter = Tweeter.new(self)
+      @redis   = EM::P::Redis.connect
+    end
+    
+    # Attempts to pop and process an item from the front of the queue.
+    # Also, it will queue up the next check - if current item was empty,
+    # it will happen after a specified delay otherwise it will check now.
+    def check_queue
+      logger.debug "Checking Redis for outgoing messages"
+      @redis.lpop(@@namespace) do |res|
+        if res.blank?
+          logger.debug "Empty queue, scheduling check in #{@@polling_delay} seconds"
+          schedule_check(@@polling_delay)
+        else
+          logger.debug "Got item, processing and scheduling next check"
+          begin
+            handle_action Yajl::Parser.parse(res)
+          rescue Yajl::ParseError => e
+            logger.error "Couldn't parse json: #{e.message}"
+          end
+          schedule_check
+        end
+      end
+    end
+    
+    # Check the queue. 
+    #
+    # @param [Integer, nil] time the specified delay. If nil, it will be done now.
+    def schedule_check(time = nil)
+      if time == nil
+        check_queue
+      else
+        EventMachine.add_timer(@@polling_delay) { check_queue }
+      end
+    end
+    
+    # Processes a given action action - calling handle action
+    # if present.
+    def process_action(res)
+      if res.is_a?(Hash) && res["action"].present?
+        handle_action(res["action"], res["arguments"])
+      end
+    end
+    
+    # Calls the correct method on the tweeter if present
+    # and in the whitelist. logs and caught argument errors.
+    def handle_action(action, args)
+      args ||= []
+      @tweeter.send(action, *[*args]) if @@action_whitelist.include?(action)
+    rescue ArgumentError
+      logger.warn "Incorrect call for #{action} with arguuments #{args}"
+    end
+    
+    # Starts the queue processor with an initial check.
+    # raises an exception if the reactor isn't running.
+    def self.start
+      raise "EventMachine must be running" unless EM.reactor_running?
+      new.check_queue
+    end
+    
+  end
+end

data/lib/bird_grinder/tweeter/search.rb

@@ -0,0 +1,71 @@
+module BirdGrinder
+  class Tweeter
+    class Search
+      is :loggable
+      
+      # 30 seconds between searches
+      DELAY_SEARCH = 30
+      
+      cattr_accessor :search_base_url
+      @@search_base_url = "http://search.twitter.com/"
+      
+      def initialize(parent)
+        logger.debug "Initializing Search"
+        @parent = parent
+      end
+      
+      # Uses the twitter search api to look up a
+      # given query. If :repeat is given, it will
+      # repeat indefinitely, getting only new messages each
+      # iteration.
+      #
+      # @param [String] query what you wish to search for
+      # @param [Hash] opts options for the query string (except for :repeat)
+      # @option opts [Boolean] :repeat if present, will repeat indefinitely.
+      def search_for(query, opts = {})
+        logger.info "Searching for #{query.inspect}"
+        opts = opts.dup
+        repeat = opts.delete(:repeat)
+        perform_search(query, opts) do |response|
+          if repeat && response.max_id?
+            logger.info "Scheduling next search iteration for #{query.inspect}"
+            EM.add_timer(DELAY_SEARCH) do
+              opts[:repeat]   = true
+              opts[:since_id] = response.max_id
+              search_for(query, opts)
+            end
+          end
+        end
+      end
+      
+      protected
+      
+      def perform_search(query, opts = {}, &blk)
+        url = search_base_url / "search.json"
+        query_opts = opts.stringify_keys
+        query_opts["q"] = query.to_s.strip
+        query_opts["rpp"] ||= 100
+        http = EventMachine::HttpRequest.new(url).get(:query => query_opts)
+        http.callback do
+          response = parse_response(http)
+          blk.call(response) if blk.present?
+          if response.results?
+            response.results.each do |result|
+              result.type = :search
+              @parent.delegate.receive_message(:incoming_search, result)
+            end
+          end
+        end
+      end
+      
+      def parse_response(http)
+        response = Yajl::Parser.parse(http.response)
+        response.to_nash.normalized
+      rescue Yajl::ParseError => e
+        logger.error "Couldn't parse search response, error:\n#{e.message}"
+        BirdGrinder::Nash.new
+      end
+      
+    end
+  end
+end

data/lib/bird_grinder/tweeter/stream_processor.rb

@@ -0,0 +1,46 @@
+module BirdGrinder
+  class Tweeter
+    class StreamProcessor
+      is :loggable
+      
+      def initialize(parent, stream_name)
+        @parent = parent
+        @stream_name = stream_name.to_sym
+        setup_parser
+      end
+      
+      def receive_chunk(chunk)
+        @parser << chunk
+      rescue Yajl::ParseError => e
+        logger.error "Couldn't parse json: #{e.message}"
+      end
+      
+      def process_stream_item(json)
+        return if !json.is_a?(Hash)
+        processed = json.to_nash.normalized
+        processed.type = lookup_type_for_steam_response(processed)
+        processed.streaming_source = @stream_name
+        logger.info "Processing Stream Tweet #{processed.id}: #{processed.text}"
+        @parent.delegate.receive_message(:incoming_stream, processed)
+      end
+   
+      protected
+      
+      def lookup_type_for_steam_response(response)
+        if response.delete?
+          :delete
+        elsif response.limit?
+          :limit
+        else
+          :tweet
+        end
+      end
+      
+      def setup_parser
+        @parser = Yajl::Parser.new
+        @parser.on_parse_complete = method(:process_stream_item)
+      end
+      
+    end
+  end
+end

data/lib/bird_grinder/tweeter/streaming.rb

@@ -0,0 +1,74 @@
+require 'bird_grinder/tweeter/stream_processor'
+
+module BirdGrinder
+  class Tweeter
+    # Basic support for the twitter streaming api. Provides
+    # access to sample, filter, follow and track. Note that
+    # it will dispatch messages as :incoming_stream, with
+    # options.streaming_source set to the stream origin.
+    class Streaming
+      is :loggable
+      
+      cattr_accessor :streaming_base_url, :api_version
+      self.streaming_base_url = "http://stream.twitter.com/"
+      self.api_version        = 1
+      
+      attr_accessor  :parent
+      
+      def initialize(parent)
+        @parent = parent
+        logger.debug "Initializing Streaming Support"
+      end
+      
+      # Start processing the sample stream
+      #
+      # @param [Hash] opts extra options for the query
+      def sample(opts = {})
+        get(:sample, opts)
+      end
+      
+      # Start processing the filter stream
+      #
+      # @param [Hash] opts extra options for the query
+      def filter(opts = {})
+        get(:filter, opts)
+      end
+      
+      # Start processing the filter stream with a given follow
+      # argument.
+      #
+      # @param [Array] args what to follow, joined with ","
+      def follow(*args)
+        opts = args.extract_options!
+        opts[:follow] = args.join(",")
+        opts[:path] = :filter
+        get(:follow, opts)
+      end
+      
+      # Starts tracking a specific query.
+      # 
+      # @param [Hash] opts extra options for the query
+      def track(query, opts = {})
+        opts[:track] = query
+        opts[:path] = :filter
+        get(:track, opts)
+      end
+      
+      protected
+      
+      def get(name, opts = {}, attempts = 0)
+        logger.debug "Getting stream #{name} w/ options: #{opts.inspect}"
+        path = opts.delete(:path)
+        processor = StreamProcessor.new(@parent, name)
+        http_opts = {
+          :on_response => processor.method(:receive_chunk),
+          :head        => {'Authorization' => @parent.auth_credentials}
+        }
+        http_opts[:query] = opts if opts.present?
+        url = streaming_base_url / api_version.to_s / "statuses" / "#{path || name}.json"
+        http = EventMachine::HttpRequest.new(url).get(http_opts)
+      end
+      
+    end
+  end
+end

data/lib/bird_grinder/tweeter.rb

@@ -0,0 +1,234 @@
+require 'uri'
+
+module BirdGrinder
+  # An asynchronous, delegate-based twitter client that uses
+  # em-http-request and yajl on the backend. It's built to be fast,
+  # minimal and easy to use.
+  #
+  # The delegate is simply any class - the tweeter will attempt to
+  # call receive_message([Symbol], [BirdGrinder::Nash]) every time
+  # it processes a message / item of some kind. This in turn makes
+  # it easy to process items. Also, it will dispatch both
+  # incoming (e.g. :incoming_mention, :incoming_direct_message) and
+  # outgoing (e.g. :outgoing_tweet) events.
+  #
+  # It has support the twitter search api (via #search) and the currently-
+  # alpha twitter streaming api (using #streaming) built right in.
+  class Tweeter
+    is :loggable, :delegateable
+    
+    require 'bird_grinder/tweeter/streaming'
+    require 'bird_grinder/tweeter/search'
+    
+    VALID_FETCHES = [:direct_messages, :mentions]
+    
+    cattr_accessor :api_base_url
+    self.api_base_url = "http://twitter.com/"
+      
+    attr_reader :auth_credentials
+        
+    # Initializes the tweeter with a given delegate. It will use
+    # username and password from your settings file for authorization
+    # with twitter.
+    #
+    # @param [Delegate] delegate the delegate class
+    def initialize(delegate)
+      check_auth!
+      @auth_credentials = [BirdGrinder::Settings.username, BirdGrinder::Settings.password]
+      delegate_to delegate
+    end
+    
+    # Automates fetching mentions / direct messages at the same time.
+    #
+    # @param [Array<Symbol>] fetches what to load - :all for all fetches, or names of the fetches otherwise
+    def fetch(*fetches)
+      options = fetches.extract_options!
+      fetches = VALID_FETCHES if fetches == [:all]
+      (fetches & VALID_FETCHES).each do |fetch_type|
+        send(fetch_type, options.dup)
+      end
+    end
+    
+    # Tells the twitter api to follow a specific user
+    #
+    # @param [String] user the screen_name of the user to follow
+    # @param [Hash] opts extra options to pass in the query string
+    def follow(user, opts = {})
+      user = user.to_s.strip
+      logger.info "Following '#{user}'"
+      post("friendships/create.json", opts.merge(:screen_name => user)) do
+        delegate.receive_message(:outgoing_follow, :user => user)
+      end
+    end
+    
+    # Tells the twitter api to unfollow a specific user
+    #
+    # @param [String] user the screen_name of the user to unfollow
+    # @param [Hash] opts extra options to pass in the query string
+    def unfollow(user, opts = {})
+      user = user.to_s.strip
+      logger.info "Unfollowing '#{user}'"
+      post("friendships/destroy.json", opts.merge(:screen_name => user)) do
+        delegate.receive_message(:outgoing_unfollow, :user => user)
+      end
+    end
+    
+    # Updates your current status on twitter with a specific message
+    #
+    # @param [String] message the contents of your tweet
+    # @param [Hash] opts extra options to pass in the query string
+    def tweet(message, opts = {})
+      message = message.to_s.strip
+      logger.debug "Tweeting #{message}"
+      post("statuses/update.json", opts.merge(:status => message)) do |json|
+        delegate.receive_message(:outgoing_tweet, status_to_args(json))
+      end
+    end
+    
+    # Sends a direct message to a given user
+    #
+    # @param [String] user the screen_name of the user you wish to dm
+    # @param [String] text the text to send to the user
+    # @param [Hash] opts extra options to pass in the query string
+    def dm(user, text, opts = {})
+      text = text.to_s.strip
+      user = user.to_s.strip
+      logger.debug "DM'ing #{user}: #{text}"
+      post("direct_messages/new.json", opts.merge(:user => user, :text => text)) do
+        delegate.receive_message(:outgoing_direct_message, :user => user, :text => text)
+      end
+    end
+    
+    # Returns an instance of BirdGrinder::Tweeter::Streaming,
+    # used for accessing the alpha streaming api for twitter.
+    #
+    # @see BirdGrinder::Tweeter::Streaming
+    def streaming
+      @streaming ||= Streaming.new(self)
+    end
+    
+    # Uses the twitter search api to look up a given
+    # query, with a set of possible options.
+    #
+    # @param [String] query the query you wish to search for
+    # @param [Hash] opts the opts to query, all except :repeat are sent to twitter.
+    # @option opts [Boolean] :repeat repeat the query indefinitely, fetching new messages each time
+    def search(query, opts = {})
+      @search ||= Search.new(self)
+      @search.search_for(query, opts)
+    end
+    
+    # Sends a correctly-formatted at reply to a given user.
+    # If the users screen_name isn't at the start of the tweet,
+    # it will be appended accordingly.
+    #
+    # @param [String] user the user to reply to's screen name
+    # @param [String] test the text to reply with
+    # @param [Hash] opts the options to pass in the query string
+    def reply(user, text, opts = {})
+      user = user.to_s.strip
+      text = text.to_s.strip
+      text = "@#{user} #{text}".strip unless text =~ /^\@#{user}\b/i
+      tweet(text, opts)
+    end
+    
+    # Asynchronously fetches the current users (as specified by your settings)
+    # direct messages from the twitter api
+    #
+    # @param [Hash] opts options to pass in the query string
+    def direct_messages(opts = {})
+      logger.debug "Fetching direct messages..."
+      get("direct_messages.json", opts) do |dms|
+        logger.debug "Fetched a total of #{dms.size} direct message(s)"
+        dms.each do |dm|
+          delegate.receive_message(:incoming_direct_message, status_to_args(dm, :direct_message))
+        end
+      end
+    end
+    
+    # Asynchronously fetches the current users (as specified by your settings)
+    # mentions from the twitter api
+    #
+    # @param [Hash] opts options to pass in the query string
+    def mentions(opts = {})
+      logger.debug "Fetching mentions..."
+      get("statuses/mentions.json", opts) do |mentions|
+        logger.debug "Fetched a total of #{mentions.size} mention(s)"
+        mentions.each do |status|
+          delegate.receive_message(:incoming_mention, status_to_args(status, :mention))
+        end
+      end
+    end
+        
+    protected
+    
+    def request(path = "/")
+      EventMachine::HttpRequest.new(api_base_url / path)
+    end
+    
+    def get(path, params = {}, &blk)
+      http = request(path).get({
+        :head => {'Authorization' => @auth_credentials},
+        :query => params.stringify_keys
+      })
+      add_response_callback(http, blk)
+      http
+    end
+    
+    def post(path, params = {}, &blk)
+      real_params = {}
+      params.each_pair { |k,v| real_params[URI.encode(k.to_s)] = URI.encode(v) }
+      http = request(path).post({
+        :head => {
+          'Authorization' => @auth_credentials,
+          'Content-Type'  => 'application/x-www-form-urlencoded'
+        },
+        :body => real_params
+      })
+      add_response_callback(http, blk)
+      http
+    end
+    
+    def add_response_callback(http, blk)
+      http.callback do
+        res = parse_response(http)
+        if res.nil?
+          logger.warn "Got back a blank / errored response."
+        elsif successful?(res)
+          blk.call(res) unless blk.blank?
+        else
+          logger.eror "Error: #{res.error} (on #{res.request})"
+        end
+      end
+    end
+    
+    def parse_response(http)
+      response = Yajl::Parser.parse(http.response)
+      if response.respond_to?(:to_ary)
+        response.map { |i| i.to_nash }
+      else
+        response.to_nash
+      end
+    rescue Yajl::ParseError => e
+      logger.error "Invalid Response: #{http.response} (#{e.message})"
+      nil
+    end
+    
+    def successful?(response)
+      response.respond_to?(:to_nash) ? !response.to_nash.error? : true
+    end
+    
+    def status_to_args(status_items, type = :tweet)
+      results = status_items.to_nash.normalized
+      results.type = type
+      results
+    end
+    
+    def check_auth!
+      if BirdGrinder::Settings["username"].blank? || BirdGrinder::Settings["username"].blank?
+        raise BirdGrinder::MissingAuthDetails, "Missing twitter username or password."
+      end
+    end
+    
+  end
+end