NAME
    Plack::Middleware::ProxyMap - Proxy Various URLs to Various Remotes

SYNOPSIS
        my $map = YAML::Load(<<'...');
        - prefix: /yahoo/
          remote: http://au.search.yahoo.com/search?p=
          preserve_host_header: 1
          env:
            HTTP_COOKIE: some cookie text
        - prefix: /google/
          remote: http://www.google.com/search?q=
        ...

        builder {
            enable "ProxyMap", proxymap => $map;
            $app;
        };

DESCRIPTION
    This middleware allows you to easily map one or more URL prefixes to
    remote URLs.

    It makes use of Plack::App::Proxy and supports its options. It also
    makes it easy to specify custom overrides to any of the PSGI environment
    entries. These are often necessary to proxy successfully.

PARAMETERS
    The input to this module is an array ref of hash refs that contain the
    following keys:

    prefix (required)
        The string that matches the beginning of the URL. It it matches, it
        is removed and the rest of the URL is tacked onto the end of the
        "remote" URL. (See below).

    remote (required)
        This is the remote URL to proxy to. The remainder of the incoming
        URL is tacked onto this after the "prefix" is removed. (See above).

    preserve_host_header (optional)
        Accepted values are 0 (default) or 1. Passed through to
        Plack::App::Proxy. See that module for more info.

        If a proxy is not working as expected, try playing with this option.

    env (optional)
        This is a hash ref that will be merged into the current plack "env"
        hash when the proxy is used.

        By default Proxymap will clear PATH_INFO, QUERY_STRING and
        HTTP_COOKIE, which is usually what you want. To not clear anything,
        set this option to a empty hash ref.

        Can be useful for cookie injection, should you need that.

    backend (optional)
        Use this to specify an alternative backend for Plack::App::Proxy.
        See that module for more info.

    debug (optional)
        Set this to 1 to warn the remote url when performing a proxy.

USAGE NOTE
    This module can make it trivial to do ajax calls from JavaScript to load
    external web pages. Since the browser thinks it is now your local web
    page, there is no cross site prevention. When you get the content back,
    you can load it into a DOM element and use things like jQuery to easily
    find data, that you can subsequently display. You can also use REST APIs
    that offer JSON but not JSONP, directly from JavaScript.

CREDIT
    This is just a simple way to use Plack::App::Proxy. Thanks to Lee
    Aylward for that work.

    Thanks to Strategic Data for supporting the writing and release of this
    module.

AUTHOR
    Ingy döt Net <ingy@cpan.org>

Copyright and License
    Copyright 2011-2014. Ingy döt Net.

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

    See <http://www.perl.com/perl/misc/Artistic.html>

