File Coverage

=head1 NAME

App::FileSync::Settings - process-wide settings and logging for App::FileSync

=head1 SYNOPSIS

        use App::FileSync::Settings;

        my $logger = App::FileSync::Settings::logger(verbose => 1);
        $logger->error('...');

        my $settings = App::FileSync::Settings::load();
        my $level = $settings->{log_level};

        my $report = App::FileSync::Settings::explain();
        printf "%s = %s (%s)\n", $_->{key}, $_->{value}, $_->{label}
                for @{ $report->{settings} };

=head1 DESCRIPTION

Settings that apply to the process rather than to one repo - the log level,
format and destination, plus the SSH identity, known-hosts file and remote
server command - are read through L<Object::Configure>.  The repos themselves
remain in F<~/.filesync/config.json>, which C<filesync init> writes; this
module does not replace that store.

The settings file is F<~/.conf/app-filesync.json> when it exists, or the path in
C<FILESYNC_SETTINGS>.  The section key is C<App__FileSync>, and a C<UNIVERSAL>
section in the same directory applies to every class that uses
Object::Configure.  Environment variables named C<App__FileSync__I<key>>
override the file:

        # ~/.conf/app-filesync.json
        { "App__FileSync": { "log_level": "debug", "log_format": "%level%: %message%" } }

        # or
        export App__FileSync__log_level=debug

C<log_file> sends the log to a file instead of standard error; leading
directories are created.  C<log_format> is a L<Log::Abstraction> format string.

C<ssh_identity>, C<ssh_known_hosts> and C<server_command> are the defaults for
every SSH repo, so a per-repo C<identity>, C<known_hosts> or C<server_command>
(written by C<filesync init --identity> and friends) only has to be set when it
differs.  C<server_command> defaults to C<filesync-server>:

        { "App__FileSync": {
                "ssh_identity"    : "~/.ssh/filesync_ed25519",
                "ssh_known_hosts" : "~/.ssh/filesync_known_hosts",
                "server_command"  : "/usr/local/bin/filesync-server"
        } }

Command output (sync summaries, plans, C<--json>) is written to standard output
by the commands themselves; the logger carries diagnostics on standard error,
so a cron job can separate the two.  C<--verbose> raises the level to C<debug>
and C<--quiet> lowers it to C<error> for that run, overriding the file.

C<wants_plain_end_of_scope_hook> and C<use_plain_end_of_scope_hook> are aliases
of the functions in L<App::FileSync::Platform>, kept for existing callers.

=head1 FUNCTIONS

=head2 config_file

Purpose: the settings file that would be used.

Args: an optional explicit path.

Returns: the explicit path when one is given; otherwise C<FILESYNC_SETTINGS> or
F<~/.conf/app-filesync.json> if that file exists; otherwise C<undef>.

Side Effects: none.

Usage:

        my $file = App::FileSync::Settings::config_file();

=head3 EXAMPLE

        my $file = App::FileSync::Settings::config_file() // 'none';
        print "settings: $file\n";

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'given', type => 'string', optional => 1 } ]

=head4 OUTPUT

        { type => 'string', optional => 1 }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        config_file(g) = g                     if g ≠ ""
        config_file(g) = d                     if d = default_path ∧ d ∈ dom FS
        config_file(g) = ⊥                     otherwise

=cut

=head2 load

Purpose: the merged process settings.

Args: optional C<config_file> and C<config_dirs> (as for
L<Object::Configure/configure>).

Returns: a hashref with every key in C<@SETTING_KEYS>, built-in defaults
overlaid by the settings file, the C<UNIVERSAL> section and C<App__FileSync__*>
environment variables.

Side Effects: reads the settings file.  Dies (through Object::Configure) when
an explicit file does not exist.

Usage:

        my $settings = App::FileSync::Settings::load(config_file => $path);

=head3 EXAMPLE

        print App::FileSync::Settings::load()->{log_level}, "\n";  # warning

=head3 API SPECIFICATION

=head4 INPUT

        {
                config_file => { type => 'string', optional => 1 },
                config_dirs => { type => 'arrayref', optional => 1 },
        }

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key            Meaning                         Resolution
        args.invalid   an argument has the wrong type  fix the call

Object::Configure's own error for a missing explicit file is passed through.

=head3 FORMAL SPECIFICATION

        load(a) = defaults ⊕ file(config_file(a)) ⊕ universal ⊕ env

=cut

=head2 explain

Purpose: where each effective setting came from, for C<filesync settings>.

Args: as L</load>.

Returns: C<{ settings_file =E<gt> $path_or_undef, settings =E<gt> \@rows }>, one
row per key in C<@SETTING_KEYS>.  Each row has the effective C<value>, a
C<source> of C<default>, C<file>, C<env> or C<merged>, and a human-readable
C<label> naming the file section, environment variable or built-in default
that supplied it.

The values are whatever L</load> returns; the provenance is reconstructed from
the same layers Object::Configure merges.  A value no modelled layer accounts
for (a C<global> section, say) is reported as C<merged> rather than claimed as
a default.

Side Effects: reads the settings file and any universal file beside it.

