1Perlbal::Manual::InternUaslesr(3C)ontributed Perl DocumePnetraltbiaoln::Manual::Internals(3)
2
6 Perlbal::Manual::Internals - Perlbal's architecture at a glance
7 VERSION
9 Perlbal 1.78.
10 DESCRIPTION
12 Connections come in from wherever and get to the TCPListener. It uses
13 Service objects to determine what kind of Client* to spawn. The Client
14 classes then handle crafting the response for the user.
15 {{ INTERNET }}
17 |
18 v
19 [Service]<===>[TCPListener]
20 ___/ | \___
21 v v v
22 [ClientManage] [ClientHTTP] [ClientProxy]
23 ^
24 |
25 v
26 [BackendHTTP]
27 Perlbal decides what backend to send a request to randomly (only
29 presently supported method). If that service has idle backend
30 connections available, configured by "backend_persist" and
31 "connect_ahead", it will reuse those connections and greatly reduce
32 latency. See more detail in Perlbal::Manual::LoadBalancer.
33 Perlbal also specializes in "spoonfeeding" data to slow clients. This
35 allows backends to continue serving requests while Perlbal transfers
36 responses back as fast as the client can read.
37 Classes
39 The following is a brief introduction/overview to the main Perlbal's
40 classes:
41 Perlbal::Socket
43 Descends from Danga::Socket.
45 Adds on to the base class to provide some functionality specifically
47 useful for creating HTTP sockets.
48 Fields
50 headers_string
52 Headers as they're being read.
53 req_headers
55 The final Perlbal::HTTPHeaders object inbound.
56 res_headers
58 Response headers outbound (Perlbal::HTTPHeaders object).
59 create_time
61 Creation time.
62 alive_time
64 Last time noted alive.
65 state
67 General purpose state; used by descendants.
68 do_die
70 If on, die and do no further requests.
71 read_buf
73 Arrayref of scalarref read from client.
74 read_ahead
76 Bytes sitting in read_buf.
77 read_size
79 Total bytes read from client, ever.
80 ditch_leading_rn
82 If true, the next header parsing will ignore a leading \r\n.
83 observed_ip_string
85 If defined, contains the observed IP string of the peer we're
86 serving. This is intended for holding the value of the X-Forwarded-
87 For and using it to govern ACLs.
88 Perlbal::TCPListener
90 Descends from Perlbal::Socket.
92 Very lightweight and fast connection accept class. Takes incoming
94 connections as fast as possible and passes them off, instantiating one
95 of the various Client* classes to handle it.
96 Fields
98 service
100 Perlbal::Service.
101 hostport
103 Scalar IP port of where this service is listening for new
104 connections.
105 sslopts
107 The SSL Options.
108 use Data::Dumper;
110 warn Dumper( $tcp_listener->{'sslopts'} );
111 The above lines would print something like the following:
113 $VAR1 = {
115 'ssl' => {
116 'SSL_cipher_list' => '...',
117 'SSL_cert_file' => '...',
118 'SSL_key_file' => ',,,',
119 'SSL_ca_path' => '...',
120 'SSL_verify_mode' => '...'
121 }
122 };
123 v6 Boolean value stating whether the installation of Perlbal supports
125 IPv6 (which basically boils down to Danga::Socket v1.6.1 and
126 IO::Socket::INET6 being available).
127 Perlbal::BackendHTTP
129 Descends from Perlbal::Socket.
131 This class handles connections to the backend web nodes for getting
133 data back to the user. This class is used by other classes such as
134 Perlbal::ClientProxy to send a request to an internal node.
135 Fields
137 client
139 Perlbal::ClientProxy connection, or undef.
140 service
142 Perlbal::Service.
143 pool
145 Perlbal::Pool; whatever pool we spawned from.
146 ip IP scalar.
148 port
150 Port scalar.
151 ipport
153 "$ip:$port".
154 reportto
156 Object; must implement reporter interface.
157 has_attention
159 Has been accepted by a webserver and we know for sure we're not
160 just talking to the TCP stack.
161 waiting_options
163 If true, we're waiting for an OPTIONS * response to determine when
164 we have attention.
165 disconnect_at
167 Time this connection will be disconnected, if it's kept-alive and
168 backend told us; otherwise "undef" for unknown.
169 content_length
171 Length of document being transferred. Only applies when the backend
172 server sends a content-length header.
173 content_length_remain
175 Bytes remaining to be read. Only applies when the backend server
176 sends a content-length header.
177 use_count
179 Number of requests this backend's been used for.
180 generation
182 Int; counts what generation we were spawned in.
183 buffered_upload_mode
185 Boolean. If on, we're doing a buffered upload transmit.
186 scratch
188 Extra storage; plugins can use it if they want.
189 Perlbal::HTTPHeaders
191 Header management. Parses headers (request and response) and stores
193 data for further user. Also manages validation of the request line so
194 that it conforms to HTTP specifications.
195 Fields
197 headers
199 href; lowercase header -> comma-sep list of values.
200 origcase
202 Href; lowercase header -> provided case.
203 hdorder
205 Aref; order headers were received (canonical order).
206 method
208 Scalar; request method (if GET request).
209 uri Scalar; request URI (if GET request).
211 type
213 "res" or "req".
214 code
216 HTTP response status code.
217 codetext
219 Status text that for response code.
220 ver Version (string) "1.1".
222 vernum
224 Version (number: major*1000+minor): "1.1" => 1001.
225 responseLine
227 First line of HTTP response (if response).
228 requestLine
230 First line of HTTP request (if request).
231 Perlbal::ClientHTTPBase
233 Descends from Perlbal::Socket.
235 Provides base functionality to Perlbal::ClientHTTP and
237 Perlbal::ClientProxy. Notably, the ability to efficiently send files to
238 the remote user. Also handles most of the state logic for statistics
239 and such. Is also used for services of type "selector".
240 Perlbal::ClientHTTPBase then reads in the request headers, and asks the
241 service to re-bless the client instance to a more specific type, for
242 either a Perlbal::ClientProxy or Perlbal::ClientHTTP (depending on
243 selector's mapping).
244 Fields
246 service
248 Perlbal::Service object.
249 replacement_uri
251 URI to send instead of the one requested; this is used to instruct
252 "_serve_request" to send an index file instead of trying to serve a
253 directory and failing.
254 scratch
256 Extra storage; plugins can use it if they want.
257 reproxy_file
259 Filename the backend told us to start opening.
260 reproxy_file_size
262 Size of file, once we "stat()" it.
263 reproxy_fh
265 If needed, IO::Handle of fd.
266 reproxy_file_offset
268 How much we've sent from the file.
269 post_sendfile_cb
271 Subref to run after we're done sendfile'ing the current file.
272 requests
274 Number of requests this object has performed for the user.
275 selector_svc
277 The original service from which we came.
278 is_ssl
280 Whether the socket was SSL attached (restricted operations).
281 Perlbal::ClientHTTP
283 Descends from Perlbal::ClientHTTPBase.
285 Very simple and lightweight class. Handles sending files to the user
287 without much overhead. Most of the functionality is contained in the
288 parent class, and this class doesn't implement much new stuff.
289 Fields
291 put_in_progress
293 1 when we're currently waiting for an async job to return.
294 put_fh
296 File handle to use for writing data.
297 put_fh_filename
299 Filename of put_fh.
300 put_pos
302 File offset to write next data at.
303 content_length
305 Length of document being transferred.
306 content_length_remain
308 Bytes remaining to be read.
309 chunked_upload_state
311 Boolean/obj: if processing a chunked upload,
312 Perlbal::ChunkedUploadState object, else undef.
313 Perlbal::ClientProxy
315 Descends from Perlbal::ClientHTTPBase.
317 Takes an incoming connection from a user and connects to a backend node
319 ("Perlbal::BackendHTTP") and relays the request. The backend can then
320 either tell the proxy to reproxy and load a file from disk, or return a
321 file directly, or just return a status message.
322 Fields
324 backend
326 Perlbal::BackendHTTP object (or "undef" if disconnected).
327 backend_requested
329 True if we've requested a backend for this request.
330 reconnect_count
332 Number of times we've tried to reconnect to backend.
333 high_priority
335 Boolean; 1 if we are or were in the high priority queue.
336 low_priority
338 Boolean; 1 if we are or were in the low priority queue.
339 reproxy_uris
341 Arrayref; URIs to reproxy to, in order.
342 reproxy_expected_size
344 Int: size of response we expect to get back for reproxy.
345 currently_reproxying
347 Arrayref; the host info and URI we're reproxying right now.
348 content_length_remain
350 Int: amount of data we're still waiting for.
351 responded
353 Bool: whether we've already sent a response to the user or not.
354 last_request_time
356 Int: time that we last received a request.
357 primary_res_hdrs
359 If defined, we are doing a transparent reproxy-URI and the headers
360 we get back aren't necessarily the ones we want. Instead, get most
361 headers from the provided "res" headers object here.
362 is_buffering
364 Bool; if we're buffering some/all of a request to memory/disk.
365 is_writing
367 Bool; if on, we currently have an "aio_write" out.
368 start_time
370 Hi-res time when we started getting data to upload.
371 bufh
373 Buffered upload filehandle object.
374 bufilename
376 String; buffered upload filename.
377 bureason
379 String; if defined, the reason we're buffering to disk.
380 buoutpos
382 Int; buffered output position.
383 backend_stalled
385 Boolean: if backend has shut off its reads because we're too slow.
386 unread_data_waiting
388 Boolean: if we shut off reads while we know data is yet to be read
389 from client.
390 chunked_upload_state
392 Bool/obj: if processing a chunked upload,
393 Perlbal::ChunkedUploadState object, else undef.
394 request_body_length
396 Integer: request's body length, either as-declared, or calculated
397 after chunked upload is complete.
398 last_upload_packet
400 Unixtime we last sent a UDP upload packet. For perlbal sending out
401 UDP packets related to upload status (for xmlhttprequest upload
402 bar).
403 upload_session
405 Client's self-generated upload session. For perlbal sending out UDP
406 packets related to upload status (for xmlhttprequest upload bar).
407 retry_count
409 Number of times we've retried this request so far after getting 500
410 errors.
411 Perlbal::ClientManage
413 Descends from Perlbal::Socket.
415 Simple interface that provides a way for users to use the management
417 interface of Perlbal. You can connect to the management port (as
418 defined in the config file) with a web browser or regular telnet (see
419 Perlbal::Manual::Management for more information on this).
420 Fields
422 service
424 Perlbal::Service.
425 buf Read buffer.
427 is_http
429 Boolean stating whether the request is HTTP.
430 ctx Perlbal::CommandContext.
432 Perlbal::Service
434 A service is a particular item that Perlbal is doing. Services can have
436 a role which defines how they behave. Each service can also have a
437 bunch of parameters set to further adjust its behavior. By itself, the
438 Service class handles maintaining pools of backend connections and
439 managing statistics about itself.
440 Fields
442 name
444 Name of the service.
445 role
447 Role type ("web_server", "reverse_proxy", etc).
448 enabled
450 Boolean; whether we're enabled or not (enabled = listening).
451 pool
453 Perlbal::Pool that we're using to allocate nodes if we're in proxy
454 mode.
455 listener
457 Perlbal::TCPListener object, when enabled.
458 reproxy_cache
460 Perlbal::Cache object, when enabled.
461 End-user tunables
463 listen
465 "IP:port" of where we're listening for new connections.
466 docroot
468 Document root for "web_server" role.
469 dirindexing
471 Boolean; directory indexing (for "web_server" role). Not async.
472 index_files
474 Arrayref of filenames to try for index files.
475 enable_concatenate_get
477 Boolean; if user can request concatenated files.
478 enable_put
480 Boolean; whether PUT is supported.
481 max_put_size
483 Max size in bytes of a put file.
484 max_chunked_request_size
486 Max size in bytes of a chunked request (to be written to disk
487 first).
488 min_put_directory
490 Number of directories required to exist at beginning of URIs in
491 put.
492 enable_delete
494 Boolean; whether DELETE is supported.
495 high_priority_cookie
497 Cookie name to check if the client's requests should be considered
498 high priority.
499 See also "high_priority_cookie_contents".
501 high_priority_cookie_contents
503 Aforementioned cookie value must contain this substring.
504 backend_persist_cache
506 Max number of persistent backends to hold onto while no clients.
507 persist_client
509 Boolean; persistent connections for clients.
510 persist_backend
512 Boolean; persistent connections for backends.
513 verify_backend
515 Boolean; get attention of backend before giving it clients (using
516 OPTIONS).
517 verify_backend_path
519 Path to check with the OPTIONS request (default is "*").
520 max_backend_uses
522 Max requests to send per kept-alive backend (default 0 =
523 unlimited).
524 connect_ahead
526 Number of spare backends to connect to in advance all the time.
527 buffer_size
529 How much data a Perlbal::ClientProxy object should buffer from a
530 backend.
531 buffer_size_reproxy_url
533 Same as above but for backends that are reproxying for us.
534 queue_relief_size
536 Number of outstanding standard priority connections to activate
537 pressure relief at.
538 queue_relief_chance
540 Int, 0-100; % chance to take a standard priority request when we're
541 in pressure relief mode.
542 trusted_upstream_proxies
544 Array of Net::Netmask objects containing netmasks for trusted
545 upstreams.
546 always_trusted
548 Boolean; if true, always trust upstreams.
549 blind_proxy
551 Boolean; if true, do not modify "X-Forwarded-For", "X-Host", or
552 "X-Forwarded-Host" headers.
553 enable_reproxy
555 Boolean; if true, advertise that server will reproxy files and/or
556 URLs.
557 reproxy_cache_maxsize
559 Maximum number of reproxy results to be cached. (0 is disabled and
560 default).
561 client_sndbuf_size
563 Bytes for "SO_SNDBUF".
564 server_process
566 Path to server process (executable).
567 persist_client_idle_timeout
569 Keep-alive timeout in seconds for clients (default is 30).
570 idle_timeout
572 Idle timeout outside of keep-alive time (default is 30).
573 Internal state
575 waiting_clients
577 Arrayref of clients waiting for backendhttp connections.
578 waiting_clients_highpri
580 Arrayref of high-priority clients waiting for backendhttp
581 connections.
582 waiting_clients_lowpri
584 Arrayref of low-priority clients waiting for backendhttp
585 connections.
586 waiting_client_count
588 Number of clients waiting for backends.
589 waiting_client_map
591 Map of clientproxy fd -> 1 (if they're waiting for a connection).
592 pending_connects
594 Hashref of "ip:port" -> $time (only one pending connect to backend
595 at a time).
596 pending_connect_count
598 Number of outstanding backend connects.
599 bored_backends
601 Arrayref of backends we've already connected to, but haven't got
602 clients.
603 hooks
605 Hashref: hookname => [ [ plugin, ref ], [ plugin, ref ], ... ].
606 plugins
608 Hashref: name => 1.
609 plugin_order
611 Arrayref: name, name, name...
612 plugin_setters
614 Hashref: { plugin_name => { key_name => coderef } }.
615 extra_config
617 Hashref with extra config options; name => values.
618 spawn_lock
620 Boolean; if true, we're currently in "spawn_backends".
621 extra_headers
623 { insert => [ [ header, value ], ... ], remove => [ header, header,
624 ... ], set => [ [ header, value ], ... ] }.
625 Used in header management interface.
627 generation
629 Int; generation count so we can slough off backends from old pools.
630 backend_no_spawn
632 { "ip:port" => 1 }.
633 If on, "spawn_backends" will ignore this "ip:port" combo.
635 buffer_backend_connect
637 0 if off; otherwise, number of bytes to buffer before we ask for a
638 backend.
639 selector
641 CODE ref, or undef, for role "selector" services.
642 default_service
644 Name of a service a selector should default to.
645 buffer_uploads
647 Boolean; enable/disable the buffered uploads to disk system.
648 buffer_uploads_path
650 Path to store buffered upload files.
651 buffer_upload_threshold_time
653 Int; buffer uploads estimated to take longer than this.
654 buffer_upload_threshold_size
656 Int; buffer uploads greater than this size (in bytes).
657 buffer_upload_threshold_rate
659 Int; buffer uploads uploading at less than this rate (in
660 bytes/sec).
661 upload_status_listeners
663 Comma separated list of "ip:port" of UDP upload status receivers.
664 upload_status_listeners_sockaddr
666 Arrayref of sockaddrs (packed ip/port).
667 enable_ssl
669 Boolean; whether this service speaks SSL to the client.
670 ssl_key_file
672 File path to key pem file.
673 ssl_cert_file
675 File to path to cert pem file.
676 ssl_cipher_list
678 OpenSSL cipher list string.
679 ssl_ca_path
681 Path to certificates directory.
682 ssl_verify_mode
684 Int; verification mode, see IO::Socket::SSL.
685 enable_error_retries
687 Boolean; whether we should retry requests after errors.
688 error_retry_schedule
690 Comma-separated seconds (full or partial) to delay between retries.
691 latency
693 Milliseconds of latency to add to request.
694 server_tokens
696 Boolean; whether to provide a "Server" header.
697 _stat_requests
699 Total requests to this service.
700 _stat_cache_hits
702 Total requests to this service that were served via the reproxy-url
703 cache.
704perl v5.36.0 2022-07-20 Perlbal::Manual::Internals(3)