weary 0.7.2 → 1.0.0.rc1

data/lib/weary/deferred.rb

@@ -0,0 +1,35 @@
+require 'weary/response'
+
+module Weary
+  # A handy abstract proxy class that is used to proxy a domain model
+  # in an asynchronous fashion. Useful if you're not interested in a
+  # Weary::Response object, but you want to pass that into a domain object
+  # when the response is available.
+  class Deferred < defined?(::BasicObject) ? ::BasicObject : ::Object
+
+    instance_methods.each {|m| undef_method(m) if m.to_s !~ /(?:^__|^nil\?$|^send$|^object_id$)/ } \
+      unless defined? ::BasicObject
+
+    attr_reader :callable
+
+    def initialize(future, model, callable=nil)
+      @future = future
+      @model = model
+      @callable = callable || ::Proc.new{|klass, response| klass.new(response) }
+      @target = nil
+    end
+
+    def complete?
+      !!@target
+    end
+
+    def method_missing(method, *args, &block)
+      if @model.method_defined? method
+        @target ||= @callable.call @model, @future.force
+        @target.send(method, *args, &block)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/weary/env.rb

@@ -0,0 +1,32 @@
+module Weary
+  class Env
+    def initialize(request)
+      @request = request
+    end
+
+    def headers
+      Hash[@request.headers.map {|k,v| ["HTTP_#{k.to_s.upcase.gsub('-','_')}", v] }]
+    end
+
+    def env
+      {
+        'REQUEST_METHOD'  => @request.method,
+        'SCRIPT_NAME'     => "",
+        'PATH_INFO'       => @request.uri.path,
+        'QUERY_STRING'    => @request.uri.query || "",
+        'SERVER_NAME'     => @request.uri.host,
+        'SERVER_PORT'     => port,
+        'REQUEST_URI'     => @request.uri.request_uri,
+        'HTTP_HOST'       => @request.uri.host,
+        'rack.url_scheme' => @request.uri.scheme,
+        'rack.input'      => @request.body,
+        'weary.request'   => @request
+      }.update headers
+    end
+
+    def port
+      (@request.uri.port || @request.uri.inferred_port).to_s
+    end
+
+  end
+end

data/lib/weary/middleware.rb

@@ -0,0 +1,9 @@
+module Weary
+  module Middleware
+    autoload :BasicAuth, 'weary/middleware/basic_auth'
+    autoload :OAuth, 'weary/middleware/oauth'
+    autoload :ContentType, 'weary/middleware/content_type'
+  end
+end
+
+

data/lib/weary/middleware/basic_auth.rb

@@ -0,0 +1,17 @@
+module Weary
+  module Middleware
+    class BasicAuth
+      AUTH_HEADER = "HTTP_AUTHORIZATION"
+
+      def initialize(app, credentials)
+        @app = app
+        @auth = [credentials.join(':')].pack('m*')
+      end
+
+      def call(env)
+        env.update AUTH_HEADER => "Basic #{@auth}"
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/weary/middleware/content_type.rb

@@ -0,0 +1,28 @@
+module Weary
+  module Middleware
+    class ContentType
+
+      CONTENT_TYPE = 'CONTENT_TYPE'
+      CONTENT_LENGTH = 'CONTENT_LENGTH'
+      FORM_URL_ENCODED = 'application/x-www-form-urlencoded'
+      MULTIPART_FORM = 'multipart/form-data'
+
+      attr_reader :type
+
+      def initialize(app, type = FORM_URL_ENCODED)
+        @app = app
+        @type = type
+      end
+
+      def call(env)
+        env.update CONTENT_TYPE => @type
+        env.update CONTENT_LENGTH => length(env['rack.input'])
+        @app.call(env)
+      end
+
+      def length(input)
+        input.size.to_s
+      end
+    end
+  end
+end

data/lib/weary/middleware/oauth.rb

