paul-resourceful 0.2.3

data/lib/resourceful/header.rb

@@ -0,0 +1,31 @@
+# A case-normalizing Hash, adjusting on [] and []=.
+# Shamelessly swiped from Rack
+module Resourceful
+  class Header < Hash
+    def initialize(hash={})
+      hash.each { |k, v| self[k] = v }
+    end
+
+    def to_hash
+      {}.replace(self)
+    end
+
+    def [](k)
+      super capitalize(k)
+    end
+
+    def []=(k, v)
+      super capitalize(k), v
+    end
+
+    def has_key?(k)
+      super capitalize(k)
+    end
+
+    def capitalize(k)
+      k.to_s.downcase.gsub(/^.|[-_\s]./) { |x| x.upcase }.gsub('_', '-')
+    end
+  end
+end
+
+

data/lib/resourceful/http_accessor.rb

@@ -0,0 +1,85 @@
+require 'net/http'
+
+require 'resourceful/version'
+require 'resourceful/options_interpreter'
+require 'resourceful/authentication_manager'
+require 'resourceful/cache_manager'
+require 'resourceful/resource'
+require 'resourceful/stubbed_resource_proxy'
+
+module Resourceful
+  # This is an imitation Logger used when no real logger is
+  # registered.  This allows most of the code to assume that there
+  # is always a logger available, which significantly improved the
+  # readability of the logging related code.
+  class BitBucketLogger
+    def warn(*args); end
+    def info(*args); end
+    def debug(*args); end
+  end
+
+  # This is the simplest logger. It just writes everything to STDOUT.
+  class StdOutLogger
+    def warn(*args); puts args; end
+    def info(*args); puts args; end
+    def debug(*args); puts args; end
+  end
+  
+  # This class provides a simple interface to the functionality
+  # provided by the Resourceful library.  Conceptually this object
+  # acts a collection of all the resources available via HTTP.
+  class HttpAccessor
+    RESOURCEFUL_USER_AGENT_TOKEN = "Resourceful/#{RESOURCEFUL_VERSION}(Ruby/#{RUBY_VERSION})"
+    
+    # A logger object to which messages about the activities of this
+    # object will be written.  This should be an object that responds
+    # to +#info(message)+ and +#debug(message)+.  
+    #
+    # Errors will not be logged.  Instead an exception will be raised
+    # and the application code should log it if appropriate.
+    attr_accessor :logger, :cache_manager
+    
+    attr_reader :auth_manager
+    
+    attr_reader :user_agent_tokens  
+    
+    INIT_OPTIONS = OptionsInterpreter.new do 
+      option(:logger, :default => Resourceful::BitBucketLogger.new)
+      option(:user_agent, :default => []) {|ua| [ua].flatten}
+      option(:cache_manager, :default => NullCacheManager.new)
+    end
+    
+    # Initializes a new HttpAccessor.  Valid options:
+    #
+    #  +:logger+:: A Logger object that the new HTTP accessor should
+    #    send log messages
+    #
+    #  +:user_agent+:: One or more additional user agent tokens to
+    #    added to the user agent string.
+    def initialize(options = {})
+      @user_agent_tokens = [RESOURCEFUL_USER_AGENT_TOKEN]
+      
+      INIT_OPTIONS.interpret(options) do |opts|
+        @user_agent_tokens.push(*opts[:user_agent].reverse)
+        self.logger = opts[:logger]
+        @auth_manager = AuthenticationManager.new()
+        @cache_manager = opts[:cache_manager]
+      end     
+    end
+    
+    # Returns the string that identifies this HTTP accessor.  If you
+    # want to add a token to the user agent string simply add the new
+    # token to the end of +#user_agent_tokens+.
+    def user_agent_string
+      user_agent_tokens.reverse.join(' ')
+    end
+    
+    # Returns a resource object representing the resource indicated
+    # by the specified URI.  A resource object will be created if necessary.
+    def resource(uri, opts = {})
+      resource = Resource.new(self, uri, opts)
+    end
+    alias [] resource
+
+  end
+end

