NAME

Apache::Wyrd::Handler - Apache Handler object for Apache::Wyrd modules

SYNOPSIS

        PerlWarn off
        <Directory /var/www/sites/BASENAME>
                SetHandler perl-script
                PerlHandler BASENAME::Handler
        </Directory>

DESCRIPTION

Handler for Apache::Wyrd documents. For more information on mod_perl and handlers, see http://perl.apache.org/docs/index.html

This module has been developed for and only been tested in Apache < 2.0 / mod_perl < 1.99. In this environment, the SYNOPSIS shows a typical set of appropriate Apache directives. Global Perl warnings are turned off, as they are more granularly handled within the package. Note that the Handler that is used is an instance of this handler. It is named, in this example, BASNAME::Handler and is found in a BASENAME directory which in @INC of a local mod_perl installation. Traditionally, this is in <apache configuration directory>/lib/perl/. If the perl module BASENAME::Handler has a use base qw(Apache::Wyrd::Handler) declaration, the handler method should properly determine the base class for the BASENAME set of Wyrds and the handler should interpret only those tags beginning <BASENAME::... A rudimentary sample of this usage is available in the t/lib directory of this package and is used for testing.

This way, several sites using Wyrds can be built, each subclassing Apache::Wyrd objects in their own idiom without interfering in the interpretation of the same objects in another BASENAME class. (However, nothing prevents a second BASENAME from including the first BASENAME in its use base declaration array). This is a feature(tm) of Apache::Wyrd and is intended to promote code re-use. It also means that multiple instances of Apache::Wyrd hierarchies on a shared machine are completely open to cross- scripting attacks. Since it is generally not sensible to have mod_perl offered in a shared environment, a version of Apache::Wyrd without this vulnerability will probably never be made.

The Handler also dumps out the error log, if needed from the DBL, where it accumulates from it's own internal calls and calls by Wyrds to the error-level functions (_warn, _error, etc.). If the "init" hashref has a non-null key called "error_page", this log will be reverse-dumped in a standard-looking error page with a backtrace of events.

METHODS

new

Accept and bless a new object. Provided for tradition's sake, since the handler method does the real work.

handler

Handle the request. This handler uses the 2 argument function prototype so that it can be instantiated in another name-space.

In the example Apache directive above, the arguments supplied by the Apache directive give it the class name "BASENAME". It uses this BASENAME to determine what is the base class of all Wyrds it handles. Consequently, it will only parse Wyrds which begin with <BASENAME::...

The handler assembles the Apache request object itself, the initialization hash for the generation of Apache::Wyrd objects, and the globals used by Apache::DBL. It then calls process and respond in sequence. If all goes well, the 'output' attribute has been set by the response method, and this is returned with the appropriate headers set.

_exception_handler

Before returning a non-OK response, the handler will send two scalars to this method and if the method returns a response, that response will be sent instead. Subclasses of Apache::Wyrd::Handler can use this method to invoke and return responses from other handlers or generate custom responders.

What arguments for the first method subclasses of this method accept and how they invoke the responding entity are entirely up to the programmer.

The default behavior is to redirect full URLs, pass internal redirections back to the handler, and handle 'request authorization' messages to Apache::Wyrd::Services::Auth.

post_process

Called by handler on a successful responses from process and respond. A hook for post-processing the final output. At the point this method is called, all the output is ready to be sent and is waiting in the output attribute, so this method traditionally manipulates $self->{'output'} directly.

add_headers

Called by handler on a successful responses from process and respond. Adds some standard headers to the response or can be overridden. By default, it adds headers to help with compatibility with AOL's famously broken proxies and other similar problems.

get_file

Based on the request, locates the file to be used and sets the file attribute to that path. It declines non-text/html files (via mime type) and, on accepting a file, passes the mtime and size of the file to the init hashref for use by the Apache::Wyrd object.

globals

defines the hashref which will be kept by the DBL object. Empty by default.

init

defines the hashref which will be used to initialize the Apache::Wyrd objects. It must return the request object under the key 'req', which is stored under the Apache::Wyrd::Handler attribute 'req' by the handler method. Any other keys are optional.

By default, if the hash key 'error_page' is set (non-null), the installation will use an error page with a debugging log. See the errorpage method.

Note also if you wish to pass data containing Wyrd constructions via CGI variables, you need to list the variables by array reference here under the taint_exceptions key. For example, a site under the namespace "TESTSITE" has a form with a text area called "widget_text" in which Wyrds may be composed. This text area's name is included in the hashref values returned by init:

  sub init {
    my ($self) = @_;
    return {
      req => $self->{'req'},
      taint_exceptions => ['widget_text'],
      .... other init keys and values ...
    }
  }

Otherwise, any data submitted by the textarea will be ignored if it contains any string beginning with <TESTSITE::.

process

"Hook" method for introducing other handling checks to the request. It should return an Apache::Constants value if it wants to override the response of the respond method. If it does this override, then it is responsible for setting it's own headers.

respond

Does the work of setting up the found page as an Apache::Wyrd object and calling it's output method. Should probably not be overridden, unless there are tweaks that cannot be accomplished in add_headers and process.

req

return the Apache request object. This handle has been initialized in handler

errorpage

Simply a formatting method. Given the error and the log in scalar form, outputs an Error Page with "Internal Server Error" at the top. Called by respond when the debugging flags are on.

BUGS/CAVEATS/RESERVED METHODS

FREE SOFTWARE

Standard warning about GNU GPL software. See LICENSE under the documentation for Apache::Wyrd

(GENERALLY) UNIX-Only

This software has only tested under Linux and Darwin, but should work for any *nix-style system. This software is not intended for use on windows or other delicate glassware.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

Apache::Wyrd::DBL

"Das Blinkenlights", a more-or-less mandatory module for centralization of calls to the Apache process or an associated DBI-type database.

The Eagle Book

"Writing Apache Modules iwth Perl and C" by Stein & MacEachern, Copyright 1999 O'Reilly & Associates, Inc., ISBN: 1-56592-567-X.

LICENSE

Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.