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.

use consistent {ibx} field for writable code paths

This is a step which makes our use of abbreviations more
consistent when referring to PublicInbox::Inbox objects.
We'll also be reducing the number of redundant fields
in SearchIdx and V2Writable code paths to make the
object graph easier-to-follow.

v2writable: drop "EPOCH.git indexing $RANGE" progress

It'll be one continuous range with IdxStack.

v2writable: allow >= 40 byte git object IDs

Another step in slowly updating our code to support SHA-256 or
whatever other hash algorithms git may support in the future.

v2writable: move {autime} and {cotime} into $sync state

The V2Writable object may be long-lived, so it makes more
sense to put the {autime} and {cotime} fields into the
shorter-lived index_sync state.

v2writable: index_sync: reduce fill_alternates calls

Instead of doing fill_alternates for every epoch we're indexing,
just do it once at the start of index_sync invocation.  This
will set us up for using a single "git cat-file" process for
indexing multiple epochs.

v2writable: introduce idx_stack

This avoids pinning a potentially large chunk of memory from
`git-log --reverse' into RAM (or triggering less predictable
swap behavior).  Instead it uses a contiguous temporary file
with a fixed-size record for every blob we'll need to index.

v2: index forwards (via `git log --reverse')

Since we'll need to expose THREADID to JMAP and IMAP users,
index all messages in the order they were committed to ensure
our `tid' (thread ID) column ascends in mirrors the same way
they do in the source inbox.

This drastically simplifies our code but increases memory
usage of `git-log'.  The next commit will bring memory use
back down at the expense of $TMPDIR usage.

index: support --rethread switch to fix old indices

Older versions of public-inbox < 1.3.0 had subtly
different semantics around threading in some corner
cases.  This switch (when combined with --reindex)
allows us to fix them by regenerating associations.

msgmap: fix atfork_* callbacks

Noticed while reindexing a largish v2 inbox in parallel on an
SSD which required checkpointing and respawning shard workers.

Fixes: f06e84220e5566e7 ("over+msgmap: do not store filename after DBI->connect")

v2writable: git_hash_raw: avoid $TMPDIR write

We can rely on FD_CLOEXEC being set by default (since Perl 5.6+)
on pipes to avoid FS/page-cache traffic, here.  We also know
"git hash-object" won't output anything until it's consumed all
of its standard input; so there's no danger of a deadlock even
in the the unlikely case git uses a hash that can't fit into
PIPE_BUF :P

search: simplify unindexing

Since over.sqlite3 seems here to stay, we no longer need to do
Message-ID lookups against Xapian and can simply rely on the
docid <=> NNTP article number equivalancy SCHEMA_VERSION=15
gave us.

This rids us of the closure-using batch_do sub in the v1
code path and vastly simplifies both v1 and v2 unindexing.

searchidx: use v5.10.1, parent.pm, drop warnings

Prefer "parent" to "base" since the former is lighter and part
of Perl 5.10+.  We'll also rely on warnings from "-w" globally
(or not) instead of via "use".

overidx: favor non-OO sub dispatch for internal subs

OO method dispatch was 10-15% slower when I was implementing the
NNTP server.  It also serves as a helpful reminder to the reader
at the callsite as to whether a sub is likely in the same
package as the caller or not.

overidx: each_by_mid: pass self and args to callbacks

This saves runtime allocations and reduces the likelyhood of
memory leaks either from cycles or buggy old Perl versions.

with_umask: pass args to callback

While it makes the code flow slightly less well in some places,
it saves us runtime allocations and indentation.

import: use common capitalization for filtering headers

In case this ends up in the same process as Mbox::msg_hdr,
it can reduce memory use by sharing the cache key in
PublicInbox::Eml::re_memo

drop binmode usage

We only support Unix-like platforms where binmode (":raw") is
the default anyways, and v5.10 semantics means it won't do
unicode_strings (unlike v5.12).  So save some lines of code.

v2: use v5.10.1, parent.pm, drop warnings

The "5.010_001" form was for Perl 5.6, which I doubt anybody
would attempt; so favor "v5.10.1" as it is more readable to
humans.  Prefer "parent" to "base" since the former is lighter.
We'll also rely on warnings from "-w" globally (or not) instead
of via "use".

We'll also update "use" statements to reflect what's actually
used by V2Writable.

t/import: quiet warning, clobber variable

The eval in key2sub via t/run.perl ("make check-run") won't
trigger the warning, but running "prove -bvw t/import.t"
directly, does.  In any case, ensure the contents of this
variable doesn't linger across runs.

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.