File Coverage

=head1 NAME

App::FileSync::Client - sync one repo, and the client-side repo commands

=head1 SYNOPSIS

        my $config = App::FileSync::Config::load_client();
        my $client = App::FileSync::Client->new(config => $config, name => 'docs', opts => { verbose => 1 });

        my $result = $client->sync;
        exit $result->{exit};

=head1 DESCRIPTION

A sync is one session with the server: hello, manifest, plan, then the
transfers the plan lists, then done.  The client keeps under
F<~/.filesync> (or C<FILESYNC_HOME>):

        cache/NAME.json          the base: what the last successful sync left
        logs/NAME.jsonl          one line per attempt, for "filesync log"
        locks/NAME.lock          held for the whole run
        trash/repos/NAME/Y/M/D/  files the sync deleted or replaced locally

Exit codes: 0 ok, 1 error, 2 another run holds the lock, 3 finished with
warnings (conflicts or skipped paths).

=head1 METHODS

=head2 new

Purpose: a client for one repo of a client configuration.

Args: C<config> (from L<App::FileSync::Config/load_client>), C<name> (the
repo's key in it), optional C<opts> (C<dry_run>, C<force>, C<no_prune>,
C<no_delta>, C<verbose>, C<quiet>), C<logger>, C<settings> (process settings,
read lazily otherwise), C<language>.

Returns: the client.

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

Usage:

        my $client = App::FileSync::Client->new(config => $config, name => 'docs');

=head3 EXAMPLE

        my $client = App::FileSync::Client->new(
                config => $config, name => 'docs', opts => { dry_run => 1 },
        );

=head3 API SPECIFICATION

=head4 INPUT

        {
                config   => { type => 'hashref' },
                name     => { type => 'string', min => 1, max => 64 },
                opts     => { type => 'hashref', optional => 1 },
                logger   => { type => 'object', optional => 1 },
                settings => { type => 'hashref', optional => 1 },
                language => { type => 'string', optional => 1 },
        }

=head4 OUTPUT

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

=head3 MESSAGES

        Key              Meaning                              Resolution
        client.no_config no configuration was given           pass config
        client.bad_name  the repo name is not a plain id      rename the repo in config.json

=head3 FORMAL SPECIFICATION

        pre config ≠ ⊥ ∧ name ∈ Id
        post self.name = name ∧ self.opts = opts ∨ ∅

=cut

=head2 sync

Purpose: run one sync session for the repo.

Args: none (see C<opts> in L</new>).

Returns: C<{ repo, ok, exit, summary, warnings, stats }>; with C<dry_run>,
also C<dry_run =E<gt> 1> and the planned C<actions>.  A lock refusal (here or
on the server) returns C<ok =E<gt> 0, exit =E<gt> 2, locked =E<gt> 1> rather than
raising: cron starting a run while the last one is finishing is normal.

Side Effects: changes the local tree and the master; updates the cache;
prunes this repo's local trash (unless C<no_prune>); appends to the run log,
whatever the outcome.

Usage:

        my $result = App::FileSync::Client->new(%args)->sync;

=head3 EXAMPLE

        my $result = $client->sync;
        printf "pulled %d, pushed %d\n", @{ $result->{summary} }{qw(pulled pushed)};
        print "warning: $_\n" for @{ $result->{warnings} };

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        {
                type => 'hashref',
                schema => {
                        repo     => { type => 'string' },
                        ok       => { type => 'integer', memberof => [ 0, 1 ] },
                        exit     => { type => 'integer', memberof => [ 0, 2, 3 ] },
                        summary  => { type => 'hashref', optional => 1 },
                        warnings => { type => 'arrayref', optional => 1 },
                },
        }

=head3 MESSAGES

        Key                  Meaning                                    Resolution
        client.no_repo       the repo is not in the configuration       filesync init
        client.bad_root      the sync root is not a directory           fix root in config.json
        client.no_marker     the root has no .filesync-root marker      mount the drive, or create the marker
        client.no_client_id  the configuration has no client_id         filesync init
        client.refused       the server refused the session             read the reason
        client.req.*         the server rejected a step                 read the reason
        client.hash_mismatch a transfer arrived corrupted               rerun the sync

=head3 FORMAL SPECIFICATION

        Î”FS
        sync = ⟨exit ↦ 2⟩                              if lock held elsewhere
        sync = ⟨exit ↦ 0 | 3⟩ ∧ local' ≡ master'       if the session completes
        sync raises ∧ base' = base                     otherwise

=head3 PSEUDOCODE

        look up the repo
        run the session (lock, transport, protocol)
        record the attempt in the run log, success or failure
        log a summary; return the result, or re-raise the error

