em-instagram 0.1 → 0.1.1

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+.rspec
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+gem 'eventmachine'
+gem 'eventmachine_httpserver'
+gem 'em-http-request'
+gem 'rspec'

data/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2013 Mosaic Sales Solutions
+
+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.md

@@ -0,0 +1,120 @@
+# Eventmachine Instagram
+
+This gem provides an interface to the Instagram API which uses EventMachine to interface with it. It is designed for use inside a larger EventMachine based application, and to make the API requests without blocking your reactor.
+
+## Installation
+
+If using Bundler, add it to your Gemfile
+
+    gem 'em-instagram'
+
+If not, just install the gem and require it in your source.
+
+## Usage
+
+### Setup
+
+By default, em-instagram ships with a basic EventMachine web server with it. This allows you to process the callbacks from the API when you subscribe. We recommend that you replace the 'default' server with one of your own as soon as possible, as this is only provided to make initial development easier.
+
+To set it up, instantiate an EventMachine::Instagram instance
+
+    instagram_args = {
+      :client_id => 'xxxxx',
+      :client_secret => "xxxxx",
+      :callback_url => "www.example.com"
+    }
+    instagram_connection = EventMachine::Instagram.new(instagram_args)
+    instagram_connection.on_update{|media| puts media.inspect}
+
+    EventMachine.run do
+      instagram_connection.start_server
+    end
+
+The basic arguments that the connection requires is the :client_id, :client_secret and :callback_url. The callback_url is the url of the server that this client is running on. By default, the provided server will just intercept any request aimed at the route, but if you define your own server (more on that later), you can alter how it behaves to different url's.
+
+You also need to define an update block. This block is called whenever new media is returned by Instagram, with the serialized JSON from the Instagram API.
+
+Finally, we wrap the server in an EventMachine run block, and boot it up. If your app is already running inside a reactor, there's no need to wrap this code in EM.run.
+
+### Adding Subscriptions
+
+To add a subscription, you call subscribe, and pass it a hash of subscription terms. The gem currently allows subscriptions to tags and geographies.
+
+    subscriptions = [{:object => "tag", :object_id => "apple"},
+    {:object => "geography", :lat => latitude, :lng => longitude, :radius => radius}]
+
+    instagram_args = {
+      :client_id => 'xxxxx',
+      :client_secret => "xxxxx",
+      :callback_url => "www.example.com"
+    }
+    instagram_connection = EventMachine::Instagram.new(instagram_args)
+    instagram_connection.on_update{|media| puts media.inspect}
+    instagram_connection.subscribe(*subscriptions)
+    EventMachine.run do
+      instagram_connection.start_server
+    end
+
+## Configuration
+
+### Logging
+
+You can pass a logger into the instagram args. This logger must expect a method called "debug", and will be passed debugging information. For an example of how to add a logger to the basic handler, using the Ruby default logger
+
+    require 'logger'
+    logger = Logger.new('log/instagram.log')
+    instagram_args = {
+      :logger => logger,
+      :client_id => 'xxxxx',
+      :client_secret => "xxxxx",
+      :callback_url => "www.example.com"
+    }
+    instagram_connection = EventMachine::Instagram.new(instagram_args)
+
+###  Custom notification behaviour
+
+The way the Instagram streaming API works is that it will post you notifications of new content. The default behaviour of em-instagram is to immediately 'fetch' that content and pass it into the update block provided by you. You can change this by calling stream on the connection object, and passing a block. This can be called multiple times, and each time, it will push a new block onto the stack. Whenever a notification comes in, every block in the stack will be called with that notification as an argument.
+
+    instagram_connection = EventMachine::Instagram.new(instagram_args)
+    instagram_connection.stream {|notification| instagram_connection.fetch notification } #preserve original functionality
+    instagram_connection.stream {|notification| my_outside_instance.notify(notification)}
+    instagram_connection.on_update{|media| puts media.inspect}
+
+### Altering the default server listening addresses
+
+By default, the provided server listens to 0.0.0.0 at port 8080. To change this, you can pass :port and :host to the initializer.
+
+    instagram_args = {
+      :port => 80,
+      :host => "myserver.vm",
+      :client_id => 'xxxxx',
+      :client_secret => "xxxxx",
+      :callback_url => "www.example.com"
+    }
+    instagram_connection = EventMachine::Instagram.new(instagram_args)
+
+### Altering the default server
+
+The server provided is deliberately very sparse. It assumes that all requests incoming are instagram requests and treats them accordingly. It is not designed to be used in a production environment, only to allow you to start developing until you know enough about your architecture to develop your own server. For my use of this gem, I wrote a server based off [evma_httpserver](https://github.com/eventmachine/evma_httpserver). Pass it in with the :server argument to the initializer.
+
+    class MyHttpServer < EM::Connection
+      include EM::HttpServer
+
+      def process_http_request
+        puts "Got a request to #{@http_request_uri}
+      end
+    end
+
+    instagram_args = {
+      :server => MyHttpServer,
+      :port => 80,
+      :host => "myserver.vm",
+      :client_id => 'xxxxx',
+      :client_secret => "xxxxx",
+      :callback_url => "www.example.com"
+    }
+    instagram_connection = EventMachine::Instagram.new(instagram_args)
+
+## Final notes
+
+This gem is in the early stages of development and is targetted at my own need to use the streaming API's in an event driven fashion. Pull requests to add functionality to the gem are more than welcome!

data/lib/em-instagram/api/media.rb

@@ -15,18 +15,18 @@ module EventMachine
 
 
       def fetch_geography(object_id)
-        @logger.debug "fetching #{object_id} updates..."
+        self.logger.debug "fetching #{object_id} updates..."
         # TODO: figure out if min_id parameter would be appropriate for reading recent tagged media
         request = media_by_geography(object_id)
-        request.errback { |error| @logger.debug "fetch error: #{error}";  EventMachine::add_timer(15) { fetch_geography object_id } }
+        request.errback { |error| self.logger.debug "fetch error: #{error}";  EventMachine::add_timer(15) { fetch_geography object_id } }
         request.callback { |media| @update_queue.push(*media) }
       end
 
       def fetch_tag(object_id)
-        @logger.debug "fetching #{object_id} updates..."
+        self.logger.debug "fetching #{object_id} updates..."
         # TODO: figure out if max_id or min_id parameter would be appropriate for reading recent tagged media
         request = media_by_tag(object_id)
-        request.errback { |error| @logger.debug "fetch error: #{error}";  EventMachine::add_timer(15) { fetch_tag object_id } }
+        request.errback { |error| self.logger.debug "fetch error: #{error}";  EventMachine::add_timer(15) { fetch_tag object_id } }
         request.callback { |media| @update_queue.push(*media) }
       end
     end

data/lib/em-instagram/api/subscriptions.rb

@@ -1,15 +1,13 @@
 module EventMachine
   class Instagram
     module Subscriptions
-      def send_subscription(params = {})
-        request :post, "/v1/subscriptions", :body => default_params.merge(params)
-      end
 
       def subscribe_to(options)
-        options = options.merge(:aspect => 'media', :callback_url => CALLBACK_URL)
-        request = send_subscription options.merge(:aspect => 'media', :callback_url => CALLBACK_URL)
-        request.errback { |error| @logger.debug "subscription error: #{error}"; EventMachine::add_timer(15) { subscribe_to options } }
-        request.callback { |response| @logger.debug "next subscription..."; EventMachine::next_tick { subscribe_next } }
+        options = options.merge(:aspect => 'media', :callback_url => self.callback_url)
+        request_body = default_params.merge(:aspect => 'media', :callback_url => self.callback_url).merge(options)
+        request = request(:post, "/v1/subscriptions", :body => request_body)
+        request.errback { |error| self.logger.debug "subscription error: #{error}"; EventMachine::add_timer(15) { subscribe_to options } }
+        request.callback { |response| self.logger.debug "next subscription..."; EventMachine::next_tick { subscribe_next } }
       end
 
       def subscriptions(params = {})
@@ -27,9 +25,9 @@ module EventMachine
 
       def subscribe_next
         if @subscription_queue.empty?
-          @logger.debug "subscribed."
+          self.logger.debug "subscribed."
         else
-          @subscription_queue.pop { |hash| send_subscription(hash); subscribe_next }
+          self.subscription_queue.pop { |hash| subscribe_to(hash); subscribe_next }
         end
       end
     end

data/lib/em-instagram/proxy_logger.rb

@@ -0,0 +1,5 @@
+class ProxyLogger
+  def debug(*args)
+    return args
+  end
+end

data/lib/em-instagram/server.rb

@@ -1,3 +1,6 @@
+require 'evma_httpserver/response'
+require 'json'
+
 module EventMachine
   class Instagram
     module Server

data/lib/em-instagram/version.rb

@@ -1,5 +1,5 @@
 module EventMachine
   class Instagram
-    VERSION = '0.1'
+    VERSION = '0.1.1'
   end
 end

data/lib/em-instagram.rb

@@ -2,6 +2,7 @@ require File.expand_path('../em-instagram/request', __FILE__)
 require File.expand_path('../em-instagram/server', __FILE__)
 require File.expand_path('../em-instagram/api/subscriptions', __FILE__)
 require File.expand_path('../em-instagram/api/media', __FILE__)
+require File.expand_path('../em-instagram/proxy_logger', __FILE__)
 
 module EventMachine
   class Instagram
@@ -11,19 +12,21 @@ module EventMachine
     BASE_URI = 'https://api.instagram.com'
     PORT = 443
 
-    attr_reader :default_params, :host, :port, :server, :logger, :subscription_queue, :update_callback
+    attr_reader :default_params, :host, :port, :server, :logger, :subscription_queue, :update_callback, :callback_url
 
     def initialize(options = nil)
       @host, @port, @server = [options[:host], options[:port], options[:server]]
       @subscription_queue = EventMachine::Queue.new
       @update_queue = EventMachine::Queue.new
-      @logger = options[:logger]
+      @callback_url = options[:callback_url]
+      @default_stream = Proc.new{|update| self.fetch update}
+      self.logger = options[:logger]
       @default_params = {:client_id => options[:client_id], :client_secret => options[:client_secret]}
       update
 
     end
 
-     def fetch(update)
+    def fetch(update)
       case update['object']
       when 'geography'
         fetch_geography update['object_id']
@@ -32,6 +35,15 @@ module EventMachine
       end
     end
 
+    def logger
+      return @logger if @logger
+      ProxyLogger.new
+    end
+
+    def logger=(logger)
+      @logger = logger
+    end
+
     def stream(&block)
       @streams ||= []
       @streams << block
@@ -47,14 +59,15 @@ module EventMachine
         if @update_callback
           @update_callback.call(item)
         else
-          @logger.debug(item)
+          self.logger.debug(item)
         end
         EventMachine::next_tick { update }
       end
     end
 
     def receive_notification(data)
-      @streams.each { |stream| stream.call(data) }
+      stream_set = @streams.nil? ? [@default_stream] : @streams
+      stream_set.each { |stream| stream.call(data) }
     end
 
     def request(method, path, options = {})

data/spec/api/media_spec.rb

@@ -0,0 +1,63 @@
+require File.expand_path('../../spec_helper', __FILE__)
+
+describe EventMachine::Instagram::Media do
+  before :each do
+    @instagram_url = "https://api.instagram.com/v1/"
+    logger = Logger.new("/dev/null") # OS dependent here!
+    client_id = "11111111"
+    client_secret = "22222222"
+    @callback_url = "myserver.vm/instagram_handler"
+    @instagram = EventMachine::Instagram.new(:logger => logger, :client_id => client_id, :client_secret => client_secret, :callback_url => @callback_url)
+    @expected_body = {:client_id=>client_id, :client_secret=>client_secret}
+    @http_stub = double("http_stub")
+    @request = double("request")
+    @request.stub(:errback => double("errback"))
+    @request.stub(:callback => double("callback"))
+    EventMachine::HttpRequest.stub(:new => @http_stub)
+  end
+
+  it "should post basic media" do
+    media_object = 2
+    EventMachine::HttpRequest.should_receive(:new).with(@instagram_url + "media/#{media_object}").and_return(@http_stub)
+    @http_stub.should_receive(:get).and_return(@request)
+    @instagram.media(media_object)
+  end
+
+  it "should be able to search on tags" do
+    tag = "banana"
+    EventMachine::HttpRequest.should_receive(:new).with(@instagram_url + "tags/#{tag}/media/recent").and_return(@http_stub)
+    @http_stub.should_receive(:get).and_return(@request)
+    @instagram.media_by_tag(tag)
+  end
+
+  it "should be able to search on geographies" do
+    geo = "banana_tree"
+    EventMachine::HttpRequest.should_receive(:new).with(@instagram_url + "geographies/#{geo}/media/recent").and_return(@http_stub)
+    @http_stub.should_receive(:get).and_return(@request)
+    @instagram.media_by_geography(geo)
+  end
+
+  it "should use the correct callbacks with the fetch geography method" do
+    geo = "banana_tree"
+    @instagram.should_receive(:media_by_geography).and_return(@request)
+    @request.should_receive(:callback) do |&callback_args|
+      queue = double("queue")
+      @instagram.send(:instance_variable_set, :@update_queue, queue)
+      queue.should_receive(:push).with({:data => "geo"})
+      callback_args.call([{:data => "geo"}])
+    end
+    @instagram.fetch_geography("banana_tree")
+  end
+
+  it "should use the correct callbacks with the fetch tags method" do
+    geo = "banana_tree"
+    @instagram.should_receive(:media_by_tag).and_return(@request)
+    @request.should_receive(:callback) do |&callback_args|
+      queue = double("queue")
+      @instagram.send(:instance_variable_set, :@update_queue, queue)
+      queue.should_receive(:push).with({:data => "geo"})
+      callback_args.call([{:data => "geo"}])
+    end
+    @instagram.fetch_tag("banana_tree")
+  end
+end

data/spec/api/subscriptions_spec.rb

@@ -0,0 +1,54 @@
+require File.expand_path('../../spec_helper', __FILE__)
+
+describe EventMachine::Instagram::Subscriptions do
+  before :each do
+    @instagram_url = "https://api.instagram.com/v1/subscriptions"
+    logger = Logger.new("/dev/null") # OS dependent here!
+    client_id = "11111111"
+    client_secret = "22222222"
+    @callback_url = "myserver.vm/instagram_handler"
+    @instagram = EventMachine::Instagram.new(:logger => logger, :client_id => client_id, :client_secret => client_secret, :callback_url => @callback_url)
+    @expected_body = {:client_id=>client_id, :client_secret=>client_secret}
+    @http_stub = double("http_stub")
+    @request = double("request")
+    @request.stub(:errback => double("errback"))
+    @request.stub(:callback => double("callback"))
+    EventMachine::HttpRequest.stub(:new => @http_stub)
+  end
+
+  it "should send a media subscription when asked to subscribe to a topic" do
+    args = {:banana => "fun"}
+    media_args = {:aspect => 'media', :callback_url => @callback_url}
+    EventMachine::HttpRequest.should_receive(:new).with(@instagram_url).and_return(@http_stub)
+    @http_stub.should_receive(:post).with(:body=> @expected_body.merge(args).merge(media_args)).and_return(@request)
+    @instagram.subscribe_to(args)
+  end
+
+  it "should be able to get a list of subscriptions" do
+    args = {:banana => "fun"}
+    EventMachine::HttpRequest.should_receive(:new).with(@instagram_url).and_return(@http_stub)
+    @http_stub.should_receive(:get).with(:query=> @expected_body.merge(args)).and_return(@request)
+    @instagram.subscriptions(args)
+  end
+
+  it "should be able to unsubscribe from a subscription" do
+    args = {:banana => "fun"}
+    EventMachine::HttpRequest.should_receive(:new).with(@instagram_url).and_return(@http_stub)
+    @http_stub.should_receive(:delete).with(:query=> @expected_body.merge(args)).and_return(@request)
+    @instagram.unsubscribe(args)
+  end
+
+  it "should push subscriptions onto a queue and then trigger the queue" do
+    queue = []
+    @instagram.send(:instance_variable_set, :@subscription_queue, queue)
+    @instagram.should_receive(:subscribe_next)
+    @instagram.subscribe(:random => "json")
+    queue.should include(:random => "json")
+  end
+
+  it "should pop items off the queue until there are none left" do
+    queue = [{:first_json => "1"}, {:second => 2}, {3 => :four}]
+    @instagram.should_receive(:subscribe_to).with(*queue).ordered
+    @instagram.subscribe_to(*queue)
+  end
+end

data/spec/em-instagram_spec.rb

@@ -0,0 +1,55 @@
+require File.expand_path('../spec_helper', __FILE__)
+
+describe EventMachine::Instagram do
+
+  before :each do
+    logger = Logger.new("/dev/null") # OS dependent here!
+    client_id = "11111111"
+    client_secret = "22222222"
+    @callback_url = "myserver.vm/instagram_handler"
+    @instagram = EventMachine::Instagram.new(:logger => logger, :client_id => client_id, :client_secret => client_secret, :callback_url => @callback_url)
+  end
+
+  it "should dispatch a fetch request to the geography API when asked for a geo" do
+    object = {'object' => "geography", "object_id" => 'banana'}
+    @instagram.should_receive(:fetch_geography).with("banana")
+    @instagram.fetch(object)
+  end
+
+  it "should dispatch a fetch request to the tags API when asked for a tag" do
+    object = {'object' => "tag", "object_id" => 'banana'}
+    @instagram.should_receive(:fetch_tag).with("banana")
+    @instagram.fetch(object)
+  end
+
+  it "should execute the provided stream block to all streams when it recieves a new notification of content" do
+    call_check = double("checker")
+    call_check_two = double("checker")
+    call_check.should_receive(:called).with("banana")
+    call_check_two.should_receive(:called).with("banana")
+    @instagram.stream{|note| call_check.called(note)}
+    @instagram.stream{|note| call_check_two.called(note)}
+    @instagram.receive_notification("banana")
+  end
+
+  it "should execute anything put onto the update queue and keep the pop waiting for more data" do
+    call_check = double("checker")
+    call_check.should_receive(:called).with("banana").twice
+    @instagram.on_update{|u| call_check.called(u)}
+    EventMachine.run do
+      @instagram.update("banana")
+      @instagram.update("banana")
+      EventMachine.next_tick{EventMachine.stop_event_loop}
+    end
+  end
+
+  it "should not throw exceptions if the logger is not present" do
+    @instagram = EventMachine::Instagram.new(:client_id => '1', :client_secret => '2', :callback_url => @callback_url)
+    expect{ @instagram.subscribe_next}.to_not raise_error
+  end
+
+  it "should use the default stream if no stream is defined" do
+    @instagram.should_receive(:fetch)
+    @instagram.receive_notification("banana")
+  end
+end

data/spec/server_spec.rb

@@ -0,0 +1,68 @@
+require File.expand_path('../spec_helper', __FILE__)
+
+describe EventMachine::Instagram::Server do
+
+  before :all do
+    module EventMachine
+      class ServerStub
+        include Instagram::Server
+        attr_accessor :http_request_method, :http_query_string, :updates, :http_post_content
+      end
+    end
+  end
+
+  before :each do
+    @response = double("response")
+    EventMachine::DelegatedHttpResponse.stub(:new => @response)
+  end
+
+  it "should create a delayed response to be able to keep processing" do
+    @response.should_receive :send_response
+    @response.should_receive :status=
+    @response.should_receive :content=
+    EventMachine::ServerStub.new.process_http_request
+  end
+
+  it "should respond with a 200 okay to a get request and set the hub challenge parameter as the contents" do
+    @response.should_receive :send_response
+    @response.should_receive(:status=).with(200)
+    @response.should_receive(:content=).with(["banana"])
+    server = EventMachine::ServerStub.new
+    server.http_request_method = "GET"
+    server.http_query_string = "hub.challenge=banana"
+    server.process_http_request
+  end
+
+  it "should respond with a 200 okay to a get request and set the content as blank if no challenge is provided" do
+    @response.should_receive :send_response
+    @response.should_receive(:status=).with(200)
+    @response.should_receive(:content=).with([])
+    server = EventMachine::ServerStub.new
+    server.http_request_method = "GET"
+    server.http_query_string = ''
+    server.process_http_request
+  end
+
+  it "should respond with a 202 and push the json to the update queue when receiving a post" do
+    json = [{'banana' => "fun"}, {'apple' => "also fun"} ]
+    @response.should_receive :send_response
+    @response.should_receive(:status=).with(202)
+    @response.should_receive(:content=).with("Accepted")
+    server = EventMachine::ServerStub.new
+    server.http_request_method = "POST"
+    server.http_post_content = json.to_json
+    server.updates = []
+    server.process_http_request
+    server.updates.should eql(json)
+  end
+
+  it "should respond with a 405 to a request type it doesn't recognise" do
+    @response.should_receive :send_response
+    @response.should_receive(:status=).with(405)
+    @response.should_receive(:content=).with('Method Not Allowed')
+    server = EventMachine::ServerStub.new
+    server.http_request_method = "DELETE"
+    server.process_http_request
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+require 'rubygems'
+require 'bundler'
+Bundler.require(:default)
+require 'logger'
+require File.expand_path('../../lib/em-instagram.rb', __FILE__)
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: em-instagram
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -82,14 +82,23 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .gitignore
+- Gemfile
+- LICENSE.md
 - README.md
 - em-instagram.gemspec
 - lib/em-instagram.rb
 - lib/em-instagram/api/media.rb
 - lib/em-instagram/api/subscriptions.rb
+- lib/em-instagram/proxy_logger.rb
 - lib/em-instagram/request.rb
 - lib/em-instagram/server.rb
 - lib/em-instagram/version.rb
+- spec/api/media_spec.rb
+- spec/api/subscriptions_spec.rb
+- spec/em-instagram_spec.rb
+- spec/server_spec.rb
+- spec/spec_helper.rb
 homepage: ''
 licenses: []
 post_install_message: 
@@ -114,5 +123,10 @@ rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: ''
-test_files: []
+test_files:
+- spec/api/media_spec.rb
+- spec/api/subscriptions_spec.rb
+- spec/em-instagram_spec.rb
+- spec/server_spec.rb
+- spec/spec_helper.rb
 has_rdoc: