hurley-http-cache 0.1.0.beta

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fb71f71333adf5e4e068bb81c474c092cc16a5f4
+  data.tar.gz: 55b436e2743064185ac7383b3e9ec71389dc0950
+SHA512:
+  metadata.gz: ee330c420cb6080c33e2ecb673a1de0efc99e1498c413cac9861d4555e6c30c12fb056fa1a7c67dca2b49047d872860599c14c07a32a951467187b952c88940a
+  data.tar.gz: 19de7bdbe98a40d5fbc70f56c3e61c721f1a0cbcdf6c9c49ef9b3d040c6592492f80fe40b297c172211c6aba4453291030882912fe9ab62115590dae0930599b

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2015 Plataformatec.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.

data/README.md

@@ -0,0 +1,93 @@
+# Hurley Http Cache
+
+[![Build Status](https://secure.travis-ci.org/plataformatec/hurley-http-cache.png?branch=master)](https://travis-ci.org/plataformatec/hurley-http-cache)
+
+a [Hurley](https://github.com/lostisland/hurley) connection that respects HTTP cache,
+by checking expiration and validation of the stored responses. This gem is a direct
+reimplementation of the [faraday-http-cache](https://github.com/plataformatec/faraday-http-cache)
+gem.
+
+## Installation
+
+Add it to your Gemfile:
+
+```ruby
+gem 'hurley-http-cache'
+```
+
+## Usage and configuration
+
+You can use an instance of the `Hurley::HttpCache` as the connection for your
+`hurley` client.
+
+```ruby
+require 'hurley'
+require 'hurley/http_cache'
+
+client = Hurley::Client.new
+client.connection = Hurley::HttpCache.new
+```
+
+The middleware accepts a `store` option for the cache backend responsible for
+recording the API responses that should be stored. Stores should respond to
+`write` and `read`, just like an object from the `ActiveSupport::Cache` API.
+
+```ruby
+store = ActiveSupport::Cache.lookup_store(:mem_cache_store, ['localhost:11211'])
+
+client = Hurley::Client.new
+# Use the connection with a Memcache server.
+client.connection = Hurley::HttpCache.new(store: store)
+
+# Or use the Rails.cache instance inside your Rails app.
+client.connection = Hurley::HttpCache.new(store: Rails.cache)
+```
+
+By default, the `Hurley::HttpCache` connection will use the `Hurley.default_connection`
+to perform the real HTTP requests when we can't use a cached response. If you
+want to use a different connection object, just pass it when creating the
+`Hurley::HttpCache` object.
+
+```ruby
+require 'hurley'
+require 'hurley-excon'
+
+client = Hurley.new
+client.connection = Hurley::HttpCache.new(HurleyExcon::Connection.new)
+```
+
+The default store provided is a simple in memory cache that lives on the client
+instance. This type of store **might not be persisted across multiple processes
+or connection instances** so it is probably not suitable for most production
+environments. Make sure that you configure a store that is suitable for you.
+
+the stdlib `JSON` module is used for serialization by default.
+If you expect to be dealing with images, you can use [Marshal][http://ruby-doc.org//core-2.2.0/Marshal.html]
+instead, or if you want to use another json library like `oj` or `yajl-ruby`.
+
+```ruby
+client = Hurley::Client.new
+client.connection = Hurley::HttpCache.new(store: Rails.cache, serializer: Marshal)
+```
+
+## Logging
+
+You can provide a `logger` option that will be receive debug informations based
+connection operations:
+
+```ruby
+client = Hurley::Client.new
+client.connection = Hurley::HttpCache.new(logger: Rails.logger)
+
+client.get('http://site/api/users')
+# logs "HTTP Cache: [GET /users] miss, store"
+```
+
+## See it live
+
+You can clone this repository, install it's dependencies with Bundler (run `bundle install`) and
+execute the files under the `examples` directory to see a sample of the gem usage.
+
+## License
+
+Copyright (c) 2015 Plataformatec. See LICENSE file.

data/lib/hurley-http-cache.rb

@@ -0,0 +1 @@
+require 'hurley/http_cache'

data/lib/hurley/http_cache.rb

@@ -0,0 +1,242 @@
+require 'hurley'
+require 'hurley/http_cache/cache_control'
+require 'hurley/http_cache/request'
+require 'hurley/http_cache/response'
+require 'hurley/http_cache/storage'
+
+module Hurley
+  class HttpCache
+    UNSAFE_VERBS = [:post, :put, :delete, :patch]
+
+    ERROR_STATUSES = 400..499
+
+    # Public: Initialize a Hurley connection that supports HTTP caching.
+    #
+    # connection   - A real connection object that can make HTTP requests
+    #                (default: the Hurley.default_connection value).
+    # shared_cache - A flag to indicate if the connection should act as a shared
+    #                cache or not (default: true)
+    # serializer   - A serializer object for the cache store (default: nil).
+    # store        - A cache store to receive the stored requests and responses
+    #                (default: nil).
+    # logger       - A Logger object (default: nil).
+    #
+    # Examples:
+    #
+    # # Initialize the connection with the Rails logger.
+    # client = Hurley.new
+    # client.connection = Hurley::HttpCache.new(logger: Rails.logger)
+    #
+    # # Initialize the connection with the Hurley Excon connection adapter.
+    # require 'hurley-excon'
+    #
+    # client = Hurley.new
+    # client.connection = Hurley::HttpCache.new(HurleyExcon::Connection.new)
+    def initialize(connection = nil, shared_cache: true, serializer: nil, store: nil, logger: nil)
+      @connection = connection || Hurley.default_connection
+      @logger = logger
+      @shared_cache = shared_cache
+
+      @storage = Storage.new(store: store, serializer: serializer, logger: logger)
+    end
+
+    # Public: Process the client request to try to serve a cache response.
+    # On a cacheable request, we will attempt to locate a valid stored response
+    # to serve. On a cache miss, we will forward the request and try to store
+    # the response for future calls.
+    # If the request can't be cached, the request will be delegated directly
+    # to the underlying connection and does nothing to the response.
+    # The processed steps will be recorded to be logged once the whole
+    # process is finished.
+    #
+    # request - The incoming Hurley::Request object.
+    #
+    # Returns a Hurley::Response object.
+    def call(request)
+      @trace = []
+      request = Hurley::HttpCache::Request.new(request)
+
+      if request.cacheable?
+        if request.no_cache?
+          response = bypass(request)
+        else
+          response = process(request)
+        end
+      else
+        trace :unacceptable
+        response = forward(request)
+      end
+
+      delete(request, response) if should_delete?(response.status_code, request.verb)
+      log_request(request)
+
+      response
+    end
+
+    private
+
+    # Internal: Perform a request bypassing the whole caching mechanism, but
+    # stores the response if possible.
+    #
+    # request - The incoming Hurley::HttpCache::Request object.
+    #
+    # Returns a Hurley::Response object.
+    def bypass(request)
+      trace :bypass
+
+      response = forward(request)
+      store(request, Hurley::HttpCache::Response.new(response))
+      response
+    end
+
+    # Internal: Locate a valid response or forwards the call to the real connection
+    # object. If no entry is present on the storage, a real response will be
+    # retrieved and stored. But if a fresh response already exists in the cache,
+    # we return it back to the client instead of doing a real HTTP request.
+    #
+    # In the case of a existing response that isn't fresh anymore, we will
+    # revalidate the response back with its origin server.
+    #
+    # request - The incoming Hurley::HttpCache::Request object.
+    #
+    # Returns the 'Hurley::HttpCache::Response' object to be served.
+    def process(request)
+      entry = @storage.read(request)
+
+      return fetch(request) if entry.nil?
+
+      entry = Hurley::HttpCache::Response.restore(request.__getobj__, entry)
+
+      if entry.fresh?
+        trace :fresh
+        response = entry
+      else
+        response = validate(entry, request)
+      end
+
+      response
+    end
+
+    # Internal: Fetch a missing response from the real connection object and
+    # stores it in the cache.
+    #
+    # request - The incoming Hurley::HttpCache::Request object.
+    #
+    # Returns the fresh 'Hurley::Response' object.
+    def fetch(request)
+      trace :miss
+
+      response = forward(request)
+      store(request, Hurley::HttpCache::Response.new(response))
+      response
+    end
+
+    # Internal: Validate a stored entry back to it's origin server
+    # using the 'If-Modified-Since' and 'If-None-Match' headers with the
+    # existing 'Last-Modified' and 'ETag' headers. If the new response
+    # is marked as 'Not Modified', the previous stored response will be used
+    # and returned. Otherwise, the freshly new response will be stored
+    # (replacing the old one) and used.
+    #
+    # entry   - A stale Hurley::HttpCache::Response retrieved from the cache.
+    # request - The incoming Hurley::HttpCache::Request object.
+    #
+    # Returns the 'Hurley::HttpCache::Response' to be forwarded to the client.
+    def validate(entry, request)
+      header = request.header
+      header['If-Modified-Since'] = entry.last_modified if entry.last_modified
+      header['If-None-Match'] = entry.etag if entry.etag
+
+      response = Hurley::HttpCache::Response.new(forward(request))
+
+      if response.not_modified?
+        trace :valid
+        entry.header.update(response.header)
+        response = entry
+      end
+      store(request, response)
+      response
+    end
+
+    # Internal: Attempt to store the response into the cache.
+    # If the response isn't cacheable we do nothing.
+    #
+    # request  - A Hurley::HttpCache::Request object.
+    # response - A Hurley::HttpCache::Response object.
+    #
+    # Returns nothing.
+    def store(request, response)
+      if shared_cache? ? response.cacheable_in_shared_cache? : response.cacheable_in_private_cache?
+        trace :store
+        @storage.write(request, response)
+      else
+        trace :invalid
+      end
+    end
+
+    # Internal: Checks if the current request method should remove any existing
+    # cache entries for the same resource.
+    #
+    # Returns true or false.
+    def should_delete?(status_code, verb)
+      UNSAFE_VERBS.include?(verb) && !ERROR_STATUSES.cover?(status_code)
+    end
+
+    # Internal: Delete an existing entry from the cache, based on the request
+    # URL or any of the 'Location' aware headers of the response.
+    #
+    # request - a Hurley::Request object.
+    # response - a Hurley::Response object.
+    #
+    # Returns nothing.
+    def delete(request, response)
+      trace :delete
+
+      urls = [response.header['Location'], response.header['Content-Location'], request.url]
+      urls.each do |url|
+        @storage.delete(url) if url
+      end
+    end
+
+    # Internal: Log the trace info about the incoming request and how the cache
+    # handled it.
+    # This method does nothing if theresn't a logger present.
+    #
+    # request - The Hurley::Request object that represents the request.
+    #
+    # Returns nothing.
+    def log_request(request)
+      return unless @logger
+
+      @logger.debug do
+        verb = request.verb.to_s.upcase
+        path = request.url.request_uri
+        "HTTP Cache: [#{verb} #{path}] #{@trace.join(', ')}"
+      end
+    end
+
+    # Internal: Calls the original connection object with the current
+    # Hurley::Request object.
+    #
+    # Returns a Hurley::Response object.
+    def forward(request)
+      @connection.call(request.__getobj__)
+    end
+
+    # Internal: Should this connection act like a 'shared cache' according
+    # to the the definition in RFC 2616?
+    def shared_cache?
+      @shared_cache
+    end
+
+    # Internal: Record a traced action to be used by the logger once the
+    # request/response phase is finished.
+    #
+    # operation - the name of the performed action, a String or Symbol.
+    #
+    # Returns nothing.
+    def trace(operation)
+      @trace << operation
+    end
+  end
+end

data/lib/hurley/http_cache/cache_control.rb

@@ -0,0 +1,118 @@
+module Hurley
+  class HttpCache
+    # Internal: A class to represent the 'Cache-Control' header options.
+    # This implementation is based on 'rack-cache' internals by Ryan Tomayko.
+    # It breaks the several directives into keys/values and stores them into
+    # a Hash.
+    class CacheControl
+
+      # Internal: Initialize a new CacheControl instance.
+      #
+      # header - The String of the 'Cache-Control' header.
+      def initialize(header)
+        @directives = parse(header.to_s)
+      end
+
+      # Internal: Check if the 'public' directive is present.
+      def public?
+        @directives['public']
+      end
+
+      # Internal: Check if the 'private' directive is present.
+      def private?
+        @directives['private']
+      end
+
+      # Internal: Check if the 'no-cache' directive is present.
+      def no_cache?
+        @directives['no-cache']
+      end
+
+      # Internal: Check if the 'no-store' directive is present.
+      def no_store?
+        @directives['no-store']
+      end
+
+      # Internal: Get the 'max-age' directive as an Integer.
+      #
+      # Returns nil if the 'max-age' directive isn't present.
+      def max_age
+        @directives['max-age'].to_i if @directives.key?('max-age')
+      end
+
+      # Internal: Get the 'max-age' directive as an Integer.
+      #
+      # takes the age header integer value and reduces the max-age and s-maxage
+      # if present to account for having to remove static age header when caching responses
+      def normalize_max_ages(age)
+        if age > 0
+          @directives['max-age'] = @directives['max-age'].to_i - age if @directives.key?('max-age')
+          @directives['s-maxage'] = @directives['s-maxage'].to_i - age if @directives.key?('s-maxage')
+        end
+      end
+
+      # Internal: Get the 's-maxage' directive as an Integer.
+      #
+      # Returns nil if the 's-maxage' directive isn't present.
+      def shared_max_age
+        @directives['s-maxage'].to_i if @directives.key?('s-maxage')
+      end
+      alias_method :s_maxage, :shared_max_age
+
+      # Internal: Check if the 'must-revalidate' directive is present.
+      def must_revalidate?
+        @directives['must-revalidate']
+      end
+
+      # Internal: Check if the 'proxy-revalidate' directive is present.
+      def proxy_revalidate?
+        @directives['proxy-revalidate']
+      end
+
+      # Internal: Get the String representation for the cache directives.
+      # Directives are joined by a '=' and then combined into a single String
+      # separated by commas. Directives with a 'true' value will omit the '='
+      # sign and their value.
+      #
+      # Returns the Cache Control string.
+      def to_s
+        booleans, values = [], []
+
+        @directives.each do |key, value|
+          if value == true
+            booleans << key
+          elsif value
+            values << "#{key}=#{value}"
+          end
+        end
+
+        (booleans.sort + values.sort).join(', ')
+      end
+
+      private
+
+      # Internal: Parse the Cache Control string to a Hash.
+      # Existing whitespace will be removed and the string is split on commas.
+      # For each part everything before a '=' will be treated as the key
+      # and the exceeding will be treated as the value. If only the key is
+      # present then the assigned value will default to true.
+      #
+      # Examples:
+      #   parse('max-age=600')
+      #   # => { 'max-age' => '600'}
+      #
+      #   parse('max-age')
+      #   # => { 'max-age' => true }
+      #
+      # Returns a Hash.
+      def parse(header)
+        header.delete(' ').split(',').each_with_object({}) do |part, directives|
+          next if part.empty?
+
+          name, value = part.split('=', 2)
+          directives[name.downcase] = (value || true) unless name.empty?
+        end
+      end
+    end
+  end
+end