weary 0.6.0 → 0.7.0

data/README.md

@@ -1,15 +1,13 @@
 # Weary
 
-_The Weary need REST_
+Weary is a tiny DSL for making the consumption of RESTful web services simple. It has evolved from the ideas put forth by libraries like [HTTParty](http://github.com/jnunemaker/httparty/ "JNunemaker's HTTParty") and [Typhoeus](http://github.com/pauldix/typhoeus "Paul Dix's Typhoeus"). It provides some sweet syntactic sugar over the Net/HTTP standard library.
 
-Weary is a tiny DSL for making the consumption of RESTful web services simple. It is the little brother to [HTTParty](http://github.com/jnunemaker/httparty/ "JNunemaker's HTTParty"). It provides a thin, gossamer-like layer over the Net/HTTP library.
-
-The things it do:
+What does it do:
 
 + Quickly build an interface to your favorite REST API.
 + Parse XML and JSON with the [Crack](http://github.com/jnunemaker/crack) library.
-+ Authenticate, basically, with Basic Authentication.
-+ Consume with [OAuth](http://oauth.net/)
++ Authentication with Basic Authentication and [OAuth](http://oauth.net/).
++ Asynchronous, multi-threaded requests.
 
 Browse the documentation here: [http://rdoc.info/projects/mwunsch/weary](http://rdoc.info/projects/mwunsch/weary)
 Peruse the [Wiki](http://wiki.github.com/mwunsch/weary) to discover libraries built with Weary and a more thorough review of the API.
@@ -19,6 +17,7 @@ Peruse the [Wiki](http://wiki.github.com/mwunsch/weary) to discover libraries bu
 + [Crack](http://github.com/jnunemaker/crack) >= 0.1.2
 + [OAuth](http://github.com/mojodna/oauth) >= 0.3.5
 + [RSpec](http://rspec.info/) (for running the tests)
++ [FakeWeb](http://github.com/chrisk/fakeweb) (for running the tests)
 
 ## Installation
 
@@ -42,10 +41,9 @@ You do have Rubygems right? You do use [Gemcutter](http://gemcutter.org/), right
 	me = user.show(:id => "markwunsch").perform
 	puts me["name"]
 	
-Hey, that's me!	
-	
+Hey, that's me!
 
-## How it works
+## The Base API/DSL
 
 Create a class that inherits from `Weary::Base` to give it methods to craft a resource request:
 
@@ -58,7 +56,7 @@ Create a class that inherits from `Weary::Base` to give it methods to craft a re
 	
 If you instantiate this class, you'll get an instance method named `foo` that crafts a GET request to "http://path/to/foo"
 
-Besides the name of the resource, you can also give `declare_resource` a block like:
+Besides the name of the resource, you can also give `declare` a block like:
 
 	declare "foo" do |r|
 		r.url = "path/to/foo"
@@ -73,7 +71,7 @@ Besides the name of the resource, you can also give `declare_resource` a block l
 So this would form a method:
 	
 	x = Foo.new
-	x.foo(:id => "mwunsch", :bar => 123)
+	x.foo :id => "mwunsch", :bar => 123
 	
 That method would return a `Weary::Request` object. Use the `perform` method and get a `Weary::Response` that you could parse and/or examine.
 
@@ -109,7 +107,7 @@ There are many ways to form URLs in Weary. You can define URLs for the entire cl
 		get "show_users"
 	end
 	
-If you don't supply a url when declaring the Resource, Weary will look to see if you've defined a domain, and will make a url for you. The above `get` declaration creates a url that looks like: *http://foo.bar/show_users.xml*
+If you don't supply a url when declaring the Resource, Weary will look to see if you've defined a domain, and will make a url for you. The above `get` declaration creates a url that looks like: *http://foo.bar/show_users.xml*. I think it's better to write the whole URL out. That's unambiguous.
 	
 ### Weary DSL
 
@@ -135,5 +133,89 @@ Then you can do something like this:
 	f.update
 	
 Which will create a POST Request for *http://foo.bar/update.xml* that will authenticate you, using basic authentication, with the username/password of "me"/"secrets" and will send the parameter `{:user => "me"}`. Easy.
+
+## Weary Class Methods
+
+Maybe you don't want the baggage that comes with `Weary::Base`. That's okay, Weary provides some basic class-level methods to Easily build a `Weary::Request`:
+
+	# See examples/repo.rb to see this in practice
+	class Repository
+
+	  def show(user, repo)
+	    Weary.get "http://github.com/api/v2/yaml/repos/show/#{user}/#{repo}"
+	  end
+
+	end
+	
+	Repository.new.show 'mwunsch', 'weary'
+	
+That will build the Get request to fetch the YAML info about this repository.
+
+Pass a block to `Weary.get` to dive further into the Request:
+
+	Weary.get "http://twitter.com/statuses/user_timeline" do |req|
+		req.follows = false
+		req.with = {:id => 'markwunsch'}
+		req.credentials = {:username => 'markwunsch', :password => 'secret'}
+		req.headers = {"User-Agent" => Weary::UserAgents["Safari 4.0.2 - Mac"]}
+	end
+	
+## Request Callbacks
+
+A `Weary::Request` has a couple of callbacks you can do:
+
+	status = Weary.get("http://twitter.com/statuses/user_timeline") do |r|
+		r.with = {:id => 'markwunsch'}
+	end
+	
+	status.before_send do |request|
+		puts "Sending a request to #{request.uri}"
+	end
+	
+	status.on_complete do |response|
+		if response.success?
+			puts response.body
+		else
+			puts "Something went wrong: #{response.code}: #{response.message}"
+		end
+	end
+	
+`before_send` is sent just before the request is made, and `on_complete` is triggered immediately following. `before_send` passes the Request object to the block and `on_complete` passes the Response object.
+
+You don't need to define `on_complete`, though. Passing a block to the `perform` method of the Request also defines this callback or will overwrite what you had previously defined:
+
+	status.perform do |response|
+		puts "Request to #{response.url}, complete. Got a #{response.code}."
+	end
+	
+## Multiple Asynchronous Requests with Batch
+
+Requests, along with the `perform` method, also has a `perform!` method, which spins off a Thread to actually perform the Net::HTTP Request. This method returns a Thread object, and is encapsulated by the `perform` method.
+
+Weary::Batch allows you to make a group of `perform!` requests, firing at will. It takes a group of Requests.
+
+	# see examples/batch.rb
+	resources = %w[http://twitter.com http://github.com http://vimeo.com http://tumblr.com]
+	requests = []
+	
+	## build the group of requests:
+	resources.each do |url|
+		requests << Weary.get(url) do |req|
+			req.on_complete {|res| puts "Hello from #{res.url}"}
+		end
+	end
+	
+	## And fire them off:
+	Weary.batch(requests).perform
+	
+Batch has callbacks, just like the Request:
+
+	Weary.batch(requests).perform do
+		puts 'All done.'
+	end
+
+You can investigate the pool of threads once you've called `perform` with `Batch#pool` or look at all the returned responses with `Batch#responses`.
+
+## And more...
 	
-There's more to discover in the Wiki.	
+There's more to discover in the Wiki.

data/Rakefile

@@ -20,42 +20,18 @@ begin
     gemspec.summary = "A little DSL for consuming RESTful web services"
     gemspec.email = "mark@markwunsch.com"
     gemspec.homepage = "http://github.com/mwunsch/weary"
-    gemspec.description = "The Weary need REST: a tiny DSL that makes the consumption of RESTful web services simple."
+    gemspec.description = "A tiny DSL that makes the consumption of RESTful web services simple."
     gemspec.authors = "Mark Wunsch"
-    gemspec.add_dependency('crack', '>= 0.1.2')
-    gemspec.add_dependency('oauth', '>= 0.3.5')
+    gemspec.add_dependency 'crack', '>= 0.1.2'
+    gemspec.add_dependency 'oauth', '>= 0.3.5'
+    gemspec.add_development_dependency 'rspec'
+    gemspec.add_development_dependency 'fakeweb'
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"  
 end
 
-begin
-  require 'rake/contrib/sshpublisher'
-  namespace :rubyforge do
-
-    desc "Release gem and RDoc documentation to RubyForge"
-    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
-
-    namespace :release do
-      desc "Publish RDoc to RubyForge."
-      task :docs => [:rdoc] do
-        config = YAML.load(
-            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
-        )
-
-        host = "#{config['username']}@rubyforge.org"
-        remote_dir = "/var/www/gforge-projects/weary/"
-        local_dir = 'doc'
-
-        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
-      end
-    end
-  end
-rescue LoadError
-  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
-end
-
 desc "Open an irb session preloaded with this library"
 task :console do
   sh "irb -rubygems -I lib -r weary.rb"

data/VERSION

@@ -1 +1 @@
-0.6.0
+0.7.0

data/examples/batch.rb

@@ -0,0 +1,20 @@
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rubygems'
+require 'weary'
+require 'fakeweb'
+require 'pp'
+
+hello = "Hello from"
+resources = %w[http://twitter.com http://github.com http://vimeo.com http://tumblr.com]
+resources.each {|url| FakeWeb.register_uri :get, url, :body => "#{hello} #{url}" }
+
+requests = []
+resources.each do |url|
+  requests << Weary.get(url) do |request| 
+    request.on_complete { |response| puts response.body } 
+  end
+end
+
+Weary.batch(requests).perform
+
+FakeWeb.clean_registry

data/examples/repo.rb

@@ -2,19 +2,15 @@ $LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib
 require 'rubygems'
 require 'weary'
 
-class Repository < Weary::Base
+class Repository
   
-  def initialize(user, repo)
-    self.modify_resource(:show) do |r|
-      r.url = "http://github.com/api/v2/yaml/repos/show/#{user}/#{repo}"
-    end
-  end  
-  
-  get "show" do |r|
-    r.url = "http://github.com/api/v2/yaml/repos/show/__gh_user__/__gh_repo__"
+  def show(user, repo)
+    Weary.get "http://github.com/api/v2/yaml/repos/show/#{user}/#{repo}"
   end
       
 end
 
-weary = Repository.new('mwunsch','weary')
-puts weary.show.perform.body
+weary = Repository.new
+weary.show('mwunsch','weary').perform do |response|
+  puts response.body
+end

data/examples/status.rb

@@ -1,6 +1,7 @@
 $LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'rubygems'
 require 'weary'
+require 'pp'
 
 class Status < Weary::Base
   
@@ -14,5 +15,12 @@ class Status < Weary::Base
 end
 
 toots = Status.new
-recent_toot = toots.user_timeline(:id => "markwunsch").perform[0]
-puts "@" + recent_toot["user"]["screen_name"] + ": " + "\"#{recent_toot['text']}\""
+
+toots.user_timeline(:id => "markwunsch").perform do |response|
+  if response.success?
+    recent_toot = response[0]
+    puts "@#{recent_toot['user']['screen_name']}: \"#{recent_toot['text']}\""
+  else
+   puts "#{response.code}: #{response.message}"
+ end
+end

data/lib/weary.rb

@@ -10,19 +10,23 @@ autoload :Yaml, 'yaml'
 require 'weary/request'
 require 'weary/response'
 require 'weary/resource'
+require 'weary/batch'
 require 'weary/exceptions'
 require 'weary/httpverb'
 require 'weary/base'
 
 module Weary
   
+  # Supported HTTP Verbs
   Methods = [:get, :post, :put, :delete, :head]
+  
+  # Supported Content Types
   ContentTypes = { :json  => [:json, 'json', 'application/json', 'text/json', 'application/javascript', 'text/javascript'],
                    :xml   => [:xml, 'xml', 'text/xml', 'application/xml'],
                    :html  => [:html, 'html', 'text/html'],
                    :yaml  => [:yaml, 'yaml', 'application/x-yaml', 'text/yaml'],
-                   :plain => [:plain, 'plain', 'text/plain'] 
-  }
+                   :plain => [:plain, 'plain', 'text/plain'] }
+                   
   # A collection of User Agent strings that I stole from HURL (http://hurl.it)
   UserAgents = {
     "Firefox 1.5.0.12 - Mac" => "Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.8.0.12) Gecko/20070508 Firefox/1.5.0.12",
@@ -33,7 +37,7 @@ module Weary
     "Firefox 3.0.4 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.12) Gecko/2008102920 Firefox/3.0.4",
     "Firefox 3.5.2 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.1.2) Gecko/20090729 Firefox/3.5.2",
     "Firefox 3.5.2 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.1.2) Gecko/20090729 Firefox/3.5.2",
-    "Internet Explorer 5.2.3 – Mac" => "Mozilla/4.0 (compatible; MSIE 5.23; Mac_PowerPC)",
+    "Internet Explorer 5.2.3 - Mac" => "Mozilla/4.0 (compatible; MSIE 5.23; Mac_PowerPC)",
     "Internet Explorer 5.5" => "Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.1)",
     "Internet Explorer 6.0" => "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)",
     "Internet Explorer 7.0" => "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0)",
@@ -55,10 +59,39 @@ module Weary
     "Safari 4.0.2 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19.1"
   }
   
-  # Weary::Query quickly performs a GET request on a URL and parses the request.
-  def self.Query(url)
-    req = Weary::Request.new(url, :get).perform
-    req.parse
+  class << self
+    def get(url,&block)
+      request url, :get, block
+    end
+    
+    def post(url,&block)
+      request url, :post, block
+    end
+    
+    def put(url,&block)
+      request url, :put, block
+    end
+    
+    def delete(url,&block)
+      request url, :delete, block
+    end
+    
+    def head(url,&block)
+      request url, :head, block
+    end
+    
+    # Create a Request for the URL.
+    # Defaults to a GET Request. Use a block to further modify the Request
+    def request(url,via = :get,block = nil)
+      req = Request.new(url,via)
+      block.call(req) if block
+      req
+    end
+    
+    # Create a Batch for a group of Requests
+    def batch(*requests)
+      Batch.new(requests)
+    end
   end
   
 end

data/lib/weary/base.rb

@@ -16,8 +16,7 @@ module Weary
     
     # Each Weary::Base object has its own set of Resources
     def resources
-      @resources = Marshal.load(Marshal.dump(@@resources)) if !@resources
-      @resources
+      @resources ||= Marshal.load(Marshal.dump(@@resources))
     end
     
     # Make changes to a Resource given and rebuild the Request method for this object

data/lib/weary/batch.rb

@@ -0,0 +1,37 @@
+module Weary
+  class Batch
+    
+    attr_accessor :requests, :pool, :responses
+    
+    def initialize(*requests)
+      @requests = requests.flatten
+    end
+    
+     # A callback that is triggered after all the Responses have been received.
+    def on_complete(&block)
+      @on_complete = block if block_given?
+      @on_complete
+    end
+    
+    # A callback that is triggered before the Requests are performed
+    def before_send(&block)
+      @before_send = block if block_given?
+      @before_send
+    end
+    
+    # Perform each Request in a separate Thread. 
+    # The Threads are collected in `pool`.
+    # The Responses are collected in `responses`.
+    # Pass in a block to use as the on_complete callback.
+    def perform(&block)
+      @on_complete = block if block_given?
+      @responses = []
+      @pool = []
+      before_send.call if before_send
+      requests.each {|req| @pool << req.perform! }
+      pool.each {|res| @responses << res.value }
+      on_complete.call if on_complete
+      responses
+    end
+  end
+end

data/lib/weary/exceptions.rb

@@ -11,5 +11,5 @@ module Weary
   class NotFound            < ClientError; end #404
   class MethodNotAllowed    < ClientError; end #405
   class ResourceConflict    < ClientError; end #409
-  class UnprocessableEntity < ClientError; end #422  
+  class UnprocessableEntity < ClientError; end #422
 end

data/lib/weary/httpverb.rb

@@ -6,7 +6,7 @@ module Weary
     def initialize(http_verb = :get)
       self.verb = http_verb      
     end
-    
+
     def normalize
       return verb.to_s.strip.downcase.intern
     end
@@ -24,7 +24,7 @@ module Weary
         when :head
           Net::HTTP::Head
         else
-          Net::HTTP::Get  
+          raise "Weary does not recognize the HTTP verb '#{normalize.inspect}'."
       end
     end
     

data/lib/weary/request.rb

@@ -1,20 +1,34 @@
 module Weary
   class Request
     
-    attr_reader :uri
-    attr_accessor :options
+    attr_reader :uri, :with, :credentials
+    attr_accessor :headers
   
     def initialize(url, http_verb= :get, options={})
-      self.method = http_verb
       self.uri = url
-      self.options = options
+      self.via = http_verb
+      self.credentials = {:username => options[:basic_auth][:username], 
+                          :password => options[:basic_auth][:password]} if options[:basic_auth]
+      self.credentials = options[:oauth] if options[:oauth]
+      if (options[:body])
+        self.with = options[:body]
+      end
+      self.headers = options[:headers] if options[:headers]
+      self.follows = true
+      if options.has_key?(:no_follow)
+        self.follows = options[:no_follow] ? false : true
+      end
     end
-  
+    
+    # Create a URI object for the given URL
     def uri=(url)
       @uri = URI.parse(url)
+      if (with && !request_preparation.request_body_permitted?)
+        @uri.query = with
+      end
     end
     
-    def method=(http_verb)
+    def via=(http_verb)
       verb = HTTPVerb.new(http_verb).normalize
       @http_verb = if Methods.include?(verb)
         verb
@@ -23,44 +37,113 @@ module Weary
       end
     end
     
-    def method
+    def via
       @http_verb
     end
     
-    def perform
-      req = http.request(request)
-      response = Response.new(req, @http_verb)
-      if response.redirected?
-        return response if options[:no_follow]
-        response.follow_redirect
+    # Set parameters to send with the Request.
+    # If this Request does not accept a body (a GET request for instance),
+    # set the query string for the url.
+    def with=(params)
+      @with = (params.respond_to?(:to_params) ? params.to_params : params)
+      if (!request_preparation.request_body_permitted?)
+        uri.query = @with
       end
-      response
     end
     
-    private
-      def http
-        connection = Net::HTTP.new(@uri.host, @uri.port)
-        connection.use_ssl = @uri.is_a?(URI::HTTPS)
-        connection.verify_mode = OpenSSL::SSL::VERIFY_NONE if connection.use_ssl
-        connection
+    # Credentials to send to Authorize the Request
+    # For basic auth, use a hash with keys :username and :password
+    # For OAuth, use an Access Token
+    def credentials=(auth)
+      if auth.is_a?(OAuth::AccessToken)
+        @credentials = auth
+      else
+        @credentials = {:username => auth[:username], :password => auth[:password]}
       end
+    end
+    
+    # Should the Request follow redirects?
+    def follows=(bool)
+      @follows = (bool ? true : false)
+    end
+
+    def follows?
+      @follows
+    end
+    
+    # A callback that is triggered after the Response is received.
+    def on_complete(&block)
+      @on_complete = block if block_given?
+      @on_complete
+    end
     
-      def request
-        request_class = HTTPVerb.new(@http_verb).request_class        
-        prepare = request_class.new(@uri.request_uri)
-        
-        prepare.body = options[:body].is_a?(Hash) ? options[:body].to_params : options[:body] if options[:body]
-        prepare.basic_auth(options[:basic_auth][:username], options[:basic_auth][:password]) if options[:basic_auth]
-        if options[:headers]
-          options[:headers].each_pair do |key, value|
-            prepare[key] = value
-          end
+    # A callback that is sent before the Request is fired.
+    def before_send(&block)
+      @before_send = block if block_given?
+      @before_send
+    end
+    
+    # Perform the Request, returns the Response. Pass a block in to use
+    # as the on_complete callback.
+    def perform(&block)
+      @on_complete = block if block_given?
+      response = perform!
+      response.value
+    end
+    
+    # Spins off a new thread to perform the Request.
+    def perform!(&block)
+      @on_complete = block if block_given?
+      Thread.new {
+        before_send.call(self) if before_send
+        req = http.request(request)
+        response = Response.new(req, self)
+        if response.redirected? && follows?
+          response.follow_redirect
+        else
+          on_complete.call(response) if on_complete
+          response
         end
-        if options[:oauth]
-          options[:oauth].sign!(prepare)
+      }
+    end
+    
+    # Build the HTTP connection.
+    def http
+      connection = Net::HTTP.new(uri.host, uri.port)
+      connection.verify_mode = OpenSSL::SSL::VERIFY_NONE if connection.use_ssl?
+      connection
+    end
+    
+    # Build the HTTP Request.
+    def request
+      req = request_preparation
+      
+      req.body = with if (with && req.request_body_permitted?)
+      if (credentials)
+        if (credentials.is_a?(OAuth::AccessToken))
+          credentials.sign!(req)
+        else
+          req.basic_auth(credentials[:username], credentials[:password])
+        end
+      end
+      
+      if headers
+        headers.each_pair do |key, value|
+          req[key] = value
         end
-        prepare
       end
+      
+      req
+    end
+    
+    # Prepare the HTTP Request.
+    # The Request has a lifecycle:
+    # Prepare with `request_preparation`
+    # Build with `request`
+    # Fire with `perform`
+    def request_preparation
+      HTTPVerb.new(via).request_class.new(uri.request_uri)
+    end
 
   end
 end