1Perlbal::Manual::Hooks(U3s)er Contributed Perl DocumentatPieornlbal::Manual::Hooks(3)
2
3
4
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.38.0 2023-07-19 Perlbal::Manual::Hooks(3)