File Coverage

=head1 NAME

App::FileSync::Transport::SSH - run the server over ssh

=head1 SYNOPSIS

        my $transport = App::FileSync::Transport::SSH->new(
                server => 'filesync@files.example.com', repo => 'docs', client => 'laptop',
                identity => '~/.ssh/filesync_ed25519',
        );
        ...
        $transport->close or warn $transport->error_text;

=head1 METHODS

=head2 new

Purpose: start C<filesync-server> on the server host for one session.

Args: C<server> (C<user@host>, C<host> or C<user@[v6]>), C<repo>, C<client>,
optional C<role> (default C<client>), C<server_command> (default
C<filesync-server>), C<host_key_checking> (C<yes>, the default, or
C<accept-new>), C<known_hosts>, C<identity>, C<port>, C<command> (the local
ssh program), C<extra_args> (arrayref of extra ssh arguments).

Returns: the transport.

Side Effects: runs C<ssh ... SERVER PROGRAM --repo R --client C --role X
--proto 2>.  ssh's standard error goes to a temporary file, never the
protocol pipe, and is available from L</error_text>.  On Windows a C<.cmd> or
C<.bat> ssh wrapper is started through C<COMSPEC>, since CreateProcess cannot
start one directly.

Usage:

        my $transport = App::FileSync::Transport::SSH->new(%args);

=head3 EXAMPLE

        my $t = App::FileSync::Transport::SSH->new(
                server => 'backup', repo => 'photos', client => 'nas', role => 'replica', port => 2222,
        );
        print join(' ', @{ $t->command }), "\n";

=head3 API SPECIFICATION

=head4 INPUT

        {
                server            => { type => 'string', matches => $SERVER },
                repo              => { type => 'string', min => 1, max => 64 },
                client            => { type => 'string', min => 1, max => 64 },
                role              => { type => 'string', optional => 1, memberof => [ 'client', 'replica' ] },
                server_command    => { type => 'string', optional => 1, matches => $PROGRAM },
                host_key_checking => { type => 'string', optional => 1, memberof => [ 'yes', 'accept-new' ] },
                known_hosts       => { type => 'string', optional => 1 },
                identity          => { type => 'string', optional => 1 },
                port              => { type => 'integer', optional => 1, min => 1, max => 65535 },
                command           => { type => 'string', optional => 1 },
                extra_args        => { type => 'arrayref', optional => 1 },
        }

=head4 OUTPUT

        { type => 'object', isa => 'App::FileSync::Transport::SSH' }

=head3 MESSAGES

        Key                  Meaning                                    Resolution
        transport.missing    server, repo or client absent              fix the repo config
        transport.bad_value  a value is unsafe or out of range          fix the repo config or settings
        transport.bad_id     the repo or client is not a plain id       fix the repo config
        io.write             the error file cannot be created           check the temp directory

=head3 FORMAL SPECIFICATION

        pre server ∈ SERVER ∧ repo ∈ Id ∧ client ∈ Id ∧ role ∈ ROLES ∧ program ∈ PROGRAM
            âˆ§ (port = ⊥ ∨ 0 < port ≤ 65535) ∧ ∀ a : extra_args • a ∈ TEXT ∧ '\n' ∉ a
        argv = ⟨ssh⟩ ⁀ options ⁀ ⟨server, program, --repo, repo, --client, client, --role, role, --proto, PROTO⟩

=head3 PSEUDOCODE

        validate every argument
        build ssh's options: fixed ones, host key policy, known hosts, identity,
        port, extra arguments
        append the server, then the remote command
        wrap a .cmd/.bat ssh in COMSPEC on Windows
        start it with standard error going to a temporary file

=cut

=head2 reader

Documented with L</exit_status> below.

=head2 writer

Documented with L</exit_status> below.

=head2 command

Documented with L</exit_status> below.

=head2 exit_status

Purpose: the session's pipes, the argv that was run, and ssh's exit status.

Args: none.

Returns: the read and write handles; a copy of the argv (for C<--verbose> and
tests); the exit status after L</close> (undef before).

Side Effects: none.

Usage:

        my $argv = $transport->command;

=head3 EXAMPLE

        print "ran: @{ $transport->command }\n";

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'self', type => 'object' } ]

=head4 OUTPUT

        { type => 'scalar' }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        command = copy(self.command) ; exit_status = self.status

=cut

=head2 close

Purpose: end the ssh session.

Args: none.

Returns: 1 when ssh exited 0, else 0.  Repeated calls return 1.

Side Effects: closes both pipes, reaps ssh, records its exit status and
signal, and reads what it wrote to standard error.

Usage:

        $transport->close or warn $transport->error_text, "\n";

=head3 EXAMPLE

        unless ($transport->close) {
                printf "ssh exited %d: %s\n", $transport->exit_status, $transport->error_text;
        }

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'self', type => 'object' } ]

=head4 OUTPUT

        { type => 'integer', memberof => [ 0, 1 ] }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        close = 1 ⇔ closed ∨ exit(ssh) = 0

=cut

=head2 error_text

Purpose: what ssh or the remote shell said, for when the protocol failed.

Args: none.

Returns: the text, trimmed, with blank lines collapsed.

Side Effects: reads the error file if L</close> has not yet.

Usage:

        my $why = $transport->error_text;

=head3 EXAMPLE

        print $transport->error_text, "\n";        # "Permission denied (publickey)."

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'self', type => 'object' } ]

=head4 OUTPUT

        { type => 'string' }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        error_text = squeeze(trim(stderr))

=cut

=head2 valid_server

Documented with L</valid_program> below.

=head2 valid_program

Purpose: check a server address and a remote program path.

Args: the value.

Returns: 1 or 0.

A server is C<user@host>, C<host> or C<user@[ipv6]>; the user and host must
start with a letter or digit, so neither can be read as an ssh option (a
leading C<->) and nothing can split into another word.  A program is a path of
letters, digits, C<.>, C<_>, C</> and C<->, not starting with C<->.

Side Effects: none.

Usage:

        die "bad server\n" unless App::FileSync::Transport::SSH::valid_server($server);

=head3 EXAMPLE

        App::FileSync::Transport::SSH::valid_server('filesync@files.example.com');      # 1
        App::FileSync::Transport::SSH::valid_server('-oProxyCommand=sh');               # 0
        App::FileSync::Transport::SSH::valid_server('-v@host');                         # 0

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'value', type => 'string', optional => 1 } ]

=head4 OUTPUT

        { type => 'integer', memberof => [ 0, 1 ] }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        valid_server(v) ⇔ v ∈ SERVER
        valid_program(v) ⇔ v ∈ PROGRAM

=cut