File Coverage

=head1 NAME

App::FileSync::IO - filesystem primitives for App::FileSync

=head1 SYNOPSIS

        use App::FileSync::IO qw(write_atomic read_text sha256_file);

        write_atomic('/srv/filesync/.filesync/repos/docs/master.json', $json);
        my $text = read_text($path);

=head1 DESCRIPTION

Every function raises a catalogued error (see L<App::FileSync::I18N>) that
names the path and carries the operating system's reason.

=head1 FUNCTIONS

=head2 open_file

Purpose: open a file in binary mode.

Args: C<$path>, C<$mode> (C<< < >>, C<< > >> or C<<< >> >>>).

Returns: the filehandle.

Side Effects: creates or truncates the file for C<< > >>, creates it for
C<<< >> >>>.

Usage:

        my $fh = open_file($path, '<');

=head3 EXAMPLE

        my $out = open_file('/tmp/report.bin', '>');
        print {$out} $bytes;
        close $out;

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'handle' }

=head3 MESSAGES

        Key        Meaning                          Resolution
        io.read    the file cannot be opened        check it exists and is readable
        io.write   the file cannot be created       check the directory is writable
        io.append  the file cannot be appended to   check permissions and free space

=head3 FORMAL SPECIFICATION

        open_file : PATH × MODE ↛ HANDLE
        pre  mode ∈ {<, >, >>} ∧ (mode = < ⇒ path ∈ dom FS)
        post mode = > ⇒ FS'(path) = ⟨⟩

=cut

=head2 read_text

Purpose: read a whole file as bytes.

Args: C<$path>.

Returns: the contents (an empty string for an empty file).

Side Effects: none.

Usage:

        my $json = read_text($config_path);

=head3 EXAMPLE

        my $marker = read_text("$root/.filesync-root");

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'string' }

=head3 MESSAGES

        Key       Meaning                     Resolution
        io.read   the file cannot be opened   check it exists and is readable

=head3 FORMAL SPECIFICATION

        read_text : PATH ↛ seq BYTE
        pre  path ∈ dom FS
        post result = FS(path)

=cut

=head2 temp_file

Purpose: create a temporary file beside its final location.

Args: C<$directory>; created if missing.

Returns: an arrayref C<[ $filehandle, $path ]>.

Side Effects: creates the file exclusively (C<O_EXCL>), so a planted file or
symlink of the same name cannot be written through.  Its permissions are those
an ordinary C<open> would give under the current umask.  The name starts with
C<.filesync-tmp->, which the scanner ignores and stale-temp cleanup removes.

Usage:

        my ($fh, $temp) = @{ temp_file($directory) };

=head3 EXAMPLE

        my ($fh, $temp) = @{ temp_file('/home/foo/Documents/notes') };
        print {$fh} $bytes;
        close $fh;
        install_file($temp, '/home/foo/Documents/notes/plan.txt');

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

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

=head3 MESSAGES

        Key          Meaning                                  Resolution
        io.mkdir     the directory cannot be created          check permissions
        io.temp      no temporary file can be made there      check permissions and free space

=head3 FORMAL SPECIFICATION

        Î”FS
        dir? : PATH ; t! : PATH
        t! ∉ dom FS ∧ dirname(t!) = dir? ∧ FS' = FS ∪ {t! ↦ ⟨⟩}

=cut

=head2 write_atomic

Purpose: replace a file's contents so readers see the old or the new version,
never a mixture.

Args: C<$path>, C<$data> (bytes).

Returns: 1.

Side Effects: creates missing parent directories; writes a temporary file in
the same directory and renames it over C<$path>.  The temporary file is
removed if any step fails.

Usage:

        write_atomic($path, json_encode($config) . "\n");

=head3 EXAMPLE

        write_atomic('/tmp/state.json', qq({"ok":1}\n));

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'integer', min => 1, max => 1 }

