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.

extindex: minor cost reductions

Don't bother decoding the 20-byte SHA-1 to a 40-byte hex value
since we don't read it, anyways.  We can also use the on-stack
ibx->eidx_key value instead of dispatching the method again.

extindex: speed up Xapian cleanup in --gc

Avoiding repeated SQL statements brings --gc down to 2-3 minutes
from around 10.  We'll also add some checkpoints around over and
xref3 cleanups.

set nodatacow on more SQLite files

We'll set nodatacow when detecting existing but empty
files, and also their directories in more cases (for
auxiliary -wal, -journal, -shm files).  Hopefully
this keeps performance reasonable on CoW FSes.

admin: add '# ' prefix for progress messages

It's more consistent with TAP output and hopefully puts
users at ease in case they don't understand the meaning
of a message.

lei_to_mail: show --output on augment progress failure

Just in case it fails when there's many parallel invocations.

extindex: support --reindex --fast

This mode only checks history for missed/stale messages
and doesn't attempt to reindex messages which are already
indexed.

view: save memory by dropping smsg->{from_name} on use

We'll also save a few LoC when generating it.  $smsg objects can
linger a while when rendering large threads, so saving a few
bytes here can add up to several hundred KB saved.

I noticed this while chasing the ref cycle leak in commit
b28e74c9dc0a (www: fix ref cycle from threading w/ extindex, 2021-10-03).
While there's no longer a leak, releasing memory earlier can
allow it to be reused sooner and reduce both memory traffic and
memory pressure.

http: avoid Perl target cache for psgi.input

By using syswrite to populate env->{psgi.input}.  The substr()
call IO::Handle->write will trigger Perl's target/scratchpad and
result in a permanent allocation.  Since this is a cold path,
that allocation is pointless, and syswrite() can already write a
substring.

Allowing Perl to cache a large allocation in a cold path only
result in fragmentation and wasted RAM.

write(2) on a regular file won't result in short writes
unless the FS quotas or free space limits are hit, or the buffer
is close to overflowing (e.g. the 0x7ffff000-byte Linux limit).
Since our HTTP server will never buffer that much in RAM,
there's no need to retry syswrite nor rely on the retrying
implicit in IO::Handle->write and the "print" perlop.

view: discard Eml->{bdy} when done using

We can release the raw body buffer once we've obtained a copy of
the decoded buffer.  This reduces memory pressure ahead of some
expensive diff processing.

solver_git: shorten scalar lifetimes

Some of these scalar buffers may be large patches, so try
to keep them as short-lived as possible to reduce memory
pressure.

net_reader: hoist out _imap_fetch_bodies

We'll be supporting pipelining in a future commit, since
Tor is too slow and increasing batch size can use too much
memory.

git: fatalize async callback errors by default

This should help us catch BUG: errors (and then some) in
-extindex and other read-write code paths.  Only read-only
daemons should warn on async callback failures, since those
aren't capable of causing data loss.

git: async_abort includes --batch-check requests

We need to abort both check-only and cat requests when
aborting, since we'll be aborting more aggressively
in in read-write paths.

git: use async_wait_all everywhere

Some code paths may use maximum size checks, so ensure
any checks are waited on, too.

overidx: each_by_mid: account for messages being deleted

This may fix some extindex problems and should get rid of
the "Can't bless non-reference value" errors.

ds: tmpio: avoid Perl target cache

The use of `substr' here an argument to `print' was causing Perl
to internally cache its target buffer.  Since `syswrite()'
already offers a buffer offset arg and length limits, just use
`syswrite' directly.  We were using autoflush anyways, so the
lack of buffering was of no concern performance-wise.

The target buffer could get to roughly ~10MB under some loads,
but it was usually a cold path and using memory which cannot be
released nor reused in other places.

