rest-core 0.3.0 → 0.4.0.pre.0

data/CHANGES.md

@@ -1,5 +1,59 @@
 # rest-core CHANGES
 
+## rest-core 0.4.0 -- ?
+
+### Incompatible changes:
+
+* [dry] Now `RestCore::Ask` is renamed to `RestCore::Dry` for better
+  understanding. Thanks miaout17
+
+* [client] Now `request` method takes an env and an app to make requests,
+  instead of a weird requests array.
+
+### Compatible changes:
+
+* [client] Introduced a new method `request_full` which is exactly the same
+  as `request` but also returns various information from the app, including
+  `RESPONSE_STATUS` and `RESPONSE_HEADERS`
+
+* [client] Removed various unused, untested, undocumented legacy from
+  rest-graph.
+
+* [error] Introduced `RestCore::Error` which is the base class for all
+  exceptions raised by rest-core
+
+* [builder] Now `RestCore::Builder.default_app` is the default app which
+  would be used for building clients without setting an app. By default,
+  it's `RestClient`, but you can change it if you like.
+
+* [builder] It no longer builds a @wrapped app. If you don't understand this,
+  then this does nothing for you. It's an internal change. (or bug fix)
+
+* [wrapper] Now `RestCore::Wrapper.default_app` is the default app which
+  would be used for wrapping middlewares without setting an app. By default,
+  it's `Dry`, but you can change it if you like.
+
+* [wrapped] Fixed a bug that force middlewares to implement `members` method,
+  which should be optional. Thanks miaout17
+
+* [simple]   Added a Simple client, which only wraps RestClient
+* [univeral] Added an Universal client, which could be used for anything
+* [flurry]   Added a Flurry client, along with its `Flurry::RailsUtil`
+* [mixi]     Added a Mixi client
+
+* [bypass] Added a Bypass middleware which does nothing but passing env
+* [oauth2_header] OAuth2Header is a middleware which would pass access_token
+  in header instead of in query string.
+* [common_logger] nil object would no longer be logged
+* [json_decode] Do nothing if we are being asked for env (dry mode)
+* [middleware] Now not only query values would be escaped, but also keys.
+
+* [rib-rest-core] Introduced an interactive shell. You'll need [rib][] to
+  run this: `rib rest-core`. It is using an universal client to access
+  arbitrary websites.
+
+[rib]: https://github.com/godfat/rib
+
 ## rest-core 0.3.0 -- 2011-09-03
 
 * [facebook] RestGraph is Facebook now.
@@ -16,6 +70,7 @@
 * [oauth2_query] Now we always use the term "access_token"
 * [config] Now Config#load and Config#load_for_rails take namespace
   e.g. rest-core.yaml:
+
       development:
         facebook:
           app_id: 123

data/README.md

@@ -1,4 +1,5 @@
 # rest-core [![Build Status](http://travis-ci.org/godfat/rest-core.png)](http://travis-ci.org/godfat/rest-core)
+
 by Cardinal Blue <http://cardinalblue.com>
 
 ## LINKS:
@@ -10,7 +11,7 @@ by Cardinal Blue <http://cardinalblue.com>
 
 ## DESCRIPTION:
 
-A modular Ruby REST client collection/infrastructure.
+A modular Ruby REST client collection/infrastructure
 
 In this era of web services and mashups, we have seen a blooming of REST
 APIs. One might wonder, how do we use these APIs easily and elegantly?
@@ -53,9 +54,7 @@ Or if you want development version, put this in Gemfile:
     linkedin.authorize!('..') # paste your code from browser
     linkedin.me               # get current user info
 
-    # below is exactly the same as [rest-graph][]
-    require 'rest-core/client/rest-graph'
-    RestGraph.new.get('4')                   # get user info
+    RestCore::Facebook.new.get('4') # get user info
 
 See [example][] for more complex examples.
 
@@ -86,6 +85,104 @@ See [built-in clients][] for more complex examples.
 
 [built-in clients]: https://github.com/cardinalblue/rest-core/tree/master/lib/rest-core/client
 
