rest-more 0.8.0 → 1.0.0

data/.travis.yml

@@ -1,4 +1,5 @@
-script: 'git submodule update --init; bundle exec rake test:travis'
+before_install: 'git submodule update --init'
+script: 'bundle exec rake test:travis'
 
 env:
   - 'RESTMORE=rest-more'
@@ -11,4 +12,5 @@ rvm:
   - 1.9.3
   - rbx-18mode
   - rbx-19mode
-  - jruby
+  - jruby-18mode
+  - jruby-19mode

data/CHANGES.md

@@ -1,32 +1,52 @@
 # CHANGES
 
+## rest-more 1.0.0 -- 2012-03-17
+
+### Enhancement
+
+All clients are now asynchrony-aware. Asynchrony support is added in
+rest-core >=1.0.0. Whenever you pass a callback block, the response
+would then be passed to the block. Error handling is different, too.
+In synchronous style, usually an exception would be raised, but in
+asynchronous style, the exception would be passed to the block instead
+of being raised.
+
+* [`Dropbox`] Added Dropbox support.
+* [`Bing::Error`] Added `code` method to get the original error code.
+* [`Twitter::Error`] Added `code` method to get HTTP status code.
+* [`Facebook::Error`] Instead of passing `[true]`, pass error messages.
+* [`Facebook`] Pages related API is reimplemented. Passing a block would
+  result a serious call to the callback block, ending with a nil.
+* [`Config`] Make sure the default attributes module is there even if
+  the config file isn't presented.
+
 ## rest-more 0.8.0 -- 2011-11-29
 
 ### Incompatible changes
 
-* [Facebook::RailsUtil] Some methods are renamed. For example,
+* [`Facebook::RailsUtil`] Some methods are renamed. For example,
   `rc_facebook_write_rg_fbs` is renamed to `rc_facebook_write_fbs`.
   All renamed methods are considered private, so we're not listing them here.
 
-* [Facebook::RailsUtil] `rc_facebook_storage_key` is changed to:
+* [`Facebook::RailsUtil`] `rc_facebook_storage_key` is changed to:
   `"rc_facebook_#{rc_facebook.app_id}"`, your users might need to
   login again in order to save the access_token into the new place.
 
 ### Bugs fixes
 
-* [Github] Fixed usage of Oauth2Query.
+* [`Github`] Fixed usage of `Oauth2Query`.
 
-* [Facebook] Now we're using POST in `authorize!` to exchange the
+* [`Facebook`] Now we're using POST in `authorize!` to exchange the
   access_token with the code instead of GET. If we're using GET,
   we would run into a risk where a user might use the code to
   get other people's access_token via the cache. Using POST would
   prevent this because POSTs are not cached.
 
-* [Facebook::RailsUtil] Fixed a serious bug. The bug would jump up if
+* [`Facebook::RailsUtil`] Fixed a serious bug. The bug would jump up if
   you're using :write_session or :write_cookies or :write_handler along
   with :auto_authorize, for example:
   `rc_facebook_setup(:auto_authorize => true, :write_session => true)`
-  The problem is that Facebook::RailsUtil is not removing the invalid
+  The problem is that `Facebook::RailsUtil` is not removing the invalid
   access_token stored in session or cookie, and yet it is considered
   authorized, making redirecting to Facebook and redirecting back doesn't
   update the access_token. `rc_facebook_cleanup` is introduced to remove
@@ -35,72 +55,72 @@
 
 ### Enhancement
 
-* [Facebook] Now we use `default_data` to get the default data,
+* [`Facebook`] Now we use `default_data` to get the default data,
   instead of relying `Defaults` middleware.
 
-* [Facebook] Protected methods are changed to private.
+* [`Facebook`] Protected methods are changed to private.
 
-* [Flurry] `app_info` now accepts opts.
-* [Flurry] `event_metrics` is renamed to `event_summary`
-* [Flurry] `event_metrics` is now the API for accessing 'eventMetrics/Event'
-* [Flurry] If you didn't pass dates, now default to for 7 days.
-* [Flurry] Instead of overriding `query`, defining `default_query`
+* [`Flurry`] `app_info` now accepts opts.
+* [`Flurry`] `event_metrics` is renamed to `event_summary`
+* [`Flurry`] `event_metrics` is now the API for accessing 'eventMetrics/Event'
+* [`Flurry`] If you didn't pass dates, now default to for 7 days.
+* [`Flurry`] Instead of overriding `query`, defining `default_query`
 
-* [Linkedin+Twitter] Removed `Defaults` middleware because now we're using
+* [`Linkedin`+`Twitter`] Removed `Defaults` middleware because now we're using
   the data from `Oauth1Client` instead.
 
-* [Linkedin+Twitter] Removed `oauth_token`, `oauth_token=`,
+* [`Linkedin`+`Twitter`] Removed `oauth_token`, `oauth_token=`,
   `oauth_token_secret`, and `oauth_token_secret=` because we're using them
   from `Oauth1Client` instead.
 
-* [Linkedin+Twitter] Removed `set_token` because it's handled in
+* [`Linkedin`+`Twitter`] Removed `set_token` because it's handled in
   `Oauth1Client` now.
 
-* [Twitter::RailsUtil] Now `rc_twitter_setup` accepts options like
+* [`Twitter::RailsUtil`] Now `rc_twitter_setup` accepts options like
   `rc_facebook_setup`: `auto_authorize`, `ensure_authorized`,
   `write_session`, `write_cookies`, `write_handler`, and `check_handler`.
 
-* [Mixi] Removed `Defaults` middleware in favor of `default_data`.
+* [`Mixi`] Removed `Defaults` middleware in favor of `default_data`.
 
-* [Facebook+Github+Mixi+Twitter] Added a `me` method for accessing current
-  user information.
+* [`Facebook`+`Github`+`Mixi`+`Twitter`] Added a `me` method for accessing
+  current user information.
 
 ## rest-more 0.7.2.1 -- 2011-11-05
 
 ### Bugs fixes
 
-* [Facebook::RailsUtil] Fixed a missed change which should be made.
+* [`Facebook::RailsUtil`] Fixed a missed change which should be made.
 
 ## rest-more 0.7.2 -- 2011-11-05
 
 ### Incompatible changes
 
-* [Flurry] renamed `api_key` to `apiKey` to better match the original name
+* [`Flurry`] renamed `api_key` to `apiKey` to better match the original name
   from flurry. Also renamed `access_code` to `apiAccessCode`.
-* [Facebook::RailsUtil] Some `module_function`s are changed to controller's
+* [`Facebook::RailsUtil`] Some `module_function`s are changed to controller's
   private methods. You aren't using it if you don't know what does this mean.
 
 ### Enhancement
 
 * Added `rib-rest-core` command line tool, extracted from rest-core.
-* [RailsUtilUtil] Introduced this to ease the pain writing RailsUtil for
+* [`RailsUtilUtil`] Introduced this to ease the pain writing RailsUtil for
   various clients.
-* [Bing] Added Bing client and its RailsUtil.
-* [Github] Added RailsUtil for Github client.
-* [Linkedin] Added RailsUtil for Linkedin client.
-* [Mixi] Added RailsUtil for Mixi client.
-* [Twitter] Added RailsUtil for Twitter client.
+* [`Bing`] Added `Bing` client and its RailsUtil.
+* [`Github`] Added RailsUtil for Github client.
+* [`Linkedin`] Added RailsUtil for Linkedin client.
+* [`Mixi`] Added RailsUtil for Mixi client.
+* [`Twitter`] Added RailsUtil for Twitter client.
 
 ## rest-more 0.7.1 -- 2011-10-31
 
 ### Bugs fixes
 
-* [Mixi] Fixed `RC::Mixi.new(:access_token => 'access_token')` which is not
+* [`Mixi`] Fixed `RC::Mixi.new(:access_token => 'access_token')` which is not
   working before.
 
 ### Enhancement
 
-* [Mixi] `RC::Mixi#authorize!` now works like `RC::Facebook#authorize!`
+* [`Mixi`] `RC::Mixi#authorize!` now works like `RC::Facebook#authorize!`
   That is now we pass code like this: `mixi.authorize!(:code => code)`
 
 * `RestCore::Config` and `RestCore::RailsUtilUtil` are now moved to rest-more
@@ -108,10 +128,10 @@
 ## rest-more 0.7.0 -- 2011-10-08
 
 * Extracted from [rest-core][] 0.4.0
-* [Facebook] Added `RC::Facebook#parse_fbsr!` which can parse Facebook's new
+* [`Facebook`] Added `RC::Facebook#parse_fbsr!` which can parse Facebook's new
   cookie. Also, `RC::Facebook#parse_cookies!` would look for that too.
