lei_mail_sync: show non-matching SHA

It could prove useful for diagnosing bugs (either on our
end or an MUA's), or storage device failures.

lei inspect: show ISO8601 {rt} and {dt}, too

While inspect is intended for debugging, the Unix epoch in
seconds requires extra steps for human consumption; just
steal what we used for "lei q -f json" output.

lei inspect: add atfork hook

This is necessary for in case an inspect command is run
in a parallel with other commands.

doc: lei: describe lei-daemon-kill and upgrades

While we're at it, start dropping copyright years
since it seems acceptable to not have them:

  https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/

Copyright years are also a noisy to update every year (maybe,
just maybe, we'll make it to 2022...)

lei: remove unused ->busy time arg

Our graceful shutdown doesn't time out clients.

lei up: support --exclude=, --no-(external|remote|local)

These can be used to temporarily disable  using certain
externals in case of temporary network failure or mount point
unavailability.

lei: conditionally add "\n" to error messages

Some error messages already include "\n" (w/ file+line info),
so don't add another one.  (`warn' will automatically add its
caller location unless there's a final "\n").

lei up: propagate redispatch_all failure via exit code

We can still continue with some local externals, maybe;
but the error needs to be propagated to the calling process
for scripting purposes.

lei: use die for external and query handling

This allows "lei up" to continue processing unrelated externals
if on output fails.

lei up: prefix `remote' and `local' with `o_'

This will help distinguish between mail outputs and external
public-inboxes.

test_common: lazy-require AutoReap

This might speed up non-daemon-using tests.

Makefile.PL: drop generated lib/PublicInbox.pm in blib/

Running "make test" on this project doesn't pass unless you've got an
existing PublicInbox.pm in your @INC, presumably nobody's set this up
on a fresh machine in a while.

This Makefile.PL trickery seems to do it, I've validated this with
this ad-hoc test of committing blib/ and Makefile to the repository:

    git clean -dxf; perl Makefile.PL && make -j8 all && git add -f blib Makefile.PL Makefile && git commit -m"now"

Running that in interactive rebase before/after shows that only the
PublicInbox.pm file was added to blib/lib/. We use $(INST_LIB) instead
of a hardcoded 'blib/lib' now, but it's what ExtUtils::MakeMaker
recommends, so it's probably for the better.

As far as I can tell this broke with 1fae720d (build: generate
PublicInbox.pm with $VERSION, 2021-04-01), but I have not tested
that. See also 1fae720d (build: generate PublicInbox.pm with $VERSION,
2021-04-01) which made the PublicInbox.pm a generated file.

v2: mirrors don't clobber msgs w/ reused Message-IDs

For odd messages with reused Message-IDs, the second message
showing up in a mirror (via git-fetch + -index) should never
clobber an entry with a different blob in over.

This is noticeable only if the messages arrive in-between
indexing runs.

Fixes: 4441a38481ed ("v2: index forwards (via `git log --reverse')")

extindex: show mismatches for messages deleted from inbox

There seems to be a bug in v2 inbox reindexing somewhere...

extindex: better locations for {quit} checks

Check for graceful termination at every message since it's
a fairly inexpensive check.

extindex: guard against false mismatch unrefs

I'm not sure if this is a bug or not (or it could be
an old bug in the v2 indexing code).

extindex: retry sync_inbox before reindex

Ensure the num highwater mark of the target inbox is stable
before using it.  Otherwise we may end up repeating work
done to index a message.

extindex: use localtime to display lock time

Since this is intended for use on the command-line,
include TZ offset in time and try to shorten the
message a bit so it wraps less on a terminal.

msgmap: do not cache num_highwater

Caching the value doesn't seem necessary from a performance
perspective, and it adds a caveat for read-only users which
may lead to bugs in future code.

eml: fix leak workaround

Our previous workaround didn't actually work around the leak in
<https://rt.cpan.org/Public/Bug/Display.html?id=139622> since
croak()-via-Perl was still invoked before the SV reference
count could be decremented.

Put in a proper workaround which saves warnings onto a temporary
variable and only croak after ->decode or ->encode returns; not
inside those methods.

MANIFEST: regenerate with: git ls-files >MANIFEST

lei sockets: favor level-triggered epoll for fairness

Sigfd->event_step needs priority over script/lei clients,
LeiSelfSocket, and everything else.

input_pipe: do not loop in ->event_step for fairness

Sigfd->event_step needs priority over InputPipe (and everything
else).  We keep Edge Triggering here but use ->requeue instead
of looping inside event_step.  This was necessary because
InputPipe can be used with regular files which can't be
monitored with epoll.

We'll also rid of the vestigial lei-oneshot support while we're
at it.

pkt_op: favor level-triggered epoll for fairness

Sigfd->event_step needs priority over PktOp (and everything else).
We'll also add ECONNRESET checking, here, since it could see
bidirectional use in the future.

This is unlikely to have any sort of performance difference
since this is only for small, occasional packets, but the code
reduction is nice.

wqworker: favor level-triggered epoll for fairness

Sigfd->event_step needs priority over WQWorkers (and everything
else).  Do that by running once per event_loop iteration rather
than looping inside event_step.  This lowers throughput since it
requires more syscalls, but that's the price of fairness.

t/lei*: set EDITOR for dumb terminals

Running tests over a non-interactive ssh session fails,
otherwise.

doc: lei: add manpages for remaining commands

At this point all of the current lei commands, aside from -help and
-sucks, should be covered.

doc: lei: restore alphabetical order to some listings

Most the lei-related entries in txt2pre and Makefile.PL are in
alphabetical order.  Reorder the few that aren't.

While at it, reflow the Makefile.PL entries in preparation for the
entries that will be added in the next commit.

extindex: avoid triggering a buggy unref

We can't attempt to unref messages beyond the highwater mark of
an inbox.  This bugfix was found by commit c485036d0b1ce7ed
(extindex: guard against buggy unrefs, 2021-10-14), which
actually did its intended job and guarded against a buggy unref.

httpd/async: switch to level-triggered epoll

We'll save ourselves some code here and let the kernel do more
work, instead.

inbox + search: use 5.10.1 and do some golfing

Some yak-shaving while I try to track down other bugs...

lei_to_mail: quiet down abort messages

We don't need to flood the terminal with "W: $oid is  (!= blob)\n"
messages when somebody nukes a git cat-file process from under
us.

lei_overview: die rather than lei->fail

This will make our code more flexible in case it gets used in
non-lei things.

extindex: prune invalid alternate entries on --gc

Seeing the same warning over and over again gets annoying.

lei: more eval guards for die on failure

Relying on $lei->fail is unsustainable since there'll always
be parts of our code and dependencies which can trigger die()
and break the event loop.

lei: always keep cwd fd {3} for ->fchdir

The extra FD shouldn't cause noticeable overhead in short-lived
workers, and it lets us simplify lei->rel2abs.  Get rid of a
2-argument form of open() while we're at it, since it's been
considered for warning+deprecation by Perl for safety reasons.

lei: golf PATH2CFG cleanup

More code means more bugs.

httpd: move pipeline logic into event_step

Most of the HTTP server code was written for Danga::Socket and
not fully-transitioned to take advantage of PublicInbox::DS.
This change brings it up-to-date with the style of pipeline
handling used for -imapd and -nntpd.

imapd+nntpd: drop timer-based expiration

It's needlessly complex and O(n), so it doesn't scale well to a
high number of clients nor is it easy-to-scale with the data
structures available to us in pure Perl.

In any case, I see no evidence of either -imapd nor -nntpd
experiencing high connection loads on public-facing sites.
-httpd has never had its own timer-based expiration, either.

Fwiw, public-inbox.org itself has been running a public-facing
HTTP/HTTPS server with no userspace idle client expiration for
the past 8 years or with no ill effect.  Clients can come and go
as they wish, and SO_KEEPALIVE takes care of truly broken
connections if they're gone for ~2 hours.

Internet connections drop all time, so it should be harmless to
drop connections w/o warning since both NNTP and IMAP protocols
have well-defined semantics for determining if a message was
truncated (as does HTTP/1.1+).

dir_idle: do not add watches in ->new

There's no savings in having two ways to add watches to an
inotify nor kqueue descriptor.

smsg: add ->oidbin method

This makes some of our code less noisy by reducing the
amount of pack('H*', ...) use.

lei q: guard query_done against die()

v2w->wq_do('done') may die on I/O errors, and likely other
places.  Just guard the entire block with an eval and ->fail
as appropriate.

lei forget-search: support multiple args

I've been testing a lot of searches which I don't want to keep
around, so make it easy to remove a bunch at once.  We'll behave
like rm(1) and keep going in the face of failure.

lei note-event: fix explicit flush reliability

We need to send the socket over to lei/store and wait for the
kernel to drop the socket refcount down to zero before
script/lei can exit.

This is not a new bug and only caused very sporadic test
failures.  I only noticed it while simplifying IPC stuff.

lei + ipc: simplify process reaping

Simplify our APIs and force dwaitpid() to work in async mode for
all lei workers.  This avoids having lingering zombies for
parallel searches if one worker finishes soon before another.

The old distinction between "old" and "new" workers was
needlessly complex, error-prone, and embarrasingly bad.

We also never handled v2:// writers properly before on
Ctrl-C/Ctrl-Z (SIGINT/SIGTSTP), so add them to @WQ_KEYS
to ensure they get handled by $lei when appropropriate.

lei forget-search: fix for symlink-ed paths

If lei up and edit-search work on something, so should forget-search.

lei q: avoid kw lookup failure on remote mboxrd

When importing several sources in parallel via http(s) mboxrd,
we need to be able to get keywords of uncommitted documents
directly from shard workers.  Otherwise, Xapian DocNotFound
errors happen because the read-only LeiSearch won't see
documents from uncomitted transactions.  Keep in mind that it's
possible the keywords can be changed on-the-fly even for
uncommitted documents because of inotify watches from LeiNoteEvent.

www: various help text updates

`dt:' documentation is redundant with `d:' approxidate support;
so drop `dt:' since mairix uses `d:'.  We'll also document
`rt:' since there are legit messages from senders with broken
clocks.

Reduce indentation level of help texts to be in 2-space
increments to using too much horizontal space.

We'll always place IMAP ahead of NNTP since it's alphabetical
and there's likely more IMAP clients out there.

Add "--ng NEWSGROUP" to -init instructions if configured.

There's also some minor wording changes throughout.

lei up --all: send signals to workers, receive errors

The redispatch mechanism wasn't routing signals and messages
between redispatched workers and script/lei properly.  We now
rely on PktOp to do bidirectional message forwarding and
carefully avoiding circular references by using PktOp.

lei up: actually rely on DESTROY for --alllll

We need to use DESTROY here to ensure we wait for workers, too;
not just the initial dispatch.

Fixes: cafbd77b3c82167d ("lei up: avoid excessively parallel --all")

lei: TSTP affects all curl and related subprocesses

By relying more on pgroups for remaining remaining processes,
this lets us pause all curl+tail subprocesses with a single
kill(2) to avoid cluttering stderr.

We won't bother pausing the pigz/gzip/bzip2/xz compressor
process not cat-file processes, though, since those don't write
to the terminal and they idle soon after the workers react to
SIGSTOP.

AutoReap is hoisted out from TestCommon.pm.  CLONE_SKIP
is gone since we won't be using Perl threads any time
soon (they're discouraged by the maintainers of Perl).

git: cat-file --batch are their own pgrp

We want these long-lived processes to die naturally when their
parent dies.  Hopefully this improves graceful shutdown for
-extindex because I'm interrupting a lot of reindexing...

git: ->fail invokes current callback

While we try to invoke all pending callbacks to force error
handling, the current callback wasn't getting invoked on
invoked on async_abort if my_read/my_readline failed.

git: async_err shows retried requests properly

We make $req a reference upon retrying, but
"SCALAR(...)" in error messages isn't helpful, so
dereference the scalar ref.

lei: use send() perlop for signals

This may save us a small bit of startup time since there's
fewer args and opcodes should be smaller.

lei: give workers their own process group

This lets users Ctrl-Z from their terminal to pause an entire
git-clone process hierarchy.

lei: -d (--dir) and -O (only) shortcuts

`-d' seems like a non-brainer for --dir with inspect.

I find myself using `--only' a bit, too, and `-O' seems like
a reasonable shortcut for it.

lei add-external --mirror: respect client umask

While lei is intended for non-public mail and runs umask(077)
by default, externals are one area which can safely defer to
the user's umask.

Instead of sending it unconditionally with every command, only
have lei-daemon request it when necessary.

clone+fetch: respect umask for all downloaded files

Since public inboxes are usually intended to be public,
the File::Temp default permission of 0600 is wrong.
Just respect the user's umask in this case as git-clone
does.

This doesn't work for "lei add-external --mirror", yet;
but it will...

lei inspect: account for non-extindex inboxes

Inbox->xdb does not exist, but this code path was apparently
never tested :x  I noticed this on basic v2 inbox, but it could
happen with any v1/v2 inbox.  Move ->num2docid into Search
so it's less awkward to use.

extindex: guard against buggy unrefs

I noticed some unref messages which shouldn't have been
happening, but they were.  Which is troubling.  So add
a guard around an unref path until we can get to the bottom
of this.

fetch: support --try-remote/-T for alternate remote names

This allows -fetch to work out-of-the-box on using the
grokmirror 2.x default of "_grokmirror".

t/nntpd-tls: change diag() to like() assertion

This test wasn't finished when I initially wrote it :x

t/git: avoid "once" warning for async_warn

No point in testing use_ok when we have no outside dependencies
nor exports in this case.

t/lei-mirror: avoid reading ~/.public-inbox/config in test

Oops, we shouldn't attempt to read a users' actual HOME when
running -index, since mine has a bunch of invalid entries in
there.

eml: avoid Encode 2.87..3.12 leak

Encode::FB_CROAK leaks memory in old versions of Encode:
<https://rt.cpan.org/Public/Bug/Display.html?id=139622>

Since I expect there's still many users on old systems and old
Perls, we can use "$SIG{__WARN__} = \&croak" here with
Encode::FB_WARN to emulate Encode::FB_CROAK behavior.

t/www_listing: require opt-in for grokmirror tests

grokmirror 2.x seems to idle in several places for 5s at-a-time,
causing t/www_listing.t to take longer than "make check-run" on
a 4-core system when run without grokmirror.  So make it
optional but add some test knobs to allow tailing the log
output so I can see what's going on.

test_common: hoist out tail_f sub

We'll be reusing this in more places.  While we're at it, allow
it to tail all run_script() users, including lei() in TestCommon.

xt/perf-msgview: drop unnecessary use_ok

require_mods covers it, and we're not testing Plack itself.

www: preload: load ExtSearch via ->ALL

This ought to give us more CoW savings and fragmentation
avoidance in -httpd.

extindex: set {current_info} in eidxq processing

This gives context as to where warnings are coming from.

treewide: use warn() or carp() instead of env->{psgi.errors}

Large chunks of our codebase and 3rd-party dependencies do not
use ->{psgi.errors}, so trying to standardize on it was a
fruitless endeavor.  Since warn() and carp() are standard
mechanism within Perl, just use that instead and simplify a
bunch of existing code.

lei: use standard warn() in more places

warn() is easier to augment with context information, and
frankly unavoidable in the presence of 3rd-party libraries
we don't control.

extindex: show OID on bad blob failure

AFAIK I've never hit these messages, but I might be glad
if I ever do.

daemon: set $SIG{__WARN__} properly

Eml->warn_ignore_cb itself returns a callback, so creating a
reference to it was wrong when assigning it to $SIG{__WARN__};

Fixes: 176cd51f9aa81b74 ("daemon: quiet down Eml-related warnings")

lei up --all: show output for warnings

This helps users make sense of which saved searches some
warnings were coming from.

Since I often create and discard externals, some warnings
from saved searches were confusing to me without output context:

  "`$FOO' is unknown"
  "$FOO not indexed by Xapian"

doc: relnotes: note some recent improvements

index: optimize after all SQLite DB commits

This covers v1 inboxes, as well.  We also guard the execution
since "PRAGMA optimize" was only introduced in SQLite 3.18.0
(2017-03-30)

lei/store: use remove_doc to save some LoC

extindex: flush pending reindex before unref

This prevents unnecessary message renumbering and I/O.

Without this change, there is a small window for long-running
WWW streaming requests to miss a message that was unref-ed
before reindexing.  If we expose an "All Mail" mailbox via
IMAP/JMAP, this will save client traffic.

www: _/text/config/raw Last-Modified: is mm->created_at

This allows IMAP mirrors to keep UIDVALIDITY synchronized (and
"LIST ACTIVE.TIMES" in NNTP).  "lei add-external --mirror" will
automatically set it, as will the combination of
public-inbox-clone + public-inbox-index.

This avoids the need for extra endpoints or config entries,
at least...

msgmap: ->new_file to supports $ibx arg, drop ->new

The original Msgmap->new API was v1-specific and not necessary.
The ->new_file API now supports an $ibx object being passed to
it, simplify -no_fsync use.  It will also make an upcoming
change easier...

daemon: unconditionally close Xapian shards on cleanup

The cost of opening a Xapian DB (even with shards) isn't high,
so save some FDs and just close it.  We hit Xapian far less than
over.sqlite3 and we discard the MSet ASAP even when streaming
large responses.

This simplifies our code a bit and hopefully helps reduce
fragmentation by increasing mortality of late allocations.

msgmap: share most of check_inodes w/ over

We still need to account for msgmap being open all the time
and not having separate read-only vs. read-write packages.

msgmap: use DBI->prepare_cached

msgmap is not performance-critical enough to justify doing our
own prepared statement caching.  Just rely on the functionality
of DBI here so future changes will be easier.

There's also minor style changes to avoid dirtying refcount
cache lines bumping by repeating hash lookups rather than attempting
to store them as locals.

nntp: use defined-OR from Perl 5.10 for msgid check

"<0>" could be a valid Message-ID, maybe...

search: delete QueryParser along with DB handle

Xapian::QueryParser is attached to the Xapian::Database,
so holding onto the QueryParser was preventing us from
releasing DB handles if a query was performed.

daemon: quiet down Eml-related warnings

Email::Address::XS is quite noisy and there's nothing we can
really do about messages we're serving from read-only daemons.

daemon: use v5.10.1, disable local warnings

We're moving towards relying on "perl -w" for warnings and
v5.12 for strict.

isearch: do not access Extsearch->{over} directly

It may not exist due to periodic cleanup to avoid excessive FD use.

extindex: avoid invalid blobs after unref

When unref-ing a blob from xref3, make sure the "preferred"
smsg->{blob} doesn't point to the blob we just unrefed.  This
is necessary because we periodically checkpoint our extindex
process to allow -watch and -mda processes to run.

This also gets rid of a lot of redundant code for ->remove_xref3,
since it's all handled in ExtSearchIdx, now.

extindex: more consistent doc removal

We need to ensure a message is consistently removed from eidxq,
over and Xapian in all cases.  Removing from eidxq saves users
from some noisy error messages.

extindex: share unref logic in more places

We can use the same logic for --gc and --reindex and
'd' log entries

They're similar enough and the actual need to unref should
be fairly rare.  We could go a lot faster if we didn't show
progress for --gc and --reindex, actually.

extindex: rename var: active => active_shards

We also have the idea of active inboxes, too, so "active shards"
ought to make the purpose of the data structure more obvious.

sqlite: PRAGMA optimize on close

As recommended by SQLite documentation[1]:

  To achieve the best long-term query performance without the need
  to do a detailed engineering analysis of the application schema
  and SQL, it is recommended that applications run "PRAGMA optimize"
  (with no arguments) just before closing each database connection.

Hopefully that works for our use cases and can make things
faster for us.

[1] https://www.sqlite.org/pragma.html#pragma_optimize

extindex: speed up --reindex --fast

This required some tweaking of xref3 indices in over.sqlite3,
but the end result is it brings no-op "--reindex --fast --all"
checks down to roughly 20 minutes (from 30-40 minutes) on
lore/all.

This is faster because a bunch of small SQLite queries are still
slower en-mass than a bunch of perlops.  Despite the lack of IPC
overhead, crossing .so boundaries and repeating lookups over
btrees is still slower than doing the same with Perl hash tables.

doc: lei-refresh-mail-sync: drop repeated word

extindex: sync each inbox before checking for missed messages

Otherwise, it gets too noisy and we repeat some work
when we do an actual sync, since the last_commit info
will be out-of-date.

lei/store: keep ".err-XXXX" in stderr tmpfile

This is slighly more meaningful since the file is already
in ~/.local/share/lei/store, so "lei_store" was redundant
(and the "XXXX" are random characters replaced by File::Temp)

extindex: --gc doesn't touch ghost entries

We were deleting ghost entries, this was usually harmless since
other messages could fill-in-the-blanks, but could cause
misthreading in odd cases where a big chunk of a thread is
missing and the latest messages only referenced ghosts.

We'll also save some cycles when scanning Xapian shards since
docids won't be <= 0.