#+TITLE: Guile-SSH Architecture
#+STARTUP: content hidestars

Copyright (C) Artyom V. Poptsov <poptsov.artyom@gmail.com>

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

* Architecture
The main goal of this project is to provide a [[https://www.gnu.org/software/guile/][GNU Guile]] (Scheme) interface to
[[https://www.libssh.org/][libssh]] library which in turn implements [[https://en.wikipedia.org/wiki/Secure_Shell][SSH protocol]] (RFC 4250 and others.)

There are two main reasons that Guile-SSH uses libssh:

1. It was originally started as a wrapper to the libssh.

2. It's not easy to do the implementation of SSH protocol right; as it is the
   foundation for secure communication there's a great burden of maintaining
   the security of the code.  =libssh= has comprehensive testing, it is passed
   at least one [[https://www.libssh.org/2019/12/10/libssh-0-9-3-and-libssh-0-8-8-security-release/][security audit]] and it has many users.

In addition to the basic SSH client/server API (provided by libssh itself)
Guile-SSH provides high-level procedures for operations over SSH channels.

The project is split into two parts: a C library (=libguile-ssh=) and a Scheme
=ssh= library.

** Versioning
Guile-SSH uses [[https://semver.org/][semantic versioning]].

Starting from the version 1.0.0, the format is =MAJOR.MINOR.PATCH=, where the
rules for incrementing each part are:

- =MAJOR= version is incremented when incompatible API changes are introduced.
- =MINOR= version is incremented when some functionality is added in a
  backward compatible manner.
- =PATCH= version is incremented when backward compatible bug fixes are
  introduced.

** Code Map
*** Overview
C library code is in =libguile-ssh= directory.  All the GNU Guile modules are
in =modules= directory.

Files are usually installed according to the prefix specified to =configure=
script (=/usr/local= by default.)

Auxiliary files include:
- =AUTHORS= contains list of people who contributed to the library
  development.
- =COPYING= contains the terms of GNU General Public License.
- =INSTALL= contains general instructions for building/installing of
  Guile-SSH.
- =NEWS= describes user-visible changes.
- =TODO= contains plans for the further development and list of known bugs.

*** C API
C API is not public at the moment as it is not important for the task
Guile-SSH tries accomplish.

Nevertheless public and stable C API might be advantageous in some situations
like writing other low-level Scheme libraries or low-level Guile-SSH testing.

Each SMOB (Small Object) -- a GNU Guile object described in C -- is split into
three files:
- =*-type.c= contains the implementation of a SMOB and some very basic
  procedures for it.
- =*-func.c= contains the most of the procedures for working with that SMOB.
- =*-main.c= contains the =init= procedure that initializes the SMOB.

There are some common procedures that are written in separate files not
related to any SMOB (like =log= procedures.)

All C code compiles into a =libguile-ssh.so= shared library that is being
copied into the target system during the installation process.

*** Scheme API
Scheme API is public and should be kept stable when it's possible.  When this
API changes a note must be issued in the =NEWS= file.

All Scheme module source files are in =modules/ssh= directory.

Scheme modules are being installed into =${GUILE_SITE}/ssh= directory on the
target system.  All the modules will be compiled and produced =.go= files will
be installed to =site-ccache= directory which is something like this:
=${libdir}/guile/3.0/site-ccache/ssh/=.

Guile-SSH includes the following Guile modules:
- =auth.scm=    -- User authentication.
- =agent.scm=   -- Interaction with SSH authentication agent instances.
- =channel.scm= -- Channel manipulation.
- =dist.scm=    -- Distributed forms.
  - =dist/job.scm=  -- Low-level distributed job API.
  - =dist/node.scm= -- Low-level distributed node API.
- =key.scm=     -- Keys management.
- =log.scm=     -- Interface to libssh logging facilities
- =message.scm= -- Procedures for working with SSH messages.
- =popen.scm=   -- Remote popen API.
- =server.scm=  -- Server API.
- =session.scm= -- Session management.
- =sftp.scm=    -- SFTP client API.
- =shell.scm=   -- High-level API to a remote shell.
- =tunnel.scm=  -- SSH tunnels.
- =version.scm= -- Information about versions.

*** Examples
Examples are important as they provide a hint how the library can be used for
real tasks.

Guile-SSH examples are stored in =examples= directory in the root of the
repository.

Examples are being copied into =${prefix}/share/guile-ssh/examples= directory
during the installation process.

*** Tests
Tests are in =tests= directory.  They are written using SRFI-61.

When a new functionality is being added a new test case (or several test
cases) should be written for it.

Tests are using SSH client and a server written in Guile-SSH from =examples=.

*** Documentation
Documentation is written in Texinfo format and can be found in =doc=
directory.  It compiles into =guile-ssh.info= Info file and is being copied
into =${prefix}/share/info/= during the installation process.

