puma 0.8.2 → 0.9.0

data/lib/puma/const.rb

@@ -71,7 +71,7 @@ module Puma
 
     PATH_INFO = 'PATH_INFO'.freeze
 
-    PUMA_VERSION = VERSION = "0.8.2".freeze
+    PUMA_VERSION = VERSION = "0.9.0".freeze
 
     PUMA_TMP_BASE = "puma".freeze
 
@@ -121,12 +121,45 @@ module Puma
 
     SERVER_PROTOCOL = "SERVER_PROTOCOL".freeze
     HTTP_11 = "HTTP/1.1".freeze
+    HTTP_10 = "HTTP/1.0".freeze
 
     SERVER_SOFTWARE = "SERVER_SOFTWARE".freeze
     GATEWAY_INTERFACE = "GATEWAY_INTERFACE".freeze
     CGI_VER = "CGI/1.2".freeze
 
-    STOP_COMMAND = "!".freeze
+    STOP_COMMAND = "?".freeze
+    HALT_COMMAND = "!".freeze
 
+    RACK_INPUT = "rack.input".freeze
+    RACK_URL_SCHEME = "rack.url_scheme".freeze
+    RACK_AFTER_REPLY = "rack.after_reply".freeze
+
+    HTTP = "http".freeze
+    HTTPS = "https".freeze
+
+    HTTPS_KEY = "HTTPS".freeze
+
+    HTTP_VERSION = "HTTP_VERSION".freeze
+    HTTP_CONNECTION = "HTTP_CONNECTION".freeze
+
+    HTTP_11_200 = "HTTP/1.1 200 OK\r\n".freeze
+    HTTP_10_200 = "HTTP/1.0 200 OK\r\n".freeze
+
+    CLOSE = "close".freeze
+    KEEP_ALIVE = "Keep-Alive".freeze
+
+    CONTENT_LENGTH2 = "Content-Length".freeze
+    CONTENT_LENGTH_S = "Content-Length: ".freeze
+    TRANSFER_ENCODING = "Transfer-Encoding".freeze
+
+    CONNECTION_CLOSE = "Connection: close\r\n".freeze
+    CONNECTION_KEEP_ALIVE = "Connection: Keep-Alive\r\n".freeze
+
+    TRANSFER_ENCODING_CHUNKED = "Transfer-Encoding: chunked\r\n".freeze
+    CLOSE_CHUNKED = "0\r\n\r\n".freeze
+
+    COLON = ": ".freeze
+
+    NEWLINE = "\n".freeze
   end
 end

data/lib/puma/control_cli.rb

@@ -0,0 +1,112 @@
+require 'optparse'
+
+require 'puma/const'
+require 'yaml'
+require 'uri'
+
+require 'socket'
+
+module Puma
+  class ControlCLI
+
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def setup_options
+      @parser = OptionParser.new do |o|
+        o.on "-S", "--state PATH", "Where the state file to use is" do |arg|
+          @path = arg
+        end
+      end
+    end
+
+    def connect
+      if str = @state['status_address']
+        uri = URI.parse str
+        case uri.scheme
+        when "tcp"
+          return TCPSocket.new uri.host, uri.port
+        when "unix"
+          path = "#{uri.host}#{uri.path}"
+          return UNIXSocket.new path
+        else
+          raise "Invalid URI: #{str}"
+        end
+      end
+
+      raise "No status address configured"
+    end
+
+    def run
+      setup_options
+
+      @parser.parse! @argv
+
+      @state = YAML.load_file(@path)
+
+      cmd = @argv.shift
+
+      meth = "command_#{cmd}"
+
+      if respond_to?(meth)
+        __send__(meth)
+      else
+        raise "Unknown command: #{cmd}"
+      end
+    end
+
+    def command_pid
+      puts "#{@state['pid']}"
+    end
+
+    def command_stop
+      sock = connect
+      sock << "GET /stop HTTP/1.0\r\n\r\n"
+      rep = sock.read
+
+      body = rep.split("\r\n").last
+      if body != '{ "status": "ok" }'
+        raise "Invalid response: '#{body}'"
+      else
+        puts "Requested stop from server"
+      end
+    end
+
+    def command_halt
+      sock = connect
+      s << "GET /halt HTTP/1.0\r\n\r\n"
+      rep = s.read
+
+      body = rep.split("\r\n").last
+      if body != '{ "status": "ok" }'
+        raise "Invalid response: '#{body}'"
+      else
+        puts "Requested halt from server"
+      end
+    end
+
+    def command_restart
+      sock = connect
+      sock << "GET /restart HTTP/1.0\r\n\r\n"
+      rep = sock.read
+
+      body = rep.split("\r\n").last
+      if body != '{ "status": "ok" }'
+        raise "Invalid response: '#{body}'"
+      else
+        puts "Requested restart from server"
+      end
+    end
+
+    def command_stats
+      sock = connect
+      s << "GET /stats HTTP/1.0\r\n\r\n"
+      rep = s.read
+
+      body = rep.split("\r\n").last
+
+      puts body
+    end
+  end
+end

