NAME

Plack::Middleware::MockProxyFrontend - virtualhost-aware PSGI app developer tool

SYNOPSIS

 # in app.psgi
 use Plack::Builder;
 
 builder {
     enable 'MockProxyFrontend',
         SSL_key_file  => 'key.pem',
         SSL_cert_file => 'cert.pem';
     $app;
 };

DESCRIPTION

This middleware implements the HTTP proxy protocol… without the proxy: it passes every request down to the wrapped PSGI application. Your application becomes the browser's entire internet: no matter which address you navigate to, the response comes from the wrapped PSGI application.

This is useful in the development of PSGI applications that do virtual hosting, i.e. dispatching on hostname. Instead of testing your application by going to http://localhost:5000/, you go to https://example.com/ (or whatever your site is). Your application will see a request for https://example.com/, not http://localhost:5000/, e.g. when your framework generates absolute links. And then when the page loads, the browser will think it is showing you the real https://example.com/, e.g. in the address bar.

The way this works is that instead of typing http://localhost:5000/ into the browser's address bar to test your app (or wherever your development server is listening), you put localhost:5000 as the HTTP/HTTPS proxy in the browser's configuration. Then any URL you navigate to will end up being served by your application, so e.g. absolute links to https://example.com/ will just work.

NOTE

If you use plackup to start your application, use --no-default-middleware to prevent it wrapping Plack::Middleware::Lint around this middleware. Lint reacts badly to a browser speaking the proxy protocol to it.

Generally MockProxyFrontend ought to be the outermost middleware in your stack. Most other middlewares will work OK when confronted with the proxy protocol, but they are not really designed for it, so it is best to convert the request to a normal HTTP request as soon as possible.

CONFIGURATION OPTIONS

SSL_*

Configuration options for IO::Socket::SSL that will be used to construct an SSL context.

You don't need to pass any of these unless you need SSL support. If you need it, SSL_key_file and SSL_cert_file are probably the options you are looking for.

Note that SSL support requires a PSGI server that implements the psgix.io extension.

host_acceptor

A function that will be called to decide whether to serve a request. If it returns false, the request will be refused, otherwise it will be served. The function will be passed the (lowercased) hostname from the request, both as its sole argument and in $_. E.g.:

 enable 'MockProxyFrontend',
     host_acceptor => sub { 'webmonkeys.io' eq $_ };

Defaults to accepting all requests.

http_server

An object that responds to $self->handle_connection( $env, $socket, $app ). This will be passed the connection from CONNECT requests. E.g.:

 enable 'MockProxyFrontend',
     http_server => do {
         require Starlet::Server;
         Starlet::Server->new
     };

Defaults to an instance of HTTP::Server::PSGI.

BUGS AND LIMITATIONS

Error checking and attitude toward security is lackadaiscal.

There are NO TESTS because I wouldn't know how to write them.

This was written as a developer tool, not for deployment anywhere that could be described as production. Otherwise I wouldn't be releasing it in this state.

Use at your own risk.

Mind you, I am anything but opposed to fixing these problems – I am just not losing sleep over them. Patches welcome and highly appreciated.

AUTHOR

Aristotle Pagaltzis <pagaltzis@gmx.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Aristotle Pagaltzis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.