palidanx-koala 0.9.0

data/CHANGELOG

@@ -0,0 +1,98 @@
+v0.9.0
+-- Added parse_signed_request to handle Facebook's new authentication scheme
+  -- note: creates dependency on OpenSSL (OpenSSL::HMAC) for decryption
+-- Added GraphCollection class to provide paging support for GraphAPI get_connections and search methods (thanks to jagthedrummer)    
+-- Added get_page method to easily fetch pages of results from GraphCollections
+-- Exchanging sessions for tokens now works properly when provided invalid/expired session keys
+-- You can now include a :typhoeus_options key in TyphoeusService#make_request's options hash to control the Typhoeus call (for example, to set :disable_ssl_peer_verification => true) 
+-- All paths provided to HTTP services start with leading / to improve compatibility with stubbing libraries
+-- If Facebook returns nil for search or get_connections requests, Koala now returns nil rather than throwing an exception
+
+v0.8.0
+-- Breaking interface changes
+  -- Removed string overloading for the methods, per 0.7.3, which caused Marshaling issues
+  -- Removed ability to provide a string as the second argument to url_for_access_token, per 0.5.0
+
+v0.7.4 
+-- Fixed bug with get_user_from_cookies
+
+v0.7.3
+-- Added support for picture sizes -- thanks thhermansen for the patch!
+-- Adjusted the return values for several methods (get_access_token, get_app_access_token, get_token_from_session_key, get_tokens_from_session_keys, get_user_from_cookies)
+  -- These methods now return strings, rather than hashes, which makes more sense
+  -- The strings are overloaded with an [] method for backwards compatibility (Ruby is truly amazing)
+    -- Using those methods triggers a deprecation warning
+    -- This will be removed by 1.0
+  -- There are new info methods (get_access_token_info, get_app_access_token_info, get_token_info_from_session_keys, and get_user_info_from_cookies) that natively return hashes, for when you want the expiration date
+-- Responses with HTTP status 500+ now properly throw errors under Net::HTTP 
+-- Updated changelog
+-- Added license
+
+v0.7.2
+-- Added support for exchanging session keys for OAuth access tokens (get_token_from_session_key for single keys, get_tokens_from_session_keys for multiple)
+-- Moved Koala files into a koala/ subdirectory to minimize risk of name collisions
+-- Added OAuth Playground git submodule as an example 
+-- Updated tests, readme, and changelog
+
+v0.7.1
+-- Updated RealtimeUpdates#list_subscriptions and GraphAPI#get_connections to now return an 
+array of results directly (rather than a hash with one key)
+-- Fixed a bug with Net::HTTP-based HTTP service in which the headers hash was improperly formatted
+-- Updated readme
+
+v0.7.0
+-- Added RealtimeUpdates class, which can be used to manage subscriptions for user updates (see http://developers.facebook.com/docs/api/realtime)
+-- Added picture method to graph API, which fetches an object's picture from the redirect headers.
+-- Added _greatly_ improved testing with result mocking, which is now the default set of tests
+-- Renamed live testing spec to koala_spec_without_mocks.rb
+-- Added Koala::Response class, which encapsulates HTTP results since Facebook sometimes sends data in the status or headers
+-- Much internal refactoring
+-- Updated readme, changelog, etc.
+
+
+v0.6.0
+-- Added support for the old REST API thanks to cbaclig's great work
+-- Updated tests to conform to RSpec standards
+-- Updated changelog, readme, etc.
+
+v0.5.1
+-- Documentation is now on the wiki, updated readme accordingly.
+
+v0.5.0
+-- Added several new OAuth methods for making and parsing access token requests
+-- Added test suite for the OAuth class
+-- Made second argument to url_for_access_token a hash (strings still work but trigger a deprecation warning)
+-- Added fields to facebook_data.yml
+-- Updated readme
+
+v0.4.1
+-- Encapsulated GraphAPI and OAuth classes in the Koala::Facebook module for clarity (and to avoid claiming the global Facebook class)
+-- Moved make_request method to Koala class from GraphAPI instance (for use by future OAuth class functionality)
+-- Renamed request method to api for consistancy with Javascript library
+-- Updated tests and readme
+
+v0.4.0
+-- Adopted the Koala name
+-- Updated readme and tests
+-- Fixed cookie verification bug for non-expiring OAuth tokens
+
+v0.3.1
+-- Bug fixes.
+
+v0.3
+-- Renamed Graph API class from Facebook::GraphAPI to FacebookGraph::API
+-- Created FacebookGraph::OAuth class for tokens and OAuth URLs
+-- Updated method for including HTTP service (think we've got it this time) 
+-- Updated tests
+-- Added CHANGELOG and gemspec
+
+v0.2
+-- Gemified the project
+-- Split out HTTP services into their own file, and adjusted inclusion method
+
+v0.1
+-- Added modular support for Typhoeus
+-- Added tests
+
+v0.0
+-- Hi from F8!  Basic read/write from the graph is working

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2010 Alex Koppel
+
+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/Manifest

@@ -0,0 +1,44 @@
+CHANGELOG
+LICENSE
+Manifest
+Rakefile
+examples/oauth_playground/Capfile
+examples/oauth_playground/LICENSE
+examples/oauth_playground/Rakefile
+examples/oauth_playground/config.ru
+examples/oauth_playground/config/deploy.rb
+examples/oauth_playground/config/facebook.yml
+examples/oauth_playground/lib/load_facebook.rb
+examples/oauth_playground/lib/oauth_playground.rb
+examples/oauth_playground/readme.md
+examples/oauth_playground/spec/oauth_playground_spec.rb
+examples/oauth_playground/spec/spec_helper.rb
+examples/oauth_playground/tmp/restart.txt
+examples/oauth_playground/views/index.erb
+examples/oauth_playground/views/layout.erb
+init.rb
+koala.gemspec
+lib/koala.rb
+lib/koala/graph_api.rb
+lib/koala/http_services.rb
+lib/koala/realtime_updates.rb
+lib/koala/rest_api.rb
+readme.md
+spec/facebook_data.yml
+spec/koala/api_base_tests.rb
+spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb
+spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb
+spec/koala/graph_api/graph_api_no_access_token_tests.rb
+spec/koala/graph_api/graph_api_with_access_token_tests.rb
+spec/koala/graph_api/graph_collection_tests.rb
+spec/koala/live_testing_data_helper.rb
+spec/koala/net_http_service_tests.rb
+spec/koala/oauth/oauth_tests.rb
+spec/koala/realtime_updates/realtime_updates_tests.rb
+spec/koala/rest_api/rest_api_no_access_token_tests.rb
+spec/koala/rest_api/rest_api_with_access_token_tests.rb
+spec/koala_spec.rb
+spec/koala_spec_helper.rb
+spec/koala_spec_without_mocks.rb
+spec/mock_facebook_responses.yml
+spec/mock_http_service.rb

data/Rakefile

@@ -0,0 +1,16 @@
+# Rakefile
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+# gem management
+Echoe.new('palidanx-koala', '0.9.0') do |p|
+  p.summary    = "A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation."
+  p.description = "Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services."
+  p.url            = "http://github.com/palidanx/koala"
+  p.author         = ["Alex Koppel", "Chris Baclig", "Rafi Jacoby", "Context Optional"]
+  p.email          = "alex@alexkoppel.com"
+  p.ignore_pattern = ["tmp/*", "script/*", "pkg/*"]
+  p.development_dependencies = []
+  p.retain_gemspec = true
+end

data/init.rb

@@ -0,0 +1,2 @@
+# init.rb
+require 'koala'

data/koala.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{palidanx-koala}
+  s.version = "0.9.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Alex Koppel, Chris Baclig, Rafi Jacoby, Context Optional"]
+  s.date = %q{2010-09-29}
+  s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services.}
+  s.email = %q{alex@alexkoppel.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "Rakefile", "init.rb", "koala.gemspec", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb", "spec/koala/graph_api/graph_api_no_access_token_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/live_testing_data_helper.rb", "spec/koala/net_http_service_tests.rb", "spec/koala/oauth/oauth_tests.rb", "spec/koala/realtime_updates/realtime_updates_tests.rb", "spec/koala/rest_api/rest_api_no_access_token_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala_spec.rb", "spec/koala_spec_helper.rb", "spec/koala_spec_without_mocks.rb", "spec/mock_facebook_responses.yml", "spec/mock_http_service.rb"]
+  s.homepage = %q{http://github.com/palidanx/koala}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Koala", "--main", "readme.md"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{koala}
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/koala.rb

@@ -0,0 +1,296 @@
+require 'cgi'
+require 'digest/md5'
+
+# rubygems is required to support json, how facebook returns data
+require 'rubygems'
+require 'json'
+
+# openssl is required to support signed_request
+require 'openssl'
+
+# include default http services
+require 'koala/http_services'
+
+# add Graph API methods
+require 'koala/graph_api'
+
+# add REST API methods
+require 'koala/rest_api'
+
+require 'koala/realtime_updates'
+
+module Koala
+    
+  module Facebook
+    # Ruby client library for the Facebook Platform.
+    # Copyright 2010 Facebook
+    # Adapted from the Python library by Alex Koppel, Rafi Jacoby, and the team at Context Optional
+    #
+    # Licensed under the Apache License, Version 2.0 (the "License"); you may
+    # not use this file except in compliance with the License. You may obtain
+    # a copy of the License at
+    #     http://www.apache.org/licenses/LICENSE-2.0
+    #
+    # Unless required by applicable law or agreed to in writing, software
+    # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+    # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    # License for the specific language governing permissions and limitations
+    # under the License.
+    # 
+    # This client library is designed to support the Graph API and the official
+    # Facebook JavaScript SDK, which is the canonical way to implement
+    # Facebook authentication. Read more about the Graph API at
+    # http://developers.facebook.com/docs/api. You can download the Facebook
+    # JavaScript SDK at http://github.com/facebook/connect-js/.
+
+    class API
+      # initialize with an access token 
+      def initialize(access_token = nil)
+        @access_token = access_token
+      end
+      
+      def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
+        # Fetches the given path in the Graph API.
+        args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
+
+        # add a leading /
+        path = "/#{path}" unless path =~ /^\//
+
+        # make the request via the provided service
+        result = Koala.make_request(path, args, verb, options)
+        
+        # Check for any 500 errors before parsing the body
+        # since we're not guaranteed that the body is valid JSON
+        # in the case of a server error
+        raise APIError.new({"type" => "HTTP #{result.status.to_s}", "message" => "Response body: #{result.body}"}) if result.status >= 500
+        
+        # Parse the body as JSON and check for errors if provided a mechanism to do so 
+        # Note: Facebook sometimes sends results like "true" and "false", which aren't strictly objects
+        # and cause JSON.parse to fail -- so we account for that by wrapping the result in []
+        body = response = JSON.parse("[#{result.body.to_s}]")[0]
+        if error_checking_block
+          yield(body)
+        end
+        
+        # now return the desired information
+        if options[:http_component]
+          result.send(options[:http_component])
+        else
+          body
+        end
+      end
+    end
+    
+    class GraphAPI < API
+      include GraphAPIMethods
+    end
+    
+    class RestAPI < API
+      include RestAPIMethods
+    end
+    
+    class GraphAndRestAPI < API
+      include GraphAPIMethods
+      include RestAPIMethods
+    end
+    
+    class RealtimeUpdates < API
+      include RealtimeUpdateMethods
+    end
+    
+    class APIError < Exception
+      attr_accessor :fb_error_type
+      def initialize(details = {})
+        self.fb_error_type = details["type"]  
+        super("#{fb_error_type}: #{details["message"]}")
+      end
+    end
+    
+    
+    class OAuth
+      attr_reader :app_id, :app_secret, :oauth_callback_url
+      def initialize(app_id, app_secret, oauth_callback_url = nil)
+        @app_id = app_id
+        @app_secret = app_secret
+        @oauth_callback_url = oauth_callback_url 
+      end
+
+      def get_user_info_from_cookie(cookie_hash)
+        # Parses the cookie set by the official Facebook JavaScript SDK.
+        # 
+        # cookies should be a Hash, like the one Rails provides
+        # 
+        # If the user is logged in via Facebook, we return a dictionary with the
+        # keys "uid" and "access_token". The former is the user's Facebook ID,
+        # and the latter can be used to make authenticated requests to the Graph API.
+        # If the user is not logged in, we return None.
+        # 
+        # Download the official Facebook JavaScript SDK at
+        # http://github.com/facebook/connect-js/. Read more about Facebook
+        # authentication at http://developers.facebook.com/docs/authentication/.
+
+        if fb_cookie = cookie_hash["fbs_" + @app_id.to_s]
+          # remove the opening/closing quote
+          fb_cookie = fb_cookie.gsub(/\"/, "")
+
+          # since we no longer get individual cookies, we have to separate out the components ourselves
+          components = {}
+          fb_cookie.split("&").map {|param| param = param.split("="); components[param[0]] = param[1]}
+
+          # generate the signature and make sure it matches what we expect
+          auth_string = components.keys.sort.collect {|a| a == "sig" ? nil : "#{a}=#{components[a]}"}.reject {|a| a.nil?}.join("")
+          sig = Digest::MD5.hexdigest(auth_string + @app_secret)          
+          sig == components["sig"] && (components["expires"] == "0" || Time.now.to_i < components["expires"].to_i) ? components : nil
+        end
+      end
+      alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
+    
+      def get_user_from_cookie(cookies)
+        if info = get_user_info_from_cookies(cookies)
+          string = info["uid"]
+        end
+      end
+      alias_method :get_user_from_cookies, :get_user_from_cookie
+    
+      # URLs
+    
+      def url_for_oauth_code(options = {})
+        # for permissions, see http://developers.facebook.com/docs/authentication/permissions
+        permissions = options[:permissions]
+        scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
+
+        callback = options[:callback] || @oauth_callback_url
+        raise ArgumentError, "url_for_oauth_code must get a callback either from the OAuth object or in the options!" unless callback
+
+        # Creates the URL for oauth authorization for a given callback and optional set of permissions
+        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}"    
+      end
+        
+      def url_for_access_token(code, options = {})
+        # Creates the URL for the token corresponding to a given code generated by Facebook
+        callback = options[:callback] || @oauth_callback_url
+        raise ArgumentError, "url_for_access_token must get a callback either from the OAuth object or in the parameters!" unless callback
+        "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
+      end
+            
+      def get_access_token_info(code)
+        # convenience method to get a parsed token from Facebook for a given code
+        # should this require an OAuth callback URL?
+        get_token_from_server(:code => code, :redirect_uri => @oauth_callback_url)
+      end
+      
+      def get_access_token(code)
+        # upstream methods will throw errors if needed
+        if info = get_access_token_info(code) 
+          string = info["access_token"]        
+        end
+      end
+      
+      def get_app_access_token_info
+        # convenience method to get a the application's sessionless access token 
+        get_token_from_server({:type => 'client_cred'}, true)
+      end
+      
+      def get_app_access_token
+        if info = get_app_access_token_info
+          string = info["access_token"] 
+        end
+      end
+      
+      # signed_request
+      def parse_signed_request(request)
+        # Facebook's signed requests come in two parts -- the signature and the data payload
+        # see http://developers.facebook.com/docs/authentication/canvas
+        encoded_sig, payload = request.split(".")
+        
+        sig = base64_url_decode(encoded_sig)
+
+        # if the signature matches, return the data, decoded and parsed as JSON
+        if OpenSSL::HMAC.digest("sha256", @app_secret, payload) == sig
+          JSON.parse(base64_url_decode(payload))
+        else
+          nil
+        end
+      end
+
+      # from session keys
+      def get_token_info_from_session_keys(sessions)
+        # fetch the OAuth tokens from Facebook
+        response = fetch_token_string({
+          :type => 'client_cred',
+          :sessions => sessions.join(",")
+        }, true, "exchange_sessions")
+        
+        # Facebook returns an empty body in certain error conditions
+        if response == "" 
+          raise APIError.new("ArgumentError", "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!")
+        end
+        
+        JSON.parse(response)
+      end
+  
+      def get_tokens_from_session_keys(sessions)
+        # get the original hash results
+        results = get_token_info_from_session_keys(sessions)
+        # now recollect them as just the access tokens
+        results.collect { |r| r ? r["access_token"] : nil }
+      end
+      
+      def get_token_from_session_key(session)
+        # convenience method for a single key
+        # gets the overlaoded strings automatically
+        get_tokens_from_session_keys([session])[0]
+      end
+      
+      protected
+      
+      def get_token_from_server(args, post = false)
+        # fetch the result from Facebook's servers
+        result = fetch_token_string(args, post)
+        
+        # if we have an error, parse the error JSON and raise an error
+        raise APIError.new((JSON.parse(result)["error"] rescue nil) || {}) if result =~ /error/
+
+        # otherwise, parse the access token
+        parse_access_token(result)       
+      end
+      
+      def parse_access_token(response_text)
+        components = response_text.split("&").inject({}) do |hash, bit|
+          key, value = bit.split("=")
+          hash.merge!(key => value)
+        end
+        components 
+      end
+
+      def fetch_token_string(args, post = false, endpoint = "access_token")
+        Koala.make_request("/oauth/#{endpoint}", {
+          :client_id => @app_id, 
+          :client_secret => @app_secret
+        }.merge!(args), post ? "post" : "get").body
+      end
+      
+      # base 64
+      def base64_url_decode(string)
+        # to properly decode what Facebook provides, we need to add == to the end
+        # and translate certain characters to others before running the actual decoding
+        # see http://developers.facebook.com/docs/authentication/canvas 
+        "#{string}==".tr("-_", "+/").unpack("m")[0]
+      end
+    end
+  end
+  
+  # finally, set up the http service Koala methods used to make requests
+  # you can use your own (for HTTParty, etc.) by calling Koala.http_service = YourModule
+  def self.http_service=(service)
+    self.send(:include, service)
+  end
+
+  # by default, try requiring Typhoeus -- if that works, use it
+  begin
+    require 'typhoeus'
+    Koala.http_service = TyphoeusService
+  rescue LoadError
+    Koala.http_service = NetHTTPService
+  end
+end