data/lib/puma/events.rb

@@ -2,10 +2,17 @@ require 'puma/const'
 require 'stringio'
 
 module Puma
+  # The default implement of an event sink object used by Server
+  # for when certain kinds of events occur in the life of the server.
+  #
+  # The methods available are the events that the Server fires.
+  #
   class Events
 
     include Const
 
+    # Create an Events object that prints to +stdout+ and +stderr+.
+    #
     def initialize(stdout, stderr)
       @stdout = stdout
       @stderr = stderr
@@ -13,11 +20,19 @@ module Puma
 
     attr_reader :stdout, :stderr
 
+    # An HTTP parse error has occured.
+    # +server+ is the Server object, +env+ the request, and +error+ a
+    # parsing exception.
+    #
     def parse_error(server, env, error)
       @stderr.puts "#{Time.now}: HTTP parse error, malformed request (#{env[HTTP_X_FORWARDED_FOR] || env[REMOTE_ADDR]}): #{error.inspect}"
       @stderr.puts "#{Time.now}: ENV: #{env.inspect}\n---\n"
     end
 
+    # An unknown error has occured.
+    # +server+ is the Server object, +env+ the request, +error+ an exception
+    # object, and +kind+ some additional info.
+    #
     def unknown_error(server, env, error, kind="Unknown")
       if error.respond_to? :render
         error.render "#{Time.now}: #{kind} error", @stderr
@@ -29,6 +44,9 @@ module Puma
 
     DEFAULT = new(STDOUT, STDERR)
 
+    # Returns an Events object which writes it's status to 2 StringIO
+    # objects.
+    #
     def self.strings
       Events.new StringIO.new, StringIO.new
     end

data/lib/puma/null_io.rb

@@ -0,0 +1,35 @@
+module Puma
+
+  # Provides an IO-like object that always appears to contain no data.
+  # Used as the value for rack.input when the request has no body.
+  #
+  class NullIO
+
+    # Always returns nil
+    #
+    def gets
+      nil
+    end
+
+    # Never yields
+    #
+    def each
+    end
+
+    # Always returns nil
+    #
+    def read(count)
+      nil
+    end
+
+    # Does nothing
+    #
+    def rewind
+    end
+
+    # Does nothing
+    #
+    def close
+    end
+  end
+end

data/lib/puma/rack_patch.rb

@@ -1,7 +1,10 @@
 require 'rack/commonlogger'
 
 module Rack
-  # Patch CommonLogger to use after_reply
+  # Patch CommonLogger to use after_reply.
+  #
+  # Simply request this file and CommonLogger will be a bit more 
+  # efficient.
   class CommonLogger
     remove_method :call
 

data/lib/puma/server.rb

@@ -5,12 +5,15 @@ require 'stringio'
 require 'puma/thread_pool'
 require 'puma/const'
 require 'puma/events'
+require 'puma/null_io'
 
 require 'puma_http11'
 
 require 'socket'
 
 module Puma
+
+  # The HTTP Server itself. Serves out a single Rack app.
   class Server
 
     include Puma::Const
