File Coverage

=head1 NAME

App::FileSync::Admin - server-side repo, client and recovery administration

=head1 SYNOPSIS

        my $admin = App::FileSync::Admin->new(root => '/srv/filesync');
        $admin->repo_create(name => 'docs');
        $admin->client_allow(repo => 'docs', client => 'laptop');
        my $report = $admin->verify(repo => 'docs', deep => 1);

=head1 DESCRIPTION

The library behind C<filesync-admin>.  Methods return hashrefs or arrayrefs
for the command line to print (or encode as JSON) and raise catalogued
errors (see L<App::FileSync::I18N>) on failure.

=head1 METHODS

=head2 new

Purpose: an administrator for one server root.

Args: optional C<root> (default C<FILESYNC_ROOT>, then F</srv/filesync>),
C<logger> (default from L<App::FileSync::Settings>), C<language>.

Returns: the object.

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

Usage:

        my $admin = App::FileSync::Admin->new(root => $root);

=head3 EXAMPLE

        my $admin = App::FileSync::Admin->new;
        print $admin->root, "\n";  # /srv/filesync unless FILESYNC_ROOT says otherwise

=head3 API SPECIFICATION

=head4 INPUT

        {
                root     => { type => 'string', optional => 1 },
                logger   => { type => 'object', optional => 1 },
                language => { type => 'string', optional => 1 },
        }

=head4 OUTPUT

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

=head3 MESSAGES

        Key            Meaning                  Resolution
        args.invalid   an argument is malformed fix the call

=head3 FORMAL SPECIFICATION

        root' = first non-empty ⟨root, FILESYNC_ROOT, "/srv/filesync"⟩

=cut

=head2 root

Purpose: the server root this object administers.

Args: none.

Returns: the path.

Side Effects: none.

Usage:

        my $root = $admin->root;

=head3 EXAMPLE

        print $admin->root, "\n";

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

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

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        root = self.root

=cut

=head2 repo_create

Purpose: create a repo: its master tree, metadata directories, policy and an
empty index.

Args: C<name> (a repo id), optional C<trash_days>, C<max_deletes>,
C<max_delete_percent> (non-negative integers) and C<ignore> (patterns; the
default ignore list when absent or empty).

Returns: C<{ name, master, config }> (the master and config paths).

Side Effects: creates F<ROOT/master/NAME> and F<ROOT/.filesync/repos/NAME>.

Usage:

        $admin->repo_create(name => 'docs', trash_days => 60);

=head3 EXAMPLE

        my $made = $admin->repo_create(name => 'photos', ignore => [ '*.tmp', '/cache/' ]);
        print "master at $made->{master}\n";

=head3 API SPECIFICATION

=head4 INPUT

        {
                name               => { type => 'string', min => 1, max => 64 },
                trash_days         => { type => 'integer', min => 0, optional => 1 },
                max_deletes        => { type => 'integer', min => 0, optional => 1 },
                max_delete_percent => { type => 'integer', min => 0, optional => 1 },
                ignore             => { type => 'arrayref', optional => 1 },
        }

=head4 OUTPUT

        {
                type => 'hashref',
                schema => {
                        name   => { type => 'string' },
                        master => { type => 'string' },
                        config => { type => 'string' },
                },
        }

=head3 MESSAGES

        Key                  Meaning                      Resolution
        admin.bad_repo       the name is not a valid id   letters, digits, . _ - ; at most 64
        admin.repo_exists    the repo already exists      choose another name
        io.mkdir / io.write  the files cannot be written  check permissions

=head3 FORMAL SPECIFICATION

        Î”FS
        pre name ∈ Id ∧ repo_config_path(root, name) ∉ dom FS
        post repo_config_path(root, name) ∈ dom FS' ∧ index(name) = ∅

=head3 PSEUDOCODE

        validate the name; refuse if the repo exists
        start from the default policy; apply the given limits and ignore list
        create the master and metadata directories
        save the policy and an empty index

=cut

