pancake 0.1.8

data/lib/pancake/logger.rb

@@ -0,0 +1,200 @@
+# Pancake::Logger == Merb::Logger
+class Pancake::Logger < Extlib::Logger
+  # :api: public
+  def verbose!(message, level = :warn)
+    send("#{level}!", message) if Pancake.configuration.verbose_logging
+  end
+
+  # :api: public
+  def verbose(message, level = :warn)
+    send(level, message) if Pancake.configuration.verbose_logging
+  end
+end
+
+# require "time" # httpdate
+# ==== Public Pancake Logger API
+#
+# To replace an existing logger with a new one:
+#  Pancake::Logger.set_log(log{String, IO},level{Symbol, String})
+#
+# Available logging levels are
+#   Pancake::Logger::{ Fatal, Error, Warn, Info, Debug }
+#
+# Logging via:
+#   Pancake.logger.fatal(message<String>,&block)
+#   Pancake.logger.error(message<String>,&block)
+#   Pancake.logger.warn(message<String>,&block)
+#   Pancake.logger.info(message<String>,&block)
+#   Pancake.logger.debug(message<String>,&block)
+#
+# Logging with autoflush:
+#   Pancake.logger.fatal!(message<String>,&block)
+#   Pancake.logger.error!(message<String>,&block)
+#   Pancake.logger.warn!(message<String>,&block)
+#   Pancake.logger.info!(message<String>,&block)
+#   Pancake.logger.debug!(message<String>,&block)
+#
+# Flush the buffer to
+#   Pancake.logger.flush
+#
+# Remove the current log object
+#   Pancake.logger.close
+#
+# ==== Private Pancake Logger API
+#
+# To initialize the logger you create a new object, proxies to set_log.
+#   Pancake::Logger.new(log{String, IO},level{Symbol, String})
+module Pancake
+
+  class Logger
+
+    attr_accessor :level
+    attr_accessor :delimiter
+    attr_accessor :auto_flush
+    attr_reader   :buffer
+    attr_reader   :log
+    attr_reader   :init_args
+
+    # ==== Notes
+    # Ruby (standard) logger levels:
+    # :fatal:: An unhandleable error that results in a program crash
+    # :error:: A handleable error condition
+    # :warn:: A warning
+    # :info:: generic (useful) information about system operation
+    # :debug:: low-level information for developers
+    Levels = Mash.new({
+      :fatal => 7,
+      :error => 6,
+      :warn  => 4,
+      :info  => 3,
+      :debug => 0
+    }) unless const_defined?(:Levels)
+
+    @@mutex = {}
+
+    public
+
+    # To initialize the logger you create a new object, proxies to set_log.
+    #
+    # ==== Parameters
+    # *args:: Arguments to create the log from. See set_logs for specifics.
+    def initialize(*args)
+      set_log(*args)
+    end
+
+    # Replaces an existing logger with a new one.
+    #
+    # ==== Parameters
+    # log<IO, String>:: Either an IO object or a name of a logfile.
+    # log_level<~to_sym>::
+    #   The log level from, e.g. :fatal or :info. Defaults to :error in the
+    #   production environment and :debug otherwise.
+    # delimiter<String>::
+    #   Delimiter to use between message sections. Defaults to " ~ ".
+    # auto_flush<Boolean>::
+    #   Whether the log should automatically flush after new messages are
+    #   added. Defaults to false.
+    def set_log(stream = Pancake.configuration.log_stream,
+      log_level  = Pancake.configuration.log_level,
+      delimiter  = Pancake.configuration.log_delimiter,
+      auto_flush = Pancake.configuration.log_auto_flush)
+
+      @buffer                   = []
+      @delimiter                = delimiter
+      @auto_flush               = auto_flush
+
+      if Levels[log_level]
+        @level                  = Levels[log_level]
+      else
+        @level                  = log_level
+      end
+
+      @log                      = stream
+      @log.sync                 = true
+      @mutex = (@@mutex[@log] ||= Mutex.new)
+    end
+
+    # Flush the entire buffer to the log object.
+    def flush
+      return unless @buffer.size > 0
+      @mutex.synchronize do
+        @log.write(@buffer.slice!(0..-1).join(''))
+      end
+    end
+
+    # Close and remove the current log object.
+    def close
+      flush
+      @log.close if @log.respond_to?(:close) && !@log.tty?
+      @log = nil
+    end
+
+    # Appends a message to the log. The methods yield to an optional block and
+    # the output of this block will be appended to the message.
+    #
+    # ==== Parameters
+    # string<String>:: The message to be logged. Defaults to nil.
+    #
+    # ==== Returns
+    # String:: The resulting message added to the log file.
+    def <<(string = nil)
+      message = ""
+      message << delimiter
+      message << string if string
+      message << "\n" unless message[-1] == ?\n
+      @buffer << message
+      flush if @auto_flush
+
+      message
+    end
+    alias :push :<<
+
+    # Generate the logging methods for Pancake.logger for each log level.
+    Levels.each_pair do |name, number|
+      class_eval <<-LEVELMETHODS, __FILE__, __LINE__
+
+      # Appends a message to the log if the log level is at least as high as
+      # the log level of the logger.
+      #
+      # ==== Parameters
+      # string<String>:: The message to be logged. Defaults to nil.
+      #
+      # ==== Returns
+      # self:: The logger object for chaining.
+      def #{name}(message = nil)
+        if #{number} >= level
+          message = block_given? ? yield : message
+          self << message if #{number} >= level
+        end
+        self
+      end
+
+      # Appends a message to the log if the log level is at least as high as
+      # the log level of the logger. The bang! version of the method also auto
+      # flushes the log buffer to disk.
+      #
+      # ==== Parameters
+      # string<String>:: The message to be logged. Defaults to nil.
+      #
+      # ==== Returns
+      # self:: The logger object for chaining.
+      def #{name}!(message = nil)
+        if #{number} >= level
+          message = block_given? ? yield : message
+          self << message if #{number} >= level
+          flush if #{number} >= level
+        end
+        self
+      end
+
+      # ==== Returns
+      # Boolean:: True if this level will be logged by this logger.
+      def #{name}?
+        #{number} >= level
+      end
+      LEVELMETHODS
+    end
+
+  end
+
+end

