This is derived from the environment, not the configuration file: We
might not want to trust the configuration file until we've decided
whether we like its permissions.

This includes:

  * a CachedDir::join method.
  * functions to read and write from provided filenames in a
    CachedDir.
  * a method to tell whether a fs-mistrust error is about bad file
    permissions, or failure to inspect file permissions or some other
    kind of IO problem.

The environment where the test runner does its thing seems to want
to run as root with umask 000, which naturally makes the fs
permissions checks freak out.

Make config builders, not validated structs, [de]serialize

See merge request tpo/core/arti!487

 * Builders additionally derive: Debug, Serialize, Deserialize.

 * Validated structs no longer derive: Serialize, Deserialize
   and all related attributes deleted.

 * As a consequence, all the `#[serde(deny_unknown_fields)]`
   are gone.  That means that right now unknown fields are totally
   ignored.  This is good for compatibility but poor for useability.
   Doing something better here is #417, in progress.

 * As a consequence, delete tor_dirmgr::retry::default_parallelism.
   (The default value was already duplicated into a builder attr.)

Having a consistent order will make the nest commit easier to read.

We want to be able to serialise as well as deserialise configurations.

FallbackDir: orports: Introduce and use VecBuilder

See merge request tpo/core/arti!474

Apropos
  tpo/core/arti!474 (comment 2800481)

GuardUsage: restrictions: Use list builder

See merge request tpo/core/arti!475

And drop the ad-hoc orport() method.  This brings FallbackDir's
orports field in line with our list builder API.

The general semver note in "configuation" seems to cover most of this.

This avoids it having to recapitulate defaulting logic.

This is for lists of plain types (non-builder types).

This allows us to use this with an item builder type which doesn't
impl Default.  (Obviously this only makes sense for items which aren't
actually builders.)

It is Quite Vexing that we have to use [ ] rather than the < > around
the generics, particularly given that we are also using [ ] to signal
"this is arrayish".

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

The docs were a lie.  $docs_and_attrs was missing from the expander.

And add a note about how any supplied docs are handled.

CI: Check that the lockfile is up to date.

See merge request tpo/core/arti!484

Although these do not appear in the config, it does have a builder.
It seems sensible to get rid of this ad-hoc list manipulation site,
and replace it with our standard list builder API.

define_list_builder_helper requires that the builder element type be
Deserialize.  Currently GuardUsageRestriction is a transparent, public
enum, so we aren't really exposing anything.

We could introduce GuardUsageRestrictionBuilder now, but
since it's not in the config and thereofore only in the public API of
the lower crates, we can definitely put that off.

Replace list builder API and do not expose ThingListBuilder as part of config API

See merge request !481

For at least one job, run the first cargo run with --locked.  This
will fail if the lockfile needs updating.

I have verified that this correctly detects this situation:
  https://gitlab.torproject.org/Diziet/arti/-/pipelines/37692
failed.  Now I have rebased this branch onto main to get the fix to
Cargo.lock.

Fix config version

See merge request tpo/core/arti!482

This type was returned by the public DownloadSchedule::builder
function.  But the only thing that seems to have noticed that the type
name itself wasn't exported, was rustdoc.  Hmmm.

The new API is (roughly) as discussed in
  #451

This is quite a large commit and it is not convenient to split it up.
It contains the following changes:

 * Redo the list builder and accessor macros implemnetation,
   including docs and tests.

 * Change uses of define_list_config_builder.  In each case:
   - Move the docs about the default value to the containing field.
   - Remove the other docs (which were just recapitulations, and
     are now not needed since the ListBuilder is no longer public).
   - Rewmove or replace `pub` in the define_list_builder_helper call,
     so that the builder is no longer public.
   - Change the main macro call site to use define_list_builder_helper.
   - Add a call to define_list_builder_accessors.

 * Make the module `list_builder` pub so that we have somewhere to
   put the overview documentation.

 * Consequential changes:
   - Change `outer.inner().replace(X)` to `outer.set_inner(X)`
   - Consequential changes to imports (`use` statements).

This removes a caveat from the API and will be convenient for what is
coming.

The list accessor macro is going to want this.

Previously this field was differently named to its serde and to its
accessors.  We are about to introduce a macro_rules macro which will
provide list accessors and we don't want that macro to have a field
renaming feature.

So stop renaming the field.