TODO: update and add a few more items

SpamAssassin has used re2c (via sa-compile) for many years, now,
and it seems to work fine, there.  GMime also looks promising
when combined with Inline::C since GMime can operate on mmap-ed
regions.

Given the inevitable demise of many .orgs when price rise;
supporting a URL rewriter similar to .mailmap makes sense.

And HTTP CONNECT seems like something our -httpd can support
to let firewalled users read over NNTP.

ds: ->Reset initializes $nextq

I haven't noticed this being a problem in practice, but
be consistent with the rest of the singleton stuff.
Since we always call Reset() at load time, only do
initialization in that sub and not at declaration.

t/common: set $0 when running script w/o fork

We can localize changes to $0 so $0 is restored when the
"script" sub is done.  This will be helpful when we encounter
a stuck/slow processes during our tests (hopefully never!)

t: localize the PI_CONFIG env

We don't want the user's ~/.public-inbox/config to be read from
during tests.  I only noticed this because I had a non-existent
pathname for one of my inboxes :x

I've also verified this change by running "inotifywait
~/.public-inbox/config -m" in another terminal while running
"make check"; (perhaps a portable solution could make it
into the test suite).

replace: quiet "git gc" invocation

Since we give users no indication or control of how "git gc"
runs, showing its progress is confusing.

t/replace: quiet "git fsck" invocation

Test output can be a terminal if running as "perl -I lib t/$FOO.t",
and showing fsck progress is pointless for tests.

t/httpd-unix: FreeBSD expects to fail with EADDRINUSE

Tested FreeBSD 11.2.  I'm starting to think I'm too conservative
with this check and it could be safely expanded to cover any OS
with UNIX sockets.

Makefile.PL: MANIFEST dependency fix

We need to force an update to Makefile (not Makefile.PL) when
MANIFEST changes.  Since "Makefile" (aka. "$(FIRST_MAKEFILE)")
is already a single-colon make target; we can't create a
double-colon rule to augment it.  So we'll continue using a
"Makefile.PL" rule, but have it recreate the resulting Makefile

Finally, change the "check" target to use "prove -b" instead of
"prove -l" so we test against "blib/lib", since what's in the
"blib" dir will be installed.

Fixes: 4c20de0694d06ff3 ("Makefile.PL: add dependency on MANIFEST contents")

httpd|nntpd: avoid missed signal wakeups

Our attempt at using a self-pipe in signal handlers was
ineffective, since pure Perl code execution is deferred
and Perl doesn't use an internal self-pipe/eventfd.  In
retrospect, I actually prefer the simplicity of Perl in
this regard...

We can use sigprocmask() from Perl, so we can introduce
signalfd(2) and EVFILT_SIGNAL support on Linux and *BSD-based
systems, respectively.  These OS primitives allow us to avoid a
race where Perl checks for signals right before epoll_wait() or
kevent() puts the process to sleep.

The (few) systems nowadays without signalfd(2) or IO::KQueue
will now see wakeups every second to avoid missed signals.

dskqxs: fix missing EV_DISPATCH define

Oops, IO::KQueue support was broken due to this missing
constant.  Add a new ds-kqxs.t test case to ensure we
test the IO::KQueue path if IO::KQueue is available.

msgtime: deal with strange minutes in TZ offsets

I'm not sure if TZ minute offsets aside from '00' or '30' exist,
but lets just deal with them properly when negative.  Examples
taken from various inboxes on lore.kernel.org.  These are mostly
message from spammers, but some are legitimate messages.

t/msgtime: add more checks for known cases

Broken email clients sent the darndest things, make sure
we can still support them when we make Date::Parse optional.

t/msgtime: show date in test descriptions

Otherwise it's hard to figure what fails.

tests: move giant inbox/git dependent tests to xt/

xt/ is typically reserved for "eXtended tests" intended for
the maintainers and not ordinary users.  Since these require
special configuration and do nothing by waste cycles
during startup, they qualify.

t/perf-*.t: use $ENV{GIANT_INBOX_DIR} consistently

It's more consistent with our current terminology and
"PI_DIR" is already used to override ~/.public-inbox/
(which holds "config" and possibly other files which affect
all inboxes for a particular user, but is not an inbox itself);
so stop advertising GIANT_PI_DIR in skip messages.

tests: quiet down commit graph

Newer versions of git enable the commit graph by default.
Since we blow away our temporary directories every test,
generating graphis is a waste and clutters stderr with
"Computing commit graph generation numbers" messages.

tests: use File::Temp->newdir instead of tempdir()

We'll also introduce a tmpdir() API to give tempdirs
consistent names.

xapcmd: replace Xtmpdirs with File::Temp->newdir

Since we're using Perl 5.10.1 and File::Temp 0.19+, we don't
need Xtmpdirs at all for cleaning up tempdirs on failure and
can just rely on the DESTROY handler provided by File::Temp.

t/nntpd-validate: get rid of threads dependency

Threads are officially discouraged by perl5-porters and proves
problematic with my Perl installation when using run_mode=1
to speed up tests.  So just use fork() and pipes to share
results from Net::NNTP.

t/common: start_script replaces spawn_listener

We can shave several hundred milliseconds off tests which spawn
daemons by preloading and avoiding startup time for common
modules which are already loaded in the parent process.

This also gives ENV{TAIL} support to all tests which support
daemons which log to stdout/stderr.

daemon: avoid race when quitting workers

While the master process has a self-pipe to avoid missing
signals, worker processes lack that aside from a pipe to
detect master death.

That pipe doesn't exist when there's no master process,
so it's possible DS::close never finishes because it
never woke up from epoll_wait.  So create a pipe on
the worker_quit signal and force it into epoll/kevent
so it wakes up right away.

daemon: use sigprocmask when respawning workers

We need to block signals in workers during respawns
until they're ready to receive signals.

daemon: use sigprocmask to block signals at startup

