'rufus-verbs'

'rufus-verbs' is an extended HTTP client library (gem). It provides the four main HTTP "verbs" as Ruby methods : get, put, post and delete.

It wraps a certain number of techniques that make it a decent tool for manipulating web resources.

Head and Options are supported as well.

currently :

• follows redirections (disable with :noredir => true)
• automatically adds _method={post|put} in the request parameters with the option :fake_put => true
• HTTPS aware ('verify none' by default)
• HTTP basic authentication
• doesn't propagate auth credentials in case of redirection to different host
• advertises and uses gzip compression
• proxy-aware (HTTP_PROXY env var or :proxy option)
• conditional GET (via ConditionalEndPoint class)
• request body built via a block (post and put)
• cookie-aware (if :cookies option is explicitely set to true)
• http digest authentication (rfc 2617) (auth ok, auth-int not tested)
• query parameters are automatically escaped (disable with :no_escape => true)
• fopen(uri) method (feels like open-uri's open method, but provides all the previously mentioned features)

maybe later :

• retry on failure
• cache awareness
• greediness (automatic parsing for content like JSON or YAML)
• persistent cookie jar

gem install rufus-verbs

or download it from RubyForge.

The arguments to the "verbs" follow the schema method_name(uri, opts) or method_name(opts). Post and put accept an optional block parameter.

require 'rufus/verbs'

include Rufus::Verbs

using get(), post(), put() and delete() directly

res = get "http://en.wikipedia.org/wiki/Ruby"
puts res.body

res = get :uri => "http://en.wikipedia.org/wiki/Ruby"
puts res.body

post "http://resta.farian.server:7080/inventory/tools/0", :d => "hammer"
  # passing the data via the :d (or :data) option

res = post "http://resta.farian.server:7080/inventory/tools/1" do
  "sliver bullet"
end
  # the data is generated by a block

puts res.code.to_i
  # 201... resource created, note that by default,
  # an instance of Net::HTTPResponse is returned

puts get("http://resta.farian.server:7080/inventory/tools/0", :body => true)
  # "sliver bullet" (directly returning the content of the response)

# oops, typo

put "http://resta.farian.server:7080/inventory/tools/1" do
  "silver bullet"
end

put "http://resta.farian.server:7080/inventory/tools/1" do |request|
  request['Content-Type'] = "text/plain"
  "no silver bullet"
end
  # the block accepts a 'request' (Net::HTTPREquest) argument

delete "http://resta.farian.server:7080/inventory/tools/0"
  # I don't need that hammer anymore

ms = options "http://resta.farian.server:7080/inventory/tools"
p ms
  # should yield something like [ :get, :head, :post ]

res = head "http://resta.farian.server:7080/inventory/tools"
  # same as get() but only the response headers will be returned
  # not the response body.

Using get() and co via an EndPoint to share common options for a set of requests

ep =
  EndPoint.new(
    :host => "resta.farian.host",
    :port => 7080,
    :resource => "inventory/tools")

res = ep.get :id => 1
  # still a silver bullet ?

res = ep.get :id => 0
  # where did the hammer go ?


A ConditionalEndPoint is an EndPoint that will use conditional GETs whenever possible

```ruby
ep = ConditionalEndPoint.new(
  :host => "resta.farian.zion",
  :port => 7080,
  :resource => "inventory/tools")

res = ep.get :id => 1
  # first call will retrieve the representation completely

res = ep.get :id => 1
  # the server (provided that it supports conditional GETs) only
  # returned a 304 answer, the response is returned from the
  # ConditionalEndPoint cache

More about conditional GETs at http://ruturajv.wordpress.com/2005/12/27/conditional-get-request/

Cookies may be activated for an endpoint in this way :

ep = EndPoint.new :cookies => true

res = ep.get "http://resta.farian.zion/tools/3"
res = ep.post("http://resta.farian.zion/tools") { "hammer" }

Digest authentication and basic authentication are available at request or endpoint level :

ep = EndPoint.new :http_basic_authentication => [ "toto", "secretpass" ]

ep = EndPoint.new :digest_authentication => [ "toto", "secretpass" ]

res = get "http://server/doc0", :hba => [ "toto", "secretpass" ]

res = get(
  "http://server/doc1",
  :digest_authentication => [ "toto", "secretpass" ])

The Rufus::Verbs module provides as well a fopen method, which mostly feels like the open method of open-uri.

res = fopen "CHANGELOG.txt"

Rufus::Verbs.fopen "mydir/mypath.txt" do |f|
  puts f.readlines
end

res = Rufus::Verbs.fopen "http://whatever.nada.ks"

res = Rufus::Verbs.fopen "http://whatever.nada.ks", :noredir => true

But it follows redirections (has all the rufus-verbs features). It's provided for when targets are local files or URIs.

This fopen() method makes sure to return an object that has a read() method (like a File instance has).

The tests may provide good intel as on 'rufus-verbs' usage as well : http://rufus.rubyforge.org/svn/trunk/verbs/test/

A list of options supported by rufus-verbs, in alphabetical order.

Most of the options are, well, optional, see the usage for some clarifications about the preseance of the options among them (trying to do it in the 'least surprise' spirit).

R means that the option can be used at request level only, RE means Request or EndPoint level.

• :auth (proc, RE) this option takes a Ruby proc, it can be used for custom authentication schemes

get "http://resource:7777/items/1", :auth => lambda do |request|
  request['X-Secret-Auth-Header'] = "let me in, it's OK"
end

see :http_basic_authentication for the basic HTTP authentication mechanism

• :base (string, RE) the base of a resource path

  :base / :resource / :id --> "inventory" / "tools" / "7" --> "/inventory/tools/7"

• :body (boolean, RE) by default, a request returns a Net::HTTPResponse instance, with :body => true, the request will return the body of response directly

• :cache_size (integer, ConditionalEndPoint only) by default, a ConditionalEndPoint will cache 147 results (and it'll start discarded the least recently used cached responses). This option is used to set this cache's size.

• :cookies (boolean/integer, E) when not set or set to false, rufus-verbs won't care about cookies. If set to true or an integer value, set-cookie requests by the servers will be honoured. The integer value will be interpreted as the size of the 'cookie jar', the default size being 77. The least recently used cookies will be discarded. The cookie jar implementation is not persistent.

• :d (string, R) the short variant of :data

• :data (string, R) the data (request body) for a put or a post.

• :digest_authentication (pair of strings, RE) the pair username/password to be used for digest authentication.

• :dry_run (boolean, RE) when :dry_run => true, the request will be prepared but not executed and will be returned instead of the HTTP response (used for testing)

• :fake_put (boolean, RE) when set to true, PUT and DELETE requests will be faked as POST requests where the _method query parameter is set to 'put' or 'delete' respectively

• :fd the short version of :form_data

• :form_data this option expects a hash. The (post or put) request body will then be built with this hash.

• :h (a hash String => String, RE) short for :headers

• :headers (a hash String => String, RE) A Hash of additional request headers to pass

• :hba (pair of strings, RE) short for :http_basic_authentication

• :host (string, RE) the host or IP address for the request

• :http_basic_authentication (pair of strings, RE) will activate HTTP basic authentication, takes a pair (array) argument [ user, pass ]

• :id (string, R) the id part of a full resource path (see :base)

• :max_redirections (integer, RE) by default, rufus-verbs will follow any number of redirections. A limit can be set via this option

• :no_escape (boolean, RE) by default, query parameters are escaped. When this option is set to true, no escaping will be performed before the request[s].

• :no_redirections (boolean, RE) when set to 'true', redirections will not be followed, the server response will be returned directly, even if it's a redirection notification.

• :noredir (boolean, RE) the short version for :no_redirections.

• :nozip (boolean, RE) if set to true will prevent gzip encoding (advertising) when GETting content

• :params (hash or string, RE) a hash of parameters that will get appended to the URI of the request. A string like "a=b?x=y" can be given as well (equivalent to :query)

• :path (string, RE) the path (between port and the query string)

• :port (string, RE) the port for the request

• :proxy (uri, string or false, RE) by default, rufus-verbs will try to use the proxy given in the HTTP_PROXY environment variable (URI). If this :proxy option is set to false, no proxy will be used. It can take the value of a URI (String or URI instance) as well.

• :query (hash or string, R) a hash of parameters that will get appended to the URI of the request. A string like "a=b?x=y" can be given as well (equivalent to :params)

• :raw_response (boolean, RE) the request will be executed and the HTTP response will be returned immediately, no redirection following, content decompression or eventual caching (conditional GET) will take place

• :res (string, RE) a short version of :resource

• :resource the resource (or the middle) of a full resource path (see :base)

• :scheme (string, R) 'http' or 'https'

• :ssl_verify_peer (boolean, RE) by default, rufus-verbs doesn't verify ssl certificates. With this option set to true, it will.

• :timeout (integer, RE) sets the timeout (both open_ and read_timeout) for the request (and the endpoint), expects a value expressed in seconds.

• :to (integer, RE) shortcut for :timeout

• :u (uri, string, RE) the short version of :uri

• :uri (uri, string, RE) the URI for the request (or the endpoint)

• :user_agent (string, RE) for setting a custom 'User-Agent' HTTP header

• :v (string/boolean/IO, RE) the short version of :verbose

• :verbose (string/boolean/IO, RE) can be set to true or to an IO instance. If set to true, messages will be directed to STDOUT. Can be set to any IO instance. Will produces verbose messages similar to those of the fine cURL utility.

the gem rufus-lru

On the Rufus-Ruby mailing list:

http://groups.google.com/group/rufus-ruby

http://github.com/jmettraux/rufus-verbs/issues

http://github.com/jmettraux/rufus-verbs

git clone git://github.com/jmettraux/rufus-verbs.git

John Mettraux, jmettraux@gmail.com, http://lambda.io/jmettraux

MIT