ipc: switch wq to use the event loop

This will let us to maximize the capability of our asynchronous
git API.  This lets us avoid relying on EOF to notify lei2mail
workers; thus giving us the option of running fewer lei_xsearch
worker processes in parallel than local sources.

I tried using a synchronous git API; and even with libgit2 in
the same process to avoid the IPC cost failed to match the
throughput afforded by this change.  This is because libgit2 is
built (at least on Debian) with the SHA-1 collision code enabled
and ubc_check stuff was dominating my profiles.

lei: more consistent dedupe and ovv_buf init

This fixes "--dedupe none" with Maildir where we don't
create the object at all.

doc: add lei-overview(7)

[ew: s/mboxrd/mboxcl2/ since that's what mutt uses]

doc: start manpages for lei commands

Add manpages for lei and the currently implemented subcommands.  The
included options and their descriptions follow to a large degree the
--help output, dropping some options that are not currently wired up.

TODO: add item for dealing with base-85 binary patches

False-positives from search results are no fun

content_hash: skip Sender for cross posted messages

This regression was introduced long ago and matches behavior
originally specified in the comments.  It makes a noticeable
improvement with search results using -extindex ("all") and
lei results with multiple inboxes.

Update some style bits at the top of the test case while
we're at it.

Fixes: f0ef0a56a8957d6f ("v2: improve deduplication checks")

shared_kv: simplify PID+object guard for cleanup

We don't need another hash slot when we can encode the object ID
and PID owner into the field name itself.

ipc: move on_destroy scope to inside the eval

It saves us a line of code

git: synchronous cat_file may return type and OID

Instead of forcing callers to set a variable to write into,
we'll just rely on wantarray.

lei: less error-prone FD mapping

Keeping track of non-standard FDs gets tricky, so make it easier
by relying on st_dev/st_ino mapping in the transmitted objects.

We'll keep using numbers for the standard FDs since we need to
be able to easily redirect them in the producer (main daemon)
process for (gzip|bzip2|xz) if writing to a compressed mbox.

ipc: more consistent behavior between worker types

Localize signals inside the respective worker loops
in case there's circular references.

We'll also rely on OnDestroy to trigger exits from the
ipc_worker_loop like we do with wq_worker_loop.  And
also add some more developer documentation to help future
developers.

The default signals remain different, for now.
Cleanup some unnecessary "use" statements while we're
loading OnDestroy.

lei_xsearch: drop repeated "Xapian" in error message

Copy+paste error :x

ipc: wq: support passing fields to workers

This will be useful for pre-sharing certain file handles.

lei: dclose: fix typo

Oops :x

v2writable: nproc: use sysconf() on Linux and FreeBSD

No need to fork a process on platforms I use daily, at least.

lei_overview: clear redundant ovv_buf definition

Declaring "my $buf" inside that `if' branch was useless, so
we've been declaring it per-callback when {l2m} isn't in use.

lei: complete option switch args

And add tests for existing completion cases

gcf2: rely on Perl 5.10 to avoid needless ++

And note the PublicInbox::Spawn side effect of setting
PERL_INLINE_DIRECTORY.

lei: set PWD correctly for path expansion

While commit d1b9582872d1824f166a038dcf32b6ae8c6dc735
("lei: pass FD to CWD via cmsg, use fchdir on server")
ensured things work properly to get the daemon in the
right directory, it forgot to deal with places where
we expand relative paths based on the current working
directory.

lei: fix comment regarding client payload

The client PID is no longer sent to the daemon.

lei: drop "git" command forwarding

It was intended as a proof-of-concept and no longer needed.

eml: favor index() over regexp match

Where applicable, index() is faster than entering the regexp
engine and we favor it in several other places, as well.

use defined-or in a few more places

Mainly around fork() calls, but some nearby places as well.

spawn: split() on regexp, not a literal string

It doesn't appear Perl (as of 5.32.x) has any internal
optimization for splitting on a single-byte, so give it
a regexp instead of letting it compile and discard a
new one every single time.

miscidx: switch to lazy transactions

This fixes a sporadic failure on a 1/2 core VM where
"git cat-file --batch" hasn't started up by the time
$cleanup->() destroys the ALL.git directory in t/lei.t
(but not t/lei-oneshot.t).

This happens because dwaitpid() runs inside the event loop
asynchronously and we were able to return to the client before
the cat-file process could even start.

I could not reproduce this failure on my usual 4-core
workstation via "schedtool -a 0x1" to force the entire
test to use a single core.

Lazy transactions matches OverIdx and SearchIdx behavior, and
I've verified this lets us avoid problems with old Xapian
versions (on CentOS 7.x) which failed to set FD_CLOEXEC.

doc: start working on public-inbox-extindex(1) manpage

It's barely started, but I started writing this weeks ago, but
I'm still unsure about some behavioral/usability things and
hoping work on lei(1) can flush them out.

build: check with lexgrog(1) if available

This will make life easier for Debian package maintainers
running lintian.

cf. commit 1350f5ab09f72c75ac2cd6c88f6a2b9e198fef55
    ("public-inbox-v[12]-format.pod: make lexgrog happy")

doc: extindex-format: make lexgrog happy

Based on commit 1350f5ab09f72c75ac2cd6c88f6a2b9e198fef55
("public-inbox-v[12]-format.pod: make lexgrog happy")

lei: use Time::HiRes stat for nanosecond resolution

The default stat() lacks subsecond granularity and may
lead to config updates being ignored.

lei q: continue remote search if torsocks(1) is missing

torsocks is just one of many ways to get curl to use Tor,
so we'll continue if we can't find torsocks in our PATH
and assume the user has a proxy configured via curlrc,
the command-line, environment variable, or even firewall
rules.

lei q: reject remotes early if curl(1) is missing

This ought to provide a better user experience for
users if they attempt to use remote externals but
don't have curl installed.

We can avoid repeating PATH search in every worker here, too.

lei q: demangle and quiet curl output

curl(1) writes to stderr one byte-at-a-time (presumably for the
progress bar).  This ends up being unreadable on my terminal
when parallel processes are trying to write error messages.

So instead, we'll capture the output to a file and run
'tail -f' on it if --verbose is enabled.

Since HTTP 404s from non-existent results are a common response,
we'll ignore them and stay silent, matching behavior of local
searches.

lei q: drop "oid" output format

The default deduplication command-line arguments would be
non-sensical for such an option and probably confusing.  It
doesn't seem worth the code to support OID-only output when it's
easy enough to use one of the JSON formats to extract the same
info.

We also don't have OIDs if using remotes, and the
to-be-implemented memoization will be optional.

lei: reinstate JSON smsg output deduplication

This was accidentally clobbered completely in
("lei q: fix JSON overview with remote externals").
There are now more tests to prevent future regressions.

doc: re-add missing 1.6 release notes

I missed these during the merge :x

doc: README + INSTALL: update with -imapd info

I forgot to update these when releasing 1.6 :x

smsg: parse_references: micro-optimization

With Perl 5.10+, we can rely on the defined-or-assignment (//=)
operator to avoid repeatedly rewriting an SV.

This may not provide a measurable difference here, but
it's more consistent with current style where things like
commit a05445fb400108e60ede7d377cf3b26a0392eb24
("config: config_fh_parse: micro-optimize") provide a measurable
improvement.

smsg: make parse_references an object method

Having parse_references in OverIdx was awkward and Smsg is
a better place for it.

lei q: fix JSON overview with remote externals

We can't (and don't need to) repeatedly get the $each_smsg
callback for each URI since that clobbers {ovv_buf} before
it can be output.

I initially thought this was a dedupe-related bug and
moved the dedupe code into the $each_smsg callback to
minimize differences.  Nevertheless it's a nice code
reduction.

I also thought it was related to incomplete smsg info,
so {references} is now filled in correctly for dedupe.

lei_xsearch: use curl -d '' for nginx compatibility

It appears Content-Length and/or Content-Type headers are
required by nginx with POST requests.

varnish alone doesn't have this requirement and my (perhaps
lossy) reading of RFC 2616, 7230, 7231 didn't note this, either.

In any case, we must support nginx even if it's overly strict.

Reported-By: Kyle Meyer <kyle@kyleam.com>
Link: https://public-inbox.org/meta/87v9bmswkh.fsf@kyleam.com/

lei q: honor --no-local to force remote searches

This can be useful for testing remote behavior, or for
augmenting local results.  It'll also be possible to explicitly
include/exclude externals via CLI switches (once names are
decided).

lei q: disable remote externals if locals exist

--remote should be explicitly enabled if local externals are
present, since users may be offline or on expensive + metered
Internet while traveling.

In the future, --remote will probably default to
caching/memoizing all messages it fetches to increase the
usefulness of --local.

ipc: get rid of wq_set_recv_modes

Just open every FD as read/write.  Perl (or any non-broken
runtime) won't care and won't attempt to use F_SETFL to alter
file description flags; as attempting to change those would
lead to unpleasant side effects if the file description is
shared with another process.

ipc: wq supports arbitrarily large payloads

This should not be needed, but somebody using lei could
theoretically create thousands of external URLs and
only have a handful of workers, which means the per-worker
URI list could be large.

lei q: limit concurrency to 4 remote connections

Unfortunately, this isn't a per-host limit, yet; but
nevertheless reduces load on existing PublicInbox::WWW
instances, since requesting a mboxrd is one of the more
expensive operations.

treewide: reseed RNG in child processes

This prevents name conflicts leading to retries and slowdowns in
temporary file name generation.  No actual data corruption
resulted because all temporary files are opened with O_EXCL
anyways.

This may increase security for IMAP, NNTP, and HTTPS sessions
using TLS, but it's all public data anyways.

lei add-external: don't allow non-existent directories

At least not yet, though we may support mirroring via git.

lei forget-external: don't show redundant "not found"

Pathname/URL canonicalization may not change the result at
all, so there's no point in trying (and failing) the same
form twice if pre and post-canonicalization are identical.

lei q: support a bunch of curl(1) options

Some of these options will make sense when on weird networks
(behind firewalls, etc.)  Some of these options may not make
sense at all.

This allows users who prefer to use the SOCKS5 proxy support in
curl rather than torsocks(1), but we'll still support torsocks
by default since some Tor instances aren't on the default
127.0.0.1:9050.

lei forget-external: just show the location

No need to show the full key name since the user mainly
uses the location.

lei completion: handle URLs with port numbers

This improves the experience for developers running local
instances of PublicInbox::WWW without permissions to bind
port 80 or 443.

lei: default "-f $mfolder" args for common MUAs

At least mail, mailx, mutt, and neomutt follow this convention.
Heirloom mailx doesn't support Maildir (our default), but GNU
mailutils mail/mailx does.

lei: oneshot: preserve stdout if writing mbox

We still need stdout if launching an MUA.

lei_to_mail: drop cyclic reference if not using IPC

This may fix another interrupt-related segfault I'm occasionally
seeing (but so far unable to reproduce).

lei: support remote externals

Via curl(1), since that lets us easily use tor on a
per-connection basis via LD_PRELOAD (torsocks) or proxy.
We'll eventually support more curl options which can allow
users to get past firewalls and deal with other odd network
configurations.

lei: move external vivification to xsearch

This seems like a better place to put it given upcoming
URI support, which starts in this commit.

lei forget-external: bash completion support

The tricky bit was getting around word splitting bash
does on URLs.  This may work with other shells, too.

lei: forget-external support with canonicalization

For proper matching, we'll do a better job canonicalizing
URLs and path names for matching.  Of course, users may edit
the file outside of lei, so ensure we try both the canonicalized
and as-is form provided by the user.

I also don't think we'll need to store externals info in
MiscIdx; just the config file is fine.

lei: remove @TO_CLOSE_ATFORK_CHILD

..At least limit it to a single file handle.  The write end
EOFpipe can be limited in scope and auto-closed when $quit is
clobbered, leaving only the listener.  The listener is the only
handle that needs to be closed explicitly due to it being on the
stack in the Listener->event_step => accept_dispatch => lei_$FOO
code path.

Everything else gets clobbered by DS->Reset in children after
forking.

lei_xsearch: reduce reference paths to lxs

Having an extra reference to LeiXSearch from the OpPipe $done_op
map is unnecessary and makes the reference graph more complex
than it needs to be.  Just use $lei->{lxs} to simplify and
reduce the likelyhood of bugs.

lei: remove INT/QUIT/TERM handlers, fix daemon EOF

The signal handlers on the client side were unnecessary,
all we need is to handle socket EOF properly in the daemon
by killing xsearch and l2m workers.

lei: oneshot: use client $io[2] for placeholder

STDERR may actually get closed in ->ipc_atfork_child in
oneshot mode, so ensure we pass in a valid file handle
to avoid warnings ->wq_do.

lei_to_mail: avoid segfault on exit

Worker exit causes DESTROY ordering to become unpredictable and
leads to Perl segfaulting.  Instead, rely on OnDestroy and
explicit triggering after wq_worker_loop to ensure we finish
all outstanding git requests before worker exit.

lei: fix inadvertant FD sharing

$wq->{-ipc_atfork_child_close} neededed to be initialized properly.
And start setting $0 in workers to improve visibility.

lei: show {pct} and {oid} in From_ lines and filenames

From_ lines are shown when mbox* variants are output to stdout,
making {oid} and {pct} information visible without risking being
propagated to other importer processes if they were in
lei-specific X-* headers.

Maildirs already had OIDs in the filename, now they gain Xapian
{pct} in case anybody cares.

lei_xsearch: eliminate some unused, commented-out code

lei q: retrieve keywords for local, non-external messages

This isn't tested for now, so maybe it works.

lei_overview: rename {relevance} => {pct}

The old name was too long compared to the rest of the field
names.  With the Xapian method being named ->get_percent,
"pct" is a well known abbreviation for "percent" and already
used internally by our wrapper.

..And cleanup some excess whitespace while we're in the area.

lei_to_mail: call PublicInbox::IPC::DESTROY

It doesn't seem to matter at the moment, but it should
save us from some surprises down the line.

lei_xsearch: keep l2m->{-wq_s1} while preparing query

This caused a performance regression which made parallel
lei2mail processes fail prematurely and fall back to
writing blobs in the lei_xsearch worker.

lei: dump and clear errors.log in daemon mode

Inspired by "dmesg -c", this should help users report bugs
and avoids eating up $XDG_RUNTIME_DIR.

Once lei is ready for release, hopefully the need for this
should be few an far between, but shit happens.

lei q: cleanup store initialization

Since we no longer leak an FD for over.sqlite3, we can
initialize and actually enable it by default as originally
intended.

overidx: eidx_prep: fix leftover dbh reference

Leaving $dbh in another field was causing over.sqlite3 to
remain open after ->dbh_close.  Fix up some minor style
issues while we're at it.

lei: exit code in oneshot mode

waitpid() in DESTROY ends up setting $? for the exit status,
thus we must reap IPC children before calling CORE::exit.

This fixes t/lei-oneshot.t with TEST_RUN_MODE=0

lei: allow more mbox inode types

We may attempt to write an mbox to any terminal, block, or
character device, not just regular files and FIFOs/pipes.
The only thing that is known to not work is a directory.

Sockets may be possible with some OSes (e.g. Plan 9) or
filesystems.  This fixes t/lei.t on FreeBSD 11.x

lei_overview: start implementing format detection

We'll need it for IMAP support, at least.  Proper mbox family
detection will be expensive, so deal with it later.

lei: test some likely errors due to misuse

Because user errors happen...

t/lei: fix double-running of socket test with oneshot

We split out t/lei-oneshot.t and t/lei.t so it's easier
to isolate run-mode specific bugs and behavior and there's
no reason to rerun the socket daemon tests.

lei_overview: do not write if $lei->{1} is gone

We'll invalidate the {1} (stdout) field on SIGPIPE,
so don't trigger a Perl warning by writing to it.

lei q: fix augment of compressed mailboxes

We need to delay writing out the mailbox until the compressor
process is up and running, so have startq wait a bit.  This
means we must create the pipe early and hand it off to the
workers before augmenting, despite spawning the
gzip/pigz/xz/bzip2 process after augment is complete.

lei: write daemon errors to the sock directory

Most everything should be captured by the __WARN__ handlers and
routed to syslog, but it appears Perl may write to stderr in
some emergency cases, as can libc or other libraries.  Just
point it to a small file that's cleared on reboot.

lei q: do not spawn MUA early

I'm not sure why, but mutt sometimes won't detect small
quickly.  We'll display a progress bar meter when writing
results, instead.

lei q: fix SIGPIPE handling from lei2mail workers

We need to properly propagate SIGPIPE to the top-level
lei-daemon process and avoid relying on auto-close,
since auto-close triggers Perl warnings when explicit
close() does not.

lei q: start ->mset while query_prepare runs

We don't need the result of query_prepare (for augmenting or
mass unlinking) until we're ready to deduplicate and write
results to the filesystem.  This ought to let us hide some of
the cost of Xapian searches on multi-device/core systems for
extremely expensive searches.

lei_to_mail: optimize for MUAs

Instead of optimizing our own performance, this optimizes
our data to reduce work done by the MUA consumer.

Maildir and mbox destinations no longer support any notion of
the IMAP \Recent flag.  JMAP has no functioning \Recent
equivalent, and neither do we.

In practice, having MUAs (e.g. mutt) clear the \Recent flag when
committing changes to the mbox is expensive: it creates a
rename(2) storm with Maildir and overwrites the entire mbox.

For mboxcl2 (and mboxcl), we'll further optimize mutt behavior
by setting the Lines: header in addition to Content-Length.

With these changes, mutt exits instantaneously on mboxcl2,
mboxcl, and Maildirs generated by "lei q".

lei q: parallelize Maildir and mbox writing

With 4 dedicated workers, this seems to provide a 100-120%
speedup on a 4 core machine when writing thousands of search
results to a Maildir or mbox.  This also sets us up for
high-latency IMAP destinations in the future.

This opens the door to more speedup opportunities such
as optimizing dedupe locking and other ways to reduce
contention.

This change is fairly complex and convoluted, unfortunately.
Further work may allow us to simplify it and even improve
performance.

lei q: add --mua-cmd switch

It can be convenient to invoke an MUA as search results
are being written to it, as an eager person may want to
start seeing results ASAP.  This lets Maildir users
see results in the MUA as we are writing them.  Users
of IMAP will eventually be able to take advantage of
them, too.

Since we don't support mbox locking (yet?), we'll only invoke
the MUA after results are done for mbox formats.

lei: pager: pass correct env in oneshot mode

We want new environment variables when spawning the
pager from oneshot (non-daemon) mode.

lei: q: results output to Maildir and mbox* working

All the augment and deduplication stuff seems to be working
based on unit tests.  OpPipe is a nice general addition that
will probably make future state machines easier.

ipc: children don't kill on DESTROY, reduce FD sharing

Children should not be blindly killing siblings on ->DESTROY
since they're typically shorter-lived than parents.  We'll
also be more careful about on-stack variables and now we
can rely exclusively on delete ops to close FDs.

We also need to fix our SIGPIPE handling for the oneshot case
while fixing a typo for delete, so we write "!" to the EOF pipe
to ensure the parent oneshot process exits on the first worker
that hits SIGPIPE, rather than waiting for the last worker to
hit SIGPIPE.

lei_to_mail: prepare for worker offload

We'll be doing most of the work in forked off worker processes,
so ensure some of it is fork and serialization-friendly.

extindex: fix w/ Xapian 1.2.21..1.2.24

Xapian v1.2.21..v1.2.24 failed to set the close-on-exec flag
on the flintlock FD, causing "git cat-file" processes to
hold onto the lock and prevent subsequent Xapian::WritableDatabase
from locking the DB.  So cleanup git processes after committing
the miscidx transaction.

t/shared_kv: workaround old File::Spec

The version of File::Spec shipped with Perl 5.16.3 memoizes the
value of File::Spec->tmpdir, causing changes to $ENV{TMPDIR}
after-the-fact to be ignored.

We'll only work around this in the test since it's innocuous and
unlikely to matter in real-world usage (and there's many places
where we'd have to workaround this in non-test code).

t/thread-index-gap: support older DBI

...by avoiding selectall_array in favor of selectall_arrayref.
Tested with DBI 1.627.

initialize scalar for `vec' perlop modification

Older Perls (tested 5.16.3) would warn on uninitialized scalars while
newer (tested 5.28.1) do not.  Just initialize it to an empty string
since it'll be filled in by `vec'.

address: pairs: enable pure Perl version

Oops, this is needed for systems lacking Email::Address::XS

lei: pass FD to CWD via cmsg, use fchdir on server

Perl chdir() automatically does fchdir(2) if given a file
or directory handle since 5.8.8/5.10.0, so we can safely
rely on it given our 5.10.1+ requirement.

This means we no longer have to waste several milliseconds
loading the Cwd.so and making stat() calls to ensure
ENV{PWD} is correct and usable in the server.  It also lets
us work in directories that are no longer accessible via
pathname.

lei: remove temporary var on open

We can place the IO/GLOB ref directly into $self, here.

leixsearch: remove some commented out code

Dedupe is active, now, and we have $each_smsg->(...)

lei: q: lock stdout on overview output

Most writes to stdout aren't atomic and we need locking to
prevent workers from interleaving and corrupting JSON output.
The one case stdout won't require locking is if it's pointed
to a regular file with O_APPEND; as POSIX O_APPEND semantics
guarantees atomicity.