lei add-external: completion for existing URL basenames

Given the presence of one external on a certain host or prefix
path, it's logical other inboxes would share a common prefix.
For bash users, attempt to complete that using the "-o nospace"
option of bash

lei: help starts pager

Because some commands have many options which take up
multiple screens.

lei: complete basenames for include|exclude|only

This will make it even easier for RSI-afflicted users to use,
since many externals may share a common prefix.

lei q: -I/--exclude/--only support globs and basenames

We can do basename matching when it's unambiguous.  Since '*?[]'
characters are rare in URLs and pathnames, we'll do glob
matching by default to support a (curl-inspired) --globoff/-g
option to disable globbing.

And fix --exclude while we're at it

lei: propagate curl errors, improve internal consistency

IO::Uncompress::Gunzip seems to be losing $? when closing
PublicInbox::ProcessPipe.  To workaround this, do a synchronous
waitpid ourselves to force proper $? reporting update tests to
use the new --only feature for testing invalid URLs.

This improves internal code consistency by having {pkt_op}
parse the same ASCII-only protocol script/lei understands.

We no longer pass {sock} to worker processes at all,
further reducing FD pressure on per-user limits.

lei: err: avoid uninitialized variable warnings

pkt_op: rely on DS::in_loop global

No reason to check for $lei->{oneshot} here.

lei: further reduce lei2mail FD pressure

We don't need to be sending errors directly to the client, but
instead go through lei-daemon or the top-level one-shot process.

lei: reduce FD pressure from lei2mail worker

lei2mail doesn't need stdin anymore, so we can use the [0] slot
for the $not_done keepalive purposes.

lei q: support --jobs [SEARCHERS],[WRITERS]

This comma-delimited parameter allows controlling the number or
lei_xsearch and lei2mail worker processes.  With the change
to make IPC wq_* work use the event loop, it's now safe to
run fewer worker processes for searching with no risk of
deadlocks.

MAX_PER_HOST isn't configurable yet for remote hosts,
and maybe it shouldn't be due to potential for abuse.

lei q: tidy up progress reporting

We won't be reporting progress when output is going to stdout
since it can clutter up the terminal unless stderr != stdout,
which probably isn't worth checking.

We'll also use a more agnostic mset_progress which may
make it easier to support worker-less invocations.

lei_overview: avoid unnecessary {l2m} delete

We may reuse these objects in the non-worker code paths.

doc: lei-q: note "-a" and link to Xapian QueryParser

"-a" is supported by mairix, too.  We should also note somewhere
the query parsing features supported by Xapian.

lei_xsearch: ensure curl.err and tail(1) cleanup happens

We can safely rely on exit(0) here when interacting with curl(1)
and git(1), unlike query workers which hit Xapian directly,
where some badness happens when hit with a signal while
retrieving an mset.

pktop: fix potential undefined var

In case we have other bugs in our code.

cmd_ipc4: fix comments and formatting

lei q: do not leave temporary files after oneshot exit

Avoid on-stack shortcuts which may prevent destructors from
firing since we're not inside the event loop.  We'll also tidy
up the unlink mechanism in LeiOverview while we're at it.

lib: explicitly distinguish oneshot use

The daemon must not be fooled into thinking it's in oneshot
after a lei client disconnects and erases {sock}.

lei_xsearch: truncate curl stderr after reading it

We may have further URLs to read in that process, so ensure
we don't end up having tail send stale data.

lei: q: shell completion for --(include|exclude|only)

Because .onion URLs names are long!

lei: complete: do not complete non-arg options w/ help text

Some of our command-line switches take no arguments, and need
no completion for those arguments.

lei q: support --only, --include and --exclude

-I is short for --include since it's standard for C compilers
(along with Perl and Ruby).  There are no single-character
shortcuts for --exclude or --only, since I don't expect
--exclude to be used very often and --only is already short (and
will support shell completion).

lei q: emit progress and counting via PktOp

Sometimes it can be confusing for "lei q" to finish writing to a
Maildir|mbox and not know if it did anything.  So show some
per-external progress and stats.

These can be disabled via the new --quiet/-q switch.

We differ slightly from mairix(1) here, as we use stderr
instead of stdout for reporting totals (and we support
parallel queries from various sources).

lei_query: default to 10000 messages as documented

Otherwise, we were only getting 50 matches without (-t)
thread expansion.

lei: switch to use SEQPACKET socketpair instead of pipe

This will allow us to use larger messages and do progress
reporting to accumulate in the main daemon.

doc: note optional BSD::Resource use

We've actually been capable of using this since 2019(*) in our
spawn code for PSGI limiters.  And it's been used since 2016 in
our tests.  It's a dependency of SpamAssassin, and Danga::Socket
used it, too.

(*) commit 721368cd04bfbd03c0d9173fff633ae34f16409a
    ("spawn: support RLIMIT_CPU, RLIMIT_DATA and RLIMIT_CORE")

