File Coverage

=head1 NAME

App::FileSync - cron-driven file synchronisation without a daemon

=head1 VERSION

0.001.1

=head1 SYNOPSIS

        filesync init --repo documents --root ~/Documents \
                --transport local --server-root /srv/filesync --remote-repo documents
        filesync sync --repo documents --dry-run
        filesync sync --repo documents

=head1 DESCRIPTION

App::FileSync keeps one directory per client in step with a master copy on a server, and
keeps a separate machine holding a replica of that master.  Every run is a short-lived CLI
process suitable for cron or the Windows Task Scheduler: there is no daemon, no database
and no web interface.

Only files whose content changed are transferred.  Data frames are deflated when that
makes them smaller, and files of at least 64 KiB are sent as rsync-style block deltas
when the other side already holds an older copy, so an edit moves the changed blocks
rather than the whole file.  C<filesync sync --no-delta> forces whole files.  Each run
reports the payload bytes it sent and received and how many files moved as a delta, and
C<filesync log> repeats those figures for past runs.

Every message the tools print is looked up in a catalogue
(L<App::FileSync::I18N>), so a translation is one new catalogue.

This module holds the pieces shared by the client, the server and the admin tools:
byte-transparent JSON, path validation, conflict-copy naming and atomic file writes.

=head1 FUNCTIONS

=head2 json_encode

Purpose: encode a structure as one line of canonical JSON.

Args: C<$data>, any JSON-encodable value.

Returns: the JSON text, keys sorted, with no trailing newline.

Side Effects: none.

Usage:

        print {$fh} json_encode($event), "\n";

=head3 EXAMPLE

        print json_encode({ b => 1, a => [ 'x' ] }), "\n";      # {"a":["x"],"b":1}

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'data', type => 'scalar', optional => 1 } ]

=head4 OUTPUT

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

=head3 MESSAGES

JSON::PP's own error for a value it cannot encode (a code reference, say).

=head3 FORMAL SPECIFICATION

        json_encode : VALUE → TEXT
        json_decode(json_encode(v)) = v

=cut

=head2 json_decode

Purpose: decode one JSON document, keeping strings as byte strings.

Args: C<$text>.

Returns: the decoded structure.  Strings that fit in bytes are downgraded, so a
path read back from JSON names the same file as the bytes it was written from.

Side Effects: none.

Usage:

        my $config = json_decode(read_text($path));

=head3 EXAMPLE

        my $entry = json_decode('{"p":"caf\u00e9.txt"}');
        print length($entry->{p}), "\n";   # 8 (bytes), not 9

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'text', type => 'string' } ]

=head4 OUTPUT

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

=head3 MESSAGES

JSON::PP's own error for malformed JSON.

=head3 FORMAL SPECIFICATION

        json_decode : TEXT ↛ VALUE
        âˆ€ s : STRING in result • ¬ utf8_flag(s) ∨ ∃ c ∈ s • ord c > 255

=cut

=head2 validate_relpath

Purpose: decide whether a path is safe to join to a sync root.

Args: C<$path>, a relative path as it travels on the wire.

Returns: a two-element list C<(1, undef)> for a usable path, or
C<(0, $reason)> where C<$reason> is a translated explanation.  (A list rather
than a reference because every caller destructures it at once, and it is
called once per path in the tree.)

Side Effects: none.

Usage:

        my ($ok, $reason) = validate_relpath($path);

=head3 EXAMPLE

        my ($ok, $why) = validate_relpath('notes/../secret');
        print "$why\n" unless $ok;    # parent path component

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'path', type => 'scalar', optional => 1 } ]

=head4 OUTPUT

        { type => 'arrayref', min => 2, max => 2 }

=head3 MESSAGES

        Key                       Meaning
        path.missing              no path was given
        path.not_text             the path is a reference
        path.empty                the path is empty
        path.too_long             longer than 4096 bytes
        path.absolute             starts with /
        path.drive                starts with a drive letter
        path.backslash            contains a backslash
        path.nul                  contains a NUL byte
        path.control              contains a control character
        path.empty_component      contains //, or starts or ends with /
        path.dot_component        has a . component
        path.parent_component     has a .. component
        path.component_too_long   a component is longer than 255 bytes

