doc: Refactor Dovecot and OfflineIMAP migration sections

Move the sections on (a) Dovecot morals and (b) migration from
OfflineIMAP from the baseline case document to separate documents.

doc: Review of the "Baseline" case

The *baseline.mdwn* documentation case is seen over by Guilhem and
Gustav. Documentation is adopted to the current *master* state and
clarified on a few items.

This case is actually not a good baseline case, since it presents the
start of a multi account setup:

TODO Title this "ACCOUNT=private" case "Prepared for multi account
setup"

doc: Add overview and multi account case placeholder

Create a placeholder for the multi account setup case. Also complete
with an overview of configuration cases.

doc: refactor rename case document

Merge branch 'master' into case-of-multi-account

`make test`: Only consider tests/*/run.

long-lived tests: sleep between 1ms and 999ms.

`shuf -n1 -i1-99` produces a number between 1 and 99, hence `sleep
"0.$(shuf -n1 -i1-99)"` pauses for some time between 100ms and 990ms.
Moreover it's not uniformly distributed as multiples of 100ms (0.100,
0.200, …, 0.900) have twice the probability of other numbers.

Improve wording.

tests/run: use the current date as Message-ID in `sample_message`.

A random 128-bit UUID obtained from /proc/sys/kernel/random/uuid works
too but is Linux-specific and requires the proc(5) pseudo-filesystem to
be mounted at /proc.

typo fixes

Net::IMAP::InterIMAP: call shutdown(2) on teardown also for type=tunnel.

Since we now use socketpair(2) for type=tunnel (instead of a pair of
unnamed pipes) we can unify communication endpoints creation and
teardown.

.gitignore update.

Add .gitignore.

typofix

tests/run: set 'mailbox_list_index = yes' in dovecot.conf.

LAYOUT=index requires mailbox_list_index = yes.  It's the default since
dovecot 2.3, but we set it explicitly to support older versions.

tests: don't fail when a pid can't be killed.

(Usually on ESRCH.)

tests/run: Don't void the command's standard error.

tests/run: Honor $TMPDIR if the variable is set.

Otherwise use /dev/shm.

typofix

Manpages: clarify that the tunnel command is run following Perl's `exec` semantics.

It is passed to `/bin/sh -c` when it contains shell metacharacters; and
split into words and passed to execvp(3) otherwise.

        https://perldoc.perl.org/functions/exec.html

(Since c8fb54897f046a5a3fb4c1d45dc21fd8bcd882e3 the value no longer
needs to stard with a forward slash.)

Add test-suite (requires dovecot-imapd).

New option 'list-reference' to specify a reference name.

This is useful for synchronizing multiple remote servers against
different namespaces belonging to the same local IMAP server (using a
different InterIMAP instance for each local namespace ↔ remote
synchronization, for instance with the newy provided systemd template
unit file).

libinterimap: use socketpair(2) in tunnel mode.

Rather than two pipe(2).  Also, use SOCK_CLOEXEC to save a fcntl() call
when setting the close-on-exec flag on the socket (even though Perl will
likely call fcntl() anyway).

interimap: fix handling of mod-sequence values greater or equal than 2 << 63.

SQLite processes every INTEGER values as a 8-byte signed integer, so we
need to manually do the conversion from/to uint64_t client-side if we
don't want to overflow or receive floats.

https://www.sqlite.org/datatype3.html#storage_classes_and_datatypes
http://jakegoulding.com/blog/2011/02/06/sqlite-64-bit-integers/

We could also do the same trick for local/remote UIDs, UIDVALITY and
UIDNEXT values to slim the database down at the expense of pre/post-
processing.  (Values of SQLite's INTEGER class are 1, 2, 3, 4, 6, or 8
bytes signed integers depending on the manitudes, so we could save some
space for values ≥2³¹.)  But that seems a little overkill.

interimap: Enforce SQLite foreign key constraints.

Setting the 'foreign_keys' PRAGMA during a multi-statement transaction
(when SQLite is not in autocommit mode) is a no-op.

https://www.sqlite.org/pragma.html#pragma_foreign_keys
https://www.sqlite.org/foreignkeys.html#fk_enable

interimap: avoid caching hierarchy delimiters forever in the database.

Following recommendation from
https://www.imapwiki.org/ClientImplementation/MailboxList#Hierarchy_separators

Instead, use null characters internally, and substitute them with the
local and remote hierarchy delimiters (which thus no longer need to
match) for IMAP commands.  This require a database schema upgrade to
alter the mailbox name column type from TEXT to BLOB.  We're using
SQLite's user_version PRAGMA to keep track of schema version; beware
that `.dump` doesn't export its value!

In logging messages, local and remote mailbox names are shown as is
(with their respective delimiters) while database mailbox names are
shown by replacing null characters with the *local* hierarchy delimiter.

Moreover for mailbox names specified on the command line or the
configuration file (with the "list-mailbox" option) the *local*
hierarchy delimiter should be used.

interimap: Refactor --target handling.

Also, accept comma-separated values for --target.

interimap: fail when two non-INBOX LIST replies return different separators.

This never happens for a single LIST command, but may happen if
mailboxes from different namespaces are being listed.  The workaround
here is to run a new interimap instance for each namespace.

interimap: accept C-style escape sequences in 'list-mailbox'.

This is useful for defining names containing control characters (incl.
\0 for unspecified hierarchy delimiter).

interimap: Factor out error throwing.

Also, write which --target to use in --delete command suggestions.

libinterimap: astring is 1*ASTRING-CHAR / string.

Not 1*ATOM-CHAR / string.  Also accept LIST responses mailbox names
containing '%', '*', or ']'.

From RFC 3501:

        astring         = 1*ASTRING-CHAR / string
        ASTRING-CHAR    = ATOM-CHAR / resp-specials
        list            = "LIST" SP mailbox SP list-mailbox
        list-mailbox    = 1*list-char / string
        list-char       = ATOM-CHAR / list-wildcards / resp-specials
        list-wildcards  = "%" / "*"
        resp-specials   = "]"

libinterimap: quote() the empty string as "" instead of a 0-length literal.

Compression asside, this saves 3 bytes and one round-trip on servers not
supporting non-synchronizing literals, and 4 bytes otherwise.

libinterimap: bugfix: fix escaped hierarchy delimiters in LIST reponses.

The were returned as escaped quoted specials, like "\\", not as a single
character (backslash in this case).

wibble

Case documentation more sections

Provide section content for

 * Portal
 * Overview
 * Dovecot morals, including namespaces and fs
 * Migrate from OfflineIMAP

Refactor case documentation structure

Case documentation configuration update

Update instructions

 * Harmonise hash for bash commands
 * Don't write "sudo" in commands
 * Correct some typos

Fripost case documentation update avoid shell in configs

Inital on Fripost case documentation

Watch out for multiple TODO's in the documentation. The setup works, but
need completion on philosophy and particularities on multi account setup

Gitignore update

Prepare new release.

Bump copyright years.

Bump version number.

Change e-mail address.

Net::IMAP::InterIMAP: add support for TLSv1.3 (on recent enough Net::SSLeay).

Also, change "SSL_protocols" default value from "!SSLv2 !SSLv3" to
"!SSLv2 !SSLv3 !TLSv1 !TLSv1.1".  I.e., only enable TLSv1.2 and later,
which is the default in Debian's OpenSSL as of 1.1.1-2, cf.
https://tracker.debian.org/news/998835/accepted-openssl-111-2-source-into-unstable/ .

pullimap, interimap: don't autocreate statefile or database in long-lived mode.

interimap.service: use --watch=60 rather than --notify.

Note on migrations.

Specify minimum Perl and Net::SSLeay versions.

pullimap, interimap: Use $XDG_CONFIG_HOME/$NAME/config as config file.

typofix

pullimap: use extended SEARCH (RFC 4731) when available

Improve ESEARCH response parsing for full RFC 4466 compatibility.

Improve wording.

typofix

Fix uninitialized value $set in quotemeta

Add support for untagged ESEARCH responses from RFC 4731.

Library: new API idle_start() and idle_stop().

Fix manpage generation with pandoc >=2.1

Add missing changelog entry.

Fix manpage generation with pandoc >=1.18.

Ensure the lower bound of UID ranges is at least 1.

Minor manpage fixes.

pullimap: replace non RFC 5321-compliant envelope sender addresses by <>.

interimap.service: s/--watch/--notify/.

Update changelog.

wibble

"fingerprint" now only pins the cert's SPKI, not the cert itself.

bugfix: when resuming a sync, only consider UIDs greater than a known UIDNEXT.

wibble

wibble

pullimap: quote the local part if need be (cf. RFC 5321).

wibble

pullimap: enable locally unsetting the 'purge-after' option.

pullimap: Clean up PATH.

pullimap: precise that the mailbox needs to be UTF-7 encoded and unquoted.

pullimap: fix struct flock packing

interimap: reformulation in manpage

interimap: Fix watch value when --watch is not set.

typo

pullimap: use fcntl(2) not flock(2) to lock the statefile.

interimap: use SQLite's own locking mechanism to lock down the database.

(instead of rolling our own)

punct

Use a monotype font for IMAP extensions.

Net::IMAP::InterIMAP, interimap: Add support for IMAP NOTIFY [RFC 5465].

Unsollicited LIST responses are currently ignored, hence interimap won't
detect mailbox creation/deletion/subcription/unsubscription.

interimap: fix memory leak.

Net::IMAP::InterIMAP: quit idling when a time jump of at least 30s is detected

This forces a write, so we can better detect detect dead peers after
hibernation for instance.

Net::IMAP::InterIMAP: set SO_{RCV,SND}TIMEO on the socket so we can detect dead peers

Net::IMAP::InterIMAP: set binmode on the socket (and our pipe ends)

Net::IMAP::InterIMAP optimisation: ignore a new message that's immediately expunged

(before we had a chance to sync it)

Net::IMAP::InterIMAP: Don't increase UIDNEXT when receiving EXISTS responses.

Indeed, if the server sends

    * n EXISTS
    * n EXPUNGE

meaning a new message is received, and is immediately removed
afterwards, the server might have allocated a new UID for the removed
message.

wibble

Explicitly specify inner links for older pandoc.

interimap: convert manpage to markdown.

pullimap: honor the the four-space rule in the markdown.

pullimap: improve manpage.

wibble

pullimap.md: Fix pandoc syntax.

Convert pullimap's manpage to pandoc.

IDLE: fix race condition when an untagged response is received after the DONE