racknga 0.9.1 → 0.9.2

data/lib/racknga/exception_mail_notifier.rb

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2010  Kouhei Sutou <kou@clear-code.com>
+# Copyright (C) 2010-2011  Kouhei Sutou <kou@clear-code.com>
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -29,21 +29,50 @@ module Racknga
   class ExceptionMailNotifier
     def initialize(options)
       @options = Utils.normalize_options(options || {})
+      reset_limitation
     end
 
     def notify(exception, environment)
-      host = @options[:host] || "localhost"
       return if to.empty?
-      mail = format(exception, environment)
+
+      if limitation_expired?
+        send_summaries unless @summaries.empty?
+        reset_limitation
+      end
+
+      if @mail_count < max_mail_count_in_limit_duration
+        send_notification(exception, environment)
+      else
+        @summaries << summarize(exception, environment)
+      end
+
+      @mail_count += 1
+    end
+
+    private
+    def reset_limitation
+      @mail_count = 0
+      @count_start_time = Time.now
+      @summaries = []
+    end
+
+    def limitation_expired?
+      (Time.now - @count_start_time) > limit_duration
+    end
+
+    def send(mail)
+      host = @options[:host] || "localhost"
       Net::SMTP.start(host, @options[:port]) do |smtp|
         smtp.send_message(mail, from, *to)
       end
     end
 
-    private
-    def format(exception, environment)
-      header = format_header(exception, environment)
-      body = format_body(exception, environment)
+    def create_mail(options)
+      subject = [@options[:subject_label], options[:subject]].compact.join(' ')
+      header = header(:subject => subject)
+
+      body = options[:body]
+
       mail = "#{header}\r\n#{body}"
       mail.force_encoding("utf-8")
       begin
@@ -53,24 +82,28 @@ module Racknga
       mail.force_encoding("ASCII-8BIT")
     end
 
-    def format_header(exception, environment)
+    def header(options)
       <<-EOH
 MIME-Version: 1.0
 Content-Type: Text/Plain; charset=#{charset}
 Content-Transfer-Encoding: #{transfer_encoding}
 From: #{from}
 To: #{to.join(', ')}
-Subject: #{encode_subject(subject(exception, environment))}
+Subject: #{encode_subject(options[:subject])}
 Date: #{Time.now.rfc2822}
 EOH
     end
 
-    def format_body(exception, environment)
+    def send_notification(exception, environment)
+      mail = create_mail(:subject => exception.to_s,
+                         :body => notification_body(exception, environment))
+      send(mail)
+    end
+
+    def notification_body(exception, environment)
       request = Rack::Request.new(environment)
       body = <<-EOB
-URL: #{request.url}
---
-#{exception.class}: #{exception}
+#{summarize(exception, environment)}
 --
 #{exception.backtrace.join("\n")}
 EOB
@@ -98,8 +131,26 @@ EOE
       body
     end
 
-    def subject(exception, environment)
-      [@options[:subject_label], exception.to_s].compact.join(' ')
+    def send_summaries
+        subject = "summaries of #{@summaries.size} notifications"
+        mail = create_mail(:subject => subject,
+                           :body => report_body)
+        send(mail)
+    end
+
+    def report_body
+      @summaries[0..10].join("\n\n")
+    end
+
+    def summarize(exception, environment)
+      request = Rack::Request.new(environment)
+      <<-EOB
+Timestamp: #{Time.now.rfc2822}
+--
+URL: #{request.url}
+--
+#{exception.class}: #{exception}
+EOB
     end
 
     def to
@@ -125,6 +176,16 @@ EOE
       @options[:charset] || 'utf-8'
     end
 
+    DEFAULT_MAX_MAIL_COUNT_IN_LIMIT_DURATION = 2
+    def max_mail_count_in_limit_duration
+      @options[:max_mail_count_in_limit_duration] || DEFAULT_MAX_MAIL_COUNT_IN_LIMIT_DURATION
+    end
+
+    DEFAULT_LIMIT_DURATION = 60 # one minute
+    def limit_duration
+      @options[:limit_duration] || DEFAULT_LIMIT_DURATION
+    end
+
     def transfer_encoding
       case charset
       when /\Autf-8\z/i

