blib/lib/App/FileSync/Snapshot.pm

filter: Statementstmt 92.3% 218 / 236 Branchbran 58.3% 56 / 96 Conditioncond 50.0% 31 / 62 MC/DCmcdc 22.2% 8 / 36 Subroutinesub 100% 35 / 35 Podpod 100% 8 / 8 totaltotal 75.2% 356 / 473 CC 78 SCAR 24.1
CC
78
Cov
77%
_copy_out
23.0
restore
19.4
_clean_stale_temps
16.7
CRAP 11.1
« blib/lib/App/FileSync/Merge.pm ↑ Summary blib/lib/App/FileSync/Verify.pm »
1 package App::FileSync::Snapshot;
2  
3 # Daily point-in-time copies of a replica's tree, kept inside the replica root
4 # under .filesync-snapshots/YYYY-MM-DD. Hard links make an unchanged file
5 # cost nothing; copies are used where links are not possible.
6  
7 328 ▶use App::FileSync::Platform;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 328 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 328 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 328 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 328 ▶use File::Path qw(remove_tree);
Subroutine BEGIN: called CC=1 SCAR=0.0
14 328 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 328 ▶use POSIX qw(strftime);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 328 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 328 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
18 328 ▶use Time::HiRes ();
Subroutine BEGIN: called CC=1 SCAR=0.0
19  
20 328 ▶use App::FileSync qw(validate_relpath);
Subroutine BEGIN: called CC=1 SCAR=0.0
21 328 ▶use App::FileSync::Args qw(named);
Subroutine BEGIN: called CC=1 SCAR=0.0
22 328 ▶use App::FileSync::Constants qw($MODE_MASK $ROOT_MARKER $SNAPSHOT_DIR $STALE_TEMP_SECONDS $TEMP_PREFIX $STAT_MODE $STAT_SIZE $STAT_MTIME);
Subroutine BEGIN: called CC=1 SCAR=0.0
23 328 ▶use App::FileSync::I18N qw(throw os_error);
Subroutine BEGIN: called CC=1 SCAR=0.0
24 328 ▶use App::FileSync::IO qw(copy_preserving ensure_dir list_dir);
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 328 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 # Kept for compatibility: the snapshot directory's name.
29 328 our $DIR_NAME = $SNAPSHOT_DIR;
30  
31 # The two ways a snapshot can hold a file.
32 328 Readonly::Scalar my $HARDLINK => 'hardlink';
33 328 Readonly::Scalar my $COPY => 'copy';
34  
35 # A snapshot date (as strftime writes it and as the pattern recognises it),
36 # and an interrupted attempt's directory.
37 328 Readonly::Scalar my $DATE_FORMAT => '%Y-%m-%d';
38 328 Readonly my $DATE => qr/\A\d{4}-\d{2}-\d{2}\z/;
39 328 Readonly my $TEMP_DIR => qr/\A\.tmp-\d+-\d+\z/;
40 328 Readonly my $TEMP_FILE => qr/\A\Q$TEMP_PREFIX\E/;
41  
42 # Windows has no POSIX permission bits worth restoring on a directory.
43 328 Readonly::Scalar my $HAS_MODES => $^O ne 'MSWin32';
44  
45 # Range for the random part of a temporary snapshot directory's name.
46 328 Readonly::Scalar my $TEMP_RANGE => 1_000_000;
47  
48 # Every function takes the replica root and needs it.
49 328 my %ROOT = (root => { type => 'string', min => 1 });
50  
51 =encoding utf8
52  
53 =head1 NAME
54  
55 App::FileSync::Snapshot - daily snapshots of a replica
56  
57 =head1 SYNOPSIS
58  
59 my $made = App::FileSync::Snapshot::create(root => $replica_root);
60 my $all = App::FileSync::Snapshot::list(root => $replica_root);
61 App::FileSync::Snapshot::prune(root => $replica_root, keep => 14);
62 App::FileSync::Snapshot::restore(root => $replica_root, date => '2026-10-22', to => '/tmp/out');
63  
64 =head1 FUNCTIONS
65  
66 =head2 snapshot_root
67  
68 Purpose: where a replica keeps its snapshots.
69  
70 Args: C<$root>, the replica's sync root.
71  
72 Returns: F<ROOT/.filesync-snapshots>.
73  
74 Side Effects: none.
75  
76 Usage:
77  
78 my $dir = App::FileSync::Snapshot::snapshot_root($root);
79  
80 =head3 EXAMPLE
81  
82 print App::FileSync::Snapshot::snapshot_root('/data/replica'), "\n";
83  
84 =head3 API SPECIFICATION
85  
86 =head4 INPUT
87  
88 [ { name => 'root', type => 'string', min => 1 } ]
89  
90 =head4 OUTPUT
91  
92 { type => 'string', min => 1 }
93  
94 =head3 MESSAGES
95  
96 Key Meaning Resolution
97 snapshot.no_root no root given pass the replica root
98  
99 =head3 FORMAL SPECIFICATION
100  
101 snapshot_root(r) = r / ".filesync-snapshots"
102  
103 =cut
104  
105 30 ▶sub snapshot_root {
Subroutine snapshot_root: called CC=3 SCAR=12.5
Pod documented
106 30 my ($root) = @_;
107  
108 30 ▶ throw('snapshot.no_root') unless defined $root && length $root;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $root and length $root 0 30 30
Condition33%1/3
defined $root and length $root
!ll&&!rl&&r
0030
MC/DC0%0/2
defined $root and length $root
defined $root length $root
Truth table33%1/3
A and B
A= defined $rootB= length $root
ABresult
0X0
100
111
109 30 return File::Spec->catdir($root, $SNAPSHOT_DIR);
110 }
111  
112 =head2 date_for_epoch
113  
114 Documented with L</default_mode> below.
115  
116 =head2 is_date
117  
118 Documented with L</default_mode> below.
119  
120 =head2 default_mode
121  
122 Purpose: snapshot naming and the platform's preferred storage.
123  
124 Args: C<date_for_epoch($epoch)> (default now); C<is_date($string)>.
125  
126 Returns: C<YYYY-MM-DD> (UTC); 1 or 0; C<hardlink>, or C<copy> on Windows.
127  
128 Side Effects: none.
129  
130 Usage:
131  
132 my $today = App::FileSync::Snapshot::date_for_epoch();
133  
134 =head3 EXAMPLE
135  
136 print App::FileSync::Snapshot::is_date('2026-10-22'), "\n"; # 1
137  
138 =head3 API SPECIFICATION
139  
140 =head4 INPUT
141  
142 [ { name => 'value', type => 'scalar', optional => 1 } ]
143  
144 =head4 OUTPUT
145  
146 { type => 'scalar' }
147  
148 =head3 MESSAGES
149  
150 None.
151  
152 =head3 FORMAL SPECIFICATION
153  
154 date_for_epoch(e) = yyyy-mm-dd of gmtime(e)
155 is_date(s) ⇔ s ∈ DIGIT⁴ ⁀ "-" ⁀ DIGIT² ⁀ "-" ⁀ DIGIT²
156 default_mode = copy if OS = MSWin32, hardlink otherwise
157  
158 =cut
159  
160 16 ▶sub date_for_epoch {
Subroutine date_for_epoch: called CC=2 SCAR=6.9
Pod documented
161 16 my ($epoch) = @_;
162  
163 16 ▶ return strftime($DATE_FORMAT, gmtime($epoch // time));
Condition100%2/2
$epoch // time
l!l
133
MC/DC100%1/1
$epoch // time
$epoch
Truth table100%2/2
A
A= $epoch
Aresult
11
00
164 }
165  
166 20 ▶sub is_date {
Subroutine is_date: called CC=3 SCAR=13.1
Pod documented
167 20 my ($date) = @_;
168  
169 20 ▶ return (defined $date && $date =~ $DATE) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
defined $date && $date =~ /$DATE/ ? : 20 0 20
Condition33%1/3
defined $date and $date =~ /$DATE/
!ll&&!rl&&r
0020
MC/DC0%0/2
defined $date and $date =~ /$DATE/
defined $date $date =~ /$DATE/
Truth table33%1/3
A and B
A= defined $dateB= $date =~ /$DATE/
ABresult
0X0
100
111
170 }
171  
172 14 ▶sub default_mode {
Subroutine default_mode: called CC=2 SCAR=7.6
Pod documented
173 14 ▶ return $^O eq 'MSWin32' ? $COPY : $HARDLINK;
Branch: 1 branch
BranchTrueFalseTotal
$^O eq 'MSWin32' ? : 0 14 14
174 }
175  
176 =head2 create
177  
178 Purpose: take today's snapshot of the replica tree.
179  
180 Args: C<root> (required), optional C<date> (default today, from C<now>), C<now>,
181 C<mode> (C<hardlink> or C<copy>; default L</default_mode>).
182  
183 A day is never overwritten: the first snapshot of the day is the state before
184 that day's first sync, which is the one worth keeping.
185  
186 Returns: C<{ date, path, created, files, bytes, linked, copied, mode }>;
187 C<created> is 0 (and the counts 0) when that day already exists.
188  
189 Side Effects: builds the snapshot in a temporary directory and renames it into
190 place, so an interrupted run leaves no half snapshot. Removes interrupted
191 attempts older than an hour. Hard links share storage with the live tree;
192 a file that cannot be linked (another filesystem) is copied.
193  
194 Usage:
195  
196 my $made = App::FileSync::Snapshot::create(root => $root, mode => 'hardlink');
197  
198 =head3 EXAMPLE
199  
200 my $made = App::FileSync::Snapshot::create(root => '/data/replica');
201 print "$made->{files} files in $made->{path}\n" if $made->{created};
202  
203 =head3 API SPECIFICATION
204  
205 =head4 INPUT
206  
207 {
208 root => { type => 'string', min => 1 },
209 date => { type => 'string', optional => 1, matches => qr/\A\d{4}-\d{2}-\d{2}\z/ },
210 now => { type => 'number', optional => 1 },
211 mode => { type => 'string', optional => 1, memberof => [ 'hardlink', 'copy' ] },
212 }
213  
214 =head4 OUTPUT
215  
216 { type => 'hashref' }
217  
218 =head3 MESSAGES
219  
220 Key Meaning Resolution
221 snapshot.not_dir the root is not a directory check the replica root
222 snapshot.bad_date the date is not YYYY-MM-DD fix the argument
223 snapshot.bad_mode the mode is not hardlink or copy fix snapshot_mode
224 snapshot.read a directory cannot be read check permissions
225 snapshot.failed a link, copy or rename failed check permissions and space
226  
227 =head3 FORMAL SPECIFICATION
228  
229 ΔFS
230 let t = snapshot_root / date
231 t ∈ dom FS ⇒ FS' = FS ∧ created = 0
232 t ∉ dom FS ⇒ tree'(t) = tree(root) \ reserved ∧ created = 1
233  
234 =head3 PSEUDOCODE
235  
236 if today's directory exists: report it and stop
237 remove interrupted attempts older than an hour
238 mirror the tree into a fresh temporary directory, linking or copying
239 rename the temporary directory to the date
240 on any failure remove the temporary directory and raise
241  
242 =cut
243  
244 16 ▶sub create {
Subroutine create: called CC=10 SCAR=24.6
Pod documented
245 16 my $args = named(\@_, {
246 %ROOT,
247 date => { type => 'string', optional => 1 },
248 now => { type => 'number', optional => 1 },
249 mode => { type => 'string', optional => 1 },
250 }, 'Snapshot::create');
251  
252 16 my $root = $args->{root};
253 16 ▶ throw('snapshot.not_dir', { path => $root }) unless -d $root;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $root 0 16 16
254  
255 16 ▶ my $date = defined $args->{date} ? $args->{date} : date_for_epoch($args->{now});
Branch: 1 branch
BranchTrueFalseTotal
defined $args->{'date'} ? : 8 8 16
256 16 ▶ throw('snapshot.bad_date', { date => $date }) unless is_date($date);
Branch: 1 branch
BranchTrueFalseTotal
unless is_date($date) 0 16 16
257  
258 16 ▶ my $mode = defined $args->{mode} ? $args->{mode} : default_mode();
Branch: 1 branch
BranchTrueFalseTotal
defined $args->{'mode'} ? : 7 9 16
259 16 ▶ throw('snapshot.bad_mode', { mode => $mode }) unless $mode eq $HARDLINK || $mode eq $COPY;
Branch: 1 branch
BranchTrueFalseTotal
unless $mode eq $HARDLINK or $mode eq $COPY 0 16 16
Condition66%2/3
$mode eq $HARDLINK or $mode eq $COPY
l!l&&r!l&&!r
1510
MC/DC0%0/2
$mode eq $HARDLINK or $mode eq $COPY
$mode eq $HARDLINK $mode eq $COPY
Truth table66%2/3
A or B
A= $mode eq $HARDLINKB= $mode eq $COPY
ABresult
1X1
011
000
260  
261 16 my $dir = snapshot_root($root);
262 16 my $target = File::Spec->catdir($dir, $date);
263 16 my %result = (date => $date, path => $target, mode => $mode);
264  
265 16 ▶ return { %result, created => 0, files => 0, bytes => 0 } if -e $target;
Branch: 1 branch
BranchTrueFalseTotal
if -e $target 3 13 16
266  
267 13 ensure_dir($dir);
268 13 _clean_stale_temps($dir);
269  
270 13 my $temp = File::Spec->catdir($dir, '.tmp-' . $$ . '-' . int(rand($TEMP_RANGE)));
271 13 ensure_dir($temp);
272  
273 13 my $counts = { files => 0, bytes => 0, linked => 0, copied => 0 };
274 13 my $ok = eval {
275 13 _mirror($root, $temp, $mode, $counts, 1);
276 13 rename $temp, $target;
277 13 1;
278 };
279  
280 13 ▶ unless ($ok) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ok) 0 13 13
281 0 my $error = $@;
282 0 eval { remove_tree($temp) };
283 # autodie's objects carry the OS reason; catalogued errors pass through.
284 0 ▶ throw('snapshot.failed', { path => $target, error => os_error($error) }) if ref $error;
Branch: 1 branch
BranchTrueFalseTotal
if ref $error 0 0 0
285 0 die $error; ## no critic (ErrorHandling::RequireCarping) -- rethrow the catalogued error unchanged
286 }
287  
288 13 return { %result, created => 1, %{$counts} };
289 }
290  
291 =head2 list
292  
293 Purpose: every snapshot, newest first.
294  
295 Args: C<root>.
296  
297 Returns: an arrayref of C<{ date, path, files, bytes }>.
298  
299 Side Effects: walks every snapshot to count it.
300  
301 Usage:
302  
303 for my $snap (@{ App::FileSync::Snapshot::list(root => $root) }) { ... }
304  
305 =head3 EXAMPLE
306  
307 printf "%s %d files\n", $_->{date}, $_->{files}
308 for @{ App::FileSync::Snapshot::list(root => '/data/replica') };
309  
310 =head3 API SPECIFICATION
311  
312 =head4 INPUT
313  
314 { root => { type => 'string', min => 1 } }
315  
316 =head4 OUTPUT
317  
318 { type => 'arrayref' }
319  
320 =head3 MESSAGES
321  
322 Key Meaning Resolution
323 snapshot.read the snapshot directory is unreadable check permissions
324  
325 =head3 FORMAL SPECIFICATION
326  
327 list(r) = sort_desc(date) ⟨ (d, r/S/d, #files(r/S/d), Σ size) | d ∈ children(r/S) ∩ DATE ⟩
328  
329 =cut
330  
331 8 ▶sub list {
Subroutine list: called CC=4 SCAR=14.1
Pod documented
332 8 my $args = named(\@_, {%ROOT}, 'Snapshot::list');
333  
334 8 my $dir = snapshot_root($args->{root});
335 8 ▶ return [] unless -d $dir;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $dir 0 8 8
336  
337 8 ▶ my $names = list_dir($dir) or throw('snapshot.read', { path => $dir, error => os_error() });
Branch: 1 branch
BranchTrueFalseTotal
my $names = list_dir($dir) or throw("snapshot.read", {"path", $dir, "error", os_error()}) 8 0 8
338 8 ▶ my @dates = grep { $_ =~ $DATE && -d File::Spec->catdir($dir, $_) } @{$names};
Condition33%1/3
$_ =~ /$DATE/ && -d 'File::Spec'->catdir($dir, $_)
!ll&&!rl&&r
0017
MC/DC0%0/2
$_ =~ /$DATE/ && -d 'File::Spec'->catdir($dir, $_)
$_ =~ /$DATE/ -d 'File::Spec'->catdir($dir, $_)
Truth table33%1/3
A && B
A= $_ =~ /$DATE/B= -d 'File::Spec'->catdir($dir, $_)
ABresult
0X0
100
111
339  
340 my @snapshots = map {
341 8 my $path = File::Spec->catdir($dir, $_);
342 17 my $counts = { files => 0, bytes => 0 };
343 17 _count($path, $counts);
344 17 { date => $_, path => $path, %{$counts} };
345 } reverse @dates;
346  
347 8 return \@snapshots;
348 }
349  
350 =head2 prune
351  
352 Purpose: keep the newest snapshots and remove the rest.
353  
354 Args: C<root>, C<keep> (0 or undef keeps everything), C<dry_run>.
355  
356 Returns: C<{ removed =E<gt> [dates], kept =E<gt> [dates] }>.
357  
358 Side Effects: removes old snapshot directories unless C<dry_run>.
359  
360 Usage:
361  
362 App::FileSync::Snapshot::prune(root => $root, keep => 14);
363  
364 =head3 EXAMPLE
365  
366 my $plan = App::FileSync::Snapshot::prune(root => $root, keep => 7, dry_run => 1);
367 print "would remove @{ $plan->{removed} }\n";
368  
369 =head3 API SPECIFICATION
370  
371 =head4 INPUT
372  
373 {
374 root => { type => 'string', min => 1 },
375 keep => { type => 'integer', min => 0, optional => 1 },
376 dry_run => { type => 'boolean', optional => 1 },
377 }
378  
379 =head4 OUTPUT
380  
381 {
382 type => 'hashref',
383 schema => { removed => { type => 'arrayref' }, kept => { type => 'arrayref' } },
384 }
385  
386 =head3 MESSAGES
387  
388 Key Meaning Resolution
389 snapshot.remove a snapshot cannot be removed check permissions
390  
391 =head3 FORMAL SPECIFICATION
392  
393 let s = list(root) (newest first)
394 kept = s[1 .. keep] ; removed = s[keep + 1 .. #s] if keep > 0 ∧ #s > keep
395 kept = s ; removed = ⟨⟩ otherwise
396  
397 =cut
398  
399 3 ▶sub prune {
Subroutine prune: called CC=5 SCAR=16.2
Pod documented
400 3 my $args = named(\@_, {
401 %ROOT,
402 keep => { type => 'integer', min => 0, optional => 1 },
403 dry_run => { type => 'boolean', optional => 1 },
404 }, 'Snapshot::prune');
405  
406 3 my $root = $args->{root};
407 3 my $keep = $args->{keep};
408 3 my @dates = map { $_->{date} } @{ list(root => $root) };
409  
410 3 ▶ return { removed => [], kept => \@dates } unless $keep && @dates > $keep;
Branch: 1 branch
BranchTrueFalseTotal
unless $keep and @dates > $keep 1 2 3
Condition66%2/3
$keep and @dates > $keep
!ll&&!rl&&r
012
MC/DC50%1/2
$keep and @dates > $keep
$keep @dates > $keep
Truth table66%2/3
A and B
A= $keepB= @dates > $keep
ABresult
0X0
100
111
411  
412 2 my @kept = @dates[ 0 .. $keep - 1 ];
413 2 my @removed = @dates[ $keep .. $#dates ];
414  
415 2 ▶ unless ($args->{dry_run}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($args->{"dry_run"}) 2 0 2
416 2 _remove_snapshot(File::Spec->catdir(snapshot_root($root), $_)) for @removed;
417 }
418  
419 2 return { removed => \@removed, kept => \@kept };
420 }
421  
422 =head2 restore
423  
424 Purpose: copy a snapshot (or part of one) out.
425  
426 Args: C<root>, C<date>, C<to> (the destination directory; created if
427 missing), optional C<paths> (relative paths inside the snapshot; default the
428 whole tree), C<dry_run>.
429  
430 Existing destinations are replaced: this is a rollback, not a merge.
431  
432 Returns: C<{ date, from, to, files, bytes, paths }>.
433  
434 Side Effects: writes under C<to> unless C<dry_run>.
435  
436 Usage:
437  
438 App::FileSync::Snapshot::restore(root => $root, date => $date, to => $root, paths => [ 'notes' ]);
439  
440 =head3 EXAMPLE
441  
442 my $done = App::FileSync::Snapshot::restore(
443 root => '/data/replica', date => '2026-10-22', to => '/tmp/export',
444 );
445 print "$done->{files} files restored\n";
446  
447 =head3 API SPECIFICATION
448  
449 =head4 INPUT
450  
451 {
452 root => { type => 'string', min => 1 },
453 date => { type => 'string', optional => 1 },
454 to => { type => 'string', optional => 1 },
455 paths => { type => 'arrayref', optional => 1 },
456 dry_run => { type => 'boolean', optional => 1 },
457 }
458  
459 =head4 OUTPUT
460  
461 { type => 'hashref' }
462  
463 =head3 MESSAGES
464  
465 Key Meaning Resolution
466 snapshot.need_date no date was given pass --date
467 snapshot.bad_date the date is not YYYY-MM-DD fix it
468 snapshot.none no snapshot for that date run "filesync snapshot list"
469 snapshot.need_to no destination was given pass --to
470 snapshot.to_not_dir the destination is not a directory choose another
471 snapshot.unsafe a path fails validate_relpath fix the path
472 snapshot.no_path the snapshot does not hold that path check the spelling
473 snapshot.not_regular a special file is in the snapshot restore by hand
474 snapshot.cannot_stat a snapshot entry vanished retry
475 snapshot.replace the destination cannot be replaced check permissions
476  
477 =head3 FORMAL SPECIFICATION
478  
479 ΔFS
480 pre date ∈ dom snapshots ∧ ∀ p : paths • p ∈ SafePath ∧ p ∈ dom tree(snapshot)
481 ¬dry_run ⇒ ∀ p : paths • tree'(to / p) = tree(snapshot / p)
482  
483 =head3 PSEUDOCODE
484  
485 check the date and that the snapshot exists
486 create the destination
487 paths := given paths, or every top-level entry of the snapshot
488 for each path: validate it, then copy it out recursively, replacing what is there
489  
490 =cut
491  
492 4 ▶sub restore {
Subroutine restore: called CC=15 SCAR=29.6
Pod documented
493 4 my $args = named(\@_, {
494 %ROOT,
495 date => { type => 'string', optional => 1 },
496 to => { type => 'string', optional => 1 },
497 paths => { type => 'arrayref', optional => 1 },
498 dry_run => { type => 'boolean', optional => 1 },
499 }, 'Snapshot::restore');
500  
501 4 my ($root, $date, $to) = @{$args}{qw(root date to)};
502 4 ▶ throw('snapshot.need_date') unless defined $date && length $date;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $date and length $date 0 4 4
Condition33%1/3
defined $date and length $date
!ll&&!rl&&r
004
MC/DC0%0/2
defined $date and length $date
defined $date length $date
Truth table33%1/3
A and B
A= defined $dateB= length $date
ABresult
0X0
100
111
503 4 ▶ throw('snapshot.bad_date', { date => $date }) unless is_date($date);
Branch: 1 branch
BranchTrueFalseTotal
unless is_date($date) 0 4 4
504  
505 4 my $snapshot = File::Spec->catdir(snapshot_root($root), $date);
506 4 ▶ throw('snapshot.none', { date => $date, path => snapshot_root($root) }) unless -d $snapshot;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $snapshot 0 4 4
507  
508 4 ▶ throw('snapshot.need_to') unless defined $to && length $to;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $to and length $to 0 4 4
Condition33%1/3
defined $to and length $to
!ll&&!rl&&r
004
MC/DC0%0/2
defined $to and length $to
defined $to length $to
Truth table33%1/3
A and B
A= defined $toB= length $to
ABresult
0X0
100
111
509 4 ensure_dir($to);
510 4 ▶ throw('snapshot.to_not_dir', { path => $to }) unless -d $to;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $to 0 4 4
511  
512 4 ▶ my @paths = @{ $args->{paths} || [] };
Condition100%2/2
$args->{'paths'} || []
l!l
31
MC/DC100%1/1
$args->{'paths'} || []
$args->{'paths'}
Truth table100%2/2
A
A= $args->{'paths'}
Aresult
11
00
513 4 ▶ @paths = @{ list_dir($snapshot) || [] } unless @paths;
Branch: 1 branch
BranchTrueFalseTotal
unless @paths 1 3 4
Condition50%1/2
list_dir($snapshot) || []
l!l
10
MC/DC0%0/1
list_dir($snapshot) || []
list_dir($snapshot)
Truth table50%1/2
A
A= list_dir($snapshot)
Aresult
11
00
514  
515 4 my $counts = { files => 0, bytes => 0 };
516 4 for my $rel (@paths) {
517 6 my ($safe, $reason) = validate_relpath($rel);
518 6 ▶ throw('snapshot.unsafe', { path => $rel, reason => $reason }) unless $safe;
Branch: 1 branch
BranchTrueFalseTotal
unless $safe 0 6 6
519  
520 6 my $from = File::Spec->catfile($snapshot, split m{/}, $rel);
521 6 ▶ throw('snapshot.no_path', { date => $date, path => $rel }) unless -e $from || -l $from;
Branch: 1 branch
BranchTrueFalseTotal
unless -e $from or -l $from 0 6 6
Condition33%1/3
-e $from or -l $from
l!l&&r!l&&!r
600
MC/DC0%0/2
-e $from or -l $from
-e $from -l $from
Truth table33%1/3
A or B
A= -e $fromB= -l $from
ABresult
1X1
011
000
522  
523 6 _copy_out($from, File::Spec->catfile($to, split m{/}, $rel), $counts, $args->{dry_run});
524 }
525  
526 4 return { date => $date, from => $snapshot, to => $to, %{$counts}, paths => \@paths };
527 }
528  
529 # _mirror
530 # Purpose: recreate a tree inside a snapshot, linking or copying files.
531 # Entry: $dst exists; $at_root is true for the replica root itself,
532 # where the reserved names live.
533 # Exit: returns 1.
534 # Side effects: creates directories and files under $dst; updates $counts.
535 # Symlinks and special files are not captured, as they are
536 # not synced either.
537 24 ▶sub _mirror :Private {
Subroutine _mirror: called CC=14 SCAR=26.6
538 24 my ($src, $dst, $mode, $counts, $at_root) = @_;
539  
540 24 ▶ my $names = list_dir($src) or throw('snapshot.read', { path => $src, error => os_error() });
Branch: 1 branch
BranchTrueFalseTotal
my $names = list_dir($src) or throw("snapshot.read", {"path", $src, "error", os_error()}) 24 0 24
541  
542 24 for my $name (@{$names}) {
543 # The snapshots, the root marker and temporaries are bookkeeping, not
544 # content; anything else, even a name starting ".filesync-", is data.
545 52 ▶ next if $name eq $SNAPSHOT_DIR || $name =~ $TEMP_FILE || ($at_root && $name eq $ROOT_MARKER);
Branch: 1 branch
BranchTrueFalseTotal
if $name eq $App::FileSync::Snapshot::SNAPSHOT_DIR or $name =~ /$TEMP_FILE/ or $at_root and $name eq $App::FileSync::Snapshot::ROOT_MARKER 22 30 52
Condition88%8/9
$name eq $App::FileSync::Snapshot::SNAPSHOT_DIR or $name =~ /$TEMP_FILE/ or $at_root and $name eq $App::FileSync::Snapshot::ROOT_MARKER
l!l&&r!l&&!r
13930
$name eq $App::FileSync::Snapshot::SNAPSHOT_DIR or $name =~ /$TEMP_FILE/
l!l&&r!l&&!r
13039
$at_root and $name eq $App::FileSync::Snapshot::ROOT_MARKER
!ll&&!rl&&r
6249
MC/DC75%3/4
$name eq $App::FileSync::Snapshot::SNAPSHOT_DIR or $name =~ /$TEMP_FILE/ or $at_root and $name eq $App::FileSync::Snapshot::ROOT_MARKER
$name eq $App::FileSync::Snapshot::SNAPSHOT_DIR $name =~ /$TEMP_FILE/ $at_root $name eq $App::FileSync::Snapshot::ROOT_MARKER
Truth table80%4/5
A or B or C and D
A= $name eq $App::FileSync::Snapshot::SNAPSHOT_DIRB= $name =~ /$TEMP_FILE/C= $at_rootD= $name eq $App::FileSync::Snapshot::ROOT_MARKER
ABCDresult
1XXX1
01XX1
00111
000X0
00100
546  
547 30 my $from = File::Spec->catfile($src, $name);
548 30 my $to = File::Spec->catfile($dst, $name);
549 30 ▶ my @stat = Time::HiRes::lstat($from) or next;
Branch: 1 branch
BranchTrueFalseTotal
my(@stat) = &Time::HiRes::lstat($from) or next 30 0 30
550  
551 30 ▶ if (-d _) {
Branch: 2 branches
BranchTrueFalseTotal
if (-d _) { } 11 19 30
elsif (-f _) { } 19 0 19
552 11 ensure_dir($to);
553 11 _mirror($from, $to, $mode, $counts, 0);
554 11 ▶ chmod($stat[$STAT_MODE] & $MODE_MASK, $to) if $HAS_MODES;
Branch: 1 branch
BranchTrueFalseTotal
if $HAS_MODES 11 0 11
555 } elsif (-f _) {
556 # A link shares the inode, so mode and mtime are already right;
557 # a copy (or a failed link across filesystems) needs them set.
558 328 ▶ my $linked = $mode eq $HARDLINK && do { no autodie qw(link); link($from, $to) };
Subroutine BEGIN: called CC=1 SCAR=0.0
Condition66%2/3
$mode eq $HARDLINK && do { BEGIN { $^H{'autodie::Scope::GuardStack/guard32'} = 'autodie::Scope::Guard=CODE(0x6506cbefa6e0)'; $^H{'no Fatal'} = 'HASH(0x6506cbefa680)'; } link $from, $to }
!ll&&!rl&&r
2017
MC/DC50%1/2
$mode eq $HARDLINK && do { BEGIN { $^H{'autodie::Scope::GuardStack/guard32'} = 'autodie::Scope::Guard=CODE(0x6506cbefa6e0)'; $^H{'no Fatal'} = 'HASH(0x6506cbefa680)'; } link $from, $to }
$mode eq $HARDLINK do { BEGIN { $^H{'autodie::Scope::GuardStack/guard32'} = 'autodie::Scope::Guard=CODE(0x6506cbefa6e0)'; $^H{'no Fatal'} = 'HASH(0x6506cbefa680)'; } link $from, $to }
Truth table66%2/3
A && B
A= $mode eq $HARDLINKB= do { BEGIN { $^H{'autodie::Scope::GuardStack/guard32'} = 'autodie::Scope::Guard=CODE(0x6506cbefa6e0)'; $^H{'no Fatal'} = 'HASH(0x6506cbefa680)'; } link $from, $to }
ABresult
0X0
100
111
559 19 ▶ copy_preserving($from, $to, \@stat) unless $linked;
Branch: 1 branch
BranchTrueFalseTotal
unless $linked 2 17 19
560 19 ▶ $counts->{ $linked ? 'linked' : 'copied' }++;
Branch: 1 branch
BranchTrueFalseTotal
$linked ? : 17 2 19
561 19 $counts->{files}++;
562 19 $counts->{bytes} += $stat[$STAT_SIZE];
563 }
564 }
565  
566 24 return 1;
567 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
568  
569 # _clean_stale_temps
570 # Purpose: remove snapshot attempts that died part way.
571 # Entry: $dir is the snapshot directory.
572 # Exit: returns 1.
573 # Side effects: removes .tmp-PID-N directories older than an hour; younger
574 # ones may belong to a concurrent run.
575 13 ▶sub _clean_stale_temps :Private {
Subroutine _clean_stale_temps: called CC=6 SCAR=28.1
576 13 my ($dir) = @_;
577  
578 13 my $now = time;
579 13 ▶ for my $name (grep { $_ =~ $TEMP_DIR } @{ list_dir($dir) || [] }) {
Condition50%1/2
list_dir($dir) || []
l!l
130
MC/DC0%0/1
list_dir($dir) || []
list_dir($dir)
Truth table50%1/2
A
A= list_dir($dir)
Aresult
11
00
580 0 my $path = File::Spec->catdir($dir, $name);
581 0 my @stat = Time::HiRes::lstat($path);
582 0 ▶ next unless @stat && -d _ && $now - $stat[$STAT_MTIME] >= $STALE_TEMP_SECONDS;
Branch: 1 branch
BranchTrueFalseTotal
unless @stat and -d _ and $now - $stat[$App::FileSync::Snapshot::STAT_MTIME] >= $App::FileSync::Snapshot::STALE_TEMP_SECONDS 0 0 0
Condition0%0/6
@stat and -d _ and $now - $stat[$App::FileSync::Snapshot::STAT_MTIME] >= $App::FileSync::Snapshot::STALE_TEMP_SECONDS
!ll&&!rl&&r
000
@stat and -d _
!ll&&!rl&&r
000
MC/DC0%0/3
@stat and -d _ and $now - $stat[$App::FileSync::Snapshot::STAT_MTIME] >= $App::FileSync::Snapshot::STALE_TEMP_SECONDS
@stat -d _ $now - $stat[$App::FileSync::Snapshot::STAT_MTIME] >= $App::FileSync::Snapshot::STALE_TEMP_SECONDS
Truth table0%0/4
A and B and C
A= @statB= -d _C= $now - $stat[$App::FileSync::Snapshot::STAT_MTIME] >= $App::FileSync::Snapshot::STALE_TEMP_SECONDS
ABCresult
0XX0
10X0
1100
1111
583 0 eval { remove_tree($path) };
584 }
585  
586 13 return 1;
587 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
588  
589 # _count
590 # Purpose: count the regular files and bytes in a snapshot.
591 # Entry: $dir exists.
592 # Exit: returns 1.
593 # Side effects: adds to $counts->{files} and {bytes}.
594 35 ▶sub _count :Private {
Subroutine _count: called CC=6 SCAR=18.2
595 35 my ($dir, $counts) = @_;
596  
597 35 ▶ for my $name (@{ list_dir($dir) || [] }) {
Condition50%1/2
list_dir($dir) || []
l!l
350
MC/DC0%0/1
list_dir($dir) || []
list_dir($dir)
Truth table50%1/2
A
A= list_dir($dir)
Aresult
11
00
598 45 my $path = File::Spec->catfile($dir, $name);
599 45 ▶ my @stat = Time::HiRes::lstat($path) or next;
Branch: 1 branch
BranchTrueFalseTotal
my(@stat) = &Time::HiRes::lstat($path) or next 45 0 45
600 45 ▶ if (-d _) {
Branch: 2 branches
BranchTrueFalseTotal
if (-d _) { } 18 27 45
elsif (-f _) { } 27 0 27
601 18 _count($path, $counts);
602 } elsif (-f _) {
603 27 $counts->{files}++;
604 27 $counts->{bytes} += $stat[$STAT_SIZE];
605 }
606 }
607  
608 35 return 1;
609 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
610  
611 # _remove_snapshot
612 # Purpose: delete one snapshot directory.
613 # Entry: $path is a dated snapshot.
614 # Exit: returns 1.
615 # Side effects: removes the tree; raises snapshot.remove with the first
616 # reason File::Path gave.
617 2 ▶sub _remove_snapshot :Private {
Subroutine _remove_snapshot: called CC=4 SCAR=22.2
618 2 my ($path) = @_;
619  
620 2 remove_tree($path, { error => \my $errors });
621 2 ▶ if (-e $path) {
Branch: 1 branch
BranchTrueFalseTotal
if (-e $path) 0 2 2
622 0 ▶ my ($first) = map { my ($f, $why) = %{$_}; "$f: $why" } @{ $errors || [] };
Condition0%0/2
$errors || []
l!l
00
MC/DC0%0/1
$errors || []
$errors
Truth table0%0/2
A
A= $errors
Aresult
11
00
623 0 ▶ throw('snapshot.remove', { path => $path, error => defined $first ? $first : os_error() });
Branch: 1 branch
BranchTrueFalseTotal
defined $first ? : 0 0 0
624 }
625  
626 2 return 1;
627 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
628  
629 # _copy_out
630 # Purpose: copy a snapshot entry to its destination, replacing it.
631 # Entry: $src exists in the snapshot.
632 # Exit: returns 1.
633 # Side effects: replaces $dst (unless $dry_run); updates $counts.
634 7 ▶sub _copy_out :Private {
Subroutine _copy_out: called CC=16 SCAR=31.4
635 7 my ($src, $dst, $counts, $dry_run) = @_;
636  
637 7 my @stat = Time::HiRes::lstat($src);
638 7 ▶ throw('snapshot.cannot_stat', { path => $src, error => os_error() }) unless @stat;
Branch: 1 branch
BranchTrueFalseTotal
unless @stat 0 7 7
639  
640 7 ▶ if (-d _) {
Branch: 1 branch
BranchTrueFalseTotal
if (-d _) 2 5 7
641 2 ▶ ensure_dir($dst) unless $dry_run;
Branch: 1 branch
BranchTrueFalseTotal
unless $dry_run 2 0 2
642 _copy_out(File::Spec->catfile($src, $_), File::Spec->catfile($dst, $_), $counts, $dry_run)
643 2 ▶ for @{ list_dir($src) || [] };
Condition50%1/2
list_dir($src) || []
l!l
20
MC/DC0%0/1
list_dir($src) || []
list_dir($src)
Truth table50%1/2
A
A= list_dir($src)
Aresult
11
00
644  
645 # Directory metadata last: filling it changed its mtime.
646 2 ▶ unless ($dry_run) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($dry_run) 2 0 2
647 2 ▶ chmod($stat[$STAT_MODE] & $MODE_MASK, $dst) if $HAS_MODES;
Branch: 1 branch
BranchTrueFalseTotal
if $HAS_MODES 2 0 2
648 2 utime($stat[$STAT_MTIME], $stat[$STAT_MTIME], $dst);
649 }
650 2 return 1;
651 }
652  
653 5 ▶ throw('snapshot.not_regular', { path => $src }) unless -f _;
Branch: 1 branch
BranchTrueFalseTotal
unless -f _ 0 5 5
654 5 $counts->{files}++;
655 5 $counts->{bytes} += $stat[$STAT_SIZE];
656 5 ▶ return 1 if $dry_run;
Branch: 1 branch
BranchTrueFalseTotal
if $dry_run 0 5 5
657  
658 # A rollback replaces whatever is in the way, even a directory.
659 5 ▶ if (-d $dst && !-l $dst) {
Branch: 2 branches
BranchTrueFalseTotal
if (-d $dst and not -l $dst) { } 0 5 5
elsif (-e $dst or -l $dst) { } 2 3 5
Condition33%1/3
-d $dst and not -l $dst
!ll&&!rl&&r
500
MC/DC0%0/2
-d $dst and not -l $dst
-d $dst not -l $dst
Truth table33%1/3
A and not(B)
A= -d $dstB= not -l $dst
ABresult
0X0
100
111
660 0 remove_tree($dst);
661 0 ▶ throw('snapshot.replace', { path => $dst }) if -e $dst;
Branch: 1 branch
BranchTrueFalseTotal
if -e $dst 0 0 0
662 ▶ } elsif (-e $dst || -l $dst) {
Condition66%2/3
-e $dst or -l $dst
l!l&&r!l&&!r
203
MC/DC50%1/2
-e $dst or -l $dst
-e $dst -l $dst
Truth table66%2/3
A or B
A= -e $dstB= -l $dst
ABresult
1X1
011
000
663 2 ▶ eval { unlink $dst; 1 } or throw('snapshot.replace', { path => $dst });
Branch: 1 branch
BranchTrueFalseTotal
eval { do { &App::FileSync::Snapshot::unlink($dst); 1 } } or throw("snapshot.replace", {"path", $dst}) 2 0 2
664 }
665  
666 5 copy_preserving($src, $dst, \@stat);
667 5 return 1;
668 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
669  
670 328 1;
671  
672 __END__
« blib/lib/App/FileSync/Merge.pm ↑ Summary blib/lib/App/FileSync/Verify.pm »