From d520222050ce88388ae5e446c63642d79cc9796e Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 10 May 2011 16:34:51 -0700 Subject: configurator: update user-facing documentation Finally, we have all methods in configurator and it's much easier to document! --- lib/rainbows/configurator.rb | 117 ++++++++++++++++++++++++++++--------------- 1 file changed, 77 insertions(+), 40 deletions(-) (limited to 'lib/rainbows') diff --git a/lib/rainbows/configurator.rb b/lib/rainbows/configurator.rb index 95bb590..29d905b 100644 --- a/lib/rainbows/configurator.rb +++ b/lib/rainbows/configurator.rb @@ -2,6 +2,23 @@ # This module adds \Rainbows! to the # {Unicorn::Configurator}[http://unicorn.bogomips.org/Unicorn/Configurator.html] +# \Rainbows!-specific configuration options must be inside a the Rainbows! +# block, otherwise Unicorn::Configurator directives may be used anwwhere +# in the file. +# +# Rainbows! do +# use :ThreadSpawn # concurrency model to use +# worker_connections 400 +# keepalive_timeout 0 # zero disables keepalives entirely +# client_max_body_size 5*1024*1024 # 5 megabytes +# keepalive_requests 666 # default:100 +# client_header_buffer_size 2 * 1024 # 2 kilobytes +# end +# +# # the rest of the Unicorn configuration... +# worker_processes 8 +# stderr_path "/path/to/error.log" +# stdout_path "/path/to/output.log" module Rainbows::Configurator Unicorn::Configurator::DEFAULTS.merge!({ :use => Rainbows::Base, @@ -12,45 +29,12 @@ module Rainbows::Configurator :client_header_buffer_size => 1024, }) - # configures \Rainbows! with a given concurrency model to +use+ and - # a +worker_connections+ upper-bound. This method may be called - # inside a Unicorn/\Rainbows! configuration file: + # Configures \Rainbows! with a given concurrency model to +use+ and + # a +worker_connections+ upper-bound. This method should be called + # inside a Unicorn/\Rainbows! configuration file. # - # Rainbows! do - # use :ThreadSpawn # concurrency model to use - # worker_connections 400 - # keepalive_timeout 0 # zero disables keepalives entirely - # client_max_body_size 5*1024*1024 # 5 megabytes - # keepalive_requests 666 # default:100 - # client_header_buffer_size 16 * 1024 # 16 kilobytes - # end - # - # # the rest of the Unicorn configuration - # worker_processes 8 - # - # See the documentation for the respective Revactor, ThreadSpawn, - # and ThreadPool classes for descriptions and recommendations for - # each of them. The total number of clients we're able to serve is - # +worker_processes+ * +worker_connections+, so in the above example - # we can serve 8 * 400 = 3200 clients concurrently. - # - # The default is +keepalive_timeout+ is 5 seconds, which should be - # enough under most conditions for browsers to render the page and - # start retrieving extra elements for. Increasing this beyond 5 - # seconds is not recommended. Zero disables keepalive entirely - # (but pipelining fully-formed requests is still works). - # - # The default +client_max_body_size+ is 1 megabyte (1024 * 1024 bytes), - # setting this to +nil+ will disable body size checks and allow any - # size to be specified. - # - # The default +keepalive_requests+ is 100, meaning a client may - # complete 100 keepalive requests after the initial request before - # \Rainbows! forces a disconnect. Lowering this can improve - # load-balancing characteristics as it forces HTTP/1.1 clients to - # reconnect after the specified number of requests, hopefully to a - # less busy host or worker process. This may also be used to mitigate - # denial-of-service attacks that use HTTP pipelining. + # All other methods in Rainbows::Configurator must be called + # inside this block. def Rainbows!(&block) block_given? or raise ArgumentError, "Rainbows! requires a block" @block = true @@ -63,11 +47,31 @@ module Rainbows::Configurator @block or abort "must be inside a Rainbows! block" end - def worker_connections(nr) + # This limits the number of connected clients per-process. The total + # number of clients on a server is +worker_processes+ * +worker_connections+. + # + # This option has no effect with the Base concurrency model, which is + # limited to +1+. + # + # Default: 50 + def worker_connections(clients) check! - set_int(:worker_connections, nr, 1) + set_int(:worker_connections, clients, 1) end + # Select a concurrency model for use with \Rainbows!. You must select + # this with a Symbol (prefixed with ":"). Thus if you wish to select + # the Rainbows::ThreadSpawn concurrency model, you would use: + # + # Rainbows! do + # use :ThreadSpawn + # end + # + # See the {Summary}[link:Summary.html] document for a summary of + # supported concurrency models. +options+ may be specified for some + # concurrency models, but the majority do not support them. + # + # Default: :Base (no concurrency) def use(model, *options) check! mod = begin @@ -92,11 +96,26 @@ module Rainbows::Configurator set[:use] = mod end + # Sets the value (in seconds) the server will wait for a client in + # between requests. The default value should be enough under most + # conditions for browsers to render the page and start retrieving + # extra elements. + # + # Setting this value to +0+ disables keepalive entirely + # + # Default: 5 seconds def keepalive_timeout(seconds) check! set_int(:keepalive_timeout, seconds, 0) end + # This limits the number of requests which can be made over a keep-alive + # connection. This is used to prevent single client from monopolizing + # the server and to improve fairness when load-balancing across multiple + # machines by forcing a client to reconnect. This may be helpful + # in mitigating some denial-of-service attacks. + # + # Default: 100 requests def keepalive_requests(count) check! case count @@ -107,6 +126,13 @@ module Rainbows::Configurator end end + # Limits the maximum size of a request body for all requests. + # Setting this to +nil+ disables the maximum size check. + # + # Default: 1 megabyte (1048576 bytes) + # + # If you want endpoint-specific upload limits and use a + # "rack.input"-streaming concurrency model, see the Rainbows::MaxBody def client_max_body_size(bytes) check! err = "client_max_body_size must be nil or a non-negative Integer" @@ -120,6 +146,17 @@ module Rainbows::Configurator set[:client_max_body_size] = bytes end + # This governs the amount of memory allocated for an individual read(2) or + # recv(2) system call when reading headers. Applications that make minimal + # use of cookies should not increase this from the default. + # + # Rails applications using session cookies may want to increase this to + # 2048 bytes or more depending on expected request sizes. + # + # Increasing this will increase overall memory usage to your application, + # as you will need at least this amount of memory for every connected client. + # + # Default: 1024 bytes def client_header_buffer_size(bytes) check! set_int(:client_header_buffer_size, bytes, 1) -- cgit v1.2.3-24-ge0c7