=head2 repo_list

Purpose: the repos under this root.

Args: none.

Returns: an arrayref of names, sorted.

Side Effects: reads the metadata directory.

Usage:

        print "$_\n" for @{ $admin->repo_list };

=head3 EXAMPLE

        my $repos = $admin->repo_list;
        print @{$repos} ? "@{$repos}\n" : "none\n";

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'arrayref' }

=head3 MESSAGES

None; a root with no repos gives an empty list.

=head3 FORMAL SPECIFICATION

        repo_list = sort { n | n ∈ children(root/.filesync/repos) ∧ isdir(n) }

=cut

=head2 repo_show

Purpose: a repo's policy and where it lives.

Args: C<$name>.

Returns: C<{ config, master, meta, clients }>; C<clients> is a sorted arrayref.

Side Effects: reads the repo config.

Usage:

        my $info = $admin->repo_show('docs');

=head3 EXAMPLE

        my $info = $admin->repo_show('docs');
        print "trash kept $info->{config}{trash_days} days\n";

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'name', type => 'string', min => 1 } ]

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key              Meaning                  Resolution
        admin.bad_repo   the name is not an id    check the spelling
        config.no_repo   the repo does not exist  filesync-admin repo list

=head3 FORMAL SPECIFICATION

        repo_show(n) = ⟨config ↦ load_repo(n), master ↦ master_dir(n), meta ↦ meta_dir(n), clients ↦ sort dom config.clients⟩

=cut

=head2 client_allow

Purpose: let a client (or replica) sync a repo.

Args: C<repo>, C<client> (a client id), optional C<role> (C<client>, the
default, or C<replica>).

Returns: C<{ client, role }>.

Side Effects: rewrites the repo config.  Allowing an existing client again
changes its role.

Usage:

        $admin->client_allow(repo => 'docs', client => 'backup', role => 'replica');

=head3 EXAMPLE

        $admin->client_allow(repo => 'docs', client => 'laptop');

=head3 API SPECIFICATION

=head4 INPUT

        {
                repo   => { type => 'string', min => 1 },
                client => { type => 'string', optional => 1 },
                role   => { type => 'string', optional => 1, memberof => [ 'client', 'replica' ] },
        }

=head4 OUTPUT

        { type => 'hashref', schema => { client => { type => 'string' }, role => { type => 'string' } } }

=head3 MESSAGES

        Key               Meaning                         Resolution
        admin.bad_client  the client id is not valid      letters, digits, . _ - ; at most 64
        admin.bad_role    the role is not client/replica  choose one of those
        admin.bad_repo    the repo name is not an id      check the spelling
        config.no_repo    the repo does not exist         create it first

=head3 FORMAL SPECIFICATION

        Î”RepoConfig
        pre client ∈ Id ∧ role ∈ {client, replica}
        clients' = clients ⊕ {client ↦ role}

=cut

=head2 client_list

Purpose: the clients allowed on a repo.

Args: C<$repo>.

Returns: an arrayref, sorted by id, of C<{ client, role, base }>; C<base> is 1
when the server holds that client's base (it has synced at least once).

Side Effects: reads the repo config.

Usage:

        for my $c (@{ $admin->client_list('docs') }) { ... }

=head3 EXAMPLE

        printf "%-12s %s\n", $_->{client}, $_->{role} for @{ $admin->client_list('docs') };

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'repo', type => 'string', min => 1 } ]

=head4 OUTPUT

        { type => 'arrayref' }

=head3 MESSAGES

        Key              Meaning                  Resolution
        config.no_repo   the repo does not exist  check the name

=head3 FORMAL SPECIFICATION

        client_list(r) = sort ⟨ (c, role(c), base(c) ∈ dom FS) | c ∈ dom clients(r) ⟩

=cut

=head2 client_forget

Purpose: drop the server's base for a client, so its next sync starts afresh.

Args: C<repo>, C<client>.

Returns: C<{ removed =E<gt> 0|1, path }>.

