searchview: convert nested and Atom display to over.sqlite3

git blob retrieval dominates on these, "&x=t" (nested) is
roughly the same due to increased overhead for ->get_percent
storage balancing out the mass-loading from SQLite.

Atom "&x=A" is sped up slightly and uses less memory in the
long-lived response.

searchview: speed up search summary by ~10%

Instead of loading one article at-a-time from over.sqlite3, we
can use SQL to mass-load IN (?,?, ...) all results with a single
SQLite query.  Despite SQLite being in-process and having no
network latency, the reduction in SQL query executions from
loading multiple rows at once speeds things up significantly.

We'll keep the over->get_art optimizations from the previous
commit, since it still speeds up long-lived responses, slightly.

searchview: use over.sqlite3 instead of Xapian docdata

This is a step towards improving kernel page cache hit rates by
relying on over.sqlite3 for document data instead of Xapian.
Some micro-optimization to over->get_art was required to
maintain performance.

smsg: reduce utf8::decode call sites

Both callers of load_from_data call utf8::decode, so just
do utf8::decode in load_from_data.

search: make qparse_new an internal function

We'll probably be reusing it from another package in a future commit.

searchquery: split off from searchview

Since this was already a separate package, split it off
into its own file since SearchView may not handle inbox
groups.

search: export mdocid subroutine

No need to have awkward globrefs for this.

search: improve comments around constants

We'll probably be adding more value columns like THREADID to sort
on.

www: reduce long-lived PublicInbox::Search references

While this is unlikely to be a problem in current practice,
keeping Xapian DBs open for long responses can interfere with
free space recovery after -compact.

In the future, it will interfere with inbox search grouping
and lead to unexpected results.

xapcmd: simplify {reindex} parameter passing

No need to localize it, here, since we can just refer to it
in the `$opt' hashref.  Hopefully this improves readability
for others like it does for me.

I sometimes wonder if the concept of a stack in high-level
languages is even necessary...

search: v2: ensure shards are numerically sorted

This seems required to correctly get the NNTP article number
from Xapian docid on combined Xapian DBs.  The default
(ASCII-betical) sorting was only acceptable for -imapd users
until somebody hit 11 (or more) shards, which is a rare case.

init: drop -N alias for --skip-artnum

It may be too easily confused for --newsgroup or --ng.  This is
too rarely used and never made it into a release, so it should
be fine.

init: support --newsgroup option

We can reduce the need to edit the config file for NNTP group names
this way.

init: support --help and -?

And speed those up with some lazy loading, too.

compact: support --help/-? and perform lazy loading

This probably won't be used much, but --help can still
make sense.

admin: progress shows the inbox being indexed

This is helpful with --all, or when multiple inboxes
are being indexed.

doc: note -compact and -xcpdb are rarely used

Slowly improving the learning curve...

v2writable: show newline after "indexing all of .. " message

Otherwise things get very confusing when verbosity is enabled :x

smsg: handle wide characters in raw mail headers

There may be messages in the wild with wide characters in
headers which aren't non-RFC2047 encoded.  Assume UTF-8 so
those fields can round trip through over.sqlite3.

This doesn't affect docdata.glass in Xapian, but it does
affect how over.sqlite3 stores the same deflated info.

doc: add public-inbox-tuning(7) manpage

Determining storage device speed and latencies doesn't
seem portable or even possible with the wide variety
of storage layers in use.

This means we need to write a tuning document and hope
users read and improve on it :P

grok-pull.post_update_hook: favor --sequential-shard for HDD

--sequential-shard offers better performance on HDD than -j0
since the on-disk active set can be kept small (with -j $HIGH_NUM).
--batch-size can also be helpful for systems with much RAM.

index|compact|xcpdb: support --all switch

For -index, this is a convenient way to quickly index all
inboxes after a grok-pull.  Might as well support it for
rarely used commands like -compact and -xcpdb, too.

v2writable: remove IdxStack import

We use IdxStack via log2stack() from SearchIdx, now.

xcpdb: wire up new index options and --help

--sequential-shard also disables the copy parallelism (--jobs),
so it can be useful for systems unable to handle parallel random
I/O but still want many shards.

There was a missing "use strict", too, which is fixed.

admin: don't warn when --jobs exceeds shards

Established tools like make(1), prove(1) and xargs(1) don't warn
when the desired parallelism level can't be met, either.

xapcmd: reduce CPU idling when shards exceeds job count

In case there's unbalanced shards AND we're limiting parallelism
while using many shards, spawn the next task in the queue ASAP
once a task is done, instead of waiting for all tasks to finish
before spawning the next batch.

Unbalanced shards probably isn't a big issue for most users;
however many smaller shards with few jobs can be useful for HDD
users to reduce the effect of random writes.

xcpdb: support --no-fsync from CLI

This was omitted in 8b1950055d51d436 :x

Fixes: 8b1950055d51d436 ("index+xcpdb: rename `--no-sync' to `--no-fsync'")

