rest-more 0.8.0 → 1.0.0

data/Rakefile

@@ -14,7 +14,7 @@ task 'gem:spec' do
     s.version  = RestMore::VERSION
     s.homepage = 'https://github.com/cardinalblue/rest-more'
 
-    %w[rest-core].each{ |g| s.add_runtime_dependency(g) }
+    %w[rest-core].each{ |g| s.add_runtime_dependency(g, '>=1.0.0') }
 
     s.authors  = ['Cardinal Blue', 'Lin Jen-Shin (godfat)']
     s.email    = ['dev (XD) cardinalblue.com']

data/TODO.md

@@ -1,14 +1,4 @@
 # TODO
 
-## high
-
-* middleware revisit (how to initialize?)
-
-## medium
-
-* what about async request? yield callback? coroutine?
-* dependency?
-
-## low
-
-* test utility
+* document about how to migrate from rest-graph to rest-more
+* more tests

data/doc/ToC.md

@@ -0,0 +1,9 @@
+
+# rest-more documentation
+
+## Table of Content
+
+* [Facebook tutorial for the beginners, using Rails 3](tutorial/facebook.md)
+* [Migrate from rest-graph](rest-graph.md)
+* [Overview and Design Concept](design.md)
+* [Picking Dependency](dependency.md)

data/doc/dependency.md

@@ -0,0 +1,4 @@
+
+# Picking Dependency
+
+

data/doc/design.md

@@ -0,0 +1,4 @@
+
+# Overview and Design Concept
+
+

data/doc/rest-graph.md

@@ -0,0 +1,4 @@
+
+# Migrate from rest-graph
+
+

data/doc/tutorial/facebook.md