data/lib/resourceful/net_http_adapter.rb

@@ -0,0 +1,60 @@
+require 'net/http'
+require 'net/https'
+require 'addressable/uri'
+
+require 'pathname'
+require Pathname(__FILE__).dirname + 'header'
+
+module Addressable
+  class URI
+    def absolute_path
+      absolute_path = ""
+      absolute_path << self.path.to_s
+      absolute_path << "?#{self.query}" if self.query != nil
+      absolute_path << "##{self.fragment}" if self.fragment != nil
+      return absolute_path
+    end
+  end
+end
+
+module Resourceful
+
+  class NetHttpAdapter
+    def self.make_request(method, uri, body = nil, header = nil)
+      uri = uri.is_a?(Addressable::URI) ? uri : Addressable::URI.parse(uri)
+
+      req = net_http_request_class(method).new(uri.absolute_path)
+      header.each { |k,v| req[k] = v } if header
+      conn = Net::HTTP.new(uri.host, uri.port)
+      conn.use_ssl = (/https/i === uri.scheme)
+      begin 
+        conn.start
+        res = conn.request(req, body)
+      ensure
+        conn.finish
+      end
+
+      [ Integer(res.code),
+        Resourceful::Header.new(res.header.to_hash),
+        res.body
+      ]
+    ensure
+      
+    end
+
+    private
+
+    def self.net_http_request_class(method)
+      case method
+      when :get     then Net::HTTP::Get
+      when :head    then Net::HTTP::Head
+      when :post    then Net::HTTP::Post
+      when :put     then Net::HTTP::Put
+      when :delete  then Net::HTTP::Delete
+      end
+
+    end
+
+  end
+
+end

data/lib/resourceful/options_interpreter.rb

@@ -0,0 +1,78 @@
+require 'set'
+
+module Resourceful
+  # Class that supports a declarative way to pick apart an options
+  # hash.
+  #
+  #     OptionsInterpreter.new do 
+  #       option(:accept) { |accept| [accept].flatten.map{|m| m.to_str} }
+  #       option(:http_header_fields, :default => {})
+  #     end.interpret(:accept => 'this/that')
+  #     # => {:accept => ['this/that'], :http_header_fields => { } }
+  #
+  # The returned hash contains :accept with the pass accept option
+  # value transformed into an array and :http_header_fields with its
+  # default value.
+  #     
+  #     OptionsInterpreter.new do 
+  #       option(:max_redirects)
+  #     end.interpret(:foo => 1, :bar => 2)
+  #     # Raises ArgumentError: Unrecognized options: foo, bar
+  #
+  # If options are passed that are not defined an exception is raised.
+  #
+  class OptionsInterpreter
+    def self.interpret(options_hash, &block)
+      interpreter = self.new(options_hash)
+      interpreter.instance_eval(&block)
+      
+      interpreter.interpret
+    end      
+    
+    def initialize(&block)
+      @handlers = Hash.new
+      
+      instance_eval(&block) if block_given?
+    end
+    
+    def interpret(options_hash, &block) 
+      unless (unrecognized_options = (options_hash.keys - supported_options)).empty?
+        raise ArgumentError, "Unrecognized options: #{unrecognized_options.join(", ")}"
+      end
+      
+      options = Hash.new
+      handlers.each do |opt_name, a_handler|
+        opt_val = a_handler.call(options_hash)
+        options[opt_name] = opt_val if opt_val
+      end
+      
+      yield(options) if block_given?
+      
+      options
+    end
+    
+    def option(name, opts = {}, &block)
+
+      passed_value_fetcher = if opts[:default] 
+                               default_value = opts[:default]
+                               lambda{|options_hash| options_hash[name] || default_value}
+                             else
+                               lambda{|options_hash| options_hash[name]}
+                             end
+      
+      handlers[name] = if block_given?
+                         lambda{|options_hash| (val = passed_value_fetcher.call(options_hash)) ? block.call(val) : nil}
+                       else
+                         passed_value_fetcher
+                       end
+    end
+    
+    def supported_options
+      handlers.keys
+    end
+    
+    private
+    
+    attr_reader :handlers
+  end
+end