data/lib/pancake/master.rb

@@ -0,0 +1,123 @@
+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, *args)
+      File.expand_path(File.join(File.dirname(file), *args))
+    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
+
+    def handle_errors!(*args)
+      @handle_errors = begin
+                         if args.size > 1
+                           args.flatten
+                         else
+                           args.first
+                         end
+                      end
+    end
+
+    def handle_errors?
+      if @handle_errors.nil?
+        !(Pancake.env == "development")
+      else
+        case @handle_errors
+        when Array
+          @handle_errors.include?(Pancake.env)
+        when TrueClass, FalseClass
+          @handle_errors
+        when String
+          Pancake.env == @handle_errors
+        end
+      end
+    end
+
+    def default_error_handling!
+      @handle_errors = nil
+    end
+
+    def logger
+      @logger ||= Pancake::Logger.new
+    end
+
+    def logger=(logr)
+      @logger = logr
+    end
+  end # self
+end # Pancake

data/lib/pancake/middleware.rb

@@ -0,0 +1,347 @@
+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|
+        m.middleware.new(a, *m.args, &m.block)
+      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, *_args, &block)
+      stack(middleware).use(middleware, *_args, &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 :args, :block, :stack, :options
+
+      class << self
+        def use(mware, *_args, &block)
+          new(mware).use(mware, *_args, &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, *_args, &block)
+        @middleware, @args, @block = mware, _args, 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.args = result.args.map{|element| element.dup}
+        result.options = result.options.dup
+        result
+      end
+    end
+  end # Middleware
+end # Pancake

data/lib/pancake/middlewares/logger.rb

@@ -0,0 +1,16 @@
+require 'logger'
+module Pancake
+  module Middlewares
+    class Logger
+      attr_reader :app
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        env[Pancake::Constants::ENV_LOGGER_KEY] ||= Pancake.logger
+        @app.call(env)
+      end
+    end
+  end
+end