Subject: | constructor returns true on failure |
my $sftp = Net::SFTP::Foreign->new($host)
or die "$host: connect failed\n";
will not have the expected result because your code still returns true even when the connection fails. I can see arguments in favor of this approach (i.e. making all the error handling code look consistent), but I believe it is inconsistent with how most network libraries handle their constructors. (Maybe I'm wrong. Find some examples that follow your approach.)
More importantly, your documentation for new() doesn't describe this behavior, but only hints at it by saying "An explicit check for errors should be included always after the constructor call."