data/lib/racknga/log_database.rb

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2010  Kouhei Sutou <kou@clear-code.com>
+# Copyright (C) 2010-2011  Kouhei Sutou <kou@clear-code.com>
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -21,7 +21,13 @@ require 'fileutils'
 require 'groonga'
 
 module Racknga
+  # This is a log database based on groonga. It is used by
+  # Racknga::Middleware::Log.
+  #
+  # Normally, #purge_old_responses is only used for log
+  # maintenance.
   class LogDatabase
+    # @param [String] database_path the path for log database.
     def initialize(database_path)
       @database_path = database_path
       @context = Groonga::Context.new(:encoding => :none)
@@ -45,12 +51,23 @@ module Racknga
       @database.close
     end
 
+    # Purges old responses. To clear old logs, you should
+    # call this method. All records created before
+    # +base_time+ are removed.
+    #
+    # You can call this method by the different
+    # process from your Rack application
+    # process. (e.g. cron.) It's multi process safe.
+    #
+    # @param [Time] base_time the oldest record time to be
+    # removed. The default value is 1 day ago.
     def purge_old_entries(base_time=nil)
       base_time ||= Time.now - 60 * 60 * 24
-      entries.select do |record|
+      target_entries = entries.select do |record|
         record.time_stamp < base_time
-      end.each do |record|
-        record.key.delete
+      end
+      target_entries.each do |entry|
+        entry.key.delete
       end
     end
 

data/lib/racknga/middleware/cache.rb

@@ -16,17 +16,36 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
-require 'digest/md5'
+require 'digest'
 require 'yaml'
 require 'racknga/cache_database'
 
 module Racknga
   module Middleware
+    # This is a helper middleware for
+    # Racknga::Middleware::Cache.
+    #
+    # If your Rack application provides different views to
+    # mobile user agent and PC user agent in the same URL,
+    # this middleware is useful. Your Rack application can
+    # has different caches for mobile user agent and PC user
+    # agent.
+    #
+    # This middleware requires jpmobile.
+    #
+    # Usage:
+    #   use Racnkga::Middleware::PerUserAgentCache
+    #   use Racnkga::Middleware::Cache, :database_path => "var/cache/db"
+    #   run YourApplication
+    #
+    # @see http://jpmobile-rails.org/ jpmobile
+    # @see Racknga::Middleware::Cache
     class PerUserAgentCache
       def initialize(application)
         @application = application
       end
 
+      # For Rack.
       def call(environment)
         mobile = environment["rack.jpmobile"]
         if mobile
@@ -35,16 +54,47 @@ module Racknga
         else
           user_agent_key = "pc"
         end
-        key = environment[Cache::KEY_KEY]
-        environment[Cache::KEY_KEY] = [key, user_agent_key].join(":")
+        key = environment[Cache::KEY]
+        environment[Cache::KEY] = [key, user_agent_key].join(":")
         @application.call(environment)
       end
     end
 
+    # This is a middleware that provides page cache.
+    #
+    # This stores page contents into a groonga
+    # database. A groonga database can access by multi
+    # process. It means that your Rack application processes
+    # can share the same cache. For example, Passenger runs
+    # your Rack application with multi processes.
+    #
+    # Cache key is the request URL by default. It can be
+    # customized by env[Racknga::Cache::KEY]. For example,
+    # Racknga::Middleware::PerUserAgentCache and
+    # Racknga::Middleware::JSONP use it.
+    #
+    # This only caches the following responses:
+    # * 200 status response.
+    # * text/*, */json, */xml or */*+xml content type response.
+    #
+    # Usage:
+    #   use Racnkga::Middleware::Cache, :database_path => "var/cache/db"
+    #   run YourApplication
+    #
+    # @see Racknga::Middleware::PerUserAgentCache
+    # @see Racknga::Middleware::JSONP
+    # @see Racknga::Middleware::Deflater
+    # @see Racknga::CacheDatabase
     class Cache
-      KEY_KEY = "racknga.cache.key"
-      START_TIME_KEY = "racknga.cache.start_time"
+      KEY = "racknga.cache.key"
+      START_TIME = "racknga.cache.start_time"
 
