blib/lib/App/FileSync.pm

filter: Statementstmt 97.0% 132 / 136 Branchbran 92.3% 72 / 78 Conditioncond 73.3% 11 / 15 MC/DCmcdc 50.0% 4 / 8 Subroutinesub 96.9% 32 / 33 Podpod 100% 11 / 11 totaltotal 93.2% 262 / 281 CC 50 SCAR 20.0
CC
50
Cov
94%
validate_relpath
18.0
__ANON__
11.0
_validate_id
7.0
CRAP 7.4
« blib/lib/App/FileSync/Admin.pm ↑ Summary blib/lib/App/FileSync/Ignore.pm »
1 package App::FileSync;
2  
3 # The pieces shared by the client, the server and the admin tools:
4 # byte-transparent JSON, path and id validation, conflict-copy naming, date
5 # parsing and (re-exported from App::FileSync::IO) atomic file writes.
6  
7 # TODO: from the 0.002.0 gap analysis. Pre-release blockers first.
8 #
9 # Behaviour that is silently wrong or inconsistent:
10 # TODO: trash retention of 0 means different things on each side: the client's
11 # local_trash_days 0 keeps trash forever (Client.pm, "//"), the server's
12 # trash_days 0 silently becomes 30 days (Store.pm prune_trash, "||").
13 # Pick one meaning, document it, add a regression test.
14 # TODO: document for users that 0 switches off --max-deletes and
15 # --max-delete-percent (only Merge's internal POD says so; not the help
16 # text, the admin POD or website/html/commands.html).
17 # TODO: give --max-delete-percent an upper bound of 100 (150 is accepted).
18 # TODO: Params::Validate::Strict failures bypass the catalogue and name the
19 # internal parameter ('trash_days') instead of the option (--trash-days).
20 # TODO: I18N::warning is exported but never called or tested, and its
21 # trailing "\n" to carp puts the location on its own line, unlike its
22 # FORMAL SPECIFICATION. Test and fix it, or remove it.
23 #
24 # Failure and rollback paths no test runs:
25 # TODO: Delta past the 8 MiB scan window (the literal tail loop in diff):
26 # large-file deltas are unverified; "local $SCAN_LIMIT" makes it cheap.
27 # TODO: Snapshot rollback: a failed build should remove its temp directory.
28 # TODO: IO::write_atomic failure (a full disk): the temp file is discarded.
29 # TODO: Scan::clean_stale_temps never deletes a stale temp in any test.
30 # TODO: type changes: moving a directory into the trash (Trash::move_to_trash)
31 # and replacing a directory with a file (IO::clear_target).
32 # TODO: the admin root-not-writable path in Admin::repo_create.
33 #
34 # Commands and APIs with no tests:
35 # TODO: filesync-admin "repo show" and "client list" (Admin::repo_show,
36 # Admin::client_list) never run, in-process or through the CLI.
37 # TODO: Protocol::close, Transport::SSH::command and exit_status,
38 # Transport::Local::error_text, Store::root and Store::repo.
39 # TODO: the extra_args check in Transport::SSH->new has never run.
40 #
41 # Mutation testing:
42 # TODO: the 80% score is 10 mutants, all in Platform.pm. Mutation-test Merge,
43 # Delta, the server's %MAY table and the deletion guard.
44 # TODO: kill the two survivors: nothing checks the return value of
45 # Platform::use_plain_end_of_scope_hook.
46 #
47 # Documentation:
48 # TODO: =head3 PSEUDOCODE for the 24 public routines over 15 lines without it
49 # (Server::new, Client::new, Trash::move_to_trash and prune,
50 # Merge::check_delete_limit, Scan::clean_stale_temps, Ignore::new, ...).
51 # TODO: UTF-8 notes in Scan, Ignore, Trash, Snapshot and Store: names are
52 # bytes, and NFC and NFD forms of a name are different files.
53 # TODO: warn when the client cache is damaged: the run silently re-hashes
54 # every file (no data is at risk; the merge base is on the server).
55 # TODO: remove the unused message key word.snapshot, and make t/locales.t
56 # report unused keys as well as missing ones.
57 #
58 # Post-release roadmap: features.
59 # TODO: incremental manifests (a change journal or Merkle summary), so an
60 # idle run costs almost nothing instead of O(files).
61 # TODO: "filesync watch": sync on file changes (inotify, FSEvents,
62 # ReadDirectoryChangesW), with cron as the fallback.
63 # TODO: let a client restore from the server's trash (admin-only today).
64 # TODO: selective sync: a client takes only a subtree of a repo.
65 # TODO: --bwlimit and a quiet-hours window for metered links.
66 # TODO: monitoring output: a node-exporter textfile, or a status --json health
67 # summary that alerts on repeated exit codes 3 or 4.
68 # TODO: reconcile NFC and NFD forms of a name (the macOS/Linux gap).
69 # TODO: a conflict review command to list and resolve conflict copies.
70 #
71 # Post-release roadmap: technical debt.
72 # TODO: widen mutation testing (Merge, Delta, Server, Trash first) and gate CI
73 # on condition coverage (57% now).
74 # TODO: pipeline the protocol: one request in flight bounds throughput by the
75 # round-trip time.
76 # TODO: stream the plan as JSON lines instead of one huge line, which also
77 # bounds message size.
78 # TODO: fsync: renames are atomic between processes but not durable across a
79 # power cut.
80 # TODO: an optional native rolling checksum (Inline::C or XS) to lift the
81 # 8 MiB scan window; pure Perl manages about 2.5 MB/s when nothing matches.
82 # TODO: one validation error layer that turns Params::Validate::Strict
83 # failures into catalogue messages naming the CLI option.
84  
85 333 ▶use App::FileSync::Platform;
Subroutine BEGIN: called CC=1 SCAR=0.0
86  
87 333 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
88 333 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
89 333 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
90 333 ▶use feature 'current_sub';
Subroutine BEGIN: called CC=1 SCAR=0.0
91  
92 333 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
93 333 ▶use JSON::MaybeXS ();
Subroutine BEGIN: called CC=1 SCAR=0.0
94 333 ▶use POSIX qw(strftime);
Subroutine BEGIN: called CC=1 SCAR=0.0
95 333 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
96 333 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
97 333 ▶use Time::Local ();
Subroutine BEGIN: called CC=1 SCAR=0.0
98  
99 333 ▶use App::FileSync::Constants qw($MAX_ID_LENGTH $SECONDS_PER_DAY);
Subroutine BEGIN: called CC=1 SCAR=0.0
100 333 ▶use App::FileSync::I18N qw(message throw);
Subroutine BEGIN: called CC=1 SCAR=0.0
101 333 ▶use App::FileSync::IO qw(write_atomic read_text set_mtime);
Subroutine BEGIN: called CC=1 SCAR=0.0
102  
103 333 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
104  
105 333 our @EXPORT_OK = qw(
106 json_encode json_decode
107 validate_relpath validate_repo_name validate_client_id
108 conflict_name name_with_suffix split_name
109 format_utc parse_since parse_until
110 write_atomic read_text set_mtime
111 );
112  
113 # Limits on paths as they travel on the wire. Package variables rather than
114 # Readonly because they document the protocol and tests read them.
115 333 our $MAX_PATH_BYTES = 4096;
116 333 our $MAX_COMPONENT_BYTES = 255;
117  
118 # A conflict-copy name is kept this far inside the common 255-byte limit, and
119 # never trims the original stem below the minimum.
120 333 Readonly::Scalar my $CONFLICT_NAME_BYTES => 200;
121 333 Readonly::Scalar my $MIN_STEM_BYTES => 16;
122  
123 # The alphabet of a repo or client id: it becomes a directory name.
124 333 Readonly my $ID_PATTERN => qr/\A[A-Za-z0-9][A-Za-z0-9._-]*\z/;
125  
126 # What an unusable client id is replaced with in a conflict-copy name.
127 333 Readonly::Scalar my $UNKNOWN_CLIENT => 'unknown';
128  
129 # format_utc's ISO 8601 basic format: 20261104T014157Z.
130 333 Readonly::Scalar my $UTC_STAMP => '%Y%m%dT%H%M%SZ';
131  
132 # JSON::MaybeXS picks Cpanel::JSON::XS, then JSON::XS, then the core JSON::PP,
133 # and installing it pulls in Cpanel::JSON::XS wherever there is a compiler. On
134 # a 100,000-file manifest Cpanel::JSON::XS decodes in 0.2s where JSON::PP takes
135 # about 15s. All three read any valid JSON, so a client and a server using
136 # different backends still understand each other. The text differs only in
137 # number formatting (Cpanel::JSON::XS writes a whole-valued float as 1000.0),
138 # which decodes to the same value everywhere.
139 #
140 # Deliberately utf8(0): paths are byte strings on the wire, and both ends of the
141 # protocol are this implementation.
142 333 my $JSON = JSON::MaybeXS->new->canonical->allow_nonref;
143  
144 # Both backends return UTF8-flagged strings even though paths are byte strings on
145 # disk. Left alone, the flag makes -e/stat encode the name a second time and
146 # every non-ASCII file "disappears". This downgrades back to the original
147 # bytes; only a genuine wide-character string is encoded as UTF-8.
148 #
149 # Hash keys need the same treatment, and manifests are keyed by path, but a key
150 # cannot be changed in place: a non-ASCII key is deleted and stored again as
151 # bytes. An ASCII key names the same file flagged or not, so it is left alone,
152 # which keeps the cost to one pattern match per key.
153 #
154 # A lexical coderef rather than a named sub: it runs once per JSON value (six
155 # times per manifest entry), and the Sub::Private enforce wrapper would cost
156 # more than the work. Being lexical, nothing outside this file can reach it.
157 62163 ▶my $to_bytes = sub {
Subroutine __ANON__: called CC=11 SCAR=24.0
158 # Work through @_ aliases: copying the scalar would rewrite the copy only.
159 62163 ▶ if (ref($_[0]) eq 'HASH') {
Branch: 3 branches
BranchTrueFalseTotal
if (ref $_[0] eq 'HASH') { } 10992 51171 62163
elsif (ref $_[0] eq 'ARRAY') { } 1772 49399 51171
elsif (defined $_[0] and not ref $_[0] and utf8::is_utf8($_[0])) { } 9 50245 50254
160 10992 my $hash = $_[0];
161 10992 for my $key (grep { /[^\x00-\x7f]/ } keys %{$hash}) {
162 13 my $bytes = $key;
163 13 ▶ utf8::encode($bytes) unless utf8::downgrade($bytes, 1);
Branch: 1 branch
BranchTrueFalseTotal
unless utf8::downgrade($bytes, 1) 0 13 13
164 # delete first: a flagged key and its bytes are the same hash key.
165 13 my $value = delete $hash->{$key};
166 13 $hash->{$bytes} = $value;
167 }
168 10992 __SUB__->($_) for values %{$hash};
169 } elsif (ref($_[0]) eq 'ARRAY') {
170 1772 __SUB__->($_) for @{ $_[0] };
171 ▶ } elsif (defined($_[0]) && !ref($_[0]) && utf8::is_utf8($_[0])) {
Condition100%6/6
defined $_[0] and not ref $_[0] and utf8::is_utf8($_[0])
!ll&&!rl&&r
855485359
defined $_[0] and not ref $_[0]
!ll&&!rl&&r
1084548544
MC/DC100%3/3
defined $_[0] and not ref $_[0] and utf8::is_utf8($_[0])
defined $_[0] not ref $_[0] utf8::is_utf8($_[0])
Truth table100%4/4
A and not(B) and C
A= defined $_[0]B= not ref $_[0]C= utf8::is_utf8($_[0])
ABCresult
0XX0
10X0
1100
1111
172 9 ▶ utf8::encode($_[0]) unless utf8::downgrade($_[0], 1);
Branch: 1 branch
BranchTrueFalseTotal
unless utf8::downgrade($_[0], 1) 0 9 9
173 }
174 62163 return 1;
175 333 };
176  
177 =encoding utf8
178  
179 =head1 NAME
180  
181 App::FileSync - cron-driven file synchronisation without a daemon
182  
183 =head1 VERSION
184  
185 0.002.1
186  
187 =head1 SYNOPSIS
188  
189 filesync-admin --root ~/filesync repo create documents
190 filesync init --repo documents --root ~/Documents \
191 --transport local --server-root ~/filesync --remote-repo documents
192 filesync sync --repo documents --dry-run
193 filesync sync --repo documents
194  
195 =head1 DESCRIPTION
196  
197 App::FileSync keeps a directory on each client in step with one master copy on
198 the server. Clients never talk to each other: each pushes its changes to the
199 master and pulls everyone else's from it, so a change made on one client - a
200 new file, an edit or a deletion - reaches the others on their next run. Any
201 number of clients can share a repo this way.
202  
203 A separate machine can hold a replica of the master. Every run is a
204 short-lived CLI process suitable for cron or the Windows Task Scheduler: there
205 is no daemon, no database and no web interface.
206  
207 Only files whose content changed are transferred. Data frames are deflated when that
208 makes them smaller, and files of at least 64 KiB are sent as rsync-style block deltas
209 when the other side already holds an older copy, so an edit moves the changed blocks
210 rather than the whole file. C<filesync sync --no-delta> forces whole files. Each run
211 reports the payload bytes it sent and received and how many files moved as a delta, and
212 C<filesync log> repeats those figures for past runs.
213  
214 Every message the tools print is looked up in a catalogue
215 (L<App::FileSync::I18N>), so a translation is one new catalogue.
216  
217 This module holds the pieces shared by the client, the server and the admin tools:
218 byte-transparent JSON, path validation, conflict-copy naming and atomic file writes.
219  
220 =head1 FUNCTIONS
221  
222 =head2 json_encode
223  
224 Purpose: encode a structure as one line of canonical JSON.
225  
226 Args: C<$data>, any JSON-encodable value.
227  
228 Returns: the JSON text, keys sorted, with no trailing newline.
229  
230 Side Effects: none.
231  
232 Usage:
233  
234 print {$fh} json_encode($event), "\n";
235  
236 =head3 EXAMPLE
237  
238 print json_encode({ b => 1, a => [ 'x' ] }), "\n"; # {"a":["x"],"b":1}
239  
240 =head3 API SPECIFICATION
241  
242 =head4 INPUT
243  
244 [ { name => 'data', type => 'scalar', optional => 1 } ]
245  
246 =head4 OUTPUT
247  
248 { type => 'string', min => 1 }
249  
250 =head3 MESSAGES
251  
252 The JSON backend's own error for a value it cannot encode (a code reference,
253 say). L<JSON::MaybeXS> chooses the backend: L<Cpanel::JSON::XS>, else
254 L<JSON::XS>, else L<JSON::PP>.
255  
256 =head3 FORMAL SPECIFICATION
257  
258 json_encode : VALUE → TEXT
259 json_decode(json_encode(v)) = v
260  
261 =cut
262  
263 4602 ▶sub json_encode {
Subroutine json_encode: called CC=1 SCAR=0.0
Pod documented
264 4602 my ($data) = @_;
265  
266 4602 return $JSON->encode($data);
267 }
268  
269 =head2 json_decode
270  
271 Purpose: decode one JSON document, keeping strings as byte strings.
272  
273 Args: C<$text>.
274  
275 Returns: the decoded structure. Strings that fit in bytes are downgraded, so a
276 path read back from JSON names the same file as the bytes it was written from.
277  
278 Side Effects: none.
279  
280 Usage:
281  
282 my $config = json_decode(read_text($path));
283  
284 =head3 EXAMPLE
285  
286 my $entry = json_decode('{"p":"caf\u00e9.txt"}');
287 print length($entry->{p}), "\n"; # 8 (bytes), not 9
288  
289 =head3 API SPECIFICATION
290  
291 =head4 INPUT
292  
293 [ { name => 'text', type => 'string' } ]
294  
295 =head4 OUTPUT
296  
297 { type => 'scalar', optional => 1 }
298  
299 =head3 MESSAGES
300  
301 The JSON backend's own error for malformed JSON, so its wording depends on
302 which backend L<JSON::MaybeXS> chose (L<Cpanel::JSON::XS>, else L<JSON::XS>,
303 else L<JSON::PP>).
304  
305 =head3 FORMAL SPECIFICATION
306  
307 json_decode : TEXT ↛ VALUE
308 ∀ s : STRING in result • ¬ utf8_flag(s) ∨ ∃ c ∈ s • ord c > 255
309  
310 =cut
311  
312 5129 ▶sub json_decode {
Subroutine json_decode: called CC=1 SCAR=0.0
Pod documented
313 5129 my ($text) = @_;
314  
315 5129 my $data = $JSON->decode($text);
316 5125 $to_bytes->($data);
317  
318 5125 return $data;
319 }
320  
321 =head2 validate_relpath
322  
323 Purpose: decide whether a path is safe to join to a sync root.
324  
325 Args: C<$path>, a relative path as it travels on the wire.
326  
327 Returns: a two-element list C<(1, undef)> for a usable path, or
328 C<(0, $reason)> where C<$reason> is a translated explanation. (A list rather
329 than a reference because every caller destructures it at once, and it is
330 called once per path in the tree.)
331  
332 Side Effects: none.
333  
334 Usage:
335  
336 my ($ok, $reason) = validate_relpath($path);
337  
338 =head3 EXAMPLE
339  
340 my ($ok, $why) = validate_relpath('notes/../secret');
341 print "$why\n" unless $ok; # parent path component
342  
343 =head3 API SPECIFICATION
344  
345 =head4 INPUT
346  
347 [ { name => 'path', type => 'scalar', optional => 1 } ]
348  
349 =head4 OUTPUT
350  
351 { type => 'arrayref', min => 2, max => 2 }
352  
353 =head3 MESSAGES
354  
355 Key Meaning
356 path.missing no path was given
357 path.not_text the path is a reference
358 path.empty the path is empty
359 path.too_long longer than 4096 bytes
360 path.absolute starts with /
361 path.drive starts with a drive letter
362 path.backslash contains a backslash
363 path.nul contains a NUL byte
364 path.control contains a control character
365 path.empty_component contains //, or starts or ends with /
366 path.dot_component has a . component
367 path.parent_component has a .. component
368 path.component_too_long a component is longer than 255 bytes
369  
370 Resolution: rename the file on the side that holds it.
371  
372 =head3 FORMAL SPECIFICATION
373  
374 SafePath == { p : seq BYTE |
375 0 < #p ≤ 4096 ∧ head p ≠ '/' ∧ ¬ drive(p) ∧
376 '\' ∉ ran p ∧ ran p ∩ CONTROL = ∅ ∧
377 ∀ c : split('/', p) • c ∉ {⟨⟩, ".", ".."} ∧ #c ≤ 255 }
378 validate_relpath(p) = (1, ⊥) if p ∈ SafePath
379 = (0, reason) otherwise
380  
381 =head3 PSEUDOCODE
382  
383 reject undef, references and empty strings
384 reject paths over 4096 bytes
385 reject absolute, drive-relative, backslash, NUL and control characters
386 for each "/"-separated component:
387 reject empty, ".", ".." and components over 255 bytes
388 accept
389  
390 =cut
391  
392 1700 ▶sub validate_relpath {
Subroutine validate_relpath: called CC=18 SCAR=28.9
Pod documented
393 1700 my ($path) = @_;
394  
395 # One key per rejection, checked in order: the first problem found is
396 # the one reported.
397 1700 ▶ my $problem =
Branch: 9 branches
BranchTrueFalseTotal
!defined($path) ? : 1 1699 1700
ref $path ? : 2 1697 1699
!length($path) ? : 1 1696 1697
length $path > $App::FileSync::MAX_PATH_BYTES ? : 1 1695 1696
$path =~ m[\A/] ? : 2 1693 1695
$path =~ /\A[A-Za-z]:/ ? : 1 1692 1693
$path =~ /\\/ ? : 1 1691 1692
$path =~ /\0/ ? : 2 1689 1691
$path =~ /[\x01-\x1f\x7f]/ ? : 2 1687 1689
398 !defined $path ? 'path.missing'
399 : ref $path ? 'path.not_text'
400 : !length $path ? 'path.empty'
401 : length($path) > $MAX_PATH_BYTES ? 'path.too_long'
402 : $path =~ m{\A/} ? 'path.absolute'
403 : $path =~ /\A[A-Za-z]:/ ? 'path.drive'
404 : $path =~ /\\/ ? 'path.backslash'
405 : $path =~ /\0/ ? 'path.nul'
406 : $path =~ /[\x01-\x1f\x7f]/ ? 'path.control'
407 : undef;
408  
409 # Components are only worth checking once the whole path is plausible.
410 1700 ▶ unless (defined $problem) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $problem) 1687 13 1700
411 1687 for my $part (split m{/}, $path, -1) {
412 1905 ▶ $problem =
Branch: 4 branches
BranchTrueFalseTotal
$part eq '' ? : 2 1903 1905
$part eq '.' ? : 1 1902 1903
$part eq '..' ? : 2 1900 1902
length $part > $App::FileSync::MAX_COMPONENT_BYTES ? : 1 1899 1900
413 $part eq '' ? 'path.empty_component'
414 : $part eq '.' ? 'path.dot_component'
415 : $part eq '..' ? 'path.parent_component'
416 : length($part) > $MAX_COMPONENT_BYTES ? 'path.component_too_long'
417 : undef;
418 1905 ▶ last if defined $problem;
Branch: 1 branch
BranchTrueFalseTotal
if defined $problem 6 1899 1905
419 }
420 }
421  
422 1700 ▶ return defined $problem ? (0, message($problem)) : (1, undef);
Branch: 1 branch
BranchTrueFalseTotal
defined $problem ? : 19 1681 1700
423 }
424  
425 =head2 validate_repo_name
426  
427 Documented with L</validate_client_id> below.
428  
429 =head2 validate_client_id
430  
431 Purpose: decide whether a repo name or client id is usable as a directory name.
432  
433 Args: C<$value>.
434  
435 Returns: C<(1, undef)>, or C<(0, $reason)> with a translated reason. The
436 alphabet is C<[A-Za-z0-9][A-Za-z0-9._-]*>, at most 64 characters.
437  
438 Side Effects: none.
439  
440 Usage:
441  
442 my ($ok, $reason) = validate_client_id($id);
443  
444 =head3 EXAMPLE
445  
446 my ($ok, $why) = validate_repo_name('../etc');
447 print "$why\n"; # bad repo name '../etc'
448  
449 =head3 API SPECIFICATION
450  
451 =head4 INPUT
452  
453 [ { name => 'value', type => 'scalar', optional => 1 } ]
454  
455 =head4 OUTPUT
456  
457 { type => 'arrayref', min => 2, max => 2 }
458  
459 =head3 MESSAGES
460  
461 Key Meaning Resolution
462 id.missing no value was given supply one
463 id.not_text the value is a reference pass a string
464 id.empty the value is empty supply one
465 id.too_long longer than 64 characters shorten it
466 id.bad outside the allowed alphabet use letters, digits, . _ -
467  
468 =head3 FORMAL SPECIFICATION
469  
470 Id == { s : seq CHAR | 0 < #s ≤ 64 ∧ head s ∈ ALNUM ∧ ran s ⊆ ALNUM ∪ {'.','_','-'} }
471 validate(s) = (1, ⊥) if s ∈ Id, (0, reason) otherwise
472  
473 =cut
474  
475 1247 ▶sub validate_repo_name {
Subroutine validate_repo_name: called CC=1 SCAR=0.0
Pod documented
476 1247 my ($value) = @_;
477  
478 1247 return _validate_id('id.repo_name', $value);
479 }
480  
481 599 ▶sub validate_client_id {
Subroutine validate_client_id: called CC=1 SCAR=0.0
Pod documented
482 599 my ($value) = @_;
483  
484 599 return _validate_id('id.client_id', $value);
485 }
486  
487 # _validate_id
488 # Purpose: shared check for repo names and client ids.
489 # Entry: $what_key is the catalogue key naming the kind of id;
490 # $value is the candidate.
491 # Exit: returns (1, undef) or (0, translated reason).
492 # Side effects: none.
493 1846 ▶sub _validate_id :Private {
Subroutine _validate_id: called CC=7 SCAR=19.5
494 1846 my ($what_key, $value) = @_;
495  
496 1846 ▶ my $problem =
Branch: 5 branches
BranchTrueFalseTotal
!defined($value) ? : 1 1845 1846
ref $value ? : 1 1844 1845
!length($value) ? : 2 1842 1844
length $value > $App::FileSync::MAX_ID_LENGTH ? : 2 1840 1842
!($value =~ /$ID_PATTERN/) ? : 11 1829 1840
497 !defined $value ? 'id.missing'
498 : ref $value ? 'id.not_text'
499 : !length $value ? 'id.empty'
500 : length($value) > $MAX_ID_LENGTH ? 'id.too_long'
501 : $value !~ $ID_PATTERN ? 'id.bad'
502 : undef;
503  
504 1846 ▶ return defined $problem
Branch: 1 branch
BranchTrueFalseTotal
defined $problem ? : 17 1829 1846
505 ? (0, message($problem, { what => message($what_key), value => $value }))
506 : (1, undef);
507 333 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
508  
509 =head2 parse_since
510  
511 Purpose: the start of a time window.
512  
513 Args: C<$value> (C<YYYY-MM-DD> or an epoch), optional C<$option> naming the
514 command-line option for the error message (default C<--since>).
515  
516 Returns: the epoch, or C<undef> when C<$value> is undef. A date means
517 midnight UTC that day.
518  
519 Side Effects: none.
520  
521 Usage:
522  
523 my $since = parse_since($opts{since});
524  
525 =head3 EXAMPLE
526  
527 print parse_since('2026-10-22'), "\n"; # 1792627200
528  
529 =head3 API SPECIFICATION
530  
531 =head4 INPUT
532  
533 [
534 { name => 'value', type => 'string', optional => 1 },
535 { name => 'option', type => 'string', optional => 1 },
536 ]
537  
538 =head4 OUTPUT
539  
540 { type => 'integer', optional => 1, min => 0 }
541  
542 =head3 MESSAGES
543  
544 Key Meaning Resolution
545 when.bad neither a date nor an epoch use YYYY-MM-DD or digits
546  
547 =head3 FORMAL SPECIFICATION
548  
549 parse_since : (DATE ∪ ℕ ∪ {⊥}) ↛ ℕ ∪ {⊥}
550 parse_since(n) = n ; parse_since(d) = midnight_utc(d) ; parse_since(⊥) = ⊥
551  
552 =cut
553  
554 34 ▶sub parse_since {
Subroutine parse_since: called CC=2 SCAR=7.0
Pod documented
555 34 my ($value, $option) = @_;
556  
557 34 ▶ my ($epoch) = @{ _parse_when($value, $option || '--since') };
Condition50%1/2
$option || '--since'
l!l
034
MC/DC0%0/1
$option || '--since'
$option
Truth table50%1/2
A
A= $option
Aresult
11
00
558 30 return $epoch;
559 }
560  
561 =head2 parse_until
562  
563 Purpose: the end of a time window.
564  
565 Args: as for L</parse_since> (default option name C<--until>).
566  
567 Returns: the epoch, or C<undef>. A date means the last second of that day, so
568 C<--until 2026-10-22> includes that day's runs.
569  
570 Side Effects: none.
571  
572 Usage:
573  
574 my $until = parse_until($opts{until});
575  
576 =head3 EXAMPLE
577  
578 print parse_until('2026-10-22'), "\n"; # 1792713599
579  
580 =head3 API SPECIFICATION
581  
582 =head4 INPUT
583  
584 [
585 { name => 'value', type => 'string', optional => 1 },
586 { name => 'option', type => 'string', optional => 1 },
587 ]
588  
589 =head4 OUTPUT
590  
591 { type => 'integer', optional => 1, min => 0 }
592  
593 =head3 MESSAGES
594  
595 Key Meaning Resolution
596 when.bad neither a date nor an epoch use YYYY-MM-DD or digits
597  
598 =head3 FORMAL SPECIFICATION
599  
600 parse_until(n) = n ; parse_until(d) = midnight_utc(d) + 86399 ; parse_until(⊥) = ⊥
601  
602 =cut
603  
604 33 ▶sub parse_until {
Subroutine parse_until: called CC=4 SCAR=14.1
Pod documented
605 33 my ($value, $option) = @_;
606  
607 33 ▶ my ($epoch, $is_date) = @{ _parse_when($value, $option || '--until') };
Condition50%1/2
$option || '--until'
l!l
033
MC/DC0%0/1
$option || '--until'
$option
Truth table50%1/2
A
A= $option
Aresult
11
00
608 31 ▶ return (defined $epoch && $is_date) ? $epoch + $SECONDS_PER_DAY - 1 : $epoch;
Branch: 1 branch
BranchTrueFalseTotal
defined $epoch && $is_date ? : 18 13 31
Condition66%2/3
defined $epoch and $is_date
!ll&&!rl&&r
01318
MC/DC50%1/2
defined $epoch and $is_date
defined $epoch $is_date
Truth table66%2/3
A and B
A= defined $epochB= $is_date
ABresult
0X0
100
111
609 }
610  
611 # _parse_when
612 # Purpose: parse "YYYY-MM-DD" or an epoch.
613 # Entry: $value may be undef; $option names the option for errors.
614 # Exit: returns [ $epoch_or_undef, $is_date ]; a date cutoff means a
615 # different instant at each end of a range, hence the flag.
616 # Side effects: raises when.bad for anything else.
617 67 ▶sub _parse_when :Private {
Subroutine _parse_when: called CC=5 SCAR=16.1
618 67 my ($value, $option) = @_;
619  
620 67 ▶ my $parsed =
Branch: 3 branches
BranchTrueFalseTotal
!defined($value) ? : 1 66 67
$value =~ /\A\d+\z/ ? : 36 30 66
$value =~ /\A(\d{4})-(\d{2})-(\d{2})\z/ ? : 24 6 30
621 !defined $value ? [ undef, 0 ]
622 : $value =~ /\A\d+\z/ ? [ $value + 0, 0 ]
623 : $value =~ /\A(\d{4})-(\d{2})-(\d{2})\z/ ? [ Time::Local::timegm(0, 0, 0, $3, $2 - 1, $1), 1 ]
624 : undef;
625  
626 67 ▶ throw('when.bad', { option => $option, value => $value }) unless $parsed;
Branch: 1 branch
BranchTrueFalseTotal
unless $parsed 6 61 67
627 61 return $parsed;
628 333 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
629  
630 =head2 format_utc
631  
632 Purpose: a compact UTC timestamp.
633  
634 Args: optional C<$epoch> (default now).
635  
636 Returns: C<YYYYMMDDTHHMMSSZ>.
637  
638 Side Effects: none.
639  
640 Usage:
641  
642 my $stamp = format_utc($run->{ts});
643  
644 =head3 EXAMPLE
645  
646 print format_utc(0), "\n"; # 19700101T000000Z
647  
648 =head3 API SPECIFICATION
649  
650 =head4 INPUT
651  
652 [ { name => 'epoch', type => 'number', optional => 1 } ]
653  
654 =head4 OUTPUT
655  
656 { type => 'string', matches => qr/\A\d{8}T\d{6}Z\z/ }
657  
658 =head3 MESSAGES
659  
660 None.
661  
662 =head3 FORMAL SPECIFICATION
663  
664 format_utc : ℕ → STAMP
665 format_utc(e) = yyyy mm dd 'T' HH MM SS 'Z' of gmtime(e)
666  
667 =cut
668  
669 163 ▶sub format_utc {
Subroutine format_utc: called CC=2 SCAR=7.2
Pod documented
670 163 my ($epoch) = @_;
671  
672 163 ▶ return strftime($UTC_STAMP, gmtime($epoch // time));
Condition50%1/2
$epoch // time
l!l
1630
MC/DC0%0/1
$epoch // time
$epoch
Truth table50%1/2
A
A= $epoch
Aresult
11
00
673 }
674  
675 =head2 split_name
676  
677 Purpose: split a relative path into directory, stem and extension.
678  
679 Args: C<$path>.
680  
681 Returns: an arrayref C<[ $dir, $stem, $ext ]>; C<$dir> has no trailing slash
682 and is empty at the top level, C<$ext> includes its dot and is empty when there
683 is none. A leading dot (C<.profile>) is part of the stem.
684  
685 Side Effects: none.
686  
687 Usage:
688  
689 my ($dir, $stem, $ext) = @{ split_name('a/b/report.txt') };
690  
691 =head3 EXAMPLE
692  
693 my $parts = split_name('notes/plan.v2.txt'); # ['notes', 'plan.v2', '.txt']
694  
695 =head3 API SPECIFICATION
696  
697 =head4 INPUT
698  
699 [ { name => 'path', type => 'string', min => 1 } ]
700  
701 =head4 OUTPUT
702  
703 { type => 'arrayref', min => 3, max => 3 }
704  
705 =head3 MESSAGES
706  
707 None.
708  
709 =head3 FORMAL SPECIFICATION
710  
711 split_name(p) = (d, s, e) where p = d ⁀ "/" ⁀ s ⁀ e ∨ (d = ⟨⟩ ∧ p = s ⁀ e)
712 e = ⟨⟩ ∨ (head e = '.' ∧ '.' ∉ ran(tail e)) ; s ≠ ⟨⟩
713  
714 =cut
715  
716 27 ▶sub split_name {
Subroutine split_name: called CC=3 SCAR=11.0
Pod documented
717 27 my ($path) = @_;
718  
719 27 ▶ my ($dir, $base) = $path =~ m{\A(.*)/([^/]+)\z} ? ($1, $2) : ('', $path);
Branch: 1 branch
BranchTrueFalseTotal
$path =~ m[\A(.*)/([^/]+)\z] ? : 2 25 27
720 27 ▶ my ($stem, $ext) = $base =~ /\A(.+)(\.[^.]+)\z/ ? ($1, $2) : ($base, '');
Branch: 1 branch
BranchTrueFalseTotal
$base =~ /\A(.+)(\.[^.]+)\z/ ? : 21 6 27
721  
722 27 return [ $dir, $stem, $ext ];
723 }
724  
725 =head2 name_with_suffix
726  
727 Purpose: make a name unique by numbering it before its extension.
728  
729 Args: C<$path>, C<$suffix> (a number).
730  
731 Returns: C<report-2.txt> for C<report.txt> and 2, keeping the directory.
732  
733 Side Effects: none.
734  
735 Usage:
736  
737 my $candidate = name_with_suffix($loser_name, $n);
738  
739 =head3 EXAMPLE
740  
741 print name_with_suffix('a/b.txt', 3), "\n"; # a/b-3.txt
742  
743 =head3 API SPECIFICATION
744  
745 =head4 INPUT
746  
747 [
748 { name => 'path', type => 'string', min => 1 },
749 { name => 'suffix', type => 'integer', min => 1 },
750 ]
751  
752 =head4 OUTPUT
753  
754 { type => 'string', min => 1 }
755  
756 =head3 MESSAGES
757  
758 None.
759  
760 =head3 FORMAL SPECIFICATION
761  
762 let (d, s, e) = split_name(p)
763 name_with_suffix(p, n) = join(d, s ⁀ "-" ⁀ n ⁀ e)
764  
765 =cut
766  
767 0 ▶sub name_with_suffix {
Subroutine name_with_suffix: not called CC=1 SCAR=6.9
Pod documented
768 0 my ($path, $suffix) = @_;
769  
770 0 my ($dir, $stem, $ext) = @{ split_name($path) };
771 0 return _join_dir($dir, "$stem-$suffix$ext");
772 }
773  
774 =head2 conflict_name
775  
776 Purpose: the name a losing version is kept under.
777  
778 Args: C<$path>, C<$client_id> (may be undef), C<$epoch> (default now).
779  
780 Returns: the original name with C<.conflict-CLIENT-TIMESTAMP> inserted before
781 the extension, kept within 200 bytes so it fits common filesystems.
782  
783 Side Effects: none.
784  
785 Usage:
786  
787 my $name = conflict_name('notes.txt', 'laptop-1', time);
788  
789 =head3 EXAMPLE
790  
791 print conflict_name('report.txt', 'laptop-1', 1_792_664_100), "\n";
792 # report.conflict-laptop-1-20261022T101500Z.txt
793  
794 =head3 API SPECIFICATION
795  
796 =head4 INPUT
797  
798 [
799 { name => 'path', type => 'string', min => 1 },
800 { name => 'client_id', type => 'string', optional => 1 },
801 { name => 'epoch', type => 'number', optional => 1 },
802 ]
803  
804 =head4 OUTPUT
805  
806 { type => 'string', min => 1 }
807  
808 =head3 MESSAGES
809  
810 None.
811  
812 =head3 FORMAL SPECIFICATION
813  
814 let (d, s, e) = split_name(p) ; id = sanitise(c) ; t = format_utc(when)
815 let room = max(16, 200 − #(".conflict-" ⁀ id ⁀ "-" ⁀ t ⁀ e))
816 conflict_name(p, c, when) = join(d, s[1..room] ⁀ ".conflict-" ⁀ id ⁀ "-" ⁀ t ⁀ e)
817  
818 =cut
819  
820 27 ▶sub conflict_name {
Subroutine conflict_name: called CC=5 SCAR=16.6
Pod documented
821 27 my ($path, $client_id, $epoch) = @_;
822  
823 27 my ($dir, $stem, $ext) = @{ split_name($path) };
824  
825 # The id lands in a file name, so anything outside the id alphabet is
826 # flattened rather than trusted.
827 27 ▶ my $id = defined $client_id ? $client_id : $UNKNOWN_CLIENT;
Branch: 1 branch
BranchTrueFalseTotal
defined $client_id ? : 27 0 27
828 27 $id =~ s/[^A-Za-z0-9._-]+/_/g;
829 27 ▶ $id = $UNKNOWN_CLIENT unless length $id;
Branch: 1 branch
BranchTrueFalseTotal
unless length $id 0 27 27
830  
831 27 my $tail = ".conflict-$id-" . format_utc($epoch) . $ext;
832  
833 # Keep the whole name inside the 255-byte limit of common filesystems.
834 27 my $room = $CONFLICT_NAME_BYTES - length($tail);
835 27 ▶ $room = $MIN_STEM_BYTES if $room < $MIN_STEM_BYTES;
Branch: 1 branch
BranchTrueFalseTotal
if $room < $MIN_STEM_BYTES 0 27 27
836 27 ▶ $stem = substr($stem, 0, $room) if length($stem) > $room;
Branch: 1 branch
BranchTrueFalseTotal
if length $stem > $room 0 27 27
837  
838 27 return _join_dir($dir, $stem . $tail);
839 }
840  
841 # _join_dir
842 # Purpose: put a relative directory and a name back together.
843 # Entry: $dir may be empty (top level).
844 # Exit: returns "dir/name" or "name".
845 # Side effects: none.
846 27 ▶sub _join_dir :Private {
Subroutine _join_dir: called CC=2 SCAR=6.9
847 27 my ($dir, $name) = @_;
848  
849 27 ▶ return length($dir) ? "$dir/$name" : $name;
Branch: 1 branch
BranchTrueFalseTotal
length $dir ? : 2 25 27
850 333 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
851  
852 =head2 write_atomic
853  
854 Documented with L</set_mtime> below.
855  
856 =head2 read_text
857  
858 Documented with L</set_mtime> below.
859  
860 =head2 set_mtime
861  
862 Re-exported from L<App::FileSync::IO>, where they are documented.
863  
864 =cut
865  
866 333 1;
867  
868 __END__
« blib/lib/App/FileSync/Admin.pm ↑ Summary blib/lib/App/FileSync/Ignore.pm »