@@ -0,0 +1,173 @@
+# How to build a Facebook application within Rails 3 using the rest-more gem
+
+1. Before you start, I strongly recommend reading these:
+
+    * Apps on Facebook.com -> <http://developers.facebook.com/docs/guides/canvas/>
+    * Graph API -> <http://developers.facebook.com/docs/reference/api/>
+    * Authentication -> <http://developers.facebook.com/docs/authentication/>
+    * Heroku: Building a Facebook Application -> <http://devcenter.heroku.com/articles/facebook/>
+
+
+2. Go to [FB Developers website](http://facebook.com/developers) and create a new FB app. Set its canvas name, canvas url and your site URL. Make sure the canvas type is set to "iframe" (which should be the case by default).
+
+
+3. Build a new Rails application.
+
+    ``` shell
+        rails new <name>
+    ```
+
+4. Declare rest-more and its dependencies in the Gemfile. Add these lines:
+
+    ``` ruby
+        gem 'rest-more'
+
+        # these gems are used in rest-more
+        gem 'json' # you may also use other JSON parsers/generators, i.e. 'yajl-ruby' or 'json_pure'
+    ```
+
+    And run:
+
+    ``` shell
+        bundle install
+    ```
+
+5. In order to configure your Rails application for the Facebook application you created, you must create a `rest-core.yaml` file in your /config directory and fill it with your Facebook configuration. If you plan to run your application in the Facebook canvas, also provide a canvas name.
+
+    Example:
+
+    ``` yaml
+        development:
+          facebook:
+            app_id: 'XXXXXXXXXXXXXX'
+            secret: 'YYYYYYYYYYYYYYYYYYYYYYYYYYY'
+            callback_host: 'my.dev.host.com'
+
+        production:
+          facebook:
+            app_id: 'XXXXXXXXXXXXXX'
+            secret: 'YYYYYYYYYYYYYYYYYYYYYYYYYYY'
+            canvas: 'yourcanvasname'
+            callback_host: 'my.production.host.com'
+    ```
+
+   If you push to Heroku, your production callback_host should be `yourappname.heroku.com`. You can also access your app directly running `rails server` (or just `rails s`) in your console, but if you do not have an external IP address (e.g. you are behind a NAT), you will need to use a service called a tunnel in order to make your application accessible to the outer world (and Facebook callbacks). You'll find more information on setting up a tunnel here: <http://tunnlr.com/>.
+
+6. Let's create a first controller for your app - ScratchController.
+
+    ``` shell
+        rails generate controller Scratch
+    ```
+
+7. The next step will be to include rest-more in your controller. You should put this line in:
+
+    ``` ruby
+        include RC::Facebook::RailsUtil
+    ```
+
+     Now you can make use of the rest-more commands :)
+
+8. To actually use rest-more in a controller action, you will need to first call "rc_facebook_setup", which reads the configuration from the rest-core.yaml and creates a Facebook client.   Let's set this up in a before_filter.
+
+    Add this line after the `include RestGraph::RailsUtil`:
+
+    ``` ruby
+        before_filter :filter_setup_facebook
+    ```
+
+    And declare filter_setup_facebook as a private function:
+
+    ``` ruby
+        private
+        def filter_setup_facebook
+          rc_facebook_setup(:auto_authorize => true)
+        end
+    ```
+
+    The `:auto_authorize` argument of `rc_facebook_setup` tells rest-more to redirect users to the app authorization page if the app is not authorized yet.
+
+    Hooray! You can now perform all kinds of Graph API operations using the Facebook client.
+
+9. Let's start with following sample action in the Scratch controller:
+
+    ``` ruby
+        def me
+          render :text => rc_facebook.get('me').inspect
+        end
+    ```
+
+10. To run this, go to the /config/routes.rb file to set up the default routing. For now you will just need this line:
+
+    ``` ruby
+        match ':controller/:action'
+    ```
+
+11. Commit your change in git, and then push to Heroku:
+
+    ``` shell
+        git add .
+        git commit -m "first test of rest-more using scratch/me"
+        git push heroku master
+    ```
+
+    After you push your app to Heroku, you can open <http://yourappname.heroku.com/scratch/me> in your browser. If you are not yet logged into Facebook, it will ask you to log in.  If you are logged in your Facebook account, this address should redirect you to the authorization page and ask if you want to let your application access your public information. After you confirm, you should be redirected back to 'scratch/me' action which will show your basic information.
+
+12. To see other information, such as your home feed, is very easy. You can add another sample action to your controller:
+
+    ``` ruby
+        def feed
+          render :text => rc_facebook.get('me/home').inspect
+        end
+    ```
+
+    If you will push the changes to Heroku and go to <http://yourappname.heroku.com/scratch/feed>, the page should display a JSON hash with all the data from your Facebook home feed.
+
+
+13. Now let's try to access your Facebook wall. You need to add a new action to your controller:
+
+    ``` ruby
+        def wall
+          render :text => rc_facebook.get('me/feed').inspect
+        end
+    ```
+
+    Note that Facebook's naming is such that your home news feeds is accessed via `me/home` and your profile walls is accessed via `me/feed` ...
+
+    Actually, I need to warn you that this time the action won't work properly. Why? Because users didn't grant you the permission to access their walls! You need to ask them for this special permission and that means you need to add something more to your controller.
+
+    So, we will organize all the permissions we need as a scope and pass them to the `rc_facebook_setup` call. I find it handy to make the scope array and declare what kind of permissions I need just inside this array. If you feel it's a good idea, you can add this line to your private setup function, just before you call `rc_facebook_setup`:
+
+    ``` ruby
+        scope = []
+        scope << 'read_stream'
+    ```
+
+    The only permission you need right now is the 'read_stream' permission. You can find out more about different kinds of user permissions here: <http://developers.facebook.com/docs/authentication/permissions/>
+
+    You also need to add the `auto_authorize_scope` argument to the `rc_facebook_setup`. It will look this way now:
+
+    ``` ruby
+        rc_facebook_setup(:auto_authorize => true, :auto_authorize_scope => scope.join(','))
+    ```
+
+    As you see, you might as well pass the argument like this `:auto_authorize_scope => 'read_stream'`, but once you have to get a lot of different permissions, it's very useful to put them all in an array, because it's more readable and you can easily delete or comment out any one of them.
+
+    Now save your work and push it to Heroku or just try in your tunneled development environment. /scratch/wall URL should give you the hash with user's wall data now!
+
+    Remember. Anytime you need to get data of a new kind, you need to ask user for a certain permission first and that means you need to declare this permission in your scope array!
+
+14. What else? If you know how to deal with hashes then you will definitely know how to get any kind of data you want using the rest_graph object. Let's say you want to get a last object from a user's wall (last in terms of time, last posted, so the first on the wall and therefore first to Ruby). Let's take a look at the /scratch/feed page. The hash which is printed on this page has 2 keys - data and paging. Let's leave the paging key aside. What's more interesting here comes as a value of 'data'. So the last object in any user's wall will be simply:
+
+    ``` ruby
+        rc_facebook.get('me/feed')['data'].first
+    ```
+
+    Now let's say you want only to keep the name of the author of this particular object. You can get it by using:
+
+    ``` ruby
+        rc_facebook.get('me/feed')['data'].first['from']['name']
+    ```
+
+    That's it!
+
+15. More information on customizing rest-more and its functions are to be found here: <https://github.com/cardinalblue/rest-more>

