rocket_pants 1.0.0.rc.1

data/lib/rocket_pants.rb

@@ -0,0 +1,41 @@
+require 'active_support/all'
+require 'action_dispatch'
+require 'action_dispatch/routing'
+require 'action_controller'
+
+require 'moneta'
+require 'moneta/memory'
+
+module RocketPants
+  require 'rocket_pants/exceptions'
+
+  # Set up the routing in advance.
+  require 'rocket_pants/routing'
+  ActionDispatch::Routing::Mapper.send :include, RocketPants::Routing
+
+  require 'rocket_pants/railtie' if defined?(Rails::Railtie)
+
+  # Extra parts of RocketPants.
+  autoload :Base,            'rocket_pants/base'
+  autoload :Client,          'rocket_pants/client'
+  autoload :Cacheable,       'rocket_pants/cacheable'
+  autoload :CacheMiddleware, 'rocket_pants/cache_middleware'
+
+  # Helpers for various testing frameworks.
+  autoload :TestHelper,      'rocket_pants/test_helper'
+  autoload :RSpecMatchers,   'rocket_pants/rspec_matchers'
+
+  mattr_accessor :caching_enabled
+  self.caching_enabled = false
+
+  mattr_writer :cache
+
+  class << self
+    alias caching_enabled? caching_enabled
+
+    def cache
+      @@cache ||= Moneta::Memory.new
+    end
+  end
+
+end

data/lib/rocket_pants/base.rb

@@ -0,0 +1,60 @@
+require 'rocket_pants/exceptions'
+
+module RocketPants
+
+  autoload :Caching,         'rocket_pants/controller/caching'
+  autoload :ErrorHandling,   'rocket_pants/controller/error_handling'
+  autoload :Instrumentation, 'rocket_pants/controller/instrumentation'
+  autoload :Rescuable,       'rocket_pants/controller/rescuable'
+  autoload :Respondable,     'rocket_pants/controller/respondable'
+  autoload :Versioning,      'rocket_pants/controller/versioning'
+  autoload :UrlFor,          'rocket_pants/controller/url_for'
+
+  class Base < ActionController::Metal
+
+    abstract!
+
+    MODULES = [
+      ActionController::HideActions,
+      ActionController::UrlFor,
+      ActionController::Redirecting,
+      ActionController::ConditionalGet,
+      ActionController::RackDelegation,
+      ActionController::RecordIdentifier,
+      UrlFor,
+      Respondable,
+      Versioning,
+      Instrumentation,
+      Caching,
+      ActionController::MimeResponds,
+      # Include earliest as possible in the request.
+      AbstractController::Callbacks,
+      ActionController::Rescue,
+      ErrorHandling,
+      Rescuable
+    ]
+
+    # If possible, include the Rails controller methods in Airbrake to make it useful.
+    begin
+      require 'airbrake'
+      require 'airbrake/rails/controller_methods'
+      MODULES << Airbrake::Rails::ControllerMethods
+    rescue LoadError => e
+    end
+
+    MODULES.each do |mixin|
+      include mixin
+    end
+
+    respond_to :json
+
+    # Bug fix for rails - include compatibility.
+    config_accessor :protected_instance_variables
+    self.protected_instance_variables = %w(@assigns @performed_redirect @performed_render
+      @variables_added @request_origin @url @parent_controller @action_name
+      @before_filter_chain_aborted @_headers @_params @_response)
+
+    ActiveSupport.run_load_hooks(:rocket_pants, self)
+
+  end
+end

data/lib/rocket_pants/cache_middleware.rb

@@ -0,0 +1,59 @@
+module RocketPants
+  class CacheMiddleware
+    
+    NOT_MODIFIED = [304, {}, []]
+    
+    def initialize(app)
+      @app = app
+    end
+    
+    def call(env)
+      dup._call env
+    end
+    
+    def _call(env)
+      @env = env
+      if has_valid_etag?
+        debug "Cache key is valid, returning not modified response."
+        NOT_MODIFIED.dup
+      else
+        @app.call env
+      end
+    end
+    
+    private
+    
+    def request_path
+      @env['SCRIPT_NAME'].to_s + @env['PATH_INFO'].to_s
+    end
+
+    def has_valid_etag?
+      return false if (etags = request_etags).blank?
+      debug ""
+      etags.any? do |etag|
+        cache_key, value = extract_cache_key_and_value etag
+        debug "Processing cache key for path #{request_path}"
+        debug "Checking cache key #{cache_key} matches the value #{value}"
+        fresh? cache_key, value
+      end
+    end
+    
+    def extract_cache_key_and_value(etag)
+      etag.to_s.split(":", 2)
+    end
+    
+    def fresh?(key, value)
+      RocketPants.cache[key.to_s] == value
+    end
+    
+    def request_etags
+      stored = @env['HTTP_IF_NONE_MATCH']
+      stored.present? && stored.to_s.scan(/"([^"]+)"/)
+    end
+    
+    def debug(message)
+      Rails.logger.debug message if defined?(Rails.logger)
+    end
+
+  end
+end