xapcmd: simplify sub reference

We don't need to fully-qualify when referring to subs in
the same namespace, nor do we need make a SCALAR ref only
to dereference it

(Yes, still learning Perl :x)

convert: set No_COW on copied SQLite files

We'll use our existing logic and use sqlite_backup_from_file,
which appeared in 1.39 (along with sqlite_backup_to_file).

convert: check ARGV more correctly

Instead of silently ignoring excessive args, don't let a user
specify an extra directory.  Furthermore, we'll support the odd
case where BOFH wants to name an $INBOX_DIR to be `0' :P

convert: speed up --help

Lazy-loading dependencies speeds up --help by several hundred
milliseconds and is a huge step towards user-friendliness.

convert: support new -index options

Converting v1 inboxes from v2 can be a painful experience
on HDD.  Some of the new options in the CLI or config
file make it less painful.

searchidx: use singular `$opt' for consistency with v2

The rest of our indexing code uses `$opt' instead of `$opts'.

index: cleanup internal variables

Move away from hard-to-read alllowercase naming and favor
snake_case or separated-by-dashes.

We'll keep `--indexlevel' as-is for now, since it's been around
for several releases; but we'll support `--index-level' in the
CLI and update our documentation in a few months.

We'll also clarify that publicInbox.indexMaxSize is only
intended for -index, and not -watch or -mda.

admin: use a generic variable name

We parse other options, too, not just --max-size

avoid File::Temp::tempfile in more places

We can use open(..., undef) natively in Perl in t/import.t

In places where we need a pathname, the File::Temp OO API
gives us auto-unlinking for free.

msgmap: tmp_clone: simplify + meaningful filename

Trying to use the newer ->sqlite_backup_to_dbh method doesn't
seem worth it, as we'll have to support DBD::SQLite <= 1.60
another decade or more.

Dumping 'msgmap-XXXXXXX' into $INBOX_DIR can appear a bit
confusing to users, so give it a "mm_tmp-$PID-XXXXXXXX" name
to emphasize it's a temporary file tied to a given PID.

We also don't want to penalize read-only daemons with
loading File::Temp, so do it lazily.

index+xcpdb: improve SIG{INT,TERM,HUP,PIPE} behavior

-index now invokes ->DESTROY like xcpdb does, which is necessary
to cleanup $INBOX_DIR/msgmap-XXXXXXX files.  We'll also exit
with the expected values for various signals by adding 128
as described in <https://www.tldp.org/LDP/abs/html/exitcodes.html>

-xcpdb now terminates worker processes and xapian-compact(1)
invocations when prematurely killed, too.

doc: add some notes around -xcpdb / -edit / -purge

These rarely-used commands have some caveats that needed
expanding on.

doc: index: more notes about latest changes

With LKML on an HDD, a giant --batch-size of 500m ends up being
pretty useful.  I was able to index LKML in ~16 hours on a
system that had other activity on it.  The big downside was it
was eating up over 5g of RAM :x.

We'll also fix up a duplicated indexBatchSize section, fix
formatting around global vs per-inbox indexSequentialShard,
and ensure section 5 manpages are linked correctly.