@@ -0,0 +1,31 @@
+require 'weary/middleware'
+require 'simple_oauth'
+
+module Weary
+  module Middleware
+    class OAuth
+      AUTH_HEADER = "HTTP_AUTHORIZATION"
+
+      def initialize(app, consumer_key, access_token)
+        @app = app
+        @oauth = {
+          :consumer_key => consumer_key,
+          :token => access_token
+        }
+      end
+
+      def call(env)
+        env.update AUTH_HEADER => sign(env).to_s
+        @app.call(env)
+      end
+
+      def sign(env)
+        req = Rack::Request.new(env)
+        SimpleOAuth::Header.new req.request_method,
+                                req.url,
+                                req.params,
+                                @oauth
+      end
+    end
+  end
+end

data/lib/weary/request.rb

@@ -1,140 +1,153 @@
+require 'addressable/uri'
+require 'future'
+require 'rack'
+
+require 'weary/env'
+require 'weary/adapter'
+
+autoload :Middleware, 'weary/middleware'
+autoload :MultiJson, 'multi_json'
+
 module Weary
+  # A Request is an interface to an http request. It doesn't actually make the
+  # request. Instead, it builds itself up into a Rack environment. A Request
+  # object is technically a Rack middleware, with a call method. The Request
+  # manipulates the passed in environment, then passes on to the adapter: A
+  # Rack application. Because the Request performs so much manipulation on
+  # the Rack env, you can attach middleware to it to act on its mutated env.
   class Request
-    
-    attr_reader :uri, :with, :credentials
-    attr_accessor :headers
-  
-    def initialize(url, http_verb= :get, options={})
+    attr_reader :uri
+
+    def initialize(url, method='GET')
       self.uri = url
-      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]
-      self.with = options[:body] if options[:body]
-      self.headers = options[:headers] if options[:headers]
-      self.follows = options[:no_follow] ? false : true
-    end
-    
-    # Create a URI object for the given URL
+      self.method = method
+      @middlewares = []
+      yield self if block_given?
+    end
+
+    # Set and normalize the url for the Request.
     def uri=(url)
-      @uri = URI.parse(url)
-      if (with && !connection.request_body_permitted?)
-        @uri.query = with
+      uri = Addressable::URI.parse(url).normalize!
+      @uri = uri
+    end
+
+    # A Rack interface for the Request. Applies itself and whatever
+    # middlewares to the env and passes the new env into the adapter.
+    #
+    # environment - A Hash for the Rack env.
+    #
+    # Returns an Array of three items; a Rack tuple.
+    def call(environment)
+      app = adapter.new
+      middlewares = @middlewares
+      stack = Rack::Builder.new do
+        middlewares.each do |middleware|
+          klass, *args = middleware
+          use klass, *args[0...-1].flatten, &args.last
+        end
+        run app
       end
+      stack.call rack_env_defaults.merge(environment.update(env))
+    end
+
+    # Build a Rack environment representing this Request.
+    def env
+      Weary::Env.new(self).env
     end
-    
-    def via=(http_verb)
-      verb = HTTPVerb.new(http_verb).normalize
-      @http_verb = if Methods.include?(verb)
-        verb
-      else
-        :get
+
+    # The HTTP request method for this Request.
+    def method
+      @method
+    end
+
+    # Set and normalize the HTTP request method.
+    def method=(verb)
+      @method = verb.to_s.upcase
+    end
+
+    def headers(hash=nil)
+      @headers = hash unless hash.nil?
+      @headers ||= {}
+    end
+
+    def user_agent(agent)
+      headers.update 'User-Agent' => agent
+    end
+
+    def params(parameters=nil)
+      if !parameters.nil?
+        if ["POST", "PUT"].include? method
+          @body = query_params_from_hash(parameters)
+          body StringIO.new(@body)
+          use Weary::Middleware::ContentType
+        else
+          uri.query_values = parameters
+          @body = uri.query
+        end
       end
+      @body
+    end
+
+    def json(parameters)
+      json = MultiJson.encode(parameters)
+      body StringIO.new(json)
+      json
     end