+## A simple interactive shell with [rib][]
+
+You need to install [rib][] in order to try this interactive shell:
+
+    gem install rib
+
+Then you can try this by running `rib rest-core`:
+
+    rest-core>> self.site = 'https://api.github.com/users/'
+    rest-core>> get 'cardinalblue', {}, :json_decode => true
+
+Which is using `RestCore::Universal` for accessing arbitrary websites.
+
+[rib]: https://github.com/godfat/rib
+
+## GLOSSARY:
+
+* A _client_ is a class which can new connections to make requests.
+  For instance, `RestCore::Facebook.new.get('4')`
+
+* An _app_ is an HTTP client which would do the underneath HTTP requests.
+  For instance, `RestCore::RestClient` is an HTTP client which uses
+  rest-client gem (`::RestClient`) to make HTTP requests.
+
+* A _middleware_ is a component for a rest-core stack.
+  For instance, `RestCore::DefaultSite` is a middleware which would add
+  default site URL in front of the request URI if it is not started with
+  http://, thus you can do this: `RestCore::Facebook.get('4')` without
+  specifying where the site (Facebook) it is.
+
+* `RestCore::Wrapper` is a utility which could help you wrap a number of
+  middlewares into another middleware. Currently, it's used in
+  `RestCore::Buidler` and `RestCore::Cache`.
+
+* `RestCore::Builder` is a utility which could help you build a _client_
+  with a collection of _middlewares_ and an _app_. i.e. a rest-core stack.
+
+* `RestCore::Middleware` is a utility which could help you build a non-trivial
+  middleware. More explanation to come...
+
+* `RestCore::Client` is a module which would be included in a generated
+  _client_ by `RestCore::Builder`. It contains a number of convenient
+  functions which is generally useful.
+
+* `RestCore::ClientOAuth1` is a module which should be included in a OAuth1.0
+  client. It contains a number of convenient functions which is useful for an
+  OAuth 1.0 client.
+
+* An `env` is a hash which contains all the information for both request and
+  response. It's mostly seen in `@app.call(env)` See other explanation
+  such as `env[RestCore::REQUEST_METHOD]` for more detail.
+
+* `env[RestCore::REQUEST_METHOD]` is a symbol representing which HTTP method
+  would be used in the subsequent HTTP request. The possible values are
+  either: `:get`, `:post`, `:put` or `:delete`.
+
+* `env[RestCore::REQUEST_PATH]` is a string representing which HTTP path
+  would be used in the subsequent HTTP request. This path could also include
+  the protocol, not only the path. e.g. `"http://graph.facebook.com/4"` or
+  simply `"4"`. In the case of built-in Facebook client, the
+  `RestCore::DefaultSite` middleware would take care of the site.
+
+* `env[RestCore::REQUEST_QUERY]` is a hash which keys are query keys and
+  values are query values. Both keys and values' type should be String, not
+  Symbol. Values with nil or false would be ignored. Both keys and values
+  would be escaped automatically.
+
+* `env[RestCore::REQUEST_PAYLOAD]` is a hash which keys are payload keys and
+  values are payload values. Both keys and values' type should be String,
+  not Symbol. Values with nil or false would be ignored. Both keys and values
+  would be escaped automatically.
+
+* `env[RestCore::REQUEST_HEADERS]` is a hash which keys are header names and
+  values are header values. Both keys and values' type should be String,
+  not Symbol. Values with nil or false would be ignored.
+
+* `env[RestCore::RESPONSE_BODY]` is a string which is returned by the server.
+  Might be nil if there's no response or not yet making HTTP request.
+
+* `env[RestCore::RESPONSE_STATUS]` is a number which is returned by the
+  server for the HTTP status. Might be nil if there's no response or not
+  yet making HTTP request.
+
+* `env[RestCore::RESPONSE_HEADERS]` is a hash which is returned by the server
+  for the response headers. Both keys and values' type should be String.
+
+* `env[RestCore::DRY]` is a boolean (either `true` or `false` or `nil`) which
+  indicates that if we're only asking for modified `env`, instead of making
+  real requests. It's used to ask for the real request URI, etc.
+
+* `env[RestCore::FAIL]` is an array which contains failing events. Events
+  could be any objects, it's handled by `RestCore::ErrorDetector` or any
+  other custom _middleware_.
+
+* `env[RestCore::LOG]` is an array which contains logging events. Events
+  could be any objects, it's handled by `RestCore::CommonLogger` or
+  any other custom _middleware_.
+
 ## LICENSE:
 
   Apache License 2.0

