# rkitover/net-ssh2 architecture

> Architecture diagram of the GitHub repository rkitover/net-ssh2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rkitover/net-ssh2
- Repository: https://github.com/rkitover/net-ssh2

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application Layer
    subgraph "Client Application" 
        direction TB
        ClientApp["Perl Scripts (example/)"]:::client
    end

    %% Perl API Layer
    subgraph "Perl API Layer"
        direction TB
        Core["Net::SSH2.pm"]:::perlapi
        Channel["Channel.pm"]:::perlapi
        Dir["Dir.pm"]:::perlapi
        File["File.pm"]:::perlapi
        KnownHosts["KnownHosts.pm"]:::perlapi
        Listener["Listener.pm"]:::perlapi
        PublicKey["PublicKey.pm"]:::perlapi
        SFTP["SFTP.pm"]:::perlapi
    end

    %% XS Glue Layer
    subgraph "XS Glue Layer"
        direction TB
        XS["SSH2.xs"]:::xs
        Typemap["typemap"]:::xs
        PPPort["ppport.h"]:::xs
    end

    %% Native Libraries Layer
    subgraph "Native Libraries"
        direction TB
        LibSSH2["libssh2"]:::ext
        Crypto["OpenSSL / libgcrypt"]:::ext
    end

    %% Build & Utilities
    subgraph "Build & Utilities"
        direction TB
        Makefile["Makefile.PL"]:::xs
        GenConst["gen_constants.pl"]:::xs
        TestHarness["Test Suite (t/)"]:::client
    end

    %% Network / Remote Server
    SSHServer["SSH2 Server (TCP)"]:::network

    %% Runtime Flow
    ClientApp -->|"use Net::SSH2" | Core
    Core -->|"calls method"| XS
    Channel -->|"calls method"| XS
    Dir -->|"calls method"| XS
    File -->|"calls method"| XS
    KnownHosts -->|"calls method"| XS
    Listener -->|"calls method"| XS
    PublicKey -->|"calls method"| XS
    SFTP -->|"calls method"| XS
    XS -->|"libssh2_* functions"| LibSSH2
    LibSSH2 -->|"crypto ops"| Crypto
    LibSSH2 -->|"<--> SSH packets"| SSHServer

    %% Build Flow
    Makefile -.->|"generate XS stubs"| XS
    Makefile -.->|"link against"| LibSSH2
    GenConst -.->|"generate constants"| Core

    %% Test & Examples
    TestHarness -->|"validates API"| Core
    ClientApp -->|"demonstrate usage"| TestHarness

    %% Click Events
    click ClientApp "https://github.com/rkitover/net-ssh2/tree/master/example/"
    click Core "https://github.com/rkitover/net-ssh2/blob/master/lib/Net/SSH2.pm"
    click Channel "https://github.com/rkitover/net-ssh2/blob/master/lib/Net/SSH2/Channel.pm"
    click Dir "https://github.com/rkitover/net-ssh2/blob/master/lib/Net/SSH2/Dir.pm"
    click File "https://github.com/rkitover/net-ssh2/blob/master/lib/Net/SSH2/File.pm"
    click KnownHosts "https://github.com/rkitover/net-ssh2/blob/master/lib/Net/SSH2/KnownHosts.pm"
    click Listener "https://github.com/rkitover/net-ssh2/blob/master/lib/Net/SSH2/Listener.pm"
    click PublicKey "https://github.com/rkitover/net-ssh2/blob/master/lib/Net/SSH2/PublicKey.pm"
    click SFTP "https://github.com/rkitover/net-ssh2/blob/master/lib/Net/SSH2/SFTP.pm"
    click XS "https://github.com/rkitover/net-ssh2/blob/master/SSH2.xs"
    click Typemap "https://github.com/rkitover/net-ssh2/tree/master/typemap"
    click Makefile "https://github.com/rkitover/net-ssh2/blob/master/Makefile.PL"
    click GenConst "https://github.com/rkitover/net-ssh2/blob/master/util/gen_constants.pl"
    click TestHarness "https://github.com/rkitover/net-ssh2/tree/master/t/"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef perlapi fill:#90EE90,stroke:#333,stroke-width:1px
    classDef xs fill:#FFA500,stroke:#333,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef network fill:#F0F0F0,stroke:#333,stroke-width:1px
```