data/lib/rocket_pants/cacheable.rb

@@ -0,0 +1,19 @@
+module RocketPants
+  module Cacheable
+    extend ActiveSupport::Concern
+    
+    included do
+      after_save    :record_cache! if respond_to?(:after_save)
+      after_destroy :remove_cache! if respond_to?(:after_destroy)
+    end
+    
+    def record_cache!
+      RocketPants::Caching.record self
+    end
+    
+    def remove_cache!
+      RocketPants::Caching.remove self
+    end
+    
+  end
+end

data/lib/rocket_pants/client.rb

@@ -0,0 +1,135 @@
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/string/inflections'
+
+require 'rocket_pants/exceptions'
+
+require 'api_smith'
+require 'will_paginate/collection'
+
+module RocketPants
+  # Implements a generalised base for building clients on top of
+  # the rocket pants controller. This automatically unpacks the API
+  # into the correct response types, handles errors (using the same error registry
+  # as the server) and in general makes it simpler to implement api clients.
+  #
+  # @example A versioned api client
+  #   class MyApiClient < RocketPants::Client
+  #
+  #     class Profile < APISmith::Smash
+  #       property :name
+  #       property :email
+  #     end
+  #
+  #     version 1
+  #     base_uri "http://api.example.com/"
+  #
+  #     def profile
+  #       get 'profile', :transformer => Profile
+  #     end
+  #   end
+  #
+  class Client < APISmith::Base
+    
+    class_attribute :_version, :_actual_endpoint
+    
+    class << self
+      
+      # @overload version
+      #   @return [Integer] the current API version number for this client
+      # @overload version(number)
+      #   Sets a variable noting what version of the api the client uses and updates
+      #   the endpoint to prefix it with the given version number.
+      #   @param [Integer] number the version of the api to process.
+      def version(number = nil)
+        if number.nil?
+          _version
+        else
+          self._version = number
+          endpoint _actual_endpoint
+          number
+        end
+      end
+      
+      alias _original_endpoint endpoint
+
+      # Sets the endpoint url, taking into account the version number as a
+      # prefix if present.
+      def endpoint(path)
+        self._actual_endpoint = path
+        _original_endpoint File.join(*[_version, path].compact.map(&:to_s))
+      end
+      
+    end
+    
+    # Initializes a new client, optionally setting up the host for this client.
+    # @param [Hash] options general client options
+    # @option options [String] :api_host the overriden base_uri host for this client instance.
+    def initialize(options = {})
+      super
+      # Setup the base uri if passed in to the client.
+      if options[:api_host].present?
+        add_request_options! :base_uri => HTTParty.normalize_base_uri(options[:api_host])
+      end
+    end
+    
+    private
+    
+    # Give a response hash from the api, will transform it into
+    # the correct data type.
+    # @param [Hash] response the incoming response
+    # @param [hash] options any options to pass through for transformation
+    # @return [Object] the transformed response.
+    def transform_response(response, options = {})
+      # Now unpack the response into the data types.
+      inner = response.delete("response")
+      objects = unpack inner, options
+      # Unpack pagination as a special case.
+      if response.has_key?("pagination")
+        paginated_response objects, response
+      else
+        objects
+      end
+    end
+    
+    # Returns an API response wrapped in a will_paginate collection
+    # using the pagination key in the response container to set up
+    # the current number of total entries and page details.
+    # @param [Array<Object>] objects the actual response contents
+    # @param [Hash{String => Object}] The response container
+    # @option container [Hash] "pagination" the pagination data to use.
+    def paginated_response(objects, container)
+      pagination = container.delete("pagination")
+      WillPaginate::Collection.create(pagination["current"], pagination["per_page"]) do |collection|
+        collection.replace objects
+        collection.total_entries = pagination["count"]
+      end
+    end
+    
+    # Finds and uses the transformer for a given incoming object to
+    # unpack it into a useful data type.
+    # @param [Hash, Array<Hash>] object the response object to unpack
+    # @param [Hash] options the unpacking options
+    # @option options [Hash] :transformer,:as the transformer to use
+    # @return The transformed data or the data itself when no transformer is specified.
+    def unpack(object, options = {})
+      transformer = options[:transformer] || options[:as]
+      transformer ? transformer.call(object) : object
+    end
+    
+    # Processes a given response to check for the presence of an error,
+    # either by the response not being a hash (e.g. it is returning HTML instead
+    # JSON or HTTParty couldn't parse the response).
+    # @param [Hash, Object] response the response to check errors on
+    # @raise [RocketPants::Error] a generic error when the type is wrong, or a registered error subclass otherwise.
+    def check_response_errors(response)
+      if !response.is_a?(Hash)
+        raise RocketPants::Error, "The response from the server was not in a supported format."
+      elsif response.has_key?("error")
+        klass = RocketPants::Errors[response["error"]] || RocketPants::Error
+        raise klass.new(response["error_description"])
+      end
+    end
+    
+  end
+end

