How rkitover/net-ssh2 works
Project Type and Purpose
• This is a Perl CPAN library (Net::SSH2) providing an interface to the native C libssh2 library. Its purpose is to allow Perl applications to perform SSH2 operations (connect, authenticate, open channels, use SFTP/SCP) by calling high-level Perl methods that are implemented via an XS glue layer to the underlying libssh2 C API.
Top-Level Components
a. Client Application
• Any Perl script or module that uses Net::SSH2 (for example files in the example/ directory).
b. Perl API Layer
• Pure-Perl modules under lib/Net/SSH2/*.pm (e.g. Channel.pm, SFTP.pm, PublicKey.pm, KnownHosts.pm). These define the object interface and high-level method dispatch.
c. XS Glue Layer
• The SSH2.xs file and typemap that bind Perl method calls to the corresponding libssh2 C functions.
d. Native Library
• The external libssh2 library (linked at build time via Makefile.PL) and its dependencies (OpenSSL or libgcrypt).
e. Network/Remote Server
• The actual SSH2 server that Net::SSH2 communicates with over TCP.
Relationships & Data Flow
• The Client Application imports Net::SSH2 modules ➔ calls Perl API methods.
• Perl API methods dispatch into the XS Glue Layer ➔ which marshals arguments and calls C functions in libssh2.
• libssh2 invokes crypto libraries (OpenSSL/libgcrypt) as needed for key exchange, encryption, compression.
• libssh2 communicates over the network (TCP) with the remote SSH2 server ➔ handles packets, channels, SFTP requests.
• Responses bubble back up through libssh2 ➔ XS Glue ➔ Perl API ➔ back to the Client Application.
Architectural Patterns & Design Principles
• Layered Architecture: clear separation between high-level Perl interface, XS binding, and native C library.
• Modular Organization: each SSH concept (Channel, SFTP, KnownHosts, etc.) is isolated in its own Perl module.
• Foreign Function Interface (FFI/XS) pattern: XS layer as the bridge between Perl and C.
• Test Harness: automated tests under t/ ensure interface stability; example/ scripts demonstrate usage.
f. A build step inset showing Makefile.PL invoking the XS compiler and linking to libssh2.
g. Test suite (t/) and example directory as side components to show validation and usage.