feat: Add statistics for direct/preprocessed cache miss

test: Use machine-parsable statistics IDs in tests

refactor(test): Improve duplicate tests in base suite

feat: Sort output of --print-stats

enhance: Prepare for a ccache invocation having multiple results

That is, “result” as in “increased statistics counter”.

fix: Remove obsolete statistics counter and comment when disabled

refactor: Improve handling of statistics updates and expected events

Ccache uses exceptions for both truly exceptional events (such as I/O
error) and non-exceptional events (such as unsupported compiler
arguments). Regardless of the nature of the event, at most one
statistics counter can be incremented.

Improve this by:

- Using nonstd::expected instead of exceptions internally in the main
  code flow. This makes the code easier to reason about.
- Adding support for communicating several statistics counter updates
  both for success and failure code paths. This is in preparation for
  future improvements of statistics related to secondary storage.

chore: Fix example in dockerfiles/README

docs: Use non-legacy markup for block IDs

feat(file-storage): Add support for flat layout

feat(http-storage): Add support for subdirs layout, making it default

enhance(test): Let http-server create subdirectories as needed

fix(test): Remove debug printout and move Bazel layout test

fix: Don’t read let Context read user configuration in unit tests

accd21e4 inadvertently made unit tests populate Context::config from the
environment and the user configuration. Fix this by moving code for
reading config, setting of logging, etc. into a separate method only to
be called by non-test code.

As noted by Michael Kruse in #815.