@@ -22,12 +25,15 @@ module Puma
     attr_accessor :min_threads
     attr_accessor :max_threads
     attr_accessor :persistent_timeout
+    attr_accessor :auto_trim_time
 
-    # Creates a working server on host:port (strange things happen if port
-    # isn't a Number).
+    # Create a server for the rack app +app+.
+    #
+    # +events+ is an object which will be called when certain error events occur
+    # to be handled. See Puma::Events for the list of current methods to implement.
     #
-    # Use HttpServer#run to start the server and HttpServer#acceptor.join to 
-    # join the thread that's processing incoming requests on the socket.
+    # Server#run returns a thread that you can join on to wait for the server
+    # to do it's work.
     #
     def initialize(app, events=Events::DEFAULT)
       @app = app
@@ -36,10 +42,11 @@ module Puma
       @check, @notify = IO.pipe
       @ios = [@check]
 
-      @running = false
+      @status = :stop
 
       @min_threads = 0
       @max_threads = 16
+      @auto_trim_time = 1
 
       @thread = nil
       @thread_pool = nil
@@ -61,33 +68,77 @@ module Puma
       }
     end
 
-    def add_tcp_listener(host, port)
-      @ios << TCPServer.new(host, port)
+    # On Linux, use TCP_CORK to better control how the TCP stack
+    # packetizes our stream. This improves both latency and throughput.
+    #
+    if RUBY_PLATFORM =~ /linux/
+      # 6 == Socket::IPPROTO_TCP
+      # 3 == TCP_CORK
+      # 1/0 == turn on/off
+      def cork_socket(socket)
+        socket.setsockopt(6, 3, 1) if socket.kind_of? TCPSocket
+      end
+
+      def uncork_socket(socket)
+        socket.setsockopt(6, 3, 0) if socket.kind_of? TCPSocket
+      end
+    else
+      def cork_socket(socket)
+      end
+
+      def uncork_socket(socket)
+      end
     end
 
+    # Tell the server to listen on host +host+, port +port+.
+    # If optimize_for_latency is true (the default) then clients connecting
+    # will be optimized for latency over throughput.
+    #
+    def add_tcp_listener(host, port, optimize_for_latency=true)
+      s = TCPServer.new(host, port)
+      if optimize_for_latency
+        s.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+      end
+      @ios << s
+    end
+
+    # Tell the server to listen on +path+ as a UNIX domain socket.
+    #
     def add_unix_listener(path)
       @ios << UNIXServer.new(path)
     end
 
-    # Runs the server.  It returns the thread used so you can "join" it.
-    # You can also access the HttpServer#acceptor attribute to get the
-    # thread later.
+    def backlog
+      @thread_pool and @thread_pool.backlog
+    end
+
+    def running
+      @thread_pool and @thread_pool.spawned
+    end
+
+    # Runs the server.  It returns the thread used so you can join it.
+    # The thread is always available via #thread to be join'd
+    #
     def run
       BasicSocket.do_not_reverse_lookup = true
 
-      @running = true
+      @status = :run
 
       @thread_pool = ThreadPool.new(@min_threads, @max_threads) do |client|
         process_client(client)
       end
 
+      if @auto_trim_time
+        @thread_pool.auto_trim!(@auto_trim_time)
+      end
+
       @thread = Thread.new do
         begin
           check = @check
           sockets = @ios
           pool = @thread_pool
 
-          while @running
+          while @status == :run
             begin
               ios = IO.select sockets
               ios.first.each do |sock|
@@ -104,7 +155,8 @@ module Puma
               @events.unknown_error self, env, e, "Listen loop"
             end
           end
-          graceful_shutdown
+
+          graceful_shutdown if @status == :stop
         ensure
           @ios.each { |i| i.close }
         end
@@ -113,22 +165,35 @@ module Puma
       return @thread
     end
 
+    # :nodoc:
     def handle_check
       cmd = @check.read(1) 
 
       case cmd
       when STOP_COMMAND