-    
-    def via
-      @http_verb
-    end
-    
-    # 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 (!connection.request_body_permitted?)
-        uri.query = @with
+
+    def body(io=nil)
+      @attachment = io unless io.nil?
+      @attachment ||= StringIO.new('')
+    end
+
+    def adapter(connection=nil)
+      @connection = connection unless connection.nil?
+      @connection ||= Weary::Adapter::NetHttp
+    end
+
+    def basic_auth(*credentials)
+      if !credentials.empty?
+        @basic_auth = true
+        use Weary::Middleware::BasicAuth, credentials
       end
+      @basic_auth
     end
-    
-    # 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]}
+
+    def oauth(consumer_key=nil, access_token=nil)
+      if !consumer_key.nil? && !access_token.nil?
+        @oauth = true
+        use Weary::Middleware::OAuth, [consumer_key, access_token]
       end
+      @oauth
     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
-    
-    # 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
-      }
-    end
-    
-    # Build the HTTP connection.
-    def http
-      socket = Net::HTTP.new(uri.host, uri.port)
-      socket.use_ssl = uri.is_a?(URI::HTTPS)
-      socket.verify_mode = OpenSSL::SSL::VERIFY_NONE if socket.use_ssl?
-      socket
-    end
-    
-    # Build the HTTP Request.
-    def request
-      req = connection
-      
-      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
+
+    # Returns a future-wrapped Response.
+    def perform
+      future do
+        status, headers, body = call(rack_env_defaults)
+        response = Weary::Response.new body, status, headers
+        yield response if block_given?
+        response
       end
-      
-      headers.each_pair {|key,value| req[key] = value } if headers
-      
-      req
-    end
-    
-    # Prepare the HTTP Request.
-    # The Request has a lifecycle:
-    # Prepare with `request_preparation`
-    # Build with `request`
-    # Fire with `perform`
-    def connection
-      HTTPVerb.new(via).request_class.new(uri.request_uri)
+    end
+
+    def use(middleware, *args, &block)
+      @middlewares << [middleware, args, block]
+    end
+
+    private
+
+    def query_params_from_hash(hash)
+      tmp_uri = Addressable::URI.new
+      tmp_uri.query_values = hash
+      tmp_uri.query
+    end
+
+    def rack_env_defaults
+      { 'rack.version'      => Rack::VERSION,
+        'rack.errors'       => $stderr,
+        'rack.multithread'  => true,
+        'rack.multiprocess' => false,
+        'rack.run_once'     => false }
     end
 
   end

data/lib/weary/resource.rb

@@ -1,135 +1,159 @@
+require 'addressable/template'
+require 'weary/request'
+
 module Weary
+  # A description of a resource made available by an HTTP request. That
+  # description is composed primarily of a url template, the HTTP method to
+  # retrieve the resource and some constraints on the parameters necessary
+  # to complete the request.
   class Resource