data/example/async.rb

@@ -0,0 +1,89 @@
+
+require 'rest-more'
+
+# RC::Builder.default_app = RC::Auto # for global default_app setting
+
+def aget_facebook opts={}
+  RC::Facebook.new(opts).get('4'){ |response|
+    if response.kind_of?(::Timeout::Error)
+      puts "TIMEOUT aget"
+    else
+      p response
+      puts "DONE aget"
+    end
+    yield if block_given?
+  }
+end
+
+def get_facebook opts={}
+  p RC::Facebook.new(opts).get('4')
+  puts "DONE get"
+rescue Timeout::Error
+  puts "TIMEOUT get"
+end
+
+
+
+puts "RC::CoolioAsync"
+RC::Facebook.builder.default_app = RC::CoolioAsync
+aget_facebook(:timeout => 0.01)
+aget_facebook(:timeout => 10.0)
+Coolio::Loop.default.run
+puts
+
+
+
+puts "RC::CoolioFiber"
+RC::Facebook.builder.default_app = RC::CoolioFiber
+Fiber.new{ get_facebook(:timeout => 0.01) }.resume
+Fiber.new{ get_facebook(:timeout => 10.0) }.resume
+Coolio::Loop.default.run
+puts
+
+
+
+puts "RC::Coolio"
+RC::Facebook.builder.default_app = RC::Coolio
+aget_facebook(:timeout => 0.01)
+aget_facebook(:timeout => 10.0)
+Fiber.new{ get_facebook(:timeout => 0.01) }.resume
+Fiber.new{ get_facebook(:timeout => 10.0) }.resume
+Coolio::Loop.default.run
+puts
+
+
+
+puts "RC::EmHttpRequestAsync"
+RC::Facebook.builder.default_app = RC::EmHttpRequestAsync
+EM.run{ aget_facebook(:timeout => 0.01){ EM.stop } }
+EM.run{ aget_facebook(:timeout => 10.0){ EM.stop } }
+puts
+
+
+
+puts "RC::EmHttpRequestFiber"
+RC::Facebook.builder.default_app = RC::EmHttpRequestFiber
+EM.run{ Fiber.new{ get_facebook(:timeout => 0.01); EM.stop }.resume }
+EM.run{ Fiber.new{ get_facebook(:timeout => 10.0); EM.stop }.resume }
+puts
+
+
+
+puts "RC::Auto for Coolio"
+RC::Facebook.builder.default_app = RC::Auto
+Coolio::TimerWatcher.new(1).attach(Coolio::Loop.default).on_timer{detach}
+aget_facebook(:timeout => 0.01)
+aget_facebook(:timeout => 10.0)
+Fiber.new{ get_facebook(:timeout => 0.01) }.resume
+Fiber.new{ get_facebook(:timeout => 10.0) }.resume
+Coolio::Loop.default.run
+puts
+puts "RC::Auto for EventMachine"
+EM.run{ aget_facebook(:timeout => 0.01){ EM.stop } }
+EM.run{ aget_facebook(:timeout => 10.0){ EM.stop } }
+EM.run{ Fiber.new{ get_facebook(:timeout => 0.01); EM.stop }.resume }
+EM.run{ Fiber.new{ get_facebook(:timeout => 10.0); EM.stop }.resume }
+puts
+puts "RC::Auto for RestClient"
+get_facebook(:timeout => 0.01)
+get_facebook(:timeout => 10.0)

data/example/facebook.rb

@@ -0,0 +1,13 @@
+
+require 'rest-more'
+require 'eventmachine'
+
+RestCore::Builder.default_app = RestCore::EmHttpRequest
+
+EM.run{
+  Fiber.new{
+    p RestCore::Facebook.new.get('4')
+    EM.stop
+  }.resume
+  puts "It's not blocking..."
+}

data/example/multi.rb

