Provided by: libperlbal-perl_1.80-4_all bug

NAME

       Perlbal::Manual::Internals - Perlbal's architecture at a glance

   VERSION
       Perlbal 1.78.

   DESCRIPTION
       Connections come in from wherever and get to the TCPListener. It uses Service objects to
       determine what kind of Client* to spawn. The Client classes then handle crafting the
       response for the user.

                                   {{ INTERNET }}
                                         |
                                         v
                     [Service]<===>[TCPListener]
                                 ___/    |    \___
                                v        v        v
                    [ClientManage]  [ClientHTTP] [ClientProxy]
                                                       ^
                                                       |
                                                       v
                                                 [BackendHTTP]

       Perlbal decides what backend to send a request to randomly (only presently supported
       method). If that service has idle backend connections available, configured by
       "backend_persist" and "connect_ahead", it will reuse those connections and greatly reduce
       latency. See more detail in Perlbal::Manual::LoadBalancer.

       Perlbal also specializes in "spoonfeeding" data to slow clients. This allows backends to
       continue serving requests while Perlbal transfers responses back as fast as the client can
       read.

   Classes
       The following is a brief introduction/overview to the main Perlbal's classes:

       Perlbal::Socket

       Descends from Danga::Socket.

       Adds on to the base class to provide some functionality specifically useful for creating
       HTTP sockets.

       Fields

       headers_string
           Headers as they're being read.

       req_headers
           The final Perlbal::HTTPHeaders object inbound.

       res_headers
           Response headers outbound (Perlbal::HTTPHeaders object).

       create_time
           Creation time.

       alive_time
           Last time noted alive.

       state
           General purpose state; used by descendants.

       do_die
           If on, die and do no further requests.

       read_buf
           Arrayref of scalarref read from client.

       read_ahead
           Bytes sitting in read_buf.

       read_size
           Total bytes read from client, ever.

       ditch_leading_rn
           If true, the next header parsing will ignore a leading \r\n.

       observed_ip_string
           If defined, contains the observed IP string of the peer we're serving. This is
           intended for holding the value of the X-Forwarded-For and using it to govern ACLs.

       Perlbal::TCPListener

       Descends from Perlbal::Socket.

       Very lightweight and fast connection accept class. Takes incoming connections as fast as
       possible and passes them off, instantiating one of the various Client* classes to handle
       it.

       Fields

       service
           Perlbal::Service.

       hostport
           Scalar IP port of where this service is listening for new connections.

       sslopts
           The SSL Options.

               use Data::Dumper;
               warn Dumper( $tcp_listener->{'sslopts'} );

           The above lines would print something like the following:

               $VAR1 = {
                         'ssl' => {
                                    'SSL_cipher_list' => '...',
                                    'SSL_cert_file' => '...',
                                    'SSL_key_file' => ',,,',
                                    'SSL_ca_path' => '...',
                                    'SSL_verify_mode' => '...'
                                  }
                       };

       v6  Boolean value stating whether the installation of Perlbal supports IPv6 (which
           basically boils down to Danga::Socket v1.6.1 and IO::Socket::INET6 being available).

       Perlbal::BackendHTTP

       Descends from Perlbal::Socket.

       This class handles connections to the backend web nodes for getting data back to the user.
       This class is used by other classes such as Perlbal::ClientProxy to send a request to an
       internal node.

       Fields

       client
           Perlbal::ClientProxy connection, or undef.

       service
           Perlbal::Service.

       pool
           Perlbal::Pool; whatever pool we spawned from.

       ip  IP scalar.

       port
           Port scalar.

       ipport
           "$ip:$port".

       reportto
           Object; must implement reporter interface.

       has_attention
           Has been accepted by a webserver and we know for sure we're not just talking to the
           TCP stack.

       waiting_options
           If true, we're waiting for an OPTIONS * response to determine when we have attention.

       disconnect_at
           Time this connection will be disconnected, if it's kept-alive and backend told us;
           otherwise "undef" for unknown.

       content_length
           Length of document being transferred. Only applies when the backend server sends a
           content-length header.

       content_length_remain
           Bytes remaining to be read. Only applies when the backend server sends a content-
           length header.

       use_count
           Number of requests this backend's been used for.

       generation
           Int; counts what generation we were spawned in.

       buffered_upload_mode
           Boolean. If on, we're doing a buffered upload transmit.

       scratch
           Extra storage; plugins can use it if they want.

       Perlbal::HTTPHeaders

       Header management. Parses headers (request and response) and stores data for further user.
       Also manages validation of the request line so that it conforms to HTTP specifications.

       Fields

       headers
           href; lowercase header -> comma-sep list of values.

       origcase
           Href; lowercase header -> provided case.

       hdorder
           Aref; order headers were received (canonical order).

       method
           Scalar; request method (if GET request).

       uri Scalar; request URI (if GET request).

       type
           "res" or "req".

       code
           HTTP response status code.

       codetext
           Status text that for response code.

       ver Version (string) "1.1".

       vernum
           Version (number: major*1000+minor): "1.1" => 1001.

       responseLine
           First line of HTTP response (if response).

       requestLine
           First line of HTTP request (if request).

       Perlbal::ClientHTTPBase

       Descends from Perlbal::Socket.

       Provides base functionality to Perlbal::ClientHTTP and Perlbal::ClientProxy. Notably, the
       ability to efficiently send files to the remote user. Also handles most of the state logic
       for statistics and such. Is also used for services of type "selector".
       Perlbal::ClientHTTPBase then reads in the request headers, and asks the service to re-
       bless the client instance to a more specific type, for either a Perlbal::ClientProxy or
       Perlbal::ClientHTTP (depending on selector's mapping).

       Fields

       service
           Perlbal::Service object.

       replacement_uri
           URI to send instead of the one requested; this is used to instruct "_serve_request" to
           send an index file instead of trying to serve a directory and failing.

       scratch
           Extra storage; plugins can use it if they want.

       reproxy_file
           Filename the backend told us to start opening.

       reproxy_file_size
           Size of file, once we "stat()" it.

       reproxy_fh
           If needed, IO::Handle of fd.

       reproxy_file_offset
           How much we've sent from the file.

       post_sendfile_cb
           Subref to run after we're done sendfile'ing the current file.

       requests
           Number of requests this object has performed for the user.

       selector_svc
           The original service from which we came.

       is_ssl
           Whether the socket was SSL attached (restricted operations).

       Perlbal::ClientHTTP

       Descends from Perlbal::ClientHTTPBase.

       Very simple and lightweight class. Handles sending files to the user without much
       overhead. Most of the functionality is contained in the parent class, and this class
       doesn't implement much new stuff.

       Fields

       put_in_progress
           1 when we're currently waiting for an async job to return.

       put_fh
           File handle to use for writing data.

       put_fh_filename
           Filename of put_fh.

       put_pos
           File offset to write next data at.

       content_length
           Length of document being transferred.

       content_length_remain
           Bytes remaining to be read.

       chunked_upload_state
           Boolean/obj: if processing a chunked upload, Perlbal::ChunkedUploadState object, else
           undef.

       Perlbal::ClientProxy

       Descends from Perlbal::ClientHTTPBase.

       Takes an incoming connection from a user and connects to a backend node
       ("Perlbal::BackendHTTP") and relays the request. The backend can then either tell the
       proxy to reproxy and load a file from disk, or return a file directly, or just return a
       status message.

       Fields

       backend
           Perlbal::BackendHTTP object (or "undef" if disconnected).

       backend_requested
           True if we've requested a backend for this request.

       reconnect_count
           Number of times we've tried to reconnect to backend.

       high_priority
           Boolean; 1 if we are or were in the high priority queue.

       low_priority
           Boolean; 1 if we are or were in the low priority queue.

       reproxy_uris
           Arrayref; URIs to reproxy to, in order.

       reproxy_expected_size
           Int: size of response we expect to get back for reproxy.

       currently_reproxying
           Arrayref; the host info and URI we're reproxying right now.

       content_length_remain
           Int: amount of data we're still waiting for.

       responded
           Bool: whether we've already sent a response to the user or not.

       last_request_time
           Int: time that we last received a request.

       primary_res_hdrs
           If defined, we are doing a transparent reproxy-URI and the headers we get back aren't
           necessarily the ones we want. Instead, get most headers from the provided "res"
           headers object here.

       is_buffering
           Bool; if we're buffering some/all of a request to memory/disk.

       is_writing
           Bool; if on, we currently have an "aio_write" out.

       start_time
           Hi-res time when we started getting data to upload.

       bufh
           Buffered upload filehandle object.

       bufilename
           String; buffered upload filename.

       bureason
           String; if defined, the reason we're buffering to disk.

       buoutpos
           Int; buffered output position.

       backend_stalled
           Boolean: if backend has shut off its reads because we're too slow.

       unread_data_waiting
           Boolean: if we shut off reads while we know data is yet to be read from client.

       chunked_upload_state
           Bool/obj: if processing a chunked upload, Perlbal::ChunkedUploadState object, else
           undef.

       request_body_length
           Integer: request's body length, either as-declared, or calculated after chunked upload
           is complete.

       last_upload_packet
           Unixtime we last sent a UDP upload packet. For perlbal sending out UDP packets related
           to upload status (for xmlhttprequest upload bar).

       upload_session
           Client's self-generated upload session. For perlbal sending out UDP packets related to
           upload status (for xmlhttprequest upload bar).

       retry_count
           Number of times we've retried this request so far after getting 500 errors.

       Perlbal::ClientManage

       Descends from Perlbal::Socket.

       Simple interface that provides a way for users to use the management interface of Perlbal.
       You can connect to the management port (as defined in the config file) with a web browser
       or regular telnet (see Perlbal::Manual::Management for more information on this).

       Fields

       service
           Perlbal::Service.

       buf Read buffer.

       is_http
           Boolean stating whether the request is HTTP.

       ctx Perlbal::CommandContext.

       Perlbal::Service

       A service is a particular item that Perlbal is doing. Services can have a role which
       defines how they behave. Each service can also have a bunch of parameters set to further
       adjust its behavior. By itself, the Service class handles maintaining pools of backend
       connections and managing statistics about itself.

       Fields

       name
           Name of the service.

       role
           Role type ("web_server", "reverse_proxy", etc).

       enabled
           Boolean; whether we're enabled or not (enabled = listening).

       pool
           Perlbal::Pool that we're using to allocate nodes if we're in proxy mode.

       listener
           Perlbal::TCPListener object, when enabled.

       reproxy_cache
           Perlbal::Cache object, when enabled.

       End-user tunables

       listen
           "IP:port" of where we're listening for new connections.

       docroot
           Document root for "web_server" role.

       dirindexing
           Boolean; directory indexing (for "web_server" role). Not async.

       index_files
           Arrayref of filenames to try for index files.

       enable_concatenate_get
           Boolean; if user can request concatenated files.

       enable_put
           Boolean; whether PUT is supported.

       max_put_size
           Max size in bytes of a put file.

       max_chunked_request_size
           Max size in bytes of a chunked request (to be written to disk first).

       min_put_directory
           Number of directories required to exist at beginning of URIs in put.

       enable_delete
           Boolean; whether DELETE is supported.

       high_priority_cookie
           Cookie name to check if the client's requests should be considered high priority.

           See also "high_priority_cookie_contents".

       high_priority_cookie_contents
           Aforementioned cookie value must contain this substring.

       backend_persist_cache
           Max number of persistent backends to hold onto while no clients.

       persist_client
           Boolean; persistent connections for clients.

       persist_backend
           Boolean; persistent connections for backends.

       verify_backend
           Boolean; get attention of backend before giving it clients (using OPTIONS).

       verify_backend_path
           Path to check with the OPTIONS request (default is "*").

       max_backend_uses
           Max requests to send per kept-alive backend (default 0 = unlimited).

       connect_ahead
           Number of spare backends to connect to in advance all the time.

       buffer_size
           How much data a Perlbal::ClientProxy object should buffer from a backend.

       buffer_size_reproxy_url
           Same as above but for backends that are reproxying for us.

       queue_relief_size
           Number of outstanding standard priority connections to activate pressure relief at.

       queue_relief_chance
           Int, 0-100; % chance to take a standard priority request when we're in pressure relief
           mode.

       trusted_upstream_proxies
           Array of Net::Netmask objects containing netmasks for trusted upstreams.

       always_trusted
           Boolean; if true, always trust upstreams.

       blind_proxy
           Boolean; if true, do not modify "X-Forwarded-For", "X-Host", or "X-Forwarded-Host"
           headers.

       enable_reproxy
           Boolean; if true, advertise that server will reproxy files and/or URLs.

       reproxy_cache_maxsize
           Maximum number of reproxy results to be cached. (0 is disabled and default).

       client_sndbuf_size
           Bytes for "SO_SNDBUF".

       server_process
           Path to server process (executable).

       persist_client_idle_timeout
           Keep-alive timeout in seconds for clients (default is 30).

       idle_timeout
           Idle timeout outside of keep-alive time (default is 30).

       Internal state

       waiting_clients
           Arrayref of clients waiting for backendhttp connections.

       waiting_clients_highpri
           Arrayref of high-priority clients waiting for backendhttp connections.

       waiting_clients_lowpri
           Arrayref of low-priority clients waiting for backendhttp connections.

       waiting_client_count
           Number of clients waiting for backends.

       waiting_client_map
           Map of clientproxy fd -> 1 (if they're waiting for a connection).

       pending_connects
           Hashref of "ip:port" -> $time (only one pending connect to backend at a time).

       pending_connect_count
           Number of outstanding backend connects.

       bored_backends
           Arrayref of backends we've already connected to, but haven't got clients.

       hooks
           Hashref: hookname => [ [ plugin, ref ], [ plugin, ref ], ... ].

       plugins
           Hashref: name => 1.

       plugin_order
           Arrayref: name, name, name...

       plugin_setters
           Hashref: { plugin_name => { key_name => coderef } }.

       extra_config
           Hashref with extra config options; name => values.

       spawn_lock
           Boolean; if true, we're currently in "spawn_backends".

       extra_headers
           { insert => [ [ header, value ], ... ], remove => [ header, header, ... ], set => [ [
           header, value ], ... ] }.

           Used in header management interface.

       generation
           Int; generation count so we can slough off backends from old pools.

       backend_no_spawn
           { "ip:port" => 1 }.

           If on, "spawn_backends" will ignore this "ip:port" combo.

       buffer_backend_connect
           0 if off; otherwise, number of bytes to buffer before we ask for a backend.

       selector
           CODE ref, or undef, for role "selector" services.

       default_service
           Name of a service a selector should default to.

       buffer_uploads
           Boolean; enable/disable the buffered uploads to disk system.

       buffer_uploads_path
           Path to store buffered upload files.

       buffer_upload_threshold_time
           Int; buffer uploads estimated to take longer than this.

       buffer_upload_threshold_size
           Int; buffer uploads greater than this size (in bytes).

       buffer_upload_threshold_rate
           Int; buffer uploads uploading at less than this rate (in bytes/sec).

       upload_status_listeners
           Comma separated list of "ip:port" of UDP upload status receivers.

       upload_status_listeners_sockaddr
           Arrayref of sockaddrs (packed ip/port).

       enable_ssl
           Boolean; whether this service speaks SSL to the client.

       ssl_key_file
           File path to key pem file.

       ssl_cert_file
           File to path to cert pem file.

       ssl_cipher_list
           OpenSSL cipher list string.

       ssl_ca_path
           Path to certificates directory.

       ssl_verify_mode
           Int; verification mode, see IO::Socket::SSL.

       enable_error_retries
           Boolean; whether we should retry requests after errors.

       error_retry_schedule
           Comma-separated seconds (full or partial) to delay between retries.

       latency
           Milliseconds of latency to add to request.

       server_tokens
           Boolean; whether to provide a "Server" header.

       _stat_requests
           Total requests to this service.

       _stat_cache_hits
           Total requests to this service that were served via the reproxy-url cache.