+      # @return [Racknga::CacheDatabase] the database used
+      #   by this middleware.
+      attr_reader :database
+
+      # @option options [String] :database_path the database
+      #   path to be stored caches.
       def initialize(application, options={})
         @application = application
         @options = Utils.normalize_options(options || {})
@@ -53,12 +103,13 @@ module Racknga
         @database = CacheDatabase.new(database_path)
       end
 
+      # For Rack.
       def call(environment)
         request = Rack::Request.new(environment)
         return @application.call(environment) unless use_cache?(request)
         age = @database.configuration.age
-        key = environment[KEY_KEY] || request.fullpath
-        environment[START_TIME_KEY] = Time.now
+        key = normalize_key(environment[KEY] || request.fullpath)
+        environment[START_TIME] = Time.now
         cache = @database.responses
         record = cache[key]
         if record and record.age == age
@@ -68,10 +119,12 @@ module Racknga
         end
       end
 
+      # ensures creating cache database.
       def ensure_database
         @database.ensure_database
       end
 
+      # close the cache database.
       def close_database
         @database.close_database
       end
@@ -97,6 +150,14 @@ module Racknga
         true
       end
 
+      def normalize_key(key)
+        if key.size > 4096
+          Digest::SHA1.hexdigest(key).force_encoding("ASCII-8BIT")
+        else
+          key
+        end
+      end
+
       def handle_request(cache, key, age, request)
         status, headers, body = @application.call(request.env)
         if skip_caching_response?(status, headers, body)
@@ -142,13 +203,13 @@ module Racknga
       end
 
       def compute_checksum(status, encoded_headers, encoded_body)
-        md5 = Digest::MD5.new
-        md5 << status.to_s
-        md5 << ":"
-        md5 << encoded_headers
-        md5 << ":"
-        md5 << encoded_body
-        md5.hexdigest.force_encoding("ASCII-8BIT")
+        checksum = Digest::SHA1.new
+        checksum << status.to_s
+        checksum << ":"
+        checksum << encoded_headers
+        checksum << ":"
+        checksum << encoded_body
+        checksum.hexdigest.force_encoding("ASCII-8BIT")
       end
 
       def valid_cache?(status, encoded_headers, encoded_body, checksum)

data/lib/racknga/middleware/deflater.rb

@@ -18,6 +18,42 @@
 
 module Racknga
   module Middleware
+    # This is a middleware that deflates response except for
+    # IE6. If your Rack application need support IE6, use
+    # this middleware instead of Rack::Deflater.
+    #
+    # Usage:
+    #   require "racknga"
+    #
+    #   use Racknga::Middleware::Deflater
+    #   run YourApplication
+    #
+    # You can use this middleware with
+    # Racknga::Middleware::Cache. You *should* use this
+    # middleware before the cache middleware:
+    #   use Racknga::Middleawre::Deflater
+    #   use Racknga::Middleawre::Cache, :database_path => "var/cache/db"
+    #   run YourApplication
+    #
+    # If you use this middleware after the cache middleware,
+    # you get two problems. It's the first problem pattern
+    # that the cache middleware may return deflated response
+    # to IE6. It's the second problem pattern that the cache
+    # middleware may return not deflated response to no IE6
+    # user agent. Here are examples:
+    #
+    # Problem case:
+    #   use Racknga::Middleawre::Cache, :database_path => "var/cache/db"
+    #   use Racknga::Middleawre::Deflater
+    #   run YourApplication
+    #
+    # Problem pattern1:
+    #   http://localhost:9292/ by Firefox -> no cache. cache deflated response.
+    #   http://localhost:9292/ by IE6     -> use deflated response cache.
+    #
+    # Problem pattern2:
+    #   http://localhost:9292/ by IE6     -> no cache. cache not deflated response.
+    #   http://localhost:9292/ by Firefox -> use not deflated response cache.
     class Deflater
       def initialize(application, options={})
         @application = application
@@ -25,6 +61,7 @@ module Racknga
         @options = Utils.normalize_options(options || {})
       end
 
+      # For Rack.
       def call(environment)
         if ie6?(environment)
           @application.call(environment)

