nntp: fix cross-newsgroup Message-ID lookups

We cannot blindly use the selected newsgroup for
HEAD/ARTICLE/BODY requests using Message-ID, since
those commands look across all newsgroups; not just
the selected one (if any).

So stuff a reference to the Inbox object into $smsg.
We can reduce args passed into set_nntp_headers() and
msg_hdr_write(), too.

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

wwwstream: fix "Atom feed" link

Oops, I wanted to stop escaping double-quotes with `qq()' but
used `q()' instead :x

Fixes: 2f61828fcb727e51 ("www: make mirror instructions more prominent")

contrib/css: limit <a> coloring to links, only

We don't want <a> tags without href= attributes to be colored,
since the `<a id=mirror>' tag in the HTML footer is intended
as an anchor destination for `<a href=#mirror>' link at the
top.

www: make mirror instructions more prominent

In order to fight the misconception that public-inboxes are
centralized, anchor "#mirror" to the clone instructions and
place an emphasis on "mirror", not just cloning.

While we're at it, better describe multi-epoch -V2 inboxes,
since some users do not seem to realize epochs consist of
different data.

v2writable: reuse read-only shard counting code

We'll also fix the read-only code to ensure we notice missing
Xapian shards, since gaps would throw off our expectation that
Xapian document IDs and NNTP article numbers are interchangeable.

overidx: document column uses

This may be useful for keeping our heads on straight dealing
with IMAP, NNTP, JMAP, etc.

wwwaltid: drop unused sqlite3_missing function

