blib/lib/App/FileSync/IO.pm

filter: Statementstmt 93.6% 192 / 205 Branchbran 66.6% 36 / 54 Conditioncond 52.5% 21 / 40 MC/DCmcdc 24.0% 6 / 25 Subroutinesub 97.5% 39 / 40 Podpod 100% 12 / 12 totaltotal 81.3% 306 / 376 CC 42 SCAR 12.9
CC
42
Cov
83%
clear_target
9.9
set_mtime
6.1
_path_error
5.9
CRAP 3.6
« blib/lib/App/FileSync/Protocol.pm ↑ Summary blib/lib/App/FileSync/Transport/Local.pm »
1 package App::FileSync::IO;
2  
3 # Filesystem primitives shared by the client, the server, the trash and the
4 # snapshots. Each one used to be written out two to four times; keeping them
5 # here means a fix (such as O_EXCL temporaries) lands everywhere at once.
6  
7 341 ▶use App::FileSync::Platform;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 341 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 341 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 341 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 341 ▶use Digest::SHA ();
Subroutine BEGIN: called CC=1 SCAR=0.0
14 341 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
15 341 ▶use Fcntl qw(SEEK_END);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 341 ▶use File::Basename qw(dirname);
Subroutine BEGIN: called CC=1 SCAR=0.0
17 341 ▶use File::Copy ();
Subroutine BEGIN: called CC=1 SCAR=0.0
18 341 ▶use File::Path qw(make_path);
Subroutine BEGIN: called CC=1 SCAR=0.0
19 341 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 341 ▶use File::Temp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
21 341 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
22 341 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
23 341 ▶use Time::HiRes ();
Subroutine BEGIN: called CC=1 SCAR=0.0
24  
25 341 ▶use App::FileSync::Constants qw($MODE_MASK $TEMP_PREFIX $STAT_MODE $STAT_MTIME $SHA_BITS);
Subroutine BEGIN: called CC=1 SCAR=0.0
26 341 ▶use App::FileSync::I18N qw(throw os_error strip_location);
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 341 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
29  
30 341 our @EXPORT_OK = qw(
31 read_text open_file temp_file write_atomic install_file clear_target
32 set_mtime sha256_file list_dir copy_preserving append_line ensure_dir
33 );
34  
35 # File::Temp wants at least four X's; ten keep collisions out of reach even
36 # with thousands of uploads in one directory.
37 341 Readonly::Scalar my $TEMP_TEMPLATE => $TEMP_PREFIX . ('X' x 10);
38  
39 # Catalogue key for each open mode, so the error names what was attempted.
40 341 Readonly my %OPEN_KEY => (
41 '<' => 'io.read',
42 '>' => 'io.write',
43 '>>' => 'io.append',
44 );
45  
46 # The permission bits a new file would get from open() under the current
47 # umask. File::Temp creates 0600 files, which would otherwise leak into the
48 # master and every replica.
49 341 Readonly::Scalar my $CREATE_MODE => oct('666');
50  
51 # Windows has no POSIX permission bits worth setting.
52 341 Readonly::Scalar my $HAS_MODES => $^O ne 'MSWin32';
53  
54 =encoding utf8
55  
56 =head1 NAME
57  
58 App::FileSync::IO - filesystem primitives for App::FileSync
59  
60 =head1 SYNOPSIS
61  
62 use App::FileSync::IO qw(write_atomic read_text sha256_file);
63  
64 write_atomic('/srv/filesync/.filesync/repos/docs/master.json', $json);
65 my $text = read_text($path);
66  
67 =head1 DESCRIPTION
68  
69 Every function raises a catalogued error (see L<App::FileSync::I18N>) that
70 names the path and carries the operating system's reason.
71  
72 =head1 FUNCTIONS
73  
74 =head2 open_file
75  
76 Purpose: open a file in binary mode.
77  
78 Args: C<$path>, C<$mode> (C<< < >>, C<< > >> or C<<< >> >>>).
79  
80 Returns: the filehandle.
81  
82 Side Effects: creates or truncates the file for C<< > >>, creates it for
83 C<<< >> >>>.
84  
85 Usage:
86  
87 my $fh = open_file($path, '<');
88  
89 =head3 EXAMPLE
90  
91 my $out = open_file('/tmp/report.bin', '>');
92 print {$out} $bytes;
93 close $out;
94  
95 =head3 API SPECIFICATION
96  
97 =head4 INPUT
98  
99 [
100 { name => 'path', type => 'string', min => 1 },
101 { name => 'mode', type => 'string', memberof => [ '<', '>', '>>' ] },
102 ]
103  
104 =head4 OUTPUT
105  
106 { type => 'handle' }
107  
108 =head3 MESSAGES
109  
110 Key Meaning Resolution
111 io.read the file cannot be opened check it exists and is readable
112 io.write the file cannot be created check the directory is writable
113 io.append the file cannot be appended to check permissions and free space
114  
115 =head3 FORMAL SPECIFICATION
116  
117 open_file : PATH × MODE ↛ HANDLE
118 pre mode ∈ {<, >, >>} ∧ (mode = < ⇒ path ∈ dom FS)
119 post mode = > ⇒ FS'(path) = ⟨⟩
120  
121 =cut
122  
123 3594 ▶sub open_file {
Subroutine open_file: called CC=3 SCAR=11.0
Pod documented
124 3594 my ($path, $mode) = @_;
125  
126 3594 my $fh;
127 3594 ▶ eval { open $fh, $mode, $path; 1 }
Condition50%1/2
$OPEN_KEY{$mode} || 'io.read'
l!l
30
MC/DC0%0/1
$OPEN_KEY{$mode} || 'io.read'
$OPEN_KEY{$mode}
Truth table50%1/2
A
A= $OPEN_KEY{$mode}
Aresult
11
00
128 3594 ▶ or throw($OPEN_KEY{$mode} || 'io.read', { path => $path, error => os_error($@) });
Branch: 1 branch
BranchTrueFalseTotal
eval { do { &App::FileSync::IO::open($fh, $mode, $path); 1 } } or throw($OPEN_KEY{$mode} || "io.read", {"path", $path, "error", os_error($@)}) 3591 3 3594
129 3591 binmode $fh;
130  
131 3591 return $fh;
132 }
133  
134 =head2 read_text
135  
136 Purpose: read a whole file as bytes.
137  
138 Args: C<$path>.
139  
140 Returns: the contents (an empty string for an empty file).
141  
142 Side Effects: none.
143  
144 Usage:
145  
146 my $json = read_text($config_path);
147  
148 =head3 EXAMPLE
149  
150 my $marker = read_text("$root/.filesync-root");
151  
152 =head3 API SPECIFICATION
153  
154 =head4 INPUT
155  
156 [ { name => 'path', type => 'string', min => 1 } ]
157  
158 =head4 OUTPUT
159  
160 { type => 'string' }
161  
162 =head3 MESSAGES
163  
164 Key Meaning Resolution
165 io.read the file cannot be opened check it exists and is readable
166  
167 =head3 FORMAL SPECIFICATION
168  
169 read_text : PATH ↛ seq BYTE
170 pre path ∈ dom FS
171 post result = FS(path)
172  
173 =cut
174  
175 1376 ▶sub read_text {
Subroutine read_text: called CC=2 SCAR=7.0
Pod documented
176 1376 my ($path) = @_;
177  
178 1376 my $fh = open_file($path, '<');
179 1373 my $text = do { local $/; <$fh> };
180 1373 close $fh;
181  
182 1373 ▶ return defined $text ? $text : '';
Branch: 1 branch
BranchTrueFalseTotal
defined $text ? : 1373 0 1373
183 }
184  
185 =head2 temp_file
186  
187 Purpose: create a temporary file beside its final location.
188  
189 Args: C<$directory>; created if missing.
190  
191 Returns: an arrayref C<[ $filehandle, $path ]>.
192  
193 Side Effects: creates the file exclusively (C<O_EXCL>), so a planted file or
194 symlink of the same name cannot be written through. Its permissions are those
195 an ordinary C<open> would give under the current umask. The name starts with
196 C<.filesync-tmp->, which the scanner ignores and stale-temp cleanup removes.
197  
198 Usage:
199  
200 my ($fh, $temp) = @{ temp_file($directory) };
201  
202 =head3 EXAMPLE
203  
204 my ($fh, $temp) = @{ temp_file('/home/foo/Documents/notes') };
205 print {$fh} $bytes;
206 close $fh;
207 install_file($temp, '/home/foo/Documents/notes/plan.txt');
208  
209 =head3 API SPECIFICATION
210  
211 =head4 INPUT
212  
213 [ { name => 'directory', type => 'string', min => 1 } ]
214  
215 =head4 OUTPUT
216  
217 { type => 'arrayref', min => 2, max => 2 }
218  
219 =head3 MESSAGES
220  
221 Key Meaning Resolution
222 io.mkdir the directory cannot be created check permissions
223 io.temp no temporary file can be made there check permissions and free space
224  
225 =head3 FORMAL SPECIFICATION
226  
227 ΔFS
228 dir? : PATH ; t! : PATH
229 t! ∉ dom FS ∧ dirname(t!) = dir? ∧ FS' = FS ∪ {t! ↦ ⟨⟩}
230  
231 =cut
232  
233 1043 ▶sub temp_file {
Subroutine temp_file: called CC=3 SCAR=11.1
Pod documented
234 1043 my ($directory) = @_;
235  
236 1043 ensure_dir($directory);
237  
238 1043 my ($fh, $path);
239 1043 ▶ eval {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { () = File::Temp::tempfile($TEMP_TEMPLATE, "DIR", $directory, "UNLINK", 0); 1 } } or throw("io.temp", {"path", $directory, "error", os_error($@)}) 1043 0 1043
240 1043 ($fh, $path) = File::Temp::tempfile($TEMP_TEMPLATE, DIR => $directory, UNLINK => 0);
241 1043 1;
242 } or throw('io.temp', { path => $directory, error => os_error($@) });
243  
244 1043 binmode $fh;
245 1043 ▶ chmod($CREATE_MODE & ~umask, $path) if $HAS_MODES;
Branch: 1 branch
BranchTrueFalseTotal
if $HAS_MODES 1043 0 1043
246  
247 1043 return [ $fh, $path ];
248 }
249  
250 =head2 write_atomic
251  
252 Purpose: replace a file's contents so readers see the old or the new version,
253 never a mixture.
254  
255 Args: C<$path>, C<$data> (bytes).
256  
257 Returns: 1.
258  
259 Side Effects: creates missing parent directories; writes a temporary file in
260 the same directory and renames it over C<$path>. The temporary file is
261 removed if any step fails.
262  
263 Usage:
264  
265 write_atomic($path, json_encode($config) . "\n");
266  
267 =head3 EXAMPLE
268  
269 write_atomic('/tmp/state.json', qq({"ok":1}\n));
270  
271 =head3 API SPECIFICATION
272  
273 =head4 INPUT
274  
275 [
276 { name => 'path', type => 'string', min => 1 },
277 { name => 'data', type => 'string' },
278 ]
279  
280 =head4 OUTPUT
281  
282 { type => 'integer', min => 1, max => 1 }
283  
284 =head3 MESSAGES
285  
286 Key Meaning Resolution
287 io.temp no temporary file can be created check permissions and space
288 io.write writing or closing the file failed check free space
289 io.rename the new file cannot replace the old check permissions
290  
291 =head3 FORMAL SPECIFICATION
292  
293 ΔFS
294 path? : PATH ; data? : seq BYTE
295 FS'(path?) = data?
296 ∀ t : dom FS' \ dom FS • ¬ prefix(TEMP, basename t)
297  
298 =cut
299  
300 775 ▶sub write_atomic {
Subroutine write_atomic: called CC=3 SCAR=11.9
Pod documented
301 775 my ($path, $data) = @_;
302  
303 775 my ($fh, $temp) = @{ temp_file(dirname($path)) };
304  
305 # print is outside autodie's reach, so its failure is checked here.
306 775 my $written = print {$fh} $data;
307 775 my $closed = eval { close $fh; 1 };
308 775 ▶ unless ($written && $closed) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($written and $closed) 0 775 775
Condition33%1/3
$written and $closed
!ll&&!rl&&r
00775
MC/DC0%0/2
$written and $closed
$written $closed
Truth table33%1/3
A and B
A= $writtenB= $closed
ABresult
0X0
100
111
309 0 my $error = os_error($@);
310 0 _discard($temp);
311 0 throw('io.write', { path => $temp, error => $error });
312 }
313  
314 775 _rename_or_discard($temp, $path);
315 775 return 1;
316 }
317  
318 =head2 install_file
319  
320 Purpose: move a verified temporary file into place.
321  
322 Args: C<$temp>, C<$target>, optional C<$mtime> (epoch, may be fractional) and
323 C<$mode> (permission bits).
324  
325 Returns: C<$target>.
326  
327 Side Effects: sets the mode (not on Windows) and mtime on C<$temp>, removes
328 whatever is at C<$target> (a file, a symlink or an empty directory), then
329 renames. C<$temp> is removed if the rename fails.
330  
331 Usage:
332  
333 install_file($temp, $abs, $mtime, $mode);
334  
335 =head3 EXAMPLE
336  
337 my ($fh, $temp) = @{ temp_file($dir) };
338 print {$fh} $content;
339 close $fh;
340 install_file($temp, "$dir/report.txt", 1_700_000_000, oct(644));
341  
342 =head3 API SPECIFICATION
343  
344 =head4 INPUT
345  
346 [
347 { name => 'temp', type => 'string', min => 1 },
348 { name => 'target', type => 'string', min => 1 },
349 { name => 'mtime', type => 'number', optional => 1 },
350 { name => 'mode', type => 'integer', optional => 1, min => 0 },
351 ]
352  
353 =head4 OUTPUT
354  
355 { type => 'string', min => 1 }
356  
357 =head3 MESSAGES
358  
359 Key Meaning Resolution
360 io.remove the old file cannot be removed check permissions
361 io.replace_dir a non-empty directory is in the way move it aside
362 io.rename the new file cannot be moved into place check permissions
363  
364 =head3 FORMAL SPECIFICATION
365  
366 ΔFS
367 temp?, target? : PATH
368 pre temp? ∈ dom FS
369 post FS'(target?) = FS(temp?) ∧ temp? ∉ dom FS'
370  
371 =cut
372  
373 265 ▶sub install_file {
Subroutine install_file: called CC=3 SCAR=11.6
Pod documented
374 265 my ($temp, $target, $mtime, $mode) = @_;
375  
376 265 ▶ chmod($mode & $MODE_MASK, $temp) if defined $mode && $HAS_MODES;
Branch: 1 branch
BranchTrueFalseTotal
if defined $mode and $HAS_MODES 265 0 265
Condition33%1/3
defined $mode and $HAS_MODES
!ll&&!rl&&r
00265
MC/DC0%0/2
defined $mode and $HAS_MODES
defined $mode $HAS_MODES
Truth table33%1/3
A and B
A= defined $modeB= $HAS_MODES
ABresult
0X0
100
111
377 265 set_mtime($temp, $mtime);
378  
379 265 clear_target($target);
380 265 _rename_or_discard($temp, $target);
381  
382 265 return $target;
383 }
384  
385 =head2 clear_target
386  
387 Purpose: make room for a file at C<$path>.
388  
389 Args: C<$path>.
390  
391 Returns: 1.
392  
393 Side Effects: removes a symlink or file at C<$path>, or an empty directory.
394 A non-empty directory is never removed.
395  
396 Usage:
397  
398 clear_target($abs);
399  
400 =head3 EXAMPLE
401  
402 clear_target('/tmp/old-copy.txt');
403  
404 =head3 API SPECIFICATION
405  
406 =head4 INPUT
407  
408 [ { name => 'path', type => 'string', min => 1 } ]
409  
410 =head4 OUTPUT
411  
412 { type => 'integer', min => 1, max => 1 }
413  
414 =head3 MESSAGES
415  
416 Key Meaning Resolution
417 io.remove the file or symlink cannot go check permissions
418 io.replace_dir a non-empty directory is in the way move it aside
419  
420 =head3 FORMAL SPECIFICATION
421  
422 ΔFS
423 path? : PATH
424 path? ∈ dom FS ∧ (kind path? ≠ dir ∨ children path? = ∅) ⇒ path? ∉ dom FS'
425  
426 =cut
427  
428 265 ▶sub clear_target {
Subroutine clear_target: called CC=7 SCAR=23.0
Pod documented
429 265 my ($path) = @_;
430  
431 # Symlinks first: -d follows them, and a link to a directory must be
432 # unlinked, not rmdir'ed.
433 265 ▶ if (-l $path || (-e _ && !-d _)) {
Branch: 2 branches
BranchTrueFalseTotal
if (-l $path or -e _ and not -d _) { } 13 252 265
elsif (-d _) { } 0 252 252
Condition66%4/6
-l $path or -e _ and not -d _
l!l&&r!l&&!r
013252
-e _ and not -d _
!ll&&!rl&&r
252013
MC/DC33%1/3
-l $path or -e _ and not -d _
-l $path -e _ not -d _
Truth table50%2/4
A or B and not(C)
A= -l $pathB= -e _C= not -d _
ABCresult
1XX1
0111
00X0
0100
434 13 ▶ eval { unlink $path; 1 } or throw('io.remove', { path => $path, error => os_error($@) });
Branch: 1 branch
BranchTrueFalseTotal
eval { do { &App::FileSync::IO::unlink($path); 1 } } or throw("io.remove", {"path", $path, "error", os_error($@)}) 13 0 13
435 } elsif (-d _) {
436 0 ▶ eval { rmdir $path; 1 } or throw('io.replace_dir', { path => $path });
Branch: 1 branch
BranchTrueFalseTotal
eval { do { &App::FileSync::IO::rmdir($path); 1 } } or throw("io.replace_dir", {"path", $path}) 0 0 0
437 }
438  
439 265 return 1;
440 }
441  
442 =head2 set_mtime
443  
444 Purpose: set a file's modification time, keeping sub-second precision where
445 the platform allows.
446  
447 Args: C<$path>, C<$mtime> (epoch; C<undef> leaves the file alone).
448  
449 Returns: 1.
450  
451 Side Effects: changes the file's atime and mtime. Where C<Time::HiRes::utime>
452 is unimplemented (some Windows builds) whole seconds are stored, which the
453 2-second comparison tolerance already allows for.
454  
455 Usage:
456  
457 set_mtime($temp, 1_700_000_123.456);
458  
459 =head3 EXAMPLE
460  
461 set_mtime('/tmp/a.txt', time - 3600);
462  
463 =head3 API SPECIFICATION
464  
465 =head4 INPUT
466  
467 [
468 { name => 'path', type => 'string', min => 1 },
469 { name => 'mtime', type => 'number', optional => 1 },
470 ]
471  
472 =head4 OUTPUT
473  
474 { type => 'integer', min => 1, max => 1 }
475  
476 =head3 MESSAGES
477  
478 Key Meaning Resolution
479 io.utime the timestamp cannot be set check ownership of the file
480  
481 =head3 FORMAL SPECIFICATION
482  
483 ΔFS
484 path? : PATH ; m? : ℝ ∪ {⊥}
485 m? = ⊥ ⇒ FS' = FS
486 m? ≠ ⊥ ⇒ |mtime'(path?) − m?| < 1
487  
488 =cut
489  
490 268 ▶sub set_mtime {
Subroutine set_mtime: called CC=6 SCAR=18.1
Pod documented
491 268 my ($path, $mtime) = @_;
492  
493 268 ▶ return 1 if !defined $mtime || eval { Time::HiRes::utime($mtime, $mtime, $path); 1 };
Branch: 1 branch
BranchTrueFalseTotal
if not defined $mtime or eval { do { &Time::HiRes::utime($mtime, $mtime, $path); 1 } } 266 2 268
Condition66%2/3
not defined $mtime or eval { do { &Time::HiRes::utime($mtime, $mtime, $path); 1 } }
l!l&&r!l&&!r
02662
MC/DC50%1/2
not defined $mtime or eval { do { &Time::HiRes::utime($mtime, $mtime, $path); 1 } }
not defined $mtime eval { do { &Time::HiRes::utime($mtime, $mtime, $path); 1 } }
Truth table66%2/3
not(A) or B
A= not defined $mtimeB= eval { do { &Time::HiRes::utime($mtime, $mtime, $path); 1 } }
ABresult
1X1
011
000
494  
495 # Only the "unimplemented" croak is expected; anything else is a real
496 # failure, reported with the reason Time::HiRes gave.
497 2 my $error = $@;
498 2 ▶ throw('io.utime', { path => $path, error => strip_location($error) })
Branch: 1 branch
BranchTrueFalseTotal
unless not ref $error and $error =~ /unimplemented/i 1 1 2
Condition66%2/3
not ref $error and $error =~ /unimplemented/i
!ll&&!rl&&r
011
MC/DC50%1/2
not ref $error and $error =~ /unimplemented/i
not ref $error $error =~ /unimplemented/i
Truth table66%2/3
not(A) and B
A= not ref $errorB= $error =~ /unimplemented/i
ABresult
0X0
100
111
499 unless !ref $error && $error =~ /unimplemented/i;
500  
501 1 ▶ eval { utime(int($mtime), int($mtime), $path); 1 }
Branch: 1 branch
BranchTrueFalseTotal
eval { do { &App::FileSync::IO::utime(int $mtime, int $mtime, $path); 1 } } or throw("io.utime", {"path", $path, "error", os_error($@)}) 1 0 1
502 or throw('io.utime', { path => $path, error => os_error($@) });
503 1 return 1;
504 }
505  
506 =head2 sha256_file
507  
508 Purpose: hash a file's contents.
509  
510 Args: C<$path>.
511  
512 Returns: the lower-case hex SHA-256, or C<undef> when C<$path> is not a
513 readable regular file.
514  
515 Side Effects: none.
516  
517 Usage:
518  
519 my $hash = sha256_file($abs);
520  
521 =head3 EXAMPLE
522  
523 print sha256_file('/etc/hostname'), "\n";
524  
525 =head3 API SPECIFICATION
526  
527 =head4 INPUT
528  
529 [ { name => 'path', type => 'string', min => 1 } ]
530  
531 =head4 OUTPUT
532  
533 { type => 'string', optional => 1, matches => qr/\A[0-9a-f]{64}\z/ }
534  
535 =head3 MESSAGES
536  
537 None; an unreadable file yields C<undef>.
538  
539 =head3 FORMAL SPECIFICATION
540  
541 sha256_file : PATH ⇸ HEX64
542 sha256_file(p) = sha256(FS(p)) if p ∈ dom FS ∧ kind p = file ∧ readable p
543  
544 =cut
545  
546 8 ▶sub sha256_file {
Subroutine sha256_file: called CC=3 SCAR=11.6
Pod documented
547 8 my ($path) = @_;
548  
549 8 my $sha = Digest::SHA->new($SHA_BITS);
550 8 ▶ my $ok = -f $path && eval { $sha->addfile($path, 'b'); 1 };
Condition33%1/3
-f $path && eval { do { $sha->addfile($path, 'b'); 1 } }
!ll&&!rl&&r
008
MC/DC0%0/2
-f $path && eval { do { $sha->addfile($path, 'b'); 1 } }
-f $path eval { do { $sha->addfile($path, 'b'); 1 } }
Truth table33%1/3
A && B
A= -f $pathB= eval { do { $sha->addfile($path, 'b'); 1 } }
ABresult
0X0
100
111
551  
552 8 ▶ return $ok ? $sha->hexdigest() : undef;
Branch: 1 branch
BranchTrueFalseTotal
$ok ? : 8 0 8
553 }
554  
555 =head2 list_dir
556  
557 Purpose: the entries of a directory.
558  
559 Args: C<$directory>.
560  
561 Returns: an arrayref of names, sorted, without C<.> and C<..>; C<undef> when
562 the directory cannot be read (C<$!> says why).
563  
564 Side Effects: none.
565  
566 Usage:
567  
568 my $names = list_dir($dir) or return 0;
569  
570 =head3 EXAMPLE
571  
572 print "$_\n" for @{ list_dir('/tmp') || [] };
573  
574 =head3 API SPECIFICATION
575  
576 =head4 INPUT
577  
578 [ { name => 'directory', type => 'string', min => 1 } ]
579  
580 =head4 OUTPUT
581  
582 { type => 'arrayref', optional => 1 }
583  
584 =head3 MESSAGES
585  
586 None; an unreadable directory yields C<undef>.
587  
588 =head3 FORMAL SPECIFICATION
589  
590 list_dir : PATH ⇸ seq NAME
591 list_dir(d) = sort(children d \ {".", ".."}) if readable d
592  
593 =cut
594  
595 1507 ▶sub list_dir {
Subroutine list_dir: called CC=3 SCAR=11.0
Pod documented
596 1507 my ($directory) = @_;
597  
598 # A missing or unreadable directory is an answer here, not an exception,
599 # so autodie is switched off for this one call and $! is left for the
600 # caller to report.
601 1507 my $dh;
602 341 ▶ my $opened = do { no autodie qw(opendir); opendir($dh, $directory) };
Subroutine BEGIN: called CC=1 SCAR=0.0
603 1507 ▶ return undef unless $opened; ## no critic (Subroutines::ProhibitExplicitReturnUndef)
Branch: 1 branch
BranchTrueFalseTotal
unless $opened 1 1506 1507
604  
605 1506 ▶ my @names = sort grep { $_ ne '.' && $_ ne '..' } readdir($dh);
Condition100%3/3
$_ ne '.' && $_ ne '..'
!ll&&!rl&&r
150615063473
MC/DC100%2/2
$_ ne '.' && $_ ne '..'
$_ ne '.' $_ ne '..'
Truth table100%3/3
A && B
A= $_ ne '.'B= $_ ne '..'
ABresult
0X0
100
111
606 1506 closedir $dh;
607  
608 1506 return \@names;
609 }
610  
611 =head2 copy_preserving
612  
613 Purpose: copy one regular file, keeping its mode and mtime.
614  
615 Args: C<$source>, C<$destination>, optional C<\@stat> of the source (saves a
616 second C<stat> when the caller already has one).
617  
618 Returns: 1.
619  
620 Side Effects: creates C<$destination>'s parent directories; overwrites
621 C<$destination>.
622  
623 Usage:
624  
625 copy_preserving($from, $to, \@stat);
626  
627 =head3 EXAMPLE
628  
629 copy_preserving('/srv/a.txt', '/backup/a.txt');
630  
631 =head3 API SPECIFICATION
632  
633 =head4 INPUT
634  
635 [
636 { name => 'source', type => 'string', min => 1 },
637 { name => 'destination', type => 'string', min => 1 },
638 { name => 'stat', type => 'arrayref', optional => 1 },
639 ]
640  
641 =head4 OUTPUT
642  
643 { type => 'integer', min => 1, max => 1 }
644  
645 =head3 MESSAGES
646  
647 Key Meaning Resolution
648 io.copy the copy could not be made check space and permissions
649  
650 =head3 FORMAL SPECIFICATION
651  
652 ΔFS
653 src?, dst? : PATH
654 FS'(dst?) = FS(src?) ∧ mtime'(dst?) = mtime(src?) ∧ mode'(dst?) = mode(src?)
655  
656 =cut
657  
658 16 ▶sub copy_preserving {
Subroutine copy_preserving: called CC=5 SCAR=17.3
Pod documented
659 16 my ($source, $destination, $stat) = @_;
660  
661 16 ▶ $stat = [ Time::HiRes::stat($source) ] unless ref($stat) eq 'ARRAY' && @{$stat};
Branch: 1 branch
BranchTrueFalseTotal
unless ref $stat eq "ARRAY" and @{$stat;} 0 16 16
Condition33%1/3
ref $stat eq "ARRAY" and @{$stat;}
!ll&&!rl&&r
0016
MC/DC0%0/2
ref $stat eq "ARRAY" and @{$stat;}
ref $stat eq "ARRAY" @{$stat;}
Truth table33%1/3
A and B
A= ref $stat eq "ARRAY"B= @{$stat;}
ABresult
0X0
100
111
662 16 ensure_dir(dirname($destination));
663  
664 16 ▶ File::Copy::copy($source, $destination)
Branch: 1 branch
BranchTrueFalseTotal
File::Copy::copy($source, $destination) or throw("io.copy", {"from", $source, "to", $destination, "error", "$!"}) 16 0 16
665 or throw('io.copy', { from => $source, to => $destination, error => "$!" });
666  
667 16 ▶ chmod($stat->[$STAT_MODE] & $MODE_MASK, $destination) if $HAS_MODES;
Branch: 1 branch
BranchTrueFalseTotal
if $HAS_MODES 16 0 16
668 16 utime($stat->[$STAT_MTIME], $stat->[$STAT_MTIME], $destination);
669  
670 16 return 1;
671 }
672  
673 =head2 append_line
674  
675 Purpose: append one line to a log or journal.
676  
677 Args: C<$path>, C<$line> (without a newline).
678  
679 Returns: 1.
680  
681 Side Effects: creates C<$path> and its directory if needed. If the file ends
682 in a torn line from a killed run, a newline is written first so the new entry
683 is not glued to the fragment.
684  
685 Usage:
686  
687 append_line($journal, json_encode($event));
688  
689 =head3 EXAMPLE
690  
691 append_line('/tmp/run.log', 'started');
692  
693 =head3 API SPECIFICATION
694  
695 =head4 INPUT
696  
697 [
698 { name => 'path', type => 'string', min => 1 },
699 { name => 'line', type => 'string' },
700 ]
701  
702 =head4 OUTPUT
703  
704 { type => 'integer', min => 1, max => 1 }
705  
706 =head3 MESSAGES
707  
708 Key Meaning Resolution
709 io.append the file cannot be appended to check permissions and space
710  
711 =head3 FORMAL SPECIFICATION
712  
713 ΔFS
714 path? : PATH ; line? : seq CHAR
715 let old = FS(path?) if path? ∈ dom FS, else ⟨⟩
716 let sep = "\n" if old ≠ ⟨⟩ ∧ last old ≠ "\n", else ⟨⟩
717 FS'(path?) = old ⁀ sep ⁀ line? ⁀ "\n"
718  
719 =cut
720  
721 731 ▶sub append_line {
Subroutine append_line: called CC=4 SCAR=14.0
Pod documented
722 731 my ($path, $line) = @_;
723  
724 731 ensure_dir(dirname($path));
725 731 ▶ my $prefix = _ends_mid_line($path) ? "\n" : '';
Branch: 1 branch
BranchTrueFalseTotal
_ends_mid_line($path) ? : 1 730 731
726  
727 731 my $fh = open_file($path, '>>');
728 731 my $written = print {$fh} $prefix, $line, "\n";
729 731 my $closed = eval { close $fh; 1 };
730 731 ▶ throw('io.append', { path => $path, error => os_error($@) }) unless $written && $closed;
Branch: 1 branch
BranchTrueFalseTotal
unless $written and $closed 0 731 731
Condition33%1/3
$written and $closed
!ll&&!rl&&r
00731
MC/DC0%0/2
$written and $closed
$written $closed
Truth table33%1/3
A and B
A= $writtenB= $closed
ABresult
0X0
100
111
731  
732 731 return 1;
733 }
734  
735 =head2 ensure_dir
736  
737 Purpose: make sure a directory exists.
738  
739 Args: C<$directory>.
740  
741 Returns: C<$directory>.
742  
743 Side Effects: creates it and any missing parents.
744  
745 Usage:
746  
747 ensure_dir(dirname($path));
748  
749 =head3 EXAMPLE
750  
751 ensure_dir('/tmp/a/b/c');
752  
753 =head3 API SPECIFICATION
754  
755 =head4 INPUT
756  
757 [ { name => 'directory', type => 'string', min => 1 } ]
758  
759 =head4 OUTPUT
760  
761 { type => 'string', min => 1 }
762  
763 =head3 MESSAGES
764  
765 Key Meaning Resolution
766 io.mkdir the directory cannot be created check permissions
767  
768 =head3 FORMAL SPECIFICATION
769  
770 ΔFS
771 d? : PATH
772 kind'(d?) = dir ∧ ∀ a : ancestors d? • kind'(a) = dir
773  
774 =cut
775  
776 3142 ▶sub ensure_dir {
Subroutine ensure_dir: called CC=3 SCAR=11.0
Pod documented
777 3142 my ($directory) = @_;
778  
779 3142 ▶ unless (-d $directory) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-d $directory) 676 2466 3142
780 676 make_path($directory, { error => \my $errors });
781 676 ▶ throw('io.mkdir', { path => $directory, error => _path_error($errors) })
Branch: 1 branch
BranchTrueFalseTotal
unless -d $directory 2 674 676
782 unless -d $directory;
783 }
784  
785 3140 return $directory;
786 }
787  
788 # _rename_or_discard
789 # Purpose: rename a temporary file over its target.
790 # Entry: $temp exists; $target's directory exists.
791 # Exit: returns 1, or raises io.rename after removing $temp.
792 # Side effects: $temp disappears either way.
793 1040 ▶sub _rename_or_discard :Private {
Subroutine _rename_or_discard: called CC=2 SCAR=8.1
794 1040 my ($temp, $target) = @_;
795  
796 1040 ▶ unless (eval { rename $temp, $target; 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
unless (eval { do { &App::FileSync::IO::rename($temp, $target); 1 } }) 0 1040 1040
797 0 my $error = os_error($@);
798 0 _discard($temp);
799 0 throw('io.rename', { from => $temp, to => $target, error => $error });
800 }
801  
802 1040 return 1;
803 341 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
804  
805 # _discard
806 # Purpose: best-effort removal of a temporary file after a failure.
807 # Entry: $path may or may not exist.
808 # Exit: returns 1.
809 # Side effects: removes $path when it can; never raises, so the original
810 # error is the one the caller reports.
811 0 ▶sub _discard :Private {
Subroutine _discard: not called CC=1 SCAR=1.7
812 0 my ($path) = @_;
813  
814 0 ▶ { no autodie qw(unlink); unlink $path }
Subroutine BEGIN: called CC=1 SCAR=0.6
815 0 return 1;
816 341 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
817  
818 # _ends_mid_line
819 # Purpose: detect a log or journal whose last line was torn by a kill.
820 # Entry: $path may or may not exist.
821 # Exit: returns 1 when the file is non-empty and its last byte is not
822 # a newline, otherwise 0.
823 # Side effects: none.
824 731 ▶sub _ends_mid_line :Private {
Subroutine _ends_mid_line: called CC=4 SCAR=13.9
825 731 my ($path) = @_;
826  
827 731 ▶ return 0 unless -s $path;
Branch: 1 branch
BranchTrueFalseTotal
unless -s $path 137 594 731
828  
829 594 my $fh = open_file($path, '<');
830 # Only the final byte matters.
831 594 seek($fh, -1, SEEK_END);
832 594 read($fh, my $last, 1);
833 594 close $fh;
834  
835 594 ▶ return (defined $last && $last ne "\n") ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
defined $last && $last ne "\n" ? : 1 593 594
Condition66%2/3
defined $last and $last ne "\n"
!ll&&!rl&&r
05931
MC/DC50%1/2
defined $last and $last ne "\n"
defined $last $last ne "\n"
Truth table66%2/3
A and B
A= defined $lastB= $last ne "\n"
ABresult
0X0
100
111
836 341 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
837  
838 # _path_error
839 # Purpose: the first reason File::Path recorded, for an io.mkdir message.
840 # Entry: $errors is File::Path's error arrayref (may be undef or empty).
841 # Exit: returns the reason text, or the current $! when there is none.
842 # Side effects: none.
843 2 ▶sub _path_error :Private {
Subroutine _path_error: called CC=5 SCAR=17.8
844 2 my ($errors) = @_;
845  
846 2 ▶ my ($first) = @{ $errors || [] };
Condition50%1/2
$errors || []
l!l
20
MC/DC0%0/1
$errors || []
$errors
Truth table50%1/2
A
A= $errors
Aresult
11
00
847 2 ▶ my ($reason) = $first ? values %{$first} : ();
Branch: 1 branch
BranchTrueFalseTotal
$first ? : 2 0 2
848 2 ▶ return defined $reason && length $reason ? $reason : "$!";
Branch: 1 branch
BranchTrueFalseTotal
defined $reason && length $reason ? : 2 0 2
Condition33%1/3
defined $reason and length $reason
!ll&&!rl&&r
002
MC/DC0%0/2
defined $reason and length $reason
defined $reason length $reason
Truth table33%1/3
A and B
A= defined $reasonB= length $reason
ABresult
0X0
100
111
849 341 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
850  
851 341 1;
852  
853 __END__
« blib/lib/App/FileSync/Protocol.pm ↑ Summary blib/lib/App/FileSync/Transport/Local.pm »