Proofread POD

Convert section heading comments to POD section headings

This commit also removes some leftover comments.

Update internal documentation to reflect improvements

Add checks to avoid removing backup files in scan_incoming

Also update internal documentation and adjust testsuite to properly cover
the new edge case.

Revise calls to ftp_syslog

The ftp_syslog procedure now requires exactly two arguments and all calls
have been changed to use Perl's fat comma and its implicit quoting for the
syslog severity keywords.

Add POD block for ftp_syslog

Rename local variable in ftp_syslog

This change of terms aligns with RFC3164.

Fixup oversights in recent commits

Rename ftp_abort to abort

Explain intended use of ftp_abort

Reindent ftp_abort

Revise calls to ftp_abort

Since ftp_abort is used as an alternative to the die builtin for certain
severe errors, the calls are regularized to omit parentheses.

Revise some abort messages

These are minor changes for consistency and to report errors.

Revise ftp_abort and add POD block

The second argument is no longer used and is redundant with the
$AbortExitCode global variable, so it is removed.

Add POD block for report_upload_to_archive procedure

Remove quasi-global %info hash

Revise mail to remove use of quasi-global %info hash

Revise reporting of replaced files

Fix message describing replacement of a file

This message is written to the log before the file has even been moved to
the staging directory, therefore it should not be past tense.

Add detail when reporting inability to exec GPG

Improve reporting of overwrites when installing files

The reported name is now the logical name in the published tree instead of
the actual name on the server's filesystem.

Rename debug procedure to reflect its actual usage and simplify call

Tidy configured email address

Rename variables holding email addresses to better describe their uses

Merge success_upload and success_directive into top-level

Move all collection of email addresses to top-level

The 'email' and 'package' keys in the quasi-global %info hash remain as
implicit arguments to mail for the time being.

Add target directory to directive_syntax exceptions

This will allow the exception handling to easily look up the email
addresses that are to be notified, since a directive_syntax exception can
be thrown before the normal processing collects this information.

Remove directive text parameter to interpret_directive

Improve error handling when running gpgv

This commit harmonizes the exit status used when the child process fails
to exec gpgv with that used by posix_spawn, and ensures that the child
process is reaped when the exec fails.

Rename validate_commands to validate_directive

A new validate_commands procedure is planned that runs during VL phase.

Fix error message for future signature timestamp

Add test for rejection of uploaded file with future timestamp

Factor signature timestamp validation out of check_replay

The main code now also checks the signature timestamp on an uploaded file;
previously this was not checked at all.

Fix search/replace error

Add checks that the rename builtin works as expected

The tool assumes that the Perl rename builtin can atomically move files
from the inbox to the scratchpad directory and among the staging, public,
and archive directories.  This commit extends the configuration checks
to confirm that the system can actually move files as expected.

Change storage of other mode flags to constants

This eliminates the global variables previously used to indicate if the
--help and/or --version flags had been specified and allows the relevant
conditionals to be resolved during the compilation phase.

Change current zone from a global variable to a constant

Only one zone is processed on each run of the tool, and the zone does not
change after the command arguments are parsed, so this is appropriate.

Change terminology:  "style" is now "zone"

The zone definitions will eventually be sections in a configuration file,
instead of being hardwired in the tool.  Backwards compatibility at the
command line for the old short option (which was used at the GNU FTP site)
has been preserved for now, although this support is undocumented and
therefore deprecated.

Simplify return sequence in signature verification

Factor out similar code for spawning gpgv subprocess

Rename automake_tests to check_automake_vulnerabilities and simplify

This also moves the checks for known GNU Automake CVE issues to the
top-level, and eliminates the now-otherwise-useless check_vulnerabilities
and check_files procedures.  The major impetus for this simplification
of the call graph was the observation that check_vulnerabilities, while
named generically, was associated with a log message citing specifically
CVE-2009-4029 and CVE-2012-3386, combined with noticing that all other
functionality had been factored out of check_files.

Factor uploaded file signature check up to top-level

Use new detached signature verification

Add verify_detached_signature

Factor analysis out of verify_clearsigned_message

This is in preparation for also using --status-fd when verifying detached
signatures for uploaded files.

Add check for scalar context in find_directive_elements

This avoids building a list when the only important detail is whether a key
is present in the directive.

Add check for existence when removing a symlink

While the later check to verify that the symlink to be removed actually is
a symlink will also fail if no such file exists, this produces a message
that confusingly reports a refusal to remove a non-symlink file.

Remove use of Cwd module

Since all file manipulations now use absolute file names, there is no
longer any need to query the current working directory.

Remove use of chdir

All file manipulations now use absolute file names.

Use File::Spec when reading directive file at top-level

Use File::Spec in success_upload and success_directive

Revise and document cleanup_dir and cleanup

Remove leftover variable in execute_commands

Tidy comment left when removing fatal

Revise exception handling

The directive processed is now still emailed if a simple exception
terminates processing a packet.  Previously, the directive text was only
emailed during normal processing or if a structured exception was thrown.

Remove fatal

