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_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     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     handle_put                  Perlbal::ClientHTTP
Called whenever we have data to write to a file being PUT.  Return a true
value to cause Perlbal to not actually save the file or do anything with
it.

HANDLER     setup_put                   Perlbal::ClientHTTP
Called as soon as we've gotten headers requesting a PUT.  Cancels the
default work if you return a true value.  Careful: this function sets up
a file descriptor for use in writes in handle_put, so if you're going to
override setup_put you will probably want to override handle_put.

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.