=cut

=head2 log

Purpose: recent run attempts from the local run log.

Args: optional C<limit> (default 20), C<since> and C<until> (C<YYYY-MM-DD>
or epoch, inclusive), C<exits> (an exit code or arrayref of them),
C<warnings> (only runs that recorded a warning, conflict or skipped path).
All filters apply before the limit.

Returns: C<{ repo, path, runs }> (runs oldest first), plus the filters used.

Side Effects: reads the log.  A torn final line from a killed run is skipped.

Usage:

        my $log = $client->log(limit => 5, exits => [ 1, 2 ]);

=head3 EXAMPLE

        for my $run (@{ $client->log(since => '2026-10-01')->{runs} }) {
                print "$run->{ts} exit $run->{exit}\n";
        }

=head3 API SPECIFICATION

=head4 INPUT

        {
                limit    => { type => 'integer', optional => 1 },
                since    => { type => 'string', optional => 1 },
                until    => { type => 'string', optional => 1 },
                exits    => { type => 'arrayref', optional => 1 },     # a lone code is wrapped
                warnings => { type => 'boolean', optional => 1 },
        }

=head4 OUTPUT

        { type => 'hashref', schema => { repo => { type => 'string' }, path => { type => 'string' }, runs => { type => 'arrayref' } } }

=head3 MESSAGES

        Key        Meaning                     Resolution
        when.bad   since/until is malformed    use YYYY-MM-DD or an epoch
        io.read    the log cannot be read      check permissions

=head3 FORMAL SPECIFICATION

        log = last limit ⟨ r ∈ runs | since ≤ r.ts ≤ until ∧ (exits = ∅ ∨ r.exit ∈ exits) ∧ (¬warnings ∨ has_warnings(r)) ⟩

=head3 PSEUDOCODE

        parse the filters
        read each JSON line of the log, skipping torn ones
        keep the runs that pass every filter
        keep the newest limit; report the filters used

=cut

=head2 verify

Purpose: compare the local tree with the base the last successful sync
recorded.  Drift means the tree changed without being synced.

Args: optional C<deep> (hash every file rather than trusting size and mtime).

Returns: the L<App::FileSync::Verify> report, plus C<repo>.

Side Effects: reads the tree; logs a summary.  Works offline: the ignore list
is the one cached by the last sync.

Usage:

        my $report = $client->verify(deep => 1);

=head3 EXAMPLE

        my $report = $client->verify;
        print $report->{ok} ? "clean\n" : scalar(@{ $report->{modified} }) . " modified\n";

=head3 API SPECIFICATION

=head4 INPUT

        { deep => { type => 'boolean', optional => 1 } }

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key               Meaning                                Resolution
        client.bad_root   the sync root is not a directory       fix root in config.json
        client.no_marker  the root has no .filesync-root marker  mount the drive

=head3 FORMAL SPECIFICATION

        verify = Verify(root, cache.entries, Ignore(cache.ignore ∪ {snapshots}))

=cut

=head2 restore

Purpose: put a path back from this repo's local trash.  The newest stored
version wins; C<list> shows them all instead.

Args: C<path>, optional C<to> (a directory; default the sync root), C<list>.

Versions are searched in this repo's trash first, then in the shared trash
that releases before 0.001.1 used, so files trashed before an upgrade can
still be restored.

Returns: with C<list>, C<{ repo, path, versions }>; otherwise
C<{ repo, path, from, to }>.

Side Effects: copies the version out; the trash entry is kept.

Usage:

        $client->restore(path => 'notes/a.txt', to => '/tmp/out');

=head3 EXAMPLE

        my $versions = $client->restore(path => 'a.txt', list => 1)->{versions};
        print "$_->{date} $_->{size}\n" for @{$versions};

=head3 API SPECIFICATION

=head4 INPUT

        {
                path => { type => 'string', min => 1 },
                to   => { type => 'string', optional => 1 },
                list => { type => 'boolean', optional => 1 },
        }

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key                 Meaning                                 Resolution
        client.unsafe       the path fails validate_relpath         fix the path
        client.no_versions  nothing of that path is in the trash    check --list
        client.not_dir      the target is not a directory           choose another
        client.exists       the destination exists                  move it aside or use --to

=head3 FORMAL SPECIFICATION

        Î”FS
        pre path ∈ SafePath ∧ versions(path) ≠ ⟨⟩ ∧ dest ∉ dom FS
        post tree'(dest) = tree(head versions(path))

=head3 PSEUDOCODE

        validate the path; list versions from the repo trash then the legacy trash
        if listing, return them
        destination := to (created) or the sync root, plus the path
        refuse to overwrite; copy the newest version out

=cut