-    attr_reader :name, :via, :with, :requires, :url
-    attr_accessor :headers
-    
-    def initialize(name)
-      self.name = name
-      self.via = :get
-      self.authenticates = false
-      self.follows = true
-    end
-    
-    # The name of the Resource. Will be a lowercase string, whitespace replaced with underscores.
-    def name=(resource_name)
-      @name = resource_name.to_s.downcase.strip.gsub(/\s/,'_')
-    end
-    
-    # The HTTP Method used to fetch the Resource
-    def via=(http_verb)
-      verb = HTTPVerb.new(http_verb).normalize
-      @via = Methods.include?(verb) ? verb : :get
-    end
-    
-    # Optional params. Should be an array. Merges with requires if that is set.
-    def with=(params)
-      @with = [params].flatten.collect {|x| x.to_sym}
-      @with = (requires | @with) if requires
-    end
-    
-    # Required params. Should be an array. Merges with `with` or sets `with`.
-    def requires=(params)
-      @requires = [params].flatten.collect {|x| x.to_sym}
-      with ? @with = (with | @requires) : (@with = @requires)
-    end
-    
-    # Sets whether the Resource requires authentication. Always sets to a boolean value.
-    def authenticates=(bool)
-      @authenticates = bool ? true : false
-    end
-    
-    # Does the Resource require authentication?
+    UnmetRequirementsError = Class.new(StandardError)
+
+    attr_reader :method
+
+    def initialize(method, uri)
+      @method = method
+      self.url uri
+    end
+
+    # An accessor method to set the url to retrieve the resource. Use either
+    # brackets to delimit url variables or prefix them with a colon, like
+    # Sinatra.
+    #
+    # Returns an Addressable::Template
+    def url(uri=nil)
+      @uri = Addressable::Template.new(uri.gsub(/:(\w+)/) { "{#{$1}}" }) unless uri.nil?
+      @uri
+    end
+
+    # An accessor to set optional parameters permitted by the resource.
+    #
+    # Returns an Array of parameters.
+    def optional(*params)
+      @optional = params unless params.empty?
+      @optional ||= []
+    end
+
+    # An accessor to set optional parameters required in order to access the
+    # resource.
+    #
+    # Returns an Array of parameters.
+    def required(*params)
+      @required = params unless params.empty?
+      @required ||= []
+    end
+
+    # An accessor to set default paramers to send to the resource.
+    def defaults(hash=nil)
+      @defaults = hash unless hash.nil?
+      @defaults ||= {}
+    end
+
+    # An accessor to set HTTP request headers.
+    def headers(hash=nil)
+      @headers = hash unless hash.nil?
+      @headers ||= {}
+    end
+
+    # Set up a Rack::Middleware to be used by the Request (which is
+    # Rack-friendly).
+    def use(middleware, *args, &block)
+      @middlewares ||= []
+      @middlewares << [middleware, args, block]
+    end
+
+    # Convenience method to set a User Agent Header
+    def user_agent(agent)
+      headers.update 'User-Agent' => agent
+    end
+
+    # Tell the Resource to anticipate Basic Authentication. Optionally,
+    # tell the Resource what parameters to use as credentials.
+    #
+    # user - The parameter in which to expect the username (defaults to :username)
+    # pass - The parameter in which to expect the password (defaults to :password)
+    def basic_auth!(user = :username, pass = :password)
+      @authenticates = :basic_auth
+      @credentials = [user, pass]
+    end
+
+    # Tell the Resource to anticipate OAuth. Optionally, tell the Resource
+    # what parameters to use as the consumer key and access token
+    #
+    # key   - The parameter in which to expect the consumer key (defaults to
+    #         :consumer_key)
+    # token - The parameter in which to expect the user access token (defaults
+    #         to :token)
+    def oauth!(key = :consumer_key, token = :token)
+      @authenticates = :oauth
+      @credentials = [key, token]
+    end
+
+    # Does the Resource anticipate some sort of authentication parameters?
     def authenticates?