@@ -0,0 +1,28 @@
+
+require 'rest-more'
+require 'eventmachine'
+RestCore::EmHttpRequest # there might be a autoload bug?
+                        # omitting this line would cause
+                        # stack level too deep (SystemStackError)
+
+RestCore::Builder.default_app = RestCore::Auto
+facebook = RestCore::Facebook.new(:log_method => method(:puts))
+
+EM.run{
+  Fiber.new{
+    fiber = Fiber.current
+    result = {}
+    facebook.get('4'){ |response|
+      result[0] = response
+      fiber.resume(result) if result.size == 2
+    }
+    puts "It's not blocking..."
+    facebook.get('4'){ |response|
+      result[1] = response
+      fiber.resume(result) if result.size == 2
+    }
+    p Fiber.yield
+    EM.stop
+  }.resume
+  puts "It's not blocking..."
+}

data/example/rails3/Gemfile

@@ -1,7 +1,7 @@
 
 source 'http://rubygems.org'
 
-gem 'rails', '3.0.9'
+gem 'rails', '3.2.1'
 
 gem 'rest-client' # for rest-core
 gem 'rest-core', :path => '../../rest-core'

data/example/rainbows.rb

@@ -0,0 +1,40 @@
+
+worker_processes 4 # assuming four CPU cores
+preload_app      true
+
+Rainbows! do
+  use :EventMachine, :em_client_class => lambda{
+    RainbowsEventMachineFiberClient
+  }
+  worker_connections        100
+
+  client_max_body_size      20*1024*1024 # 20 megabytes
+  client_header_buffer_size  8*1024      #  8 kilobytes
+end
+
+require 'rest-core'
+::RC::Builder.default_app = ::RC::Auto
+
+class RainbowsEventMachineFiberClient < Rainbows::EventMachine::Client
+  def app_call input
+    Fiber.new{ super }.resume
+  end
+end
+
+# monkey patch eventmachine to ignore errors and report them,
+# instead of crashing!!
+module ::EventMachine
+  class << self
+    alias_method :crashing_stop, :stop
+  end
+
+  def self.stop
+    if @wrapped_exception
+      $stderr.puts("WARN: #{@wrapped_exception.inspect}: " \
+                   "#{@wrapped_exception.backtrace.inspect}")
+      @wrapped_exception = nil
+    else
+      crashing_stop
+    end
+  end
+end

data/example/simple.rb

@@ -0,0 +1,8 @@
+
+require 'rest-more'
+
+p RestCore::Twitter.new.statuses('_cardinalblue').first # get user tweets
+puts
+p RestCore::Github.new.get('users/cardinalblue')        # get user info
+puts
+p RestCore::Facebook.new.get('4') # get user info

data/lib/rest-core/client/bing.rb

@@ -13,7 +13,15 @@ RestCore::Bing = RestCore::Builder.client(:AppId) do
   use s::CommonLogger  , nil
   use s::Cache         , nil, 600 do
     use s::ErrorHandler,  lambda{ |env|
-                            raise ::RestCore::Bing::Error.call(env) }
+      if env[s::ASYNC]
+        if env[s::RESPONSE_BODY].kind_of?(::Exception)
+          env
+        else
+          env.merge(s::RESPONSE_BODY => ::RestCore::Bing::Error.call(env))
+        end
+      else
+        raise ::RestCore::Bing::Error.call(env)
+      end}
     use s::ErrorDetector, lambda{ |env|
       if        env[s::RESPONSE_BODY].kind_of?(Hash) &&
          (res = env[s::RESPONSE_BODY]['SearchResponse']).kind_of?(Hash)
@@ -36,17 +44,17 @@ class RestCore::Bing::Error < RestCore::Error
   class ServiceTemporarilyUnavailable < Bing::Error; end
   class SourceTypeError               < Bing::Error; end
 
-  attr_reader :error, :url
-  def initialize error, url=''
-    @error, @url = error, url
-    super("#{error.inspect} from #{url}")
+  attr_reader :error, :code, :url
+  def initialize error, code, url=''
+    @error, @code, @url = error, code, url
+    super("[#{code}] #{error.inspect} from #{url}")
   end
 
   def self.call env
     error, url = env[RESPONSE_BODY], Middleware.request_uri(env)
     code       = extract_error_code(error)
 
-    return new(env[FAIL], url) unless code
+    return new(error, code, url) unless code
 
     case code
     when 1001; MissingParameter
@@ -58,7 +66,7 @@ class RestCore::Bing::Error < RestCore::Error
     when 3001; ResultsTemporarilyUnavailable
     when 3002; ServiceTemporarilyUnavailable
     when 4001; SourceTypeError
-    end.new(error, url)
+    end.new(error, code, url)
   end
 
   def self.extract_error_code error