Salvador Fandino

I have been working on a new release of Net::SSH2 that has undergone mayor, mostly internal, changes.

There are not too many new features. The aim has been to simplify the code, made it reliable and improve the overall consistency and behavior of the module.

Most important changes are as follows:

• Typemaps are used systematically to convert between Perl and C types:

  In previous versions of the library, inputs and specially output values were frequently handled by custom code with every method doing similar things in slightly different ways.

  Now, most of that code has been replaced by typemaps, resulting on a consistent and much saner handling of input and output values.

• Only data in the 'latin1' range is now accepted by Net::SSH2 methods. Previous versions would just get Perl internal representation of the passed data without considering its encoding and push it through libssh2.

  That caused erratic behavior, as that encoding depends on the kind of data, but also on its history and even latin1 data is commonly encoded internally as utf8.

  Now the data is in all cases converted to latin1 before being passed to libssh2. Data outside of the latin1 range just croaks.

• Error handling had also a complete overhaul:

  Before, every Net::SSH2 object was internally maintaining two error states: the one inside libssh2 and other in the Net::SSH2 wrapping layer for errors generated there. Every time the user asked for the error state, both values where combined as ($libssh2_error // $net_ssh2_error) and the resulting value returned to the user.

  That didn't work reliably, because, $libssh2_error behaves as $!. Its value is only to be checked after some operation fails. Otherwise, it is unspecified.

  Fortunately, libssh2 added support for setting the error status from outside the library in version 1.7.0, and now Net::SSH2 uses that and just keeps one error state, in a reliable way.

  Also, some module methods were reporting operational errors as undef, while others were dying. Some could even do one thing or the other depending on the type of error. Now, all of them behave the same and errors are reported returning undef.

  Note that programming errors (e.g. passing wrong arguments to a method), croak.

• XS layer simplification:

  There were several methods in the XS side accepting as input or returning complex Perl data structures which were walked and processed in XS code.

  Now, most of those functions have been broken in two parts: one written in Perl that preprocesses (or postprocesses) the data before given it to an XS part which usually just needs to pass that chewed data to libssh2.

• Method "connect" has been completely rewritten as it was too complex and affected by several bugs:

  It suffered the sometimes-die-sometimes-return-undef-on-error issue.

  Timeout handling didn't take into account the global timeout setting and then it was only influencing the Perl side of the method.

  Accepting a file descriptor number as argument was unreliable and has now been removed.

• Channel methods have also been mostly rewritten and now they behave in a similar fashion to the equivalent Perl built-ins.

  Unfortunately that means introducing some backward incompatible changes, but the old behavior was so broken, that I think it is the right thing to do.

  Actually, most of the code using Net::SSH2 that can be found in PerlMonks or StackOverflow has work-arounds for that (enabling non-blocking mode)... which doesn't work reliably either!

• Pick newer libssh2 functions when possible. For instance, libssh2 functions handling SCP operations got new versions able to handle files bigger than 2GB some releases ago. Those are used when available.
• The build system has been also improved. Now, in most cases it is able to autodetect the crypto backend used by libssh2.
  
• Method "check_hostkey" has been added. Hopefully, that means that more people would start to use the module in a secure way.

• And myriads of other small changes.
• This time, I have also given some love to the documentation. It is not a big overhaul, but I have added lots of little details here and there that are required to operate the module correctly. Specially, those related to libssh2 features that don't really work well yet.
  

Now, I would like to get the module tested also by other people. So, if you want to give me a hand and specially, if you are already one of the module users, you can do as follows:

• Grab the latest development version of the module (currently 0.59_10), build it and run the test script by hand, so that it connects to a real server and runs non trivial tests.
• If you have any scripts of your own using Net::SSH2, try them with the new version, too!
• Extra points for doing it on OS/X, Windows or in not-so-common UNIX platforms like HP-UX or AIX!!!

Cheers!