Side Effects: removes the client's base file.  The client stays allowed.

Usage:

        $admin->client_forget(repo => 'docs', client => 'laptop');

=head3 EXAMPLE

        my $done = $admin->client_forget(repo => 'docs', client => 'old-laptop');
        print $done->{removed} ? "forgot\n" : "nothing to forget\n";

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'hashref', schema => { removed => { type => 'integer' }, path => { type => 'string' } } }

=head3 MESSAGES

        Key               Meaning                        Resolution
        store.bad_client  the client id is not valid     check the spelling
        io.remove         the base cannot be removed     check permissions

=head3 FORMAL SPECIFICATION

        Î”FS
        FS' = {base_path(r, c)} ⩤ FS
        removed = 1 ⇔ base_path(r, c) ∈ dom FS

=cut

=head2 journal_dir

Purpose: where a repo's journal lives.

Args: C<$repo>.

Returns: F<ROOT/.filesync/repos/REPO/journal>.

Side Effects: reads the repo config.

Usage:

        my $dir = $admin->journal_dir('docs');

=head3 EXAMPLE

        print $admin->journal_dir('docs'), "\n";

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'repo', type => 'string', min => 1 } ]

=head4 OUTPUT

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

=head3 MESSAGES

        Key              Meaning                  Resolution
        config.no_repo   the repo does not exist  check the name

=head3 FORMAL SPECIFICATION

        journal_dir(r) = meta_dir(r) / "journal"

=cut

=head2 journal_read

Purpose: the journal's events, filtered.

Args: C<repo>; optional filters C<client> (id), C<since> and C<until>
(C<YYYY-MM-DD> or epoch, inclusive), C<exits> (arrayref of exit codes; selects
session outcomes), C<warnings> (sessions that kept conflict copies) and
C<limit> (the newest N).

Returns: an arrayref of event hashrefs, oldest first.

Side Effects: reads every monthly journal file.  A torn final line from a
killed run is skipped.

Usage:

        my $events = $admin->journal_read(repo => 'docs', since => '2026-10-01', limit => 50);

=head3 EXAMPLE

        for my $event (@{ $admin->journal_read(repo => 'docs', exits => [ 1, 2 ]) }) {
                print "$event->{ts} $event->{client} exit $event->{exit}\n";
        }

=head3 API SPECIFICATION

=head4 INPUT

        {
                repo     => { type => 'string', min => 1 },
                client   => { type => 'string', optional => 1 },
                since    => { type => 'string', optional => 1 },
                until    => { type => 'string', optional => 1 },
                exits    => { type => 'arrayref', optional => 1 },
                warnings => { type => 'boolean', optional => 1 },
                limit    => { type => 'integer', optional => 1 },
        }

=head4 OUTPUT

        { type => 'arrayref' }

=head3 MESSAGES

        Key            Meaning                         Resolution
        when.bad       since/until is not a date       use YYYY-MM-DD or an epoch
        io.read        a journal file cannot be read   check permissions

=head3 FORMAL SPECIFICATION

        let E = ⟨ e | f ∈ sort(journal files), line ∈ f, e = json(line) ∈ HASH ⟩
        journal_read = last limit (sort_by ts (filter(E)))

=head3 PSEUDOCODE

        read every journal file in name (month) order, skipping torn lines
        keep events for the client, inside since..until
        keep session outcomes with a wanted exit code, if asked
        keep sessions that kept conflict copies, if asked
        sort by time; keep the newest limit

=cut

=head2 verify

Purpose: rehash the master against its index and report what no longer
agrees.

Args: C<repo>, optional C<deep> (hash every file) and C<sample> (hash N
random files).

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

Side Effects: reads the master tree; logs a debug summary.

Usage:

        my $report = $admin->verify(repo => 'docs', deep => 1);

=head3 EXAMPLE

        my $report = $admin->verify(repo => 'docs', sample => 20);
        print $report->{ok} ? "clean\n" : "drift\n";