data/lib/resourceful/request.rb

@@ -0,0 +1,63 @@
+require 'pathname'
+require 'benchmark'
+require Pathname(__FILE__).dirname + 'response'
+require Pathname(__FILE__).dirname + 'net_http_adapter'
+
+module Resourceful
+
+  class Request
+
+    REDIRECTABLE_METHODS = [:get, :head]
+
+    attr_accessor :method, :resource, :body, :header
+    attr_reader   :request_time
+
+    def initialize(http_method, resource, body = nil, header = nil)
+      @method, @resource, @body = http_method, resource, body
+      @header = header.is_a?(Resourceful::Header) ? header : Resourceful::Header.new(header || {})
+
+      @header['Accept-Encoding'] = 'gzip, identity'
+      # 'Host' is a required HTTP/1.1 header, so set it if it isn't already
+      @header['Host'] ||= Addressable::URI.parse(resource.uri).host
+
+      # Setting the date isn't a bad idea, either
+      @header['Date'] ||= Time.now.httpdate
+    end
+
+    def response
+      @request_time = Time.now
+
+      http_resp = NetHttpAdapter.make_request(@method, @resource.uri, @body, @header)
+      response = Resourceful::Response.new(uri, *http_resp)
+      response.request_time = @request_time
+
+      response.authoritative = true
+      response
+    end
+
+    def should_be_redirected?
+      if resource.on_redirect.nil?
+        return true if method.in? REDIRECTABLE_METHODS
+        false
+      else
+        resource.on_redirect.call(self, response)
+      end
+    end
+
+    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.header.has_key?('Cache-Control') and response.header['Cache-Control'].include?('must-revalidate')
+    end
+
+    def uri
+      resource.uri
+    end
+    
+    def logger
+      resource.logger
+    end
+
+  end
+
+end

data/lib/resourceful/resource.rb

