File Coverage

=head1 NAME

App::FileSync::Merge - three-way merge of base, client and master manifests

=head1 SYNOPSIS

        my $plan = App::FileSync::Merge::plan(
                base => $base, client => $client, master => $master,
                client_id => 'laptop-1', role => 'client', now => time,
        );
        my $refusal = App::FileSync::Merge::check_delete_limit(
                deletions => $plan->{deletions}, base_size => scalar(keys %$base),
        );

=head1 FUNCTIONS

=head2 plan

Purpose: decide, path by path, what a session must do.

Args: C<base>, C<client>, C<master> (manifests: path =E<gt> entry, see
L<App::FileSync::Scan>), C<client_id>, C<role> (C<client> or C<replica>),
C<now> (the epoch used in conflict-copy names).

Returns: a hashref C<{ actions, warnings, deletions, conflicts }>.  Actions are
hashes with C<a> (pull, push, delete_local, delete_remote or conflict) and
C<p> (the path); deletions come first, so a type change never writes over a
directory.  Warnings are translated sentences.

Side Effects: none.

Usage:

        my $plan = App::FileSync::Merge::plan(%manifests, client_id => $id);

=head3 EXAMPLE

        my $plan = App::FileSync::Merge::plan(
                base   => {},
                client => { 'a.txt' => { t => 'f', h => 'aa' } },
                master => {},
        );
        print $plan->{actions}[0]{a}, "\n";        # push

=head3 API SPECIFICATION

=head4 INPUT

        {
                base      => { type => 'hashref', optional => 1 },
                client    => { type => 'hashref', optional => 1 },
                master    => { type => 'hashref', optional => 1 },
                client_id => { type => 'string', optional => 1 },
                role      => { type => 'string', memberof => [ 'client', 'replica' ], optional => 1 },
                now       => { type => 'number', optional => 1 },
        }

=head4 OUTPUT

        {
                type => 'hashref',
                schema => {
                        actions   => { type => 'arrayref' },
                        warnings  => { type => 'arrayref' },
                        deletions => { type => 'integer', min => 0 },
                        conflicts => { type => 'integer', min => 0 },
                },
        }

=head3 MESSAGES

Warnings (returned, not raised):

        Key                            Meaning
        merge.deleted_changed          deleted on the client, changed on the master; master copy restored
        merge.changed_deleted          changed on the client, deleted on the master; client copy restored
        merge.conflict_copy            changed on both; loser kept as a conflict copy
        merge.conflict_dir             changed on both; an empty directory lost
        merge.replica_overwritten      a replica's local edit was overwritten
        merge.replica_removed          a replica's extra file was removed

=head3 FORMAL SPECIFICATION

        B, A, M : PATH ⇸ ENTRY      (base, client, master)
        âˆ€ p ∈ dom B ∪ dom A ∪ dom M •
                p ∉ dom A ∧ p ∉ dom M                     â‡’ no action
                p ∉ dom A ∧ same(M p, B p)                â‡’ delete_remote p
                p ∉ dom A ∧ ¬same(M p, B p)               â‡’ pull p
                p ∉ dom M ∧ same(A p, B p)                â‡’ delete_local p
                p ∉ dom M ∧ ¬same(A p, B p)               â‡’ push p
                same(A p, M p)                            â‡’ no action
                same(A p, B p)                            â‡’ pull p
                same(M p, B p)                            â‡’ push p
                otherwise                                 â‡’ conflict p
        role = replica ⇒ actions ⊆ {pull, delete_local}

=head3 PSEUDOCODE

        if replica: mirror the master and return
        for each path in base, client or master, sorted:
                apply the table above, adding a warning where one side's change
                is undone or a conflict copy is made
        put deletions before transfers
        count deletions and conflicts

=cut

=head2 check_delete_limit

Purpose: guard against a misconfigured client (or an empty mount) wiping the
master.

Args: C<deletions> (planned), C<base_size> (files known at the last sync),
C<max_deletes> (default 200; 0 disables), C<max_delete_percent> (default 10;
0 disables), C<force>.

Returns: C<undef> when the plan is acceptable, or a translated sentence
explaining the refusal.  At least one deletion is always allowed, so a small
repo stays usable.

Side Effects: none.

Usage:

        my $refusal = App::FileSync::Merge::check_delete_limit(%counts, force => $force);

=head3 EXAMPLE

        my $why = App::FileSync::Merge::check_delete_limit(deletions => 300, base_size => 1000);
        print "$why\n" if defined $why;       # refusing to delete 300 files (limit is 200); ...

=head3 API SPECIFICATION

=head4 INPUT

        {
                deletions          => { type => 'integer', min => 0, optional => 1 },
                base_size          => { type => 'integer', min => 0, optional => 1 },
                max_deletes        => { type => 'integer', min => 0, optional => 1 },
                max_delete_percent => { type => 'number', min => 0, optional => 1 },
                force              => { type => 'boolean', optional => 1 },
        }

=head4 OUTPUT

        { type => 'string', optional => 1 }

=head3 MESSAGES

        Key                       Meaning                                Resolution
        merge.too_many            over the absolute limit                --force if intended
        merge.too_many_percent    over the percentage of known files     --force if intended

=head3 FORMAL SPECIFICATION

        allowed(n, k) ⇔ n = 0 ∨ force ∨ ((max = 0 ∨ n ≤ max) ∧ (pct = 0 ∨ k = 0 ∨ n ≤ max(1, ⌊k × pct / 100⌋)))
        check(n, k) = ⊥ if allowed(n, k), reason otherwise

=cut