data/bin/rib-rest-core

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'rib/runner'
+  # create the shell before app to prvent your bundler (if any) kicks in
+  Rib.shell
+  # we need to require anything before loading the app,
+  # and both `rib auto` (true) and `rib-auto` (nil) should work
+  require 'rib/core' if Rib.config.delete(:mimic_irb) != false
+  require 'rib/app/rest-core'
+  # load the app
+  Rib::RestCore.load
+  Rib::Runner.run(ARGV)
+rescue LoadError => e
+  abort("Error: #{e}\n"                                        \
+        "Please install rib to use interactive rest-core:\n\n" \
+        "    gem install rib\n\n"                              \
+        "Or add rib or rest-core to Gemfile if that's the case")
+end
+
+__END__
+Run as interactive rest-core client

data/example/rails2/app/controllers/application_controller.rb

@@ -3,6 +3,7 @@ class ApplicationController < ActionController::Base
   protect_from_forgery
 
   include RestCore::Facebook::RailsUtil
+  include RestCore::Flurry::RailsUtil
 
   before_filter :filter_common       , :only => [:index]
   before_filter :filter_canvas       , :only => [:canvas]

data/example/rails2/app/views/application/helper.html.erb

@@ -1 +1,2 @@
-<%= rc_facebook.app_id %>
+<%= rc_facebook.app_id  %>
+<%= rc_flurry  .api_key %>

data/example/rails2/config/rest-core.yaml

@@ -5,6 +5,10 @@ development: &default
     secret: '456'
     canvas: 'can'
 
+  flurry:
+    api_key: 'key'
+    access_code: 'code'
+
 production:
   *default
 

data/example/rails2/test/functional/application_controller_test.rb

@@ -178,6 +178,8 @@ class ApplicationControllerTest < ActionController::TestCase
   def test_helper
     get(:helper)
     assert_response :success
-    assert_equal RestCore::Facebook.default_app_id, @response.body.strip
+    assert_equal "#{RestCore::Facebook.default_app_id}\n" \
+                 "#{RestCore::Flurry  .default_api_key}",
+      @response.body.strip
   end
 end

data/example/rails3/app/controllers/application_controller.rb

@@ -3,6 +3,7 @@ class ApplicationController < ActionController::Base
   protect_from_forgery
 
   include RestCore::Facebook::RailsUtil
+  include RestCore::Flurry::RailsUtil
 
   before_filter :filter_common       , :only => [:index]
   before_filter :filter_canvas       , :only => [:canvas]

data/example/rails3/app/views/application/helper.html.erb

@@ -1 +1,2 @@
-<%= rc_facebook.app_id %>
+<%= rc_facebook.app_id  %>
+<%= rc_flurry  .api_key %>

data/example/rails3/config/rest-core.yaml

@@ -5,6 +5,10 @@ development: &default
     secret: '456'
     canvas: 'can'
 
+  flurry:
+    api_key: 'key'
+    access_code: 'code'
+
 production:
   *default
 

data/example/rails3/test/functional/application_controller_test.rb

@@ -178,6 +178,8 @@ class ApplicationControllerTest < ActionController::TestCase
   def test_helper
     get(:helper)
     assert_response :success
-    assert_equal RestCore::Facebook.default_app_id, @response.body.strip
+    assert_equal "#{RestCore::Facebook.default_app_id}\n" \
+                 "#{RestCore::Flurry  .default_api_key}",
+      @response.body.strip
   end
 end

data/lib/rest-core/app/{ask.rb → dry.rb}

@@ -1,7 +1,7 @@
 
 require 'rest-core/middleware'
 
-class RestCore::Ask
+class RestCore::Dry
   include RestCore::Middleware
   def call env
     env