index: --sequential-shard works incrementally

We should never reindex all data in Xapian unless --reindex is
specified on the command-line.  This means users who put
publicInbox.indexSequentialShard in their config file won't have
to put up with a full reindex at every invocation, only when
they specify --reindex.

We'll also cleanup the progress output to not emit non-sensical
ranges where the starting number is higher than the end.

index: require --reindex when using --xapian-only

This to avoid user error of a currently undocumented switch;
since --xapian-only always goes through the full history at
the moment.

favor `getconf _NPROCESSORS_ONLN` over GNU nproc

getconf(1) itself is POSIX, while `_NPROCESSORS_ONLN' is not.
However, FreeBSD (tested 11.4 and 12.1) and glibc (tested CentOS
7.x and Debian 10.x) both support `getconf _NPROCESSORS_ONLN'.

GNU coreutils (and thus `nproc' or `gnproc') are not installed
by default on the *BSDs, so we'll try the option most likely
to exist on both glibc and *BSDs out-of-the-box.

dir_idle: require Perl 5.22+ for kqueue

IO::KQueue requires us to use fileno(DIRHANDLE) for setting up
kqueue watches.  This use of fileno() is only supported since
Perl 5.22, so BSD users on older Perl will have to fall back to
old polling.

This affects users of -watch, currently; but will affect other
read-only Xapian users soon.

support setting No_COW on Perl <5.22

fileno(DIRHANDLE) only works on Perl 5.22+, so we need to use
dirfd(3) ourselves from Inline::C (or rely on chattr(1) being
installed).

While we're at it, rename `set_nodatacow' to `nodatacow_fd'
for consistency with `nodatacow_dir'.

index: add built-in --help / -?

Eventually, commonly-used commands run by the user will all
support --help / -? for user-friendliness.   The changes from
up-front `use' to lazy `require' speed up `--help' by 3x or so.

searchidx: use Perl truthiness to detect XAPIAN_FLUSH_THRESHOLD

XAPIAN_FLUSH_THRESHOLD is a C string in the environment, so
users may be tempted to assign an empty string in in their
shell, e.g. `XAPIAN_FLUSH_THRESHOLD= <command>' instead of using
`unset' POSIX shell built-in.

With either a value of "0" or "" (empty string), Xapian will
fall back to its default (10000 documents), which causes grief
for memory-starved users.

index: max out XAPIAN_FLUSH_THRESHOLD if using --batch-size

If XAPIAN_FLUSH_THRESHOLD is unset, Xapian will default to
10000.  That limits the effectiveness of users specifying
extremely large values of --batch-size.

While we're at it, localize the changes to globals since -index
may be eval-ed in tests (and perhaps production code in the
future).

index: --compact respects --sequential-shard

Since the --compact switch works on Xapian shards,
it makes sense that --sequential-shard affects our
usage of xapian-compact(1).

v2writable: fix batch size accounting

We need to account for whether shard parallelization is
enabled or not, since users of parallelization are expected
to have more RAM.

index+xcpdb: rename `--no-sync' to `--no-fsync'

We'll continue supporting `--no-sync' even if its yet-to-make it
it into a release, but the term `sync' is overloaded in our
codebase which may be confusing to new hackers and users.

None of our our code nor dependencies issue the sync(2) syscall,
either, only fsync(2) and fdatasync(2).

index: support --xapian-only switch

This is useful for speeding up indexing runs when only Xapian
rules change but SQLite indexing doesn't change.  This mostly
implies `--reindex', but does NOT pick up new messages (because
SQLite indexing needs to occur for that).

