jmettraux / rufus-verbs

= 'rufus-verbs'

== what is it ?

'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.


== features

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


== getting it

    gem install rufus-verbs

or download[http://rubyforge.org/frs/?group_id=4812] it from RubyForge.


== usage

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

    require 'rubygems'
    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

    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 <tt>fopen</tt> method, which mostly feels like the <tt>open</tt> 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/


== the options

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.


* <b>:auth</b> (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

* <b>:base</b> (string, RE)
the base of a resource path

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

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

* <b>:cache_size</b> (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.

* <b>:cookies</b> (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.

* <b>:d</b> (string, R)
the short variant of :data

* <b>:data</b> (string, R)
the data (request body) for a put or a post.

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

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

* <b>:fake_put</b> (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

* <b>:fd</b>
the short version of :form_data

* <b>:form_data</b>
this option expects a hash. The (post or put) request body will then be built with this hash.

* <b>:h</b> (a hash String => String, RE) 
short for :headers

* <b>:headers</b> (a hash String => String, RE) 
A Hash of additional request headers to pass

* <b>:hba</b> (pair of strings, RE) 
short for :http_basic_authentication

* <b>:host</b> (string, RE)
the host or IP address for the request

* <b>:http_basic_authentication</b> (pair of strings, RE)
will activate HTTP basic authentication, takes a pair (array) argument [ user, pass ]

* <b>:id</b> (string, R)
the id part of a full resource path (see :base)

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

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

* <b>:no_redirections</b> (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.

* <b>:noredir</b> (boolean, RE)
the short version for :no_redirections.

* <b>:nozip</b> (boolean, RE)
if set to true will prevent gzip encoding (advertising) when GETting content

* <b>:params</b> (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)

* <b>:path</b> (string, RE)
the path (between port and the query string)

* <b>:port</b> (string, RE)
the port for the request

* <b>:proxy</b> (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.

* <b>:query</b> (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)

* <b>:raw_response</b> (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

* <b>:res</b> (string, RE)
a short version of :resource

* <b>:resource</b>
the resource (or the middle) of a full resource path (see :base)

* <b>:scheme</b> (string, R)
'http' or 'https'

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

* <b>:timeout</b> (integer, RE)
sets the timeout (both open_ and read_timeout) for the request (and the endpoint), expects a value expressed in seconds.


* <b>:to</b> (integer, RE)
shortcut for :timeout

* <b>:u</b> (uri, string, RE)
the short version of :uri

* <b>:uri</b> (uri, string, RE)
the URI for the request (or the endpoint)

* <b>:user_agent</b> (string, RE)
for setting a custom 'User-Agent' HTTP header

* <b>:v</b> (string/boolean/IO, RE)
the short version of :verbose

* <b>:verbose</b> (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.


== dependencies

the gem rufus-lru[http://rufus.rubyforge.org/rufus-lru]


== mailing list

On the Rufus-Ruby list[http://groups.google.com/group/rufus-ruby] :

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


== issue tracker

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


== source

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

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


== author

John Mettraux, jmettraux@gmail.com,
http://jmettraux.wordpress.com


== the rest of Rufus

http://rufus.rubyforge.org


== license

MIT