NAME

SYNOPSIS

# Configure HTML::MasonX::ApacheLikePlackHandler to use
# our mock classes instead of Apache2::$WHATEVER.
#
# This is horribly ugly but allows us to diverge less
# in HTML::MasonX::ApacheLikePlackHandler from the
# upstream HTML::Mason::ApacheHandler.
local $ENV{HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_REQUEST_CLASS} = 'Your::ApacheLikePlackHandler::Compat::Apache2::Request';
local $ENV{HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_REQUEST_INSTANCE_CLASS} = 'Your::Mock::Apache2::Request';
local $ENV{HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_SERVERUTIL_CLASS} = 'Your::ApacheLikePlackHandler::Compat::Apache2::ServerUtil';
local $ENV{HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_STATUS_CLASS} = 'Your::ApacheLikePlackHandler::Compat::Apache2::Status';
require HTML::MasonX::ApacheLikePlackHandler;

DESCRIPTION

This is not a module intended to write new Mason applications under Plack, you probably want something like HTML::Mason::PlackHandler for that, or better yet if you're writing something new use Mason 2.0, or don't use Mason at all.

There's many possible ways to transition a HTML::Mason application running under Apache 2 and mod_perl to a Plack stack running outside of Apache, but the one I went for for the Booking.com codebase was to:

Using the fake Apache Request object above, for easy reverts back & forth between running the application on Apache2/mod_perl and nginx/uWSGI/Plack without having to change all the application logic to use the Plack API instead of the Apache API.

I was already running on Apache 1 anyway, and didn't want to bother with the Apache 1 parts of this API. So away it goes!

Removed loading of mod_perl libraries

But most importantly: Instead of requiring various Apache2::* modules we require that you define HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_{REQUEST,REQUEST_INSTANCE,STATUS,SERVERUTIL}_CLASS in %ENV before requiring this module.

Those %ENV entries should be the name of already loaded Perl packages implement an API emulating the Apache2 API this package needs. The "APACHE2_REQUEST_INSTANCE" variable is a special case though, it's the package your request object (implementing the Apache2 API) will be blessed into.

This makes for a rather convoluted API, but the goal was to modify the upstream code as little as possible, both to avoid accidentally introducing bugs, and to make it easier to incorporate future upstream patches.

EXAMPLE

Here's an example of the source of packages you could as the HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_* variables. These are just bare-minimal implementations of the Apache API that HTML::MasonX::ApacheLikePlackHandler expects uses.

HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_REQUEST_CLASS

HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_REQUEST_CLASS

package Your::ApacheLikePlackHandler::Compat::Apache2::Request;
use strict;
use warnings;
use Scalar::Util qw(blessed);
# NEEDED because of HTML::MasonX::ApacheLikePlackHandler code that
# does $this_pkg->VERSION. We should never need to change this.
our $VERSION = 1.2345;
# This is only used for:
#
# sub { Apache2::Request->new( $_[0] ) };
#
# So just return the original object. The reason for this being
# called at all is because the mod_perl 1 API would do something
# different
sub new {
my ($class, $blessed_request_object) = @_;
die "PANIC: We should only get an already blessed object as an argument"
unless blessed($blessed_request_object);
return $blessed_request_object;
}
# We do nothing except the above in this class from
# HTML::MasonX::ApacheLikePlackHandler as of writing this.

HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_SERVERUTIL_CLASS

package Your::ApacheLikePlackHandler::Compat::Apache2::ServerUtil;
use strict;
use warnings;
use Your::WebServerConfiguration qw(
PLACK_WEBSERVER_CONFIGURATION_VARIABLES
);
sub server {
my $class = shift;
die "PANIC: We should have no extra arguments to server()" if @_;
return bless {
# So it's obvious where this came from if it turns up somewhere else
THIS_IS_A_MOCK_CLASS_FOR_ONE_DIR_CONFIG_CALL => 1337
} => $class;
}
sub dir_config {
my $self = shift;
should_have_no_extra_arguments(\@_);
my %PLACK_WEBSERVER_CONFIGURATION_VARIABLES = PLACK_WEBSERVER_CONFIGURATION_VARIABLES;
return Your::MasonCompat::APR::Like::Table->new({
# Used by HTML::MasonX::ApacheLikePlackHandler::_startup()
# which only requests the MasonArgsMethod.
MasonArgsMethod => $PLACK_WEBSERVER_CONFIGURATION_VARIABLES{MasonArgsMethod},
});
}
sub server_root {
# DO we even support this? Probably not.
die "PANIC: We don't support the server_root() function";
}
# We do nothing except the above in this class from
# HTML::MasonX::ApacheLikePlackHandler as of writing this.

HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_STATUS_CLASS

package Your::ApacheLikePlackHandler::Compat::Apache2::Status;
use strict;
use warnings;
# This package is to mock Apache2::Status which provides a
# /perl-status.
#
# We don't want this, so we just provide a dummy menu_item method
# here.
#
# We *DON'T* set the version because that's what
# HTML::MasonX::ApacheLikePlackHandler checks to see if it should
# set it up properly later on. Don't do that.
sub menu_item { return }
# We do nothing except the above in this class from
# HTML::MasonX::ApacheLikePlackHandler as of writing this.

AUTHOR

Ævar Arnfjörð Bjarmason <avar@cpan.org> is responsible for HTML::MasonX::ApacheLikePlackHandler, but as described above it's almost exactly the same as derived from HTML::Mason::ApacheHandler. Refer to that package for the original authorship & copyright.