=head3 API SPECIFICATION

=head4 INPUT

        {
                repo   => { type => 'string', min => 1 },
                deep   => { type => 'boolean', optional => 1 },
                sample => { type => 'integer', min => 0, optional => 1 },
        }

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key              Meaning                  Resolution
        config.no_repo   the repo does not exist  check the name
        verify.*         see App::FileSync::Verify

=head3 FORMAL SPECIFICATION

        verify(r) = Verify(master_dir(r), index(r), ignore(r)) ⊕ ⟨repo ↦ r, master ↦ master_dir(r)⟩

=cut

=head2 reindex

Purpose: rebuild F<master.json> from the tree, hashing every file.

Used after a manual repair (a rollback from a backup, say) so the index
describes the restored master without waiting for the next client session.
The old index is deliberately not reused: a restored file can keep its size
and mtime while its content differs, which is exactly the case reindex exists
for.

Args: C<repo>, optional C<dry_run>.

Returns: C<{ repo, master, index, files, dirs, bytes, skipped, dry_run, written }>.

Side Effects: holds the repo lock (the same one the server takes), so it never
races a session; writes the index and a journal event unless C<dry_run>.

Usage:

        my $result = $admin->reindex(repo => 'docs');

=head3 EXAMPLE

        my $plan = $admin->reindex(repo => 'docs', dry_run => 1);
        print "would index $plan->{files} files\n";

=head3 API SPECIFICATION

=head4 INPUT

        {
                repo    => { type => 'string', min => 1 },
                dry_run => { type => 'boolean', optional => 1 },
        }

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key              Meaning                              Resolution
        admin.locked     a sync session holds the repo lock   retry when it has finished
        config.no_repo   the repo does not exist              check the name

=head3 FORMAL SPECIFICATION

        Î”FS
        pre lock(r) is free
        Â¬dry_run ⇒ index'(r) = scan(master_dir(r))

=head3 PSEUDOCODE

        open the repo and take its lock
        walk the master, hashing everything
        unless dry run: save the index and journal the reindex
        log and report the counts

=cut

=head2 restore

Purpose: put a path back from the server trash: into the master by default,
or into C<to> as an export.

Args: C<repo>, C<path> (the relative path as synced), optional C<to> (a
directory), C<date> (C<YYYY-MM-DD>; the newest version from that day), C<list>
(only list the versions).

Returns: with C<list>, C<{ repo, path, versions }> (rows from
L<App::FileSync::Trash/version_info>); otherwise
C<{ repo, path, from, to, date, sha256, into_master }>.

Side Effects: copies the version out (the trash entry is kept, so this is
repeatable); when restoring into the master, rebuilds the index so verify and
the next sync agree; journals the restore.

Usage:

        $admin->restore(repo => 'docs', path => 'notes/a.txt');

=head3 EXAMPLE

        my $done = $admin->restore(repo => 'docs', path => 'a.txt', to => '/tmp/out', date => '2026-10-20');
        print "restored to $done->{to}\n";

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key                  Meaning                                 Resolution
        admin.unsafe_path    the path fails validate_relpath         fix the path
        admin.no_versions    nothing of that path is in the trash    check "restore --list"
        admin.bad_date       the date is not YYYY-MM-DD              fix it
        admin.no_version_on  no version from that day                pick a listed date
        admin.not_dir        the export target is not a directory    choose another
        admin.exists         the destination exists                  move it aside first

=head3 FORMAL SPECIFICATION

        Î”FS
        pre path ∈ SafePath ∧ versions(path) ≠ ⟨⟩ ∧ dest ∉ dom FS
        post tree'(dest) = tree(chosen) ∧ (into_master ⇒ index' = scan(master))

=head3 PSEUDOCODE

        validate the path and list its trashed versions
        if listing, return them
        choose the newest version, or the newest from the given day
        destination: the master, or the export directory (created if needed)
        refuse to overwrite; copy the version out
        if into the master, rebuild the index
        journal, log and report

=cut