=head3 MESSAGES

        Key        Meaning                                Resolution
        io.temp    no temporary file can be created       check permissions and space
        io.write   writing or closing the file failed     check free space
        io.rename  the new file cannot replace the old    check permissions

=head3 FORMAL SPECIFICATION

        Î”FS
        path? : PATH ; data? : seq BYTE
        FS'(path?) = data?
        âˆ€ t : dom FS' \ dom FS • ¬ prefix(TEMP, basename t)

=cut

=head2 install_file

Purpose: move a verified temporary file into place.

Args: C<$temp>, C<$target>, optional C<$mtime> (epoch, may be fractional) and
C<$mode> (permission bits).

Returns: C<$target>.

Side Effects: sets the mode (not on Windows) and mtime on C<$temp>, removes
whatever is at C<$target> (a file, a symlink or an empty directory), then
renames.  C<$temp> is removed if the rename fails.

Usage:

        install_file($temp, $abs, $mtime, $mode);

=head3 EXAMPLE

        my ($fh, $temp) = @{ temp_file($dir) };
        print {$fh} $content;
        close $fh;
        install_file($temp, "$dir/report.txt", 1_700_000_000, oct(644));

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'temp',   type => 'string', min => 1 },
                { name => 'target', type => 'string', min => 1 },
                { name => 'mtime',  type => 'number', optional => 1 },
                { name => 'mode',   type => 'integer', optional => 1, min => 0 },
        ]

=head4 OUTPUT

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

=head3 MESSAGES

        Key                Meaning                                     Resolution
        io.remove          the old file cannot be removed              check permissions
        io.replace_dir     a non-empty directory is in the way         move it aside
        io.rename          the new file cannot be moved into place     check permissions

=head3 FORMAL SPECIFICATION

        Î”FS
        temp?, target? : PATH
        pre  temp? ∈ dom FS
        post FS'(target?) = FS(temp?) ∧ temp? ∉ dom FS'

=cut

=head2 clear_target

Purpose: make room for a file at C<$path>.

Args: C<$path>.

Returns: 1.

Side Effects: removes a symlink or file at C<$path>, or an empty directory.
A non-empty directory is never removed.

Usage:

        clear_target($abs);

=head3 EXAMPLE

        clear_target('/tmp/old-copy.txt');

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'integer', min => 1, max => 1 }

=head3 MESSAGES

        Key              Meaning                              Resolution
        io.remove        the file or symlink cannot go        check permissions
        io.replace_dir   a non-empty directory is in the way  move it aside

=head3 FORMAL SPECIFICATION

        Î”FS
        path? : PATH
        path? ∈ dom FS ∧ (kind path? ≠ dir ∨ children path? = ∅) ⇒ path? ∉ dom FS'

=cut

=head2 set_mtime

Purpose: set a file's modification time, keeping sub-second precision where
the platform allows.

Args: C<$path>, C<$mtime> (epoch; C<undef> leaves the file alone).

Returns: 1.

Side Effects: changes the file's atime and mtime.  Where C<Time::HiRes::utime>
is unimplemented (some Windows builds) whole seconds are stored, which the
2-second comparison tolerance already allows for.

Usage:

        set_mtime($temp, 1_700_000_123.456);

=head3 EXAMPLE

        set_mtime('/tmp/a.txt', time - 3600);

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'integer', min => 1, max => 1 }

=head3 MESSAGES

        Key        Meaning                         Resolution
        io.utime   the timestamp cannot be set     check ownership of the file

=head3 FORMAL SPECIFICATION

        Î”FS
        path? : PATH ; m? : ℝ ∪ {⊥}
        m? = ⊥ ⇒ FS' = FS
        m? ≠ ⊥ ⇒ |mtime'(path?) − m?| < 1

=cut

=head2 sha256_file

Purpose: hash a file's contents.

Args: C<$path>.

Returns: the lower-case hex SHA-256, or C<undef> when C<$path> is not a
readable regular file.

Side Effects: none.

Usage:

        my $hash = sha256_file($abs);