data/lib/rest-core/builder.rb

@@ -6,18 +6,34 @@ class RestCore::Builder
   include RestCore
   include Wrapper
 
+  class << self
+    attr_writer :default_app
+  end
+  def self.default_app
+    @default_app ||= RestClient
+  end
+
   def self.client *attrs, &block
     new(&block).to_client(*attrs)
   end
 
   def to_client *attrs
-    # struct = Struct.new(*members, *attrs) if RUBY_VERSION >= 1.9.2
-    struct = Struct.new(*(members + attrs))
+    fields = members + attrs
+    struct = if fields.empty?
+               Struct.new(nil)
+             else
+               Struct.new(*fields)
+             end
     client = Class.new(struct)
-    client.send(:include, Client)
     client.const_set('Struct', struct)
+    client.send(:include, Client)
     class << client; attr_reader :builder; end
     client.instance_variable_set(:@builder, self)
     client
   end
+
+  def initialize &block
+    @middles ||= []
+    instance_eval(&block) if block_given?
+  end
 end

data/lib/rest-core/client/facebook/rails_util.rb

@@ -1,33 +1,27 @@
 
+require 'rest-core/util/rails_util_util'
+
 require 'cgi'
 require 'uri'
 
-class RestCore::Facebook
-  module DefaultAttributes
-    def default_canvas                ; ''   ; end
-    def default_iframe                ; false; end
-    def default_auto_authorize        ; false; end
-    def default_auto_authorize_options; {}   ; end
-    def default_auto_authorize_scope  ; ''   ; end
-    def default_ensure_authorized     ; false; end
-    def default_write_session         ; false; end
-    def default_write_cookies         ; false; end
-    def default_write_handler         ;   nil; end
-    def default_check_handler         ;   nil; end
-  end
-
-  module RailsCache
-    def []    key       ;  read(key)                ; end
-    def []=   key, value; write(key, value)         ; end
-    def store key, value,
-              options={}; write(key, value, options); end
-  end
+module RestCore::Facebook::DefaultAttributes
+  def default_canvas                ; ''   ; end
+  def default_iframe                ; false; end
+  def default_auto_authorize        ; false; end
+  def default_auto_authorize_options; {}   ; end
+  def default_auto_authorize_scope  ; ''   ; end
+  def default_ensure_authorized     ; false; end
+  def default_write_session         ; false; end
+  def default_write_cookies         ; false; end
+  def default_write_handler         ;   nil; end
+  def default_check_handler         ;   nil; end
 end
 
 module RestCore::Facebook::RailsUtil
+  include RestCore
+
   def self.init app=Rails
-    ActiveSupport::Cache::Store.send(:include, RestCore::Facebook::RailsCache)
-    RestCore::Config.load_for_rails(RestCore::Facebook, 'facebook', app)
+    Config.load_for_rails(Facebook, 'facebook', app)
   end
 
   module Helper
@@ -40,9 +34,9 @@ module RestCore::Facebook::RailsUtil
     # skip if included already, any better way to detect this?
     return if controller.respond_to?(:rc_facebook, true)
 
-    controller.rescue_from(RestCore::Facebook::Error::AccessToken,
+    controller.rescue_from(Facebook::Error::AccessToken,
                            :with => :rc_facebook_on_access_token_error)
-    controller.helper(RestCore::Facebook::RailsUtil::Helper)
+    controller.helper(Facebook::RailsUtil::Helper)
     controller.instance_methods.select{ |method|
       method.to_s =~ /^rc_facebook/
     }.each{ |method| controller.send(:protected, method) }
@@ -50,9 +44,9 @@ module RestCore::Facebook::RailsUtil
 
   def rc_facebook_setup options={}
     rc_facebook_options_ctl.merge!(
-      rc_facebook_extract_options(options, :reject))
+      RailsUtilUtil.extract_options(Facebook.members, options, :reject))
     rc_facebook_options_new.merge!(
-      rc_facebook_extract_options(options, :select))
+      RailsUtilUtil.extract_options(Facebook.members, options, :select))
 
     # we'll need to reinitialize rc_facebook with the new options,
     # otherwise if you're calling rc_facebook before rc_facebook_setup,