I'm leaving this undocumented in the manpage for now since it's
mainly to speed up development and testing.  Users upgrading to
1.6.0 will be advised to `--reindex --rethread', anyways, due to
the threading improvements since 1.1.0-pre1.

It may make sense to document for 1.7+ when there's Xapian-only
indexing changes, though.

index: v2: --sequential-shard option

This gives better page cache utilization for Xapian indexing on
slow storage by improving locality for random I/O activity on
the Xapian DB.

Instead of doing a single-pass to index both SQLite and Xapian;
this indexes them separately.  The first pass is identical to
indexlevel=basic: it indexes both over.sqlite3 and msgmap.sqlite3.

Subsequent passes only operate on a single Xapian shard for
documents belonging to that shard.  Given enough shards, each
individual shard can be made small enough to fit into the kernel
page cache and avoid HDD seeks for read activity.

Doing rough tests with a busy system with a 7200 RPM HDD with ext4,
full indexing of LKML (9 epochs) goes from ~80 hours (-j0) to
~30 hours (-j8) with 16GB RAM with 7 shards configured and fsync(2)
disabled (--no-sync) and `--batch-size=10m'.

v2writable: fix rethread cleanup

We need to drop old ghosts properly while inside the
transaction, otherwise it becomes a no-op.  This isn't a big
deal, as it only results in a few dangling DB rows and a
small amount of wasted space.

xapcmd: drop outdated comment

We replaced Xtmpdir with File::Temp->newdir in
commit 2a3e3a0469f54f6a4f80bf04614e5ddd794a6c5e
("xapcmd: replace Xtmpdirs with File::Temp->newdir")
but forgot to remove the outdated comment.

xapcmd: remove redundant searchidx require

We already "use" it starting with commit
cd8dd7b08fddc7c2b5f218c3fcaa5dca5f9ad945
("search: support SWIG-generated Xapian.pm"),
so there's no need to require it redundantly.

xapcmd: quietly no-op on indexlevel=basic

I find myself mindlessly adding "-c" to public-inbox-index,
and other users may do the same.  Instead of erroring out,
we'll just silently ignore it, for now and allow
public-inbox-compact to work on SQLite-only inboxes.

We'll only check for xapian-compact if search exists, since
it won't be needed in case we support SQLite VACUUM.

syscall: support sparc64 (and maybe other big-endian systems)

Thanks to the GCC compile farm project, we can wire up syscalls
for sparc64 and set system-specific SFD_* constants properly.

I've FINALLY figured out how to use POSIX::SigSet to generate
a usable buffer for the syscall perlfunc.  This is required
for endian-neutral behavior and relevant to sparc64, at least.

There's no need for signalfd-related stuff to be constants,
either.  signalfd initialization is never a hot path and a stub
subroutine for constants uses several KB of memory in the
interpreter.

We'll drop the needless SEEK_CUR import while we're importing
O_NONBLOCK, too.

imap: search support BODY key

This is specified in RFC 3501 but was accidentally omitted :x
I probably got it confused with TEXT, so add a comment about
TEXT being "everything" in the message.

www: avoid warnings on YYYYMMDD-only t= query parameter

While we always generate YYYYMMDDhhmmss query parameters
ourselves, the regexps in paginate_recent allow YYYYMMDD-only
(no hhmmss) timestamps, so don't trigger Time::Local::timegm
warnings about empty numeric comparisons on empty strings when a
client starts making up their own URLs.

msgmap: tmp_clone: use MEMORY journal upon reconnect

Since reindexing releases the DB handle every indexBatchSize bytes,
we need to ensure we keep the journal in-memory when reopening
the DB since this is throwaway data.

t/epoll: adjust for u64_mod_8 case

epoll_wait_mod8 places a dummy element into the [2] slot of the
nested array, which caused is_deeply to fail.

Tested on aarch64.

watch: quiet some warnings on spam mailboxes

Email::Address::XS and PublicInbox::MsgTime both emit warnings
which are likely to trigger from spam messages.  Since this can
be configured to remove spam, just filter out those warnings to
avoid cluttering up stderr with useless information.

t/indexlevels-mirror-v1: localize ENV change

We don't want ENV changes propagated to other tests
when using t/run.perl via "make check-run"

t/nntpd: do not fork on indexing, test v2

No need to waste resources when doing minimal work.  With
PI_TEST_VERSION=2, this fixes a test failure where
Net::NNTP::DESTROY was getting called in the shard process.

We'll also get rid of an unnecessary use_ok under v2, too.