-      @authenticates
-    end
-    
-    # Sets whether the Resource should follow redirection. Always sets to a boolean value.
-    def follows=(bool)
-      @follows = bool ? true : false
-    end
-    
-    # Should the resource follow redirection?
-    def follows?
-      @follows
-    end
-    
-    # Set the Resource's URL as a URI
-    def url=(uri)
-      @url = URI.parse(uri)
-    end
-    
-    # A hash representation of the Resource
-    def to_hash
-      {@name.to_sym => { :via => via,
-                         :with => with,
-                         :requires => requires,
-                         :follows => follows?,
-                         :authenticates => authenticates?,
-                         :url => url,
-                         :headers => headers}}
-    end
-    
-    # Take parameters, default params, and credentials and build a Request object for this Resource
-    def build!(params={}, defaults=nil, credentials=nil)
-      uri = @url
-      parameters = setup_parameters(params, defaults)
-      request_opts = setup_options(parameters, credentials)
-      uri.query = request_opts[:query].to_params if request_opts[:query]
-      Request.new(uri.normalize.to_s, @via, request_opts)
-    end
-    
-    # Setup the parameters to make the Request with
-    def setup_parameters(params={}, defaults=nil)
-      params = defaults ? defaults.merge(params) : params
-      find_missing_requirements(params)
-      remove_unnecessary_params(params)
-    end
-    
-    # Search the given parameters to see if they are missing any required params
-    def find_missing_requirements(params)
-      if (@requires && !@requires.empty?)
-        missing_requirements = @requires - params.keys
-        raise ArgumentError, "This resource is missing required parameters: '#{missing_requirements.inspect}'" unless missing_requirements.empty?
-      end
-    end
-    
-    # Remove params that have not been specified with #with
-    def remove_unnecessary_params(params)
-      params.delete_if {|k,v| !@with.include?(k) } if (@with && !@with.empty?)
-    end
-    
-    # Setup the options to be passed into the Request
-    def setup_options(params={}, credentials=nil)
-      options = {}
-      prepare_request_body(params, options)
-      setup_authentication(options, credentials)
-      options[:no_follow] = true if !follows?
-      options[:headers] = @headers if !@headers.blank?
-      options
-    end
-    
-    # Prepare the Request query or body depending on the HTTP method
-    def prepare_request_body(params, options={})
-      if (@via == :post || @via == :put)
-          options[:body] = params unless params.blank?
-      else
-          options[:query] = params unless params.blank?
-      end
-      options
-    end
-    
-    # Prepare authentication credentials for the Request
-    def setup_authentication(options, credentials=nil)
-      if authenticates?
-        raise ArgumentError, "This resource requires authentication and no credentials were given." if credentials.blank?
-        if credentials.is_a?(OAuth::AccessToken)
-          options[:oauth] = credentials
-        else
-          options[:basic_auth] = credentials
+      !!@authenticates
+    end
+
+    # The keys expected as parameters to the Request.
+    def expected_params
+      defaults.keys.map(&:to_s) | optional.map(&:to_s) | required.map(&:to_s)
+    end
+
+    # Does the Resource expect this parameter to be used to make the Request?
+    def expects?(param)
+      expected_params.include? param.to_s
+    end
+
+    # The parameter keys that must be fulfilled to create the Request.
+    def requirements
+      required.map(&:to_s) | url.keys
+    end
+
+    # Given a hash of Request parameters, do they meet the requirements?
+    def meets_requirements?(params)
+      requirements.reject {|k| params.keys.map(&:to_s).include? k.to_s }.empty?
+    end
+
+    # Construct the request from the given parameters.
+    #
+    # Yields the Request
+    #
+    # Returns the Request.
+    # Raises a Weary::Resource::UnmetRequirementsError if the requirements
+    #   are not met.
+    def request(params={})
+      params.delete_if {|k,v| v.nil? || v.to_s.empty? }
+      params.update(defaults)
+      raise UnmetRequirementsError, "Required parameters: #{requirements}" \
+        unless meets_requirements? params
+      credentials = pull_credentials params if authenticates?
+      mapping = url.keys.map {|k| [k, params.delete(k) || params.delete(k.to_sym)] }
+      request = Weary::Request.new url.expand(Hash[mapping]), @method do |r|
+        r.headers headers
+        if !expected_params.empty?
+          r.params params.reject {|k,v| !expects? k }
+        end
+        r.send @authenticates, *credentials if authenticates?
+        if !@middlewares.nil? && !@middlewares.empty?
+          @middlewares.each {|middleware| r.use *middleware }
         end
       end
-      options
-    end
-    
+      yield request if block_given?
+      request
+    end
+    alias build request
+
+
+    private
+
+    # Private: Separate the credentials for authentication from the other
+    # request parameters.
+    def pull_credentials(params)
+      (@credentials || []).map do |credential|
+        params.delete(credential) || params.delete(credential.to_s)
+      end.compact
+    end
+
+
   end
 end