lotus-controller 0.2.0 → 0.3.0

data/lib/lotus/action.rb

@@ -5,6 +5,7 @@ require 'lotus/action/redirect'
 require 'lotus/action/exposable'
 require 'lotus/action/throwable'
 require 'lotus/action/callbacks'
+require 'lotus/action/validatable'
 require 'lotus/action/callable'
 
 module Lotus
@@ -33,28 +34,30 @@ module Lotus
     #
     # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
     #
-    # @see Lotus::Action::Configurable
     # @see Lotus::Action::Rack
     # @see Lotus::Action::Mime
     # @see Lotus::Action::Redirect
     # @see Lotus::Action::Exposable
     # @see Lotus::Action::Throwable
     # @see Lotus::Action::Callbacks
+    # @see Lotus::Action::Validatable
+    # @see Lotus::Action::Configurable
     # @see Lotus::Action::Callable
     def self.included(base)
       base.class_eval do
-        include Configurable
         include Rack
         include Mime
         include Redirect
         include Exposable
         include Throwable
         include Callbacks
+        include Validatable
+        include Configurable
         prepend Callable
       end
     end
 
-    protected
+    private
 
     # Finalize the response
     #
@@ -66,9 +69,12 @@ module Lotus
     # @api private
     # @abstract
     #
-    # @see Lotus::Action::Mime
-    # @see Lotus::Action::Cookies
-    # @see Lotus::Action::Callable
+    # @see Lotus::Action::Mime#finish
+    # @see Lotus::Action::Exposable#finish
+    # @see Lotus::Action::Callable#finish
+    # @see Lotus::Action::Session#finish
+    # @see Lotus::Action::Cookies#finish
+    # @see Lotus::Action::Cache#finish
     def finish
     end
   end

data/lib/lotus/action/cache.rb