@@ -0,0 +1,266 @@
+require 'pathname'
+require Pathname(__FILE__).dirname + 'request'
+
+module Resourceful
+
+  # This exception used to indicate that the request did not succeed.
+  # The HTTP response is included so that the appropriate actions can
+  # be taken based on the details of that response
+  class UnsuccessfulHttpRequestError < Exception
+    attr_reader :http_response, :http_request
+ 
+    # Initialize new error from the HTTP request and response attributes.
+    def initialize(http_request, http_response)
+      super("#{http_request.method} request to <#{http_request.uri}> failed with code #{http_response.code}")
+      @http_request = http_request
+      @http_response = http_response
+    end
+  end
+
+  class Resource
+    attr_reader :accessor
+    attr_accessor :default_options
+
+    # 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, options = {})
+      @accessor, @uris = accessor, [uri]
+      @default_options = options
+      @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
+
+    # 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 = {})
+      log_request_with_time "GET [#{uri}]" do
+        do_read_request(:get, header)
+      end
+    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 = "", options = {})
+      raise ArgumentError, ":content_type must be specified" unless options.has_key?(:content_type)
+
+      log_request_with_time "POST [#{uri}]" do
+        do_write_request(:post, data, options)
+      end
+    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 = "", options = {})
+      raise ArgumentError, ":content_type must be specified" unless options.has_key?(:content_type)
+
+      log_request_with_time "PUT [#{uri}]" do
+        do_write_request(:put, data, options)
+      end
+    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(options = {})
+      log_request_with_time "DELETE [#{uri}]" do
+        do_write_request(:delete, {}, options)
+      end
+    end
+
+    # Performs a read request (HEAD, GET). Users should use the #get, etc methods instead.
+    #
+    # This method handles all the work of following redirects.
+    #
+    # @param method<Symbol> The method to perform
+    #
+    # @return <Response>
+    #
+    # @raise [UnsuccessfulHttpRequestError] unless the request is a
+    #   success, ie the final request returned a 2xx response code
+    #
+    def do_read_request(method, header = {})
+      request = Resourceful::Request.new(method, self, nil, default_options.merge(header))
+      accessor.auth_manager.add_credentials(request)
+
+      cached_response = accessor.cache_manager.lookup(request)
+      if cached_response
+        logger.info("    Retrieved from cache")
+        if not cached_response.stale?
+          # We're done!
+          return cached_response
+        else
+          logger.info("    Cache entry is stale")
+          request.set_validation_headers(cached_response)
+        end
+      end
+
+      response = request.response
+
+      if response.is_not_modified?
+        logger.info("    Resource not modified")
+        cached_response.header.merge!(response.header)
+        cached_response.request_time = response.request_time
+        response = cached_response
+        response.authoritative = true
+      end
+
+      if response.is_redirect? and request.should_be_redirected?
+        if response.is_permanent_redirect?
+          @uris.unshift response.header['Location'].first
+          logger.info("    Permanently redirected to #{uri} - Storing new location.")
+          response = do_read_request(method, header)
+        else
+          redirected_resource = Resourceful::Resource.new(self.accessor, response.header['Location'].first)
+          logger.info("    Redirected to #{redirected_resource.uri} - Storing new location.")
+          response = redirected_resource.do_read_request(method, header)
+        end
+      end
+
+      if response.is_not_authorized? && !@already_tried_with_auth
+        @already_tried_with_auth = true
+        accessor.auth_manager.associate_auth_info(response)
+        logger.info("Authentication Required. Retrying with auth info")
+        response = do_read_request(method, header)
+      end
+
+      raise UnsuccessfulHttpRequestError.new(request,response) unless response.is_success?
+
+      accessor.cache_manager.store(request, response) if response.is_success?
+
+      return response
+    end
+
+    # Performs a write request (POST, PUT, DELETE). Users should use the #post, etc 
+    # methods instead.
+    #
+    # This method handles all the work of following redirects.
+    #
+    # @param [Symbol] method  The method to perform
+    # @param [String] data    Body of the http request.
+    # @param [Hash]   header  Header for the HTTP resquest.
+    #
+    # @return [Response]
+    #
+    # @raise [UnsuccessfulHttpRequestError] unless the request is a
+    #   success, ie the final request returned a 2xx response code
+    def do_write_request(method, data = nil, header = {})
+      request = Resourceful::Request.new(method, self, data, default_options.merge(header))
+      accessor.auth_manager.add_credentials(request)
+
+      response = request.response
+
+      if response.is_redirect? and request.should_be_redirected?
+        if response.is_permanent_redirect?
+          @uris.unshift response.header['Location'].first
+          response = do_write_request(method, data, header)
+        elsif response.code == 303 # see other, must use GET for new location
+          redirected_resource = Resourceful::Resource.new(self.accessor, response.header['Location'].first)
+          response = redirected_resource.do_read_request(:get, header)
+        else
+          redirected_resource = Resourceful::Resource.new(self.accessor, response.header['Location'].first)
+          response = redirected_resource.do_write_request(method, data, header)
+        end
+      end
+
+      if response.is_not_authorized? && !@already_tried_with_auth
+        @already_tried_with_auth = true
+        accessor.auth_manager.associate_auth_info(response)
+        logger.debug("Authentication Required. Retrying with auth info")
+        response = do_write_request(method, data, header)
+      end
+
+      raise UnsuccessfulHttpRequestError.new(request,response) unless response.is_success?
+
+      accessor.cache_manager.invalidate(uri)
+      return response
+    end
+
+    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
+
+    def logger
+      accessor.logger
+    end
+
+  end
+
+end