blib/lib/App/FileSync/Store.pm

filter: Statementstmt 97.5% 160 / 164 Branchbran 64.2% 18 / 28 Conditioncond 47.3% 9 / 19 MC/DCmcdc 8.3% 1 / 12 Subroutinesub 96.2% 51 / 53 Podpod 100% 25 / 25 totaltotal 87.7% 264 / 301 CC 23 SCAR 8.0
CC
23
Cov
89%
_load_entries
5.4
_assert_no_symlinked_parent
5.0
move_to_trash
4.8
CRAP 2.2
« blib/lib/App/FileSync/Config.pm ↑ Summary blib/lib/App/FileSync/Lock.pm »
1 package App::FileSync::Store;
2  
3 # The server's view of one repo: the master tree, its index (master.json), the
4 # per-client bases, the trash, the journal and the session lock, all under
5 # ROOT/master/REPO and ROOT/.filesync/repos/REPO.
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::Basename qw(dirname);
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  
19 328 ▶use parent -norequire, 'App::FileSync::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
20 328 ▶use App::FileSync::Base;
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 328 ▶use App::FileSync qw(json_encode json_decode read_text write_atomic validate_relpath validate_client_id validate_repo_name);
Subroutine BEGIN: called CC=1 SCAR=0.0
23 328 ▶use App::FileSync::Args qw(named);
Subroutine BEGIN: called CC=1 SCAR=0.0
24 328 ▶use App::FileSync::Config;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 328 ▶use App::FileSync::Constants qw($STALE_TEMP_SECONDS $TRASH_DAYS);
Subroutine BEGIN: called CC=1 SCAR=0.0
26 328 ▶use App::FileSync::I18N qw(strip_location throw);
Subroutine BEGIN: called CC=1 SCAR=0.0
27 328 ▶use App::FileSync::IO qw(append_line ensure_dir install_file);
Subroutine BEGIN: called CC=1 SCAR=0.0
28 328 ▶use App::FileSync::Ignore;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 328 ▶use App::FileSync::Lock;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 328 ▶use App::FileSync::Scan;
Subroutine BEGIN: called CC=1 SCAR=0.0
31 328 ▶use App::FileSync::Trash;
Subroutine BEGIN: called CC=1 SCAR=0.0
32  
33 328 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
34  
35 # A month's journal file name: 2026-11.jsonl.
36 328 Readonly::Scalar my $JOURNAL_NAME => '%Y-%m.jsonl';
37  
38 =encoding utf8
39  
40 =head1 NAME
41  
42 App::FileSync::Store - the server-side files of one repo
43  
44 =head1 SYNOPSIS
45  
46 my $store = App::FileSync::Store->new(root => '/srv/filesync', repo => 'docs');
47 my $lock = $store->acquire_lock() or die 'busy';
48 my $index = $store->load_index();
49 my $scan = $store->walk_master($index);
50 $store->save_index($scan->{manifest});
51  
52 =head1 METHODS
53  
54 =head2 new
55  
56 Purpose: open a repo on the server.
57  
58 Args: C<root>, C<repo>, optional C<config> (the repo config, read from disk
59 when omitted) and C<language>.
60  
61 Returns: the store.
62  
63 Side Effects: reads the repo config.
64  
65 Usage:
66  
67 my $store = App::FileSync::Store->new(root => $root, repo => $repo);
68  
69 =head3 EXAMPLE
70  
71 my $store = App::FileSync::Store->new(root => '/srv/filesync', repo => 'docs');
72 print $store->master_dir, "\n";
73  
74 =head3 API SPECIFICATION
75  
76 =head4 INPUT
77  
78 {
79 root => { type => 'string', min => 1 },
80 repo => { type => 'string', min => 1 },
81 config => { type => 'hashref', optional => 1 },
82 language => { type => 'string', optional => 1 },
83 }
84  
85 =head4 OUTPUT
86  
87 { type => 'object', isa => 'App::FileSync::Store' }
88  
89 =head3 MESSAGES
90  
91 Key Meaning Resolution
92 args.invalid root or repo missing pass both
93 store.bad_repo the repo name is not an id use letters, digits, '.', '_', '-'
94 config.no_repo the repo does not exist filesync-admin repo create
95  
96 =head3 FORMAL SPECIFICATION
97  
98 new(r, n, c) = ⟨root ↦ r, repo ↦ n, config ↦ c or load_repo(r, n), ignore ↦ Ignore(config.ignore)⟩
99  
100 =cut
101  
102 395 ▶sub new {
Subroutine new: called CC=3 SCAR=11.0
Pod documented
103 395 my $class = shift;
104 395 my $args = named(\@_, {
105 root => { type => 'string', min => 1 },
106 repo => { type => 'string', min => 1 },
107 config => { type => 'hashref', optional => 1 },
108 language => { type => 'string', optional => 1 },
109 }, 'Store->new');
110  
111 # The name becomes a directory under the root, so it must be a plain id
112 # before any path is built from it.
113 395 my ($ok, $reason) = validate_repo_name($args->{repo});
114 395 ▶ throw('store.bad_repo', { reason => $reason }) unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 1 394 395
115  
116 394 ▶ my $config = $args->{config} || App::FileSync::Config::load_repo($args->{root}, $args->{repo});
Condition66%2/3
$args->{'config'} || App::FileSync::Config::load_repo($args->{'root'}, $args->{'repo'})
l!l&&r!l&&!r
813130
MC/DC0%0/2
$args->{'config'} || App::FileSync::Config::load_repo($args->{'root'}, $args->{'repo'})
$args->{'config'} App::FileSync::Config::load_repo($args->{'root'}, $args->{'repo'})
Truth table66%2/3
A || B
A= $args->{'config'}B= App::FileSync::Config::load_repo($args->{'root'}, $args->{'repo'})
ABresult
1X1
011
000
117  
118 return bless {
119 root => $args->{root},
120 repo => $args->{repo},
121 language => $args->{language},
122 config => $config,
123 394 ignore => App::FileSync::Ignore->new(patterns => $config->{ignore}),
124 }, $class;
125 }
126  
127 =head2 root
128  
129 Documented with L</journal_path> below.
130  
131 =head2 repo
132  
133 Documented with L</journal_path> below.
134  
135 =head2 config
136  
137 Documented with L</journal_path> below.
138  
139 =head2 master_dir
140  
141 Documented with L</journal_path> below.
142  
143 =head2 meta_dir
144  
145 Documented with L</journal_path> below.
146  
147 =head2 index_path
148  
149 Documented with L</journal_path> below.
150  
151 =head2 trash_dir
152  
153 Documented with L</journal_path> below.
154  
155 =head2 lock_path
156  
157 Documented with L</journal_path> below.
158  
159 =head2 journal_path
160  
161 Purpose: where the repo's pieces live.
162  
163 Args: none.
164  
165 Returns: the server root, the repo name, the config hashref, and the paths of
166 the master tree (F<ROOT/master/REPO>), the metadata directory, the index
167 (F<master.json>), the trash, the lock file and this month's journal
168 (F<journal/YYYY-MM.jsonl>, UTC).
169  
170 Side Effects: none.
171  
172 Usage:
173  
174 my $master = $store->master_dir;
175  
176 =head3 EXAMPLE
177  
178 print join("\n", $store->master_dir, $store->index_path, $store->journal_path), "\n";
179  
180 =head3 API SPECIFICATION
181  
182 =head4 INPUT
183  
184 [ { name => 'self', type => 'object' } ]
185  
186 =head4 OUTPUT
187  
188 { type => 'string' }
189  
190 =head3 MESSAGES
191  
192 None.
193  
194 =head3 FORMAL SPECIFICATION
195  
196 master_dir = root / "master" / repo
197 meta_dir = root / ".filesync" / "repos" / repo
198 index_path = meta_dir / "master.json"
199 journal_path = meta_dir / "journal" / yyyy-mm(now) ⁀ ".jsonl"
200  
201 =cut
202  
203 0 ▶sub root {
Subroutine root: not called CC=1 SCAR=6.9
Pod documented
204 0 my ($self) = @_;
205  
206 0 return $self->{root};
207 }
208  
209 0 ▶sub repo {
Subroutine repo: not called CC=1 SCAR=6.9
Pod documented
210 0 my ($self) = @_;
211  
212 0 return $self->{repo};
213 }
214  
215 541 ▶sub config {
Subroutine config: called CC=1 SCAR=0.0
Pod documented
216 541 my ($self) = @_;
217  
218 541 return $self->{config};
219 }
220  
221 1737 ▶sub master_dir {
Subroutine master_dir: called CC=1 SCAR=0.0
Pod documented
222 1737 my ($self) = @_;
223  
224 1737 return File::Spec->catdir($self->{root}, 'master', $self->{repo});
225 }
226  
227 1788 ▶sub meta_dir {
Subroutine meta_dir: called CC=1 SCAR=0.0
Pod documented
228 1788 my ($self) = @_;
229  
230 1788 return App::FileSync::Config::repo_meta_dir($self->{root}, $self->{repo});
231 }
232  
233 434 ▶sub index_path {
Subroutine index_path: called CC=1 SCAR=0.0
Pod documented
234 434 my ($self) = @_;
235  
236 434 return File::Spec->catfile($self->meta_dir(), 'master.json');
237 }
238  
239 197 ▶sub trash_dir {
Subroutine trash_dir: called CC=1 SCAR=0.0
Pod documented
240 197 my ($self) = @_;
241  
242 197 return File::Spec->catdir($self->meta_dir(), 'trash');
243 }
244  
245 188 ▶sub lock_path {
Subroutine lock_path: called CC=1 SCAR=0.0
Pod documented
246 188 my ($self) = @_;
247  
248 188 return File::Spec->catfile($self->meta_dir(), 'locks', 'repo.lock');
249 }
250  
251 557 ▶sub journal_path {
Subroutine journal_path: called CC=1 SCAR=0.0
Pod documented
252 557 my ($self) = @_;
253  
254 # One journal file per UTC month, so old months can be archived whole.
255 557 return File::Spec->catfile($self->meta_dir(), 'journal', strftime($JOURNAL_NAME, gmtime()));
256 }
257  
258 =head2 base_path
259  
260 Purpose: where a client's base (its state at its last sync) is stored.
261  
262 Args: C<$client>, a client id.
263  
264 Returns: F<META/clients/CLIENT.json>.
265  
266 Side Effects: none.
267  
268 Usage:
269  
270 my $path = $store->base_path('laptop-1');
271  
272 =head3 EXAMPLE
273  
274 unlink $store->base_path($client) if $forget;
275  
276 =head3 API SPECIFICATION
277  
278 =head4 INPUT
279  
280 [
281 { name => 'self', type => 'object' },
282 { name => 'client', type => 'string', min => 1 },
283 ]
284  
285 =head4 OUTPUT
286  
287 { type => 'string', min => 1 }
288  
289 =head3 MESSAGES
290  
291 Key Meaning Resolution
292 store.bad_client the id is not a valid client id use letters, digits, . _ -
293  
294 =head3 FORMAL SPECIFICATION
295  
296 pre client ∈ Id
297 base_path(client) = meta_dir / "clients" / client ⁀ ".json"
298  
299 =cut
300  
301 325 ▶sub base_path {
Subroutine base_path: called CC=2 SCAR=6.9
Pod documented
302 325 my ($self, $client) = @_;
303  
304 # The id becomes a file name, so it must not be able to climb out of the
305 # clients directory.
306 325 my ($ok, $reason) = validate_client_id($client);
307 325 ▶ $self->_throw('store.bad_client', { reason => $reason }) unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 1 324 325
308  
309 324 return File::Spec->catfile($self->meta_dir(), 'clients', "$client.json");
310 }
311  
312 =head2 acquire_lock
313  
314 Purpose: take the repo's session lock without waiting.
315  
316 Args: none.
317  
318 Returns: the lock handle, or C<undef> when another session holds it.
319  
320 Side Effects: creates the lock file.
321  
322 Usage:
323  
324 my $lock = $store->acquire_lock() or return refuse('locked');
325  
326 =head3 EXAMPLE
327  
328 if (my $lock = $store->acquire_lock) { ... }
329  
330 =head3 API SPECIFICATION
331  
332 =head4 INPUT
333  
334 [ { name => 'self', type => 'object' } ]
335  
336 =head4 OUTPUT
337  
338 { type => 'handle', optional => 1 }
339  
340 =head3 MESSAGES
341  
342 Key Meaning Resolution
343 io.append the lock file cannot be made check permissions
344  
345 =head3 FORMAL SPECIFICATION
346  
347 acquire_lock = Lock::acquire(lock_path, nonblock)
348  
349 =cut
350  
351 184 ▶sub acquire_lock {
Subroutine acquire_lock: called CC=1 SCAR=0.0
Pod documented
352 184 my ($self) = @_;
353  
354 184 return App::FileSync::Lock::acquire(path => $self->lock_path(), nonblock => 1);
355 }
356  
357 =head2 abs_path
358  
359 Purpose: the absolute path in the master for a relative path.
360  
361 Args: C<$rel>.
362  
363 Returns: the path under L</master_dir>.
364  
365 Side Effects: none. Raises if C<$rel> is unsafe or if a directory on the way
366 is a symlink, so nothing can be written outside the master through one.
367  
368 Usage:
369  
370 my $abs = $store->abs_path($path);
371  
372 =head3 EXAMPLE
373  
374 my $abs = $store->abs_path('notes/plan.txt');
375  
376 =head3 API SPECIFICATION
377  
378 =head4 INPUT
379  
380 [
381 { name => 'self', type => 'object' },
382 { name => 'rel', type => 'string' },
383 ]
384  
385 =head4 OUTPUT
386  
387 { type => 'string', min => 1 }
388  
389 =head3 MESSAGES
390  
391 Key Meaning Resolution
392 path.unsafe the path fails validate_relpath rename the file
393 store.symlink a parent directory is a symlink remove the symlink
394  
395 =head3 FORMAL SPECIFICATION
396  
397 pre rel ∈ SafePath ∧ ∀ a : ancestors(master / rel) ∩ under(master) • kind a ≠ symlink
398 abs_path(rel) = master / rel
399  
400 =cut
401  
402 672 ▶sub abs_path {
Subroutine abs_path: called CC=2 SCAR=7.0
Pod documented
403 672 my ($self, $rel) = @_;
404  
405 672 my ($ok, $reason) = validate_relpath($rel);
406 672 ▶ $self->_throw('path.unsafe', { path => $rel, reason => $reason }) unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 0 672 672
407  
408 672 $self->_assert_no_symlinked_parent($rel);
409  
410 672 return File::Spec->catfile($self->master_dir(), split m{/}, $rel);
411 }
412  
413 =head2 load_index
414  
415 Documented with L</save_base> below.
416  
417 =head2 save_index
418  
419 Documented with L</save_base> below.
420  
421 =head2 load_base
422  
423 Documented with L</save_base> below.
424  
425 =head2 save_base
426  
427 Purpose: read and write the master's index and a client's base.
428  
429 Args: C<save_index(\%entries)>; C<load_base($client)>;
430 C<save_base($client, \%entries)>.
431  
432 Returns: the entries hashref (empty when the file does not exist); 1 for the
433 save methods.
434  
435 Side Effects: the save methods replace the file atomically.
436  
437 Usage:
438  
439 my $index = $store->load_index();
440 $store->save_base($client, $base_after);
441  
442 =head3 EXAMPLE
443  
444 my $base = $store->load_base('laptop-1');
445 print scalar(keys %{$base}), " paths known to laptop-1\n";
446  
447 =head3 API SPECIFICATION
448  
449 =head4 INPUT
450  
451 [
452 { name => 'self', type => 'object' },
453 { name => 'client', type => 'string', optional => 1 },
454 { name => 'entries', type => 'hashref', optional => 1 },
455 ]
456  
457 =head4 OUTPUT
458  
459 { type => 'hashref' }
460  
461 =head3 MESSAGES
462  
463 Key Meaning Resolution
464 config.parse the file is not valid JSON run filesync-admin reindex
465 io.write the file cannot be written check space
466  
467 =head3 FORMAL SPECIFICATION
468  
469 load(p) = json(FS(p)).entries if p ∈ dom FS ∧ is a hash, else ∅
470 save(p, e): FS'(p) = json(⟨version ↦ 1, entries ↦ e⟩) ⁀ "\n"
471  
472 =cut
473  
474 196 ▶sub load_index {
Subroutine load_index: called CC=1 SCAR=0.0
Pod documented
475 196 my ($self) = @_;
476  
477 196 return $self->_load_entries($self->index_path());
478 }
479  
480 232 ▶sub save_index {
Subroutine save_index: called CC=1 SCAR=0.0
Pod documented
481 232 my ($self, $entries) = @_;
482  
483 232 return $self->_save_entries($self->index_path(), $entries);
484 }
485  
486 174 ▶sub load_base {
Subroutine load_base: called CC=1 SCAR=0.0
Pod documented
487 174 my ($self, $client) = @_;
488  
489 174 return $self->_load_entries($self->base_path($client));
490 }
491  
492 147 ▶sub save_base {
Subroutine save_base: called CC=1 SCAR=0.0
Pod documented
493 147 my ($self, $client, $entries) = @_;
494  
495 147 return $self->_save_entries($self->base_path($client), $entries);
496 }
497  
498 =head2 walk_master
499  
500 Purpose: scan the master, reusing indexed hashes where size and mtime match.
501  
502 Args: optional C<\%cache> (usually the current index; C<{}> forces a rehash).
503  
504 Returns: the L<App::FileSync::Scan/scan> result: C<{ manifest, stats, skipped }>.
505  
506 Side Effects: reads the master tree.
507  
508 Usage:
509  
510 my $scan = $store->walk_master($store->load_index);
511  
512 =head3 EXAMPLE
513  
514 my $fresh = $store->walk_master({});
515 printf "%d files\n", $fresh->{stats}{files};
516  
517 =head3 API SPECIFICATION
518  
519 =head4 INPUT
520  
521 [
522 { name => 'self', type => 'object' },
523 { name => 'cache', type => 'hashref', optional => 1 },
524 ]
525  
526 =head4 OUTPUT
527  
528 { type => 'hashref' }
529  
530 =head3 MESSAGES
531  
532 Key Meaning Resolution
533 store.no_master the master directory is gone restore it or recreate the repo
534  
535 =head3 FORMAL SPECIFICATION
536  
537 pre isdir(master_dir)
538 walk_master(c) = scan(master_dir, ignore, c)
539  
540 =cut
541  
542 181 ▶sub walk_master {
Subroutine walk_master: called CC=3 SCAR=11.4
Pod documented
543 181 my ($self, $cache) = @_;
544  
545 181 my $master = $self->master_dir();
546 181 ▶ $self->_throw('store.no_master', { path => $master }) unless -d $master;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $master 0 181 181
547  
548 return App::FileSync::Scan::scan(
549 root => $master,
550 ignore => $self->{ignore},
551 181 ▶ cache => $cache || {},
Condition50%1/2
$cache || {}
l!l
1810
MC/DC0%0/1
$cache || {}
$cache
Truth table50%1/2
A
A= $cache
Aresult
11
00
552 );
553 }
554  
555 =head2 ensure_parent
556  
557 Purpose: create the directory a master path will be written into.
558  
559 Args: C<$rel>.
560  
561 Returns: the parent directory.
562  
563 Side Effects: creates missing directories.
564  
565 Usage:
566  
567 $store->ensure_parent($path);
568  
569 =head3 EXAMPLE
570  
571 $store->ensure_parent('new/deep/dir/file.txt');
572  
573 =head3 API SPECIFICATION
574  
575 =head4 INPUT
576  
577 [
578 { name => 'self', type => 'object' },
579 { name => 'rel', type => 'string', min => 1 },
580 ]
581  
582 =head4 OUTPUT
583  
584 { type => 'string', min => 1 }
585  
586 =head3 MESSAGES
587  
588 As for L</abs_path>, plus C<io.mkdir>.
589  
590 =head3 FORMAL SPECIFICATION
591  
592 isdir'(dirname(abs_path(rel)))
593  
594 =cut
595  
596 185 ▶sub ensure_parent {
Subroutine ensure_parent: called CC=1 SCAR=0.0
Pod documented
597 185 my ($self, $rel) = @_;
598  
599 185 return ensure_dir(dirname($self->abs_path($rel)));
600 }
601  
602 =head2 temp_file
603  
604 Purpose: an exclusive temporary file beside a master path.
605  
606 Args: C<$rel>, the path the temporary file will become.
607  
608 Returns: C<[ $filehandle, $path ]>.
609  
610 Side Effects: creates the file (and its directory).
611  
612 Usage:
613  
614 my ($fh, $temp) = @{ $store->temp_file($path) };
615  
616 =head3 EXAMPLE
617  
618 my ($fh, $temp) = @{ $store->temp_file('notes/plan.txt') };
619 print {$fh} $content;
620 close $fh;
621 $store->commit_temp('notes/plan.txt', $temp, time, oct(644));
622  
623 =head3 API SPECIFICATION
624  
625 =head4 INPUT
626  
627 [
628 { name => 'self', type => 'object' },
629 { name => 'rel', type => 'string', min => 1 },
630 ]
631  
632 =head4 OUTPUT
633  
634 { type => 'arrayref', min => 2, max => 2 }
635  
636 =head3 MESSAGES
637  
638 As for L</abs_path>, plus C<io.temp>.
639  
640 =head3 FORMAL SPECIFICATION
641  
642 temp_file(rel) = App::FileSync::IO::temp_file(dirname(abs_path(rel)))
643  
644 =cut
645  
646 179 ▶sub temp_file {
Subroutine temp_file: called CC=1 SCAR=0.0
Pod documented
647 179 my ($self, $rel) = @_;
648  
649 179 return App::FileSync::IO::temp_file(dirname($self->abs_path($rel)));
650 }
651  
652 =head2 commit_temp
653  
654 Purpose: move a verified temporary file into the master.
655  
656 Args: C<$rel>, C<$temp>, optional C<$mtime> and C<$mode>.
657  
658 Returns: the absolute path written.
659  
660 Side Effects: see L<App::FileSync::IO/install_file>.
661  
662 Usage:
663  
664 $store->commit_temp($path, $temp, $mtime, $mode);
665  
666 =head3 EXAMPLE
667  
668 $store->commit_temp('a.txt', $temp, 1_700_000_000, oct(600));
669  
670 =head3 API SPECIFICATION
671  
672 =head4 INPUT
673  
674 [
675 { name => 'self', type => 'object' },
676 { name => 'rel', type => 'string', min => 1 },
677 { name => 'temp', type => 'string', min => 1 },
678 { name => 'mtime', type => 'number', optional => 1 },
679 { name => 'mode', type => 'integer', optional => 1 },
680 ]
681  
682 =head4 OUTPUT
683  
684 { type => 'string', min => 1 }
685  
686 =head3 MESSAGES
687  
688 As for L<App::FileSync::IO/install_file> and L</abs_path>.
689  
690 =head3 FORMAL SPECIFICATION
691  
692 commit_temp(rel, t, m, mode) = install_file(t, abs_path(rel), m, mode)
693  
694 =cut
695  
696 176 ▶sub commit_temp {
Subroutine commit_temp: called CC=1 SCAR=0.0
Pod documented
697 176 my ($self, $rel, $temp, $mtime, $mode) = @_;
698  
699 176 return install_file($temp, $self->abs_path($rel), $mtime, $mode);
700 }
701  
702 =head2 move_to_trash
703  
704 Purpose: move a master path into the repo's trash.
705  
706 Args: C<$rel>, optional C<$epoch>.
707  
708 Returns: where it went, or C<undef> if it was not there.
709  
710 Side Effects: see L<App::FileSync::Trash/move_to_trash>.
711  
712 Usage:
713  
714 my $trashed = $store->move_to_trash($path, time);
715  
716 =head3 EXAMPLE
717  
718 my $where = $store->move_to_trash('old/report.txt');
719  
720 =head3 API SPECIFICATION
721  
722 =head4 INPUT
723  
724 [
725 { name => 'self', type => 'object' },
726 { name => 'rel', type => 'string', min => 1 },
727 { name => 'epoch', type => 'number', optional => 1 },
728 ]
729  
730 =head4 OUTPUT
731  
732 { type => 'string', optional => 1 }
733  
734 =head3 MESSAGES
735  
736 As for L<App::FileSync::Trash/move_to_trash> and L</abs_path>.
737  
738 =head3 FORMAL SPECIFICATION
739  
740 abs_path(rel) ∉ dom FS ⇒ result = ⊥
741 abs_path(rel) ∈ dom FS ⇒ result = Trash::move_to_trash(abs_path(rel), rel, trash_dir, epoch)
742  
743 =cut
744  
745 17 ▶sub move_to_trash {
Subroutine move_to_trash: called CC=4 SCAR=15.6
Pod documented
746 17 my ($self, $rel, $epoch) = @_;
747  
748 17 my $abs = $self->abs_path($rel);
749 17 ▶ return undef unless -e $abs || -l $abs; ## no critic (Subroutines::ProhibitExplicitReturnUndef)
Branch: 1 branch
BranchTrueFalseTotal
unless -e $abs or -l $abs 0 17 17
Condition33%1/3
-e $abs or -l $abs
l!l&&r!l&&!r
1700
MC/DC0%0/2
-e $abs or -l $abs
-e $abs -l $abs
Truth table33%1/3
A or B
A= -e $absB= -l $abs
ABresult
1X1
011
000
750  
751 17 ▶ return App::FileSync::Trash::move_to_trash(
Branch: 1 branch
BranchTrueFalseTotal
defined $epoch ? : 17 0 17
752 src => $abs,
753 rel => $rel,
754 root => $self->trash_dir(),
755 epoch => defined $epoch ? $epoch : time,
756 );
757 }
758  
759 =head2 clean_stale_temps
760  
761 Documented with L</prune_trash> below.
762  
763 =head2 prune_trash
764  
765 Purpose: housekeeping at the start of a session.
766  
767 Args: C<clean_stale_temps(max_age =E<gt> SECONDS)>;
768 C<prune_trash(days =E<gt> N, dry_run =E<gt> BOOL)>. Defaults: one hour, and
769 the repo's C<trash_days> (30).
770  
771 Returns: the number of temporaries removed; the arrayref of trash buckets
772 removed.
773  
774 Side Effects: deletes stale temporaries from the master and expired trash.
775  
776 Usage:
777  
778 $store->clean_stale_temps();
779 $store->prune_trash();
780  
781 =head3 EXAMPLE
782  
783 my $pruned = $store->prune_trash(dry_run => 1);
784  
785 =head3 API SPECIFICATION
786  
787 =head4 INPUT
788  
789 {
790 max_age => { type => 'integer', min => 0, optional => 1 },
791 days => { type => 'number', optional => 1 },
792 dry_run => { type => 'boolean', optional => 1 },
793 }
794  
795 =head4 OUTPUT
796  
797 { type => 'scalar' }
798  
799 =head3 MESSAGES
800  
801 None.
802  
803 =head3 FORMAL SPECIFICATION
804  
805 clean_stale_temps = Scan::clean_stale_temps(master_dir, age)
806 prune_trash = Trash::prune(trash_dir, days)
807  
808 =cut
809  
810 174 ▶sub clean_stale_temps {
Subroutine clean_stale_temps: called CC=3 SCAR=11.4
Pod documented
811 174 my ($self, %args) = @_;
812  
813 174 my $master = $self->master_dir();
814 174 ▶ return 0 unless -d $master;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $master 0 174 174
815  
816 return App::FileSync::Scan::clean_stale_temps(
817 root => $master,
818 174 ▶ max_age => defined $args{max_age} ? $args{max_age} : $STALE_TEMP_SECONDS,
Branch: 1 branch
BranchTrueFalseTotal
defined $args{'max_age'} ? : 0 174 174
819 );
820 }
821  
822 166 ▶sub prune_trash {
Subroutine prune_trash: called CC=3 SCAR=13.1
Pod documented
823 166 my ($self, %args) = @_;
824  
825 return App::FileSync::Trash::prune(
826 root => $self->trash_dir(),
827 days => defined $args{days} ? $args{days} : ($self->{config}{trash_days} || $TRASH_DAYS),
828 dry_run => $args{dry_run},
829 166 ▶ );
Branch: 1 branch
BranchTrueFalseTotal
defined $args{'days'} ? : 0 166 166
Condition33%1/3
$self->{"config"}{"trash_days"} or $App::FileSync::Store::TRASH_DAYS
l!l&&r!l&&!r
16600
MC/DC0%0/2
$self->{"config"}{"trash_days"} or $App::FileSync::Store::TRASH_DAYS
$self->{"config"}{"trash_days"} $App::FileSync::Store::TRASH_DAYS
Truth table33%1/3
A or B
A= $self->{"config"}{"trash_days"}B= $App::FileSync::Store::TRASH_DAYS
ABresult
1X1
011
000
830 }
831  
832 =head2 journal
833  
834 Purpose: append an event to this month's journal.
835  
836 Args: C<\%event>; a C<ts> (now) is added.
837  
838 Returns: 1.
839  
840 Side Effects: appends one JSON line, creating the journal directory.
841  
842 Usage:
843  
844 $store->journal({ client => $id, action => 'push', path => $path, result => 'ok' });
845  
846 =head3 EXAMPLE
847  
848 $store->journal({ action => 'reindex', files => 10, result => 'ok' });
849  
850 =head3 API SPECIFICATION
851  
852 =head4 INPUT
853  
854 [
855 { name => 'self', type => 'object' },
856 { name => 'event', type => 'hashref' },
857 ]
858  
859 =head4 OUTPUT
860  
861 { type => 'integer', min => 1, max => 1 }
862  
863 =head3 MESSAGES
864  
865 Key Meaning Resolution
866 io.append the journal cannot be written check space
867  
868 =head3 FORMAL SPECIFICATION
869  
870 FS'(journal_path) = FS(journal_path) ⁀ json({ts ↦ now} ⊕ event) ⁀ "\n"
871  
872 =cut
873  
874 556 ▶sub journal {
Subroutine journal: called CC=1 SCAR=0.0
Pod documented
875 556 my ($self, $event) = @_;
876  
877 556 append_line($self->journal_path(), json_encode({ ts => time, %{$event} }));
878 556 return 1;
879 }
880  
881 # _assert_no_symlinked_parent
882 # Purpose: refuse to write through a symlinked directory in the master.
883 # Entry: $rel has passed validate_relpath.
884 # Exit: returns 1.
885 # Side effects: raises store.symlink. Stops at the first missing directory:
886 # nothing below it can be a symlink yet.
887 672 ▶sub _assert_no_symlinked_parent :Private {
Subroutine _assert_no_symlinked_parent: called CC=5 SCAR=16.2
888 672 my ($self, $rel) = @_;
889  
890 672 my @parts = split m{/}, $rel;
891 672 pop @parts;
892  
893 672 my $current = $self->master_dir();
894 672 for my $part (@parts) {
895 46 $current = File::Spec->catfile($current, $part);
896 46 ▶ last unless -e $current || -l $current;
Branch: 1 branch
BranchTrueFalseTotal
unless -e $current or -l $current 7 39 46
Condition66%2/3
-e $current or -l $current
l!l&&r!l&&!r
3907
MC/DC50%1/2
-e $current or -l $current
-e $current -l $current
Truth table66%2/3
A or B
A= -e $currentB= -l $current
ABresult
1X1
011
000
897 39 ▶ $self->_throw('store.symlink', { path => $current }) if -l $current;
Branch: 1 branch
BranchTrueFalseTotal
if -l $current 0 39 39
898 }
899  
900 672 return 1;
901 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
902  
903 # _load_entries
904 # Purpose: read an index or base file.
905 # Entry: $path may not exist.
906 # Exit: returns the entries hashref (empty for a missing file or one
907 # without an entries hash).
908 # Side effects: raises config.parse for a corrupt file.
909 370 ▶sub _load_entries :Private {
Subroutine _load_entries: called CC=5 SCAR=16.8
910 370 my ($self, $path) = @_;
911  
912 370 ▶ return {} unless -e $path;
Branch: 1 branch
BranchTrueFalseTotal
unless -e $path 80 290 370
913  
914 290 my $text = read_text($path);
915 290 my $document = eval { json_decode($text) };
916 290 ▶ $self->_throw('config.parse', { path => $path, error => strip_location($@) }) if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 290 290
917  
918 290 ▶ return (ref($document) eq 'HASH' && ref($document->{entries}) eq 'HASH') ? $document->{entries} : {};
Branch: 1 branch
BranchTrueFalseTotal
ref $document eq 'HASH' && ref $document->{'entries'} eq 'HASH' ? : 290 0 290
Condition33%1/3
ref $document eq "HASH" and ref $document->{"entries"} eq "HASH"
!ll&&!rl&&r
00290
MC/DC0%0/2
ref $document eq "HASH" and ref $document->{"entries"} eq "HASH"
ref $document eq "HASH" ref $document->{"entries"} eq "HASH"
Truth table33%1/3
A and B
A= ref $document eq "HASH"B= ref $document->{"entries"} eq "HASH"
ABresult
0X0
100
111
919 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
920  
921 # _save_entries
922 # Purpose: write an index or base file.
923 # Entry: $entries may be undef (written as empty).
924 # Exit: returns 1.
925 # Side effects: replaces $path atomically.
926 379 ▶sub _save_entries :Private {
Subroutine _save_entries: called CC=2 SCAR=7.1
927 379 my ($self, $path, $entries) = @_;
928  
929 379 ▶ write_atomic($path, json_encode({ version => 1, entries => $entries || {} }) . "\n");
Condition50%1/2
$entries || {}
l!l
3790
MC/DC0%0/1
$entries || {}
$entries
Truth table50%1/2
A
A= $entries
Aresult
11
00
930 379 return 1;
931 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
932  
933 328 1;
934  
935 __END__
« blib/lib/App/FileSync/Config.pm ↑ Summary blib/lib/App/FileSync/Lock.pm »