Dancer::Middleware::Rebase - a Plack middleware to be used for Dancer
version 0.8.0
This is a Plack::Middleware specifically geared to the Dancer framework. The goal is to let you rebase your application easily, i.e. let you move your application that usually lives in http://example.com/ into http://example.com/some/prefix/ or even http://whatever.example.com/other/prefix/.
http://example.com/
http://example.com/some/prefix/
http://whatever.example.com/other/prefix/
This can be particularly useful in a reverse-proxy deployment, where the application is called by the proxy HTTP server and thus lives in a different namespace with respect to the one available to the end user.
Suppose for example that you have a reverse-proxy deployment, where the end user calls route /homepage in your application using the URI http://example.com/app/homepage. If you are using Apache with the following configuration:
/homepage
http://example.com/app/homepage
ProxyPass /app/ http://internal:3000/ ProxyPassReverse /app/ http://internal:3000/
then the route in your application will be called as http://internal:3000/homepage. This leads to two problems:
http://internal:3000/homepage
both uri_for() and request.base() refer to http://internal:3000/. This means that it's very likely that your links will be wrong, e.g. consider the link to the CSS file in a standard Dancer application:
uri_for()
request.base()
http://internal:3000/
<link rel="stylesheet" href="<% request.base %>/css/style.css" />
This will be expanded to http://internal:3000//css/style.css which will not be accessible by the end user. This particular problem can be addressed using Plack::Middleware::ReverseProxy, which massages $env in order to restore the originally requested scheme, host and port;
http://internal:3000//css/style.css
$env
the additional path prefix /app/ has been stripped by Apache and there is no reference to it. While the problem above can be addressed with Plack::Middleware::ReverseProxy, there is no standard solution for addressing this issue and you have to work out your own.
/app/
You might think that you can address the latter problem with a proper Apache configuration:
ProxyPass /app/ http://internal:3000/app/ ProxyPassReverse /app/ http://internal:3000/app/
but with this configuration you receive a request towards http://internal:3000/app/homepage, which is not going to work smoothly for different reasons:
http://internal:3000/app/homepage
you have to set a proper prefix for rebasing all the routes;
even so, you are not able to rebase the static part of the site, i.e. your CSS files are still ruled out unless you address them specifically in the Apache configuration.
Dancer::Middleware::Rebase addresses all these problems at the same time. You can set a base URI that will be propagated in the $env passed to your application. In particular, it will set all the proper variables that are then used by Dancer::Request methods base() and uri_for() in order to establish the URI where all stuff can be referred.
base()
In case you like keeping the prefix part in the Apache configuration, anyway, you still have the problem of stripping it before giving it to the application. In this case, you can set a strip parameter to eliminate the prefix from the PATH_INFO component of $env.
strip
PATH_INFO
This module is a Plack::Middleware, so you have to configure it inside plack_middlewares like this:
Plack::Middleware
plack_middlewares
plack_middlewares: - - "+Dancer::Middleware::Rebase" - base - "http://example.com/app" - strip - 1
Please note that you have to put a plus sign before the module name, otherwise Plack will think that it is a name to be referred to the Plack::Middleware namespace.
You can set the following options:
the URI that has to be set as the base one. This will be what you eventually get when you call request.base in your code and in your templates, and it is also used by uri_for.
request.base
uri_for
either a true value or a string that starts with /. In the first case, the path portion of the base URI will be used as a prefix to be stripped from PATH_INFO, otherwise the specified string is used. You should only need the first approach, anyway.
/
path
base
Flavio Poletti <polettix@cpan.org>
Copyright (C) 2011 by Flavio Poletti <polettix@cpan.org>.
This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
To install Dancer::Middleware::Rebase, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dancer::Middleware::Rebase
CPAN shell
perl -MCPAN -e shell install Dancer::Middleware::Rebase
For more information on module installation, please visit the detailed CPAN module installation guide.