data/lib/rocket_pants/controller/caching.rb

@@ -0,0 +1,135 @@
+require 'set'
+require 'digest/md5'
+
+module RocketPants
+  # RocketPants::Caching adds unobtrusive support for automatic HTTP-level caching
+  # to controllers built on Rocket Pants. It will automatically.
+  module Caching
+    extend ActiveSupport::Concern
+    
+    included do
+      class_attribute :cached_actions, :caching_timeout, :caching_options
+      self.caching_timeout     = 5.minutes
+      self.cached_actions      = Set.new
+      self.caching_options     = {:public => true}
+    end
+    
+    class << self
+          
+      # Removes the cache record for a given object, making sure
+      # It isn't contained in the Rocket Pants etag cache thus
+      # ignoring it in incoming responses.
+      # @param [Object] object what to remove from the cache
+      def remove(object)
+        RocketPants.cache.delete cache_key_for(object)
+      end
+    
+      # Takes a given object and sets the stored etag in the Rocket Pants
+      # etag key to have the correct value.
+      #
+      # Doing this means that on subsequent requests with caching enabled,
+      # the request will be automatically recorded by the middleware and not
+      # actually served.
+      #
+      # Please note that this expects the object has a cache_key method
+      # defined that will return a string, useable for caching. If not,
+      # it will use inspect which is a VERY VERY bad idea (and will likely
+      # be removed in the near future).
+      #
+      # @param [#cache_key] object what to record in the cache
+      def record(object, cache_key = cache_key_for(object))
+        default_etag = object.inspect
+        if object.respond_to?(:cache_key).presence && (ck = object.cache_key).present?
+          default_etag = ck
+        end
+        generated_etag = Digest::MD5.hexdigest(default_etag)
+        RocketPants.cache[cache_key] = generated_etag
+      end
+      
+      # Given an object, returns the etag value to be used in
+      # the response / etag header (prior to any more processing).
+      # If the object isn't in the cache, we'll instead record
+      # it and return the etag for it.
+      # @param [#cache_key] object what to look up the etag for
+      def etag_for(object)
+        cache_key = cache_key_for(object)
+        etag_value = RocketPants.cache[cache_key].presence || record(object, cache_key)
+        "#{cache_key}:#{etag_value}"
+      end
+    
+      # Returns the default cache key for a given object.
+      # Note that when the object defines a rp_object_key method, it will
+      # be used as the
+      #
+      # @param [Object, #rp_object_key] the object to find the cache key for.
+      def cache_key_for(object)
+        if object.respond_to?(:rp_object_key) && (ok = object.rp_object_key).present?
+          Digest::MD5.hexdigest ok
+        else
+          suffix = (object.respond_to?(:new?) && object.new?) ? "new" : object.id
+          Digest::MD5.hexdigest "#{object.class.name}/#{suffix}"
+        end
+      end
+    
+      def normalise_etag(identifier_or_object)
+        %("#{identifier_or_object.to_s}")
+      end
+    
+    end
+    
+    module ClassMethods
+      
+      # Sets up automatic etag and cache control headers for api resource
+      # controllers using an after filter. Note that for the middleware
+      # to actually be inserted, `RocketPants.enable_caching` needs to be
+      # set to true.
+      # @param [Symbol*] args a collection of action names to perform caching on.
+      # @param [Hash] options options to configure caching
+      # @option options [Integer, ActiveSupport::Duration] :cache_for the amount of
+      #    time to cache timeout based actions for.
+      # @example Setting up caching on a series of actions
+      #   caches :index, :show
+      # @example Setting up caching with options
+      #   caches :index, :show, :cache_for => 3.minutes
+      def caches(*args)
+        options     = args.extract_options!
+        self.cached_actions += Array.wrap(args).map(&:to_s).compact
+        # Setup the time based caching.
+        if options.has_key?(:cache_for)
+          self.caching_timeout = options.delete(:cache_for)
+        end
+        # Merge in any caching options for other controllers.
+        caching_options.merge!(options.delete(:caching_options) || {})
+      end
+      
+    end
+    
+    def cache_action?(action = params[:action])
+      RocketPants.caching_enabled? && cached_actions.include?(action)
+    end
+    
+    def cache_response(resource, single_resource)
+      # Add in the default options.
+      response.cache_control.merge! caching_options
+      # We need to set the etag based on the object when it is singular
+      # Note that the object is responsible for clearing the etag cache.
+      if single_resource
+        response["ETag"] = Caching.normalise_etag Caching.etag_for(resource)
+      # Otherwise, it's a collection and we need to use time based caching.
+      else
+        response.cache_control[:max_age] = caching_timeout
+      end
+    end
+    
+    # The callback use to automatically cache the current response object, using it's
+    # cache key as a guide. For collections, instead of using an etag we'll use the request
+    # path as a cache key and instead use a timeout.
+    def post_process_exposed_object(resource, type, singular)
+      super # Make sure we invoke the old hook.
+      if cache_action?
+        cache_response resource, singular
+      end
+    end
+      
+  end
+end