`$SIG{FOO} = "IGNORE"' will cause the daemon to miss signals
entirely.  Instead, we can use sigprocmask to block signal
delivery until we have our signal handlers setup.  This closes a
race where a PID file can be written for an init script and a
signal to be dropped via "IGNORE".

.gitignore: ignore local prove(1) files

As described in prove(1), .prove is storage for --state=save
and .proverc allows per-worktree customizations.

t/nntpd-tls: sometimes SSL_connect succeeds quickly

It seems caching can happen within OpenSSL or negotiation
can be delayed in some cases.  In any case, don't barf on
PublicInbox::TLS::epollbit() when connect_SSL succeeds
unexpectedly.

t/httpd-corner: wait for worker process death

We need to ensure the worker process is terminated before
starting a new connection, so leave a persistent HTTP/1.1
connection open and wait for the SIGKILL to take effect
and drop the client.

t/xcpdb-reshard: test xcpdb --compact

We did not have a test for this, and need to guard against
regressions when changing Xapcmd to use File::Temp->newdir
in future commits.

t/v1-add-remove-add: quiet down "git init"

Use the "-q" flag like everywhere else.

tests: use strict everywhere

The "strict" pragma makes code easier to debug, and we had
undeclared variables as a result in t/watch_maildir_v2.t.
So use it everywhere to be consistent with the rest of our
code.

tests: disable daemon workers in a few more places

There were still a few places where we used worker processes
unnecessarily in tests, causing a small amount of unnecessary
overhead.

Followup-to: ad221e9b2852f6c5 ("t/*.t: disable nntpd/httpd worker processes in most tests")

mboxgz: fix compiler parse error under under Perl 5.16.3

Perl 5.16.3 (and possibly older versions) fails with the
following errors (from CentOS7):

  Use of ?PATTERN? without explicit operator is deprecated
  Search pattern not terminated

check for File::Temp 0.19 for ->newdir method

This is distributed with Perl 5.10.1 and onwards, so it should
not be an installation burden for any users.  I'm planning to
move away from tempdir() entirely and use File::Temp->newdir to
remove dependencies on END{} blocks.

t/xcpdb-reshard: use run_script for -xcpdb

This more than doubles the speed of the test, since we make
many invocations of -xcpdb.

t/indexlevels-mirror*: switch to run_script

This more than doubles the speed of these tests

t/v2mda: switch to run_script in many places

This more than doubles the speed of the test.

t/watch_filter_rubylang: run_script for -init and -index

This nets us a 20% speedup or so.

t/nntpd: use run_script for -init

This only gives a 5% speedup or so, but anything helps.

t/watch_maildir_v2: use run_script for -init

This only gives a small 10% speedup or so, but anything helps.

t/httpd: use run_script for -init

This only gives a small ~10% speedup, since -httpd still
needs execve, but any speedup is welcome.

t/convert-compact: convert to run_script

While this didn't use IPC::Run, having to reload several Perl
modules and scripts is slow and inefficient, so roughly
double the speed of this test.

t/v2mirror: switch to default run_mode for speedup

We need to be careful and explicitly close FDs before doing
-index, since we can't rely on FD_CLOEXEC without execve(2)
syscalls.

doc: remove IPC::Run as a dev and test dependency

It's no longer needed and we're able to speed up some
of our tests as a result.

t/mda_filter_rubylang: drop IPC::Run dependency

This test runs more than twice as fast, now.

t/mda: switch to run_script for testing

Another noticeable speedup, this test is roughly ~3x faster now.

t/v2mirror: get rid of IPC::Run dependency

Not taking advantage of faster run modes in run_script, yet
since some lifetime problems need to be sorted.

t/purge: convert to run_script

This nets us another sizeable speedup.

t/init: convert to using run_script

This gives a 2-3x speedup on the test with the default
run_mode=1.

t/edit: switch to use run_script

Perl parsing is slow, and run_script default behavior allows
this to speed up t/edit.t by over 100% in my case.

t/common: introduce run_script wrapper for t/cgi.t

This will give us a consistent interface for running
test scripts in more performant ways while still giving
us a consistent interface to recreate real-world behavior
via spawn() (fork + execve), if needed.

The default run_mode (1) is faster and can run within the test
process with some minor adjustments to our code to avoid global
state.

This avoids the significante overhead of Perl code loading,
parsing and compilation phases.

spawn: which: allow embedded slash for relative path

This makes the subroutine behave more like which(1) command
and will make using spawn() in tests easier.

xapcmd: do not fire END and DESTROY handlers in child

We need to bypass whatever Test::More does with END/DESTROY
handlers for use in lon-lived process.  This doesn't affect
any of our normal code since we don't use END/DESTROY for
Xapcmd and its callers.

import: only pass Inbox object to SearchIdx->new

SearchIdx->new no longer accepts a GIT_DIR path as its argument
since commit 585314673236d664729fe3ab2d4fb229d1c0f2d5
("searchidx: require PublicInbox::Inbox (or InboxWritable) ref")

inboxwritable: add ->cleanup method

We've been using this in -edit, and will be using it in some
more scripts and tests to optimize for run_mode=2 with
run_script.

Keeping this in the *Writable modules since I don't see it being
useful for the WWW and NNTP read-only interfaces which use
PublicInbox::Inbox.

learn: pass global variables into subs

Avoid 'Variable "%s" will not stay shared' warnings
when the contents of this script eval'ed into a sub.

mda: pass global variables into subs

Avoid 'Variable "%s" will not stay shared' warnings
when the contents of this script eval'ed into a sub.

init: pass global variables into subs

Avoid 'Variable "%s" will not stay shared' warnings
when the contents of this script eval'ed into a sub.

We also need to rely on ->DESTROY instead of END{}
to unlink the lock file on sub exit.

index: pass global variables into subs

Avoid 'Variable "%s" will not stay shared' warnings
when the contents of this script eval'ed into a sub.

admin: get rid of singleton $CFG var

PublicInbox::Admin::config() just adds an extra layer of
indirection which we barely rely on.  So get rid of this
global variable and make it easier to run tests in the
future without relying on global state.

edit: use OO API of File::Temp to shorten lifetime

Instead of relying on END{} blocks, rely on ->DESTROY
so the temporary files go out-of-scope and system
resources get released, sooner.

edit: pass global variables into subs

Avoid 'Variable "%s" will not stay shared' warnings
when the contents of this script eval'ed into a sub.

mboxgz: use Compress::Raw::Zlib instead of IO::Compress::Gzip

IO::Compress::Gzip is a wrapper around Compress::Raw::Zlib,
anyways, and being able to easily detach buffers to return them
via ->getline is nice.  This results in a 1-2% performance
improvement when fetching giant mboxes.

mbox: split mboxgz out into a separate file

It'll make using Compress::Raw::Zlib easier, since we
can use that and import constants more easily.

mbox: unused mid_clean import

We're gradually phasing mid_clean out (in favor of mids()).

doc: check-man: save the result of successful runs

We can keep a stamp around if the corresponding manpage hasn't
changed to avoid re-running man(1) and awk(1).

t/psgi_mount: require SearchIdx before using

We may not implicitly load it via other means in the future.

t/common: move unix_server to t/httpd-corner.t

unix_server() is not commonly used, only t/httpd-corner.t uses
it and most HTTP tests use TCP since most HTTP libraries only
support TCP.

t/common: inline stream_to_string into t/feed.t

We only use it in one place and have favored test_psgi
in newer tests, so move it out-of-the-way to reduce startup
overhead of other *.t files.

doc: mknews: support Email::MIME <1.930

Email::MIME::header_str is not available until 1.930, so the
rest of our code uses Email::MIME::header for compatibility
with distros, since CentOS 7.x only has 1.926.

convert: remove duplicated GetOptions() call

We only need to parse the command-line once.

inboxwritable: drop {-importer} cyclic reference

InboxWritable caching the result of ->importer leads to a
circular references with returned (V2Writable|Import) object
holds onto the calling InboxWritable object.

With public-inbox-watch, this leads to a memory leak if a user
is reloading via SIGHUP after a message is imported (it would
only become noticeable with SIGHUPs after every message imported).

I would not expect anybody to to notice this in real-world
usage.  I only noticed this since I was making -xcpdb suitable
for long-lived process use (e.g. "mod_perl style") and a flock
remained unreleased on v1 inboxes after resharding.

WatchMaildir (used by -watch) already handles caching of the
importer object itself, and all of our other real-world uses of
->importer are short-lived or designed for batch scripts, so
there's no need to cache the importer result internally.

xapcmd: localize %SIG changes using "local"

Perl's "local" allows changes to %SIG (and %ENV) to be limited
to its enclosing block.  This allows us to get rid of a global
variable and ad-hoc method for restoring signal handlers.

solvergit: use --unidiff-zero with git-apply(1)

I sometimes post context-free documentation patches generated
with "-U0" to reduce size and bandwidth overhead when replacing
URLs or updating copyright notices.  git-apply(1) needs the
--unidiff-zero switch to work properly with context-free
patches.

Given our search looks for blob OIDs, and we're never going
to be running the code we regenerate, "--unidiff-zero" ought
to be safe.

doc: drop a repeated word

t/*.t: disable nntpd/httpd worker processes in most tests

And explicitly test for respawning in t/httpd-corner.t

There's no need to have an extra entries in the process table
for most tests we run, since that's not what we're testing.

t/hl_mod.t: remove IPC::Run (and File::Temp) dependency

We already load PublicInbox::Spawn for which(), so using spawn()
isn't unreasonable.  And rely on "skip" to log the omitted test
if w3m is missing, which means we need to update the "&&"
escaping test to be self-referential on the same line.

File::Temp was totally unused, there; and we can use "open ...,undef"
in Perl to easily create anonymous temporary files for use with
spawn().

t/httpd-corner.t: get rid of IPC::Run for running curl

We already load PublicInbox::Spawn, so there's no need to
add another dependency to make life difficult for potential
contributors.

t/httpd-corner.t: drop unnecessary bytes:: for length()

We don't need to force byte semantics for a buffer we clearly
create (via ->read) with byte semantics.  Since we didn't
"use bytes" in t/httpd-corner.t, it was inadvertantly made
available by IPC::Run (which goes away, next).

t/*.t: remove IPC::Run dependency for git commands

One small step towards making tests easier-to-run.  We can rely
on "local $ENV{GIT_DIR}" for potentially shell-unsafe path
names, and the rest of our path names are relative and don't
contain characters which require escaping.

edit: check for write errors writing "From_" line

We need to check every print to a regular file for errors,
because storage devices inevitably fail.

edit: propagate correct editor exit code

exit($?) is never correct, since ($? >> 8) is needed to extract
the correct exit code, as other information (e.g. such as signal)
is encoded in $? in addition to the exit code.

doc: actually document publicinboxwatch.watchspam

Instead of copy-pasting the documentation for `spamcheck'.

