1Perlbal::Manual::InternUaslesr(3C)ontributed Perl DocumePnetraltbiaoln::Manual::Internals(3)
2
3
4

NAME

6       Perlbal::Manual::Internals - Perlbal's architecture at a glance
7
8   VERSION
9       Perlbal 1.78.
10
11   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
16                                   {{ INTERNET }}
17                                         |
18                                         v
19                     [Service]<===>[TCPListener]
20                                 ___/    |    \___
21                                v        v        v
22                    [ClientManage]  [ClientHTTP] [ClientProxy]
23                                                       ^
24                                                       |
25                                                       v
26                                                 [BackendHTTP]
27
28       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
34       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
38   Classes
39       The following is a brief introduction/overview to the main Perlbal's
40       classes:
41
42       Perlbal::Socket
43
44       Descends from Danga::Socket.
45
46       Adds on to the base class to provide some functionality specifically
47       useful for creating HTTP sockets.
48
49       Fields
50
51       headers_string
52           Headers as they're being read.
53
54       req_headers
55           The final Perlbal::HTTPHeaders object inbound.
56
57       res_headers
58           Response headers outbound (Perlbal::HTTPHeaders object).
59
60       create_time
61           Creation time.
62
63       alive_time
64           Last time noted alive.
65
66       state
67           General purpose state; used by descendants.
68
69       do_die
70           If on, die and do no further requests.
71
72       read_buf
73           Arrayref of scalarref read from client.
74
75       read_ahead
76           Bytes sitting in read_buf.
77
78       read_size
79           Total bytes read from client, ever.
80
81       ditch_leading_rn
82           If true, the next header parsing will ignore a leading \r\n.
83
84       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
89       Perlbal::TCPListener
90
91       Descends from Perlbal::Socket.
92
93       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
97       Fields
98
99       service
100           Perlbal::Service.
101
102       hostport
103           Scalar IP port of where this service is listening for new
104           connections.
105
106       sslopts
107           The SSL Options.
108
109               use Data::Dumper;
110               warn Dumper( $tcp_listener->{'sslopts'} );
111
112           The above lines would print something like the following:
113
114               $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
124       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
128       Perlbal::BackendHTTP
129
130       Descends from Perlbal::Socket.
131
132       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
136       Fields
137
138       client
139           Perlbal::ClientProxy connection, or undef.
140
141       service
142           Perlbal::Service.
143
144       pool
145           Perlbal::Pool; whatever pool we spawned from.
146
147       ip  IP scalar.
148
149       port
150           Port scalar.
151
152       ipport
153           "$ip:$port".
154
155       reportto
156           Object; must implement reporter interface.
157
158       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
162       waiting_options
163           If true, we're waiting for an OPTIONS * response to determine when
164           we have attention.
165
166       disconnect_at
167           Time this connection will be disconnected, if it's kept-alive and
168           backend told us; otherwise "undef" for unknown.
169
170       content_length
171           Length of document being transferred. Only applies when the backend
172           server sends a content-length header.
173
174       content_length_remain
175           Bytes remaining to be read. Only applies when the backend server
176           sends a content-length header.
177
178       use_count
179           Number of requests this backend's been used for.
180
181       generation
182           Int; counts what generation we were spawned in.
183
184       buffered_upload_mode
185           Boolean. If on, we're doing a buffered upload transmit.
186
187       scratch
188           Extra storage; plugins can use it if they want.
189
190       Perlbal::HTTPHeaders
191
192       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
196       Fields
197
198       headers
199           href; lowercase header -> comma-sep list of values.
200
201       origcase
202           Href; lowercase header -> provided case.
203
204       hdorder
205           Aref; order headers were received (canonical order).
206
207       method
208           Scalar; request method (if GET request).
209
210       uri Scalar; request URI (if GET request).
211
212       type
213           "res" or "req".
214
215       code
216           HTTP response status code.
217
218       codetext
219           Status text that for response code.
220
221       ver Version (string) "1.1".
222
223       vernum
224           Version (number: major*1000+minor): "1.1" => 1001.
225
226       responseLine
227           First line of HTTP response (if response).
228
229       requestLine
230           First line of HTTP request (if request).
231
232       Perlbal::ClientHTTPBase
233
234       Descends from Perlbal::Socket.
235
236       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
245       Fields
246
247       service
248           Perlbal::Service object.
249
250       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
255       scratch
256           Extra storage; plugins can use it if they want.
257
258       reproxy_file
259           Filename the backend told us to start opening.
260
261       reproxy_file_size
262           Size of file, once we "stat()" it.
263
264       reproxy_fh
265           If needed, IO::Handle of fd.
266
267       reproxy_file_offset
268           How much we've sent from the file.
269
270       post_sendfile_cb
271           Subref to run after we're done sendfile'ing the current file.
272
273       requests
274           Number of requests this object has performed for the user.
275
276       selector_svc
277           The original service from which we came.
278
279       is_ssl
280           Whether the socket was SSL attached (restricted operations).
281
282       Perlbal::ClientHTTP
283
284       Descends from Perlbal::ClientHTTPBase.
285
286       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
290       Fields
291
292       put_in_progress
293           1 when we're currently waiting for an async job to return.
294
295       put_fh
296           File handle to use for writing data.
297
298       put_fh_filename
299           Filename of put_fh.
300
301       put_pos
302           File offset to write next data at.
303
304       content_length
305           Length of document being transferred.
306
307       content_length_remain
308           Bytes remaining to be read.
309
310       chunked_upload_state
311           Boolean/obj: if processing a chunked upload,
312           Perlbal::ChunkedUploadState object, else undef.
313
314       Perlbal::ClientProxy
315
316       Descends from Perlbal::ClientHTTPBase.
317
318       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
323       Fields
324
325       backend
326           Perlbal::BackendHTTP object (or "undef" if disconnected).
327
328       backend_requested
329           True if we've requested a backend for this request.
330
331       reconnect_count
332           Number of times we've tried to reconnect to backend.
333
334       high_priority
335           Boolean; 1 if we are or were in the high priority queue.
336
337       low_priority
338           Boolean; 1 if we are or were in the low priority queue.
339
340       reproxy_uris
341           Arrayref; URIs to reproxy to, in order.
342
343       reproxy_expected_size
344           Int: size of response we expect to get back for reproxy.
345
346       currently_reproxying
347           Arrayref; the host info and URI we're reproxying right now.
348
349       content_length_remain
350           Int: amount of data we're still waiting for.
351
352       responded
353           Bool: whether we've already sent a response to the user or not.
354
355       last_request_time
356           Int: time that we last received a request.
357
358       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
363       is_buffering
364           Bool; if we're buffering some/all of a request to memory/disk.
365
366       is_writing
367           Bool; if on, we currently have an "aio_write" out.
368
369       start_time
370           Hi-res time when we started getting data to upload.
371
372       bufh
373           Buffered upload filehandle object.
374
375       bufilename
376           String; buffered upload filename.
377
378       bureason
379           String; if defined, the reason we're buffering to disk.
380
381       buoutpos
382           Int; buffered output position.
383
384       backend_stalled
385           Boolean: if backend has shut off its reads because we're too slow.
386
387       unread_data_waiting
388           Boolean: if we shut off reads while we know data is yet to be read
389           from client.
390
391       chunked_upload_state
392           Bool/obj: if processing a chunked upload,
393           Perlbal::ChunkedUploadState object, else undef.
394
395       request_body_length
396           Integer: request's body length, either as-declared, or calculated
397           after chunked upload is complete.
398
399       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
404       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
408       retry_count
409           Number of times we've retried this request so far after getting 500
410           errors.
411
412       Perlbal::ClientManage
413
414       Descends from Perlbal::Socket.
415
416       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
421       Fields
422
423       service
424           Perlbal::Service.
425
426       buf Read buffer.
427
428       is_http
429           Boolean stating whether the request is HTTP.
430
431       ctx Perlbal::CommandContext.
432
433       Perlbal::Service
434
435       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
441       Fields
442
443       name
444           Name of the service.
445
446       role
447           Role type ("web_server", "reverse_proxy", etc).
448
449       enabled
450           Boolean; whether we're enabled or not (enabled = listening).
451
452       pool
453           Perlbal::Pool that we're using to allocate nodes if we're in proxy
454           mode.
455
456       listener
457           Perlbal::TCPListener object, when enabled.
458
459       reproxy_cache
460           Perlbal::Cache object, when enabled.
461
462       End-user tunables
463
464       listen
465           "IP:port" of where we're listening for new connections.
466
467       docroot
468           Document root for "web_server" role.
469
470       dirindexing
471           Boolean; directory indexing (for "web_server" role). Not async.
472
473       index_files
474           Arrayref of filenames to try for index files.
475
476       enable_concatenate_get
477           Boolean; if user can request concatenated files.
478
479       enable_put
480           Boolean; whether PUT is supported.
481
482       max_put_size
483           Max size in bytes of a put file.
484
485       max_chunked_request_size
486           Max size in bytes of a chunked request (to be written to disk
487           first).
488
489       min_put_directory
490           Number of directories required to exist at beginning of URIs in
491           put.
492
493       enable_delete
494           Boolean; whether DELETE is supported.
495
496       high_priority_cookie
497           Cookie name to check if the client's requests should be considered
498           high priority.
499
500           See also "high_priority_cookie_contents".
501
502       high_priority_cookie_contents
503           Aforementioned cookie value must contain this substring.
504
505       backend_persist_cache
506           Max number of persistent backends to hold onto while no clients.
507
508       persist_client
509           Boolean; persistent connections for clients.
510
511       persist_backend
512           Boolean; persistent connections for backends.
513
514       verify_backend
515           Boolean; get attention of backend before giving it clients (using
516           OPTIONS).
517
518       verify_backend_path
519           Path to check with the OPTIONS request (default is "*").
520
521       max_backend_uses
522           Max requests to send per kept-alive backend (default 0 =
523           unlimited).
524
525       connect_ahead
526           Number of spare backends to connect to in advance all the time.
527
528       buffer_size
529           How much data a Perlbal::ClientProxy object should buffer from a
530           backend.
531
532       buffer_size_reproxy_url
533           Same as above but for backends that are reproxying for us.
534
535       queue_relief_size
536           Number of outstanding standard priority connections to activate
537           pressure relief at.
538
539       queue_relief_chance
540           Int, 0-100; % chance to take a standard priority request when we're
541           in pressure relief mode.
542
543       trusted_upstream_proxies
544           Array of Net::Netmask objects containing netmasks for trusted
545           upstreams.
546
547       always_trusted
548           Boolean; if true, always trust upstreams.
549
550       blind_proxy
551           Boolean; if true, do not modify "X-Forwarded-For", "X-Host", or
552           "X-Forwarded-Host" headers.
553
554       enable_reproxy
555           Boolean; if true, advertise that server will reproxy files and/or
556           URLs.
557
558       reproxy_cache_maxsize
559           Maximum number of reproxy results to be cached. (0 is disabled and
560           default).
561
562       client_sndbuf_size
563           Bytes for "SO_SNDBUF".
564
565       server_process
566           Path to server process (executable).
567
568       persist_client_idle_timeout
569           Keep-alive timeout in seconds for clients (default is 30).
570
571       idle_timeout
572           Idle timeout outside of keep-alive time (default is 30).
573
574       Internal state
575
576       waiting_clients
577           Arrayref of clients waiting for backendhttp connections.
578
579       waiting_clients_highpri
580           Arrayref of high-priority clients waiting for backendhttp
581           connections.
582
583       waiting_clients_lowpri
584           Arrayref of low-priority clients waiting for backendhttp
585           connections.
586
587       waiting_client_count
588           Number of clients waiting for backends.
589
590       waiting_client_map
591           Map of clientproxy fd -> 1 (if they're waiting for a connection).
592
593       pending_connects
594           Hashref of "ip:port" -> $time (only one pending connect to backend
595           at a time).
596
597       pending_connect_count
598           Number of outstanding backend connects.
599
600       bored_backends
601           Arrayref of backends we've already connected to, but haven't got
602           clients.
603
604       hooks
605           Hashref: hookname => [ [ plugin, ref ], [ plugin, ref ], ... ].
606
607       plugins
608           Hashref: name => 1.
609
610       plugin_order
611           Arrayref: name, name, name...
612
613       plugin_setters
614           Hashref: { plugin_name => { key_name => coderef } }.
615
616       extra_config
617           Hashref with extra config options; name => values.
618
619       spawn_lock
620           Boolean; if true, we're currently in "spawn_backends".
621
622       extra_headers
623           { insert => [ [ header, value ], ... ], remove => [ header, header,
624           ... ], set => [ [ header, value ], ... ] }.
625
626           Used in header management interface.
627
628       generation
629           Int; generation count so we can slough off backends from old pools.
630
631       backend_no_spawn
632           { "ip:port" => 1 }.
633
634           If on, "spawn_backends" will ignore this "ip:port" combo.
635
636       buffer_backend_connect
637           0 if off; otherwise, number of bytes to buffer before we ask for a
638           backend.
639
640       selector
641           CODE ref, or undef, for role "selector" services.
642
643       default_service
644           Name of a service a selector should default to.
645
646       buffer_uploads
647           Boolean; enable/disable the buffered uploads to disk system.
648
649       buffer_uploads_path
650           Path to store buffered upload files.
651
652       buffer_upload_threshold_time
653           Int; buffer uploads estimated to take longer than this.
654
655       buffer_upload_threshold_size
656           Int; buffer uploads greater than this size (in bytes).
657
658       buffer_upload_threshold_rate
659           Int; buffer uploads uploading at less than this rate (in
660           bytes/sec).
661
662       upload_status_listeners
663           Comma separated list of "ip:port" of UDP upload status receivers.
664
665       upload_status_listeners_sockaddr
666           Arrayref of sockaddrs (packed ip/port).
667
668       enable_ssl
669           Boolean; whether this service speaks SSL to the client.
670
671       ssl_key_file
672           File path to key pem file.
673
674       ssl_cert_file
675           File to path to cert pem file.
676
677       ssl_cipher_list
678           OpenSSL cipher list string.
679
680       ssl_ca_path
681           Path to certificates directory.
682
683       ssl_verify_mode
684           Int; verification mode, see IO::Socket::SSL.
685
686       enable_error_retries
687           Boolean; whether we should retry requests after errors.
688
689       error_retry_schedule
690           Comma-separated seconds (full or partial) to delay between retries.
691
692       latency
693           Milliseconds of latency to add to request.
694
695       server_tokens
696           Boolean; whether to provide a "Server" header.
697
698       _stat_requests
699           Total requests to this service.
700
701       _stat_cache_hits
702           Total requests to this service that were served via the reproxy-url
703           cache.
704
705
706
707perl v5.36.0                      2022-07-20     Perlbal::Manual::Internals(3)
Impressum