Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 116 lines (88 sloc) 5.24 kb
9543def0 »
2005-07-22 start of more docs wrt configuration
1 TO_DOCUMENT:
2 -- hooking management commands
3
4e362a56 »
2004-07-09 Big changes to Perlbal, including: a new plugins system. This system
4 Perlbal Hooks --
5
6 -- INTRODUCTION --
7
8 Basically, a hook is a bit of code that is run at certain stages in the
9 requests that Perlbal handles. There are all kinds of hooks available and
10 they all do different things. Some are only applicable to some of the
11 roles and others are applicable only to certain classes. Each hook is
12 described in detail below, but first a description of the basics of a hook.
13
14 In general, you define a hook by calling the "register_hook" method on a
15 Perlbal::Service object. You specify what hook you are interested in and
16 provide a reference to a subroutine that will be called with the parameters
17 particular to that hook.
18
19 There are three types of hooks:
20
21 --- Global hooks
22 These are hooks that are defined on a global scale. They are set like so:
23
24 Perlbal::register_global_hook('foo', sub { return 0; });
25
26 That would define a global hook named foo that would return 0 when it's
27 called. (Return codes from hooks will be explained below.)
28
29 --- Service handler hooks
30 A handler hook is attached to a particular service. These hooks are called
31 one at a time, starting from the top of the hook list on a service, until
32 one hook returns 1. At that point, no further hooks are called. For
33 example:
34
35 $service->register_hook('bar', sub {
36 # do something
37 return 1;
38 });
39
40 When this hook runs, it would return 1, signalling to Perlbal that it had
41 done what it needed to do and that Perlbal shouldn't call any further
42 hooks. You can use this type of hook to create sets of plugins that all
43 handle different types of requests, and when one hook had handled a request
44 it wouldn't continue telling other hooks about the request.
45
46 --- Service general hooks
47 These hooks are defined the same way as above, but general hooks are all
48 run. The return code is ignored. This can be useful for putting in code
49 that records statistics about an action or something to that effect.
50
51
52 -- HOOKS --
53
54 The following hooks are defined in the Perlbal distribution:
55
56 GENERAL end_proxy_request Perlbal::ClientProxy
57 This hook is called when the ClientProxy object is being closed.
58
d0df4619 »
2005-07-22 add generic "start_http_request" that works for both clientproxy and …
59 HANDLER start_http_request Perlbal::ClientProxy / Perlbal::ClientHTTP
60 A generic hook that works for both webserver and proxy modes, run
61 after either the specific "start_proxy_request" or "start_web_request"
62 hooks below. Like those, you return true from this hook to takeover
63 the connection.
64
4e362a56 »
2004-07-09 Big changes to Perlbal, including: a new plugins system. This system
65 HANDLER start_proxy_request Perlbal::ClientProxy
66 Called as soon as we've read in headers from a user but right before we've
67 requested a backend connection. If a true value is returned, Perlbal will
68 not request a backend.
69
70 HANDLER start_file_reproxy Perlbal::ClientProxy, $filename_ref
71 Called when we've been told to reproxy a file. If you return a true
72 value, Perlbal will not perform any operations on the file and will simply
73 return. You can also change the file in the scalar ref passed as the
74 second parameter.
75
76 HANDLER backend_client_assigned Perlbal::BackendHTTP
77 Happens right after a backend is given a client, but before we've talked to
78 the backend and asked it to do something. If you return a true value, the
79 process is stopped and you will manually have to send the client's request
80 to the backend, etc.
81
82 HANDLER start_web_request Perlbal::ClientHTTP
83 When a 'web' service has gotten headers and is about to serve it... return
84 a true value to cancel the default handling of web requests.
85
86 HANDLER start_send_file Perlbal::ClientHTTPBase
87 Called when we've opened a file and are about to start sending it to the
88 user using sendfile. Return a true value to cancel the default sending.
89
90 HANDLER start_serve_request Perlbal::ClientHTTPBase, $uri_ref
91 Called when we're about to serve a local file, before we've done any
92 work. You can change the file served by modifying $uri_ref, and cancel the
93 process by returning a true value.
94
153feec0 »
2006-05-26 added modify_response_headers hook
95 HANDLER modify_response_headers Perlbal::ClientHTTPBase
96 Called when we've set all the headers, and are about to serve a file.
97 You can change or add response headers at this point, or cancel the
98 process by returning a true value. You will have to send the response to
99 the client yourself if you do this.
100
d99cc6cb »
2006-05-26 added reproxy_fh_finished hook
101 HANDLER reproxy_fh_finished Perlbal::ClientHTTPBase
102 Called when a reproxy file has completed and is about to close the file
103 handle. You can cancel the process by returning a true value. You will
104 have to close the reproxy_fh yourself, and if you do this.
105
4e362a56 »
2004-07-09 Big changes to Perlbal, including: a new plugins system. This system
106 HANDLER backend_response_received Perlbal::BackendHTTP
107 Called as soon as response headers are read from the backend. If you
108 return a true value, will stop all handling at that point.
2d03fdc0 »
2004-07-13 New Perlbal feature: PUT support. This gives Perlbal the ability to h…
109
d938b01d »
2004-08-27 Add in a hook that is called when a request that's not high priority is
110 HANDLER make_high_priority Perlbal::ClientProxy
111 Called when a request is received and right before we're about to determine
112 if this request is high priority or not. Return a true value to make the
113 request high priority; false to leave it alone. Note that this is only
114 called when the request isn't already high priority due to cookie priority
115 scheduling, which is done inside Perlbal's Service module.
Something went wrong with that request. Please try again.