-* [Facebook] Fixed that parsing an invalid signed_request would raise an
+* [`Facebook`] Fixed that parsing an invalid signed_request would raise an
   error. From now on it would simply ignore it and wipe out the data.
-* [Flurry] Some minor updates.
+* [`Flurry`] Some minor updates.
 
 [rest-core]: https://github.com/cardinalblue/rest-core

data/Gemfile

@@ -5,6 +5,7 @@ source 'http://rubygems.org'
 gem 'rest-core', :path => 'rest-core' if
   File.exist?("#{File.dirname(File.expand_path(__FILE__))}/rest-core/Gemfile")
 gem 'rest-client'
+gem 'em-http-request'
 gem 'rest-more', :path => '.'
 
 gem 'rake'
@@ -20,6 +21,7 @@ gem 'ruby-hmac'
 
 platforms(:ruby) do
   gem 'yajl-ruby'
+  gem 'cool.io-http'
 end
 
 platforms(:jruby) do
@@ -27,4 +29,4 @@ platforms(:jruby) do
 end
 
 gem 'rails', '2.3.14' if ENV['RESTMORE'] == 'rails2'
-gem 'rails', '3.0.9'  if ENV['RESTMORE'] == 'rails3'
+gem 'rails', '3.2.1'  if ENV['RESTMORE'] == 'rails3'

data/README.md

@@ -1,7 +1,16 @@
-# rest-more [![Build Status](http://travis-ci.org/godfat/rest-more.png)](http://travis-ci.org/godfat/rest-more)
+# rest-more [![Build Status](https://secure.travis-ci.org/godfat/rest-more.png?branch=master)](http://travis-ci.org/godfat/rest-more)
 
 by Cardinal Blue <http://cardinalblue.com>
 