-        @running = false
+        @status = :stop
+        return true
+      when HALT_COMMAND
+        @status = :halt
         return true
       end
 
       return false
     end
 
+    # Given a connection on +client+, handle the incoming requests.
+    #
+    # This method support HTTP Keep-Alive so it may, depending on if the client
+    # indicates that it supports keep alive, wait for another request before
+    # returning.
+    #
     def process_client(client)
+      parser = HttpParser.new
+
       begin
         while true
-          parser = HttpParser.new
+          parser.reset
+
           env = @proto_env.dup
           data = client.readpartial(CHUNK_SIZE)
           nparsed = 0
@@ -150,7 +215,7 @@ module Puma
 
               if data.size > nparsed
                 data.slice!(0, nparsed)
-                parser = HttpParser.new
+                parser.reset
                 env = @proto_env.dup
                 nparsed = 0
               else
@@ -171,12 +236,16 @@ module Puma
             end
           end
         end
+
+      # The client disconnected while we were reading data
       rescue EOFError, SystemCallError
-        client.close rescue nil
+        # Swallow them. The ensure tries to close +client+ down
 
+      # The client doesn't know HTTP well
       rescue HttpParserError => e
         @events.parse_error self, env, e
 
+      # Server error
       rescue StandardError => e
         @events.unknown_error self, env, e, "Read"
 
@@ -191,6 +260,9 @@ module Puma
       end
     end
 
+    # Given a Hash +env+ for the request read from +client+, add
+    # and fixup keys to comply with Rack's env guidelines.
+    #
     def normalize_env(env, client)
       if host = env[HTTP_HOST]
         if colon = host.index(":")
@@ -223,6 +295,19 @@ module Puma
       env[REMOTE_ADDR] = client.peeraddr.last
     end
 
+    # The object used for a request with no body. All requests with
+    # no body share this one object since it has no state.
+    EmptyBody = NullIO.new
+
+    # Given the request +env+ from +client+ and a partial request body
+    # in +body+, finish reading the body if there is one and invoke
+    # the rack app. Then construct the response and write it back to
+    # +client+
+    #
+    # +cl+ is the previously fetched Content-Length header if there
+    # was one. This is an optimization to keep from having to look
+    # it up again.
+    #
     def handle_request(env, client, body, cl)
       normalize_env env, client
 
@@ -230,26 +315,16 @@ module Puma
         body = read_body env, client, body, cl
         return false unless body
       else
-        body = StringIO.new("")
-      end
-
-      env["rack.input"] = body
-      env["rack.url_scheme"] =  env["HTTPS"] ? "https" : "http"
-
-      allow_chunked = false
-
-      if env['HTTP_VERSION'] == 'HTTP/1.1'
-        allow_chunked = true
-        http_version = "HTTP/1.1 "
-        keep_alive = env["HTTP_CONNECTION"] != "close"
-      else
-        http_version = "HTTP/1.0 "
-        keep_alive = env["HTTP_CONNECTION"] == "Keep-Alive"
+        body = EmptyBody
       end
 
-      chunked = false
+      env[RACK_INPUT] = body
+      env[RACK_URL_SCHEME] =  env[HTTPS_KEY] ? HTTPS : HTTP
 
-      after_reply = env['rack.after_reply'] = []
+      # A rack extension. If the app writes #call'ables to this
+      # array, we will invoke them when the request is done.
+      #
+      after_reply = env[RACK_AFTER_REPLY] = []
 
       begin
         begin
@@ -264,26 +339,58 @@ module Puma
           content_length = res_body[0].size
         end
 
-        client.write http_version
-        client.write status.to_s
-        client.write " "
-        client.write HTTP_STATUS_CODES[status]
-        client.write "\r\n"
+        cork_socket client
 