@@ -84,7 +78,7 @@ module RestCore::Facebook::RailsUtil
 
   # override this if you need different app_id and secret
   def rc_facebook
-    @rc_facebook ||= RestCore::Facebook.new(rc_facebook_options_new)
+    @rc_facebook ||= Facebook.new(rc_facebook_options_new)
   end
 
   def rc_facebook_on_access_token_error error=nil
@@ -157,7 +151,7 @@ module RestCore::Facebook::RailsUtil
     if rc_facebook_options_ctl.has_key?(key)
       rc_facebook_options_ctl[key]
     else
-      RestCore::Facebook.send("default_#{key}")
+      Facebook.send("default_#{key}")
     end
   end
 
@@ -221,8 +215,10 @@ module RestCore::Facebook::RailsUtil
   def rc_facebook_check_code
     return if rc_facebook.authorized? || !params[:code]
 
-    rc_facebook.authorize!(:code => params[:code],
-                          :redirect_uri => rc_facebook_normalized_request_uri)
+    rc_facebook.authorize!(
+      :code         => params[:code],
+      :redirect_uri => rc_facebook_normalized_request_uri)
+
     logger.debug(
       "DEBUG: Facebook: detected code with "   \
       "#{rc_facebook_normalized_request_uri}," \
@@ -329,13 +325,6 @@ module RestCore::Facebook::RailsUtil
     !rc_facebook_oget(:auto_authorize_options).blank? ||
      rc_facebook_oget(:auto_authorize)
   end
-
-  def rc_facebook_extract_options options, method
-    # Hash[] is for ruby 1.8.7
-    # map(&:to_sym) is for ruby 1.8.7
-    Hash[options.send(method){ |(k, v)|
-      RestCore::Facebook.members.map(&:to_sym).member?(k) }]
-  end
   # ==================== end misc ================================
 end
 

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

@@ -13,28 +13,24 @@ RestCore::Facebook = RestCore::Builder.client(
                           'Accept-Language' => 'en-us'}
   use s::Oauth2Query   , nil
 
-  use s::CommonLogger  , lambda{|obj|obj}
-
+  use s::CommonLogger  , nil
   use s::Cache         , nil, 3600 do
-    use s::ErrorHandler  , lambda{ |env|
-                             raise ::RestCore::Facebook::Error.call(env) }
-    use s::ErrorDetector , lambda{ |env|
+    use s::ErrorHandler,  lambda{ |env|
+                            raise ::RestCore::Facebook::Error.call(env) }
+    use s::ErrorDetector, lambda{ |env|
       if env[s::RESPONSE_BODY].kind_of?(Hash)
         env[s::RESPONSE_BODY]['error'] ||
         env[s::RESPONSE_BODY]['error_code']
       end}
 
-    use s::JsonDecode    , true
-    run s::Ask
+    use s::JsonDecode  , true
   end
 
   use s::Defaults      , :data     => lambda{{}},
                          :old_site => 'https://api.facebook.com/'
-
-  run s::RestClient
 end
 
-class RestCore::Facebook::Error < RuntimeError
+class RestCore::Facebook::Error < RestCore::Error
   include RestCore
   class AccessToken        < Facebook::Error; end
   class InvalidAccessToken < AccessToken     ; end
@@ -91,7 +87,7 @@ module RestCore::Facebook::Client
 
   def next_page hash, opts={}, &cb
     if hash['paging'].kind_of?(Hash) && hash['paging']['next']
-      request(opts, [:get, hash['paging']['next']], &cb)
+      get(hash['paging']['next'], {}, opts, &cb)
     else
       yield(nil) if block_given?
     end
@@ -99,7 +95,7 @@ module RestCore::Facebook::Client
 
   def prev_page hash, opts={}, &cb
     if hash['paging'].kind_of?(Hash) && hash['paging']['previous']
-      request(opts, [:get, hash['paging']['previous']], &cb)
+      get(hash['paging']['previous'], {}, opts, &cb)
     else
       yield(nil) if block_given?
     end
@@ -171,8 +167,8 @@ module RestCore::Facebook::Client
   def authorize! opts={}
     query = {:client_id => app_id, :client_secret => secret}.merge(opts)
     self.data = Vendor.parse_query(
-                  request({:json_decode => false}.merge(opts),
-                          [:get, url('oauth/access_token', query)]))
+                  get(url('oauth/access_token'), query,
+                      {:json_decode => false}.merge(opts)))
   end
 
   # old rest facebook api, i will definitely love to remove them someday
@@ -181,15 +177,14 @@ module RestCore::Facebook::Client
     uri = url("method/#{path}", {:format => 'json'}.merge(query),
               {:site => old_site}.merge(opts))
     if opts[:post]
-      request(
-        opts.merge('cache.key' => uri, 'cache.post' => true),
-        [:post,
-         url("method/#{path}", {:format => 'json'},
-             {:site => old_site}.merge(opts)),
-         {}, query],
-        &cb)
+      post(url("method/#{path}", {:format => 'json'},
+               {:site => old_site}.merge(opts)),
+           query,
+           {}   ,
+           opts.merge('cache.key' => uri, 'cache.post' => true),
+           &cb)
     else
-      request(opts, [:get, uri], &cb)
+      get(uri, {}, opts, &cb)
     end
   end
 
@@ -209,7 +204,8 @@ module RestCore::Facebook::Client
   def exchange_sessions query={}, opts={}, &cb
     q = {:client_id => app_id, :client_secret => secret,
          :type => 'client_cred'}.merge(query)
-    request(opts, [:post, url('oauth/exchange_sessions', q)], &cb)
+    post(url('oauth/exchange_sessions', q),
+         {}, {}, opts, &cb)
   end
 
   protected

data/lib/rest-core/client/flurry/rails_util.rb

@@ -0,0 +1,72 @@
+
+require 'rest-core/util/rails_util_util'
+
+module RestCore::Flurry::DefaultAttributes
+  def default_api_key    ; nil; end
+  def default_access_code; nil; end
+end
+
+module RestCore::Flurry::RailsUtil
+  include RestCore
+
+  def self.init app=Rails
+    Config.load_for_rails(Flurry, 'flurry', app)
+  end
+
+  module Helper
+    def rc_flurry
+      controller.send(:rc_flurry)
+    end
+  end
+
+  def self.included controller
+    # skip if included already, any better way to detect this?
+    return if controller.respond_to?(:rc_flurry, true)
+
+    controller.helper(Flurry::RailsUtil::Helper)
+    controller.instance_methods.select{ |method|
+      method.to_s =~ /^rc_flurry/
+    }.each{ |method| controller.send(:protected, method) }
+  end
+
+  def rc_flurry_setup options={}
+    rc_flurry_options_ctl.merge!(
+      RailsUtilUtil.extract_options(Flurry.members, options, :reject))
+    rc_flurry_options_new.merge!(
+      RailsUtilUtil.extract_options(Flurry.members, options, :select))
+
+    # we'll need to reinitialize rc_flurry with the new options,
+    # otherwise if you're calling rc_flurry before rc_flurry_setup,
+    # you'll end up with default options without the ones you've passed
+    # into rc_flurry_setup.
+    rc_flurry.send(:initialize, rc_flurry_options_new)
+
+    true # keep going
+  end
+
+  def rc_flurry
+    @rc_flurry ||= Flurry.new(rc_flurry_options_new)
+  end
+
+  module_function
+
+  # ==================== begin options utility =======================
+  def rc_flurry_oget key
+    if rc_flurry_options_ctl.has_key?(key)
+      rc_flurry_options_ctl[key]
+    else
+      Flurry.send("default_#{key}")
+    end
+  end
+
+  def rc_flurry_options_ctl
+    @rc_flurry_options_ctl ||= {}
+  end
+
+  def rc_flurry_options_new
+    @rc_flurry_options_new ||= {:log_method => logger.method(:debug)}
+  end
+  # ==================== end options utility =======================
+end
+
+RestCore::Flurry::RailsUtil.init(Rails)