t/edit: use PublicInbox::Git::qx for pathname safety

Another case where spaces can be in TMPDIR and cause
shell expansion with `command` to fail.

tests: rely on PublicInbox::Git for pathname safety

It's possible (but unlikely) a user will put spaces in TMPDIR
and cause File::Temp::tempdir() to return a temporary directory
with spaces in the filename, making it unsafe for shell
expansion.

PublicInbox::Git didn't exist when t/mda.t was written, and
I just forgot about PublicInbox::Git->qx for t/plack.t :x

t/httpd-corner.t: check for curl(1) errors in big async test

curl(1) can fail and we need to invalidate the test in the
rare case it fails.

index: "git log" failures are fatal

While I've never seen "git log" fail on its own, it could happen
one day and we should be prepared to abort indexing when it
happens.

Beef up tests for t/spawn.t to ensure close() behaves
on popen_rd the way we expect it to.

searchidxshard: reuse $SIG{__WARN__} callback from Admin

We don't want to define $SIG{__WARN__} in the worker to call an
existing non-default callback.  Instead update ->{current_info}
the same way the V2Writable master process does.

I noticed this while reindexing with a large XAPIAN_FLUSH_THRESHOLD
and seeing the wrong epoch on my terminal from a shard because the
shard worker was spawned while reindexing a higher-numbered epoch.

public-inbox v1.2.0

build: add "git-dist" target for making gzipped tarballs

Since MANIFEST is tied to files tracked by git, adding generated
files such as NEWS to that is more effort than its worth (esp.
when I'm wondering if MakeMaker is useful compared to only using
GNU make).

I also have trouble reading CamelCase, so lower-case names
are nicer and more consistent with previous releases
(which were all generated with "git archive"); but did not
include NEWS.

doc: mknews: force plain-text NEWS to UTF-8

We'll have non-7-bit ASCII in the 1.2.0 release notes.

TODO: update item for multiple Date: headers

That's the only head-scratcher of the bunch remaining, since
that relies on ranges.

doc: add public-inbox.cgi(1) manpage

Yet another case of documenting things which should NOT be used :>

doc: add public-inbox-purge(1) manpage

Tools intended for end users need manpages, and doubly so
to convince potential users NOT to use them :)

hval: replace "&apos;" with "&#39;" for compatibility

While testing 216light.css changes, I managed to hit some cases
where dillo failed to render &apos; correctly, but I also can't
reproduce it reliably.  Anyways, it's definitely a problem with
some old browsers and newer versions of highlight already work
around it, but Debian 10.x has 3.41, so use "&#39;" to maximize
compatibility.

contrib/css/216light: improve contrast a bit

"#ff0" foreground on a "#fff" background is just too difficult
to distinguish, among other things.  So choose slightly darker
colors when using a (painful) "#fff" background.

qspawn: psgi_qx: delay callback until waitpid returns

We need to detect "git apply" failures reliably when patches
fail.  This is necessary for solving for blob 81c1164ae5 in
https://public-inbox.org/git/ when at least two messages can
solve for it (and one of them fails):

1. https://public-inbox.org/git/b9fb52b8-8168-6bf0-9a72-1e6c44a281a5@oracle.com/
2. https://public-inbox.org/git/56664222-6c29-09dc-ef78-7b380b113c4a@oracle.com/

solvergit: deal with false-positive dfpost: results

When solving for blob 81c1164ae5 in https://public-inbox.org/git/,
at least two messages get indexed with the dfpost result for
that blob (after fixing MsgIter to decode all text/* parts):

1. https://public-inbox.org/git/b9fb52b8-8168-6bf0-9a72-1e6c44a281a5@oracle.com/
2. https://public-inbox.org/git/56664222-6c29-09dc-ef78-7b380b113c4a@oracle.com/

However, only the first message contains a usable patch.  So
we must adjust SolverGit to account for multiple messages
hitting the same "dfpost:" search result and attempt
"git apply" on all results, not just the first.

In the future, changes to SearchIdx.pm may rid us of invalid
search results and speed up performance (at the expense of
developer/indexing time); but we need to account for old search
indices, first.

msgiter: attempt to decode all text/* bodies

We want to index text/x-patch and text/x-diff, at least,
since "git format-patch" can generate a patch series as
attachments using --attach.

msgiter: do not assume UTF-8 if Email::MIME->body_str succeeds

ISO-2202-JP and other non-UTF-8 messages need to be displayed
correctly.

Fixes: 7d82a8bc04ce ('handle "multipart/mixed" messages which are not multipart')

search: add note about SCHEMA_VERSION 15

--reindex has gotten better over the years, and having parallel
Xapian DB directories would exceed all available disk space for
some users with giant inboxes.

wwwlisting: fix spelling and clarify sub location

Spell "Schwartzian" correctly, and clarify the location of
"modified" since we have multiple subs named "modified"