Resolution: rename the file on the side that holds it.

=head3 FORMAL SPECIFICATION

        SafePath == { p : seq BYTE |
                0 < #p ≤ 4096 ∧ head p ≠ '/' ∧ ¬ drive(p) ∧
                '\' ∉ ran p ∧ ran p ∩ CONTROL = ∅ ∧
                âˆ€ c : split('/', p) • c ∉ {⟨⟩, ".", ".."} ∧ #c ≤ 255 }
        validate_relpath(p) = (1, ⊥)        if p ∈ SafePath
                            = (0, reason)   otherwise

=head3 PSEUDOCODE

        reject undef, references and empty strings
        reject paths over 4096 bytes
        reject absolute, drive-relative, backslash, NUL and control characters
        for each "/"-separated component:
                reject empty, ".", ".." and components over 255 bytes
        accept

=cut

=head2 validate_repo_name

Documented with L</validate_client_id> below.

=head2 validate_client_id

Purpose: decide whether a repo name or client id is usable as a directory name.

Args: C<$value>.

Returns: C<(1, undef)>, or C<(0, $reason)> with a translated reason.  The
alphabet is C<[A-Za-z0-9][A-Za-z0-9._-]*>, at most 64 characters.

Side Effects: none.

Usage:

        my ($ok, $reason) = validate_client_id($id);

=head3 EXAMPLE

        my ($ok, $why) = validate_repo_name('../etc');
        print "$why\n";       # bad repo name '../etc'

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'value', type => 'scalar', optional => 1 } ]

=head4 OUTPUT

        { type => 'arrayref', min => 2, max => 2 }

=head3 MESSAGES

        Key           Meaning                         Resolution
        id.missing    no value was given              supply one
        id.not_text   the value is a reference        pass a string
        id.empty      the value is empty              supply one
        id.too_long   longer than 64 characters       shorten it
        id.bad        outside the allowed alphabet    use letters, digits, . _ -

=head3 FORMAL SPECIFICATION

        Id == { s : seq CHAR | 0 < #s ≤ 64 ∧ head s ∈ ALNUM ∧ ran s ⊆ ALNUM ∪ {'.','_','-'} }
        validate(s) = (1, ⊥) if s ∈ Id, (0, reason) otherwise

=cut

=head2 parse_since

Purpose: the start of a time window.

Args: C<$value> (C<YYYY-MM-DD> or an epoch), optional C<$option> naming the
command-line option for the error message (default C<--since>).

Returns: the epoch, or C<undef> when C<$value> is undef.  A date means
midnight UTC that day.

Side Effects: none.

Usage:

        my $since = parse_since($opts{since});

=head3 EXAMPLE

        print parse_since('2026-10-22'), "\n";        # 1792627200

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'value',  type => 'string', optional => 1 },
                { name => 'option', type => 'string', optional => 1 },
        ]

=head4 OUTPUT

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

=head3 MESSAGES

        Key        Meaning                              Resolution
        when.bad   neither a date nor an epoch          use YYYY-MM-DD or digits

=head3 FORMAL SPECIFICATION

        parse_since : (DATE ∪ â„• ∪ {⊥}) ↛ â„• ∪ {⊥}
        parse_since(n) = n ; parse_since(d) = midnight_utc(d) ; parse_since(⊥) = ⊥

=cut

=head2 parse_until

Purpose: the end of a time window.

Args: as for L</parse_since> (default option name C<--until>).

Returns: the epoch, or C<undef>.  A date means the last second of that day, so
C<--until 2026-10-22> includes that day's runs.

Side Effects: none.

Usage:

        my $until = parse_until($opts{until});

=head3 EXAMPLE

        print parse_until('2026-10-22'), "\n";        # 1792713599

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'value',  type => 'string', optional => 1 },
                { name => 'option', type => 'string', optional => 1 },
        ]

