koala 0.8.0 → 0.9.0

data/CHANGELOG

@@ -1,3 +1,13 @@
+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

data/Manifest

@@ -2,6 +2,20 @@ 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
@@ -16,6 +30,7 @@ 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

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake'
 require 'echoe'
 
 # gem management
-Echoe.new('koala', '0.8.0') do |p|
+Echoe.new('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/arsduo/koala"

data/examples/oauth_playground/Capfile

@@ -0,0 +1,2 @@
+load 'deploy' if respond_to?(:namespace) # cap2 differentiator
+load 'config/deploy' # remove this line to skip loading any of the default tasks

data/examples/oauth_playground/LICENSE

@@ -0,0 +1,22 @@
+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/examples/oauth_playground/Rakefile

@@ -0,0 +1,4 @@
+namespace :oauth_playground do
+  
+  
+end

data/examples/oauth_playground/config.ru

@@ -0,0 +1,27 @@
+# gems
+require 'sinatra'
+require 'logger'
+require 'yaml'
+
+# app files
+require 'koala'
+require File.join(File.dirname(__FILE__), 'lib', 'load_facebook.rb')
+require File.join(File.dirname(__FILE__), 'lib', 'oauth_playground.rb')
+
+# LOGGING
+# set up the logfile
+Dir.mkdir('log') unless File.exists?('log')
+log_filename = File.join(File.dirname(__FILE__), "log", "sinatra.log")
+log = File.new(log_filename, "a+")
+
+# log requests
+use Rack::CommonLogger, log 
+# log application-generated code
+LOGGER = Logger.new(log_filename) 
+# log output to stdout and stderr as well
+$stdout.reopen(log)
+$stderr.reopen(log)
+
+# activate the app
+disable :run
+run OAuthPlayground

data/examples/oauth_playground/config/deploy.rb

@@ -0,0 +1,39 @@
+set :application, "oauth_playground"
+set :repository,  "git://github.com/arsduo/oauth_playground.git"
+set :domain, "oauth.twoalex.com"
+set :deploy_to, "$HOME/rails_apps/#{application}/"
+
+# authentication
+set :scm, "git"
+set :user, "alexkm"
+set :use_sudo, false
+ssh_options[:forward_agent] = true
+
+# web server
+role :web, "oauth.twoalex.com"                          # Your HTTP server, Apache/etc
+role :app, "oauth.twoalex.com"                          # This may be the same as your `Web` server
+role :db,  "oauth.twoalex.com", :primary => true  # This is where Rails migrations will run
+
+
+# other git-related commands
+set :branch, "master"
+default_run_options[:pty] = true
+# cache the repository locally to speed updates
+set :repository_cache, "git_cache" 
+set :deploy_via, :remote_cache
+
+
+# passenger-specific deploy tasks
+namespace :deploy do
+  task :start do
+    run "#{try_sudo} touch #{File.join(current_path,'tmp','restart.txt')}"
+  end
+  
+  task :stop do
+    # nothing
+  end
+  
+  task :restart, :roles => :app, :except => { :no_release => true } do
+    run "touch #{File.join(current_path,'tmp','restart.txt')}"
+  end
+end

data/examples/oauth_playground/config/facebook.yml

@@ -0,0 +1,13 @@
+development:
+  api_key: 171e3563d4fee42e0ba27450838bba32
+  secret_key: c81302ccef57cbdd2e68b2229e54cd2f
+  app_id: 119347844754245
+
+test:
+  api_key: 
+  secret_key: 
+
+production:
+  api_key: 25e1cec0df2b3bfa781da3ed78da3a1e
+  secret_key: e45e55a333eec232d4206d2703de1307
+  app_id: 119908831367602

data/examples/oauth_playground/lib/load_facebook.rb

@@ -0,0 +1,3 @@
+# load Facebook info for this environment
+FACEBOOK_INFO = YAML.load_file(File.join(File.dirname(__FILE__), "..", "config", "facebook.yml"))[ENV["RACK_ENV"]]
+

data/examples/oauth_playground/lib/oauth_playground.rb

@@ -0,0 +1,187 @@
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+require 'rubygems'
+require 'sinatra'
+require 'erb'
+
+class OAuthPlayground < Sinatra::Application
+  
+  set :root, APP_ROOT  
+
+  include Koala
+
+  layout :layout
+
+  get "/" do
+    @app_data = FACEBOOK_INFO.merge("callback_url" => "#{request.scheme}://#{request.host}/")
+    @oauth = Facebook::OAuth.new(@app_data["app_id"], @app_data["secret_key"], @app_data["callback_url"])
+    
+    # get authentication info
+    set_facebook_cookies 
+    set_oauth_data
+    set_access_token
+    
+    unless (@permissions = params[:permissions]) && @permissions.length > 0
+      @active_permissions = (get_active_permissions || {}).inject([]) do |active, perm| 
+        # collect our active permissions
+        active << perm[0].to_sym if perm[1] == 1
+        active
+      end
+      @fetched_permissions = true
+    else
+      @active_permissions = @permissions.collect {|p| p.to_sym}
+    end
+        
+    @available_permissions = [
+      {:name => "User Activity", :perms => ACTIVITY_PERMISSIONS},
+      {:name => "User Info", :perms => USER_PERMISSIONS},
+      {:name => "Friend Info", :perms => FRIEND_PERMISSIONS}
+    ]
+  
+    erb :index
+  end
+  
+  get "/subscriptions" do
+    # validate that this is a valid response
+    # it will automatically render the result of the verification
+    # e.g. either the challenge phrase or false
+    subscription = Facebook::RealtimeUpdates.meet_challenge(params) do |verification_token|
+      token_parts = verification_token.split("|")
+      expected = Digest::MD5.hexdigest("#{token_parts.first}~koala")
+      logger.info "expected: #{expected}"
+      logger.info "got: #{token_parts.last}"
+      # determine if this is a valid token -- that is, if the send part is a properly encoding of the first
+      expected == token_parts.last
+    end
+  end
+  
+  helpers do
+    def logger
+      LOGGER
+    end 
+  end
+
+  # helpers
+
+  # set up our understanding of the user's session
+  
+  def set_access_token
+    # get the access token from wherever we can
+    @access_token ||= (set_oauth_data && @oauth_access_token) || (set_facebook_cookies && @cookie_access_token)
+  end
+  
+  def set_oauth_data
+    unless @oauth_access_token
+      if (@code = params[:code]) && @raw_access_response = @oauth.send(:fetch_token_string, {:code => @code, :redirect_uri => @app_data["callback_url"]})
+        parsed = @oauth.send(:parse_access_token, @raw_access_response)
+        @oauth_access_token = parsed["access_token"]
+        @expiration = parsed["expires"] || "Does not expire (offline)"
+      end
+    end
+    
+    @oauth_access_token
+  end
+  
+  def set_facebook_cookies
+    unless @facebook_cookies
+      if @facebook_cookies = @oauth.get_user_from_cookie(request.cookies)
+        @cookie_access_token = @facebook_cookies["access_token"]
+      end
+    end
+    
+    @facebook_cookies
+  end
+  
+  def set_uid
+    # get the OAuth data, including fetching the access token, if available and necessary
+    # e.g. if we have an OAuth token and no cookie data    
+    unless @uid 
+      if @facebook_cookies
+        @uid = @facebook_cookies["uid"]
+      elsif token = set_access_token
+        # we have to fetch the info
+        @graph = Facebook::GraphAPI.new(token)
+        result = @graph.get_object("me")
+        @uid = result["id"]
+      end
+    end
+    @uid
+  end
+  
+  # fetch the active permissions about the user    
+  def get_active_permissions
+    set_access_token
+    if @access_token && !@permissions && set_uid
+      # if we don't have permissions set but have an access token
+      # grab the user's info
+      @rest = Facebook::RestAPI.new(@access_token)      
+      result = @rest.fql_query("select #{all_permissions.join(",")} from permissions where uid = #{@uid.to_s}")
+      result.first
+    end  
+  end
+  
+  # list of permissions
+
+  def all_permissions
+    ACTIVITY_PERMISSIONS + USER_PERMISSIONS + FRIEND_PERMISSIONS
+  end
+  
+  ACTIVITY_PERMISSIONS = [
+    :publish_stream, # Enables your application to post content, comments, and likes to a user's stream and to the streams of the user's friends, without prompting the user each time.
+    :create_event, # Enables your application to create and modify events on the user's behalf
+    :rsvp_event, # Enables your application to RSVP to events on the user's behalf
+    :sms, # Enables your application to send messages to the user and respond to messages from the user via text message
+    :offline_access # Enables your application to perform authorized requests on behalf of the user at any time. By default, most access tokens expire after a short time period to ensure applications only make requests on behalf of the user when the are actively using the application. This permission makes the access token returned by our OAuth endpoint long-lived.
+  ]
+
+  USER_PERMISSIONS = [
+    :email, # Provides access to the user's primary email address in the email property. Do not spam users. Your use of email must comply both with Facebook policies and with the CAN-SPAM Act.
+    :read_insights, # Provides read access to the Insights data for pages, applications, and domains the user owns.
+    :read_stream, # Provides access to all the posts in the user's News Feed and enables your application to perform searches against the user's News Feed
+    :user_about_me, # Provides access to the "About Me" section of the profile in the about property
+    :user_activities, # Provides access to the user's list of activities as the activities connection
+    :user_birthday, # Provides access to the full birthday with year as the birthday_date property
+    :user_education_history, # Provides access to education history as the education property
+    :user_events, # Provides access to the list of events the user is attending as the events connection
+    :user_groups, # Provides access to the list of groups the user is a member of as the groups connection
+    :user_hometown, # Provides access to the user's hometown in the hometown property
+    :user_interests, # Provides access to the user's list of interests as the interests connection
+    :user_likes, # Provides access to the list of all of the pages the user has liked as the likes connection
+    :user_location, # Provides access to the user's current location as the current_location property
+    :user_notes, # Provides access to the user's notes as the notes connection
+    :user_online_presence, # Provides access to the user's online/offline presence
+    :user_photo_video_tags, # Provides access to the photos the user has been tagged in as the photos connection
+    :user_photos, # Provides access to the photos the user has uploaded
+    :user_relationships, # Provides access to the user's family and personal relationships and relationship status
+    :user_religion_politics, # Provides access to the user's religious and political affiliations
+    :user_status, # Provides access to the user's most recent status message
+    :user_videos, # Provides access to the videos the user has uploaded
+    :user_website, # Provides access to the user's web site URL
+    :user_work_history # Provides access to work history as the work property
+  ]
+  
+  FRIEND_PERMISSIONS = [
+    :read_friendlists, # Provides read access to the user's friend lists
+    :read_requests, # Provides read access to the user's friend requests
+    :friends_about_me, # Provides access to the "About Me" section of the profile in the about property
+    :friends_activities, # Provides access to the user's list of activities as the activities connection
+    :friends_birthday, # Provides access to the full birthday with year as the birthday_date property
+    :friends_education_history, # Provides access to education history as the education property
+    :friends_events, # Provides access to the list of events the user is attending as the events connection
+    :friends_groups, # Provides access to the list of groups the user is a member of as the groups connection
+    :friends_hometown, # Provides access to the user's hometown in the hometown property
+    :friends_interests, # Provides access to the user's list of interests as the interests connection
+    :friends_likes, # Provides access to the list of all of the pages the user has liked as the likes connection
+    :friends_location, # Provides access to the user's current location as the current_location property
+    :friends_notes, # Provides access to the user's notes as the notes connection
+    :friends_online_presence, # Provides access to the user's online/offline presence
+    :friends_photo_video_tags, # Provides access to the photos the user has been tagged in as the photos connection
+    :friends_photos, # Provides access to the photos the user has uploaded
+    :friends_relationships, # Provides access to the user's family and personal relationships and relationship status
+    :friends_religion_politics, # Provides access to the user's religious and political affiliations
+    :friends_status, # Provides access to the user's most recent status message
+    :friends_videos, # Provides access to the videos the user has uploaded
+    :friends_website, # Provides access to the user's web site URL
+    :friends_work_history # Provides access to work history as the work property
+  ]
+end

data/examples/oauth_playground/readme.md

@@ -0,0 +1,8 @@
+A simple OAuth Playground chock full of the info you need to test your OAuth-based Facebook application.
+
+To Do's
+=======
+
+* Extend the permissions controls to cover all available permissions
+* Make expiration dates human-readable
+* Let people plug in their own app (updating the app's connect properties through setAppProperties)

data/examples/oauth_playground/spec/oauth_playground_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+require 'ruby-debug'
+
+describe 'OAuthPlayground' do
+  before :each do
+    @hydra = Typhoeus::Hydra.hydra
+  end
+  
+  after :each do 
+    @hydra.clear_stubs
+  end
+  
+  it 'should load the index' do
+    get '/'
+    last_response.should be_ok
+  end
+
+=begin  
+  # unfortunately, this fails when you pass the get method a param named code!
+  # fixing this will require some mucking around in Rack::Test
+  
+  it "should make a request to Facebook's OAuth server when passed a code" do 
+    test_string = Regexp.new("The time is #{Time.now.to_i}")
+
+    # stub out the request and make sure it's returned
+    @hydra.stub("https://#{Koala::Facebook::GRAPH_SERVER}/oauth/access_token", "get").and_return(test_string)
+    
+    get "/", {"code" => "foo_bar"}
+
+    # make sure the body includes the request string
+    last_response.body.should =~ test_string
+  end
+=end
+end
+

data/examples/oauth_playground/spec/spec_helper.rb

@@ -0,0 +1,36 @@
+require 'rubygems'
+require 'sinatra'
+require 'rack/test'
+require 'typhoeus'
+require 'koala'
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'oauth_playground.rb')
+require File.join(File.dirname(__FILE__), '..', 'lib', 'load_facebook.rb')
+
+OAuthPlayground.set(
+  :environment => :test,
+  :run => false,
+  :raise_errors => true,
+  :logging => false
+)
+
+module TestHelper
+  
+  def app
+    # change to your app class if using the 'classy' style
+    OAuthPlayground
+  end
+  
+  def body
+    last_response.body
+  end
+  
+  def status
+    last_response.status
+  end
+  
+  include Rack::Test::Methods
+
+end
+
+include TestHelper