The uses of fatal have been entirely converted to simple and structured
exceptions, allowing the gatekeeper to continue processing after a bad
upload is encountered.

Normalize simple exception messages

Remove remaining calls to fatal

These reflect system errors and are replaced with simple exceptions.

Use structured exception to report an unsigned directive

Use structured exceptions in execute_commands

Fix incorrect error messages for empty directives

Revise install_files

 - eliminate unneeded intermediate variable
 - add separate variable for external public file name
 - adjust layout
 - replace call to fatal with structured exception

The message produced for an existing file is changed and shortened;
the testsuite is adjusted accordingly.

Rearrange comment to match pattern

Use new mkdir_p helper in install_files

Instead of using File::Path or invokgin the system mkdir, we now emulate
"mkdir -p" using about 5 lines of Perl elsewhere in the script.

Tidy split line that now fits on one line

Fix example given in comment

Revise archive procedure in gatekeeper

 - a structured exception for general processing errors is added
 - the archive sub is renamed to archive_filepair
 - a file and its detached signature are now archived together
 - the archived filename now contains an extra number beyond the timestamp
   only if actually needed for uniqueness
   - the extra number, if used, matches between a file and its signature
   - the archived filename is claimed by creating an "archive stamp" file
 - the option to archive and overwrite a file using "replace" now handles
   the file and its signature as a pair
 - the system mkdir(1) and mv(1) commands are no longer invoked here
 - the testsuite is adjusted accordingly

Add helper procedure implementing "mkdir -p" in Perl

Use File::Spec for symlink operations

Use structured exceptions for empty directive

Add structured exception for GPG signature verification errors

This commit also adjusts check_files to use the package configuration
exception at the check for a lack of keyrings and tidies the syntax for a
similar check at top-level.

Add structured exception for known Automake vulnerabilities

Add structured exception for invalid signature timestamp

Add structured exception for filename mismatch

This commit also changes the exception handling for exceptions carrying
long-form messages, instead of continuing to list their types individually
and removes testsuite support for a long-obsolete log message that could
never actually be produced.

Add structured exception for directive replay

Add structured exception for unknown package error and move email check

The check for a missing per-package email list had to be moved to
validate_commands to allow the unknown package exception to be thrown.

This now makes the server misconfiguration scenario of a missing email
list distinguishable from the user error scenario of an unknown package.
The testsuite is adjusted accordingly.

Add structured exception for package configuration errors

Factor directory_package_name out of directory_email_addresses

Move check for missing "directory" element to interpret_directive

This is now considered a directive syntax error and detected earlier;
the testsuite is adjusted accordingly.

Send the summary for a structured exception to syslog

Add structured exception for directive syntax errors

This also improves the reporting of these errors, with a highlight line
inserted for each error encountered, in context.

Add initial structured exception infrastructure

Revise fatal to throw an exception and move report phase accordingly

This is an intermediate step towards collecting reporting at top-level.

This commit also enables the cleanup processing that has long been present,
but was skipped due to fatal calling exit instead of throwing an exception.
The testsuite is adjusted accordingly.

Add final section dividers to older testsuite files

Fix oversight in find_directory

An empty "directory" element would cause a warning from perl due to the
first element in the @values array being undefined.

Rename configurable directory variables and convert them to globals

Uploads arrive in Inbox_dir and are atomically transferred to Scratch_dir
for processing.  Uploaded files to be published are copied to Stage_dir
and atomically transferred to locations underneath Public_dir, while files
withdrawn from publication are atomically transferred to locations
underneath Archive_dir.  The new variable names better describe the
purposes of these directories.

These variables are also converted from file-scope lexicals to true global
variables, with access scoped lexically using Perl's "our" feature.

Remove testsuite logic that supported optional processing phase tags

All relevant messages now have phase tags in all cases.

Add processing phase tag "PV" for directive parsing and validation phase

Add processing phase tag "AA" for authentication/authorization phase

Add processing phase tag "EX" for execution phase

Add processing phase tag "RP" for report phase

Add processing phase tag "SC" for scan phase

Add infrastructure to support logging current processing phase

This also collects the definition of $Log_Style to the Logging group in
preparation for future documentation improvements.

Replace ftp_warn with general warning handler in gatekeeper

This also sends any warnings generated by perl itself to syslog, which
will cause random test failures with the current testsuite, thus ensuring
that all such warnings will be fixed.

Fix use of uninitialized values in interpret_directive

Move test for missing version to interpret_directive

This changes the handling for this type of invalid directive.  These are
no longer sent to the ftp-upload-report address, but instead go only to
the ftp-upload-script box.  The testsuite is adjusted accordingly.

Regularize mail sent by debug as compared to mail sent by mail

Factor SMTP client out of mail and debug

Fix bug in find_directory

Contrary to documentation, the return value was tainted.

Remove useless check of operation list

The interpret_directive function either returns an operation list or
throws an exception, so testing the returned value is silly.  This code
had been carried over from previous refactoring when the return value of
read_directive_file was changed to an operation list; it had been a flag
nominally, but was actually a constant in read_directive_file.