pezra-resourceful 0.5.4

data/lib/resourceful/options_interpretation.rb

@@ -0,0 +1,72 @@
+module Resourceful
+  # Declarative way of interpreting options hashes
+  #
+  #    include OptionsInterpretion
+  #    def my_method(opts = {})
+  #      extract_opts(opts) do |opts|
+  #        host = opts.extract(:host)
+  #        port = opts.extract(:port, :default => 80) {|p| Integer(p)}
+  #      end
+  #    end
+  #
+  module OptionsInterpretation
+    # Interpret an options hash
+    #
+    # @param [Hash] opts
+    #   The options to interpret.
+    # 
+    # @yield block that used to interpreter options hash
+    #
+    # @yieldparam [Resourceful::OptionsInterpretion::OptionsInterpreter] interpeter
+    #   An interpreter that can be used to extract option information from the options hash.
+    def extract_opts(opts, &blk)
+      opts = opts.clone
+      yield OptionsInterpreter.new(opts)
+
+      unless opts.empty?
+        raise ArgumentError, "Unrecognized options: #{opts.keys.join(", ")}"
+      end
+
+    end
+
+    class OptionsInterpreter
+      def initialize(options_hash)
+        @options_hash = options_hash
+      end
+   
+      # Extract a particular option.
+      #
+      # @param [String] name
+      #   Name of option to extract
+      # @param [Hash] interpreter_opts
+      #   ':default'
+      #   :: The default value, or an object that responds to #call 
+      #      with the default value.
+      #   ':required'
+      #   :: Boolean indicating if this option is required.  Default: 
+      #      false if a default is provided; otherwise true.
+      def extract(name, interpreter_opts = {}, &blk)
+        option_required = !interpreter_opts.has_key?(:default)
+        option_required = interpreter_opts[:required] if interpreter_opts.has_key?(:required)
+        
+        raise ArgumentError, "Required option #{name} not provided" if option_required && !@options_hash.has_key?(name) 
+        # We have the option we need
+
+        orig_val = @options_hash.delete(name)
+        
+        if block_given?
+          yield orig_val
+
+        elsif orig_val
+          orig_val
+          
+        elsif interpreter_opts[:default] && interpreter_opts[:default].respond_to?(:call)
+          interpreter_opts[:default].call()
+
+        elsif interpreter_opts[:default]
+          interpreter_opts[:default]
+        end
+      end
+    end
+  end
+end

data/lib/resourceful/request.rb

