| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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])
defined $_[0] and not ref $_[0]
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])
| |||||||||||||||||||||||||||||||||||||||||||
| 172 | 9 | ▶ | utf8::encode($_[0]) unless utf8::downgrade($_[0], 1); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 411 | 1687 | for my $part (split m{/}, $path, -1) { | |||||||||||||||||||||||||||||||||||||||||
| 412 | 1905 | ▶ | $problem = | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 4 branches
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 419 | } | ||||||||||||||||||||||||||||||||||||||||||
| 420 | } | ||||||||||||||||||||||||||||||||||||||||||
| 421 | |||||||||||||||||||||||||||||||||||||||||||
| 422 | 1700 | ▶ | return defined $problem ? (0, message($problem)) : (1, undef); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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'
MC/DC0%0/1
$option || '--since'
$option
Truth table50%1/2
A
A= $option
| |||||||||||||||||||||||||||||||||||||||||||
| 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'
MC/DC0%0/1
$option || '--until'
$option
Truth table50%1/2
A
A= $option
| |||||||||||||||||||||||||||||||||||||||||||
| 608 | 31 | ▶ | return (defined $epoch && $is_date) ? $epoch + $SECONDS_PER_DAY - 1 : $epoch; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
defined $epoch and $is_date
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
MC/DC0%0/1
$epoch // time
$epoch
Truth table50%1/2
A
A= $epoch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 720 | 27 | ▶ | my ($stem, $ext) = $base =~ /\A(.+)(\.[^.]+)\z/ ? ($1, $2) : ($base, ''); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 828 | 27 | $id =~ s/[^A-Za-z0-9._-]+/_/g; | |||||||||||||||||||||||||||||||||||||||||
| 829 | 27 | ▶ | $id = $UNKNOWN_CLIENT unless length $id; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 836 | 27 | ▶ | $stem = substr($stem, 0, $room) if length($stem) > $room; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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__ | ||||||||||||||||||||||||||||||||||||||||||