=head3 EXAMPLE

        print sha256_file('/etc/hostname'), "\n";

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'string', optional => 1, matches => qr/\A[0-9a-f]{64}\z/ }

=head3 MESSAGES

None; an unreadable file yields C<undef>.

=head3 FORMAL SPECIFICATION

        sha256_file : PATH ⇸ HEX64
        sha256_file(p) = sha256(FS(p))   if p ∈ dom FS ∧ kind p = file ∧ readable p

=cut

=head2 list_dir

Purpose: the entries of a directory.

Args: C<$directory>.

Returns: an arrayref of names, sorted, without C<.> and C<..>; C<undef> when
the directory cannot be read (C<$!> says why).

Side Effects: none.

Usage:

        my $names = list_dir($dir) or return 0;

=head3 EXAMPLE

        print "$_\n" for @{ list_dir('/tmp') || [] };

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

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

=head3 MESSAGES

None; an unreadable directory yields C<undef>.

=head3 FORMAL SPECIFICATION

        list_dir : PATH ⇸ seq NAME
        list_dir(d) = sort(children d \ {".", ".."})   if readable d

=cut

=head2 copy_preserving

Purpose: copy one regular file, keeping its mode and mtime.

Args: C<$source>, C<$destination>, optional C<\@stat> of the source (saves a
second C<stat> when the caller already has one).

Returns: 1.

Side Effects: creates C<$destination>'s parent directories; overwrites
C<$destination>.

Usage:

        copy_preserving($from, $to, \@stat);

=head3 EXAMPLE

        copy_preserving('/srv/a.txt', '/backup/a.txt');

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'source',      type => 'string', min => 1 },
                { name => 'destination', type => 'string', min => 1 },
                { name => 'stat',        type => 'arrayref', optional => 1 },
        ]

=head4 OUTPUT

        { type => 'integer', min => 1, max => 1 }

=head3 MESSAGES

        Key       Meaning                      Resolution
        io.copy   the copy could not be made   check space and permissions

=head3 FORMAL SPECIFICATION

        Î”FS
        src?, dst? : PATH
        FS'(dst?) = FS(src?) ∧ mtime'(dst?) = mtime(src?) ∧ mode'(dst?) = mode(src?)

=cut

=head2 append_line

Purpose: append one line to a log or journal.

Args: C<$path>, C<$line> (without a newline).

Returns: 1.

Side Effects: creates C<$path> and its directory if needed.  If the file ends
in a torn line from a killed run, a newline is written first so the new entry
is not glued to the fragment.

Usage:

        append_line($journal, json_encode($event));

=head3 EXAMPLE

        append_line('/tmp/run.log', 'started');

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

        { type => 'integer', min => 1, max => 1 }

=head3 MESSAGES

        Key         Meaning                           Resolution
        io.append   the file cannot be appended to    check permissions and space

=head3 FORMAL SPECIFICATION

        Î”FS
        path? : PATH ; line? : seq CHAR
        let old = FS(path?) if path? ∈ dom FS, else ⟨⟩
        let sep = "\n" if old ≠ ⟨⟩ ∧ last old ≠ "\n", else ⟨⟩
        FS'(path?) = old ⁀ sep ⁀ line? ⁀ "\n"

=cut

=head2 ensure_dir

Purpose: make sure a directory exists.

Args: C<$directory>.

Returns: C<$directory>.

Side Effects: creates it and any missing parents.

Usage:

        ensure_dir(dirname($path));

=head3 EXAMPLE

        ensure_dir('/tmp/a/b/c');

=head3 API SPECIFICATION

=head4 INPUT

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

=head4 OUTPUT

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

=head3 MESSAGES

        Key        Meaning                          Resolution
        io.mkdir   the directory cannot be created  check permissions

=head3 FORMAL SPECIFICATION

        Î”FS
        d? : PATH
        kind'(d?) = dir ∧ ∀ a : ancestors d? • kind'(a) = dir

=cut