@@ -0,0 +1,234 @@
+require 'pathname'
+require 'benchmark'
+require 'resourceful/response'
+require 'resourceful/net_http_adapter'
+require 'resourceful/exceptions'
+
+module Resourceful
+
+  class Request
+
+    REDIRECTABLE_METHODS = [:get, :head]
+    CACHEABLE_METHODS = [:get, :head]
+    INVALIDATING_METHODS = [:post, :put, :delete]
+
+    attr_accessor :method, :resource, :body, :header
+    attr_reader   :request_time, :accessor
+
+    # @param [Symbol] http_method
+    #   :get, :put, :post, :delete or :head
+    # @param [Resourceful::Resource] resource
+    # @param [String] body
+    # @param [Resourceful::Header, Hash] header
+    def initialize(http_method, resource, body = nil, header = nil)
+      @method, @resource, @body = http_method, resource, body
+      @accessor = @resource.accessor
+      @header = header.is_a?(Resourceful::Header) ? header : Resourceful::Header.new(header)
+
+      # Resourceful handled gzip encoding transparently, so set that up
+      @header.accept_encoding ||= 'gzip, identity'
+
+      # 'Host' is a required HTTP/1.1 header, overrides Host in user-provided headers
+      @header.host = @resource.host
+
+      # Setting the date isn't a bad idea, either
+      @header.date ||= Time.now.httpdate
+
+      # Add any auth credentials we might want
+      add_credentials!
+
+    end
+
+    # Uses the auth manager to add any valid credentials to this request
+    def add_credentials!
+      @accessor.auth_manager.add_credentials(self)
+    end
+
+    # Performs all the work. Handles caching, redirects, auth retries, etc
+    def fetch_response
+      if cached_response
+        if needs_revalidation?(cached_response)
+          logger.info("    Cache needs revalidation")
+          set_validation_headers!(cached_response)
+        else
+          # We're done!
+          return cached_response
+        end
+      end
+
+      response = perform!
+
+      response = revalidate_cached_response(response) if cached_response && response.not_modified?
+      response = follow_redirect(response)            if should_be_redirected?(response)
+      response = retry_with_auth(response)            if needs_authorization?(response)
+
+      raise UnsuccessfulHttpRequestError.new(self, response) if response.error?
+
+      if cacheable?(response)
+        store_in_cache(response)
+      elsif invalidates_cache?
+        invalidate_cache
+      end
+
+      return response
+    end
+
+    # Should we look for a response to this request in the cache?
+    def skip_cache?
+      return true unless method.in? CACHEABLE_METHODS
+      header.cache_control && header.cache_control.include?('no-cache')
+    end
+
+    # The cached response
+    def cached_response
+      return if skip_cache?
+      return if @cached_response.nil? && @already_checked_cache
+      @cached_response ||= begin
+        @already_checked_cache = true
+        resp = accessor.cache_manager.lookup(self)
+        logger.info("    Retrieved from cache") if resp
+        resp
+      end
+    end
+
+    # Revalidate the cached response with what we got from a 304 response
+    def revalidate_cached_response(not_modified_response)
+      logger.info("    Resource not modified")
+      cached_response.revalidate!(not_modified_response)
+      cached_response
+    end
+
+    # Follow a redirect response
+    def follow_redirect(response)
+      raise MalformedServerResponse.new(self, response) unless response.header.location
+      if response.moved_permanently?
+        new_uri = response.header.location.first
+        logger.info("    Permanently redirected to #{new_uri} - Storing new location.")
+        resource.update_uri new_uri
+        @header.host = resource.host
+        response = fetch_response
+      elsif response.see_other? # Always use GET for this redirect, regardless of initial method
+        redirected_resource = Resourceful::Resource.new(self.accessor, response.header['Location'].first)
+        response = Request.new(:get, redirected_resource, body, header).fetch_response
+      else
+        redirected_resource = Resourceful::Resource.new(self.accessor, response.header['Location'].first)
+        logger.info("    Redirected to #{redirected_resource.uri} - Caching new location.")
+        response = Request.new(method, redirected_resource, body, header).fetch_response
+      end
+    end
+
+    # Add any auth headers from the response to the auth manager, and try the request again
+    def retry_with_auth(response)
+      @already_tried_with_auth = true
+      logger.info("Authentication Required. Retrying with auth info")
+      accessor.auth_manager.associate_auth_info(response)
+      add_credentials!
+      response = fetch_response
+    end
+
+    # Does this request need to be authorized? Will only be true if we haven't already tried with auth
+    def needs_authorization?(response)
+      !@already_tried_with_auth && response.unauthorized?
+    end
+
+    # Store the response to this request in the cache
+    def store_in_cache(response)
+      # RFC2618 - 14.18 : A received message that does not have a Date header 
+      # field MUST be assigned one by the recipient if the message will be cached 
+      # by that recipient.
+      response.header.date ||= response.response_time.httpdate
+
+      accessor.cache_manager.store(self, response) 
+    end
+
+    # Invalidated the cache for this uri (eg, after a POST)
+    def invalidate_cache
+      accessor.cache_manager.invalidate(resource.uri)
+    end
+
+    # Is this request & response permitted to be stored in this (private) cache?
+    def cacheable?(response)
+      return false unless response.success?
+      return false unless method.in? CACHEABLE_METHODS
+      return false if header.cache_control && header.cache_control.include?('no-store')
+      true
+    end
+
+    # Does this request invalidate the cache?
+    def invalidates_cache?
+      return true if method.in? INVALIDATING_METHODS
+    end
+
+    # Perform the request, with no magic handling of anything.
+    def perform!
+      @request_time = Time.now
+
+      http_resp = adapter.make_request(@method, @resource.uri, @body, @header)
+      @response = Resourceful::Response.new(uri, *http_resp)
+      @response.request_time = @request_time
+      @response.authoritative = true
+
+      @response
+    end
+
+    # Is this a response a redirect, and are we permitted to follow it?
+    def should_be_redirected?(response)
+      return false unless response.redirect?
+      if resource.on_redirect.nil?
+        return true if method.in? REDIRECTABLE_METHODS
+        false
+      else
+        resource.on_redirect.call(self, response)
+      end
+    end
+
+    # Do we need to revalidate our cache?
+    def needs_revalidation?(response)
+      return true if forces_revalidation?
+      return true if response.stale?
+      return true if max_age && response.current_age > max_age
+      return true if response.must_be_revalidated?
+      false
+    end
+
+    # Set the validation headers of a request based on the response in the cache
+    def set_validation_headers!(response)
+      @header['If-None-Match'] = response.header['ETag'] if response.header.has_key?('ETag')
+      @header['If-Modified-Since'] = response.header['Last-Modified'] if response.header.has_key?('Last-Modified')
+      @header['Cache-Control'] = 'max-age=0' if response.must_be_revalidated?    
+    end
+
+    # @return [String]   The URI against which this request will be, or was, made.
+    def uri
+      resource.uri
+    end
+
+    # Does this request force us to revalidate the cache?
+    def forces_revalidation?
+      if max_age == 0 || header.cache_control && cc.include?('no-cache')
+        logger.info("    Client forced revalidation")
+        true
+      else 
+        false
+      end
+    end
+
+    # Indicates the maxmimum response age in seconds we are willing to accept
+    #
+    # Returns nil if we don't care how old the response is
+    def max_age
+      if header['Cache-Control'] and header['Cache-Control'].include?('max-age')
+        header['Cache-Control'].split(',').grep(/max-age/).first.split('=').last.to_i
+      end
+    end
+
+    def logger
+      resource.logger
+    end
+
+    def adapter
+      accessor.http_adapter
+    end
+  end
+
+end

