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 )