note: IO::Handle::write uses `substr' internally, too;
so nothing would be gained using IO::Handle:write.

msg_iter: split_quotes adds trailing "\n"

The regexp in split_quotes relies on the presence of a
final "\n", so add it wherever we need to instead of
making it the responsibility of every caller.

This probably doesn't matter in practice since every
email seems to have a "\n" as the final byte (due to
the way SMTP works), but maybe there's some odd ones
that'll get imported via lei.

overidx: subject_path: allow non-ASCII char in subject matches

This should bring us closer to the "Base subject" definition in
IMAP ORDEREDSUBJECT (RFC 5256 2.1).  Larger changes may cause
some breakage (until --reindex).  But for now, a reindex will
prevents the non-ASCII subjects from being normalized to the
same fuzzy "thread" in the thread view.

extindex: --gc checkpoints

We need to ensure -extindex --gc runs don't prevent other
work from happening in the meantime.  I actually caused
my -extindex to OOM due to the lack of checkpoints :x

We'll also hoist out the shard scanning into its own sub
in preparation for lei/store usage.

xt/perf-msgview: modernize, support TEST_BLOB

This helped me quickly reproduce a bug in Encode[1] and
will help me determine performance implications of workarounds
for the aforementioned bug.

[1] https://rt.cpan.org/Public/Bug/Display.html?id=139622

index: --reindex w/ --{since,until,before,after}

This lets administrators reindex specific time ranges
according to git "approxidate" formats.  These arguments
are passed directly to underlying git-log(1) invocations
and may still reach into old epochs.

Since these options rely on git committer dates (which we infer
from the most recent Received: header), they are not guaranteed
to be strictly tied to git history and it's possible to
over/under-reindex some messages.  It's probably not a major
problem in practice, though; reindexing a few extra messages
is generally harmless aside from some extra device wear.

Since this currently relies on git-log, these options do not
affect -extindex, yet.

extsearchidx: favor 20-byte OID comparison

As with most of our internal-only code, favor smaller
comparisons to reduce memory traffic.

overidx: update comment for new sub name

`shard_remove_eidx_info' was made unnecessary with commit
82b805db3ad9 (searchidxshard: IPC conversion, part 2, 2021-01-03)
and we now call `remove_eidx_info' directly.

{dir,inbox}idle: use level-triggered epoll

Both read(2) on inotify and kevent(2) return a finite amount of
events.  Let the kernel notify us again in cases where we'd
need to retry instead of looping ourselves.  This can prevent
missed/delayed notifications while still ensuring fairness in
busy event loops.

hl_mod: don't memoize highlight::codeGenerator objects

Making them immortal doesn't seem worth it, since doing immortal
allocations after process startup leads to fragmentation.  While
the allocations made by highlight are small, those small
allocations can break up contiguous regions and prevent
consolidation by the malloc implementation.

Since instantiating code generators doesn't seem too expensive,
just use and delete them ASAP.

www: fix ref cycle from threading w/ extindex

Unlike v1 inboxes (which don't accept duplicate Message-IDs at
all), and v2 inboxes (which generate a new Message-ID for
duplicates), extindex must accept duplicate Message-IDs as-is.

This was fine for storage, but prevented the reference-cycle
mechanism of our message threading display algorithm from working
reliably.  It could no longer delete the ->{parent} field from
clobbered entries in the %id_table.

So we now take into account reused Message-IDs and never clobber
entries in %id_table.  Instead, we mark reused Message-IDs as
"imposters" and special-case them by injecting them as children
after all other threading is complete.

This cycle was noticed using a pre-release of Devel::Mwrap::PSGI:
  https://80x24.org/mwrap-perl.git

t/thread-cycle: make Email::Simple optional

We only use it if Mail::Thread is available, and often it's not.

extsearchidx: emit diagnostics for missing blobs

I'm not sure why they weren't emitted, earlier.

content_hash: normalize whitespace before hashing addresses

This should prevent some false duplicates.  I noticed this
while implementing "lei mail-diff", and only noticed it when
I implemented the ContentDigestDbg wrapper for mail-diff.

lei mail-diff: diagnostic command to diff mail contents

This is useful in finding the cause of deduplication bugs,
and possibly the cause of missing threads reported by
Konstantin in <20211001130527.z7eivotlgqbgetzz@meerkat.local>

usage:

  u=https://yhbt.net/lore/all/87czop5j33.fsf@tynnyri.adurom.net/raw
  lei mail-diff $u

extsearchidx: attach_config: set {ibx_map} value to $ibx

It doesn't seem to matter, actually, but this matches the
behavior of attach_inbox and the comment in ->new.

lei inspect: fix "mid:" prefix, expand to Xapian

This fixes inspect for uninitialized instances, and adds Xapian
("xdoc") output if available.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Message-ID: <20211001204943.l4yl6xvc45c5eapz@meerkat.local>

lei inspect: integerize "bytes" and "lines" fields

These are always numeric, but none of the Perl code cares;
we want to prevent JSON from quoting them.

extsearchidx: do not process eidxq w/o config

When indexing a single inbox, do not attempt reindexing code
paths without a full config, otherwise ordering comparisons
won't work.

doc: lei-daemon: new manpage

In case users see "lei-daemon" in ps(1) or syslog and wonder.

Helped-by: Kyle Meyer <kyle@kyleam.com>

ds: inline set_cloexec

I'm thinking we can drop support for Linux <2.6.27 soonish and
just use EPOLL_CLOEXEC.  Perl without signalfd (or
EVFILT_SIGNAL) is miserable, actually.

inbox: keep DB handles if git processes are live

Having git processes outlive DB handles is likely to hurt
from a fragmentation perspective if the DB handle needs to
be recreated immediately due to a git->cat_async callback.
So only unref DB handles when we're sure there's no live
git users left, otherwise check the inodes.

We'll also avoid needless localization checks in git->cleanup
and make the return value more obvious since the pid fields are
unconditionally deleted nowadays.

inbox: inline and eliminate git_cleanup

It was probably incorrect to use from max_git_epoch, and it's
small enough to inline into do_cleanup.  We'll also eliminate
the unnecessary deletion of {-altid_map} while we're in the
area, since we no longer cache/memoize that.

Fixes: 7e5cea05f061e757 ("inbox: rewrite cleanup to be more aggressive")

ds: simplify signalfd use

Since signalfd is often combined with our event loop, give it a
convenient API and reduce the code duplication required to use it.

EventLoop is replaced with ::event_loop to allow consistent
parameter passing and avoid needlessly passing the package name
on stack.

We also avoid exporting SFD_NONBLOCK since it's the only flag we
support.  There's no sense in having the memory overhead of a
constant function when it's in cold code.

ipc: run Net::SSLeay::randomize

Currently we don't use OpenSSL from child processes of parents
which use OpenSSL, but we may in the future.  So ensure OpenSSL
initializes its PRNG after these forks to avoid one security
pitfall down the line.

daemon: make SO_ACCEPTFILTER a shared variable

Constant subroutines use more memory and there's no need to
optimize it for inlining since it's only used at startup.

listener: switch to level-triggered epoll

On second thought, the ->requeue + accept retry code path isn't
worth the userspace complexity and overhead.  Level-triggered
epoll has always annoyed me since it takes an inefficient code
path in the kernel; but taking our less-efficient code path in
Perl seems even worse.  We also need to take load distribution
into account for multi-worker systems.

doc: lei-security: some more updates

Virtual users will probably be used for read-write IMAP/JMAP
support.  The potential for various kernel/hardware bugs and
attacks also needs to be highlighted.

search_view: various navigation tweaks

This improves the "&x=t" navigation between the thread overview
(skeleton) section at the bottom and jumping back to the top for
the mbox download form.  The "--links below ..." text ought to
be helpful for users unfamiliar with the /$MSGID/T/ and /$MSGID/t/
views.

git: shorten --git-dir= in CLI with chdir in spawn

Long pathnames are difficult to read and distinguish in ps(1)
output.  Deep paths can also slow down pathname resolution
when dealing with loose objects, so we put "cat-file --batch"
deeper into the directory tree.

Since v2 processes are in the form of $INBOXDIR/all.git, keep
the basename of $INBOXDIR in --git-dir= so it's easy to
distinguish between processes just by looking at ps(1).

While "git -C" also exists, it's only present in git 1.8.5+.
We also need to keep in mind the "directory" pointed to by
--git-dir= need not be a directory (nor a symlink pointing
to one).

This reduces pathname resolution overhead for v1 and v2 inbox
git processes, but unfortunately not for extindex since that
needs to store alternates as absolute paths.

ds: drop ::later support

add_uniq_timer seems sufficient, and we'll drop the last
user of ::later (IMAP) and switch to unique timers.

ds: simplify idle time expiry, slightly

While it doesn't look like $EXPMAP can be populated in
non-obvious ways via ->DESTROY, it still makes sense to keep it
close to some of our other code around cleanup to reduce
the likelyhood of subtle bugs in case semantics change..