1Perlbal::Manual::Hooks(U3s)er Contributed Perl DocumentatPieornlbal::Manual::Hooks(3)
2
3
4

NAME

6       Perlbal::Manual::Hooks - How Perlbal's hooks work
7
8   VERSION
9       Perlbal 1.78.
10
11   DESCRIPTION
12       Basically, a hook is a bit of code that is run at certain stages in the
13       requests that Perlbal handles.There are all kinds of hooks available
14       and they all do different things. Some are only applicable to some of
15       the roles and others are applicable only to certain classes. Each hook
16       is described in detail below, but first a description of the basics of
17       a hook.
18
19       In general, you define a hook by calling the "register_hook" method on
20       a Perlbal::Service object. You specify what hook you are interested in
21       and provide a reference to a subroutine that will be called with the
22       parameters particular to that hook.
23
24       There are three types of hooks:
25
26   Global hooks
27       These are hooks that are defined on a global scale. They are set like
28       so:
29
30           Perlbal::register_global_hook('foo', sub { return 0; });
31
32       That would define a global hook named foo that would return 0 when it's
33       called. (Return codes from hooks will be explained below)
34
35       Global hooks are useful to define management commands. See
36       "manage_command" under Perlbal::Manual::Plugins for more information.
37
38   Service handler hooks
39       A handler hook is attached to a particular service. These hooks are
40       called one at a time until one hook returns 1. At that point, no
41       further hooks are called. For example:
42
43           $service->register_hook('bar', sub {
44               # do something
45               return 1;
46           });
47
48       When this hook runs, it would return 1, signalling to Perlbal that it
49       had done what it needed to do and that Perlbal shouldn't call any
50       further hooks. You can use this type of hook to create sets of plugins
51       that all handle different types of requests, and when one hook had
52       handled a request it wouldn't continue telling other hooks about the
53       request.
54
55       backend_client_assigned
56
57       Happens right after a backend is assigned to a client, but before we've
58       talked to the backend and asked it to do something. If you return a
59       true value, the process is stopped and you will manually have to send
60       the client's request to the backend, etc.
61
62       Called in Perlbal::BackendHTTP.
63
64       Available in role "reverse_proxy".
65
66       backend_readable_verify
67
68       When the backend is about to start sending the response.
69
70       Called in Perlbal::BackendHTTP.
71
72       Available in all roles.
73
74       backend_response_received
75
76       Called as soon as response headers are read from the backend. If you
77       return a true value, will stop all handling at that point.
78
79       Called in Perlbal::BackendHTTP.
80
81       Available in all roles.
82
83       backend_write_verify
84
85       When the backend is ready to receive the request.
86
87       Called in Perlbal::BackendHTTP.
88
89       Available in all roles.
90
91       concat_get_poststat_file_missing
92
93       Called when a missing file was requested in a request for multiple
94       files concatenated, right before sending the 404 response. Return a
95       true value to overtake the connection.
96
97       Called in Perlbal::ClientHTTPBase.
98
99       Available in role "web_server".
100
101       See also "concat_get_poststat_pre_send",
102       "static_get_poststat_file_missing" and "static_get_poststat_pre_send".
103
104       concat_get_poststat_pre_send
105
106       Called when the resulting file of a request for multiple files
107       concatenated is about to be sent, right before the 200 response code is
108       added as a header. Return a true value to overtake the connection.
109
110       Called in Perlbal::ClientHTTPBase.
111
112       Available in role "web_server".
113
114       See also "concat_get_poststat_file_missing",
115       "static_get_poststat_file_missing" and "static_get_poststat_pre_send".
116
117       handle_put
118
119       Called when handling a PUT request.
120
121       Called in Perlbal::ClientHTTP.
122
123       Available in role "web_server".
124
125       make_high_priority
126
127       Called when a request is received and right before we're about to
128       determine if this request is high priority or not. Return a true value
129       to make the request high priority; false to leave it alone. Note that
130       this is only called when the request isn't already high priority due to
131       cookie priority scheduling, which is done inside Perlbal::Service.
132
133       Called in Perlbal::ClientProxy.
134
135       Available in all roles.
136
137       make_low_priority
138
139       Called when a request is received and right before we're about to
140       determine if this request is high priority or not. Return a true value
141       to make the request low priority; false to leave it alone.
142
143       Called in Perlbal::ClientProxy.
144
145       Available in all roles.
146
147       modify_response_headers
148
149       Called when we've set all the headers, and are about to serve a file.
150       You can change or add response headers at this point, or cancel the
151       process by returning a true value. You will have to send the response
152       to the client yourself if you do this.
153
154       Called in Perlbal::ClientHTTPBase.
155
156       Available in role "web_server".
157
158       proxy_read_request
159
160       Called on the request before we send the request to a backend.
161
162       Called in Perlbal::ClientProxy.
163
164       Available in all roles.
165
166       put_writeout
167
168       Called when there is some put data to write out.
169
170       Called in Perlbal::ClientHTTP.
171
172       Available in role "web_server".
173
174       reproxy_fh_finished
175
176       Called when a reproxy file has completed and is about to close the file
177       handle. You can cancel the process by returning a true value (in which
178       case you will have to close the reproxy_fh yourself).
179
180       Called in Perlbal::ClientHTTPBase.
181
182       Available in role "web_server".
183
184       reproxy_response_received
185
186       Called as soon as response headers are read from a reproxied backend.
187       If you return a true value, will stop all handling at that point.
188
189       Called in Perlbal::ClientProxy.
190
191       Available in role "reverse_proxy".
192
193       return_to_base
194
195       Called when a request has been finished, and control of the Client*
196       object is about to be transferred back to ownership by a service
197       selector. Return a true value if the perlbal core action in this
198       situation should be bypassed.
199
200       Called in Perlbal::ClientHTTPBase.
201
202       Available in all roles.
203
204       start_file_reproxy
205
206       Called when we've been told to reproxy a file. If you return a true
207       value, Perlbal will not perform any operations on the file and will
208       simply return. You can also change the file in the scalar ref passed as
209       the second parameter.
210
211       Called in Perlbal::ClientProxy; receives $filename_ref, a reference to
212       the filename.
213
214       Available in role "reverse_proxy".
215
216       start_http_request
217
218       A generic hook that works for both webserver and proxy modes, run after
219       either the specific "start_proxy_request" or "start_web_request" hooks
220       below. Like those, you return true from this hook to takeover the
221       connection.
222
223       Called in Perlbal::ClientProxy and Perlbal::ClientHTTP.
224
225       Available in roles "reverse_proxy" and "web_server".
226
227       start_proxy_request
228
229       Called as soon as we've read in headers from a user but right before
230       we've requested a backend connection. If a true value is returned,
231       Perlbal will not request a backend.
232
233       Called in Perlbal::ClientProxy.
234
235       Available in role "reverse_proxy".
236
237       start_send_file
238
239       Called when we've opened a file and are about to start sending it to
240       the user using sendfile. Return a true value to cancel the default
241       sending.
242
243       Called in Perlbal::ClientHTTPBase.
244
245       Available in role "web_server".
246
247       start_serve_request
248
249       Called when we're about to serve a local file, before we've done any
250       work. You can change the file served by modifying $uri_ref, or cancel
251       the process by returning a true value.
252
253       Called in Perlbal::ClientHTTPBase; receives $uri_ref, a reference to
254       the URI.
255
256       Available in role "web_server".
257
258       start_web_request
259
260       When a service has gotten headers and is about to serve it. Return a
261       true value to cancel the default handling of web requests.
262
263       Called in Perlbal::ClientHTTP.
264
265       Available in role "web_server".
266
267       static_get_poststat_file_missing
268
269       Called when a missing static single file was requested, right before
270       sending the 404 response. Return a true value to overtake the
271       connection.
272
273       Called in Perlbal::ClientHTTPBase.
274
275       Available in role "web_server".
276
277       See also "concat_get_poststat_file_missing",
278       "concat_get_poststat_pre_send" and "static_get_poststat_pre_send".
279
280       static_get_poststat_pre_send
281
282       Called when a static single file is about to be sent, right before the
283       200 response code is added as a header. Return a true value to overtake
284       the connection.
285
286       Called in Perlbal::ClientHTTPBase.
287
288       Available in role "web_server".
289
290       See also "concat_get_poststat_file_missing",
291       "concat_get_poststat_pre_send" and "static_get_poststat_file_missing".
292
293   Service general hooks
294       These hooks are defined the same way as above, but general hooks are
295       all run. The return code is ignored. This can be useful for putting in
296       code that records statistics about an action or something to that
297       effect.
298
299       end_proxy_request
300
301       This hook is called when the Perlbal::ClientProxy object is being
302       closed.
303
304       Available in role "reverse_proxy".
305
306   SEE ALSO
307       Perlbal::Manual::Internals, Perlbal::Manual::Plugins.
308
309
310
311perl v5.36.0                      2022-07-20         Perlbal::Manual::Hooks(3)