weary 0.4.3 → 0.5.0

data/README.md

@@ -8,14 +8,18 @@ The things 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/)
 
 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.
 
 ## Requirements
 
-+ Crack >= 0.1.2
-+ Nokogiri >= 1.3.1 (if you want to use the #search method)
-+ Rspec (for running the tests)
++ [Crack](http://github.com/jnunemaker/crack) >= 0.1.2
++ [Nokogiri](http://github.com/tenderlove/nokogiri) >= 1.3.1 (if you want to use the #search method)
++ [OAuth](http://github.com/mojodna/oauth) >= 0.3.5 (if you want to use OAuth)
++ [RSpec](http://rspec.info/) (for running the tests)
 
 ## Installation
 
@@ -66,6 +70,8 @@ Besides the name of the resource, you can also give `declare_resource` a block l
 		r.requires = [:id, :bar] 				# an array of params that the resource requires to be in the query/body
 		r.with = [:blah]						# an array of params that you can optionally send to the resource
 		r.authenticates = false					# does the method require basic authentication? defaults to false
+		r.oauth = false							# does this resource use OAuth to authorize you? it's boolean
+		r.access_token = nil					# if you're using OAuth, you should provide the user's access token.
 		r.follows = false						# if this is set to false, the formed request will not follow redirects.
 		r.headers = {'Accept' => 'text/html'}	# send custom headers. defaults to nil.
 	end
@@ -116,4 +122,23 @@ There are many ways to form URLs in Weary. You can define URLs for the entire cl
 The string `<domain><resource>.<format>` helps define a simple pattern for creating URLs. These will be filled in by your resource declaration. The above `get` declaration creates a url that looks like: *http://foo.bar/show_users.xml*
 	
 If you use the `<domain>` flag but don't define a domain, an exception will be raised.
-	
+	
+### Weary DSL
+
+You can create some defaults for all of our resources easily:
+
+	class Foo
+		extend Weary
+
+		domain "http://foo.bar/"
+		url "<domain><resource>.<format>"
+		format :xml
+		headers {'Accept' => 'text/html'}							# set headers
+		authenticates "basic_username","basic_password"				# basic authentication
+		with [:login, :token]										# params that should be sent with every request
+		oauth OAuth::AccessToken.new(consumer, "token", "secret")	# an access token for OAuth
+		
+		post "update"	# uses the defaults defined above!			
+	end
+	
+There's more to discover in the Wiki.	

data/Rakefile

@@ -54,6 +54,11 @@ 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"
+end
+
 Spec::Rake::SpecTask.new do |t|
   t.spec_files = FileList['spec/**/*_spec.rb']
   t.spec_opts = ['--color','--format nested']

data/VERSION

@@ -1 +1 @@
-0.4.3
+0.5.0

data/lib/weary.rb

@@ -8,8 +8,10 @@ require 'rubygems'
 require 'crack'
 
 gem 'nokogiri'
+gem 'oauth'
 autoload :Yaml, 'yaml'
 autoload :Nokogiri, 'nokogiri'
+autoload :OAuth, 'oauth'
 
 require 'weary/request'
 require 'weary/response'
@@ -90,6 +92,14 @@ module Weary
     @headers = headers
   end
   alias set_headers headers
+  
+  # Set the Access Token for OAuth. This must be an OAuth::AccessToken object.
+  # See http://github.com/mojodna/oauth/ to learn how to create Tokens
+  # Setting this will make resources use OAuth and this token by default.
+  def oauth(token)
+    raise ArgumentError, "Token needs to be an OAuth::AccessToken object" unless token.is_a?(OAuth::AccessToken)
+    @oauth = token
+  end
 
   # Declare a resource. Use it with a block to setup the resource
   #
@@ -98,10 +108,13 @@ module Weary
   # [<tt>with</tt>] An array of parameters that will be passed to the body or query of the request. If you pass a hash, it will define default <tt>values</tt> for params <tt>keys</tt>
   # [<tt>requires</tt>] Array of members of <tt>:with</tt> that are required by the resource.
   # [<tt>authenticates</tt>] Boolean value; does the resource require authentication?
+  # [<tt>oauth</tt>] Boolean value; does the resource use OAuth?
+  # [<tt>access_token</tt>] Provide the Token for OAuth. Must be an OAuth::AccessToken object.
   # [<tt>url</tt>] The url of the resource. You can use the same flags as #construct_url
   # [<tt>format</tt>] The format you would like to request. Defaults to json
   # [<tt>follows</tt>] Boolean; Does this follow redirects? Defaults to true
   # [<tt>domain</tt>] Sets the domain you would like this individual resource to be on (if you include the domain flag in <tt>url</tt>)
+  # [<tt>headers</tt>] Set headers for the HTTP Request
   def declare(name)
     resource = prepare_resource(name,:get)
     yield resource if block_given?
@@ -141,6 +154,10 @@ module Weary
       preparation.url = (@url_pattern || "<domain><resource>.<format>")
       preparation.with = @always_with unless @always_with.nil?
       preparation.headers = @headers unless (@headers.nil? || @headers.empty?)
+      if !@oauth.nil?
+        preparation.oauth = true
+        preparation.access_token = @oauth
+      end
       return preparation
     end
     
@@ -148,6 +165,12 @@ module Weary
       if resource.authenticates?
         raise StandardError, "Can not authenticate unless username and password are defined" unless (@username && @password)
       end
+      if resource.oauth?
+        if resource.access_token.nil?
+          raise StandardError, "Access Token is not provided" if @oauth.nil?
+          resource.access_token = @oauth
+        end
+      end
       @resources ||= []
       @resources << resource.to_hash 
       craft_methods(resource)
@@ -214,6 +237,24 @@ module Weary
       if resource.authenticates?
         code << %Q{options[:basic_auth] = {:username => "#{@username}", :password => "#{@password}"} \n}
       end
+      if resource.oauth?
+        consumer_options = ""
+        resource.access_token.consumer.options.each_pair {|k,v| 
+          if k.is_a?(Symbol)
+            k_string = ":#{k}"
+          else
+            k_string = "'#{k}'"
+          end
+          if v.is_a?(Symbol)
+            v_string = ":#{v}"
+          else
+            v_string = "'#{v}'"
+          end
+          consumer_options << "#{k_string} => #{v_string},"
+        }
+        code << %Q{ oauth_consumer = OAuth::Consumer.new("#{resource.access_token.consumer.key}","#{resource.access_token.consumer.secret}",#{consumer_options.chop}) \n}
+        code << %Q{ options[:oauth] = OAuth::AccessToken.new(oauth_consumer, "#{resource.access_token.token}", "#{resource.access_token.secret}") \n}
+      end
       unless resource.follows_redirects?
         code << %Q{options[:no_follow] = true \n}
       end

data/lib/weary/request.rb

@@ -78,6 +78,9 @@ module Weary
             prepare[key] = value
           end
         end
+        if options[:oauth]
+          options[:oauth].sign!(prepare)
+        end
         prepare
       end
 

data/lib/weary/resource.rb

@@ -1,6 +1,6 @@
 module Weary
   class Resource
-    attr_accessor :name, :domain, :with, :requires, :via, :format, :url, :authenticates, :follows, :headers
+    attr_accessor :name, :domain, :with, :requires, :via, :format, :url, :authenticates, :follows, :headers, :oauth, :access_token
     
     def initialize(name)
       self.name = name
@@ -9,6 +9,7 @@ module Weary
       self.follows = true
       self.with = []
       self.requires = []
+      self.oauth = false
     end
     
     def name=(resource_name)
@@ -82,14 +83,38 @@ module Weary
       @url = pattern
     end
     
-    def authenticates?
-      if @authenticates
+    def oauth=(bool)
+      @authenticates = false if bool
+      @oauth = if bool
+        true
+      else
+        false
+      end
+    end
+    
+    def authenticates=(bool)
+      @oauth = false if bool
+      @authenticates = if bool
         true
       else
         false
       end
     end
     
+    def authenticates?
+      @authenticates
+    end
+    
+    def oauth?
+      @oauth
+    end
+    
+    def access_token=(token)
+      raise ArgumentError, "Token needs to be an OAuth::AccessToken object" unless token.is_a?(OAuth::AccessToken)
+      @oauth = true
+      @access_token = token
+    end
+    
     def follows_redirects?
       if @follows
         true
@@ -107,7 +132,9 @@ module Weary
                          :format => @format,
                          :url => @url,
                          :domain => @domain,
-                         :headers => @headers}}
+                         :headers => @headers,
+                         :oauth => oauth?,
+                         :access_token => @access_token}}
     end
     
   end

data/lib/weary/response.rb

@@ -17,14 +17,17 @@ module Weary
       self.format = http_response.content_type
     end
     
+    # Is this an HTTP redirect?
     def redirected?
       @raw.is_a?(Net::HTTPRedirection)
     end
     
+    # Was this Request successful?
     def success?
       (200..299).include?(@code)
     end
     
+    # Returns a symbol corresponding to the Response's Content Type
     def format=(type)
       @format = case type
         when *ContentTypes[:json]
@@ -42,6 +45,7 @@ module Weary
       end
     end
     
+    # Follow the Redirect
     def follow_redirect
       if redirected?
         Request.new(@raw['location'], @method).perform
@@ -66,11 +70,13 @@ module Weary
       end
     end
     
+    # Same as parse[key]
     def [](key)
       parse[key]
     end
     
-    # Search the body with a CSS/XPath selector with Nokogiri
+    # Search the body with a CSS/XPath selector with Nokogiri.
+    # If the document is not XMLish, fall back to #parse and ditch the selector.
     def search(selector)
       if @format == (:xml || :html)
         doc = Nokogiri.parse(@body)

data/spec/weary/request_spec.rb

@@ -38,4 +38,12 @@ describe Weary::Request do
     # not exactly kosher.
   end
   
+  it "should prepare an oauth scheme if a token is provided" do
+    consumer = OAuth::Consumer.new("consumer_token","consumer_secret",{:site => 'http://foo.bar'})
+    token = OAuth::AccessToken.new(consumer, "token", "secret")
+    test = Weary::Request.new("http://foo.bar", :post, {:oauth => token})
+    test.send(:request).oauth_helper.options[:token].should == token
+    # seems a good a way as any to test if OAuth helpers have been added to the request
+  end
+  
 end

data/spec/weary/resource_spec.rb

@@ -35,6 +35,33 @@ describe Weary::Resource do
     @test.authenticates?.should == false
   end
   
+  it "oauth should be boolean" do
+    @test.oauth = "foobar"
+    @test.oauth?.should == true
+    @test.oauth = false
+    @test.oauth?.should == false    
+  end
+  
+  it "oauth should override basic authentication" do
+    @test.authenticates = true
+    @test.oauth = true
+    @test.authenticates?.should == false
+    @test.oauth?.should == true
+  end
+  
+  it "providing an access token should set oauth to true" do
+    consumer = OAuth::Consumer.new("consumer_token","consumer_secret",{:site => 'http://foo.bar'})
+    token = OAuth::AccessToken.new(consumer, "token", "secret")
+    @test.oauth = false
+    @test.access_token = token
+    @test.oauth?.should == true
+    @test.access_token.should == token
+  end
+  
+  it "an access token must contain an OAuth::AccessToken" do
+    lambda { @test.access_token = "foobar" }.should raise_error
+  end
+  
   it 'follows_redirects? should be boolean' do
     @test.follows = "false"
     @test.follows_redirects?.should == true

data/spec/weary_spec.rb

@@ -57,6 +57,39 @@ describe Weary do
     end
   end
   
+  describe "OAuth" do
+    before do
+      consumer = OAuth::Consumer.new("consumer_token","consumer_secret",{:site => 'http://foo.bar'})
+      @token = OAuth::AccessToken.new(consumer, "token", "secret")
+      @test.oauth @token
+    end
+    
+    it "should accept an OAuth Access Token" do
+      @test.instance_variable_get(:@oauth).should == @token
+      lambda { @test.oauth "foobar" }.should raise_error
+    end
+    it "should notify the Resource that this is using OAuth" do
+      @test.domain "http://foo.bar"
+      r = @test.declare("show")
+      r.oauth?.should == true
+      r.access_token.should == @token
+    end
+    it "should be able to handle tokens set within the resource intelligently" do
+      test = Class.new
+      test.instance_eval { extend Weary }
+      test.domain "http://foo.bar"
+      r = test.declare("show")
+      r.oauth?.should == false
+      r.access_token.should == nil
+      r.oauth = true
+      lambda { test.send(:form_resource, r) }.should raise_error
+      r.access_token = @token
+      r.access_token.should == @token
+      test.send(:form_resource, r)[:show][:oauth].should == true
+      test.send(:form_resource, r)[:show][:access_token].should == @token
+    end
+  end
+  
   describe "Set Headers" do
     it "should be a hash of values to pass in the Request head" do
       @test.on_domain "http://foo.bar"

data/weary.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{weary}
-  s.version = "0.4.3"
+  s.version = "0.5.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mark Wunsch"]
-  s.date = %q{2009-06-30}
+  s.date = %q{2009-07-15}
   s.description = %q{The Weary need REST: a tiny DSL that makes the consumption of RESTful web services simple.}
   s.email = %q{mark@markwunsch.com}
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: weary
 version: !ruby/object:Gem::Version 
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors: 
 - Mark Wunsch
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-30 00:00:00 -04:00
+date: 2009-07-15 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency