doc: add some recommendations around slow HDDs

grok-pull is still painful with serialization on an old USB 2.0
HDD, but at least it can finish with flock(1) and disabling
parallelization.  While parallel "git fetch" doesn't seem so
bad, slow seeks are exacerbated by parallel reads in Xapian.
That means some updates can take days instead of hours.  The
same updates take only seconds or minutes on an SSD.

config: reject `\n' in `inboxdir'

"\n" and other characters requiring quoting and/or escaping in
in $GIT_DIR/objects/info/alternates was not supported in git 2.11
and earlier; nor does it seem supported at all in libgit2.

This will allow us to support sharing git-cat-file or similar
endpoints across multiple inboxes via alternates.

This breaks an existing use case for anybody wacky
enough to put `\n' in the `inboxdir' pathname; but I doubt
this affects anybody.

doc: release notes and version info updates

Update release notes with some features in the 1.6 timeline.

We'll note the version availability of some command-line
options, it may help users who are reading the latest
documentation online but running older versions.

over+msgmap: do not store filename after DBI->connect

SQLite already knows the filename internally, so avoid having it
as a long-lived Perl SV to save some bytes when there's many
inboxes and open DBs.

nntpd+imapd: detect unlinked msgmap

While it's even less common to experience a replaced
msgmap.sqlite3 file, BOFHs may do the darndest things.  This is
another step towards reducing the number of needless wakeups
we need to do in long-lived read-only daemons.

over: unset sqlite_unicode attribute

None of the human-readable strings stored in over.sqlite3
require UTF-8.  Message-IDs do not, nor do the compressed
Subject IDs (sid) we use for Subject-based threading.  And the
`ddd' (doc-data-deflated) column is of course binary data.

This frees us of having to use SQL_BLOB for the `ddd', column,
and will open the door for us to use dbh_new for Msgmap, too.

xapcmd: delay over->check_inodes trigger

We must not trigger wakeups on InboxIdle users until after we've
renamed all files into place.  Otherwise, the InboxIdle caller
may just reopen the old (soon-to-be-unlinked) file.

This fixes occasional test failures in t/nntpd.t

Fixes: f977826a17f8735e ("lock: reduce inotify wakeups")

xt/mem-imapd-tls: avoid EMFILE in -imapd process

Test::More dups standard FDs and may create FDs for other
purposes.  run_mode => 0 lets us rely on FD_CLOEXEC to ensure
-imapd has enough FDs to accept all incoming connections at
the cost of higher (one-off) startup time.

imap: SEARCH fails more gracefully in non-slice mailbox

Instead of returning "BAD program fault", just give the
standard "BAD search not available"... message we show
for mailbox slices.

wwwatomstream: avoid uninitialized warnings for $email

As in Import, we'll fall back to Sender: if From: is missing,
and use the primary_address of the inboxes to indicate the total
absence of those fields.

imap: avoid warnings on non-slice mailboxes

Non-slice mailboxes never have messages themselves,
so we must not assume a message exists when sending
untagged EXISTS messages.

viewvcs: stop checking unused "B" query parameter

The resulting OID ("oid_b") is a required arg and part of
$env->{PATH_INFO}, instead; so it's never part of an optional
query parameter.

hval: to_filename: return `undef' instead of empty string

Returning an empty string for a filename makes no sense,
so instead return `undef' so the caller can setup a fallback
using the "//" operator.