data/lib/racknga/middleware/exception_notifier.rb

@@ -20,6 +20,22 @@ require 'racknga/exception_mail_notifier'
 
 module Racknga
   module Middleware
+    # This is a middleware that mails exception details on
+    # error. It's useful for finding your Rack application
+    # troubles.
+    #
+    # Usage:
+    #   require "racknga"
+    #   require "racknga/middleware/exception_notifier"
+    #
+    #   notifier_options = {
+    #     :subject_label => "[YourApplication]",
+    #     :from => "reporter@example.com",
+    #     :to => "maintainers@example.com",
+    #   }
+    #   notifiers = [Racknga::ExceptionMailNotifier.new(notifier_options)]
+    #   use Racknga::Middleware::ExceptionNotifier, :notifiers => notifiers
+    #   run YourApplication
     class ExceptionNotifier
       def initialize(application, options={})
         @application = application
@@ -27,6 +43,7 @@ module Racknga
         @notifiers = @options[:notifiers] || []
       end
 
+      # For Rack.
       def call(environment)
         @application.call(environment)
       rescue Exception => exception

data/lib/racknga/middleware/instance_name.rb

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2011  Ryo Onodera <onodera@clear-code.com>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+module Racknga
+  module Middleware
+    # This is a middleware that adds "X-Responsed-By" header
+    # to responses. It's useful to determine responded
+    # server when your Rack applications are deployed behind
+    # load balancers.
+    #
+    # Usage:
+    #   require "racknga"
+    #   use Racknga::Middleware::InstanceName
+    #   run YourApplication
+    class InstanceName
+      attr_reader :header
+      def initialize(application, options={})
+        @application = application
+        @options = options
+
+        @header = construct_header.freeze
+        @headers = construct_headers.freeze
+      end
+
+      # For Rack.
+      def call(environment)
+        response = @application.call(environment).to_a
+
+        [
+          response[0],
+          response[1].merge(@headers),
+          response[2],
+        ]
+      end
+
+      def application_name
+        @options[:application_name] || @application.class.name
+      end
+
+      def version
+        @options[:version]
+      end
+
+      def revision
+        `git describe --abbrev=7 HEAD`.strip # XXX be SCM-agonostic
+      end
+
+      def server
+        `hostname`.strip
+      end
+
+      def user
+        `id --user --name`.strip
+      end
+
+      private
+      DEFAULT_HEADER_NAME = "X-Responsed-By"
+      def header_name
+        @options[:header_name] || DEFAULT_HEADER_NAME
+      end
+
+      def construct_headers
+        {
+          header_name => header,
+        }
+      end
+
+      def construct_header
+        format_header(format_application_name(application_name),
+                      format_version(version),
+                      format_revision(revision),
+                      format_server(server),
+                      format_user(user))
+      end
+
+      def format_header(*arguments)
+        arguments.compact.join(" ")
+      end
+
+      def format_application_name(name)
+        format_if_possible(name) do
+          "#{name}"
+        end
+      end
+
+      def format_version(version)
+        format_if_possible(version) do
+          "v#{version}"
+        end
+      end
+
+      def format_revision(revision)
+        format_if_possible(revision) do
+          "(at #{revision})"
+        end
+      end
+
+      def format_server(server)
+        format_if_possible(server) do
+          "on #{server}"
+        end
+      end
+
+      def format_user(user)
+        format_if_possible(user) do
+          "by #{user}"
+        end
+      end
+
+      def format_if_possible(data)
+        if data and (data.respond_to?(:to_s) and not data.to_s.empty?)
+          result = yield
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/racknga/middleware/jsonp.rb

@@ -18,26 +18,87 @@
 
 module Racknga
   module Middleware