=head2 snapshot_create

Purpose: take today's snapshot of a replica.

Args: optional C<keep> (how many snapshots to keep; default the repo's
C<snapshot_keep>, else 14; 0 keeps all).

Returns: C<{ repo, ok, exit, keep, pruned, older, ... }> with the
L<App::FileSync::Snapshot/create> result merged in; C<exit =E<gt> 2> when
another run holds the lock.

Side Effects: holds the repo lock; creates a snapshot; prunes old ones when a
new one was made.

Usage:

        my $made = $client->snapshot_create(keep => 7);

=head3 EXAMPLE

        my $made = $client->snapshot_create;
        print $made->{created} ? "snapshot $made->{date}\n" : "already have $made->{date}\n";

=head3 API SPECIFICATION

=head4 INPUT

        { keep => { type => 'integer', min => 0, optional => 1 } }

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key                 Meaning                           Resolution
        client.not_replica  the repo is a client              snapshots are for replicas
        snapshot.*          see App::FileSync::Snapshot

=head3 FORMAL SPECIFICATION

        pre role = replica
        created ∧ keep > 0 ⇒ #snapshots' ≤ keep

=head3 PSEUDOCODE

        refuse unless the repo is a replica
        take the lock, or report that another run holds it
        choose the mode and the number to keep
        create today's snapshot; prune if one was made

=cut

=head2 snapshot_list

Purpose: a replica's snapshots, newest first.

Args: none.

Returns: C<{ repo, snapshots }>.

Side Effects: walks every snapshot to count it.

Usage:

        my $list = $client->snapshot_list;

=head3 EXAMPLE

        print "$_->{date}\n" for @{ $client->snapshot_list->{snapshots} };

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'hashref', schema => { repo => { type => 'string' }, snapshots => { type => 'arrayref' } } }

=head3 MESSAGES

        Key              Meaning                            Resolution
        client.no_repo   the repo is not in the config      filesync init

=head3 FORMAL SPECIFICATION

        snapshot_list = ⟨repo ↦ name, snapshots ↦ Snapshot::list(root)⟩

=cut

=head2 snapshot_restore

Purpose: copy a snapshot (or one path of it) back.

Args: C<date>, optional C<path> (one relative path; default everything) and
C<to> (default the sync root, which rolls the replica back).

Returns: the L<App::FileSync::Snapshot/restore> result plus C<repo>, C<ok>,
C<exit> and C<into_root>; C<exit =E<gt> 2> when another run holds the lock.

Side Effects: holds the repo lock; replaces files under C<to>.

Usage:

        $client->snapshot_restore(date => '2026-10-20', path => 'notes');

=head3 EXAMPLE

        my $done = $client->snapshot_restore(date => '2026-10-20', to => '/tmp/export');
        print "$done->{files} files\n";

=head3 API SPECIFICATION

=head4 INPUT

        {
                date => { type => 'string', optional => 1 },
                path => { type => 'string', optional => 1 },
                to   => { type => 'string', optional => 1 },
        }

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

See L<App::FileSync::Snapshot/restore>.

=head3 FORMAL SPECIFICATION

        Î”FS
        into_root ⇔ to = root
        tree'(to / p) = tree(snapshot(date) / p) for each restored p

=cut

=head2 cache_path

Documented with L</log_path> below.

=head2 log_path

Purpose: where this repo's cache and run log live.

Args: none.

Returns: F<HOME/cache/NAME.json>, F<HOME/logs/NAME.jsonl>.

Side Effects: none.

Usage:

        my $path = $client->cache_path;

=head3 EXAMPLE

        print $client->log_path, "\n";

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

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

=head3 MESSAGES

        Key              Meaning                        Resolution
        config.no_home   no home directory is known     set HOME or FILESYNC_HOME

=head3 FORMAL SPECIFICATION

        cache_path = home / "cache" / name ⁀ ".json"
        log_path   = home / "logs" / name ⁀ ".jsonl"

=cut

=head2 cache

Purpose: the cached base and last-run summary.

Args: none.

Returns: the cache hashref, always with an C<entries> hashref; an empty cache
when there is none or it is unreadable (the next sync rebuilds it).

Side Effects: reads the cache file.

Usage:

        my $last = $client->cache->{last_run};

=head3 EXAMPLE

        my $cache = $client->cache;
        printf "%d files at the last sync\n", scalar keys %{ $cache->{entries} };

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'hashref', schema => { entries => { type => 'hashref' } } }

=head3 MESSAGES

None; a damaged cache is treated as empty.

=head3 FORMAL SPECIFICATION

        cache = json(FS(cache_path)) if that parses to an object, else ⟨entries ↦ ∅⟩

=cut