This fixes uninitialized variable warnings because split()
on an empty string returns `undef', which caused to_filename
to warn on s// and tr// ops.

viewvcs: allow "0" as a path name

This means we need to filter out "" from query parameters.
While we're at it, update comments for the WWW endpoint.

doc: standards: link IMAP capabilities and response codes

We'll be implementing some IMAP search/threading extensions in
IMAP and providing analogues over HTTP via JMAP.

t/spawn: fix test reliability

Since Perl doesn't internally use a self-pipe for
sleep/select/poll/etc, wake up every 10ms to ensure
it can see the SIGCHLD; since neither signalfd nor EVFILT_SIGNAL
are always available.

Fixes: 761baa2a300e4268 ("spawn: unblock SIGCHLD in subprocess")

mda: use PublicInbox::Address to extract emails

I'm not sure why this wasn't done in Jun/July 2016 when I was
working on PublicInbox::Address to replace the DoS-vulnerable
Email::Address.

Nowadays, PublicInbox::Address allows using Email::Address::XS
which should be fast and robust.

doc/technical/whyperl: note Perl 7 announcement

Right now[1] the Perl upstream plan is to maintain 5 compatibility
in Perl 7 for at least 5 years[1], and perhaps drop it when Perl 8
comes along.  That said, distros may pick it and maintain 5 on their
own given the vast amounts of perfectly good legacy code out there.

[1] http://nntp.perl.org/group/perl.perl5.porters/257817
[2] http://nntp.perl.org/group/perl.perl5.porters/257565

doc/technical/whyperl: reword bit around installed docs

I originally proposed this rewording to address Leah's comment
but forgot to squash it in :x

Link: https://public-inbox.org/meta/20200408221741.GA10142@dcvr/
Cc: Leah Neukirchen <leah@vuxu.org>

doc: daemon: update documentation around Inline::C

`~/.cache/public-inbox/inline-c' is supported, nowadays
for convenience, but Inline::C usage will remain opt-in.

git: use v5.10.1, parent.pm and Time::HiRes::stat

parent.pm is leaner than base.pm, and Time::HiRes::stat is
more accurate, so take advantage of these Perl 5.10+-isms
since it's been over a year since we left 5.8 behind.

gzipfilter: check http->{forward} for client disconnects

We actually don't do anything with {env} or {'psgix.io'}
on client aborts, so checking the truthiness of '{forward}'
is necessary.

daemon: warn on missing blobs

Since -edit and -purge should be rare and TOCTOU around them
rarer still; missing {blobs} could be indicative of a real bug
elsewhere.  Warn on them.

And I somehow ended up with 3 different field names for Inbox
objects.  Perhaps they'll be made consistent in the future.

gzipfilter: drop HTTP connection on bugs or data corruption

While all the {async_next} callbacks needed eval guards anyways
because of DS->write, {async_eml} callbacks did not.

Ensure any bugs in our code or data corruption result in
termination of the HTTP connection, so as not to leave clients
hanging on a response which never comes or is mangled in some
way.

wwwattach: support async blob retrievals

We can reuse some of the GzipFilter infrastructure used by other
WWW components to handle slow blob retrieval, here.  The
difference from previous changes is we don't decide on the 200
status code until we've retrieved the blob and found the
attachment.

While we're at it, ensure we can compress text attachment
responses once again, since all text attachments are served
as text/plain.

wwwtext: simplify gzf_maybe use

gzf_maybe always returns a GzipFilter object, even if it uses
CompressNoop.  We can also use ->zflush instead of
->translate(undef) here for the final bit.

view: simplify eml_entry callers further

This simplifies the primary callers of eml_entry while only making
mknews.perl worse.

www: update internal docs

We no longer favor getline+close for streaming PSGI responses
when using public-inbox-httpd.  We still support it for other
PSGI servers, though.

wwwstream: eliminate ::response, use html_oneshot

All of our streaming responses use ::aresponse, now, and our
synchronous responses use html_oneshot.  So there's no need
for the old WwwStream::response.

view: /$INBOX/$MSGID/t/: avoid extra hash lookup in eml case

We can build and buffer the HTML <head> section once the first
non-ghost message in a thread is loaded, so there's no need to
perform an extra check on $ctx->{nr} once the $eml is ready.

view: eml_entry: reduce parameters

We can save stack space and simplify subroutine calls, here.

ssearchview: /$INBOX/?q=$QUERY&x=t uses async blobs

Another 10% or so speedup when displaying full messages off
search results.

feed: /$INBOX/new.html fetches blobs asynchronously

Once again this speeds another endpoint up 10% or so.

feed: generate_i: eliminate pointless loop

$ctx->{msgs} won't ever contain undef values.

view: update /$INBOX/$MSGID/T/ to be async

Another 10% or so speedup in a frequently-hit endpoint.

view: /$INBOX/$MSGID/t/ reads blobs asynchronously

Once again, this shows a ~10% speedup with multi-message
threads in xt/httpd-async-stream.t regardless of whether
TEST_JOBS is 1 or 100.

view: make /$INBOX/$MSGID/ permalink async

This will allow -httpd to handle other requusts if waiting on
an HDD seek or git to decode a blob.

wwwstream: subclass off GzipFilter

This makes WwwStream closer to MboxGz and WwwAtomStream
and will eventually allow us to follow the same patterns.

wwwstream: use parent.pm and no warnings

parent.pm is leaner than base and we'll rely on `-w' for
warnings during development.

remove unused/redundant zlib-related imports

Z_FINISH is the default for Compress::Raw::Zlib::Deflate->flush,
anyways, so there's no reason to import it.  And none of C::R::Z
is needed in WwwText now that gzf_maybe handles it all.

www: start making gzipfilter the parent response class

Virtually all of our responses are going to be gzipped, anyways.
This will allow us to utilize zlib as a buffering layer and
share common code for async blob retrieval responses.

To streamline this and allow GzipFilter to be a parent class,
we'll replace the NoopFilter with a similar CompressNoop class
which emulates the two Compress::Raw::Zlib::Deflate methods we
use.

This drops a bunch of redundant code and will hopefully make
upcoming WwwStream changes easier to reason about.

wwwstream: reduce blob fetch paths for ->getline

This will make it easier to support asynchronous blob
retrievals.  The `$ctx->{nr}' counter is no longer implicitly
supplied since many users didn't care for it, so stack overhead
is slightly reduced.

wwwstream: reduce object graph depth

Like with WwwAtomStream and MboxGz, we can bless the existing
$ctx object directly to avoid allocating a new hashref.  We'll
also switch from "->" to "::" to reduce stack utilization.

wwwatomstream: support async blob fetch

This allows -httpd to handle other requests while waiting
for git to retrieve and decode blobs.  We'll also break
apart t/psgi_v2.t further to ensure tests run against
-httpd in addition to generic PSGI testing.

Using xt/httpd-async-stream.t to test against clones of meta@public-inbox.org
shows a 10-12% performance improvement with the following env:
TEST_JOBS=1000 TEST_CURL_OPT=--compressed TEST_ENDPOINT=new.atom

xt/httpd-async-stream: allow more options

We want to be able to parallelize and stress test more
endpoints and toggle `--compressed' and possibly other
options in curl.

wwwatomstream: reuse $ctx as $self

No need to deepen our object graph, here.

wwwatomstream: use PublicInbox::Inbox->modified for feed_updated

stat(2) on the inboxdir is unlikely to be correct, now that
msgmap truncates its journal (rather than unlinking it).

wwwatomstream: simplify feed_update callers

We always return Z (UTC) times, anyways, so we'll always
use gmtime() on the seconds-after-the-epoch.

mbox: async blob fetch for "single message" raw mboxrd

This restores gzip-by-default behavior for /$INBOX/$MSGID/raw
endpoints for all indexed inboxes.  Unindexed v1 inboxes will
remain uncompressed, for now.

mboxgz: reduce hash depth

We can bless $ctx directly into a MboxGz object to reduce
hash lookups and allocations.

mboxgz: do asynchronous git blob retrievals

This lets the -httpd worker process make better use of time
instead of waiting for git-cat-file to respond.  With 4 jobs in
the new test case against a clone of
<https://public-inbox.org/meta/>, a speedup of 10-12% is shown.
Even a single job shows a 2-5% improvement on an SSD.

stop auto-loading Plack::Middleware::Deflater

Instead of gzipping some (mbox.gz, manifest.js.gz) responses and
leaving P::M::D to do the rest, we gzip everything ourselves,
now, so P::M::D is redundant.

qspawn: learn to gzip streaming responses

This will allow us to gzip responses generated by cgit
and any other CGI programs or long-lived streaming
responses we may spawn.

wwwstatic: support gzipped directory listings

This will allow others to mimic our award-winning homepage
design without needing to rely on Plack::Middleware::Deflater
or varnish to compress responses.

mbox: remove html_oneshot import

It's no longer needed, we no longer show a runtime error
for zlib being missing, as zlib is a hard requirement.

Fixes: a318e758129d616b ("make zlib-related modules a hard dependency")

{gzip,noop}filter: ->zmore returns undef, always

This simplifies callers, as witnessed by the change to
WwwListing.  It adds overhead to NoopFilter, but NoopFilter
should see little use as nearly all HTTP clients request gzip.

gzipfilter: replace Compress::Raw::Deflate usages

The new ->zmore and ->zflush APIs make it possible to replace
existing verbose usages of Compress::Raw::Deflate and simplify
buffering logic for streaming large gzipped data.

One potentially user visible change is we now break the mbox.gz
response on zlib failures, instead of silently continuing onto
the next message.  zlib only seems to fail on OOM, which should
be rare; so it's ideal we drop the connection anyways.

wwwlisting: use GzipFilter for HTML

The changes to GzipFilter here may be beneficial for building
HTML and XML responses in other places, too.

www: need: use WwwStream::html_oneshot

It'll give us a nicer HTML header and footer.

wwwtext: switch to html_oneshot

No point in streaming a tiny response via ->getline,
but we may stream to a gzipped buffer, later.

wwwtext: gzip text/plain responses, as well

Most of our plain-text responses are config files
big enough to warrant compression.

www*stream: gzip ->getline responses

Our most common endpoints deserve to be gzipped.

wwwstream: oneshot: perform gzip without middleware

Plack::Middleware::Deflater forces us to use a memory-intensive
closure.  Instead, work towards building compressed strings in
memory to reduce the overhead of buffering large HTML output.

gzipfilter: minor cleanups

We currently don't use bytes::length in ->write, so there's no
need to `use bytes'.  Favor `//=' to describe the intent of the
conditional assignment since the C::R::Z::Deflate object is
always truthy.  Also use the local $gz variable to avoid
unnecessary {gz} hash lookups.

git_async_cat: unref pipes on EOF from git->cleanup

We avoided a managed circular reference in 10ee3548084c125f
but introduced a pipe FD leak, instead.  So handle the EOF
we get when the "git cat-file --batch" process exits and
closes its stdout FD.

v2: remove ->close entirely.  PublicInbox::Git->cleanup
handles all cleanup.  This prevents us from inadvertantly
deleting the {async_cat} field associated with a different
pipe than the one GAC is monitoring.

Fixes: 10ee3548084c125f ("git_async_cat: remove circular reference")

inboxidle: warn on inotify_add_watch failures

inotify_add_watch(2), open(2), stat(2) may all fail due to
permissions errors, especially when running -nntpd/-imapd
as `nobody' as recommended.

t/import: test for nasty characters

Spammers may send emails with nasty characters which can throw
off git-fast-import.  Users with non-existent or weaker spam
filters may be susceptible to corruption in the fast-import
stream as a result.

This was actually quietly fixed in git on 2020-06-01 by
commit 9ab886546cc89f37819e1ef09cb49fd9325b3a41
("smsg: introduce ->populate method"), but no test case
was created.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Link: https://public-inbox.org/meta/87imf4qn87.fsf@x220.int.ebiederm.org/
Link: https://public-inbox.org/meta/20200601100657.14700-6-e@yhbt.net/

watch: don't burn CPU on IDLE failures

Network connections fail and need to be detected sooner rather
than later during IDLE to avoid backtrace floods.  In case the
IDLE process dies completely, don't respawn right away, either,
to avoid entering a respawn loop.

There's also a typo fix :P

spawn: drop unused sys/uio.h include

We no longer use writev(2) in pi_fork_exec to emit errors.

overidx: document why we don't use SQLite WAL

I was wondering about this myself the other day and had to read
up on it.  So make a note of it for future readers.

tests: add use/require statements for TEST_RUN_MODE=0

The default (and fast) TEST_RUN_MODE=2 preloads most modules,
but TEST_RUN_MODE=0 is more realistic and can catch some
problems which may show up in real-world use.

watch: retry signals to kill IDLE and polling processes

To ensure reliable signal delivery in Perl, it seems we need to
repeatedly signal processes which aren't using signalfd (or
EVFILT_SIGNAL) with our event loop.

spawn: modernize with parent.pm, drop warnings.pm

parent.pm is smaller than base.pm, and we'll also move
towards relying on `-w' (or not) to toggle process-wide
warnings during development.

spawn: make @RLIMITS an array

Making the RLIMITS list a function doesn't allow constant
folding, so just make it an array accessible to other modules.

inboxidle: avoid per-inbox anonymous subs

Anonymous subs cost over 5K each on x86-64.  So prefer the
less-recommended-but-still-documented way of using
Linux::Inotify2::watch to register watchers.

This also updates FakeInotify to detect modifications correctly
when used on systems with neither IO::KQueue nor
Linux::Inotify2.

t/run: show unexpected output lines in logs

This will help us catch warnings in new code and notice
inadvertantly skipped tests.

watch: make waitpid() synchronous for Maildir scans

Maildir scanning still happens in the main process.  Scanning
dozens of Maildirs is still time-consuming and monopolizes the
event loop during WatchMaildir::event_step.  This can cause
cause zombies to accumulate before Sigfd::event_step triggers
DS::reap_pids.

spawn: unblock SIGCHLD in subprocess

Subprocess we spawn may want to use SIGCHLD for themselves.
This also ensures we restore default signal handlers
in the pure Perl version.

watch: ensure SIGCHLD works in forked children

In case our git or spam checker subprocesses spawn
subprocesses of their own.  We'll also ensure signal
handlers are properly setup before unblocking them.

watch: show path for warnings from spam messages

It could be useful to see warnings generated for known problematic
messages just as it is for possibly non-problematic ones.

watch: check for duplicates in ->over before spamcheck

It's cheaper to check for duplicates than run `spamc'
repeatedly when rechecking.  We already do this for
v1 with by using the "ls" command with fast-import,
but v2 requires checking against over.sqlite3.

watch: simplify internal structures

We won't be attempting to reuse Mail::IMAPConnections used to
check authentication info, for now, so stop storing
$self->{mics}.

We can also combine $poll initialization for IMAP and NNTP
to avoid data structure duplication.  Furthermore, rely on
autovivification to create {idle_pids} and {poll_pids}.

imaptracker: use flock(2) around writes

SQLite only issues non-blocking F_SETLK ops (not F_SETLKW) and
retries failures using a configurable busy_timeout.  SQLite's
busy loop sleeps for a millisecond and retries the lock until
the configured busy_timeout is hit.

Trying to set ->sqlite_busy_timeout to larger values (e.g. 30000
milliseconds) still leads to failure when running the new stress
test with 8 processes with TMPDIR on a 7200 RPM HDD.

Inspection of SQLite source reveals there's no built-in way to
use F_SETLKW, so tack on the existing flock(2) support we use to
synchronize git + SQLite + Xapian for inbox writing.  We use
flock(2) instead of POSIX fcntl(2) locks since Perl doesn't
provide a way to manipulate "struct flock" portably.

watch: support ~/.netrc via Net::Netrc

While git-credential-netrc exists in git.git contrib/, it may
not be widely known or installed.  Net::Netrc is already a
standard part of most (if not all) Perl installations, so use it
directly if available.

watch: use our own "git credential" wrapper

Git.pm may not be installed on some systems; or some users have
multiple Perl installations and Git.pm is not available to the
Perl running -watch.  Accomodate both those types of users by
providing our own "git credential" wrapper.

watch: enable autoflush for STDOUT and STDERR

In case output is redirected to a pipe, ensure stdout and stderr
are always unbuffered, as -watch may go long periods without
any output to fill up buffers.

watch: show user-specified URL consistently.