data/lib/resourceful/resource.rb

@@ -0,0 +1,178 @@
+require 'pathname'
+require 'resourceful/request'
+
+module Resourceful
+
+  class Resource
+    attr_reader :accessor
+
+    # Build a new resource for a uri
+    #
+    # @param accessor<HttpAccessor> 
+    #   The parent http accessor
+    # @param uri<String, Addressable::URI> 
+    #   The uri for the location of the resource
+    def initialize(accessor, uri, default_header = {})
+      @accessor, @uris = accessor, [uri]
+      @default_header = Resourceful::Header.new({'User-Agent' => Resourceful::RESOURCEFUL_USER_AGENT_TOKEN}.merge(default_header))
+      @on_redirect = nil
+    end
+
+    # The uri used to identify this resource. This is almost always the uri
+    # used to create the resource, but in the case of a permanent redirect, this
+    # will always reflect the lastest uri.
+    #
+    # @return Addressable::URI 
+    #   The current uri of the resource
+    def effective_uri
+      @uris.first
+    end
+    alias uri effective_uri
+
+    def default_header(temp_defaults = {})
+      temp_defaults.merge(@default_header)
+    end
+
+    # Returns the host for this Resource's current uri
+    def host
+      Addressable::URI.parse(uri).host
+    end
+
+    # Updates the effective uri after following a permanent redirect
+    def update_uri(uri)
+      @uris.unshift(uri)
+    end
+
+    # When performing a redirect, this callback will be executed first. If the callback
+    # returns true, then the redirect is followed, otherwise it is not. The request that
+    # triggered the redirect and the response will be passed into the block. This can be
+    # used to update any links on the client side.
+    #
+    # Example:
+    #
+    #   author_resource.on_redirect do |req, resp|
+    #     post.author_uri = resp.header['Location']
+    #   end
+    #
+    # @yieldparam callback<request, response>
+    #   The action to be executed when a request results in a redirect. Yields the 
+    #   current request and result objects to the callback.
+    #
+    # @raise ArgumentError if called without a block 
+    def on_redirect(&callback)
+      if block_given?
+        @on_redirect = callback
+      else
+        @on_redirect
+      end
+    end
+
+    # Performs a GET on the resource, following redirects as neccessary, and retriving
+    # it from the local cache if its available and valid.
+    #
+    # @return [Response] The Response to the final request made.
+    #
+    # @raise [UnsuccessfulHttpRequestError] unless the request is a
+    #   success, ie the final request returned a 2xx response code
+    def get(header = {})
+      request(:get, nil, header)
+    end
+
+    def head(header = {})
+      request(:head, nil, header)
+    end
+    # :call-seq:
+    #   post(data = "", :content_type => mime_type)
+    #
+    # Performs a POST with the given data to the resource, following redirects as 
+    # neccessary.
+    #
+    # @param [String] data
+    #   The body of the data to be posted
+    # @param [Hash] options
+    #   Options to pass into the request header. At the least, :content_type is required.
+    #
+    # @return [Response]  The Response to the final request that was made.
+    #
+    # @raise [ArgumentError] unless :content-type is specified in options
+    # @raise [UnsuccessfulHttpRequestError] unless the request is a
+    #   success, ie the final request returned a 2xx response code
+    def post(data = nil, header = {})
+      request(:post, data, header)
+    end
+
+    # :call-seq:
+    #   put(data = "", :content_type => mime_type)
+    #
+    # Performs a PUT with the given data to the resource, following redirects as 
+    # neccessary.
+    #
+    # @param [String] data
+    #   The body of the data to be posted
+    # @param [Hash] options
+    #   Options to pass into the request header. At the least, :content_type is required.
+    #
+    # @return [Response] The response to the final request made.
+    #
+    # @raise [ArgumentError] unless :content-type is specified in options
+    # @raise [UnsuccessfulHttpRequestError] unless the request is a
+    #   success, ie the final request returned a 2xx response code
+    def put(data, header = {})
+      request(:put, data, header)
+    end
+
+    # Performs a DELETE on the resource, following redirects as neccessary.
+    #
+    # @return <Response>
+    #
+    # @raise [UnsuccessfulHttpRequestError] unless the request is a
+    #   success, ie the final request returned a 2xx response code
+    def delete(header = {})
+      request(:delete, nil, header)
+    end
+
+    def logger
+      accessor.logger
+    end
+
+    private
+
+    # Ensures that the request has a content type header
+    def ensure_content_type(body, header)
+      return if header.has_key?(:content_type) 
+      
+      if body.respond_to?(:content_type)
+        header[:content_type] = body.content_type
+        return
+      end
+      
+      return if default_header.has_key?(:content_type) 
+
+      # could not figure it out
+      raise MissingContentType
+    end
+
+    # Actually make the request
+    def request(method, data, header)
+      ensure_content_type(data, header) if data
+
+      data = StringIO.new(data) if data.kind_of?(String)
+
+      log_request_with_time "#{method.to_s.upcase} [#{uri}]" do
+        request = Request.new(method, self, data, default_header.merge(header))
+        request.fetch_response
+      end
+    end
+
+    # Log it took the time to make the request
+    def log_request_with_time(msg, indent = 2)
+      logger.info(" " * indent + msg)
+      result = nil
+      time = Benchmark.measure { result = yield }
+      logger.info(" " * indent + "-> Returned #{result.code} in %.4fs" % time.real)
+      result
+    end
+
+  end
+
+end