doc: glossary: add information for dates and timestamps

These have been confusing to me in the past, too.

doc: start glossary for overlapping concepts

This is intended to keep track of concepts with different terms
between NNTP, IMAP, config file, lei storage, and upcoming
JMAP support.

lei import: skip trashed Maildir messages

This matches IMAP behavior in NetReader in skipping \\Deleted
messages.  Since lei may be used for personal, non-public mail;
Draft messages are NOT skipped by "lei import".

lei import: simplify Maildir handling

Having a one-off Maildir functionality in LeiStore doesn't seem
worth the maintenance burden, especially given an upcoming
change to skip trashed messages.

I expect this will hurt performance slightly with extra IPC
overhead for the socket copy, but "lei import" may eventually
become rare or at least not hit messages redundantly.

watch: IMAP: ignore \Deleted and \Draft messages

This matches existing Maildir behavior, as trash and draft
messages have little reason to be exposed publicly.

doc: technical/data_structures: update for EOFpipe

ParentPipe no longer exists and was replaced by the more
flexible EOFpipe.

lei q: remove angle brackets around Message-IDs

They're unnecessary visual noise, and angle brackets don't
always work as intended when going through Xapian's query
parser.

Since we already use "m:" and "refs:" instead of the actual
header names, it should be obvious we're at liberty to
abbreviate such things

Link: https://public-inbox.org/meta/20210304184348.GA19350@dcvr/

lei q: one -t shouldn't set `flagged' on external mail

We only want to set `flagged' if a user requests it via
a two '-t' switches.

Fixes: 232f8e376fe2856c ("lei q: -tt marks direct hits as flagged")

lei q: fix --import-before default and FIFO output

commit 6c551bffd75afb41d9b5e4774068abe7e06ed0e7
("lei q: --import-augment for mbox and mbox.gz") added a check to
in _pre_augment_mbox for the option being a ref() to distinguish
between default values and user-supplied values (which are
non-ref SCALARs from Getopt::Long).

However, LeiQuery failed to use a SCALAR ref as the default
value, making the check in _pre_augment_mbox useless.  We
now update LeiQuery to use \1 instead of 1 as the default
value so "lei q -f mboxrd ..." to stdout works once again.

Unfortunately, testing with redirects pointed to regular
files didn't trigger the code paths being updated.  Testing
with a FIFO revealed further bugs in the FIFO handling code
which are also fixed in this commit.

We'll also update the $lei->out error message to be
less-specific about "stdout" and use the term "output", instead,
since LeiToMail replaces stdout for all mbox outputs.

search: use "z:" instead of "bytes:" prefix

So far, searching by size has never been publicly documented,
and IMHO, of questionable utility.  In any case, "z:" is what
mairix(1) uses, so it may be familiar to existing mairix users
(I've never used this prefix myself).

So far, this prefix is only used internally in tests and in
auto-translated queries from IMAP; thus this incompatible change
is unlikely to affect anyone.

lei q: s/import-augment/import-before/g

Since this importing of keywords is active even when --augment
isn't specified, calling it --import-before seems more
appropriate.

In the future, this will likely default to adding unseen emails
to lei/store, not just updating keywords.

Link: https://public-inbox.org/meta/20210303222930.GA18597@dcvr/T/

t/lei_to_mail: no need to cat in FIFO test

We're not forking, here, so there's no need to rely on FD_CLOEXEC
to resolve deadlock issues.

lei q: --import-augment for mbox and mbox.gz

The trickiest output formats we support due to the possibility
of filesystem FIFOS and pipes for <gzip|xz|bzip2>.

This completes another phase of keyword sync support.

lei_xsearch: cleanup {pkt_op_p} on exceptions

We must ensure pkt_op_p doesn't live beyond the scope of
->do_query in the top-level lei-daemon, otherwise it can leave a
stray socket hanging around in case of exceptions.

lei: dclose: do not EPOLL_CTL_DEL w/o event_init

It's possible we'll hit a die() statement which triggers
lei->dclose, but aren't in the event loop, yet.

lei q: support --import-augment for IMAP

IMAP is similar to Maildir and we can now preserve keyword
updates done on IMAP folders.

lei q: import flags when clobbering/augmenting Maildirs

This will eventually be supported for other mail stores,
but Maildir is the easiest to test and support, here.

This lets us avoid a situation where flag changes get
lost between search results.

lei: use maildir_each_eml in more places

This saves us some code and redundant callsites for
eml_from_path.  We'll change maildir_each_eml to include the
filename to facilitate an upcoming change to "lei q" without
--augment

lei_xsearch: add_eml for remote mboxrd, not set_eml

set_eml will clobber any existing keywords.  Since remote
mboxrds cannot (and should not) be sending keywords to us,
we shouldn't let remote external requests clobber already-set
keywords if they exist.

eml: each_part: document IMAP user of the $all parameter

I already forgot what it does and thought I was misusing
the API :x

ds: import croak properly

We use croak in several places but weren't importing it :x

inbox: ->mailboxid accessor

This will be necessary for "mailboxIds" as described in RFCs 8620 and
8621 (for JMAP).  We may implement "MAILBOXID" in RFC 8474 for IMAP,
as well.

lei p2q: fix /dev/null filenames, fix phrase quoting rules

/dev/null mis-handling was reported by Kyle Meyer.

Phrases quoting rules are also refined to avoid leaving spaces
unquoted when "phrase generator" characters exist.  Also,
context-free hunk headers no longer clobber the in_diff
state of the parser, since git can still generate those.

Link: https://public-inbox.org/meta/87k0qrrhve.fsf@kyleam.com/

lei q: improve early aborts w/ remote externals

We must issue LeiStore->done if a client disconnects
while we're streaming from a remote external.  This
can happen via SIGPIPE, or if a client process is
interrupted by any other means.

lei q: fix "-" shortcut for --stdin

Due to the way our option parser handles this special case, it
must be the first option spec.  This helps us document things
better, even, since many command accept either a pathname or
--stdin|-.

lei p2q: patch-to-query generator for "lei q --stdin"

Instead of teaching the to-be-implemented "lei show" to search
threads/messages based commits, this orthogonal sub-command is
designed to generate queries for use with "lei q --stdin".

URI-escaped query parameters may be generated with --uri for
HTTP(S) public-inbox instances, but otherwise the output is
designed for "lei q --stdin".

To find threads for a given git commit from a git worktree:

lei p2q $COMMIT_OID | lei q --stdin -t ...

It can also read via --stdin|-

curl $INBOX_URL/$MSGID/raw | lei p2q - | lei q --stdin -t

Or from the filesystem:

lei p2q $(git format-patch -1) | lei q --stdin -t

This defaults to only generating "dfpost:"-prefixed terms since
I've found those most useful for finding messages relating to a
commit.  This is subject to change.

--want=s@ is a comma-separated or multi-value list of prefixes
that defaults to "dfpost7".  Not all are implemented, yet, but
s, dfn, dfpre, and dfpost all seem to mostly work.  Phrase
handling may need to be tweaked to work with Xapian.

OR, NEAR, ADJ, AND, NOT may be used with --want
(e.g. --want=dfpost,OR,dfn)

Prefixing the field prefix with '+' or '-' (e.g. --want=+dfpost)
generates "+dfpost:$EXTRACTED_OID" for Xapian.   For non-boolean
search prefixes, wildcard (*) may also be supplied: (--want=dfn*)

For boolean search prefixes, suffixing the field prefix with a
digit (e.g. --want=dfpost7) provides a minimum length, allowing
truncated variations to be searched.  This is helpful for
finding older messages as git chooses longer dfpost|dfpre
abbreviations as repos get larger.

Automatic date range generation is not implemented, yet.

examples/cgit-commit-filter: improve quoted text handling

With an example such as:

something before "quoted phrase" something after

The Xapian will now see:

[ "something before", "quoted phrase", "something after" ]

whereas before it would see:

[ "something before", "quoted", "phrase", "something after" ]

which should improve search results accuracy when looking
up commits by commit title (subject).

doc: lei-overview: add performance and bash completion sections

Take care of a couple of the items mentioned at
<https://public-inbox.org/meta/20210218202818.GA19443@dcvr>.

doc: lei-import: drop markup of "stdin"

stdin isn't placed in C<> elsewhere.

doc: lei: update manpages

Catch up with recent developments.

lei_xsearch: more detail about ->xdb call chain

I was just wondering this myself :x

t/lei_store: rename $lst to $sto

`$sto' is prevalent throughout the rest of the lei code,
and `$lst' seems like an abbreviation for "list".

I don't like the noise from commits like this, but I hope the
long-term payoff being less confusing to new developers is worth
it...

lei import|convert: support mbox locking on reads

In case somebody is writing non-atomically, ensure we
take read locks when opening mbox files for reading.

v2: squash: load MboxLock even for .eml files

lei q: support mbox locking by default

While this diverges from from mairix(1) behavior, it's the safer
option.  We'll follow Debian policy by supporting fcntl and
dotlocks by default (in that order).  Users who do not want
locking can use "--lock=none"

This will be used in a read-only capacity for watching
mailboxes for keyword updates via inotify or EVFILT_VNODE.

lei: style fix for $oldset declaration

We want /^sub oldset/ to match to keep editors and
things like ctags happy.

lei q: -tt marks direct hits as "flagged"

This can be used to quickly distinguish messages which were
direct hits when doing thread expansion vs messages that
were merely part of the same thread.

This is NOT mairix-derived behavior, but I occasionally found
it useful when looking at results in an MUA to know whether
a message was a direct hit or not.

This makes "-t" consistent with non-"-t" cases as far as keyword
reading goes.

test_common: io_modes: always support read/write

This avoids warnings when redirecting STDIN to a scalarref
via run_script().

lei import: use --in-format/-F for consistency

Since we recommend $IN_FORMAT:$LOCATION, this is hopefully not
intrusive (not that this is released software, yet).  This is
to be consistent with "lei convert" usage.

We'll keep "-f" only for output formats, since that is used
for "lei q" and "lei convert" for outputs

lei convert: support IMAP output and "-F eml" inputs

eml ("message/rfc822" MIME type) is supported by "lei import",
so it probably makes sense to support via convert, at least
for tests.  And IMAP support is supported in "lei q -o $MFOLDER",
so this only required renaming {nrd} => {net} and initializing
outputs before augment preparation (creating the IMAP folder)

lei q: auto-memoize remote messages into lei/store

This lets users avoid network traffic on subsequent searches at
the expense of local disk space.  --no-import-remote may be
specified to reverse this trade-off for users with little
storage.

lei_external: don't treat IPv6 URLs as globs

IPv6 addresses are hexadecimals and colons inside brackets, so
add some DWIM-ery to ensure we don't attempt to treat addresses
like "http://[dead:beef]/foo/" as a glob.

net_reader: trim exports and remove unused uri_new

More network things for -watch are isolated in NetReader, now,
so fewer exports are necessary.

watch: switch IMAP and NNTP fetch loops to NetReader

NetReader::<imap|nntp>_each were based on the -watch
code they now replace.

v2: do not warn on EINTR if user quit to fix occasional
    test failure in t/imapd.t

lei <import|convert>: support NNTP sources

We can read NNTP in -watch and Net::NNTP is shipped with Perl5,
so lei import and convert have no excuse not to support NNTP
as a client.

Authentication is not tested, yet; but should be close to what
IMAP is like...

add PublicInbox::URInntps package

We prefer the IANA-registered form of URIs to avoid confusing
users, but the URI package has yet to support it.

cf. https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=983419

lei: avoid needless env passing to subcommands

We already localize %ENV before calling dispatch(), so
it's needless overhead in spawn() to be checking env for
undef values in those cases.

treewide: avoid "delete local" construct on hashes

Apparently this feature is only in Perl 5.12+, and we're
still on Perl 5.10.

www: use PublicInbox::WwwStream

This prevents the following problem logged to the webserver's error log:

E: Undefined subroutine &PublicInbox::WwwStream::code_footer called at /usr/share/perl5/PublicInbox/WwwListing.pm line 102.
 in PublicInbox::ConfigIter=ARRAY(0x557aea68b1a8)::each_section at /usr/share/perl5/PublicInbox/ConfigIter.pm line 37.

Fixes: 7a3946ef122e ("www: support listing of inboxes")

lei_to_mail: remove unused OnDestroy import

lei q: reduce default lei2mail workers

While disk I/O is typically buffered for good scheduling,
git blob decoding uses a non-trivial amount of CPU time
and it helps to leave some CPU available for it.

lei: support "-C" to chdir in all sub commands

We'll also support "-C" at the end of most commands to give
users a little more flexibility when building command-lines.
This conflicts with "lei daemon-kill -CHLD", so that's
special-cased since "-C" makes no sense with daemon-kill,
anyways.

Unlike "git show", the to-be-implemented "lei show" will diverge
and enable "--find-copies[=<n>]" by default, so "-C[<n>]" won't
be necessary.

doc: lei: favor "-o format:$PATHNAME" over "-f"

The --format argument is redundant and may be dropped entirely.
Update the lei manpages to prefer the format prefix.

cf. https://public-inbox.org/meta/20210217044032.GA17934@dcvr/

lei_auth: trim and remove leftover worker code

LeiAuth is no longer a separate worker process.  Instead, it's
used directly by LeiToMail and LeiImport for sharing auth info
from the first worker to the rest of the workers, using
lei-daemon as a message router.  So drop the old code to reduce
human cognitive load and interpreter memory overhead.

lei convert: inline convert_start

Since we stopped using LeiAuth as a WQ worker, keeping this
around as a single-use sub makes no sense and wastes several
KB of memory.

net_reader: mic_get: reuse connections if cache enabled

We only enable {mic_cached} in WQ workers, and those
aren't expected to fork again going forward.  So cache
here avoid a penalty for the non-augmenting (imap_delete_all)
call with "lei q"

lei q: reduce wasted IMAP connection for auth

We can rework the first lei2mail worker to authenticate, and
then share auth info with the rest of the lei2mail workers.  As
with "lei import", this uses PktOp and lei-daemon to share
updated credentials between the first an subsequent l2m workers.

lei_auth: migrate common auth code from lei_import

lei_to_mail will be able to use this, too.

lei import: no separate auth worker

We'll start sharing auth info from the first worker to the
rest of the workers via wq_broadcast.

This lays the groundwork for getting rid of LeiAuth workers for
authentication work and reducing network round trips required
for IMAP.

lei convert: auth directly from worker process

Since this only has one worker, we can auth directly in the
worker since the convert worker now has access to the script/lei
{sock} for running "git credential".

lei: _lei_cfg: return empty hashref if unconfigured

Existing callers in LeiExternal actually depend on this,
and LeiAuth shouldn't need to be creating a config file
just to do a conversion against an anonymous IMAP server.

lei: keep client {sock} in short-lived workers

For non-persistent workers, there's no harm in keeping the
client socket open.  This means we can avoid dancing around
closing it in PublicInbox::LeiAuth::ipc_atfork_child.
Eventually, other WQ workers will trigger "git credential"
spawning in script/lei directly.

lei_auth: rename {nrd} field to {net} for clarity

We're authing for both reads and writes, this makes it
clear that we support both NetReader and NetWriter.

lei_store: populate ALL.git/alternates with new epochs

Since eidx_init updates ALL.git/objects/info/alternates, we need
to ensure new epochs we create from LeiStore->importer exist
before eidx_init writes alternates.

Reported-by: Kyle Meyer <kyle@kyleam.com>
Link: https://public-inbox.org/meta/8735xou0gq.fsf@kyleam.com/

t/lei*: drop $lei->(...) sub

lei() and lei_ok() are superior since they offer prototype
checks and lei_ok() adds another check + description DRY-ness.

The $lei sub was only bound to a variable since it was in
t/lei.t and named subs don't work well with the key2sub()
wrapper.

lei-daemon: prefer graceful shutdowns

We'll keep the daemon alive as long as a a script/lei client
remains connected.  This ought to improve user experience
and is in line with what -imapd/-httpd/-nntpd users have
expected over the years.

tests: clean up t/home* consistently

And update t/home2/README while we're at it.

Followup-to: 4ea3975dbed0a533 ("tests: setup_public_inboxes: use IMAP-friendly newsgroups")

t/www_listing: require grok-pull version 2 or later

The grok-pull-based tests in www_listing are incompatible with
Grokmirror v2 in two ways: the generated configuration format and the
expected exit codes.  Update the tests to work with v2, and skip them
for earlier versions.

This was tested with the latest release of Grokmirror, v2.0.7.  Note
that the "pull" and "fsck" sections are required even though they're
empty.

t/www_listing: reword grok-pull skip message

Make it clear that this skip is because grok-pull isn't available at
all because the next commit will add another skip for older versions
of Grokmirror.

t/www_listing: correct the number of tests for grok-pull skip

lei2mail: parallel augment for lock-free stores

This lets us make use of multiple cores on IMAP and Maildir
backed by SSD (or better) storage.  This benefits IMAP stores
with high network latency, but may still penalize IMAP servers
with rotational storage.

net_reader: use and accept URIimap objects in more places

This flexibility should save us some code down-the-line.

ipc: support setting a locked number of WQ workers

We can use this to ensure sharded work doesn't do unexpected
things if workers are added/removed.  We currently don't
increase/decrease workers once a workqueue is started, but
non-lei code (-httpd/imapd) may start doing so.

This also fixes a bug where lei2mail workers could not
be adjusted via --jobs on the command-line.

lei q: move augment into lei2mail workers

This is a step which will allow us to parallelize augment
on Maildir and IMAP.

ipc: add wq_broadcast

We'll give workqueues a broadcast mechanism to ensure all
workers see a certain message.  We'll also tag each worker
with {-wq_worker_nr} in preparation for work distribution.

This is intended to avoid extra connection and fork() costs
from LeiAuth in a future commit.

lei q: support IMAP/IMAPS --output destinations

Augment (and dedupe) aren't parallel, yet, so its more sensitive to
high-latency networks.

inbox_writable: require PublicInbox::MdirReader

This wasn't causing known failures, but maybe it was or will in
the future.

t/net_reader-imap: fix under TEST_RUN_MODE=0

PublicInbox::Config isn't loaded elsewhere by this file.

URIimap: overload "" to ->as_string

This interpolation is used by the upstream URI package
and we rely on it elsewhere for HTTP(S) URIs, so save
ourselves some surprises down the line.

net_writer: start implementing IMAP write support

Requiring TEST_IMAP_WRITE_URL to be set to a writable IMAP
server URL isn't ideal, but it works for now until we have time
to setup a mock dovecot/cyrus/etc... instance for testing.

net_reader: handle single-message IMAP mailboxes

Due to an off-by-one error, we were unable to read mailboxes
with only a single message of UID:1.  Without this fix, the
message with UID:1 could only be read after UID:2 was created;
so there's no permanent data loss as long as a new message
showed up.

This affects all releases of public-inbox-watch with IMAP
support, though it probably went unnoticed because single
message inboxes are rare.

tests: require Mail::IMAPClient for IMAP tests

All of our current IMAP code relies on Mail::IMAPClient
at the moment, so ensure we skip those tests on systems
without that module.

lei_to_mail: get rid of empty _post_augment_maildir

We won't have _post_augment_imap when we add IMAP support,
either.

_pre_augment_imap will not exist, either, since opening an
IMAP(S) connection can be time consuming so we'll roll that
into imap_common_init.

t/lei-externals: favor "-o format:$PATHNAME" over "-f"

It'll be less ambiguous for inputs with "lei convert" and "lei import"

cf. https://public-inbox.org/meta/20210217044032.GA17934@dcvr/

emergency: modernize and reduce syscalls

As with LeiToMail, we'll exclusively rely on O_EXCL and EEXIST
instead of "-f" (stat(2)) for file name collision checking.
Furthermore, we can rely on link(2) error handling instead of
using stat(2) to check the result of link(2).

We'll still keep the hostname in these filenames, but memoize it
on a per-instance basis since hostname changes are rare and we
can assume it won't change between "tmp" and "cur".

We'll also start embedding the PID as {"tmp.$$"} into the fiel
name to guard against accidental deletion in child processes,
instead of requiring an extra hash lookup.

Finally, avoid multiple getpid(2) syscalls in internal subs
since glibc no longer caches in getpid(3).

We'll also favor constant comparison of $! against EEXIST for
inlining. and stop doing ->autoflush when we only have a single
print + flush.

lei_to_mail: Maildir: ensure link(2) succeeds

link(2) may fail with errors other than EEXIST; just bail out
since something is likely seriously wrong.

lei: check for IMAP auth errors

We need to ensure authentication failures and error codes get
propagated to the parent process(es) properly.

v2: update MANIFEST
v3: LeiAuth.pm ->_lei_cfg bit moved to a previous commit

lei: consolidate the bulk of the IPC code

The backends for "lei add-external --mirror", "lei convert", and
"lei import" all share a similar pattern for spawning background
workers.  Hoist out the common parts to slim down our code base
a bit.

The LeiXSearch and LeiToMail workers for "lei q" remains a the
odd duck due to the deep pipelining and parallelization.

lei import: add IMAP and (maildir|mbox*):$PATHNAME support

This makes "lei import" more similar to "lei convert" and
allows importing from disparate sources simultaneously.

We'll also fix some ->child_error usage errors and make
the style of the code more similar to the "lei convert"
code.

v2: fix missing requires

lei convert: mail format conversion sub-command

This will make testing IMAP support for other commands easier, as
it doesn't write to lei/store at all.  Like the pager and MUA,
"git credential" is always spawned by script/lei (and not
lei-daemon) so it has a controlling terminal for password
prompts.

v2: fix missing requires, correct test ordering
v3: ensure config exists for IMAP auth

lei: completion: bash: generalize nospace usage

We'll be completing more options with ':', '//' and '=' in the
future, so make it easier to disable trailing spaces on
completions.

t/lei_to_mail: remove unnecessary arg passing

{zpipe} is contained entirely within the $l2m object, now.

tests: setup_public_inboxes: use IMAP-friendly newsgroups

-imapd won't support newsgroups ending with /\.[0-9]+\z/ since
it reserves those for partitioning inboxes into 50K slices.
So bump the home[0-9]+ version and switch to IMAP-friendly
newsgroup names.

lei import: move check_input_format to lei

We'll be supporting "lei convert" in a future change; so it
makes sense to share a common internal API for common error
messages.

lei import: start rearranging code for IMAP support

More to come in a later commit; some error handling and failure
modes will be trickier with IMAP due to authentication.

watch: connect to NNTP and IMAP in config order

This is hopefully less surprising to users when they're prompted
for credentials.

watch: move imap_common_init to NetReader

We'll use this in LeiImport and likely other places.

lei: bless config

We'll be needing ->url_match from PublicInbox::Config

lei: fail_handler: use correct exit code

We were shifting in the wrong direction :x

t/psgi_search: fix test around date boundaries

git approxidate won't actually return times in the future,
so "1.{hour,day,year}.from.now" all return the current epoch
time.

So just use "now" and ensure we have a predictable time zone for
testing.

search: query_approxidate: cleanup regexp, more tests

The cleanup doesn't seem to matter, I initially thought I needed
to handle "" (two double quotes) explicitly because that's what
Xapian does to escape a double quote inside a double-quoted
phrase.  It turns out we only need to be able to pass phrases
through to Xapian unmodified, and the existing group of
["\x{201c}\x{201d}] is sufficient for our purposes.