TO_DOCUMENT:
  -- hooking management commands

Perlbal Hooks --

                            -- INTRODUCTION --

Basically, a hook is a bit of code that is run at certain stages in the
requests that Perlbal handles.  There are all kinds of hooks available and
they all do different things.  Some are only applicable to some of the
roles and others are applicable only to certain classes.  Each hook is
described in detail below, but first a description of the basics of a hook.

In general, you define a hook by calling the "register_hook" method on a
Perlbal::Service object.  You specify what hook you are interested in and
provide a reference to a subroutine that will be called with the parameters
particular to that hook.

There are three types of hooks:

--- Global hooks
These are hooks that are defined on a global scale.  They are set like so:

    Perlbal::register_global_hook('foo', sub { return 0; });

That would define a global hook named foo that would return 0 when it's
called.  (Return codes from hooks will be explained below.)

--- Service handler hooks
A handler hook is attached to a particular service.  These hooks are called
one at a time, starting from the top of the hook list on a service, until
one hook returns 1.  At that point, no further hooks are called.  For
example:

    $service->register_hook('bar', sub {
        # do something
        return 1;
    });

When this hook runs, it would return 1, signalling to Perlbal that it had
done what it needed to do and that Perlbal shouldn't call any further
hooks.  You can use this type of hook to create sets of plugins that all
handle different types of requests, and when one hook had handled a request
it wouldn't continue telling other hooks about the request.

--- Service general hooks
These hooks are defined the same way as above, but general hooks are all
run.  The return code is ignored.  This can be useful for putting in code
that records statistics about an action or something to that effect.


                               -- HOOKS --

The following hooks are defined in the Perlbal distribution:

GENERAL     end_proxy_request           Perlbal::ClientProxy
This hook is called when the ClientProxy object is being closed.

HANDLER     start_http_request          Perlbal::ClientProxy / Perlbal::ClientHTTP
A generic hook that works for both webserver and proxy modes, run
after either the specific "start_proxy_request" or "start_web_request"
hooks below.  Like those, you return true from this hook to takeover
the connection.

HANDLER     start_proxy_request         Perlbal::ClientProxy
Called as soon as we've read in headers from a user but right before we've
requested a backend connection.  If a true value is returned, Perlbal will
not request a backend.

HANDLER     start_file_reproxy          Perlbal::ClientProxy, $filename_ref
Called when we've been told to reproxy a file.  If you return a true
value, Perlbal will not perform any operations on the file and will simply
return.  You can also change the file in the scalar ref passed as the
second parameter.

HANDLER     backend_client_assigned     Perlbal::BackendHTTP
Happens right after a backend is given a client, but before we've talked to
the backend and asked it to do something.  If you return a true value, the
process is stopped and you will manually have to send the client's request
to the backend, etc.

HANDLER     start_web_request           Perlbal::ClientHTTP
When a 'web' service has gotten headers and is about to serve it... return
a true value to cancel the default handling of web requests.

HANDLER     start_send_file             Perlbal::ClientHTTPBase
Called when we've opened a file and are about to start sending it to the
user using sendfile.  Return a true value to cancel the default sending.

HANDLER     start_serve_request         Perlbal::ClientHTTPBase, $uri_ref
Called when we're about to serve a local file, before we've done any
work.  You can change the file served by modifying $uri_ref, and cancel the
process by returning a true value.

HANDLER     modify_response_headers     Perlbal::ClientHTTPBase
Called when we've set all the headers, and are about to serve a file.
You can change or add response headers at this point, or cancel the
process by returning a true value.  You will have to send the response to
the client yourself if you do this.

HANDLER     reproxy_fh_finished         Perlbal::ClientHTTPBase
Called when a reproxy file has completed and is about to close the file
handle.  You can cancel the process by returning a true value.  You will
have to close the reproxy_fh yourself, and  if you do this.

HANDLER     backend_response_received   Perlbal::BackendHTTP
Called as soon as response headers are read from the backend.  If you
return a true value, will stop all handling at that point.

HANDLER     make_high_priority          Perlbal::ClientProxy
Called when a request is received and right before we're about to determine
if this request is high priority or not.  Return a true value to make the
request high priority; false to leave it alone.  Note that this is only
called when the request isn't already high priority due to cookie priority
scheduling, which is done inside Perlbal's Service module.

HANDLER     return_to_base              Perlbal::ClientHTTPBase
Called when a request has been finished, and control of the Client* object is
about to be transferred back to ownership by a service selector. Return a true
value if the perlbal core action in this situation should be bypassed.