File Coverage

=head1 NAME

App::FileSync::Server - serve one sync session against a repo's master

=head1 SYNOPSIS

        my $server = App::FileSync::Server->new(
                root => '/srv/filesync', repo => 'docs', client => 'laptop', role => 'client',
                connection => App::FileSync::Protocol->new(in => \*STDIN, out => \*STDOUT),
        );
        exit($server->run ? 0 : 1);

=head1 DESCRIPTION

A session is: hello, manifest, plan, then the transfers the plan lists, then
C<done>.  The server holds the repo lock throughout, so sessions on one repo
never interleave.  It updates the master index and the client's base only in
C<done>, after every planned action has been applied; a session that dies part
way leaves both as they were, and the next session replans from the tree.

=head1 METHODS

=head2 new

Purpose: prepare a session.

Args: C<root>, C<repo>, C<client>, C<role> (C<client> or C<replica>),
C<connection> (an L<App::FileSync::Protocol>), optional C<logger> and
C<language>.

Returns: the server object.

Side Effects: builds a logger from the settings when none is given.

Usage:

        my $server = App::FileSync::Server->new(%pinned, connection => $connection);

=head3 EXAMPLE

        my $server = App::FileSync::Server->new(
                root => $root, repo => 'docs', client => 'laptop', role => 'client', connection => $conn,
        );

=head3 API SPECIFICATION

=head4 INPUT

        {
                root       => { type => 'string', min => 1 },
                repo       => { type => 'string', min => 1, max => 64 },
                client     => { type => 'string', min => 1, max => 64 },
                role       => { type => 'string', memberof => [ 'client', 'replica' ] },
                connection => { type => 'object', can => [ 'send', 'recv' ] },
                logger     => { type => 'object', optional => 1 },
                language   => { type => 'string', optional => 1 },
        }

=head4 OUTPUT

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

=head3 MESSAGES

        Key                  Meaning                         Resolution
        server.missing       a required argument is absent   pass it
        server.bad_role      role is not client or replica   fix the forced command
        server.bad_id        repo or client is not an id     fix the forced command
        server.no_connection no connection was given         pass connection

=head3 FORMAL SPECIFICATION

        pre root ≠ "" ∧ repo ∈ Id ∧ client ∈ Id ∧ role ∈ {client, replica} ∧ connection ≠ ⊥
        post finished = 0 ∧ plan = ∅ ∧ uploads = ∅

=cut

=head2 run

Purpose: serve the whole session.

Args: none.

Returns: 1 when the session finished, 0 when it failed (the client has been
sent the error).

Side Effects: takes the repo lock; reads and writes the master, its index, the
client's base, the trash and the journal; prunes the trash and removes stale
temporaries.  A failed session is journalled (exit 2 for a lock refusal,
otherwise 1) unless it never got as far as opening the repo.

Usage:

        exit($server->run ? 0 : 1);

=head3 EXAMPLE

        my $ok = $server->run;
        warn "session failed\n" unless $ok;

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

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

=head3 MESSAGES

        Key                    Meaning                             Resolution
        server.locked          another session holds the lock      the client retries later
        server.not_allowed     the client is not registered        filesync-admin client allow
        server.wrong_role      the client is registered otherwise  fix the key's --role
        server.proto           the client speaks another protocol  upgrade one side
        server.pinned          the hello disagrees with the pin    fix the client config
        server.unknown         an unknown command arrived          upgrade one side

