edh 0.1

data/lib/edh/http_service.rb

@@ -0,0 +1,142 @@
+require 'faraday'
+require 'edh/http_service/multipart_request'
+require 'edh/http_service/response'
+
+module EDH
+  module HTTPService
+    class << self
+      # A customized stack of Faraday middleware that will be used to make each request.
+      attr_accessor :faraday_middleware
+      attr_accessor :http_options
+    end
+
+    @http_options ||= {}
+
+    # EDH's default middleware stack.
+    # We encode requests in a Passport-compatible multipart request,
+    # and use whichever adapter has been configured for this application.
+    DEFAULT_MIDDLEWARE = Proc.new do |builder|
+      builder.use EDH::HTTPService::MultipartRequest
+      builder.request :url_encoded
+      builder.adapter Faraday.default_adapter
+    end
+
+    # The address of the appropriate Passport server.
+    #
+    # @param options various flags to indicate which server to use.
+    # @option options :rest_api use the old REST API instead of the Graph API
+    # @option options :use_ssl force https, even if not needed
+    #
+    # @return a complete server address with protocol
+    def self.server(options = {})
+      if options[:server]
+        options[:server]
+      else
+        server = Passport::REST_SERVER
+        "#{options[:use_ssl] ? "https" : "http"}://#{server}"
+      end
+    end
+
+    # Makes a request directly to Passport.
+    # @note You'll rarely need to call this method directly.
+    #
+    # @see EDH::Passport::API#api
+    # @see EDH::Passport::RestAPIMethods#rest_call
+    #
+    # @param path the server path for this request
+    # @param args (see EDH::Passport::API#api)
+    # @param verb the HTTP method to use.
+    #             If not get or post, this will be turned into a POST request with the appropriate :method
+    #             specified in the arguments.
+    # @param options (see EDH::Passport::API#api)
+    #
+    # @raise an appropriate connection error if unable to make the request to Passport
+    #
+    # @return [EDH::HTTPService::Response] a response object representing the results from Passport
+    def self.make_request(path, args, verb, options = {})
+      # if the verb isn't get or post, send it as a post argument
+      args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
+
+      # turn all the keys to strings (Faraday has issues with symbols under 1.8.7)
+      params = args.inject({}) {|hash, kv| hash[kv.first.to_s] = kv.last; hash}
+
+      # figure out our options for this request
+      request_options = {:params => (verb == "get" ? params : {})}.merge(http_options || {}).merge(process_options(options))
+      if request_options[:use_ssl]
+        ssl = (request_options[:ssl] ||= {})
+        ssl[:verify] = true unless ssl.has_key?(:verify)
+      end
+
+      # set up our Faraday connection
+      # we have to manually assign params to the URL or the
+      conn = Faraday.new(server(request_options), request_options, &(faraday_middleware || DEFAULT_MIDDLEWARE))
+
+      response = conn.send(verb, path, (verb == "post" ? params : {}))
+
+      # Log URL information
+      EDH::Utils.debug "#{verb.upcase}: #{path} params: #{params.inspect}"
+      EDH::HTTPService::Response.new(response.status.to_i, response.body, response.headers)
+    end
+
+    # Encodes a given hash into a query string.
+    # This is used mainly by the Batch API nowadays, since Faraday handles this for regular cases.
+    #
+    # @param params_hash a hash of values to CGI-encode and appropriately join
+    #
+    # @example
+    #   EDH.http_service.encode_params({:a => 2, :b => "My String"})
+    #   => "a=2&b=My+String"
+    #
+    # @return the appropriately-encoded string
+    def self.encode_params(param_hash)
+      ((param_hash || {}).sort_by{|k, v| k.to_s}.collect do |key_and_value|
+        key_and_value[1] = MultiJson.dump(key_and_value[1]) unless key_and_value[1].is_a? String
+        "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
+      end).join("&")
+    end
+
+    private
+
+    def self.process_options(options)
+      if typhoeus_options = options.delete(:typhoeus_options)
+        EDH::Utils.deprecate("typhoeus_options should now be included directly in the http_options hash.  Support for this key will be removed in a future version.")
+        options = options.merge(typhoeus_options)
+      end
+
+      if ca_file = options.delete(:ca_file)
+        EDH::Utils.deprecate("http_options[:ca_file] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:ca_file].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:ca_file] = ca_file
+      end
+
+      if ca_path = options.delete(:ca_path)
+        EDH::Utils.deprecate("http_options[:ca_path] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:ca_path].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:ca_path] = ca_path
+      end
+
+      if verify_mode = options.delete(:verify_mode)
+        EDH::Utils.deprecate("http_options[:verify_mode] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:verify_mode].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:verify_mode] = verify_mode
+      end
+
+      options
+    end
+  end
+
+  # @private
+  module TyphoeusService
+    def self.deprecated_interface
+      # support old-style interface with a warning
+      EDH::Utils.deprecate("the TyphoeusService module is deprecated; to use Typhoeus, set Faraday.default_adapter = :typhoeus.  Enabling Typhoeus for all Faraday connections.")
+      Faraday.default_adapter = :typhoeus
+    end
+  end
+
+  # @private
+  module NetHTTPService
+    def self.deprecated_interface
+      # support old-style interface with a warning
+      EDH::Utils.deprecate("the NetHTTPService module is deprecated; to use Net::HTTP, set Faraday.default_adapter = :net_http.  Enabling Net::HTTP for all Faraday connections.")
+      Faraday.default_adapter = :net_http
+    end
+  end
+end

data/lib/edh/http_service/multipart_request.rb

@@ -0,0 +1,40 @@
+require 'faraday'
+
+module EDH  
+  module HTTPService
+    class MultipartRequest < Faraday::Request::Multipart
+      # Passport expects nested parameters to be passed in a certain way
+      # Faraday needs two changes to make that work:
+      # 1) [] need to be escaped (e.g. params[foo]=bar ==> params%5Bfoo%5D=bar)
+      # 2) such messages need to be multipart-encoded
+    
+      self.mime_type = 'multipart/form-data'.freeze
+    
+      def process_request?(env)
+        # if the request values contain any hashes or arrays, multipart it
+        super || !!(env[:body].respond_to?(:values) && env[:body].values.find {|v| v.is_a?(Hash) || v.is_a?(Array)})
+      end   
+    
+    
+      def process_params(params, prefix = nil, pieces = nil, &block)
+        params.inject(pieces || []) do |all, (key, value)|
+          key = "#{prefix}%5B#{key}%5D" if prefix
+
+          case value
+          when Array
+            values = value.inject([]) { |a,v| a << [nil, v] }
+            process_params(values, key, all, &block)
+          when Hash
+            process_params(value, key, all, &block)
+          else
+            all << block.call(key, value)
+          end
+        end
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when MultipartRequest lived directly under EDH
+  MultipartRequest = HTTPService::MultipartRequest  
+end

data/lib/edh/http_service/response.rb

@@ -0,0 +1,18 @@
+module EDH
+  module HTTPService
+    class Response
+      attr_reader :status, :body, :headers
+
+      # Creates a new Response object, which standardizes the response received by Passport for use within EDH.
+      def initialize(status, body, headers)
+        @status = status
+        @body = body
+        @headers = headers
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when Response lived directly under EDH
+  Response = HTTPService::Response
+end

data/lib/edh/test_users.rb

@@ -0,0 +1,188 @@
+require 'edh'
+
+module EDH
+  module Passport
+    
+    # Create and manage test users for your application.  
+    # A test user is a user account associated with an app created for the purpose 
+    # of testing the functionality of that app. 
+    # You can use test users for manual or automated testing -- 
+    # EDH's live test suite uses test users to verify the library works with Passport.
+    #
+    # @note the test user API is fairly slow compared to other interfaces
+    #       (which makes sense -- it's creating whole new user accounts!).
+    #
+    class TestUsers
+
+      # The application API interface used to communicate with Passport. 
+      # @return [EDH::Passport::API] 
+      attr_reader :api
+      attr_reader :app_id, :app_access_token, :secret
+      
+      # Create a new TestUsers instance.  
+      # If you don't have your app's access token, provide the app's secret and 
+      # EDH will make a request to Passport for the appropriate token.
+      # 
+      # @param options initialization options.
+      # @option options :app_id the application's ID.
+      # @option options :app_access_token an application access token, if known.
+      # @option options :secret the application's secret.  
+      #
+      # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
+      def initialize(options = {})
+        @app_id = options[:app_id]
+        @app_access_token = options[:app_access_token]
+        @secret = options[:secret]
+        unless @app_id && (@app_access_token || @secret) # make sure we have what we need
+          raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
+        end
+
+        # fetch the access token if we're provided a secret
+        if @secret && !@app_access_token
+          oauth = EDH::Passport::OAuth.new(@app_id, @secret)
+          @app_access_token = oauth.get_app_access_token
+        end
+        
+        @api = API.new(@app_access_token)
+      end
+
+      # Create a new test user.  
+      #
+      # @param installed whether the user has installed your app
+      # @param permissions a comma-separated string or array of permissions the user has granted (if installed)
+      # @param args any additional arguments for the create call (name, etc.)
+      # @param options (see EDH::Passport::API#api)
+      #
+      # @return a hash of information for the new user (id, access token, login URL, etc.)
+      def create(installed, permissions = nil, args = {}, options = {})
+        # Creates and returns a test user
+        args['installed'] = installed
+        args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
+        @api.graph_call(test_user_accounts_path, args, "post", options)
+      end
+
+      # List all test users for the app.
+      #
+      # @param options (see EDH::Passport::API#api)
+      #
+      # @return an array of hashes of user information (id, access token, etc.)
+      def list(options = {})
+        @api.graph_call(test_user_accounts_path, {}, "get", options)
+      end
+
+      # Delete a test user.
+      #
+      # @param test_user the user to delete; can be either a Passport ID or the hash returned by {#create}
+      # @param options (see EDH::Passport::API#api)
+      #
+      # @return true if successful, false (or an {EDH::Passport::APIError APIError}) if not
+      def delete(test_user, options = {})
+        test_user = test_user["id"] if test_user.is_a?(Hash)
+        @api.delete_object(test_user, options)
+      end
+
+      # Deletes all test users in batches of 50.
+      # 
+      # @note if you have a lot of test users (> 20), this operation can take a long time.
+      #
+      # @param options (see EDH::Passport::API#api)
+      # 
+      # @return a list of the test users that have been deleted
+      def delete_all(options = {})
+        # ideally we'd save a call by checking next_page_params, but at the time of writing
+        # Passport isn't consistently returning full pages after the first one
+        previous_list = nil
+        while (test_user_list = list(options)).length > 0
+          break if test_user_list == previous_list
+
+          test_user_list.each_slice(50) do |users| 
+            self.api.batch(options) {|batch_api| users.each {|u| batch_api.delete_object(u["id"]) }}
+          end
+          
+          previous_list = test_user_list
+        end
+      end
+
+      # Updates a test user's attributes.
+      #
+      # @note currently, only name and password can be changed; 
+      #       see {http://developers.facebook.com/docs/test_users/ the Facebook documentation}.
+      #
+      # @param test_user the user to update; can be either a Facebook ID or the hash returned by {#create}
+      # @param args the updates to make
+      # @param options (see EDH::Passport::API#api)
+      #
+      # @return true if successful, false (or an {EDH::Passport::APIError APIError}) if not
+      def update(test_user, args = {}, options = {})
+        test_user = test_user["id"] if test_user.is_a?(Hash)
+        @api.graph_call(test_user, args, "post", options)
+      end
+
+      # Make two test users friends.
+      #
+      # @note there's no way to unfriend test users; you can always just create a new one.
+      #
+      # @param user1_hash one of the users to friend; the hash must contain both ID and access token (as returned by {#create})
+      # @param user2_hash the other user to friend
+      # @param options (see EDH::Passport::API#api)
+      #
+      # @return true if successful, false (or an {EDH::Passport::APIError APIError}) if not
+      def befriend(user1_hash, user2_hash, options = {})
+        user1_id = user1_hash["id"] || user1_hash[:id]
+        user2_id = user2_hash["id"] || user2_hash[:id]
+        user1_token = user1_hash["access_token"] || user1_hash[:access_token]
+        user2_token = user2_hash["access_token"] || user2_hash[:access_token]
+        unless user1_id && user2_id && user1_token && user2_token
+          # we explicitly raise an error here to minimize the risk of confusing output
+          # if you pass in a string (as was previously supported) no local exception would be raised
+          # but the Passport call would fail
+          raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token"
+        end
+
+        u1_graph_api = API.new(user1_token)
+        u2_graph_api = API.new(user2_token)
+
+        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post", options) &&
+          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post", options)
+      end
+
+      # Create a network of test users, all of whom are friends and have the same permissions.
+      #
+      # @note this call slows down dramatically the more users you create 
+      #       (test user calls are slow, and more users => more 1-on-1 connections to be made).
+      #       Use carefully.
+      #
+      # @param network_size how many users to create
+      # @param installed whether the users have installed your app (see {#create})
+      # @param permissions what permissions the users have granted (see {#create})
+      # @param options (see EDH::Passport::API#api)
+      #
+      # @return the list of users created
+      def create_network(network_size, installed = true, permissions = '', options = {})
+        users = (0...network_size).collect { create(installed, permissions, options) }
+        friends = users.clone
+        users.each do |user|
+          # Remove this user from list of friends
+          friends.delete_at(0)
+          # befriend all the others
+          friends.each do |friend|
+            befriend(user, friend, options)
+          end
+        end
+        return users
+      end
+      
+      # The Passport test users management URL for your application.
+      def test_user_accounts_path
+        @test_user_accounts_path ||= "/#{@app_id}/accounts/test-users"
+      end      
+
+      # @private
+      # Legacy accessor for before GraphAPI was unified into API
+      def graph_api
+        EDH::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
+        @api
+      end
+    end # TestUserMethods
+  end # Passport
+end # EDH

data/lib/edh/utils.rb

@@ -0,0 +1,20 @@
+module EDH
+  module Utils
+
+    # Utility methods used by EDH.
+    require 'logger'
+    require 'forwardable'
+
+    extend Forwardable
+    extend self
+
+    def_delegators :logger, :debug, :info, :warn, :error, :fatal, :level, :level=
+
+    # The EDH logger, an instance of the standard Ruby logger, pointing to STDOUT by default.
+    # In Rails projects, you can set this to Rails.logger.
+    attr_accessor :logger
+    self.logger = Logger.new(STDOUT)
+    self.logger.level = Logger::ERROR
+
+  end
+end

data/lib/edh/version.rb

@@ -0,0 +1,3 @@
+module EDH
+  VERSION = "0.1"
+end

data/readme.md

@@ -0,0 +1,42 @@
+####config/initializers
+#### defaults to using production
+```ruby
+$passport_client = EDH::Passport::API.new
+```
+
+####optional access_token
+```ruby
+$passport_client = EDH::Passport::API.new(nil, "http://dummy-passport.dev")
+```
+####set the user token
+```ruby
+$passport_client.access_token = "abc"
+```
+
+####create returns an action id
+```ruby
+$passport_client.create("pages.fundraise", {:abc => "def", :cats => "dogs"})
+=> 1234
+#sending json example
+$passport_client.create("pages.fundraise", "{\"abc\":\"def\",\"cats\":\"dogs\"}")
+```
+
+####update an action
+```ruby
+$passport_client.update(1234, {:abc => "12345", :cats => "6789"})
+```
+
+####delete an action
+```ruby
+$passport_client.delete(1234)
+```
+
+
+Testing
+-----
+
+Unit tests are provided for all of EDH's methods.  By default, these tests run against mock responses and hence are ready out of the box:
+```bash
+# From anywhere in the project directory:
+bundle exec rake spec
+```