-
Notifications
You must be signed in to change notification settings - Fork 23
Request
Weary::Request is one of the lower level classes of Weary. On it's own, it provides some handy syntactic sugar to make HTTP requests:
Weary::Request.new "http://gist.github.com/api/v1/json/gists/mwunsch", :GETThe Request's env method does most of the magic: it builds a Rack environment.
A Request responds to the call method, takes a Hash, merges that hash with the env and passes that into an Adapter which should return a [status, headers, body] tuple -- meaning any instance of Request is also a Rack application.
Weary::Request.new("http://gist.github.com/api/v1/json/gists/mwunsch").env # A GET request by default
# => {"HTTP_HOST"=>"gist.github.com", "SERVER_NAME"=>"gist.github.com", "rack.url_scheme"=>"http", "PATH_INFO"=>"/api/v1/json/gists/mwunsch", "SCRIPT_NAME"=>"","REQUEST_URI"=>"/api/v1/json/gists/mwunsch", "weary.request"=>#<Weary::Request:0x101747b68 @method="GET", @middlewares=[], @headers={}, @uri=#<Addressable::URI:0x80ba3c4c URI:http://gist.github.com/api/v1/json/gists/mwunsch>, @attachment=#<StringIO:0x101744058>>, "SERVER_PORT"=>"80", "REQUEST_METHOD"=>"GET", "rack.input"=>#<StringIO:0x101744058>, "QUERY_STRING"=>""}Because the call method so heavily manipulates the environment, it is recommended that Rack::Middleware be applied at this level, using Request#use.
request.use Rack::Logger
request.use Rack::CommonLoggerWhen call is called, it actually creates an instance of Rack::Builder, passing the Request's middleware stack in, and finally delegating to the Adapter.
By default, the Adapter is a Net/HTTP adapter, but it can be any Rack application:
request.adapter lambda {|env| [200, {'Content-Type' => 'text/plain'}, [env.inspect]]}Request#call is all well and good for interacting with Rack, but if you want to access the response in an object-oriented fashion and take advantage of Weary's asynchronous features use perform.
Request#perform, under the covers sends the call method and wraps the returned tuple in a Response. This is all done asynchronously, and when you call the perform method, you're getting back a Future: a lightweight proxy object that only blocks the main thread when accessed. Pass a block to perform as a callback to access the Response whenever it's ready:
request.perform {|response| puts response.body if response.success? }Be forewarned! If the previous line of code is the last line of code in your script, you might never see the response.body -- the main thread will end and exit the program before the request has completed.
The Request makes it easy to attach HTTP Headers:
request.headers "User-Agent" => "Weary v1.1.0"There's a convenience method for setting a User Agent header (which you should do):
# Weary provides some User Agents for convenience
request.user_agent Weary::USER_AGENT["Internet Explorer 6.0"]Let's say you want to include some parameters with your request.
request.params :user => "mwunsch"If this is a POST or a PUT request (they allow body content), this will be attached to the body part of the request. Otherwise, this Hash is transformed into the query string on the URL.
You can also attach an IO object to be read into the request:
request.body File.new("path/to/file")There's also a convenience method to send raw JSON in the request:
request.json :user => "mwunsch"Weary provides built-in support for both Basic Auth and OAuth 1.0a at the request level:
request.basic_auth("mwunsch", "my-precious-secret")request.oauth(consumer_key, access_token, token_secret, consumer_secret)Both of these implement some custom Middleware under the covers to work their magic.