+    # This is a middleware that provides JSONP support.
+    #
+    # If you use this middleware, your Rack application just
+    # returns JSON response.
+    #
+    # Usage:
+    #   require "racknga"
+    #
+    #   use Rack::ContentLength
+    #   use Racknga::Middleware::JSONP
+    #   json_application = Proc.new do |env|
+    #     [200,
+    #      {"Content-Type" => "application/json"},
+    #      ['{"Hello": "World"}']]
+    #   end
+    #   run json_application
+    #
+    # Results:
+    #   % curl 'http://localhost:9292/'
+    #   {"Hello": "World"}
+    #   % curl 'http://localhost:9292/?callback=function'
+    #   function({"Hello": "World"})
+    #
+    # You can use this middleware with
+    # Racknga::Middleware::Cache. You *should* use this
+    # middleware before the cache middleware:
+    #   use Racknga::Middleawre::JSONP
+    #   use Racknga::Middleawre::Cache, :database_path => "var/cache/db"
+    #   run YourApplication
+    #
+    # If you use this middleware after the cache middleware,
+    # the cache middleware will cache many responses that
+    # just only differ callback parameter value. Here are
+    # examples:
+    #
+    # Recommended case:
+    #   use Racknga::Middleawre::JSONP
+    #   use Racknga::Middleawre::Cache, :database_path => "var/cache/db"
+    #   run YourApplication
+    #
+    # Requests:
+    #   http://localhost:9292/                    -> no cache. cached.
+    #   http://localhost:9292/?callback=function1 -> use cache.
+    #   http://localhost:9292/?callback=function2 -> use cache.
+    #   http://localhost:9292/?callback=function3 -> use cache.
+    #   http://localhost:9292/?callback=function1 -> use cache.
+    #
+    # Not recommended case:
+    #   use Racknga::Middleawre::Cache, :database_path => "var/cache/db"
+    #   use Racknga::Middleawre::JSONP
+    #   run YourApplication
+    #
+    # Requests:
+    #   http://localhost:9292/                    -> no cache. cached.
+    #   http://localhost:9292/?callback=function1 -> no cache. cached.
+    #   http://localhost:9292/?callback=function2 -> no cache. cached.
+    #   http://localhost:9292/?callback=function3 -> no cache. cached.
+    #   http://localhost:9292/?callback=function1 -> use cache.
     class JSONP
       def initialize(application)
         @application = application
       end
 
+      # For Rack.
       def call(environment)
         request = Rack::Request.new(environment)
         callback = request["callback"]
         update_cache_key(request) if callback
         status, headers, body = @application.call(environment)
         return [status, headers, body] unless callback
-        return [status, headers, body] unless json_response?(headers)
+        header_hash = Rack::Utils::HeaderHash.new(headers)
+        return [status, headers, body] unless json_response?(header_hash)
         body = Writer.new(callback, body)
-        [status, headers, body]
+        update_content_type(header_hash)
+        [status, header_hash, body]
       end
 
       private
       def update_cache_key(request)
         return unless Middleware.const_defined?(:Cache)
-        cache_key_key = Cache::KEY_KEY
+        cache_key = Cache::KEY
 
         path = request.fullpath
         path, parameters = path.split(/\?/, 2)
@@ -49,17 +110,28 @@ module Racknga
           path << "?" << parameters unless parameters.empty?
         end
 
-        key = request.env[cache_key_key]
-        request.env[cache_key_key] = [key, path].compact.join(":")
+        key = request.env[cache_key]
+        request.env[cache_key] = [key, path].compact.join(":")
       end
 
-      def json_response?(headers)
-        content_type = Rack::Utils::HeaderHash.new(headers)["Content-Type"]
-        content_type == "application/json" or
-          content_type == "application/javascript" or
-          content_type == "text/javascript"
+      def json_response?(header_hash)
+        content_type = header_hash["Content-Type"]
+        media_type = content_type.split(/\s*;\s*/, 2).first.downcase
+        media_type == "application/json" or
+          media_type == "application/javascript" or
+          media_type == "text/javascript"
       end
 
+      def update_content_type(header_hash)
+        content_type = header_hash["Content-Type"]
+        media_type, parameters = content_type.split(/\s*;\s*/, 2)
+        # We should use application/javascript not
+        # text/javascript when all IE <= 8 are deprecated. :<
+        updated_content_type = ["text/javascript", parameters].compact.join("; ")
+        header_hash["Content-Type"] = updated_content_type
+      end
+
+      # @private
       class Writer
         def initialize(callback, body)
           @callback = callback