=head4 OUTPUT

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

=head3 MESSAGES

        Key        Meaning                              Resolution
        when.bad   neither a date nor an epoch          use YYYY-MM-DD or digits

=head3 FORMAL SPECIFICATION

        parse_until(n) = n ; parse_until(d) = midnight_utc(d) + 86399 ; parse_until(⊥) = ⊥

=cut

=head2 format_utc

Purpose: a compact UTC timestamp.

Args: optional C<$epoch> (default now).

Returns: C<YYYYMMDDTHHMMSSZ>.

Side Effects: none.

Usage:

        my $stamp = format_utc($run->{ts});

=head3 EXAMPLE

        print format_utc(0), "\n";    # 19700101T000000Z

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'epoch', type => 'number', optional => 1 } ]

=head4 OUTPUT

        { type => 'string', matches => qr/\A\d{8}T\d{6}Z\z/ }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        format_utc : â„• → STAMP
        format_utc(e) = yyyy mm dd 'T' HH MM SS 'Z' of gmtime(e)

=cut

=head2 split_name

Purpose: split a relative path into directory, stem and extension.

Args: C<$path>.

Returns: an arrayref C<[ $dir, $stem, $ext ]>; C<$dir> has no trailing slash
and is empty at the top level, C<$ext> includes its dot and is empty when there
is none.  A leading dot (C<.profile>) is part of the stem.

Side Effects: none.

Usage:

        my ($dir, $stem, $ext) = @{ split_name('a/b/report.txt') };

=head3 EXAMPLE

        my $parts = split_name('notes/plan.v2.txt');    # ['notes', 'plan.v2', '.txt']

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'arrayref', min => 3, max => 3 }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        split_name(p) = (d, s, e) where p = d ⁀ "/" ⁀ s ⁀ e ∨ (d = ⟨⟩ ∧ p = s ⁀ e)
                        e = ⟨⟩ ∨ (head e = '.' ∧ '.' ∉ ran(tail e)) ; s ≠ ⟨⟩

=cut

=head2 name_with_suffix

Purpose: make a name unique by numbering it before its extension.

Args: C<$path>, C<$suffix> (a number).

Returns: C<report-2.txt> for C<report.txt> and 2, keeping the directory.

Side Effects: none.

Usage:

        my $candidate = name_with_suffix($loser_name, $n);

=head3 EXAMPLE

        print name_with_suffix('a/b.txt', 3), "\n";   # a/b-3.txt

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

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

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        let (d, s, e) = split_name(p)
        name_with_suffix(p, n) = join(d, s ⁀ "-" ⁀ n ⁀ e)

=cut

=head2 conflict_name

Purpose: the name a losing version is kept under.

Args: C<$path>, C<$client_id> (may be undef), C<$epoch> (default now).

Returns: the original name with C<.conflict-CLIENT-TIMESTAMP> inserted before
the extension, kept within 200 bytes so it fits common filesystems.

Side Effects: none.

Usage:

        my $name = conflict_name('notes.txt', 'laptop-1', time);

=head3 EXAMPLE

        print conflict_name('report.txt', 'laptop-1', 1_792_664_100), "\n";
        # report.conflict-laptop-1-20261022T101500Z.txt

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'path',      type => 'string', min => 1 },
                { name => 'client_id', type => 'string', optional => 1 },
                { name => 'epoch',     type => 'number', optional => 1 },
        ]

=head4 OUTPUT

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

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        let (d, s, e) = split_name(p) ; id = sanitise(c) ; t = format_utc(when)
        let room = max(16, 200 − #(".conflict-" ⁀ id ⁀ "-" ⁀ t ⁀ e))
        conflict_name(p, c, when) = join(d, s[1..room] ⁀ ".conflict-" ⁀ id ⁀ "-" ⁀ t ⁀ e)

=cut

=head2 write_atomic

Documented with L</set_mtime> below.

=head2 read_text

Documented with L</set_mtime> below.

=head2 set_mtime

Re-exported from L<App::FileSync::IO>, where they are documented.

=cut