blib/lib/App/FileSync/Config.pm

filter: Statementstmt 97.2% 107 / 110 Branchbran 57.6% 15 / 26 Conditioncond 33.3% 3 / 9 MC/DCmcdc 16.6% 1 / 6 Subroutinesub 100% 31 / 31 Podpod 100% 10 / 10 totaltotal 86.9% 167 / 192 CC 17 SCAR 9.9
CC
17
Cov
86%
home_dir
9.3
load_client
4.1
load_repo
4.0
CRAP 2.7
« blib/lib/App/FileSync/Transport/Local.pm ↑ Summary blib/lib/App/FileSync/Store.pm »
1 package App::FileSync::Config;
2  
3 # Where configuration lives and what it holds: the client's repo list in
4 # ~/.filesync/config.json, and each repo's policy under the server root.
5  
6 328 ▶use App::FileSync::Platform;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 328 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 328 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 328 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 328 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 328 ▶use JSON::PP ();
Subroutine BEGIN: called CC=1 SCAR=0.0
14 328 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 328 ▶use App::FileSync qw(json_encode json_decode read_text write_atomic);
Subroutine BEGIN: called CC=1 SCAR=0.0
17 328 ▶use App::FileSync::Args qw(positional);
Subroutine BEGIN: called CC=1 SCAR=0.0
18 328 ▶use App::FileSync::Constants qw(
Subroutine BEGIN: called CC=1 SCAR=0.0
19 $ROOT_MARKER $TEMP_PREFIX $SNAPSHOT_DIR
20 $TRASH_DAYS $MAX_DELETES $MAX_DELETE_PERCENT
21 328 );
22 328 ▶use App::FileSync::I18N qw(throw strip_location);
Subroutine BEGIN: called CC=1 SCAR=0.0
23 328 ▶use App::FileSync::IO qw(ensure_dir);
Subroutine BEGIN: called CC=1 SCAR=0.0
24  
25 328 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
26  
27 # Patterns that must never enter a manifest; they are excluded on both sides.
28 328 our @DEFAULT_IGNORE = (
29 $ROOT_MARKER,
30 "$TEMP_PREFIX*",
31 $SNAPSHOT_DIR,
32 '*.swp',
33 '*~',
34 '.#*',
35 '#*#',
36 '.DS_Store',
37 '._*',
38 'Thumbs.db',
39 'desktop.ini',
40 '*.crdownload',
41 '*.part',
42 );
43  
44 # Schemas for the positional entry points.
45 328 my %PATH_RULE = (type => 'string', min => 1);
46 328 my %ROOT_REPO = (root => {%PATH_RULE}, repo => {%PATH_RULE});
47  
48 =encoding utf8
49  
50 =head1 NAME
51  
52 App::FileSync::Config - client and repo configuration files
53  
54 =head1 SYNOPSIS
55  
56 my $client = App::FileSync::Config::load_client();
57 $client->{repos}{docs}{root} = '/home/foo/Documents';
58 App::FileSync::Config::save_client($client);
59  
60 my $repo = App::FileSync::Config::load_repo('/srv/filesync', 'docs');
61  
62 =head1 DESCRIPTION
63  
64 The client keeps one JSON file, F<~/.filesync/config.json> (or
65 C<FILESYNC_CONFIG>), listing its repos. The server keeps one JSON file per
66 repo, F<ROOT/.filesync/repos/NAME/config.json>, holding its policy (trash
67 retention, deletion limits, ignore patterns) and the allowed clients. Both are
68 written atomically.
69  
70 =head1 FUNCTIONS
71  
72 =head2 home_dir
73  
74 Purpose: the client's state directory.
75  
76 Args: none.
77  
78 Returns: C<FILESYNC_HOME>, else F<~/.filesync> (using C<HOME>, then
79 C<USERPROFILE>).
80  
81 Side Effects: none.
82  
83 Usage:
84  
85 my $home = App::FileSync::Config::home_dir();
86  
87 =head3 EXAMPLE
88  
89 print App::FileSync::Config::home_dir(), "\n"; # /home/foo/.filesync
90  
91 =head3 API SPECIFICATION
92  
93 =head4 INPUT
94  
95 []
96  
97 =head4 OUTPUT
98  
99 { type => 'string', min => 1 }
100  
101 =head3 MESSAGES
102  
103 Key Meaning Resolution
104 config.no_home no home directory is known set FILESYNC_HOME
105  
106 =head3 FORMAL SPECIFICATION
107  
108 home_dir = ENV(FILESYNC_HOME) if non-empty
109 = (ENV(HOME) or ENV(USERPROFILE)) / ".filesync" if one is non-empty
110 ↑ config.no_home otherwise
111  
112 =cut
113  
114 1096 ▶sub home_dir {
Subroutine home_dir: called CC=4 SCAR=22.3
Pod documented
115 # FILESYNC_HOME names the directory itself; otherwise it sits in the
116 # user's home (USERPROFILE on Windows, where HOME is often unset).
117 1096 my $directory = _env('FILESYNC_HOME');
118 1096 ▶ unless (defined $directory) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $directory) 0 1096 1096
119 0 ▶ my $home = _env('HOME') // _env('USERPROFILE');
Condition0%0/3
_env("HOME") // _env("USERPROFILE")
l!l&&r!l&&!r
000
MC/DC0%0/2
_env("HOME") // _env("USERPROFILE")
_env("HOME") _env("USERPROFILE")
Truth table0%0/3
A // B
A= _env("HOME")B= _env("USERPROFILE")
ABresult
1X1
011
000
120 0 ▶ throw('config.no_home') unless defined $home;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $home 0 0 0
121 0 $directory = File::Spec->catdir($home, '.filesync');
122 }
123  
124 1096 return $directory;
125 }
126  
127 =head2 client_config_path
128  
129 Purpose: where the client's repo list is stored.
130  
131 Args: none.
132  
133 Returns: C<FILESYNC_CONFIG>, else F<HOME_DIR/config.json>.
134  
135 Side Effects: none.
136  
137 Usage:
138  
139 my $path = App::FileSync::Config::client_config_path();
140  
141 =head3 EXAMPLE
142  
143 local $ENV{FILESYNC_CONFIG} = '/tmp/test.json';
144 print App::FileSync::Config::client_config_path(), "\n"; # /tmp/test.json
145  
146 =head3 API SPECIFICATION
147  
148 =head4 INPUT
149  
150 []
151  
152 =head4 OUTPUT
153  
154 { type => 'string', min => 1 }
155  
156 =head3 MESSAGES
157  
158 Key Meaning Resolution
159 config.no_home no home directory is known set FILESYNC_HOME
160  
161 =head3 FORMAL SPECIFICATION
162  
163 client_config_path = ENV(FILESYNC_CONFIG) if non-empty, else home_dir / "config.json"
164  
165 =cut
166  
167 80 ▶sub client_config_path {
Subroutine client_config_path: called CC=2 SCAR=7.2
Pod documented
168 80 my $explicit = _env('FILESYNC_CONFIG');
169  
170 80 ▶ return defined $explicit ? $explicit : File::Spec->catfile(home_dir(), 'config.json');
Branch: 1 branch
BranchTrueFalseTotal
defined $explicit ? : 80 0 80
171 }
172  
173 =head2 default_client_config
174  
175 Purpose: the configuration of a client that has no repos yet.
176  
177 Args: none.
178  
179 Returns: a new hashref C<{ version, ssh =E<gt> { command, extra_args }, repos =E<gt> {} }>.
180  
181 Side Effects: none.
182  
183 Usage:
184  
185 my $config = App::FileSync::Config::default_client_config();
186  
187 =head3 EXAMPLE
188  
189 my $config = App::FileSync::Config::default_client_config();
190 $config->{client_id} = 'laptop-1';
191  
192 =head3 API SPECIFICATION
193  
194 =head4 INPUT
195  
196 []
197  
198 =head4 OUTPUT
199  
200 {
201 type => 'hashref',
202 schema => {
203 version => { type => 'integer' },
204 ssh => { type => 'hashref' },
205 repos => { type => 'hashref' },
206 },
207 }
208  
209 =head3 MESSAGES
210  
211 None.
212  
213 =head3 FORMAL SPECIFICATION
214  
215 default_client_config = ⟨version ↦ 1, ssh ↦ default_ssh, repos ↦ ∅⟩
216  
217 =cut
218  
219 77 ▶sub default_client_config {
Subroutine default_client_config: called CC=1 SCAR=0.0
Pod documented
220 return {
221 77 version => 1,
222 ssh => _default_ssh(),
223 repos => {},
224 };
225 }
226  
227 =head2 load_client
228  
229 Purpose: read the client's repo list.
230  
231 Args: optional C<$path> (default L</client_config_path>).
232  
233 Returns: the configuration hashref; a missing file gives
234 L</default_client_config>. C<repos> and C<ssh> are always hashes.
235  
236 Side Effects: none.
237  
238 Usage:
239  
240 my $config = App::FileSync::Config::load_client($opts{config});
241  
242 =head3 EXAMPLE
243  
244 my $config = App::FileSync::Config::load_client();
245 print join(', ', sort keys %{ $config->{repos} }), "\n";
246  
247 =head3 API SPECIFICATION
248  
249 =head4 INPUT
250  
251 [ { name => 'path', type => 'string', optional => 1 } ]
252  
253 =head4 OUTPUT
254  
255 { type => 'hashref' }
256  
257 =head3 MESSAGES
258  
259 Key Meaning Resolution
260 config.parse the file is not valid JSON fix or remove it
261 config.not_object the JSON is not an object fix or remove it
262 io.read the file cannot be read check permissions
263  
264 =head3 FORMAL SPECIFICATION
265  
266 load_client(p) = normalise(json(FS(p))) if p ∈ dom FS
267 = default_client_config otherwise
268  
269 =cut
270  
271 287 ▶sub load_client {
Subroutine load_client: called CC=4 SCAR=14.0
Pod documented
272 287 my $args = positional(\@_, ['path'], { path => { type => 'string', optional => 1 } }, 'load_client');
273 287 my $path = _or_default($args->{path}, \&client_config_path);
274  
275 287 ▶ my $config = -e $path ? _load_object($path) : default_client_config();
Branch: 1 branch
BranchTrueFalseTotal
-e $path ? : 287 0 287
276  
277 # Older or hand-edited files may lack either section.
278 287 ▶ $config->{repos} = {} unless ref($config->{repos}) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $config->{"repos"} eq "HASH" 0 287 287
279 287 ▶ $config->{ssh} = _default_ssh() unless ref($config->{ssh}) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $config->{"ssh"} eq "HASH" 2 285 287
280  
281 287 return $config;
282 }
283  
284 =head2 save_client
285  
286 Purpose: write the client's repo list.
287  
288 Args: C<\%config>, optional C<$path>.
289  
290 Returns: the path written.
291  
292 Side Effects: replaces the file atomically, creating its directory.
293  
294 Usage:
295  
296 App::FileSync::Config::save_client($config, $path);
297  
298 =head3 EXAMPLE
299  
300 my $written = App::FileSync::Config::save_client(App::FileSync::Config::default_client_config());
301  
302 =head3 API SPECIFICATION
303  
304 =head4 INPUT
305  
306 [
307 { name => 'config', type => 'hashref' },
308 { name => 'path', type => 'string', optional => 1 },
309 ]
310  
311 =head4 OUTPUT
312  
313 { type => 'string', min => 1 }
314  
315 =head3 MESSAGES
316  
317 Key Meaning Resolution
318 io.write the file cannot be written check permissions and space
319  
320 =head3 FORMAL SPECIFICATION
321  
322 ΔFS
323 FS'(path) = json(config) ⁀ "\n"
324  
325 =cut
326  
327 84 ▶sub save_client {
Subroutine save_client: called CC=1 SCAR=0.0
Pod documented
328 84 my $args = positional(\@_, [qw(config path)], {
329 config => { type => 'hashref' },
330 path => { type => 'string', optional => 1 },
331 }, 'save_client');
332  
333 84 my $path = _or_default($args->{path}, \&client_config_path);
334 84 write_atomic($path, json_encode($args->{config}) . "\n");
335  
336 84 return $path;
337 }
338  
339 =head2 repo_meta_dir
340  
341 Documented with L</repo_config_path> below.
342  
343 =head2 repo_config_path
344  
345 Purpose: where a repo's metadata (and its config file) lives on the server.
346  
347 Args: C<$root>, C<$repo>.
348  
349 Returns: F<ROOT/.filesync/repos/REPO> and F<.../config.json>.
350  
351 Side Effects: none.
352  
353 Usage:
354  
355 my $meta = App::FileSync::Config::repo_meta_dir($root, $repo);
356  
357 =head3 EXAMPLE
358  
359 print App::FileSync::Config::repo_config_path('/srv/filesync', 'docs'), "\n";
360  
361 =head3 API SPECIFICATION
362  
363 =head4 INPUT
364  
365 [
366 { name => 'root', type => 'string', min => 1 },
367 { name => 'repo', type => 'string', min => 1 },
368 ]
369  
370 =head4 OUTPUT
371  
372 { type => 'string', min => 1 }
373  
374 =head3 MESSAGES
375  
376 None.
377  
378 =head3 FORMAL SPECIFICATION
379  
380 repo_meta_dir(r, n) = r / ".filesync" / "repos" / n
381 repo_config_path(r, n) = repo_meta_dir(r, n) / "config.json"
382  
383 =cut
384  
385 2693 ▶sub repo_meta_dir {
Subroutine repo_meta_dir: called CC=1 SCAR=0.0
Pod documented
386 2693 my ($root, $repo) = @_;
387  
388 2693 return File::Spec->catdir($root, '.filesync', 'repos', $repo);
389 }
390  
391 664 ▶sub repo_config_path {
Subroutine repo_config_path: called CC=1 SCAR=0.0
Pod documented
392 664 my ($root, $repo) = @_;
393  
394 664 return File::Spec->catfile(repo_meta_dir($root, $repo), 'config.json');
395 }
396  
397 =head2 default_repo_config
398  
399 Purpose: the policy of a newly created repo.
400  
401 Args: C<$name>.
402  
403 Returns: a new hashref: 30 days of trash, at most 200 or 10% of known files
404 deleted per session, inline conflict copies, modes preserved, symlinks not
405 followed, no clients, the default ignore list.
406  
407 Side Effects: none.
408  
409 Usage:
410  
411 my $config = App::FileSync::Config::default_repo_config('docs');
412  
413 =head3 EXAMPLE
414  
415 my $config = App::FileSync::Config::default_repo_config('photos');
416 $config->{trash_days} = 90;
417  
418 =head3 API SPECIFICATION
419  
420 =head4 INPUT
421  
422 [ { name => 'name', type => 'string', min => 1 } ]
423  
424 =head4 OUTPUT
425  
426 { type => 'hashref' }
427  
428 =head3 MESSAGES
429  
430 Key Meaning Resolution
431 args.invalid no name was given pass the repo name
432  
433 =head3 FORMAL SPECIFICATION
434  
435 default_repo_config(n) = ⟨name ↦ n, trash_days ↦ 30, max_deletes ↦ 200,
436 max_delete_percent ↦ 10, clients ↦ ∅, ignore ↦ DEFAULT_IGNORE, ...⟩
437  
438 =cut
439  
440 82 ▶sub default_repo_config {
Subroutine default_repo_config: called CC=1 SCAR=0.0
Pod documented
441 82 my $args = positional(\@_, ['name'], { name => {%PATH_RULE} }, 'default_repo_config');
442  
443 return {
444 version => 1,
445 name => $args->{name},
446 82 created => scalar(gmtime()) . ' UTC',
447 trash_days => $TRASH_DAYS,
448 max_deletes => $MAX_DELETES,
449 max_delete_percent => $MAX_DELETE_PERCENT,
450 conflicts => 'inline',
451 preserve_mode => JSON::PP::true,
452 allow_symlinks => JSON::PP::false,
453 clients => {},
454 ignore => [ @DEFAULT_IGNORE ],
455 };
456 }
457  
458 =head2 load_repo
459  
460 Purpose: read a repo's policy from the server root.
461  
462 Args: C<$root>, C<$repo>.
463  
464 Returns: the configuration hashref; C<ignore> is always an array and
465 C<clients> always a hash.
466  
467 Side Effects: none.
468  
469 Usage:
470  
471 my $config = App::FileSync::Config::load_repo($root, 'docs');
472  
473 =head3 EXAMPLE
474  
475 my $config = App::FileSync::Config::load_repo('/srv/filesync', 'docs');
476 print "$config->{trash_days} days of trash\n";
477  
478 =head3 API SPECIFICATION
479  
480 =head4 INPUT
481  
482 [
483 { name => 'root', type => 'string', min => 1 },
484 { name => 'repo', type => 'string', min => 1 },
485 ]
486  
487 =head4 OUTPUT
488  
489 { type => 'hashref' }
490  
491 =head3 MESSAGES
492  
493 Key Meaning Resolution
494 config.no_repo no such repo under the root filesync-admin repo create
495 config.parse the file is not valid JSON fix it by hand
496 config.not_object the JSON is not an object fix it by hand
497  
498 =head3 FORMAL SPECIFICATION
499  
500 load_repo(r, n) = normalise(json(FS(repo_config_path(r, n))))
501 pre repo_config_path(r, n) ∈ dom FS
502  
503 =cut
504  
505 422 ▶sub load_repo {
Subroutine load_repo: called CC=4 SCAR=14.0
Pod documented
506 422 my $args = positional(\@_, [qw(root repo)], {%ROOT_REPO}, 'load_repo');
507 422 my ($root, $repo) = @{$args}{qw(root repo)};
508  
509 422 my $path = repo_config_path($root, $repo);
510 422 ▶ throw('config.no_repo', { repo => $repo, root => $root }) unless -e $path;
Branch: 1 branch
BranchTrueFalseTotal
unless -e $path 2 420 422
511  
512 420 my $config = _load_object($path);
513 420 ▶ $config->{ignore} = [ @DEFAULT_IGNORE ] unless ref($config->{ignore}) eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $config->{"ignore"} eq "ARRAY" 0 420 420
514 420 ▶ $config->{clients} = {} unless ref($config->{clients}) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $config->{"clients"} eq "HASH" 0 420 420
515  
516 420 return $config;
517 }
518  
519 =head2 save_repo
520  
521 Purpose: write a repo's policy.
522  
523 Args: C<$root>, C<$repo>, C<\%config>.
524  
525 Returns: the path written.
526  
527 Side Effects: creates the repo's metadata directory; replaces the file
528 atomically.
529  
530 Usage:
531  
532 App::FileSync::Config::save_repo($root, 'docs', $config);
533  
534 =head3 EXAMPLE
535  
536 my $config = App::FileSync::Config::load_repo($root, 'docs');
537 $config->{trash_days} = 60;
538 App::FileSync::Config::save_repo($root, 'docs', $config);
539  
540 =head3 API SPECIFICATION
541  
542 =head4 INPUT
543  
544 [
545 { name => 'root', type => 'string', min => 1 },
546 { name => 'repo', type => 'string', min => 1 },
547 { name => 'config', type => 'hashref' },
548 ]
549  
550 =head4 OUTPUT
551  
552 { type => 'string', min => 1 }
553  
554 =head3 MESSAGES
555  
556 Key Meaning Resolution
557 io.mkdir the directory cannot be made check permissions
558 io.write the file cannot be written check permissions and space
559  
560 =head3 FORMAL SPECIFICATION
561  
562 ΔFS
563 FS'(repo_config_path(r, n)) = json(config) ⁀ "\n"
564  
565 =cut
566  
567 159 ▶sub save_repo {
Subroutine save_repo: called CC=1 SCAR=0.0
Pod documented
568 159 my $args = positional(\@_, [qw(root repo config)], {
569 %ROOT_REPO,
570 config => { type => 'hashref' },
571 }, 'save_repo');
572 159 my ($root, $repo) = @{$args}{qw(root repo)};
573  
574 159 ensure_dir(repo_meta_dir($root, $repo));
575 159 my $path = repo_config_path($root, $repo);
576 159 write_atomic($path, json_encode($args->{config}) . "\n");
577  
578 159 return $path;
579 }
580  
581 # _load_object
582 # Purpose: read a JSON file that must hold an object.
583 # Entry: $path exists.
584 # Exit: returns the decoded hashref.
585 # Side effects: raises config.parse or config.not_object.
586 707 ▶sub _load_object :Private {
Subroutine _load_object: called CC=3 SCAR=11.2
587 707 my ($path) = @_;
588  
589 707 my $text = read_text($path);
590 707 my $data = eval { json_decode($text) };
591 707 ▶ throw('config.parse', { path => $path, error => strip_location($@) }) if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 707 707
592 707 ▶ throw('config.not_object', { path => $path }) unless ref($data) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $data eq "HASH" 0 707 707
593  
594 707 return $data;
595 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
596  
597 # _default_ssh
598 # Purpose: the ssh section of a client config that has none.
599 # Entry: none.
600 # Exit: returns a new hashref.
601 # Side effects: none.
602 79 ▶sub _default_ssh :Private {
Subroutine _default_ssh: called CC=1 SCAR=0.0
603 79 return { command => 'ssh', extra_args => [] };
604 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
605  
606 # _env
607 # Purpose: an environment variable, treating empty as unset.
608 # Entry: $name is the variable's name.
609 # Exit: returns the value, or undef when unset or empty.
610 # Side effects: none.
611 1176 ▶sub _env :Private {
Subroutine _env: called CC=3 SCAR=12.5
612 1176 my ($name) = @_;
613  
614 1176 my $value = $ENV{$name};
615 1176 ▶ return (defined $value && length $value) ? $value : undef;
Branch: 1 branch
BranchTrueFalseTotal
defined $value && length $value ? : 1176 0 1176
Condition33%1/3
defined $value and length $value
!ll&&!rl&&r
001176
MC/DC0%0/2
defined $value and length $value
defined $value length $value
Truth table33%1/3
A and B
A= defined $valueB= length $value
ABresult
0X0
100
111
616 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
617  
618 # _or_default
619 # Purpose: use a given path, or compute the default one.
620 # Entry: $given may be undef or empty; $default is a coderef.
621 # Exit: returns the path to use.
622 # Side effects: whatever $default does (reads %ENV).
623 371 ▶sub _or_default :Private {
Subroutine _or_default: called CC=3 SCAR=11.1
624 371 my ($given, $default) = @_;
625  
626 371 ▶ return (defined $given && length $given) ? $given : $default->();
Branch: 1 branch
BranchTrueFalseTotal
defined $given && length $given ? : 293 78 371
Condition66%2/3
defined $given and length $given
!ll&&!rl&&r
780293
MC/DC50%1/2
defined $given and length $given
defined $given length $given
Truth table66%2/3
A and B
A= defined $givenB= length $given
ABresult
0X0
100
111
627 328 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
628  
629 328 1;
630  
631 __END__
« blib/lib/App/FileSync/Transport/Local.pm ↑ Summary blib/lib/App/FileSync/Store.pm »