rufus-verbs 0.1

data/README.txt

@@ -0,0 +1,248 @@
+
+= 'rufus-verbs'
+
+== what is it ?
+
+'rufus-verbs' is an extended HTTP client library. 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.
+
+
+== features
+
+currently :
+
+* follows redirections
+* 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)
+
+maybe later :
+
+* retry on failure
+* greediness (automatic parsing for content like JSON or YAML)
+* http digest authentication
+* cache awareness
+* head, options
+
+
+== getting it
+
+    sudo gem install -y 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
+
+
+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 GET) 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/
+
+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>: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>: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>:hba</b> (pair, 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, 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>:nozip</b> (boolean, RE)
+if set to true will prevent gzip encoding (advertising) when GETting content
+
+* <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
+
+* <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>: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
+
+
+== dependencies
+
+the gem rufus-lru[http://rufus.rubyforge.org/rufus-lru]
+
+
+== mailing list
+
+On the OpenWFEru-user list[http://groups.google.com/group/openwferu-users] for now :
+
+    http://groups.google.com/group/openwferu-users
+
+== issue tracker
+
+    http://rubyforge.org/tracker/?atid=18584&group_id=4812&func=browse
+
+
+== source
+
+    svn checkout http://rufus.rubyforge.org/svn/trunk/verbs
+
+
+== author
+
+John Mettraux, jmettraux@gmail.com,
+http://jmettraux.wordpress.com
+
+
+== license
+
+MIT
+

data/lib/rufus/verbs.rb

@@ -0,0 +1,74 @@
+#
+#--
+# Copyright (c) 2008, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# (MIT license)
+#++
+#
+
+#
+# John Mettraux
+#
+# Made in Japan
+#
+# 2008/01/11
+#
+
+require 'rufus/verbs/endpoint'
+require 'rufus/verbs/conditional'
+
+
+module Rufus::Verbs
+
+
+    #
+    # GET
+    #
+    def get (*args)
+
+        EndPoint.request :get, args
+    end
+
+    #
+    # POST
+    #
+    def post (*args, &block)
+
+        EndPoint.request :post, args, &block
+    end
+
+    #
+    # PUT
+    #
+    def put (*args, &block)
+
+        EndPoint.request :put, args, &block
+    end
+
+    #
+    # DELETE
+    #
+    def delete (*args)
+
+        EndPoint.request :delete, args
+    end
+end
+

data/lib/rufus/verbs/conditional.rb

@@ -0,0 +1,142 @@
+#
+#--
+# Copyright (c) 2008, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# (MIT license)
+#++
+#
+
+#
+# John Mettraux
+#
+# Made in Japan
+#
+# 2008/01/16
+#
+
+module Rufus::Verbs
+
+    #
+    # An EndPoint with a cache for conditional GETs.
+    #
+    #     ep = ConditionalEndPoint.new(
+    #         :host => "restful.server", 
+    #         :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 GET) only 
+    #         # returned a 304 answer, the response is returned from the
+    #         # ConditionalEndPoint cache
+    #
+    # The :cache_size option allows to set the size of the conditional GET
+    # cache. The default size is currently 147.
+    #
+    class ConditionalEndPoint < EndPoint
+
+        def initialize (opts)
+
+            super
+
+            cs = opts[:cache_size] || 147
+
+            require 'rubygems'
+            begin
+                require 'rufus/lru'
+            rescue LoadError
+                raise "gem 'rufus-lru' is missing, please install it."
+            end
+
+            @cache = LruHash.new cs
+        end
+
+        #
+        # Returns the count of representation 'cached' here for the
+        # purpose of conditional GET requests.
+        #
+        def cache_current_size
+
+            @cache.size
+        end
+
+        #
+        # Returns the max size of the conditional GET cache.
+        #
+        def cache_size
+
+            @cache.maxsize
+        end
+
+        private
+
+            #
+            # If the representation has already been gotten, send
+            # potential If-Modified-Since and/or If-None-Match.
+            #
+            def add_conditional_headers (req, opts)
+
+                # if path is cached send since and/or match
+
+                e = @cache[opts[:c_uri]]
+
+                return unless e # not cached
+
+                req['If-Modified-Since'] = e.lastmod if e.lastmod
+                req['If-None-Match'] = e.etag if e.etag
+
+                opts[:c_cached] = e
+            end
+
+            def handle_response (method, res, opts)
+
+                # if method is get and reply is 200, cache (if et and/or lm)
+                # if method is get and reply is 304, return from cache
+
+                super
+
+                code = res.code.to_i
+
+                return opts[:c_cached] if code == 304
+
+                cache(res, opts) if code == 200
+
+                res
+            end
+
+            def cache (res, opts)
+
+                class << res
+                    def lastmod
+                        self['Last-Modified']
+                    end
+                    def etag
+                        self['Etag']
+                    end
+                end
+
+                @cache[opts[:c_uri]] = res
+            end
+    end
+end
+