1 files changed, 75 insertions, 7 deletions

diff --git a/lib/raindrops/middleware.rb b/lib/raindrops/middleware.rb
index d45fa1a..f75af0b 100644
--- a/lib/raindrops/middleware.rb
+++ b/lib/raindrops/middleware.rb
@@ -1,18 +1,86 @@
 # -*- encoding: binary -*-
 require 'raindrops'
 
-# Raindrops middleware should be loaded at the top of Rack
-# middleware stack before other middlewares for maximum accuracy.
+# Raindrops::Middleware is Rack middleware that allows snapshotting
+# current activity from an HTTP request.  For all operating systems,
+# it returns at least the following fields:
+#
+# * calling - the number of application dispatchers on your machine
+# * writing - the number of clients being written to on your machine
+#
+# Additional fields are available for \Linux users.
+#
+# It should be loaded at the top of Rack middleware stack before other
+# middlewares for maximum accuracy.
+#
+# === Usage (Rainbows!/Unicorn preload_app=false)
+#
+# If you're using preload_app=false (the default) in your Rainbows!/Unicorn
+# config file, you'll need to create the global Stats object before
+# forking.
+#
+#    require 'raindrops'
+#    $stats ||= Raindrops::Middleware::Stats.new
+#
+# In your Rack config.ru:
+#
+#    use Raindrops::Middleware, :stats => $stats
+#
+# === Usage (Rainbows!/Unicorn preload_app=true)
+#
+# If you're using preload_app=true in your Rainbows!/Unicorn
+# config file, just add the middleware to your stack:
+#
+# In your Rack config.ru:
+#
+#    use Raindrops::Middleware
+#
+# === Linux-only extras!
+#
+# To get bound listener statistics under \Linux, you need to specify the
+# listener names for your server.  You can even include listen sockets for
+# *other* servers on the same machine.  This can be handy for monitoring
+# your nginx proxy as well.
+#
+# In your Rack config.ru, just pass the :listeners argument as an array of
+# strings (along with any other arguments).  You can specify any
+# combination of TCP or Unix domain socket names:
+#
+#    use Raindrops::Middleware, :listeners => %w(0.0.0.0:80 /tmp/.sock)
+#
+# If you're running Unicorn 0.98.0 or later, you don't have to pass in
+# the :listeners array, Raindrops will automatically detect the listeners
+# used by Unicorn master process.  This does not detect listeners in
+# different processes, of course.
+#
+# The response body includes the following stats for each listener
+# (see also Raindrops::ListenStats):
+#
+# * active - total number of active clients on that listener
+# * queued - total number of queued (pre-accept()) clients on that listener
+#
 class Raindrops::Middleware
-  attr_accessor :app, :stats, :path, :tcp, :unix
+  attr_accessor :app, :stats, :path, :tcp, :unix # :nodoc:
+
+  # A Raindrops::Struct used to count the number of :calling and :writing
+  # clients.  This struct is intended to be shared across multiple processes
+  # and both counters are updated atomically.
+  #
+  # This is supported on all operating systems supported by Raindrops
+  class Stats < Raindrops::Struct.new(:calling, :writing)
+  end
 
   # :stopdoc:
-  Stats = Raindrops::Struct.new(:calling, :writing)
   PATH_INFO = "PATH_INFO"
   require "raindrops/middleware/proxy"
-  autoload :TCP, "raindrops/middleware/tcp"
   # :startdoc:
 
+  # +app+ may be any Rack application, this middleware wraps it.
+  # +opts+ is a hash that understands the following members:
+  #
+  # * :stats - Raindrops::Middleware::Stats struct (default: Stats.new)
+  # * :path - HTTP endpoint used for reading the stats (default: "/_raindrops")
+  # * :listeners - array of host:port or socket paths (default: from Unicorn)
   def initialize(app, opts = {})
     @app = app
     @stats = opts[:stats] || Stats.new
@@ -32,7 +100,7 @@ class Raindrops::Middleware
   end
 
   # standard Rack endpoint
-  def call(env)
+  def call(env) # :nodoc:
     env[PATH_INFO] == @path and return stats_response
     begin
       @stats.incr_calling
@@ -48,7 +116,7 @@ class Raindrops::Middleware
     end
   end
 
-  def stats_response
+  def stats_response  # :nodoc:
     body = "calling: #{@stats.calling}\n" \
            "writing: #{@stats.writing}\n"