lei: avoid ETOOMANYREFS, cleanup imports

As with PublicInbox::IPC, we'll attempt to bump RLIMIT_NOFILE
and transparently workaround ETOOMANYREFS.  If that fails,
we'll give the user a hint to bump RLIMIT_NOFILE since
ETOOMANYREFS is an uncommon error which users may be unfamiliar
with.

Found while stress testing for segfaults.

ds: next_tick: avoid $_ in top-level loop iterator

$_ at the top of a potentially deep stack below may cause
surprising behavior as I experienced with ExtSearchIdx.  In the
future, we'll limit our $_ usage to easily-auditable bits (e.g.
map, grep, and small for loops)

ds: guard against stack-not-refcounted quirk of Perl 5

The Perl 5 stack is weakly-referenced for performance reasons.
This means it's possible for items in the stack to be freed
while executing further down the stack.

In lei (and perhaps public-facing read-only daemons in the
future), we'll fork and call PublicInbox::DS->Reset in the child
process.  This causes %DescriptorMap to be clobbered, allowing
the $DescriptorMap{$fd} arg to be freed inside the child
process.

When Carp::confess or Carp::longmess is called to generate a
backtrace, it may access the @DB::args array.  This array access
is not protected by reference counting and is known to cause
segfaults and other weird errors.

While the caller of an unnecessary Carp::confess may be
eliminated in a future commit, we can't guarantee our
dependencies will be free of @DB::args access attempts
in the future.

So guard against this Perl 5 quirmk by defensively bumping the
refcount of any object we call ->event_step on.

cf. https://rt.perl.org/Public/Bug/Display.html?id=131046
    https://github.com/Perl/perl5/issues/15928

import: reap git-config(1) synchronously

This avoids a zombie if another step of the event loop
takes too long.

sharedkv: do not set cache_size by default

These DBs will probably be too small to be worth increasing the
cache size of.

lei_to_mail: reduce spew on Maildir removal

At most, we'll only warn once per worker when a Maildir
disappears from under us.  We'll also use the '!' OpPipe
to note the exceptional condition, and use '|' to SIGPIPE
so it'll be a bit easier for hackers to remember.

sharedkv: use lock_for_scope_fast

This allows us to avoid repeated open() and close() syscalls
and speeds up the new xt/stress-sharedkv.t maintainer test
by roughly 7%.

lei: increase initial timeout

PublicInbox::Listener unconditionally sets O_NONBLOCK upon
accept(), so we need a larger timeout under heavy load since
there's no "dataready" accept filter on the listener.

With O_NONBLOCK already set, we don't have to set it at
->event_step_init

sharedkv: lock and explicitly disconnect {dbh}

It may be possible for updates or changes to be uncommitted
until disconnect, so we'll use flock() as we do elsewhere
to avoid the polling retry behavior of SQLite.

We also need to clear CachedKids before disconnecting to
to avoid warnings like:

  ->disconnect invalidates 1 active statement handle
  (either destroy statement handles or call finish on
  them before disconnecting)

lei: deep clone {ovv} for l2m workers

We don't need to send the temporary xsearch {git} object over to
workers, just the directory name.

lei_xsearch: load PublicInbox::Smsg

We use $smsg->populate here, so ensure it's loaded although
PublicInbox::Search currently loads it.

lei_dedupe: use Digest::SHA

While it's loaded by ContentHash, we use Digest::SHA directly in
this package for smsg and OID-only deduplication.

lei: keep $lei around until workers are reaped

This prevents SharedKV->DESTROY in lei-daemon from triggering
before DB handles are closed in lei2mail processes.  The
{each_smsg_not_done} pipe was not sufficient in this case:
that gets closed at the end of the last git_to_mail callback
invocation.

sharedkv: release {dbh} before rmtree

This may be needed to avoid warnings/errors when
operating in single process mode in the future.

lei: remove syslog dependency

It doesn't seem necessary now that we redirect and write
stuff to errors.log, which gets checked every run.

ipc: more helpful ETOOMANYREFS error messages

ETOOMANYREFS is probably a unfamiliar error to most users, so
give a hint about RLIMIT_NOFILE.  This can be hit on my system
running 3 simultaneous queries with my system default limit of
1024.

There's also no need to import Errno constants for uncommon
errors, so we'll stop using Errno, here.

We'll also try to bump RLIMIT_NOFILE as much as possible
to avoid this error.

lei: remove SIGPIPE handler

It doesn't save us any code, and the action-at-a-distance
element was making it confusing to track down actual problems.
Another potential problem was keeping references alive too long.

So do like we would a C100K server and check every write
while still ensuring lei(1) exit with a proper SIGPIPE
iff needed.

lei: remove per-child SIG{__WARN__}

The top-level $SIG{__WARN__} using $current_lei does the job,
already.

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.