remove unnecessary ->header_obj calls

We used ->header_obj in the past as an optimization with
Email::MIME.  That optimization is no longer necessary
with PublicInbox::Eml.

This doesn't make any functional difference even if we were to
go back to Email::MIME.  However, it reduces the amount of code
we have and slightly reduces allocations with PublicInbox::Eml.

searchidx: remove v1-only msg_mime sub

We can rely on the newer mids() sub directly and use faster
numeric comparisons for Msgmap unindexing in v1.

inboxwritable: rename mime_from_path to eml_from_path

This is more accurate given we use PublicInbox::Eml instead
of Email::MIME/PublicInbox::MIME, nowadays.

inboxwritable: mime_from_path: reduce `$/' scope and returns

We don't want `local $/' affecting Eml->new, and we can
use implicit returns which may be faster on older Perl.

nntp: fix STAT command

The return value of art_lookup changed but this command wasn't
updated since it wasn't tested.

Fixes: 0e6ceff37fc38f28 ("nntp: support slow blob retrievals")

improve error handling on import fork / lock failures

v?fork failures seems to be the cause of locks not getting
released in -watch.  Ensure lock release doesn't get skipped
in ->done for both v1 and v2 inboxes.  We also need to do
everything we can to ensure DB handles, pipes and processes
get released even in the face of failure.

While we're at it, make failures around `git update-server-info'
non-fatal, since smart HTTP seems more popular anyways.

v2 changes:
- spawn: show failing command
- ensure waitpid is synchronous for inotify events
- teardown all fast-import processes on exception,
  not just the failing one
- beef up lock_release error handling
- release lock on fast-import spawn failure

www: rework async_* to use method table

Although the ->async_next method does not take $self as
a receiver, but rather a PublicInbox::HTTP object, we may
still retrieve it to be called with the HTTP object via
UNIVERSAL->can.

lock: show failure path

This ought to be useful for diagnosing bugs in -watch.

msgmap: disable CoW for tmp_clone, too

The temporary clone starts as large as the full msgmap
and deletes will write to it randomly.  So ensure it
doesn't get fragmented and slower as time goes on.

wwwlisting: fix grep call for match=domain filtering

The grep call in list_match_domain_i returns true for all inboxes,
even ones without a URL that matches the regular expression, because
the qr value passed to grep is not surrounded by slashes.  Add them.

Fixes: 1988d730c0088e8b (config: support multi-value inbox.*.*url)

emergency: create full path to PI_EMERGENCY

It's possible for ~/.public-inbox/ to not exist if PI_CONFIG
points to an alternate location.  Only noticed from the previous
patch fixing t/init.t behavior.

t/init: fix test when ~/.public-inbox/ does not exist

We'll just set the documented PI_EMERGENCY env to
a writable location.

t/imap_searchqp: fix test dependencies

The query parser test pulls in all of the IMAP stuff, so it
has the same dependencies.

xapcmd: -xcpdb and -compact disable CoW, too

This gives an opportunity for users already suffering from CoW
fragmentation to at least get the Xapian DBs off CoW.  Aside
from over.sqlite3 in v1, the SQLite DBs remain untouched; though
VACUUM support may come in the future.

searchidx: disable CoW for SQLite and Xapian under btrfs

SQLite and Xapian files are written randomly, thus they become
fragmented under btrfs with copy-on-write.  This leads to
noticeable performance problems (and probably ENOSPC) as these
files get big.

lore/git (v2, <1GB) indexes around 20% faster with this on an
ancient SSD.  lore/lkml seems to be taking forever and I'll
probably cancel it to save wear on my SSD.

Unfortunately, disabling CoW also means disabling checksumming
(and compression), so we'll be careful to only set the No_COW
attribute on regeneratable data.  We want to keep CoW (and
checksums+compression) on git storage because current ref
storage is neither checksummed nor compressed, and git streams
pack output.

v2writable: use {inboxdir} for msgmap->tmp_clone

Otherwise, a user is more likely to remove the msgmap-XXXXXXXX
SQLite file from $TMPDIR and cause SQLite to error out.