@@ -0,0 +1,174 @@
+require 'lotus/action/cache/cache_control'
+require 'lotus/action/cache/expires'
+require 'lotus/action/cache/conditional_get'
+
+module Lotus
+  module Action
+    # Cache type API
+    #
+    # @since 0.3.0
+    #
+    # @see Lotus::Action::Cache::ClassMethods#cache_control
+    # @see Lotus::Action::Cache::ClassMethods#expires
+    # @see Lotus::Action::Cache::ClassMethods#fresh
+    module Cache
+      # Override Ruby's hook for modules.
+      # It includes exposures logic
+      #
+      # @param base [Class] the target action
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
+      def self.included(base)
+        base.class_eval do
+          include CacheControl, Expires
+        end
+      end
+
+      protected
+
+      # Specify response freshness policy for HTTP caches (Cache-Control header).
+      # Any number of non-value directives (:public, :private, :no_cache,
+      # :no_store, :must_revalidate, :proxy_revalidate) may be passed along with
+      # a Hash of value directives (:max_age, :min_stale, :s_max_age).
+      #
+      # See RFC 2616 / 14.9 for more on standard cache control directives:
+      # http://tools.ietf.org/html/rfc2616#section-14.9.1
+      #
+      # @param values [Array<Symbols, Hash>] mapped to cache_control directives
+      # @option values [Symbol] :public
+      # @option values [Symbol] :private
+      # @option values [Symbol] :no_cache
+      # @option values [Symbol] :no_store
+      # @option values [Symbol] :must_validate
+      # @option values [Symbol] :proxy_revalidate
+      # @option values [Hash] :max_age
+      # @option values [Hash] :min_stale
+      # @option values [Hash] :s_max_age
+      #
+      # @return void
+      #
+      # @since 0.3.0
+      # @api public
+      #
+      # @example
+      #   require 'lotus/controller'
+      #   require 'lotus/action/cache'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #     include Lotus::Action::Cache
+      #
+      #     def call(params)
+      #       # ...
+      #
+      #       # set Cache-Control directives
+      #       cache_control :public, max_age: 900, s_maxage: 86400
+      #
+      #       # overwrite previous Cache-Control directives
+      #       cache_control :private, :no_cache, :no_store
+      #
+      #       => Cache-Control: private, no-store, max-age=900
+      #
+      #     end
+      #   end
+      #
+      def cache_control(*values)
+        cache_control = CacheControl::Directives.new(*values)
+        headers.merge!(cache_control.headers)
+      end
+
+      # Set the Expires header and Cache-Control/max-age directive. Amount
+      # can be an integer number of seconds in the future or a Time object
+      # indicating when the response should be considered "stale". The remaining
+      # "values" arguments are passed to the #cache_control helper:
+      #
+      # @param amount [Integer,Time] number of seconds or point in time
+      # @param values [Array<Symbols>] mapped to cache_control directives
+      #
+      # @return void
+      #
+      # @since 0.3.0
+      # @api public
+      #
+      # @example
+      #   require 'lotus/controller'
+      #   require 'lotus/action/cache'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #     include Lotus::Action::Cache
+      #
+      #     def call(params)
+      #       # ...
+      #
+      #       # set Cache-Control directives and Expires
+      #       expires 900, :public
+      #
+      #       # overwrite Cache-Control directives and Expires
+      #       expires 300, :private, :no_cache, :no_store
+      #
+      #       => Expires: Thu, 26 Jun 2014 12:00:00 GMT
+      #       => Cache-Control: private, no-cache, no-store max-age=300
+      #
+      #     end
+      #   end
+      #
+      def expires(amount, *values)
+        expires = Expires::Directives.new(amount, *values)
+        headers.merge!(expires.headers)
+      end
+
+      # Set the etag, last_modified, or both headers on the response
+      # and halts a 304 Not Modified if the request is still fresh
+      # respecting IfNoneMatch and IfModifiedSince request headers
+      #
+      # @param options [Hash]
+      # @option options [Integer] :etag for testing IfNoneMatch conditions
+      # @option options [Date] :last_modified for testing IfModifiedSince conditions
+      #
+      # @return void
+      #
+      # @since 0.3.0
+      # @api public
+      #
+      # @example
+      #   require 'lotus/controller'
+      #   require 'lotus/action/cache'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #     include Lotus::Action::Cache
+      #
+      #     def call(params)
+      #       # ...
+      #
+      #       # set etag response header and halt 304
+      #       # if request matches IF_NONE_MATCH header
+      #       fresh etag: @resource.updated_at.to_i
+      #
+      #       # set last_modified response header and halt 304
+      #       # if request matches IF_MODIFIED_SINCE
+      #       fresh last_modified: @resource.updated_at
+      #
+      #       # set etag and last_modified response header,
+      #       # halt 304 if request matches IF_MODIFIED_SINCE
+      #       # and IF_NONE_MATCH
+      #       fresh last_modified: @resource.updated_at
+      #
+      #     end
+      #   end
+      def fresh(options)
+        conditional_get = ConditionalGet.new(@_env, options)
+
+        headers.merge!(conditional_get.headers)
+
+        conditional_get.fresh? do
+          halt 304
+        end
+      end
+    end
+  end
+end

data/lib/lotus/action/cache/cache_control.rb

@@ -0,0 +1,70 @@
+require 'lotus/action/cache/directives'
+
+module Lotus
+  module Action
+    module Cache
+
+      # Module with Cache-Control logic
+      #
+      # @since 0.3.0
+      # @api private
+      module CacheControl
+
+        # The HTTP header for Cache-Control
+        #
+        # @since 0.3.0
+        # @api private
+        HEADER = 'Cache-Control'.freeze
+
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+          def cache_control(*values)
+            @cache_control_directives ||= Directives.new(*values)
+          end
+
+          def cache_control_directives
+            @cache_control_directives || Object.new.tap do |null_object|
+              def null_object.headers
+                Hash.new
+              end
+            end
+          end
+        end
+
+        # Finalize the response including default cache headers into the response
+        #
+        # @since 0.3.0
+        # @api private
+        #
+        # @see Lotus::Action#finish
+        def finish
+          super
+          headers.merge!(self.class.cache_control_directives.headers) unless headers.include? HEADER
+        end
+
+        # Class which stores CacheControl values
+        #
+        # @since 0.3.0
+        #
+        # @api private
+        #
+        class Directives
+          def initialize(*values)
+            @directives = Lotus::Action::Cache::Directives.new(*values)
+          end
+
+          def headers
+            if @directives.any?
+              { HEADER => @directives.join(', ') }
+            else
+              {}
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lotus/action/cache/conditional_get.rb

@@ -0,0 +1,93 @@
+module Lotus
+  module Action
+    module Cache
+      # @since 0.3.0
+      # @api private
+      IF_NONE_MATCH = 'HTTP_IF_NONE_MATCH'.freeze
+
+      # The HTTP header for ETag
+      #
+      # @since 0.3.0
+      # @api private
+      ETAG          = 'ETag'.freeze
+
+      # @since 0.3.0
+      # @api private
+      IF_MODIFIED_SINCE = 'HTTP_IF_MODIFIED_SINCE'.freeze
+
+      # The HTTP header for Last-Modified
+      #
+      # @since 0.3.0
+      # @api private
+      LAST_MODIFIED = 'Last-Modified'.freeze
+
+      # ETag value object
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      class ETag
+        def initialize(env, value)
+          @env, @value = env, value
+        end
+
+        def fresh?
+          none_match && @value == none_match
+        end
+
+        def header
+          { ETAG => @value } if none_match
+        end
+
+        private
+
+        def none_match
+          @env[IF_NONE_MATCH]
+        end
+      end
+
+      # LastModified value object
+      #
+      # @since 0.3.0
+      # @api private
+      class LastModified
+        def initialize(env, value)
+          @env, @value = env, value
+        end
+
+        def fresh?
+          modified_since && Time.httpdate(modified_since).to_i >= @value.to_i
+        end
+
+        def header
+          { LAST_MODIFIED => @value.httpdate } if modified_since
+        end
+
+        private
+
+        def modified_since
+          @env[IF_MODIFIED_SINCE]
+        end
+      end
+
+      # Class responsible to determine if a given request is fresh
+      # based on IF_NONE_MATCH and IF_MODIFIED_SINCE headers
+      #
+      # @since 0.3.0
+      # @api private
+      class ConditionalGet
+        def initialize(env, options)
+          @validations = [ ETag.new(env, options[:etag]), LastModified.new(env, options[:last_modified]) ]
+        end
+
+        def fresh?
+          yield if @validations.any?(&:fresh?)
+        end
+
+        def headers
+          @validations.map(&:header).compact.reduce Hash.new, :merge
+        end
+      end
+    end
+  end
+end

data/lib/lotus/action/cache/directives.rb

@@ -0,0 +1,99 @@
+module Lotus
+  module Action
+    module Cache
+
+      # Cache-Control directives which have values
+      #
+      # @since 0.3.0
+      # @api private
+      VALUE_DIRECTIVES      = %i(max_age s_maxage min_fresh max_stale).freeze
+
+      # Cache-Control directives which are implicitly true
+      #
+      # @since 0.3.0
+      # @api private
+      NON_VALUE_DIRECTIVES  = %i(public private no_cache no_store no_transform must_revalidate proxy_revalidate).freeze
+
+      # Class representing value directives
+      #
+      # ex: max-age=600
+      #
+      # @since 0.3.0
+      # @api private
+      class ValueDirective
+        attr_reader :name
+
+        def initialize(name, value)
+          @name, @value = name, value
+        end
+
+        def to_str
+          "#{@name.to_s.tr('_', '-')}=#{@value.to_i}"
+        end
+
+        def valid?
+          VALUE_DIRECTIVES.include? @name
+        end
+      end
+
+      # Class representing non value directives
+      #
+      # ex: no-cache
+      #
+      # @since 0.3.0
+      # @api private
+      class NonValueDirective
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        def to_str
+          @name.to_s.tr('_', '-')
+        end
+
+        def valid?
+          NON_VALUE_DIRECTIVES.include? @name
+        end
+      end
+
+      # Collection of value and non value directives
+      #
+      # @since 0.3.0
+      # @api private
+      class Directives
+        include Enumerable
+
+        def initialize(*values)
+          @directives = []
+          values.each do |directive_key|
+            if directive_key.kind_of? Hash
+              directive_key.each { |name, value| self.<< ValueDirective.new(name, value) }
+            else
+              self.<< NonValueDirective.new(directive_key)
+            end
+          end
+        end
+
+        def each
+          @directives.each { |d| yield d }
+        end
+
+        def <<(directive)
+          @directives << directive if directive.valid?
+        end
+
+        def values
+          @directives.delete_if do |directive|
+            directive.name == :public && @directives.map(&:name).include?(:private)
+          end
+        end
+
+        def join(separator)
+          values.join(separator)
+        end
+      end
+    end
+  end
+end