Usage:

        my $report = App::FileSync::Settings::explain();

=head3 EXAMPLE

        for my $row (@{ App::FileSync::Settings::explain()->{settings} }) {
                printf "%-16s %-20s %s\n", $row->{key}, $row->{value}, $row->{label};
        }

=head3 API SPECIFICATION

=head4 INPUT

        {
                config_file => { type => 'string', optional => 1 },
                config_dirs => { type => 'arrayref', optional => 1 },
        }

=head4 OUTPUT

        {
                type => 'hashref',
                schema => {
                        settings_file => { type => 'string', optional => 1 },
                        settings      => { type => 'arrayref' },
                },
        }

=head3 MESSAGES

As L</load>.

=head3 FORMAL SPECIFICATION

        âˆ€ k : SETTING_KEYS •
                row(k).value = load()(k)
                row(k).source = last layer ∈ ⟨default, universal, class⟩ that sets k,
                                or merged if that layer's value ≠ row(k).value

=head3 PSEUDOCODE

        load the settings
        explain the class and universal sections of the settings file, if any
        for each key:
                start from the built-in default
                let the universal section, then the class section, override it
                without a file, let UNIVERSAL__key then App__FileSync__key override it
                if the loaded value differs from the winner, call it merged

=cut

=head2 explain_repos

Purpose: how the SSH settings resolve for every repo in a client config.

Args: C<config> (the hashref from C<App::FileSync::Config::load_client>),
C<report> (the result of L</explain>), C<config_file> (the client config path,
used in labels).

Returns: an arrayref, one entry per repo in name order, with C<repo>,
C<transport>, C<server> (when the repo records one) and C<ssh>: one
C<{key, value, source, label}> row per setting, where C<source> is C<repo>
(the repo's own entry), C<process> (the settings reported by C<explain>) or
C<default> (ssh's own default).  C<port> and C<host_key_checking> rows carry
C<repo_only =E<gt> 1>.  C<ssh> is C<undef> for the local transport, which never
runs ssh.

Side Effects: none.

Usage:

        my $repos = App::FileSync::Settings::explain_repos(
                config => $config, report => App::FileSync::Settings::explain(), config_file => $path,
        );

=head3 EXAMPLE

        for my $repo (@{ $repos }) {
                next unless $repo->{ssh};
                print "$repo->{repo}: $_->{key} = $_->{value} ($_->{label})\n" for @{ $repo->{ssh} };
        }

=head3 API SPECIFICATION

=head4 INPUT

        {
                config      => { type => 'hashref', optional => 1 },
                report      => { type => 'hashref', optional => 1 },
                config_file => { type => 'string', optional => 1 },
        }

=head4 OUTPUT

        { type => 'arrayref' }

=head3 MESSAGES

        Key            Meaning                         Resolution
        args.invalid   an argument has the wrong type  fix the call

=head3 FORMAL SPECIFICATION

        âˆ€ r : dom config.repos • ∀ k : REPO_SSH_SETTINGS •
                value(r, k) = repo(r)(k)       if repo(r)(k) ≠ ""
                            = process(k)       else if process(k) ≠ ""
                            = ""               otherwise

=head3 PSEUDOCODE

        for each repo, by name:
                record its transport and server
                if it uses ssh:
                        for each SSH setting take the repo's value, else the process
                        setting, else ssh's default
                        add the repo-only port and host-key-checking rows

=cut

=head2 logger

Purpose: the diagnostics logger for this run.

Args: as L</load>, plus C<level> (overrides the settings), C<verbose> (debug)
and C<quiet> (errors only).  A command-line flag describes this run, so it
beats the settings file.

Returns: a L<Log::Abstraction> writing to standard error, or to C<log_file>.

Side Effects: reads the settings; creates C<log_file>'s directory.

Usage:

        my $logger = App::FileSync::Settings::logger(verbose => $opts{verbose});

=head3 EXAMPLE

        my $logger = App::FileSync::Settings::logger(level => 'info');
        $logger->info('starting');

=head3 API SPECIFICATION

=head4 INPUT

        {
                config_file => { type => 'string', optional => 1 },
                config_dirs => { type => 'arrayref', optional => 1 },
                level       => { type => 'string', optional => 1 },
                verbose     => { type => 'boolean', optional => 1 },
                quiet       => { type => 'boolean', optional => 1 },
        }

=head4 OUTPUT

        { type => 'object', isa => 'Log::Abstraction' }

=head3 MESSAGES

        Key                   Meaning                         Resolution
        settings.bad_level    log_level is not a known level  use one of @VALID_LEVELS
        io.mkdir              log_file's directory cannot be made  fix log_file

=head3 FORMAL SPECIFICATION

        level = debug                      if verbose
              = error                      else if quiet
              = args.level                 else if set
              = settings.log_level         else if set
              = warning                    otherwise
        pre lc level ∈ lc VALID_LEVELS

=head3 PSEUDOCODE

        load the settings
        choose the level: argument, then settings, then the default
        reject an unknown level
        send output to log_file (creating its directory) or standard error
        build the logger; apply --verbose or --quiet over it

=cut