It's inlined into the main function, which we'll shorten
slightly with the defined-or (`//') operator.  Also noticed
and fixed a mismatched HTML tag.

imap: drop old, pre-Parse::RecDescent search parser

We switched to Parse::RecDescent during development and left
some dead code behind.

search: remove {over_ro} field

Only inbox accesses the read-only {over}, now, instead of going
through ->search.  This simplifies our object graph and avoids
potentially redundant FDs and DB handles pointing to the same
over.sqlite3 file.

search: replace ->query with ->mset

Nearly all of the search uses in the production code rely on
a Xapian mset iterator being returned (instead of an array
of $smsg objects).  So default to returning the mset and move
the burden of smsg array conversion into the test cases.

tests: add "use strict" and declare v5.10.1 compatibility

strict.pm helped me find a typo in an upcoming recent change, so
ensure we use it since it does more good than harm.  We'll also
take the opportunity here to declare v5.10.1 compatibility level
to future-proof against Perl incompatibilities.

search: remove special case for blank query

The special case (if any) belongs at a higher-level,
and this is another step towards removing {over_ro}-dependence
in our Search object.

use more idiomatic internal API for ->over access

{over_ro} being a part of the Search object is a historical
oddity which will go away, soon.  Lets start removing its use in
tests and rarely-used helper scripts.

disambiguate OverIdx and Over by field name

We'll use {oidx} as the common field name for the read-write
OverIdx, here, to disambiguate it from the read-only {over}
field.  This hopefully makes it clearer which code paths are
read-only and which are read-write.

msgmap: note how we use ->created_at

It'll likely be used in the future for JMAP, detached indices,
and maybe other things.

t/run: Perl future proofing

Bareword file handles outside of STD(IN|OUT|ERR) seem to be on
the chopping block for Perl 8.  We'll also "use v5.10.1" to
guard against future incompatibilities.

init+convert: create non-existing directory hierarchies

Following "git init" as an example, we'll create every parent
path up to the one specified, instead of attempting to continue
on when Cwd::abs_path returns `undef'.

doc: remove B<> (bold) markup from the remaining POD

B<> decreases readability of the POD source and is of dubious
usefulness in the man page.

watch: add --help/-h support

And avoid unnecessary POD markup in the man page.

config: use defined-or (//) in a few places

Just some golfing to reduce scrolling and hopefully readability.

mda+learn: add --help / -h support

"use Getopt::Long" doesn't seem too slow on a hot page cache,
and it's probably used frequently enough to be in cache.

We'll also start reducing the amount of markup in the .pod and
favoring verbatim text in documentation for readability in
source form, since the bold text seems excessive.

daemon: support --help/-h in -httpd/imapd/nntpd

For consistency with other commands, though the
protocol-specific options should refer users to
the manpage.

script/*: fold $usage into $help, support `-h' instead of -?

`-h' doesn't conflict with anything, and some users (including
git users) may be more accustomed to using it rather than the
rarely-seen-outside-of-Getopt::Long `-?' switch.

We can also rely on the GetOptions() function to emit a proper
error message instead of just "bad command-line args".

edit+purge: support `--help' and `-h' like other commands

And while we're at it, note edit is *destructive* to encourage
reading the fine manual.

admin: improve minimum version text

"inboxes 1 inboxes not supported by ..." was non-sensical.
Now it'll show "-V1 inbox not supported by ...", instead.

script/*: set executable bit on -learn and -imapd

It's useful to mark they're meant to be executable, even
if the shebang is useless.

t/v2dupindex: test indexing mirrors with duplicate messages

While it's not a known problem, our deduplicating logic may
change in the future; or a BOFH could be manually injecting
duplicate messages directly into the git epoch repositories.

Ensure indexing in mirrors doesn't break when there's
duplicates.  This is in preparation for detached indices
for multi-inbox search.

index: check for xapian-compact when using --compact

Otherwise, users may be frustrated to discover it missing
a long indexing run.

replace ParentPipe with EOFpipe

ParentPipe was a subset of EOFpipe, except EOFpipe correctly
accounts for theoretical(*) spurious wakeups on the pipe.

(*) AFAIK, spurious wakeups are/were more likely on TCP sockets
    due to checksum failures, something that's not a problem on
    local pipes.  We're also not sharing pipes like we do with
    listen sockets on accept(2), so there's no chance of another
    process grabbing bytes (unless we have bugs in our code).

ds: avoid unnecessary timer for waitpid

It doesn't seem necessary, since we won't call dwaitpid()
until we see an EOF.

watch: use EOFpipe to reduce dwaitpid wakeups

It's a bit inefficient to use a pipe, here.  However, using
dwaitpid() on a process that's not expected to exit soon is
also inefficient as it causes excessive wakeups as most of
our inbox-writing code expects synchronous waitpid().

This only affects -watch instances configured for NNTP and IMAP
clients.

ds: avoid excessive queueing when reaping PIDs

We should not enqueue reap_pids() to run more than once per
EventLoop iteration.  We'll start reformatting reap_pids
to tabs, too, since we're no longer Danga::Socket.

We should also be able to remove timer usage for reaping
down-the-line once we stop abusing dwaitpid() in -watch.

watch: comments and tiny cleanups

Get rid of an unused variable, prefix a warning and try to
better document control flow around various callbacks.

watch: block signals before fork on non-signalfd/kevent systems

In case there's non-Linux or BSD users w/o IO::KQueue, we
shouldn't let signal handlers fire in the child processes.

The child processes always assumed signals were blocked by
the parent, so no changes were necessary, there.

watch: avoid unnecessary spawning on spam removals

This should further mitigate lock contention problems
when -watch is configured to watch on a Maildir for spam
while performing a large NNTP import.

There is now a small risk a message won't get removed because if
it's in the current (uncommitted) fast-import batch, but
unlikely given the batch size is now only 10 messages.

If a that small window is hit, flipping the \Seen flag
(e.g. marking it unread, and then read again) will trigger
another removal attempt via IMAP or Maildir.

watch: log signal activities to STDERR

Sometimes it may not be apparent when/if a signal is
processed, this hopefully improves the situation.

We'll also change the process title when we're quitting
to better inform users.

rename WatchMaildir => Watch

This is no longer limited to Maildirs now that IMAP and NNTP
support exist; so give it a shorter name.

watchmaildir: use v5.10.1, drop warnings

Declare 5.10.1 to avoid potential compatibility problems with
Perl 7/8 down the line.  We'll rely on the command-line to set
or drop warnings during development, at least.

watch: limit batch size of NNTP and IMAP workers, too

We don't want to monopolize locks because processes can easily
block each other if using `watchspam' on a Maildir while a big
NNTP or IMAP import is happening.

This can also happen if somebody configured a single inbox to
watch from several sources to merge several mailboxes into one
(e.g. both an IMAP and Maildir are watched).

doc: expand on indexBatchSize regarding fragmentation

And change the documentation reference in -tuning to
point to the -index manpage while we're at it.

imapd: filter out unusable flags from search

Quiet down logs from -imapd when clients are blindly
sending some unsupported flag conditions (e.g. "DRAFT",
"DELETED") specified in RFC 3501.

tests: check-run: fixup un-squashed simplification

Link: https://public-inbox.org/meta/20200828221803.GA89978@dcvr/

tests: check-run: show skipped tests

We'll deduplicate redundant lines and show counts of skipped
tests to ensure it's easy to notice if something is unexpectedly
skipped.

imaptracker: update_last: simplify callers

By making it a no-op if last_uid is not defined.  This isn't a
hot code path, so the extra method dispatch isn't an issue.
It'll save some indentation/wrapping in future commits.

watch: flush changes to inbox before updating IMAPTracker

Data needs to hit inboxes, first.  Otherwise it's possible to
skip messages in case git-fast-import is killed before it sees
"done\n".  Now, -watch will just waste a little bandwidth in
re-downloading a seen message if it's interrupted immediately
before updating IMAPTracker.

Makefile.PL: run check-man for <= 80 columns on check-run, too

I mostly use "make check-run" instead of the slower "make check"
target, nowadays, so add this check to ensure the rendered
manpage is always be visible to more users who need big fonts.

www: more descriptive pagination

Being an easily confused person, I find "next" and "prev"
ambiguous as to whether messages on the next or previous page
will be newer or older than the current page.  Clarify that for
the threaded /$INBOX/ view and search results.

For search results sorted by relevance, we'll use "[>= $SCORE]"
or "[<= $SCORE]" to indicate to indicate directionality.

This also fixes $INBOX/new.html for unindexed v1 inboxes.

www: improve navigation around contemporary threads

Sometimes it's useful to quickly get to threads and messages
which are contemporaries of the current thread/message being
focused on.  This hopefully improves navigation by making:

a) the top line (where $INBOX_DIR/description) is shown
   a link to the latest topics in search results and
   per-thread/per-message views.

b) providing a link to contemporaries ("~YYYY-MM-DD") at
   around the thread overview skeleton area for per-thread
   and per-message views

doc: watch: expand on NNTP and IMAP-specific knobs

There's a few more, but maybe they're too esoteric
to be worth documenting at the moment (batch sizes, timeouts, etc).

doc: move watch config docs to -watch manpage

The -config manpage is a bit long and the -watch stuff is
isolated from the rest of it while we start documenting NNTP and
IMAP support.

I'm not entirely happy with the way IMAP and NNTP are
configured, it's still good enough for small setups.

This also fixes a long-standing misplaced comment about
`publicinboxwatch.spamcheck' affecting all configured inboxes,
that comment was actually for `publicinboxwatch.watchspam'.

We'll omit documenting NNTP for `watchspam', for now, given the
lack of \Seen flags in NNTP and I'm not sure if it's even
useful.  There may not be any newsgroups for sharing confirmed
spam, either...

watch: imap: only remove \Seen spam

This matches the behavior of Maildir `watchspam' handling in not
removing unseen messages.  NNTP can't match this behavior, since
NNTP servers don't store flags, clients do.

doc: speling fickses

doc: document graceful shutdown signals

Same as the read-only daemons.

overidx: inline create_ghost sub

There's no need for this to be a separate sub since there's
only a single caller.  This saves a few kilobytes at least
in short-lived processes.

imaptracker: preserve WAL journal_mode if set by user

It's no problem for most users to enable WAL, here, since
there's only a single process doing both reading and writing
(unlike the read-only daemons).  However, WAL doesn't work on
network filesystems, so it can't be enabled by default.

watchmaildir: ensure I:/W:/E: prefixes in warnings

For consistency in output, any URL/path-context-dependent
prefixes should have the same prefix as the actual warning which
triggered it.

git: show more context info on failures

I'm seeing "read: Connection timed out" from in my syslog from
-httpd.  The fail() calls in PublicInbox::Git seems to be the
only code path of ours which could trigger it...

ETIMEDOUT shouldn't happen on pipes, only sockets; and all of
our socket operations are non-blocking.  So this could be
cgit-wwwhighlight-filter.lua, but that's connecting over
localhost, though on fairly loaded HW.

search: allow testing with current xapian.git and 1.5.x

A `PI_XAPIAN' environment variable is now exposed for testing
purposes.  We'll also deal with the removal of
`NumberValueRangeProcessor' and use `NumberRangeProcessor'
in its place, but continue favoring the old Search::Xapian
since that's all that's packaged for Debian 10.x stable.

msgmap: use v5.10.1

We use the defined-or (`//', `//=') operators in 5.10,
so require 5.10.1 like the rest of our codebase.  Update
an outdated comment while we're at it.

over*: use v5.10.1, drop warnings

v5.10.1 lets us use the lighter parent.pm instead of base.pm,
and we'll rely on the shebang to enable warnings (or not).

While we're in the area, drop a no-longer-necessary import for
PublicInbox::Search, since OverIdx doesn't require search.

over: recent: remove expensive COUNT query

As noted in commit 87dca6d8d5988c5eb54019cca342450b0b7dd6b7
("www: rework query responses to avoid COUNT in SQLite"),
COUNT on many rows is expensive on big SQLite DBs.

We've already stopped using that code path long ago in WWW
while -imapd and -nntpd never used it.  So we'll adjust our
remaining test cases to not need it, either.

over: rename ->disconnect to ->dbh_close

Since we got rid of over->connect, `disconnect' no longer pairs
with it.  So name it after the `close(2)' syscall it ultimately
issues.

over: rename ->connect method to ->dbh

`->connect' is confused with the perlfunc for the `connect(2)'
syscall, and also `DBI->connect'.  Since SQLite doesn't use
sockets, the word "connect" needlessly confuses me.  Give
it a short name to match the field name we use for it, which
also matches the variable name used by the DBI(3pm) and
DBD::SQLite(3pm) manpages.

v2writable: compatibility with SWIG Xapian binding

The SWIG binding won't auto-convert IV/UV to PV like the XS
Search::Xapian binding would, so workaround that shortcoming
for now.

Fixes: a367ec1b15a2458 ("mbox: disable "&t" on existing Xapian until full reindex")

grok-pull.post_update_hook: flock(2) before SQLite check

Unlike DBD::SQLite, the sqlite3(1) CLI does not have a default
busy timeout enabled, so it easily times out while acquiring a
SHARED lock for read-only queries.  We can avoid battery-wasting
polling from the SQLite timeout handler by relying on flock(2)
as we do in our Perl code.

Furthermore, this avoids triggering some locking problems[1]
from a long "SELECT COUNT(*) ..." query and reindex.

While there may be other SQLite-related parallelism issues[1],
this works around one of them by relying on flock(2).

[1] https://public-inbox.org/meta/20200825001204.GA840@dcvr/

over+msgmap: respect WAL journal_mode if set

WAL actually seems to have ideal locking characteristics given
concurrency problems I'm experiencing with --reindex running
in parallel with expensive read-only SQLite queries:
<https://public-inbox.org/meta/20200825001204.GA840@dcvr/>

Unfortunately, we cannot blindly use WAL while preserving
compatibility with existing setups nor our guarantees that
read-only daemons are indeed "read-only".

However, respect an user's the choice to set WAL on their
own if they're comfortable with giving -nntpd/-httpd/-imapd
processes write permission to the directory storing SQLite DBs.

msgmap: use "CREATE TABLE IF NOT EXISTS"

It's fewer queries and matches what we do in OverIdx.

over: skip nodatacow on the journal

This file gets truncated anyhow, so it won't fragment.

doc: 1.6.0 release notes update

A few more things happened, here.

doc: add some more tuning notes

I've learned a thing or three about btrfs in the past few
weeks and remembered some old HDD things, too.

The Xapian MultiDatabase problem will need to be addressed
for 1.7...

searchidx: croak for Xapian DB open failure

croak() can give more context on the failure, and setting
`PERL5OPT=-MCarp=verbose' can force a stacktrace.

examples: add imapd systemd examples

We've got examples for all the other daemons, too!

index: --sequential-shard checkpoints after each shard

There's no reason we'd want Xapian to defer flushing once we've
indexed everything belonging to a particular shard.

mbox: disable "&t" on existing Xapian until full reindex

Expanding threads via over.sqlite3 for mbox.gz downloads without
Xapian effectively collapsing on the THREADID column leads to
repeated messages getting downloaded.

To avoid that situation, use a "has_threadid" Xapian metadata
flag that's only set on --reindex (and brand new Xapian DBs).

This allows admins to upgrade WWW or do --reindex in any order;
without worrying about users eating up bandwidth and CPU cycles.

search: support downloading mboxes results with full thread

Finally, the addition of THREADID for collapsing results
in Xapian lets us emulate the "mairix --threads" feature.
That is, instead of returning only the matching messages,
the entire thread is included in the downloaded mbox.gz

This requires a "public-inbox-index --reindex" to be usable.

searchidx: index THREADID in Xapian

This is the `tid' column from over.sqlite3; and will be used for
IMAP and JMAP search (among other things).

searchidx: put all shard-related stuff in SearchIdxShard.pm

We'll also rename the /^remote_/ prefix to "shard_", since
remote implies the process is on a different host.  These
methods only pass messages to a child process on the same host
OR perform operations within the same process.

searchidxshard: clear $msgref buffer properly

Merely assigning `undef' to a scalar does not free the
underlying buffer memory of a scalar.

searchview: fix mbox.gz downloads for lynx users

Unlike w3m and links, the lynx browser seems to require a `name'
attribute for `<input type=submit>' elements.  Maybe some other
browsers do, too.  The `name' attribute for submit elements
doesn't seem to cause any harm for w3m or links, users, either;
despite not (AFAIK) being part of historical or current HTML
specs.

search: add mset_to_artnums method

We can avoid importing mdocid() in several places by using
this method, simplifying callers.

init+index: support --skip-docdata for Xapian

Since we no longer read document data from Xapian, allow users
to opt-out of storing it.

This breaks compatibility with previous releases of
public-inbox, but gives us a ~1.5% space savings on Xapian
storage (and associated I/O and page cache pressure reduction).

t/nntpd-v2: set PI_TEST_VERSION=2 properly

Numbers are hard :<

smsg: remove from_mitem

We no longer read docdata.glass from anywhere in our code base.

Some adjustments were needed to t/search.t to deal with the
Xapian::WritableDatabase committing at different times, since
our ->query is avoided from PublicInbox::SearchIdx to avoid
needing a {over_ro} field.

mbox: avoid Xapian docdata in search results

Another place where we can reduce kernel page cache overhead
by hitting over.sqlite3 instead of docdata.glass.

extmsg: avoid using Xapian docdata

Once again, over.sqlite3 contains everything necessary for
Message-ID resolution.  Also, Xapian may be completely
unnecessary with the advent of over.sqlite3, but that's for
another time.

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.