NAME
   Dancer::Middleware::Rebase - a Plack middleware to be used for Dancer

VERSION
   version 0.8.0

DESCRIPTION
   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/".

   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:

      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:

   *   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:

          <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;

   *   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.

   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:

   *   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.

   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.

CONFIGURATION
   This module is a "Plack::Middleware", so you have to configure it inside
   "plack_middlewares" like this:

      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:

   base
       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".

   strip
       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.

AUTHOR
   Flavio Poletti <[email protected]>

COPYRIGHT AND LICENSE
   Copyright (C) 2011 by Flavio Poletti <[email protected]>.

   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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.