Raised once the session is open.  Each ends the session: the open uploads
are discarded, the failure is journalled, and the text (without Perl's
file and line) reaches the client as C<< { ok => 0, fatal => 1, error => ... } >>.
Most mean a client bug or a hostile client; the resolution is to fix the
client, or simply to rerun the sync.

        Key                     Meaning
        server.manifest_list    the manifest is not a list
        server.manifest_entry   a manifest entry is not an object
        server.manifest_path    a manifest path is unsafe
        server.manifest_field   a manifest t, h, s, m or mode field is malformed
        server.refused          the deletion guard stopped the plan (rerun with --force if intended)
        server.unplanned        an operation names a path that is not in the plan
        server.not_planned      the path's planned action does not allow this operation
        server.bad_field        an off, max, len, s, mode or h field is malformed
        server.conflict_name    the conflict copy is named other than the plan says
        server.conflict_unsafe  the planned conflict name is not a safe path
        server.conflict_same    the planned conflict name equals the path
        server.conflict_exists  something already exists at the conflict name
        server.conflict_move    the master's copy could not be moved aside
        server.bad_ack          an ack disagrees with the planned action
        server.busy             a second put for a path already being received
        server.no_put           chunk or chunk_end without a put
        server.too_large        one chunk is larger than the chunk limit
        server.overflow         the upload is larger than its announced size
        server.hash_mismatch    the received content does not have the announced hash
        server.size_mismatch    the received content does not have the announced size
        server.no_delta         delta data without a delta start
        server.bad_copy         a delta copy reaches outside the base file
        server.bad_signature    a pull signature is malformed
        server.no_signature     a pull delta operation without a signature
        server.cannot_stat      a planned file vanished from the master
        server.not_file         a get for a path that is a directory
        server.unfinished       done arrived before every planned action completed

=head3 FORMAL SPECIFICATION

        Î”FS
        run = 1 ⇔ hello ⨾ open ⨾ lock ⨾ loop ⨾ done succeed
        run = 0 ⇒ index' = index ∧ base' = base

=head3 PSEUDOCODE

        read and check the hello against the pinned arguments
        open the repo; check the client is allowed in its role
        take the lock (refuse with code "locked" otherwise)
        load the index and the client's base; tidy temporaries and the trash
        send the policy, then serve commands until done
        on any error: log it, journal the failed session, discard partial
        uploads, and send the error to the client

=cut

=head2 validate_forced_command

Purpose: check the command a client asked sshd to run against the arguments
pinned in F<authorized_keys>.

The pinned arguments are the authority for a session.  sshd passes the command
the client asked for in C<SSH_ORIGINAL_COMMAND>; it must agree with the pinned
repo, client, role and protocol and ask for nothing else: in particular it may
not choose its own C<--root>.

Args: C<$original> (the requested command; undef or blank is accepted),
C<\%pinned> (C<repo>, C<client>, C<role>).

Returns: C<(1, undef)> or C<(0, $reason)>.  A list, deliberately: callers
write C<my ($ok, $why) = ...>, matching L<App::FileSync/validate_relpath>.

Side Effects: none.

Usage:

        my ($ok, $reason) = App::FileSync::Server::validate_forced_command($ENV{SSH_ORIGINAL_COMMAND}, \%pinned);

=head3 EXAMPLE

        my ($ok, $why) = App::FileSync::Server::validate_forced_command(
                'filesync-server --repo docs --client laptop --role client --proto 2',
                { repo => 'docs', client => 'laptop', role => 'client' },
        );      # (1, undef)

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'original', type => 'string', optional => 1 },
                { name => 'pinned',   type => 'hashref' },
        ]

=head4 OUTPUT

        { type => 'arrayref', min => 2, max => 2 }     # returned as a two-element list

=head3 MESSAGES

        Key                   Meaning
        forced.program        the command runs some other program
        forced.argument       a token is not a --flag
        forced.no_value       a flag has no value
        forced.flag           the flag is not repo, client, role or proto
        forced.proto          the protocol differs from this server's
        forced.pinned         the value differs from the pinned one

=head3 FORMAL SPECIFICATION

        let ts = tokens(original)
        ok ⇔ (ts = ⟨⟩) ∨ ((head ts ∈ FLAG ∨ basename(head ts) = filesync-server) ∧
              âˆ€ (f, v) : flags(ts) • f ∈ {repo, client, role, proto} ∧
              (f = proto ⇒ v = PROTO) ∧ (f ≠ proto ⇒ v = pinned(f)))

=head3 PSEUDOCODE

        accept an empty command
        split on white space; allow a leading filesync-server path
        for each --flag[=value] (value from the next token if not attached):
                reject an unknown flag, a missing value, a wrong protocol
                reject a value that differs from the pinned one

=cut