-        colon = ": "
-        line_ending = "\r\n"
+        if env[HTTP_VERSION] == HTTP_11
+          allow_chunked = true
+          keep_alive = env[HTTP_CONNECTION] != CLOSE
+          include_keepalive_header = false
+
+          # An optimization. The most common response is 200, so we can
+          # reply with the proper 200 status without having to compute
+          # the response header.
+          #
+          if status == 200
+            client.write HTTP_11_200
+          else
+            client.write "HTTP/1.1 "
+            client.write status.to_s
+            client.write " "
+            client.write HTTP_STATUS_CODES[status]
+            client.write "\r\n"
+          end
+        else
+          allow_chunked = false
+          keep_alive = env[HTTP_CONNECTION] == KEEP_ALIVE
+          include_keepalive_header = keep_alive
+
+          # Same optimization as above for HTTP/1.1
+          #
+          if status == 200
+            client.write HTTP_10_200
+          else
+            client.write "HTTP/1.1 "
+            client.write status.to_s
+            client.write " "
+            client.write HTTP_STATUS_CODES[status]
+            client.write "\r\n"
+          end
+        end
+
+        colon = COLON
+        line_ending = LINE_END
 
         headers.each do |k, vs|
           case k
-          when "Content-Length"
+          when CONTENT_LENGTH2
             content_length = vs
             next
-          when "Transfer-Encoding"
+          when TRANSFER_ENCODING
             allow_chunked = false
             content_length = nil
           end
 
-          vs.split("\n").each do |v|
+          vs.split(NEWLINE).each do |v|
             client.write k
             client.write colon
             client.write v
@@ -291,12 +398,19 @@ module Puma
           end
         end
 
-        client.write "Connection: close\r\n" unless keep_alive
+        if include_keepalive_header
+          client.write CONNECTION_KEEP_ALIVE
+        elsif !keep_alive
+          client.write CONNECTION_CLOSE
+        end
 
         if content_length
-          client.write "Content-Length: #{content_length}\r\n"
+          client.write CONTENT_LENGTH_S
+          client.write content_length.to_s
+          client.write line_ending
+          chunked = false
         elsif allow_chunked
-          client.write "Transfer-Encoding: chunked\r\n"
+          client.write TRANSFER_ENCODING_CHUNKED
           chunked = true
         end
 
@@ -316,13 +430,13 @@ module Puma
         end
 
         if chunked
-          client.write "0"
-          client.write line_ending
-          client.write line_ending
+          client.write CLOSE_CHUNKED
           client.flush
         end
 
       ensure
+        uncork_socket client
+
         body.close
         res_body.close if res_body.respond_to? :close
 
@@ -332,6 +446,13 @@ module Puma
       return keep_alive
     end
 
+    # Given the requset +env+ from +client+ and the partial body +body+
+    # plus a potential Content-Length value +cl+, finish reading
+    # the body and return it.
+    #
+    # If the body is larger than MAX_BODY, a Tempfile object is used
+    # for the body, otherwise a StringIO is used.
+    #
     def read_body(env, client, body, cl)
       content_length = cl.to_i
 
@@ -377,50 +498,31 @@ module Puma
       return stream
     end
 
+    # A fallback rack response if +@app+ raises as exception.
+    #
     def lowlevel_error(e)
       [500, {}, ["No application configured"]]
     end
 
     # Wait for all outstanding requests to finish.
+    #
     def graceful_shutdown
       @thread_pool.shutdown if @thread_pool
     end
 
     # Stops the acceptor thread and then causes the worker threads to finish
     # off the request queue before finally exiting.
+    #
     def stop(sync=false)
       @notify << STOP_COMMAND
 
       @thread.join if @thread && sync
     end
 
-    def attempt_bonjour(name)
-      begin
-        require 'dnssd'
-      rescue LoadError
-        return false
-      end
-
-      @bonjour_registered = false
-      announced = false
-
-      @ios.each do |io|
-        if io.kind_of? TCPServer
-          fixed_name = name.gsub(/\./, "-")
+    def halt(sync=false)
+      @notify << HALT_COMMAND
 
-          DNSSD.announce io, "puma - #{fixed_name}", "http" do |r|
-            @bonjour_registered = true
-          end
-
-          announced = true
-        end
-      end
-
-      return announced
-    end
-
-    def bonjour_registered?
-      @bonjour_registered ||= false
+      @thread.join if @thread && sync
     end
   end
 end