feat(storage): Add support for cache sharding on secondary storage (#912)

This adds support for a shards attribute with a comma-separated list of
names for sharding (partitioning) the cache entries using Rendezvous
hashing, typically to spread the cache over a server cluster. When set,
the storage URL must contain an asterisk (*), which will be replaced by
one of the shard names to form a real URL. A shard name can optionally
have an appended weight within parentheses to indicate how much of the
key space should be associated with that shard. A shard with weight w
will contain w/S of the cache, where S is the sum of all shard weights.
A weight could for instance be set to represent the available memory for
a memory cache on a specific server. The default weight is 1.

For example,

    redis://cache-*.example.com|shards=a(3),b(1),c(1.5)

will put 55% (3/5.5) of the cache on redis://cache-a.example.com, 18%
(1/5.5) on redis://cache-b.example.com and 27% (1.5/5.5) on
redis://cache-c.example.com.

chore: Sort LICENSE.adoc entries

chore: Improve AsciiDoc markup of LICENSE.adoc

ci: Use latest codespell

chore: Fix typos

refactor: Split httplib into .h and .cpp parts

This improves recompilation speed of
src/storage/secondary/HttpStorage.cpp.

fix(file-storage): Create CACHEDIR.TAG after subdir

Otherwise creation will fail the first time with an ugly log message.

refactor: Use util::parse_double

enhance(util): Add parse_double function

chore: Fix typo in comment

enhance(util): Add replace_first function

docs: Use italics consistently for references to sections

feat(storage): Log time taken for secondary storage operations

feat(http-storage): Log translation to pseudo-SHA256 key

docs: Add scheme to link to fonts.googleapis.com (#910)

This makes it possible to view generated HTML files locally using the file scheme.

docs: Reflow some paragraphs after #911

docs: Fix links to section anchors (#911)

asciidoc uses #_section_header, but github uses #section-header.
Replace all the explicit refs with the section titles, and let
the engine handle it.

build: Only probe for faster linker in dev build mode and on x86_64

Using Gold or LLD on less common platforms such as MIPS may not be a
good idea (see e.g.
<https://www.sourceware.org/bugzilla/show_bug.cgi?id=22838>), so be
conservative and only probe for a faster linker on platforms that likely
don’t have toolchain bugs. Also, using a faster linker is in practice
only relevant for dev builds.

Fixes #907.

build: Allow overriding CCACHE_DEV_MODE on command line

fix: Disable preprocessor hits for PCHs with Clang again (#909)

I added this in 3ec58dbcaa1e7903d59dce4c77baff7bc3783269 as I thought
clang only saves the timestamps of included files, so as long as they
are turned off by -Xclang -fno-pch-timestamp, preprocessed hits should be
possible. However, clang also saves the size and possibly a hash of the
un-preprocessed source file, so preprocessed hits don't make much sense.

As long as only the timestamp of a PCH source file changed, e.g. through
git operations, there should still be direct hits.

build: Improve message when pkg-config can’t find libhiredis

pkg_check_modules stops immediately when given the REQUIRED argument so
the nicer error message won’t be reached. Fix this by simply removing
REQUIRED since that will make the configuration step fail in a better
way.

refactor: Only include zstd.h in ZstdCompressor.cpp

This avoids exposing zstd internals to those including
compression/ZstdCompressor.h.

build: Remove “_lib” suffix from ccache_lib and third_party_lib

This means that libthird_party_lib.a will become libthird_party.a which
removes repetition of “lib”. ccache_lib can’t be renamed to just ccache
since that’s the name of the main binary, so that’s renamed to
ccache_framework.

fix(storage): Reuse existing backend instances

docs: Add references to how-to guides hosted on ccache.dev

docs: Enable AsciiDoc admonition icons

docs: Add styling of AsciiDoc documents similar to the ccache.dev site

docs: Add blank lines before headings

This makes it consistent for all headings

docs(http-storage): Convert note on HTTPS not being implemented to a AsciiDoc note

feat(http-storage): Add support for the Bazel HTTP caching protocol

fix(test): Flush stdout/stderr on http-server termination

The log from http-server is lost when the process is killed. Fix this by
flushing explicitly in a signal handler.

style: Format Python code with Black

bump: Upgrade to BLAKE3 1.0.0

chore: Add hints about using conventional commits for commit messages

Use Asciidoctor instead of Asciidoc to render documentation

Asciidoctor seems to:

- Provide a nice left-hand side table of contents.
- Have nicer looking defaults.
- Be faster.
- Have less (but non-zero) quirks.

Don’t use ssize_t

It’s not portable to Windows.

Add Redis support for Windows

Add support for downloading hiredis from Internet

Use cpp-httplib 0.9.2 (#905)

Update manual after layout change of compression statistics

Document that CMake 3.10 now is needed

Use auto to simplify lambda expressions

Drop support for compiling ccache with buggy GCC 5

GCC 5 may crash when compiling C++14 generic lambdas:
<https://gcc.gnu.org/bugzilla/show_bug.cgi?id=69977>

Use util::TextTable for compression statistics

Add TextTable class

Refactor main option processing to a separate file

Set umask when creating configuration file

This opens up for not having to initialize Context before calling
Config::set_value_in_file.

Explicitly default use_syslog to false for clarity

Refactor printing of compression statistics

Convert primary storage to a public member of storage::Storage

Move/split statistics functionality into core and storage::primary

- The Counters class has been moved to core::StatisticsCounters.
- Functionality in the Statistics namespace has been split into:
    - core::StatsLog: Knows about “stats log” format.
    - core::Statistics: Knows about properties of statistics fields and
      how to present them.
    - storage::primary::PrimaryStorage: Knows how to store and update
      statistics in the primary storage backend.
    - storage::primary::StatsFile: Knows about the “stats file” format.

Move Statistic to core

Convert Sloppiness enum to type-safe class

Move code for cleanup, compressing and similar to storage/primary

Rename storage::CacheEntryWriter to EntryWriter

Move compression classes to compression directory/namespace

Convert nonstd::string_view to std::string using constructor

to_string doesn’t exist in the std::string_view form, so use the
std::string constructor to make a future conversion to newer C++
versions easier.

Tweak language

Unix systems use the name “symbolic link” or “symlink”, not “soft link”.

test: Use test_failed_internal in inode_cache suite

Using test_failed_internal makes line numbers in reported failures
correct.

Move exceptions.hpp to core

Derive ccache featues from storage registry (#903)

HTTP storage: Fix crash when not specifying port

Url::port(const std::string&) apparently doesn’t accept an empty string
as the port (even though Url::port() can return an empty string), so
work around that.

Move Util::get_path_in_cache to PrimaryStorage

PrimaryStorage is now the sole user of get_path_in_cache.

Store secondary storage hits in primary storage

Improve secondary storage framework

- Let the secondary storage framework create backend instances on demand and
  track their failure state - the framework will stop calling a backend after a
  connection error/timeout. This makes it possible for a backend to create a
  connection in the constructor if wanted.
- Added API and implementation for redacting secrets in secondary storage URLs
  and attributes. Passwords in URLs are now redacted in debug logs but not for
  "ccache -p" and "ccache -k secondary_storage".
- Adapted existing storage backends to the new APIs. In particular, the Redis
  backend could be simplified.
- Moved the SecondaryStorage class to src/storage/secondary, analogous to
  PrimaryStorage which is in src/storage/primary.

doc: Mention file URLs without double slash

Remove redundant _utils suffix for util headers

Add util::join function

Split util headers into interface and implementation sections

Move parse_signed and parse_unsigned to util

Add util::value_or_throw function

Move starts_with and ends_with to util

Move strip_whitespace to util

Sort Config::set_* methods

Use std::this_thread::sleep_for instead of usleep

For portability.

HTTP storage: Fix IPv6 address handling (#898)

Fix test-all-systems (#901)

Expose list of enabled features (#897)

HTTP storage: Implement timeout support (#896)

Closes #888.

HTTP storage: Implement authentication support (#895)

Closes #887.

Add CII Best Practices badge

Mention that test cases are preferred for contributed code

Only run redis test if backend is enabled (#891)

Add test for Redis storage with password

Remove read-only tests of HTTP and Redis storage backends

The “read-only” tests in secondary_http and secondary_redis were
inspired by the “read-only” test in secondary_file. However, that test
actually verifies the secondary storage *framework*, not the storage
backend itself, so it’s enough to just do it in secondary_file.

Make secondary_http and secondary_redis tests independent

Instead of starting an HTTP or Redis server that lives for the duration
of the test suite, start a new one for each test case. This makes tests
more independent and also opens up for future testing of e.g. different
ports and authentication modes by allowing different server
configurations for each test case.