http 0.7.4 → 0.8.0.pre

data/lib/http/content_type.rb

@@ -9,7 +9,7 @@ module HTTP
         new mime_type(str), charset(str)
       end
 
-    private
+      private
 
       # :nodoc:
       def mime_type(str)
@@ -20,7 +20,7 @@ module HTTP
       # :nodoc:
       def charset(str)
         md = str.to_s.match CHARSET_RE
-        md && md[1].to_s.strip.gsub(/^"|"$/, '')
+        md && md[1].to_s.strip.gsub(/^"|"$/, "")
       end
     end
   end

data/lib/http/errors.rb

@@ -8,6 +8,12 @@ module HTTP
   # Generic Response error
   class ResponseError < Error; end
 
-  # Request to do something when we're in the wrong state
+  # Requested to do something when we're in the wrong state
   class StateError < ResponseError; end
+
+  # Generic Cache error
+  class CacheError < Error; end
+
+  # Header name is invalid
+  class InvalidHeaderNameError < Error; end
 end

data/lib/http/headers.rb

@@ -1,6 +1,7 @@
-require 'forwardable'
+require "forwardable"
 
-require 'http/headers/mixin'
+require "http/errors"
+require "http/headers/mixin"
 
 module HTTP
   # HTTP Headers container.
@@ -11,6 +12,10 @@ module HTTP
     # Matches HTTP header names when in "Canonical-Http-Format"
     CANONICAL_HEADER = /^[A-Z][a-z]*(-[A-Z][a-z]*)*$/
 
