App-FileSync
view release on metacpan or search on metacpan
lib/App/FileSync/Transport/SSH.pm view on Meta::CPAN
# Host key policies a repo may choose.
Readonly my @HOST_KEY_CHECKING => qw(yes accept-new);
# The highest TCP port.
Readonly my $MAX_PORT => 65_535;
# Characters that would end or split an argument.
Readonly my $UNSAFE_ARG => qr/[\0\n]/;
# user@host, host, or a bracketed IPv6 literal. Both the user and the host
# start with a letter or digit, so neither can be read as an ssh option.
Readonly my $SERVER => qr/\A(?:[A-Za-z0-9][A-Za-z0-9._-]*@)?
(?:[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?|\[[0-9A-Fa-f:]+\])\z/x;
# A remote program path: only characters inert in a POSIX shell, and not
# starting with '-'.
Readonly my $PROGRAM => qr{\A[A-Za-z0-9._/][A-Za-z0-9._/-]*\z};
=encoding utf8
=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
sub new {
my $class = shift;
my $args = named(\@_, {
map({ $_ => { type => 'string', optional => 1 } }
qw(server repo client role server_command host_key_checking known_hosts identity port command)),
extra_args => { type => 'arrayref', optional => 1 },
}, 'Transport::SSH->new');
for my $required (qw(server repo client)) {
throw('transport.missing', { transport => 'SSH', what => $required })
( run in 1.406 second using v1.01-cache-2.11-cpan-99fa8243a42 )