+Lin Jen-Shin ([godfat][]) had given a talk about rest-core on
+[RubyConf Taiwan 2011][talk]. The slide is in English, but the
+talk is in Mandarin.
+
+You can also read some other topics at [doc](https://github.com/cardinalblue/rest-core/blob/master/doc/ToC.md).
+
+[godfat]: https://github.com/godfat
+[talk]: http://rubyconf.tw/2011/#6
+
 ## LINKS:
 
 * [github](https://github.com/cardinalblue/rest-more)
@@ -15,22 +24,56 @@ Various REST clients such as Facebook and Twitter built with [rest-core][]
 
 [rest-core]: https://github.com/cardinalblue/rest-core
 
+## FEATURES:
+
+Out-of-box REST clients built with rest-core for:
+
+* Bing
+* Dropbox
+* Facebook
+* Flurry
+* Github
+* Linkedin
+* Mixi
+* Twitter
+
+Rails utilities are also included.
+
 ## REQUIREMENTS:
 
-* Tested with MRI (official CRuby) 1.8.7, 1.9.2, 1.9.3, Rubinius and JRuby
-* gem install rest-core
+### Mandatory:
+
+* MRI (official CRuby) 1.8.7, 1.9.2, 1.9.3, Rubinius 1.8/1.9 and JRuby 1.8/1.9
+* gem rest-client
+
+### Optional:
+
+* Fibers only work on Ruby 1.9+
+* gem [em-http-request][] (if using eventmachine)
+* gem [cool.io-http][] (if using cool.io)
+* gem json or yajl-ruby (if using `JsonDecode` middleware)
+
+[em-http-request]: https://github.com/igrigorik/em-http-request
+[cool.io-http]: https://github.com/godfat/cool.io-http
 
 ## INSTALLATION:
 
+``` shell
     gem install rest-more
+```
 
 Or if you want development version, put this in Gemfile:
 
+``` ruby
     gem 'rest-more', :git => 'git://github.com/cardinalblue/rest-more.git',
                      :submodules => true
+```
 
 ## SYNOPSIS:
 
+The simplest usage:
+
+``` ruby
     require 'rest-more'
 
     RestCore::Twitter.new.statuses('_cardinalblue') # get user tweets
@@ -43,20 +86,136 @@ Or if you want development version, put this in Gemfile:
     linkedin.me               # get current user info
 
     RestCore::Facebook.new.get('4') # get user info
+```
 
-See [example][] for more complex examples.
+Runnable example is here: [example/simple.rb][]. Please see [slides][] from
+[rubyconf.tw/2011][rubyconf.tw] for concepts.
 
-[example]: https://github.com/cardinalblue/rest-more/tree/master/example
+[example/simple.rb]: https://github.com/cardinalblue/rest-more/blob/master/example/simple.rb
+[slides]: http://www.godfat.org/slide/2011-08-27-rest-core.html
+[rubyconf.tw]: http://rubyconf.tw/2011/#6
 
-## List of supported clients:
+## Asynchronous HTTP Requests:
 
-* Bing
-* Facebook
-* Flurry
-* Github
-* Linkedin
-* Mixi
-* Twitter
+I/O bound operations shouldn't be blocking the CPU! If you have a reactor,
+i.e. event loop, you should take the advantage of that to make HTTP requests
+not block the whole process/thread. For now, we support eventmachine and
+cool.io. By default, all clients are using `RestClient`, which is a
+synchronous HTTP client, thus blocking. It's very easy to use, but not
+very scalable (not concurrent-efficient). You can change the default app
+(i.e. HTTP clients) to an asynchronous one:
+
+``` ruby
+    require 'rest-more'
+    RestCore::Builder.default_app = RestCore::EmHttpRequest
+```
+
+or an auto-picking one, which would try to infer the correct HTTP client
+depending on the context. Either em-http-request, cool.io-http, or even
+rest-client if none of reactors is available.
+
+``` ruby
+    require 'rest-more'
+    RestCore::Builder.default_app = RestCore::Auto
+```
+
+You can also setup the `default_app` for a specific client, so that it won't
+change all the `default_app` for all the clients, like this:
+
+``` ruby
+    require 'rest-more'
+    RestCore::Facebook.builder.default_app = RestCore::Auto
+```
+
+If you're passing a block, the block is called after the response is
+available. That is the block is the callback for the request.
+
+``` ruby
+    require 'rest-more'
+    require 'eventmachine'
+    RestCore::Builder.default_app = RestCore::EmHttpRequest
+    EM.run{
+      RestCore::Facebook.new.get('4'){ |response|
+        p response
+        EM.stop
+      }
+      puts "It's not blocking..."
+    }
+```
+
+Otherwise, if you don't pass a block as the callback, EmHttpRequest (i.e.
+the HTTP client for eventmachine) would call `Fiber.yield` to yield to the
+original fiber, making asynchronous HTTP requests look like synchronous.
+If you don't understand what does this mean, you can take a look at
+[em-synchrony][]. It's basically the same idea.
+
+``` ruby
+    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..."
+    }
+```
+
+[em-synchrony]: https://github.com/igrigorik/em-synchrony
+
+Runnable example is here: [example/facebook.rb][].
+You can also make multi-requests synchronously like this:
+
+``` ruby
+    require 'rest-more'
+    require 'eventmachine'
+
+    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..."
+    }
+```
+
+Runnable example is here: [example/multi.rb][]. All `RestCore::EmHttpRequest`
+above is interchangeable with `RestCore::Auto` because `RestCore::Auto` would
+pick the right HTTP client when running inside the eventmachine's event loop.
+
+[example/facebook.rb]: https://github.com/cardinalblue/rest-more/blob/master/example/facebook.rb
+[example/multi.rb]: https://github.com/cardinalblue/rest-more/blob/master/example/multi.rb
+
+## Supported HTTP clients:
+
+* `RestCore::RestClient` (gem rest-client)
+* `RestCore::EmHttpRequest` (gem em-http-request)
+* `RestCore::Coolio` (gem cool.io)
+* `RestCore::Auto` (which would pick one of the above depending on the
+  context)
+
+## Rails Utilities
+
+To be added. But you can take a look at the [Facebook tutorial][] first.
+
+[Facebook tutorial]: https://github.com/cardinalblue/rest-more/blob/master/doc/tutorial/facebook.md
 
 ## A simple interactive shell with [rib][]:
 
@@ -79,11 +238,25 @@ Which is using `RestCore::Universal` for accessing arbitrary websites.
 * [s2sync](https://github.com/brucehsu/s2sync)
 * [s2sync_web](https://github.com/brucehsu/s2sync_web)
 
+## Powered sites:
+
+* [PicCollage](http://pic-collage.com/)
+
+## CHANGES:
+
+* [CHANGES](https://github.com/cardinalblue/rest-more/blob/master/CHANGES.md)
+
+## CONTRIBUTORS:
+
+* ayaya (@ayamomiji)
+* Lin Jen-Shin (@godfat)
+* Yun-Yan Chi (@jaiyalas)
+
 ## LICENSE:
 
 Apache License 2.0
 
-Copyright (c) 2011, Cardinal Blue
+Copyright (c) 2011-2012, Cardinal Blue
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.