rest-core 1.0.3 → 2.0.0

data/.travis.yml

@@ -1,11 +1,10 @@
 before_install: 'git submodule update --init'
-script: 'bundle exec rake test'
+script: 'ruby -r bundler/setup -S rake test'
+
+env:
+  - 'RBXOPT=-X19'
 
 rvm:
-  - 1.8.7
-  - 1.9.2
   - 1.9.3
-  - rbx-18mode
-  - rbx-19mode
-  - jruby-18mode
-  - jruby-19mode
+  - rbx-head
+  - jruby-head

data/CHANGES.md

@@ -1,5 +1,142 @@
 # CHANGES
 
+## rest-core 2.0.0
+
+This is a major release which introduces some incompatible changes.
+This is intended to cleanup some internal implementation and introduce
+a new mechanism to handle multiple requests concurrently, avoiding needless
+block.
+
+Before we go into detail, here's who can upgrade without changing anything,
+and who should make a few adjustments in their code:
+
+* If you're only using rest-more, e.g. `RC::Facebook` or `RC::Twitter`, etc.,
+  you don't have to change anything. This won't affect rest-more users.
+  (except that JsonDecode is renamed to JsonResponse, and json_decode is
+  renamed to json_response.)
+
+* If you're only using rest-core's built in middlewares to build your own
+  clients, you don't have to change anything as well. All the hard works are
+  done in rest-core. (except that ErrorHandler works a bit differently now.
+  We'll talk about detail later.)
+
+* If you're building your own middlewares, then you are the ones who need to
+  make changes. `RC::ASYNC` is changed to a flag to mean whether the callback
+  should be called directly, or only after resuming from the future (fiber
+  or thread). And now you have always to get the response from `yield`, that
+  is, you're forced to pass a callback to `call`.
+
+  This might be a bit user unfriendly at first glimpse, but it would much
+  simplify the internal structure of rest-core, because in the middlewares,
+  you don't have to worry if the user would pass a callback or not, branching
+  everywhere to make it work both synchronously and asynchronously.
+
+  Also, the old fiber based asynchronous HTTP client is removed, in favor
+  of the new _future_ based approach. The new one is more like a superset
+  of the old one, which have anything the old one can provide. Yet internally
+  it works a lot differently. They are both synchronous to the outsides,
+  but while the old one is also synchronous inside, the new one is
+  asynchronous inside, just like the purely asynchronous HTTP client.
+
+  That is, internally, it's always asynchronously, and fiber/async didn't
+  make much difference here now. This is also the reason why I removed
+  the old fiber one. This would make the middleware implementation much
+  easier, considering much fewer possible cases.
+
+  If you don't really understand what above does mean, then just remember,
+  now we ask all middlewares work asynchronously. You have always to work
+  with callbacks which passed along in `app.call(env){ |response| }`
+  That's it.
+
+So what's the most important improvement? From now on, we have only two
+modes. One is callback mode, in which case `env[ASYNC]` would be set, and
+the callback would be called. No exception would be raised in this case.
+If there's an exception, then it would be passed to the block instead.
+
+The other mode, which is synchronous, is achieved by the futures. We have
+two different kinds of futures for now, one is thread based, and the other
+is fiber based. For RestClient, thread based future would be used. For
+EventMachine, depending on the context, if the future is created on the
+main thread, then it would assume it's also wrapped inside a fiber. Since,
+we can never block the event loop! If you're not calling it in a thread,
+you must call it in a fiber. But if you're calling it in a thread, then
+the thread based future would be picked. This is because otherwise it won't
+work well exchanging information around threads and fibers.
+
+In short, rest-core would run concurrently in all contexts, archived by
+either threads or fibers depending on the context, and it would pick the
+right strategy for you.
+
+You can see [use-cases.rb][] for all possible use cases.
+
+It's a bit outdated, but you can also checkout my blog post.
+[rest-core 2.0 roadmap, thunk based response][post]
+(p.s. now thunk is renamed to future)
+
+[use-cases.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/use-cases.rb
+[post]: http://blogger.godfat.org/2012/06/rest-core-20-roadmap-thunk-based.html
+
+### Incompatible changes
+
+* [JsonDecode] is renamed to JsonResponse, and json_decode is also renamed
+  to json_response.
+* [Json] Now you can use `Json.decode` and `Json.encode` to parse and
+  generate JSONs, instead of `JsonDecode.json_decode`.
+* [Cache] Support for "cache.post" is removed.
+* [Cache] The cache key is changed accordingly to support cache for headers
+  and HTTP status. If you don't have persistent cache, this doesn't matter.
+
+* [EmHttpRequestFiber] is removed in favor of `EmHttpRequest`
+* cool.io support is removed.
+* You must provide a block to `app.call(env){ ... }`.
+* Rename Wrapper#default_app to Wrapper#default_engine
+
+### Enhancement
+
+* The default engine is changed from `RestClient` to `Auto`, which would
+  be using `EmHttpRequest` under the context of a event loop, while
+  use `RestClient` in other context as before.
+
+* `RestCore.eagerload` is introduced to load all constants eagerly. You can
+  use this before loading the application to avoid thread-safety issue in
+  autoload. For the lazies.
+
+* [JsonResponse] This is originally JsonDecode, and now we prefer multi_json
+  first, yajl-ruby second, lastly json.
+* [JsonResponse] give JsonResponse a default header Accept: application/json,
+  thanks @ayamomiji
+* [JsonRequest] This middleware would encode your payload into a JSON.
+* [CommonLogger] Now we log the request method as well.
+* [DefaultPayload] Accept arbitrary payload.
+* [DefaultQuery] Now before merging queries, converting every single key into
+  a string. This allows you to use :symbols for default query.
+
+* [ErrorHandler] So now ErrorHandler is working differently. It would first
+  try to see if `env[FAIL]` has any exception in it. If there is, then raise
+  it. Otherwise it would call error_handler and expect it to generate an
+  error object. If the error object is an exception, then raise it. If it's
+  not, then it would merge it into `env[FAIL]`. On the other hand, in the
+  case of using callbacks instead of futures, it would pass the exception
+  as the `env[RESPONSE_BODY]` instead. The reason is that you can't raise
+  an exception asynchronously and handle it safely.
+
+* [Cache] Now response headers and HTTP status are also cached.
+* [Cache] Not only GET requests are cached, HEAD and OPTIONS are cached too.
+* [Cache] The cache key is also respecting the request headers too. Suppose
+  you're making a request with different Accept header.
+
+* [Client] Add Client#wait which would block until all requests for this
+  particular client are done.
+
+### Bugs fixes
+
+* [Middleware] Sort the query before generating the request URI, making
+  sure the order is always the same.
+* [Middleware] The middleware could have no members at all.
+* [ParseQuery] The fallback function for the absence of Rack is fixed.
+* [Auto] Only use EmHttpRequest if em-http-request is loaded,
+  thanks @ayamomiji
+
 ## rest-core 1.0.3 -- 2012-08-15
 
 ### Enhancement

data/Gemfile

@@ -13,13 +13,13 @@ gem 'webmock'
 
 gem 'json'
 gem 'json_pure'
+gem 'multi_json'
 
 gem 'rack'
 gem 'ruby-hmac'
 
 platforms(:ruby) do
   gem 'yajl-ruby'
-  gem 'cool.io-http'
 end
 
 platforms(:jruby) do

data/README.md

@@ -6,8 +6,6 @@ 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
 
@@ -24,47 +22,45 @@ Modular Ruby clients interface for REST APIs
 
 There has been an explosion in the number of REST APIs available today.
 To address the need for a way to access these APIs easily and elegantly,
-we have developed [rest-core][], which consists of composable middleware
+we have developed rest-core, which consists of composable middleware
 that allows you to build a REST client for any REST API. Or in the case of
 common APIs such as Facebook, Github, and Twitter, you can simply use the
 dedicated clients provided by [rest-more][].
 
-[rest-core]: https://github.com/cardinalblue/rest-core
 [rest-more]: https://github.com/cardinalblue/rest-more
 
 ## FEATURES:
 
 * Modular interface for REST clients similar to WSGI/Rack for servers.
-* Asynchronous/Synchronous styles with or without fibers are both supported.
+* Concurrent requests with synchronous or asynchronous interfaces with
+  fibers or threads are both supported.
 
 ## REQUIREMENTS:
 
 ### Mandatory:
 
-* MRI (official CRuby) 1.8.7, 1.9.2, 1.9.3, Rubinius 1.8/1.9 and JRuby 1.8/1.9
+* MRI (official CRuby) 1.9.3, Rubinius 1.9 and JRuby 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)
+* gem json or yajl-ruby, or multi_json (if `JsonResponse` or
+  `JsonRequest` middlewares are used)
 
 [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-core
+gem install rest-core
 ```
 
 Or if you want development version, put this in Gemfile:
 
 ``` ruby
-    gem 'rest-core', :git => 'git://github.com/cardinalblue/rest-core.git',
-                     :submodules => true
+gem 'rest-core', :git => 'git://github.com/cardinalblue/rest-core.git',
+                 :submodules => true
 ```
 
 If you just want to use Facebook or Twitter clients, please take a look at
@@ -74,235 +70,231 @@ If you just want to use Facebook or Twitter clients, please take a look at
 
 ## Build Your Own Clients:
 
-You can use `RestCore::Builder` to build your own dedicated client:
+You can use `RestCore::Builder` to build your own dedicated clients.
+Note that `RC` is an alias of `RestCore`
 
 ``` ruby
-    require 'rest-core'
-
-    YourClient = RestCore::Builder.client do
-      s = RestCore
-      use s::DefaultSite , 'https://api.github.com/users/'
-      use s::JsonDecode  , true
-      use s::CommonLogger, method(:puts)
-      use s::Cache       , nil, 3600
-      run s::RestClient # the simplest and easier HTTP client
-    end
+require 'rest-core'
+YourClient = RC::Builder.client do
+  use RC::DefaultSite , 'https://api.github.com/users/'
+  use RC::JsonResponse, true
+  use RC::CommonLogger, method(:puts)
+  use RC::Cache       , nil, 3600
+end
 ```
 
 And use it with per-instance basis (clients could have different
 configuration, e.g. different cache time or timeout time):
 
 ``` ruby
-    client = YourClient.new(:cache => {})
-    client.get('cardinalblue') # cache miss
-    client.get('cardinalblue') # cache hit
+client = YourClient.new(:cache => {})
+client.get('cardinalblue') # cache miss
+client.get('cardinalblue') # cache hit
 
-    client.site = 'http://github.com/api/v2/json/user/show/'
-    client.get('cardinalblue') # cache miss
-    client.get('cardinalblue') # cache hit
+client.site = 'http://github.com/api/v2/json/user/show/'
+client.get('cardinalblue') # cache miss
+client.get('cardinalblue') # cache hit
 ```
 
-Runnable example is here: [example/rest-client.rb][]. Please see [rest-more][]
-for more complex examples, and [slides][] from [rubyconf.tw/2011][rubyconf.tw]
-for concepts.
-
-[example/rest-client.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/rest-client.rb
-[rest-more]: https://github.com/cardinalblue/rest-more
-[slides]: http://www.godfat.org/slide/2011-08-27-rest-core.html
-[rubyconf.tw]: http://rubyconf.tw/2011/#6
-
-## Asynchronous HTTP Requests:
-
-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. Below is an example for eventmachine:
+You can also make concurrent requests easily:
+(see "Advanced Concurrent HTTP Requests -- Embrace the Future" for detail)
 
 ``` ruby
-    require 'rest-core'
-
-    AsynchronousClient = RestCore::Builder.client do
-      s = RestCore
-      use s::DefaultSite , 'https://api.github.com/users/'
-      use s::JsonDecode  , true
-      use s::CommonLogger, method(:puts)
-      use s::Cache       , nil, 3600
-      run s::EmHttpRequest
-    end
+a = [client.get('cardinalblue')['name'], client.get('godfat')['name']]
+puts "It's not blocking... but doing concurrent requests underneath"
+p a # here we want the values, so it blocks here
+puts "DONE"
 ```
 
-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.
+Callback mode also available:
 
 ``` ruby
-    client = AsynchronousClient.new
-    EM.run{
-      client.get('cardinalblue'){ |response|
-        p response
-        EM.stop
-      }
-      puts "It's not blocking..."
-    }
+client.get('cardinalblue'){ |v| p v }
+puts "It's not blocking... but doing concurrent requests underneath"
+client.wait # we block here to wait for the request done
+puts "DONE"
 ```
 
-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.
+Runnable example is at: [example/simple.rb][]. Please see [rest-more][]
+for more complex examples to build clients, and [slides][] from
+[rubyconf.tw/2011][rubyconf.tw] for concepts.
 
-``` ruby
-    EM.run{
-      Fiber.new{
-        p client.get('cardinalblue')
-        EM.stop
-      }.resume
-      puts "It's not blocking..."
-    }
-```
-
-[em-synchrony]: https://github.com/igrigorik/em-synchrony
-
-Runnable example is here: [example/eventmachine.rb][].
-You can also make multi-requests synchronously like this:
-
-``` ruby
-    EM.run{
-      Fiber.new{
-        fiber = Fiber.current
-        result = {}
-        client.get('cardinalblue'){ |response|
-          result[0] = response
-          fiber.resume(result) if result.size == 2
-        }
-        client.get('cardinalblue'){ |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][].
-
-[example/eventmachine.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/eventmachine.rb
-[example/multi.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/multi.rb
-
-## Supported HTTP clients:
+[example/simple.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/simple.rb
+[rest-more]: https://github.com/cardinalblue/rest-more
+[slides]: http://www.godfat.org/slide/2011-08-27-rest-core.html
+[rubyconf.tw]: http://rubyconf.tw/2011/#6
 
-* `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)
+## List of built-in Middlewares:
+
+* `RC::AuthBasic`
+* `RC::Bypass`
+* `RC::Cache`
+* `RC::CommonLogger`
+* `RC::DefaultHeaders`
+* `RC::DefaultPayload`
+* `RC::DefaultQuery`
+* `RC::DefaultSite`
+* `RC::Defaults`
+* `RC::ErrorDetector`
+* `RC::ErrorDetectorHttp`
+* `RC::ErrorHandler`
+* `RC::FollowRedirect`
+* `RC::JsonRequest`
+* `RC::JsonResponse`
+* `RC::Oauth1Header`
+* `RC::Oauth2Header`
+* `RC::Oauth2Query`
+* `RC::Timeout`
 
 ## Build Your Own Middlewares:
 
 To be added.
 
-## Build Your Own HTTP clients:
-
-To be added.
-
-## rest-core users:
-
-* [topcoder](https://github.com/miaout17/topcoder)
-* [s2sync](https://github.com/brucehsu/s2sync)
-* [s2sync_web](https://github.com/brucehsu/s2sync_web)
+## Advanced Concurrent HTTP Requests -- Embrace the Future
 
-## Powered sites:
+### The Interface
 
-* [PicCollage](http://pic-collage.com/)
+There are a number of different ways to make concurrent requests in
+rest-core. They could be roughly categorized to two different forms.
+One is using the well known callbacks, while the other one is using
+through a technique called [future][]. Basically, it means it would
+return you a promise, which would eventually become the real value
+(response here) you were asking for whenever you really want it.
+Otherwise, the program keeps running until the value is evaluated,
+and blocks there if the computation (response) hasn't been done yet.
+If the computation is already done, then it would simply return you
+the result.
 
-## CHANGES:
+Here's a very simple example for using futures:
 
-* [CHANGES](https://github.com/cardinalblue/rest-core/blob/master/CHANGES.md)
+``` ruby
+require 'rest-core'
+YourClient = RC::Builder.client do
+  use RC::DefaultSite , 'https://api.github.com/users/'
+  use RC::JsonResponse, true
+  use RC::CommonLogger, method(:puts)
+end
+
+client = YourClient.new
+puts "rest-client with threads doing concurrent requests"
+a = [client.get('cardinalblue')['name'], client.get('godfat')['name']]
+puts "It's not blocking... but doing concurrent requests underneath"
+p a # here we want the values, so it blocks here
+puts "DONE"
+```
 
-## GLOSSARY:
+And here's a corresponded version for using callbacks:
 
-* A _client_ is a class which can new connections to make requests.
-  For instance, `RestCore::Facebook.new.get('4')`
+``` ruby
+require 'rest-core'
+YourClient = RC::Builder.client do
+  use RC::DefaultSite , 'https://api.github.com/users/'
+  use RC::JsonResponse, true
+  use RC::CommonLogger, method(:puts)
+end
+
+client = YourClient.new
+puts "rest-client with threads doing concurrent requests"
+client.get('cardinalblue'){ |v|
+         p v['name']
+       }.
+       get('godfat'){ |v|
+         p v['name']
+       }
+puts "It's not blocking... but doing concurrent requests underneath"
+client.wait # until all requests are done
+puts "DONE"
+```
 
-* 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.
+You can pick whatever works for you.
 
-* 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.
+[future]: http://en.wikipedia.org/wiki/Futures_and_promises
 
-* `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`.
+### What Concurrency Model to Choose?
 
-* `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.
+In the above example, we're using rest-client with threads, which works
+for most of cases. But you might also want to use em-http-request with
+EventMachine, which is using a faster HTTP parser. In theory, it should
+be much more efficient than rest-client and threads.
 
-* `RestCore::Middleware` is a utility which could help you build a non-trivial
-  middleware. More explanation to come...
+To pick em-http-request, you must run the requests inside the EventMachine's
+event loop, and also wrap your request with either a thread or a fiber,
+because we can't block the event loop and ask em-http-request to finish
+its job making requests.
 
-* `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.
+Here's an example of using em-http-request with threads:
 
-* `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.
+``` ruby
+require 'em-http-request'
+require 'rest-core'
+YourClient = RC::Builder.client do
+  use RC::DefaultSite , 'https://api.github.com/users/'
+  use RC::JsonResponse, true
+  use RC::CommonLogger, method(:puts)
+end
+
+client = YourClient.new
+puts "eventmachine with threads doing concurrent requests"
+EM.run{
+  Thread.new{
+    p [client.get('cardinalblue')['name'], client.get('godfat')['name']]
+    puts "DONE"
+    EM.stop
+  }
+  puts "It's not blocking... but doing concurrent requests underneath"
+}
+```
 
-* 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.
+And here's an example of using em-http-request with fibers:
 
-* `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`.
+``` ruby
+require 'fiber'           # remember to require fiber first,
+require 'em-http-request' # or rest-core won't pick fibers
+require 'rest-core'
+YourClient = RC::Builder.client do
+  use RC::DefaultSite , 'https://api.github.com/users/'
+  use RC::JsonResponse, true
+  use RC::CommonLogger, method(:puts)
+end
+
+client = YourClient.new
+puts "eventmachine with fibers doing concurrent requests"
+EM.run{
+  Fiber.new{
+    p [client.get('cardinalblue')['name'], client.get('godfat')['name']]
+    puts "DONE"
+    EM.stop
+  }
+  puts "It's not blocking... but doing concurrent requests underneath"
+}
+```
 
-* `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.
+As you can see, both of them are quite similar to each other, because the
+idea behind the scene is the same. If you don't know what concurrency model
+to pick, start with rest-client since it's the easiest one to setup.
 
-* `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.
+A full runnable example is at: [example/multi.rb][]. If you want to know
+all the possible use cases, you can also see: [example/use-cases.rb][]. It's
+also served as a test for each possible combinations, so it's quite complex
+and complete.
 
-* `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.
+[example/multi.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/multi.rb
 
-* `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.
+[example/use-cases.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/use-cases.rb
 
-* `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.
+## rest-core users:
 
-* `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.
+* [topcoder](https://github.com/miaout17/topcoder)
+* [s2sync](https://github.com/brucehsu/s2sync)
+* [s2sync_web](https://github.com/brucehsu/s2sync_web)
 
-* `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.
+## Powered sites:
 
-* `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.
+* [PicCollage](http://pic-collage.com/)
 
-* `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_.
+## CHANGES:
 
-* `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_.
+* [CHANGES](https://github.com/cardinalblue/rest-core/blob/master/CHANGES.md)
 
 ## CONTRIBUTORS: