hassox-pancake 0.1.6

data/lib/pancake/master.rb

@@ -0,0 +1,87 @@
+module Pancake
+  # A simple rack application
+  OK_APP      = lambda{|env| Rack::Response.new("OK",         200,  {"Content-Type" => "text/plain"}).finish}
+  MISSING_APP = lambda{|env| Rack::Response.new("NOT FOUND",  404,  {"Content-Type" => "text/plain"}).finish}
+
+  extend Middleware
+
+  class << self
+    attr_accessor :root
+
+    # Start Pancake.  This provides a full pancake stack to use inside a rack application
+    #
+    # @param        [Hash]    opts
+    # @option opts  [String]  :root   The root of the pancake stack
+    #
+    # @example Starting a pancake stack
+    #   Pancake.start(:root => "/path/to/root"){ MyApp # App to use}
+    #
+    # @api public
+    # @author Daniel Neighman
+    def start(opts, &block)
+      raise "You must specify a root directory for pancake" unless opts[:root]
+      self.root = opts[:root]
+
+      # Build Pancake
+      the_app = instance_eval(&block)
+      Pancake::Middleware.build(the_app, middlewares)
+    end
+
+    # Provides the environment for the currently running pancake
+    #
+    # @return [String] The currently running environment
+    # @api public
+    # @author Daniel Neighman
+    def env
+      ENV['RACK_ENV'] ||= "development"
+    end
+
+    # A helper method to get the expanded directory name of a __FILE__
+    #
+    # @return [String] an expanded version of file
+    # @api public
+    # @author Daniel Neighman
+    def get_root(file)
+      File.expand_path(File.dirname(file))
+    end
+
+    # Labels that specify what kind of stack you're intending on loading.
+    # This is a simliar concept to environments but it is in fact seperate conceptually.
+    #
+    # The reasoning is that you may want to use a particular stack type or types.
+    # By using stack labels, you can define middleware to be active.
+    #
+    # @example
+    #   Pancake.stack_labels == [:development, :demo]
+    #
+    #   # This would activate middleware marked with :development or :demo or the implicit :any label
+    #
+    # @return [Array<Symbol>]
+    #   An array of labels to activate
+    #   The default is [:production]
+    # @see Pancake.stack_labels= to set the labels for this stack
+    # @see Pancake::Middleware#stack to see how to specify middleware to be active for the given labels
+    # @api public
+    # @author Daniel Neighman
+    def stack_labels
+      return @stack_labels unless @stack_labels.nil? || @stack_labels.empty?
+      self.stack_labels = [:production]
+    end
+
+    # Sets the stack labels to activate the associated middleware
+    #
+    # @param [Array<Symbol>, Symbol] An array of labels or a single label, specifying the middlewares to activate
+    #
+    # @example
+    #   Pancake.stack_labels = [:demo, :production]
+    #
+    # @see Pancake.stack_labels
+    # @see Pancake::Middleware#stack
+    # @api public
+    # @author Daniel Neighman
+    def stack_labels=(*labels)
+      @stack_labels = labels.flatten.compact
+    end
+
+  end # self
+end # Pancake

data/lib/pancake/middleware.rb

@@ -0,0 +1,354 @@
+module Pancake
+  # Provides a mixin to use on any class to give it middleware management capabilities.
+  # This module provides a rich featureset for defining a middleware stack.
+  #
+  # Middlware can be set before, or after other middleware, can be tagged / named,
+  # and can be declared to only be active in certain types of stacks.
+  module Middleware
+
+    # When extending a base class with the Pancake::Middleware,
+    # an inner class StackMiddleware is setup on the base class.
+    # This inner class is where all the inforamation is stored on the stack to be defined
+    # The inner StackMiddleware class is also set to be inherited
+    # with the base class (and all children classes)
+    # So that each class gets its own copy and may maintain the base
+    # stack from the parent, but edit it in the child.
+    def self.extended(base)
+      base.class_eval <<-RUBY
+        class StackMiddleware < Pancake::Middleware::StackMiddleware; end
+      RUBY
+      if base.is_a?(Class)
+        base.inheritable_inner_classes :StackMiddleware
+      end
+      super
+    end # self.extended
+
+    # Build a middleware stack given an application and some middleware classes
+    #
+    # @param [Object] app a rack application to wrap in the middlware list
+    # @param [Array<StackMiddleware>] mwares an array of
+    # StackMiddleware instances where each instance
+    #   defines a middleware to use in constructing the stack
+    #
+    # @example
+    #   Pancake::Middleware.build(@app, [MWare_1, MWare_2])
+    # @return [Object]
+    #   An application instance of the first middleware defined in the array
+    #   The application should be an instance that conforms to Rack specifications
+    #
+    # @api public
+    # @since 0.1.0
+    # @author Daniel Neighman
+    def self.build(app, mwares)
+      mwares.reverse.inject(app) do |a, m|
+        case m.middleware.instance_method(:initialize).arity
+        when 1
+          m.middleware.new(a,&m.block)
+        when -2
+          m.middleware.new(a, m.options, &m.block)
+        else
+          raise "Don't know how to initialize #{m.middleware}"
+        end
+      end
+    end
+
+    # @param [Array<Symbol>] labels An array of labels specifying the stack labels to use to build the middlware list
+    #
+    # @example
+    #   MyApp.middlewares(:production) # provides all middlewares matching the :production label, or the implicit :any label
+    #   MyApp.middlewares(:development, :demo) # provides all middlewares matching the :development or :demo or implicit :any label
+    #
+    # @return [Array<StackMiddleware>]
+    #   An array of middleware specifications in the order they should be used to wrap the application
+    #
+    # @see Pancake::Middleware::StackMiddleware
+    # @see Pancake.stack_labels for a decription of stack_labels
+    # @api public
+    # @since 0.1.0
+    # @author Daniel Neighman
+    def middlewares(*labels)
+      labels = labels.flatten
+      self::StackMiddleware.middlewares(*labels)
+    end
+
+    # Useful for adding additional information into your middleware stack  definition
+    #
+    # @param [Object] name
+    #   The name of a given middleware.  Each piece of middleware has a name in the stack.
+    #   By naming middleware we can refer to it later, swap it out for a different class or even just remove it from the stack.
+    # @param        [Hash] opts An options hash
+    # @option opts  [Array<Symbol>] :labels ([:any])
+    #   An array of symbols, or a straight symbol that defines what stacks this middleware sould be active in
+    # @option opts [Object] :before
+    #   Sets this middlware to be run after the middleware named.  Name is either the name given to the
+    #   middleware stack, or the Middleware class itself.
+    # @option opts [Object] :after
+    #   Sets this middleware to be run after the middleware name.  Name is either the name given to the
+    #   middleware stack or the Middleware class itself.
+    #
+    # @example Declaring un-named middleware via the stack
+    #   MyClass.stack.use(MyMiddleware)
+    #
+    # This middleware will be named MyMiddleware, and can be specified with (:before | :after) => MyMiddleware
+    #
+    # @example Declaring a named middleware via the stack
+    #   MyClass.stack(:foo).use(MyMiddleware)
+    #
+    # This middleware will be named :foo and can be specified with (:before | :after) => :foo
+    #
+    # @example Declaring a named middleware with a :before key
+    #   MyClass.stack(:foo, :before => :bar).use(MyMiddleware)
+    #
+    # This middleware will be named :foo and will be run before the middleware named :bar
+    # If :bar is not run, :foo will not be run either
+    #
+    # @example Declaring a named middlware with an :after key
+    #   MyClass.stack(:foo, :after => :bar).use(MyMiddleware)
+    #
+    # This middleware will be named :foo and will be run after the middleware named :bar
+    # If :bar is not run, :foo will not be run either
+    #
+    # @example Declaring a named middleware with some labels
+    #   MyClass.stack(:foo, :lables => [:demo, :production, :staging]).use(MyMiddleware)
+    #
+    # This middleware will only be run when pancake is set with the :demo, :production or :staging labels
+    #
+    # @example A full example
+    #   MyClass.stack(:foo, :labels => [:staging, :development], :after => :session).use(MyMiddleware)
+    #
+    #
+    # @see Pancake::Middleware#use
+    # @api public
+    # @since 0.1.0
+    # @author Daniel Neighman
+    def stack(name = nil, opts = {})
+      if self::StackMiddleware._mwares[name] && mw = self::StackMiddleware._mwares[name]
+        unless mw.stack == self
+          mw = self::StackMiddleware._mwares[name] = self::StackMiddleware._mwares[name].dup
+        end
+        mw
+      else
+        self::StackMiddleware.new(name, self, opts)
+      end
+    end
+
+    # Adds middleware to the current stack definition
+    #
+    # @param [Class] middleware  The middleware class to use in the stack
+    # @param [Hash]  opts        An options hash that is passed through to the middleware when it is instantiated
+    #
+    # @yield The block is provided to the middlewares #new method when it is initialized
+    #
+    # @example Bare use call
+    #   MyApp.use(MyMiddleware, :some => :option){ # middleware initialization block here }
+    #
+    # @example Use call after a stack call
+    #   MyApp.stack(:foo).use(MyMiddleware, :some => :option){ # middleware initialization block here }
+    #
+    # @see Pancake::Middleware#stack
+    # @api public
+    # @since 0.1.0
+    # @author Daniel Neighman
+    def use(middleware, opts = {}, &block)
+      stack(middleware).use(middleware, opts, &block)
+    end # use
+
+    # StackMiddleware manages the definition of the middleware stack for a given class.
+    # It's instances are responsible for the definition of a single piece of middleware, and the class
+    # is responsible for specifying the full stack for a given class.
+    #
+    # When Pancake::Middleware extends a class, an inner class is created in that class called StackMiddleware.
+    # That StackMiddleware class inherits from Pancake::Middleware::StackMiddleware.
+    #
+    # @example The setup when Pancake::Middleware is extended
+    #   MyClass.extend Pancake::Middleware
+    #   # sets up
+    #
+    #   class MyClass
+    #     class StackMiddleware < Pancake::Middleware::StackMiddleware; end
+    #   end
+    #
+    # This is then set is an inheritable inner class on the extended class, such that when it is inherited,
+    # the StackMiddleware class is inherited to an inner class of the same name on the child.
+    class StackMiddleware
+      # @api private
+      class_inheritable_reader :_central_mwares, :_mwares, :_before, :_after
+      @_central_mwares, @_before, @_after, @_mwares = [], {}, {}, {}
+
+      # @api private
+      attr_reader :middleware, :name
+      # @api private
+      attr_accessor :config, :block, :stack, :options
+
+      class << self
+        def use(mware, opts, &block)
+          new(mware).use(mware, opts, &block)
+        end
+
+        # Resets this stack middlware.  Useful for specs
+        def reset!
+          _central_mwares.clear
+          _mwares.clear
+          _before.clear
+          _after.clear
+        end
+
+        # Get the middleware list for this StackMiddleware for the given labels
+        #
+        # @param [Symbol] labels The label or list of labels to construct a stack from.
+        #
+        # @example Specified labels
+        #   MyClass::StackMiddleware.middlewares(:production, :demo)
+        #
+        # @example No Labels Specified
+        #   MyClass::StackMiddleware.middlewares
+        #
+        # This will include all defined middlewares in the given stack
+        #
+        # @return [Array<StackMiddleware>]
+        #   An array of the middleware definitions to use in the order that they should be applied
+        #   Takes into account all :before, :after settings and only constructs the stack where
+        #   the labels are applied
+        #
+        # @see Pancake.stack_labels for a description on stack labels
+        # @api public
+        # @since 0.1.0
+        # @author Daniel Neighman
+        def middlewares(*labels)
+          _central_mwares.map do |name|
+            map_middleware(name, *labels)
+          end.flatten
+        end
+
+        # Map the middleware for a given <name>ed middleware.  Applies the before and after groups of middlewares
+        #
+        # @param [Object] name    The name of the middleware to map the before and after groups to
+        # @param [Symbol] labels  A label or list of labels to use to construct the middleware stack
+        #
+        # @example
+        #   MyClass::StackMiddleware.map_middleware(:foo, :production, :demo)
+        #
+        # Constructs the middleware list based on the middleware named :foo, including all :before, and :after groups
+        #
+        # @return [Array<StackMiddleware>]
+        #   Provides an array of StackMiddleware instances in the array [<before :foo>, <:foo>, <after :foo>]
+        #
+        # @api private
+        # @since 0.1.0
+        # @author Daniel Neighman
+        def map_middleware(name, *labels)
+          result = []
+          _before[name] ||= []
+          _after[name]  ||= []
+          if _mwares[name] && _mwares[name].use_for_labels?(*labels)
+            result << _before[name].map{|n| map_middleware(n)}
+            result << _mwares[name]
+            result << _after[name].map{|n| map_middleware(n)}
+            result.flatten
+          end
+          result
+        end
+
+        # Provides access to a named middleware
+        #
+        # @param [Object] name The name of the defined middleware
+        #
+        # @return [StackMiddleware] The middleware definition associated with <name>
+        #
+        # @api public
+        # @since 0.1.0
+        # @author Daniel Neighman
+        def [](name)
+          _mwares[name]
+        end
+      end
+
+      # Provides access to a named middleware
+      #
+      # @see Pancake::Middleware::StackMiddleware.[] for an explaination
+      # @since 0.1.0
+      # @author Daniel Neighman
+      def [](name)
+        self.class._mwares[name]
+      end
+
+      # @param          [Object]  name a name for this middleware definition.  Usually a symbol, but could be the class.
+      # @param          [Object]  stack the stack owner of this middleware.
+      # @param          [Hash]    options an options hash.  Provide labels for this middleware.
+      # @option options [Array]   :labels ([:any])
+      #   The labels that are associated with this middleware
+      # @option options [Object]  :before A middleware name to add this middleware before
+      # @option options [Object]  :after A middleware name to add this middleware after
+      #
+      # @see Pancake::Middleware.stack_labels
+      # @api private
+      # @author Daniel Neighman
+      def initialize(name, stack, options = {})
+        @name, @stack, @options = name, stack, options
+        @options[:labels] ||= [:any]
+      end
+
+      # Delete this middleware from the current stack
+      #
+      # @api public
+      # @since 0.1.0
+      # @author Daniel Neighman
+      def delete!
+        self.class._mwares.delete(name)
+        self.class._before.delete(name)
+        self.class._after.delete(name)
+        self.class._central_mwares.delete(name)
+        self
+      end
+
+      # Specify the actual middleware definition to use
+      #
+      # @param [Class] mware   A Middleware class to use.  This should be a class of Middleware which conforms to the Rack spec
+      # @param [Hash]  config  A configuration hash to give to the middleware class on initialization
+      # @yield The block is passed to the middleware on initialization
+      #
+      # @see Pancake::Middleware.use
+      # @api public
+      # @since 0.1.0
+      # @author Daniel Neighman
+      def use(mware, config = {}, &block)
+        @middleware, @config, @block = mware, config, block
+        @name = @middleware if name.nil?
+        if options[:before]
+          raise "#{options[:before].inspect} middleware is not defined for this stack" unless self.class._mwares.keys.include?(options[:before])
+          self.class._before[options[:before]] ||= []
+          self.class._before[options[:before]] << name
+        elsif options[:after]
+          raise "#{options[:after].inspect} middleware is not defined for this stack" unless self.class._mwares.keys.include?(options[:after])
+          self.class._after[options[:after]] ||= []
+          self.class._after[options[:after]] << name
+        else
+          self.class._central_mwares << name unless self.class._central_mwares.include?(name)
+        end
+        self.class._mwares[name] = self
+        self
+      end
+
+      # Checks if this middleware definition should be included from the labels given
+      # @param [Symbol] labels The label or list of labels to check if this middleware should be included
+      #
+      # @return [Boolean] true if this middlware should be included
+      #
+      # @api private
+      # @since 0.1.0
+      # @author Daniel Neighman
+      def use_for_labels?(*labels)
+        return true if labels.empty? || options[:labels].nil? || options[:labels].include?(:any)
+        !(options[:labels] & labels).empty?
+      end
+
+      # @api private
+      def dup
+        result = super
+        result.config = result.config.dup
+        result.options = result.options.dup
+        result
+      end
+    end
+  end # Middleware
+end # Pancake

data/lib/pancake/mime_types.rb

@@ -0,0 +1,265 @@
+require 'set'
+require 'rack/accept_media_types'
+module Pancake
+  module MimeTypes
+    # A collection of all the mime types that pancake knows about
+    #
+    # @returns [Array<Pancake::MimeTypes::Type>] an array of
+    # Pancake::MimeTypes::Type objects that pancake knows about.  To
+    # add a new type to the collection, simply create a new
+    # Pancake::MimeTypes::Type
+    #
+    # @see Pancake::MimeTypes::Type
+    # @api public
+    # @author Daniel Neighman
+    def self.types
+      @types || reset! && @types
+    end
+    
+    # Finds a Pancake::MimeTypes::Type object by the provided
+    # extension
+    #
+    # @param ext [String,Symbol] - The extension to look for
+    # @return [Pancake::MimeTypes::Type, nil] - The corresponding mime
+    # type object or nil if there were none found that match the
+    # provided extension
+    #
+    # @example
+    #   Pancake::MimeTypes.type_by_extension("html") # => A
+    #   Pancake::MimeTypes::Type object for the .html extension
+    #
+    # @see Pancake::MimeTypes::Type
+    # @api public
+    # @author Daniel Neighman
+    def self.type_by_extension(ext)
+      ext = ext.to_s
+      types.detect{|t| t.extension == ext}
+    end
+    
+    # Pancake manages mime types by grouping them together.
+    # 
+    # @return [Set<Pancake::MimeTypes::Type>] - A enumerable of Type
+    # objects associated with this group
+    #
+    # @see Pancake::MimeTypes.group
+    # @api public
+    # @author Daniel Neighman
+    def self.groups
+      @groups || reset! && @groups
+    end
+    
+    # Pancake::MimeTypes are managed by grouping them together.
+    # Each group may consist of many mime types by extension
+    # By Accessing a group that doesn't yet exist, the group is
+    # created and initialized with the matching type wwith extension
+    # A group may have many mime type / accept types associated with
+    # it
+    #
+    # @param name [String,Symbol] - The name of the group
+    #
+    # @example
+    #   Pancake::MimeTypes.group(:html)
+    #
+    # @return [Enumerable<Pancake::MimeTypes::Type>] - returns all
+    # mime types in the specified group.  If the group does not exist,
+    # or has not been accessed, the group will be created on the fly
+    # with the first mime type that matches the group name
+    #
+    # @see Pancake::MimeTypes.group_as
+    # @api public
+    # @author Daniel Neighman
+    def self.group(name)
+      groups[name.to_s]
+    end
+    
+    # Creates a group of mime types.  Any group of mimes can be
+    # arbitrarily grouped under the specified name.  The group is
+    # initilized with the mime type whose extension matches the name,
+    # and any further extensions have their mime types added to the
+    # group
+    #
+    # @param name [String,Symbol] - the name of the group to
+    # create/append
+    # @param exts [List of String,Symbol] - a list of extensions to
+    # associate with this mime type
+    #
+    # @see Pancake::MimeTypes.group
+    # @api public
+    # @author Daniel Neighman
+    def self.group_as(name, *exts)
+      exts.each do |ext|
+        group(name) << type_by_extension(ext) unless group(name).include?(type_by_extension(ext))
+      end
+      group(name)
+    end
+    
+    # Resets the Pancake::MimeType cache and re-creates the
+    # Pancake::MimeTypes default types and groups
+    # Good for use in specs
+    # @api private
+    def self.reset!
+      @types = []
+      @negotiated_accept_types = nil
+      @groups = Hash.new do |h,k|
+        k = k.to_s
+        h[k] = []
+        t = Pancake::MimeTypes.type_by_extension(k)
+        h[k] << t unless t.nil?
+        h[k]
+      end
+      reset_mime_types!
+      reset_mime_groups!
+    end
+
+    # Used in specs to reset the mime types back to their
+    # corresponding originals in Rack::Mime::MIME_TYPES
+    # @api private
+    def self.reset_mime_types!
+      # Setup the mime types based on the rack mime types
+      Rack::Mime::MIME_TYPES.each do |ext, type|
+        ext =~ /\.(.*)$/
+        e = $1
+        t = type_by_extension(ext)
+        if t
+          t.type_strings << type 
+       else
+          t = Type.new(e, type) 
+        end
+      end
+    end
+    
+    # Used in specs to reset the default mime groups of
+    # pancake::MimeTypes
+    # @api private
+    def self.reset_mime_groups!
+      # html
+      group_as(:html, "html", "htm", "xhtml")
+      group_as(:text, "text", "txt")
+      type_by_extension("xml").type_strings << "text/xml"
+
+      group_as(:svg, "svgz")
+    end
+    
+    # Negotiates the type and group that the accept_type string
+    # matches
+    # @param type [String] the accept_type header string from the
+    # request
+    # @param provided [list of String,Symbol] - A list of strings /
+    # symbols of the included groups to use to try and match this
+    # accept type header.
+    #
+    # @example
+    #   accept_type = "text/xml,text/html"
+    #   result = Pancake::MimeTypes.negotiate_accept_type(accept_type, :html,
+    #  :text)
+    #  result # => [:html, <#Pancake::MimeTypes::Type for html>]
+    #
+    # @return [Array] An array with the group name, and mime type
+    # @api public
+    # @author Daniel Neighman
+    def self.negotiate_accept_type(type, *provided)
+      accepted_types = Rack::AcceptMediaTypes.new(type)
+      provided = provided.flatten
+      key = [accepted_types, provided]
+      return negotiated_accept_types[key] if negotiated_accept_types[key]
+      
+      accepted_type = nil
+      
+      if accepted_types.include?("*/*")
+        name = provided.first
+        accepted_type = group(name).first
+        negotiated_accept_types[key] = [name, accepted_type.type_strings.first, accepted_type]
+        return negotiated_accept_types[key]
+      end
+      
+      # Check to see if any accepted types match
+      accepted_types.each do |at|
+        provided.flatten.each do |name|
+          accepted_type = match_content_type(at, name)
+          if accepted_type
+            at = accepted_type.type_strings.first if at == "*/*"
+            if accepted_types.join.size > 4096
+              # Don't save the key if it's larger than 4 k.
+              # This could hit a dos attack if it's repeatedly hit
+              # with anything large
+              negotiated_accept_types[key] = [name, at, accepted_type]
+            end
+            return [name, at, accepted_type]
+          end
+        end
+      end
+      nil
+    end
+    
+    # Negotiates the content type based on the extension and the
+    # provided groups to see if there is a match.
+    #
+    # @param ext [String] The extension to negotiate
+    # @param provided [Symbol] A list of symbols each of which is the
+    # name of a mime group
+    #
+    # @return [Symbol, String, Pancake::MimeTypes::Type] The first
+    # parameter returned is the group name that matched.  The second,
+    # is the Content-Type to respond to the client with, the third,
+    # the raw pancake mime type
+    #
+    # @see Pancake::MimeTypes.group
+    # @see Pancake::MimeTypes::Type
+    # @api public
+    def self.negotiate_by_extension(ext, *provided)
+      provided = provided.flatten
+      key = [ext, provided]
+      return negotiated_accept_types[key] if negotiated_accept_types[key]
+
+      result = nil
+      provided.each do |name|
+        group(name).each do |type|
+          if type.extension == ext
+            result = [name, type.type_strings.first, type]
+            negotiated_accept_types[key] = result
+            return result
+          end
+        end
+      end
+      result
+    end # self.negotiate_by_extension
+    
+
+    # A basic type for mime types
+    # Each type can have an extension and many type strings that
+    # correspond to the mime type that would be specified in a request
+    # When a Pancake::MimeTypes::Type is created, it is added to the
+    # Pancake::MimeTypes.types collection
+    # @api public
+    class Type
+      attr_reader   :type_strings, :extension
+
+      def initialize(extension, *type_strings)
+        @extension = extension
+        @type_strings = []
+        type_strings.flatten.each do |ts|
+          @type_strings << ts
+        end
+        MimeTypes.types << self
+      end
+    end
+    
+    private
+    # Checks to see if a group matches an accept type string
+    # @api private
+    def self.match_content_type(accept_type, key)
+      group(key).detect do |t|
+        t.type_strings.include?(accept_type) || accept_type == "*/*"
+      end
+    end
+    
+    # Provides a cache for already negotiated types
+    # @api private
+    def self.negotiated_accept_types
+      @negotiated_accept_types ||= {}
+    end
+        
+  end # MimeTypes
+end # Pancake
+
+