let FTP, NNTP, POP3, SMTP restrict Domain to IPv4 even if IPv6 is supported by using Domain/Family argument

- accept Family and Domain
- work around issues with IO::Socket::IP, which deals with argument 'Domain' in a non sub-classable way
- update various documentation about the relevant super class and SSL support
unify behavior:
- accept LocalPort with NNTP too (not only LocalAddr)
- accept LocalAddr and LocalPort with POP3, keep ResvPort for backward compatible name for LocalPort

4 files changed, 77 insertions, 27 deletions

diff --git a/lib/Net/FTP.pm b/lib/Net/FTP.pm
index 699998e..2a820aa 100644
--- a/lib/Net/FTP.pm
+++ b/lib/Net/FTP.pm
@@ -28,6 +28,7 @@ use Time::Local;
 our $VERSION = '3.07';
 
 our $IOCLASS;
+my $family_key;
 BEGIN {
   # Code for detecting if we can use SSL
   my $ssl_class = eval {
@@ -55,6 +56,10 @@ BEGIN {
   sub can_inet6 { $inet6_class };
 
   $IOCLASS = $ssl_class || $inet6_class || 'IO::Socket::INET';
+  $family_key =
+    ( $ssl_class ? $ssl_class->can_ipv6 : $inet6_class || '' )
+      eq 'IO::Socket::IP'
+      ? 'Family' : 'Domain';
 }
 
 our @ISA = ('Exporter','Net::Cmd',$IOCLASS);
@@ -120,6 +125,7 @@ sub new {
     PeerAddr  => $peer,
     PeerPort  => $arg{Port} || ($arg{SSL} ? 'ftps(990)' : 'ftp(21)'),
     LocalAddr => $arg{'LocalAddr'},
+    $family_key => $arg{Domain} || $arg{Family},
     Proto     => 'tcp',
     Timeout   => defined $arg{Timeout} ? $arg{Timeout} : 120,
     %tlsargs,
@@ -131,6 +137,7 @@ sub new {
   ${*$ftp}{'net_ftp_blksize'} = abs($arg{'BlockSize'} || 10240);
 
   ${*$ftp}{'net_ftp_localaddr'} = $arg{'LocalAddr'};
+  ${*$ftp}{'net_ftp_family'} = $arg{Domain} || $arg{Family};
 
   ${*$ftp}{'net_ftp_firewall'} = $fire
     if (defined $fire);
@@ -889,6 +896,7 @@ sub _eprt {
       Listen    => 1,
       Timeout   => $ftp->timeout,
       LocalAddr => $ftp->sockhost,
+      $family_key  => $ftp->sockdomain,
       can_ssl() ? (
         %{ ${*$ftp}{net_ftp_tlsargs} },
         SSL_startHandshake => 0,
@@ -1035,6 +1043,7 @@ sub _dataconn {
       PeerAddr  => $pasv->[0],
       PeerPort  => $pasv->[1],
       LocalAddr => ${*$ftp}{net_ftp_localaddr},
+      $family_key => ${*$ftp}{net_ftp_domain},
       Timeout   => $ftp->timeout,
       can_ssl() ? (
         SSL_startHandshake => 0,
@@ -1435,10 +1444,15 @@ Net::FTP - FTP Client class
 =head1 DESCRIPTION
 
 C<Net::FTP> is a class implementing a simple FTP client in Perl as
-described in RFC959.  It provides wrappers for a subset of the RFC959
-commands.
+described in RFC959.  It provides wrappers for the commonly used subset of the
+RFC959 commands.
+If L<IO::Socket::IP> or L<IO::Socket::INET6> is installed it also provides
+support for IPv6 as defined in RFC2428.
+And with L<IO::Socket::SSL> installed it provides support for implicit FTPS
+and explicit FTPS as defined in RFC4217.
 
-The Net::FTP class is a subclass of Net::Cmd and IO::Socket::INET.
+The Net::FTP class is a subclass of Net::Cmd and (depending on avaibility) of
+IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
 
 =head1 OVERVIEW
 
@@ -1539,8 +1553,15 @@ simply invokes the C<hash()> method for you, so that hash marks
 are displayed for all transfers.  You can, of course, call C<hash()>
 explicitly whenever you'd like.
 
-B<LocalAddr> - Local address to use for all socket connections, this
-argument will be passed to L<IO::Socket::INET>
+B<LocalAddr> - Local address to use for all socket connections. This
+argument will be passed to the super class, i.e. L<IO::Socket::INET>
+or L<IO::Socket::IP>.
+
+B<Domain> - Domain to use, i.e. AF_INET or AF_INET6. This
+argument will be passed to the IO::Socket super class.
+This can be used to enforce IPv4 even with L<IO::Socket::IP>
+which would default to IPv6.
+B<Family> is accepted as alternative name for B<Domain>.
 
 If the constructor fails undef will be returned and an error message will
 be in $@
@@ -1592,8 +1613,8 @@ Only C<LEVEL>s "C" (clear) and "P" (private) are supported.
 
 =item host ()
 
-Returns the value used by the constructor, and passed to IO::Socket::INET,
-to connect to the host.
+Returns the value used by the constructor, and passed to the IO::Socket super
+class to connect to the host.
 
 =item account( ACCT )
 
diff --git a/lib/Net/NNTP.pm b/lib/Net/NNTP.pm
index 120292c..2387700 100644
--- a/lib/Net/NNTP.pm
+++ b/lib/Net/NNTP.pm
@@ -35,16 +35,19 @@ my $nossl_warn = !$ssl_class &&
   'To use SSL please install IO::Socket::SSL with version>=2.007';
 
 # Code for detecting if we can use IPv6
+my $family_key = 'Domain';
 my $inet6_class = eval {
   require IO::Socket::IP;
   no warnings 'numeric';
-  IO::Socket::IP->VERSION(0.20);
+  IO::Socket::IP->VERSION(0.20) || die;
+  $family_key = 'Family';
 } && 'IO::Socket::IP' || eval {
   require IO::Socket::INET6;
   no warnings 'numeric';
   IO::Socket::INET6->VERSION(2.62);
 } && 'IO::Socket::INET6';
 
+
 sub can_ssl   { $ssl_class };
 sub can_inet6 { $inet6_class };
 
@@ -81,9 +84,10 @@ sub new {
     $connect{$_} = $arg{$_} for(grep { m{^SSL_} } keys %arg);
   }
 
-  foreach my $o (qw(LocalAddr Timeout)) {
+  foreach my $o (qw(LocalAddr LocalPort Timeout)) {
     $connect{$o} = $arg{$o} if exists $arg{$o};
   }
+  $connect{$family_key} = $arg{Domain} || $arg{Family};
   $connect{Timeout} = 120 unless defined $connect{Timeout};
   $connect{PeerPort} = $arg{Port} || 'nntp(119)';
   foreach my $h (@{$hosts}) {
@@ -799,8 +803,11 @@ Net::NNTP - NNTP Client class
 
 C<Net::NNTP> is a class implementing a simple NNTP client in Perl as described
 in RFC977 and RFC4642.
+With L<IO::Socket::SSL> installed it also provides support for implicit and
+explicit TLS encryption, i.e. NNTPS or NNTP+STARTTLS.
 
 The Net::NNTP class is a subclass of Net::Cmd and IO::Socket::INET.
+IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
 
 =head1 CONSTRUCTOR
 
@@ -843,10 +850,12 @@ so that the remote server becomes innd. If the C<Reader> option is given
 with a value of zero, then this command will not be sent and the
 connection will be left talking to nnrpd.
 
-B<LocalAddr> - If multiple IP addresses are present on the client host
-with a valid route to the destination, you can specify the address your
-C<Net::NNTP> connects from and this way override the operating system's
-pick.
+B<LocalAddr> and B<LocalPort> - These parameters are passed directly
+to IO::Socket to allow binding the socket to a a specific local addr and port.
+
+B<Domain> - This parameter is passed directly to IO::Socket and makes it
+possible to enforce IPv4 connections even if L<IO::Socket::IP> is used as super
+class. Alternatively B<Family> can be used.
 
 =back
 
diff --git a/lib/Net/POP3.pm b/lib/Net/POP3.pm
index 7a371d3..b523348 100644
--- a/lib/Net/POP3.pm
+++ b/lib/Net/POP3.pm
@@ -34,16 +34,19 @@ my $nossl_warn = !$ssl_class &&
   'To use SSL please install IO::Socket::SSL with version>=2.007';
 
 # Code for detecting if we can use IPv6
+my $family_key = 'Domain';
 my $inet6_class = eval {
   require IO::Socket::IP;
   no warnings 'numeric';
-  IO::Socket::IP->VERSION(0.20);
+  IO::Socket::IP->VERSION(0.20) || die;
+  $family_key = 'Family';
 } && 'IO::Socket::IP' || eval {
   require IO::Socket::INET6;
   no warnings 'numeric';
   IO::Socket::INET6->VERSION(2.62);
 } && 'IO::Socket::INET6';
 
+
 sub can_ssl   { $ssl_class };
 sub can_inet6 { $inet6_class };
 
@@ -63,7 +66,6 @@ sub new {
   }
   my $hosts = defined $host ? [$host] : $NetConfig{pop3_hosts};
   my $obj;
-  my @localport = exists $arg{ResvPort} ? (LocalPort => $arg{ResvPort}) : ();
 
   if ($arg{SSL}) {
     # SSL from start
@@ -78,7 +80,9 @@ sub new {
       PeerAddr => ($host = $h),
       PeerPort => $arg{Port} || 'pop3(110)',
       Proto => 'tcp',
-      @localport,
+      $family_key => $arg{Domain} || $arg{Family},
+      LocalAddr => $arg{LocalAddr},
+      LocalPort => exists($arg{ResvPort}) ? $arg{ResvPort} : $arg{LocalPort},
       Timeout => $arg{Timeout},
       )
       and last;
@@ -623,12 +627,16 @@ Net::POP3 - Post Office Protocol 3 Client class (RFC1939)
 This module implements a client interface to the POP3 protocol, enabling
 a perl5 application to talk to POP3 servers. This documentation assumes
 that you are familiar with the POP3 protocol described in RFC1939.
+With L<IO::Socket::SSL> installed it also provides support for implicit and
+explicit TLS encryption, i.e. POP3S or POP3+STLS.
 
 A new Net::POP3 object must be created with the I<new> method. Once
 this has been done, all POP3 commands are accessed via method calls
 on the object.
 
-The Net::POP3 class is a subclass of Net::Cmd and IO::Socket::INET.
+The Net::POP3 class is a subclass of Net::Cmd and (depending on avaibility) of
+IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
+
 
 =head1 CONSTRUCTOR
 
@@ -659,9 +667,14 @@ upgrade with C<starttls>.
 You can use SSL arguments as documented in L<IO::Socket::SSL>, but it will
 usually use the right arguments already.
 
-B<ResvPort> - If given then the socket for the C<Net::POP3> object
-will be bound to the local port given using C<bind> when the socket is
-created.
+B<LocalAddr> and B<LocalPort> - These parameters are passed directly
+to IO::Socket to allow binding the socket to a a specific local addr and port.
+For compatibility with older versions B<ResvPort> can be used instead of
+B<LocalPort>.
+
+B<Domain> - This parameter is passed directly to IO::Socket and makes it
+possible to enforce IPv4 connections even if L<IO::Socket::IP> is used as super
+class. Alternatively B<Family> can be used.
 
 B<Timeout> - Maximum time, in seconds, to wait for a response from the
 POP3 server (default: 120)
diff --git a/lib/Net/SMTP.pm b/lib/Net/SMTP.pm
index e200e37..ca6d95b 100644
--- a/lib/Net/SMTP.pm
+++ b/lib/Net/SMTP.pm
@@ -35,10 +35,12 @@ my $nossl_warn = !$ssl_class &&
   'To use SSL please install IO::Socket::SSL with version>=2.007';
 
 # Code for detecting if we can use IPv6
+my $family_key = 'Domain';
 my $inet6_class = eval {
   require IO::Socket::IP;
   no warnings 'numeric';
-  IO::Socket::IP->VERSION(0.20);
+  IO::Socket::IP->VERSION(0.20) || die;
+  $family_key = 'Family';
 } && 'IO::Socket::IP' || eval {
   require IO::Socket::INET6;
   no warnings 'numeric';
@@ -80,6 +82,7 @@ sub new {
       PeerPort => $arg{Port} || 'smtp(25)',
       LocalAddr => $arg{LocalAddr},
       LocalPort => $arg{LocalPort},
+      $family_key => $arg{Domain} || $arg{Family},
       Proto     => 'tcp',
       Timeout   => $arg{Timeout}
       )
@@ -651,12 +654,12 @@ Net::SMTP - Simple Mail Transfer Protocol Client
 This module implements a client interface to the SMTP and ESMTP
 protocol, enabling a perl5 application to talk to SMTP servers. This
 documentation assumes that you are familiar with the concepts of the
-SMTP protocol described in RFC821.
+SMTP protocol described in RFC2821.
+With L<IO::Socket::SSL> installed it also provides support for implicit and
+explicit TLS encryption, i.e. SMTPS or SMTP+STARTTLS.
 
-A new Net::SMTP object must be created with the I<new> method. Once
-this has been done, all SMTP commands are accessed through this object.
-
-The Net::SMTP class is a subclass of Net::Cmd and IO::Socket::INET.
+The Net::SMTP class is a subclass of Net::Cmd and (depending on avaibility) of
+IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
 
 =head1 EXAMPLES
 
@@ -734,7 +737,11 @@ You can use SSL arguments as documented in L<IO::Socket::SSL>, but it will
 usually use the right arguments already.
 
 B<LocalAddr> and B<LocalPort> - These parameters are passed directly
-to IO::Socket to allow binding the socket to a local port.
+to IO::Socket to allow binding the socket to a a specific local addr and port.
+
+B<Domain> - This parameter is passed directly to IO::Socket and makes it
+possible to enforce IPv4 connections even if L<IO::Socket::IP> is used as super
+class. Alternatively B<Family> can be used.
 
 B<Timeout> - Maximum time, in seconds, to wait for a response from the
 SMTP server (default: 120)