v2writable: support async git blob retrievals

This seems to speed up --reindex on smallish v2 inboxes by about
30% on both HDD and SSD.  lore/git (~1GB) on an SSD even gives a
30% improvement with 3 shards.  I'm only seeing a ~4% speedup on
LKML with a SATA SSD (which is difficult to repeat because it
takes around 4 hours).

Testing LKML on an HDD will take much more time...

examples/grok-pull.post_update_hook: fix description URL

I finally noticed descriptions weren't showing up in my mirrors :x

xt/imapd-mbsync-oimapd: fix noop due to case sensitivity

mbsync was not retrieving anything since it was looking for
"inbox" when we need to return "INBOX" as a special case
for IMAP.

Fixes: 8af34015e9aa94e5 (imap: LIST shows "INBOX" in all caps)

imap: introduce and use Git->async_prefetch

We can keep the git process more active by sending another
request to it while fetch_run_ops() is running.  This
parallelization speeds up mutt's initial FETCH for headers by
around ~35%(!).

t/init.t: don't modify ~/.public-inbox/

Tests for failures should not leave junk temporary files lying
around in a users' ~/.public-inbox/.

On a side note, I'm not sure if PI_DIR is or was ever
necessary.  It's never been documented, so perhaps
using $HOME for this is better...

index: --compact respects --jobs

And -compact supports --jobs=0 like -index to disable parallel
execution.  Running three xapian-compact processes in parallel
on a USB 2.0 HDD is pretty painful.

overidx: fix compatibility with current versions

We still need to use SQL_BLOB to ensure existing versions of
public-inbox can read over.sqlite3 because they're still using
{sqlite_unicode}.  This partially reverts commit
e9fc1290ead44e06d20ff58e0a6acb5306d4fbe2.

Fixes: e9fc1290ead44e06 ("over: unset sqlite_unicode attribute")

v2writable: {unindexed} belongs in $sync state

There's no reason for {unindexed} to persist beyond
an ->index_sync call.

searchidx: $batch_cb => v1_checkpoint

Another closure gone, and we may be able to share more
code with v2 in upcoming commits.

searchidx: support async git check

This allows v1 indexing to run while the `cat-file --batch-check'
process is waiting on high-latency storage.

v2writable: share log2stack code with v1

Another step in making v1 and v2 more similar.

index+xcpdb: support --no-sync flag

This allows us to speed up indexing operations to SQLite
and Xapian.

Unfortunately, it doesn't affect operations using
`xapian-compact' and the compactor API, since that doesn't seem
to support Xapian::DB_NO_SYNC, yet.

searchidx: make v1 indexing closer to v2

We'll switch to using IdxStack here to ensure we get repeatable
results and ascending THREADIDs according to git chronology.
This means we'll need a two-pass reindex to index existing
messages before indexing new messages.

Since we no longer have a long-lived git-log process, we don't
have to worry about old Xapian referencing the git-log pipe
w/o FD_CLOEXEC, either.

searchidx: rename _xdb_{acquire,release} => idx_

The "xdb" prefix was inaccurate since it's used by
indexlevel=basic, which is Xapian-free.  The '_' (underscore)
prefix was also wrong for a method which is called across
package boundaries.

xapcmd: set {from} properly for v1 inboxes

This was a bug, but I'm not sure where it matters, yet, but it
may matter in the future.

v2writable: clarify "epoch" comment

v2writable: get rid of {reindex_pipe} field

Since normal per-epoch indexing no longer holds a "git log"
process open, we don't need to worry about not sharing the
pipe with forked shards when we restart the indexer.

While we're in the area, better describe what `unindex' does,
since it's a rarely-used but necessary code path.

v2writable: use read-only PublicInbox::Git for cat_file

We can reduce the number of parameters we pass around on stack
and make our read-write and read-only code paths more uniform.

search: avoid copying {inboxdir}

Instead, storing {xdir} will allow us to avoid string
concatenation in the read-only path and save us a little
hash entry space.