+    # Matches valid header field name according to RFC.
+    # @see http://tools.ietf.org/html/rfc7230#section-3.2
+    HEADER_NAME_RE = /^[A-Za-z0-9!#\$%&'*+\-.^_`|~]+$/
+
     # Class constructor.
     def initialize
       @pile = []
@@ -31,7 +36,7 @@ module HTTP
     # @param [#to_s] name header name
     # @return [void]
     def delete(name)
-      name = canonicalize_header name.to_s
+      name = normalize_header name.to_s
       @pile.delete_if { |k, _| k == name }
     end
 
@@ -41,7 +46,7 @@ module HTTP
     # @param [Array<#to_s>, #to_s] value header value(s) to be appended
     # @return [void]
     def add(name, value)
-      name  = canonicalize_header name.to_s
+      name  = normalize_header name.to_s
       Array(value).each { |v| @pile << [name, v.to_s] }
     end
 
@@ -52,7 +57,7 @@ module HTTP
     #
     # @return [Array<String>]
     def get(name)
-      name = canonicalize_header name.to_s
+      name = normalize_header name.to_s
       @pile.select { |k, _| k == name }.map { |_, v| v }
     end
 
@@ -77,6 +82,7 @@ module HTTP
     def to_h
       Hash[keys.map { |k| [k, self[k]] }]
     end
+    alias_method :to_hash, :to_h
 
     # Returns headers key/value pairs.
     #
@@ -179,14 +185,21 @@ module HTTP
       alias_method :[], :coerce
     end
 
-  private
+    private
 
     # Transforms `name` to canonical HTTP header capitalization
     #
     # @param [String] name
+    # @raise [InvalidHeaderNameError] if normalized name does not
+    #   match {HEADER_NAME_RE}
     # @return [String] canonical HTTP header name
-    def canonicalize_header(name)
-      name[CANONICAL_HEADER] || name.split(/[\-_]/).map(&:capitalize).join('-')
+    def normalize_header(name)
+      normalized   = name[CANONICAL_HEADER]
+      normalized ||= name.split(/[\-_]/).map(&:capitalize).join("-")
+
+      return normalized if normalized =~ HEADER_NAME_RE
+
+      fail InvalidHeaderNameError, "Invalid HTTP header field name: #{name.inspect}"
     end
   end
 end

data/lib/http/headers/mixin.rb

@@ -1,4 +1,4 @@
-require 'forwardable'
+require "forwardable"
 
 module HTTP
   class Headers

data/lib/http/mime_type.rb

@@ -57,7 +57,7 @@ module HTTP
         aliases.fetch type, type.to_s
       end
 
-    private
+      private
 
       # :nodoc:
       def adapters
@@ -73,4 +73,4 @@ module HTTP
 end
 
 # built-in mime types
-require 'http/mime_type/json'
+require "http/mime_type/json"

data/lib/http/mime_type/adapter.rb

@@ -1,5 +1,5 @@
-require 'forwardable'
-require 'singleton'
+require "forwardable"
+require "singleton"
 
 module HTTP
   module MimeType

data/lib/http/mime_type/json.rb

@@ -1,5 +1,5 @@
-require 'json'
-require 'http/mime_type/adapter'
+require "json"
+require "http/mime_type/adapter"
 
 module HTTP
   module MimeType
@@ -17,7 +17,7 @@ module HTTP
       end
     end
 
-    register_adapter 'application/json', JSON
-    register_alias   'application/json', :json
+    register_adapter "application/json", JSON
+    register_alias   "application/json", :json
   end
 end

data/lib/http/options.rb

@@ -1,81 +1,78 @@
-require 'http/headers'
-require 'openssl'
-require 'socket'
+require "http/headers"
+require "openssl"
+require "socket"
+require "http/cache/null_cache"
 
 module HTTP
   class Options
-    # How to format the response [:object, :body, :parse_body]
-    attr_accessor :response
-
-    # HTTP headers to include in the request
-    attr_accessor :headers
-
-    # Query string params to add to the url
-    attr_accessor :params
-
-    # Form data to embed in the request
-    attr_accessor :form
-
-    # JSON data to embed in the request
-    attr_accessor :json
-
-    # Explicit request body of the request
-    attr_accessor :body
-
-    # HTTP proxy to route request
-    attr_accessor :proxy
-
-    # Socket classes
-    attr_accessor :socket_class, :ssl_socket_class
-
-    # SSL context
-    attr_accessor :ssl_context
-
-    # Follow redirects
-    attr_accessor :follow
-
-    protected :response=, :headers=, :proxy=, :params=, :form=, :json=, :follow=
-
     @default_socket_class     = TCPSocket
     @default_ssl_socket_class = OpenSSL::SSL::SSLSocket
 
+    @default_cache = Http::Cache::NullCache.new
+
     class << self
       attr_accessor :default_socket_class, :default_ssl_socket_class
+      attr_accessor :default_cache
 
       def new(options = {})
         return options if options.is_a?(self)
         super
       end
+
+      def defined_options
+        @defined_options ||= []
+      end
+
+      protected
+
+      def def_option(name, &interpreter)
+        defined_options << name.to_sym
+        interpreter ||= ->(v) { v }
+
+        attr_accessor name
+        protected :"#{name}="
+
+        define_method(:"with_#{name}") do |value|
+          dup { |opts| opts.send(:"#{name}=", instance_exec(value, &interpreter)) }
+        end
+      end
     end
 
     def initialize(options = {})
-      @response  = options[:response]  || :auto
-      @proxy     = options[:proxy]     || {}
-      @body      = options[:body]
-      @params    = options[:params]
-      @form      = options[:form]
-      @json      = options[:json]
-      @follow    = options[:follow]
-
-      @headers   = HTTP::Headers.coerce(options[:headers] || {})
-
-      @socket_class     = options[:socket_class]     || self.class.default_socket_class
-      @ssl_socket_class = options[:ssl_socket_class] || self.class.default_ssl_socket_class
-      @ssl_context      = options[:ssl_context]
+      defaults = {:response =>         :auto,
+                  :proxy =>            {},
+                  :socket_class =>     self.class.default_socket_class,
+                  :ssl_socket_class => self.class.default_ssl_socket_class,
+                  :cache =>            self.class.default_cache,
+                  :headers =>          {}}
+
+      opts_w_defaults = defaults.merge(options)
+      opts_w_defaults[:headers] = HTTP::Headers.coerce(opts_w_defaults[:headers])
+
+      opts_w_defaults.each do |(opt_name, opt_val)|
+        self[opt_name] = opt_val
+      end
+    end
+
+    def_option :headers do |headers|
+      self.headers.merge(headers)
+    end
+
+    %w(proxy params form json body follow response socket_class ssl_socket_class ssl_context persistent).each do |method_name|
+      def_option method_name
     end
 
-    def with_headers(headers)
-      dup do |opts|
-        opts.headers = self.headers.merge(headers)
+    def_option :cache do |cache_or_cache_options|
+      if cache_or_cache_options.respond_to? :perform
+        cache_or_cache_options
+      else
+        require "http/cache"
+        HTTP::Cache.new(cache_or_cache_options)
       end
     end
 
-    %w(proxy params form json body follow).each do |method_name|
-      class_eval <<-RUBY, __FILE__, __LINE__
-        def with_#{method_name}(value)
-          dup { |opts| opts.#{method_name} = value }
-        end
-      RUBY
+    def persistent?
+      !persistent.nil? && persistent != ""
     end
 
     def [](option)
@@ -97,22 +94,10 @@ module HTTP
     end
 
     def to_hash
-      # FIXME: hardcoding these fields blows! We should have a declarative
-      # way of specifying all the options fields, and ensure they *all*
-      # get serialized here, rather than manually having to add them each time
-      {
-        :response         => response,
-        :headers          => headers.to_h,
-        :proxy            => proxy,
-        :params           => params,
-        :form             => form,
-        :json             => json,
-        :body             => body,
-        :follow           => follow,
-        :socket_class     => socket_class,
-        :ssl_socket_class => ssl_socket_class,
-        :ssl_context      => ssl_context
-      }
+      hash_pairs = self.class
+                   .defined_options
+                   .flat_map { |opt_name| [opt_name, self[opt_name]] }
+      Hash[*hash_pairs]
     end
 
     def dup
@@ -121,7 +106,13 @@ module HTTP
       dupped
     end
 
-  private
+    protected
+
+    def []=(option, val)
+      send(:"#{option}=", val)
+    end
+
+    private
 
     def argument_error!(message)
       fail(Error, message, caller[1..-1])

data/lib/http/redirector.rb

@@ -22,7 +22,7 @@ module HTTP
       follow(&block)
     end
 
-  private
+    private
 
     # Reset redirector state
     def reset(request, response)
@@ -38,8 +38,8 @@ module HTTP
         fail TooManyRedirectsError if too_many_hops?
         fail EndlessRedirectError  if endless_loop?
 
-        uri = @response.headers['Location']
-        fail StateError, 'no Location header in redirect' unless uri
+        uri = @response.headers["Location"]
+        fail StateError, "no Location header in redirect" unless uri
 
         if 303 == @response.code
           @request = @request.redirect uri, :get

data/lib/http/request.rb

@@ -1,9 +1,11 @@
-require 'http/errors'
-require 'http/headers'
-require 'http/request/writer'
-require 'http/version'
-require 'base64'
-require 'uri'
+require "http/errors"
+require "http/headers"
+require "http/request/caching"
+require "http/request/writer"
+require "http/version"
+require "base64"
+require "uri"
+require "time"
 
 module HTTP
   class Request
@@ -66,7 +68,7 @@ module HTTP
     attr_reader :proxy, :body, :version
 
     # :nodoc:
-    def initialize(verb, uri, headers = {}, proxy = {}, body = nil, version = '1.1') # rubocop:disable ParameterLists
+    def initialize(verb, uri, headers = {}, proxy = {}, body = nil, version = "1.1") # rubocop:disable ParameterLists
       @verb   = verb.to_s.downcase.to_sym
       @uri    = uri.is_a?(URI) ? uri : URI(uri.to_s)
       @scheme = @uri.scheme && @uri.scheme.to_s.downcase.to_sym
@@ -78,15 +80,15 @@ module HTTP
 
       @headers = HTTP::Headers.coerce(headers || {})
 
-      @headers['Host']        ||= default_host
-      @headers['User-Agent']  ||= USER_AGENT
+      @headers["Host"]        ||= default_host
+      @headers["User-Agent"]  ||= USER_AGENT
     end
 
     # Returns new Request with updated uri
     def redirect(uri, verb = @verb)
       uri = @uri.merge uri.to_s
       req = self.class.new(verb, uri, headers, proxy, body, version)
-      req['Host'] = req.uri.host
+      req["Host"] = req.uri.host
       req
     end
 
@@ -109,7 +111,7 @@ module HTTP
     # Compute and add the Proxy-Authorization header
     def include_proxy_authorization_header
       digest = Base64.encode64("#{proxy[:proxy_username]}:#{proxy[:proxy_password]}").chomp
-      headers['Proxy-Authorization'] = "Basic #{digest}"
+      headers["Proxy-Authorization"] = "Basic #{digest}"
     end
 
     # Compute HTTP request header for direct or proxy request
@@ -127,7 +129,12 @@ module HTTP
       using_proxy? ? proxy[:proxy_port] : uri.port
     end
 
-  private
+    # @return [HTTP::Request::Caching]
+    def caching
+      Caching.new self
+    end
+
+    private
 
     def path_for_request_header
       if using_proxy?
@@ -139,7 +146,7 @@ module HTTP
 
     def uri_path_with_query
       path = uri_has_query? ? "#{uri.path}?#{uri.query}" : uri.path
-      path.empty? ? '/' : path
+      path.empty? ? "/" : path
     end
 
     def uri_has_query?

data/lib/http/request/caching.rb

@@ -0,0 +1,95 @@
+require "http/cache/headers"
+
+module HTTP
+  class Request
+    # Decorator for requests to provide convenience methods related to caching.
+    class Caching < DelegateClass(HTTP::Request)
+      INVALIDATING_METHODS = [:post, :put, :delete, :patch].freeze
+      CACHEABLE_METHODS    = [:get, :head].freeze
+
+      # When was this request sent to the server
+      #
+      # @api public
+      attr_accessor :sent_at
+
+      # Inits a new instance
+      # @api private
+      def initialize(obj)
+        super
+        @requested_at = nil
+        @received_at  = nil
+      end
+
+      # @return [HTTP::Request::Caching]
+      def caching
+        self
+      end
+
+      # @return [Boolean] true iff request demands the resources cache entry be invalidated
+      #
+      # @api public
+      def invalidates_cache?
+        INVALIDATING_METHODS.include?(verb) ||
+          cache_headers.no_store?
+      end
+
+      # @return [Boolean] true if request is cacheable
+      #
+      # @api public
+      def cacheable?
+        CACHEABLE_METHODS.include?(verb) &&
+          !cache_headers.no_store?
+      end
+
+      # @return [Boolean] true iff the cache control info of this
+      # request demands that the response be revalidated by the origin
+      # server.
+      #
+      # @api public
+      def skips_cache?
+        0 == cache_headers.max_age       ||
+          cache_headers.must_revalidate? ||
+          cache_headers.no_cache?
+      end
+
+      # @return [HTTP::Request::Caching] new request based on this
+      # one but conditional on the resource having changed since
+      # `cached_response`
+      #
+      # @api public
+      def conditional_on_changes_to(cached_response)
+        self.class.new HTTP::Request.new(
+          verb, uri, headers.merge(conditional_headers_for(cached_response)),
+          proxy, body, version).caching
+      end
+
+      # @return [HTTP::Cache::Headers] cache control helper for this request
+      # @api public
+      def cache_headers
+        @cache_headers ||= HTTP::Cache::Headers.new headers
+      end
+
+      def env
+        {"rack-cache.cache_key" => ->(r) { r.uri.to_s }}
+      end
+
+      private
+
+      # @return [Headers] conditional request headers
+      # @api private
+      def conditional_headers_for(cached_response)
+        headers = HTTP::Headers.new
+
+        cached_response.headers.get("Etag")
+          .each { |etag| headers.add("If-None-Match", etag) }
+
+        cached_response.headers.get("Last-Modified")
+          .each { |last_mod| headers.add("If-Modified-Since", last_mod) }
+
+        headers.add("Cache-Control", "max-age=0") if cache_headers.forces_revalidation?
+
+        headers
+      end
+    end
+  end
+end