view release on metacpan or  search on metacpan

lib/Mojolicious/Plugin/ClientIP/Pluggable.pm  view on Meta::CPAN

package Mojolicious::Plugin::ClientIP::Pluggable;

# ABSTRACT: Client IP header handling for Mojolicious requests

=head1 NAME

Mojolicious::Plugin::ClientIP::Pluggable - Customizable client IP detection plugin for Mojolicious

=head1 SYNOPSIS

    use Mojolicious::Lite;

    # CloudFlare-waware settings
    plugin 'ClientIP::Pluggable',
        analyze_headers => [qw/cf-pseudo-ipv4 cf-connecting-ip true-client-ip/],
        restrict_family => 'ipv4',
        fallbacks       => [qw/rfc-7239 x-forwarded-for remote_address/];


    get '/' => sub {
        my $c = shift;
        $c->render(text => $c->client_ip);
    };

    app->start;

=head1 DESCRIPTION

Mojolicious::Plugin::ClientIP::Pluggable is a Mojolicious plugin to get an IP address, which
allows to specify different HTTP-headers (and their priorities) for client IP address
extraction. This is needed as different cloud providers set different headers to disclose
real IP address.

If the address cannot be extracted from headers different fallback options are available:
detect IP address from C<X-Forwarded-For> header, detect IP address from C<forwarded> header
(rfc-7239), or use C<remote_address> environment.

The plugin is inspired by L<Mojolicious::Plugin::ClientIP>.

=head1 METHODS

=head2 client_ip

Find a client IP address from the specified headers, with optional fallbacks. The address is
validated that it is publicly available (aka routable) IP address. Empty string is returned
if no valid address can be found.

=head1 OPTIONS

=head2 analyzed_headers

Define order and names of cloud provider injected headers with client IP address.
For C<cloudflare> we found the following headers are suitable:

    plugin 'ClientIP::Pluggable',
        analyzed_headers => [qw/cf-pseudo-ipv4 cf-connecting-ip true-client-ip/].

This option is mandatory.

More details at L<https://support.cloudflare.com/hc/en-us/articles/202494830-Pseudo-IPv4-Supporting-IPv6-addresses-in-legacy-IPv4-applications>,
L<https://support.cloudflare.com/hc/en-us/articles/200170986-How-does-CloudFlare-handle-HTTP-Request-headers>,
L<https://support.cloudflare.com/hc/en-us/articles/206776727-What-is-True-Client-IP>

=head2 restrict_family

    plugin 'ClientIP::Pluggable', restrict_family => 'ipv4';
    plugin 'ClientIP::Pluggable', restrict_family => 'ipv6';

If defined only IPv4 or IPv6 addresses are considered valid among the possible addresses.

By default this option is not defined, allowing IPv4 and IPv6 addresses.

=head2 fallbacks

    plugin 'ClientIP::Pluggable',
        fallbacks => [qw/rfc-7239 x-forwarded-for remote_address/]);

Try to get valid client IP-address from fallback sources, if we fail to do that from
cloud-provider headers.

C<rfc-7239> uses C<forwarded> header, C<x-forwarded-for> use <x-forwarded-for> header
(appeared before rfc-7239 and still widely used) or use remote_address environment
(C<$c->tx->remote_address>).

Default value is C<[remote_address]>.

=head1 ENVIRONMENT

=head2 CLIENTIP_PLUGGABLE_ALLOW_LOOPBACK

Allows non-routable loopback address (C<127.0.0.1>) to pass validation. Use it for
test purposes.

Default value is C<0>, i.e. loopback addresses do not pass IP-address validation.