Since we use the non-ref scalar URL in many error messages,
favor keeping the unblessed URL in the long-lived process.

This avoids showing "snews://" to users who've specified
"nntps://" URLs, since "nntps" is IANA-registered nowadays and
what we show in our documentation, while "snews" was just a
draft the URI package picked up decades ago.

watch: add NNTP support

This is similar to IMAP support, but only supports polling.
Automatic altid support is not yet supported, yet; but may
be in the future.

v2: small grammar fix by Kyle Meyer
Link: https://public-inbox.org/meta/87sgeg5nxf.fsf@kyleam.com/

testcommon: $ENV{TAIL} supports non-@ARGV redirects

Existing use of the $ENV{TAIL} relied on parsing --std{out,err},
which was only usable for read-only daemons.  However, -watch
doesn't use PublicInbox::Daemon code(*), so attempt to figure
out redirects.

(*) -watch won't able to run as a daemon in cases when
    git-credential prompts for IMAP/NNTP passwords.
    PublicInbox::Daemon is also designed for read-only
    parallelism where all worker processes are the same.
    Any subprocesses spawned by -watch are to do specific
    tasks for a particular set of inboxes.

watch: just use ->urlmatch

We may just modify PublicInbox::Config->urlmatch in the future
to support git <1.8.5, but I wonder if there's enough users on
git <1.8.5 to justify it.

watch: remove {mdir} array

Since we store all watched directory names as keys in %mdmap,
there should be no need to keep an array of those directories
around.

t/watch_maildir*.t required changes to remove trained spam.
Once we've trained something as spam, there shouldn't be
a need to rescan it.

watch: support multiple watch: directives per-inbox

Some users will find it useful to merge several Maildir or
IMAP mailboxes into one public-inbox.  Let them do it, since
we've always supported multi-address inboxes.

watch: imap: be quiet about disconnecting on quit

If ->idle_done was handled successfully, we can just
let normal ->DESTROY disconnect and avoid ugly backtraces
when a user hits Ctrl-C to take down the process group.

watch: support imap.fetchBatchSize parameter

IMAP allows retrieving multiple messages with a single command,
and Mail::IMAPClient supports that.  Unfortunately, it means we
slurp multiple messages into memory at once.  This option allows
users to trade off memory usage to reduce network round-trips.

Ideally, we'd support pipelining; but AFAIK no widely installed
Perl IMAP library supports it.

watch: avoid long transaction to IMAPTracker

With different polling intervals, multiple processes may
simultaneously write to IMAPtracker.  This ought to reduce
SQLite busy waiting and contention issues when importing
many inboxes in parallel.

imaptracker: drop {dbname} field

It's not used anywhere since the IMAPTracker object doesn't
disconnect and reconnect.  If we ever need the filename,
{dbh}->sqlite_db_filename may be used.

Cc: Eric W. Biederman <ebiederm@xmission.com>

imaptracker: add {url} field to reduce args

Passing a $url parameter to every function was error-prone
and having {url} field for a short-lived object is appropriate.

This matches the version of IMAPTracker posted by
Eric W. Biederman on 2020-05-15 at:
https://public-inbox.org/meta/87ftc0c3r4.fsf_-_@x220.int.ebiederm.org/

The version I originally imported was based on the one
posted on 2019-10-09:
https://public-inbox.org/meta/874l0i9vhc.fsf_-_@x220.int.ebiederm.org/

Cc: Eric W. Biederman <ebiederm@xmission.com>

ds: add_timer: allow passing arg to callback.

This allows callers to avoid creating expensive closures.
We no longer pass the `$now' value to callers, as none of
the callers used it.

watch: use UID SEARCH to avoid empty UID FETCH

For mailboxes with many gaps in the UID sequence,
performing a UID SEARCH beforehand can reduce the
number of articles to fetch.

However, the downside to this is we may end up with
an arbitrarly large list of UIDs from the server.

watch: stop importers before forking

This fixes cases where watch is handling both Maildirs and IMAP
connections.  While we're at it, close open directories in the
IMAP children to save FDs.