learn: hoist out remove_or_add subroutine

We'll be reusing it for List-ID processing in the next commit.

learn: GIT_COMMITTER_<NAME|EMAIL> may be "" or "0"

Users may be zeroes or blanks.

learn: update usage statement

Use <foo|bar> since that seems to be the favored notation
for required command args (taking a hint from git(1) manpage).
While we're at it, remove the space after '<' for the redirect
to match git.git coding style.

learn: only map recipient list on "ham" or "rm"

It's assumed that "spam" can end up anywhere due to Bcc:, so we
need to scan every single inbox.  However, "rm" is usually more
targeted and and "ham" obviously only belongs in some inboxes.

learn: support multiple To/Cc headers

It's possible to specify these headers multiple times, and
PublicInbox::MDA->precheck takes that into account, so
-learn should, too.

Merge branch 'regen'

* regen:
  v2writable: use msgmap as multi_mid queue
  v2writable: move git->cleanup to the correct place
  v2writable: reindex handles 3-headered monsters
  v2writable: improve "num_for" API and disambiguate
  v2writable: set unindexed article number

doc: clean-doc: remove generated standards.txt

I need to remove all the generated documentation files
before running "git-set-file-times" for rsync to our
website.

syscall: get rid of sendfile wrappers for now

I'm not sure they'll make a measurable difference or will
be worth the effort in the future given the prevalance
of HTTPS and giant socket buffers.

Using Inline::C for this may make more sense in the
future, too, especially if we want to be able to use
GnuTLS.

hval: remove new_oneline

commit 476fc666c223f0fb ('reduce "PublicInbox::Hval->new_oneline" use')
was mis-titled, since it completely eliminated ->new_oneline use.

git: remove src_blob_url

This was intended for solver, but it's unused since
commit 915cd090798069a4
("solver: switch patch application to use a callback")

watchmaildir: remove redundant _path_to_mime

InboxWritable::maildir_path_load exists and we may support
it for use with standalone scripts.

inboxwritable: import_maildir uses maildir_path_load

I'm not sure if this will get used anywhere, but at least
call a function which exists in dead code.

www: remove unused ctx_get sub

This hasn't been used since commit 48b21cb662c1e17b7 in 2016:
("declare Inbox object for reusability")

overidx: remove unused delete_articles sub

This hasn't been used since commit 1b7e935ab1690e28
("searchidx: fix incremental index with indexlevel=basic on v1")

v2writable: use msgmap as multi_mid queue

Instead of storing Message-IDs in the Msgmap object, we can
store the blob OID.

For initial indexing of mirrors, this lets us preserve
$sync->{regen} by storing the intended article number in
the queue.

On --reindex, the article number we store in Msgmap is ignored
but only used for ordering purposes.

This also allows us to avoid ENOMEM errors if somebody abuses
our system by reusing Message-IDs; but we now risk ENOSPC
instead (but systems tend to have more FS storage than RAM).

v2writable: move git->cleanup to the correct place

We need to stop the git process to avoid leaking FDs
to Xapian if we recurse ->index_sync on reindex.

v2writable: reindex handles 3-headered monsters

And maybe 8-headered ones, too...

I noticed --reindex failing on the linux-renesas-soc mirror due
one 3-headed monster of a message having 3 sets of headers;
while another normal message had a Message-ID that matched one
of the 3 IDs of the 3-headed monster.

We still try to do the majority of indexing backwards, but we
defer indexing multi-Message-ID'd messages until the end to
ensure we get all the "good" messages in before we process the
multi-headered ones.

Link: https://public-inbox.org/meta/20191016211415.GA6084@dcvr/

v2writable: improve "num_for" API and disambiguate

Make it obvious that we're not the Msgmap sub and return an
array because it's less awkward than providing a modifiable ref
to a function to write to.

v2writable: set unindexed article number

We'll actually use the keys of this hash in future commits.

doc: update 1.2 work-in-progress release notes

Will be updating this further after some reindex and
multi-header bugs are fixed.

TODO: DHT (distributed hash table) for Message-IDs

This would encourage SPOF avoidance.  It would also make it
easier to do "Certificate Transparency"-style attestation of
messages.

examples/grok-pull.post_update_hook: fix config detection

We need to account for both the old ("mainrepo") and new
("inboxdir") names.  But "dir" was just a search+replace
error and we don't use that outside of "coderepo.dir".

TODO: add a few more items around coderepos

Going where no email client/tool has gone before...

doc: v2-format: get man output under 80 cols

We need to better ensure our manpage output is readable with a
standard terminal width.  And fix some wording while we're at
it:

* use "inbox" instead of "list" for our storage
* replace the last "$PART" reference with "$SHARD"

public-inbox-v2-format(5): fix formatting

This was being rendered as a paragraph, so line breaks weren't
preserved and it was unreadable in man.

Merge remote-tracking branch 'origin/inboxdir'

* origin/inboxdir:
  config: remove redundant inboxdir check
  config: support "inboxdir" in addition to "mainrepo"
  examples/grok-pull.post_update_hook: use "inbox_dir"

doc: enable "check-man" target via "check" in gmake

man(1) on FreeBSD supports pathnames as operands just
fine, so there's hope other BSDs follow suit and we
can enable this check target everywhere.

doc: avoid [<directory>] arg for git-clone(1)

While it is possible to host source code from the root of a URL
using git-http-backend(1), the lack of pathname in the URL can
also be confusing to users.  So just add the path name of the
project into the URL itself so users can invoke "git clone"
with one command-line argument instead of two.

Of course, previously documented URLs continue to work as normal.

doc: update public-inbox-overview(7) for v2

The overview was v1-specific and probably confusing/misleading
to new users since v2 is favored.

Hopefully improve wording while we're at it and avoid
overloading terms like "parts" (which could be confused with
Xapian "shards").

Using the word "directly" after "Mirroring mailing lists"
did not make sense to me, either.

doc: check-man: use COLUMNS env for width

That's the environment documented in ncurses(3) and man(1) from
the man-db.nongnu.org distribution of man.

config: remove redundant inboxdir check

This was causing compatibility problems for old configs
when using public-inbox-nntpd.

config: support "inboxdir" in addition to "mainrepo"

"mainrepo" ws a bad name and artifact from the early days when I
intended for there to be a "spamrepo" (now just the
ENV{PI_EMERGENCY} Maildir).  With v2, "mainrepo" can be
especially confusing, since v2 needs at least two git
repositories (epoch + all.git) to function and we shouldn't
confuse users by having them point to a git repository for v2.

Much of our documentation already references "INBOX_DIR" for
command-line arguments, so use "inboxdir" as the
git-config(1)-friendly variant for that.

"mainrepo" remains supported indefinitely for compatibility.
Users may need to revert to old versions, or may be referring
to old documentation and must not be forced to change config
files to account for this change.

So if you're using "mainrepo" today, I do NOT recommend changing
it right away because other bugs can lurk.

Link: https://public-inbox.org/meta/874l0ice8v.fsf@alyssa.is/

examples/grok-pull.post_update_hook: use "inbox_dir"

Move away from using "mainrepo" since it's confusing to
new users, especially with v2.

doc: check-man: ignore backspace char

man(1) on FreeBSD unconditionally emits backspace characters
for the bold effect despite its output being piped to awk(1).

Also tested with the man-db.nongnu.org version provided with
Debian (and presumably most other Linux systems).

mda: support --no-precheck option

Since -mda now supports List-ID to better support mirroring of
existing mailing lists, it probably makes sense to support
disabling the precheck function to provide more accurate (though
potentially spammier) mirrors of lists

Merge branch 'listid'

* listid:
  wwwtext: show listid config directive(s)
  mda, watch: wire up List-ID header support
  config: allow "0" as a valid mainrepo path
  config: avoid unnecessary '||' use
  config: simplify lookup* methods
  config: we always have {-section_order}
  Config.pm: Add support for mailing list information

admin: show failing directory

Since public-inbox-index may be run against a large list of
(intended) inboxes from the command-line, it's helpful to show
which directory fails the resolution.

doc: "check-man" target to ensure we stay <=80 cols

This should prevent future documentation changes from exceeding
the limit of standard terminals.

doc: check-NEWS.atom fails gracefully on FreeBSD make(1)

We should also note that the package "xmlstarlet" on FreeBSD
installs a command "xml" (but not "xmlstarlet") on FreeBSD.

wwwtext: show listid config directive(s)

We want to share this piece for potential mirror-ers just
like watchheader.

mda, watch: wire up List-ID header support

This also adds watchheader tests for -watch, which we never
had before :x

config: allow "0" as a valid mainrepo path

It's probably wrong to use relative path names, but things are
all relative these days anyways with shared and networked FSes.

config: avoid unnecessary '||' use

'//' is available in Perl 5.10+ which allows `0' and `""' (empty
string) to remain unclobbered.

We also don't need '||=' for initializing our internal caches.

config: simplify lookup* methods

This ensures we always process inboxes in section order and
reduces the amount of code we have to maintain for each lookup.

Avoiding the cost of inboxes object creation is not worth the
code overhead; and we can implement a config cache via Storable
easily for large configs and -mda users.

config: we always have {-section_order}

Rewrite a bunch of tests to use ordered input (emulating
"git config -l" output) so we can always walk sections in
the order they were given in the config file.

Config.pm: Add support for mailing list information

The world has turned since I first started following mailing lists and
to my surprise every mailing list that I am subscribed to properly
sets the "List-ID:" mailing list header.  So instead of doing
something clever and flexible I am adding support for looking up
public inbox mailing lists by their mailing list name.

That makes the work needed for each email trivial and easy to understand.
- Parse the "List-ID:" header.
- Lookup in the configuration which mailbox is connected to that
  "List-ID:"
- Deliver the mail to that mailbox.

To that end this change enhances PublicInbox to have an additional
mailbox configuration parameter "listid" that holds the mailing list
name.

A method is added to the PublicInbox config object called
lookup_list_id that given a mailing list name will return the
PublicInbox in the configuration that is configured to handle that
mailing list.

Signed-off-by: "Eric W. Biederman" <ebiederm@xmission.com>
[ew: avoid autovivification of $ibx->{listid} for t/config.t]

PublicInbox::Import Smuggle a raw message into add

I don't trust the MIME type to not munge my email messages in horrible
ways upon occasion.  Therefore  allow for passing in the raw message
value instead of trusting the mime object to preserve it.

Signed-off-by: "Eric W. Biederman" <ebiederm@xmission.com>
[ew: use "//" from Perl 5.10+ for defined check]

doc: remove unnecessary dependency on RelNotes directory

It was causing unnecessary rebuilds of NEWS* files

INSTALL: recommend inotify|kqueue modules for -watch

Jan Kiszka reported high polling frequency when using -watch.

It turns out OS-specific packages for Filesys::Notify::Simple do
not pull in interfaces to use kqueue or inotify, which are
required to perform power-efficient event-based wakeups on
Maildir writes.

Fix the name of the Filesys::Notify::Simple for FreeBSD while
we're at it.

Link: https://public-inbox.org/meta/c85803c6-6d77-a300-491a-9f310dd284c1@web.de/

TODO: add an item for Python pygments

Pygments seems to be a popular highlighter and widely available,
so we'll be providing support for that at some point...

Link: https://public-inbox.org/meta/20190926131836.GB10467@chatter.i7.local/
Link: https://public-inbox.org/meta/874l0zt7sd.fsf@alyssa.is/

TODO: add item for config linter and grapher

It'll be useful for tools and users to test and perhaps
visualize configs before reloading -httpd/-nntpd/-watch.

t/git-http-backend: disable worker processes

We want to ensure we run lsof(8) on the worker (if needed),
and not the master, which doesn't serve requests.

This was originally on top of a test-only patch in
https://public-inbox.org/meta/20190913015043.17149-1-e@80x24.org/
In any case, no point in spawning extra processes for this test.

doc: explain publicinbox.<name>.watchheader

It wasn't clear to me exactly what this does -- in particular, what
happens if it isn't specified?  Does it support multiple values?  A
very brief explanation can answer both of these questions without
making somebody look at the code.

doc: use local modules to generate NEWS*

We shouldn't need installed modules to generate NEWS* files.

INSTALL: note that we prefer GNU make

ExtUtils::MakeMaker uses non-POSIX '::', at least; and
our own Documentation/include.mk and our postamble are
written for GNU make.

GNU make is also more widely-installed and available than any
other make; even if I'm not generally a fan of GNU-isms.

doc: PublicInbox::SaPlugin::ListMirror manpage

This is a plugin for SpamAssassin that happens to be quite
useful in keeping spam off lists I mirror.  Hopefully more
people can find it useful now that it has a manpage.

extmsg: drop unused $have_mm variable

We rely on Inbox::mm nowadays.

examples: add grok-pull post_update_hook example

This requires the latest (to be in 1.2) -init changes for
synchronization and has no dependencies on GNU or bash-isms
so it should run on *BSD systems without GNU tools.

It does attempt to use curl on <$INBOX_URL/_/text/config/raw>,
but curl is fairly standard nowadays, and falls back to using
an invalid address to initialize.

doc: generate NEWS, NEWS.atom, and NEWS.html

We'll use our Documentation/RelNotes directory and internal APIs
to generate these files for website use (the website should be
completely reproducible).

Makefile.PL: add dependency on MANIFEST contents

This prevents breakage when running installed scripts when a
user fetches from git and forgets to run "perl Makefile.PL"
before "make install".

init: implement locking

First, we use flock(2) to wait on parallel public-inbox-init(1)
invocations while we make multiple changes using git-config(1).
This flock allows -init processes to wait on each other if using
reasonable POSIX filesystems.

Then, we also need a git-config(1)-compatible lock to prevent
user-invoked git-config(1) processes from clobbering our
changes while we're holding the flock.

doc: add manpage for public-inbox-init(1)

This old command was lacking a manpage, so (finally) create one.

init: favor --skip-epoch instead of --skip

Since I intend to add support for --skip-artnum, disambiguating
the long option name makes sense.  We'll support --skip
indefinitely for compatibility.

t/search: bail out on `git init --shared' failures

We can save future testers some time if we bail out early
on "git init --shared" failures, since things like seccomp
or non-POSIX FSes would trigger failures.

BAIL_OUT has been in Test::Simple since Perl v5.10.0, so it's
old-enough to call for our purposes.

Thanks-to: Alyssa Ross <hi@alyssa.is>
Reviewed-by: Alyssa Ross <hi@alyssa.is>
Tested-by: Alyssa Ross <hi@alyssa.is>
Link: https://public-inbox.org/meta/878sq2hd08.fsf@alyssa.is/

t/search: show file modes as octal on failures

This ought to make permissions errors on odd systems
easier to diagnose in the future.

tests: recommend running create-certs.pl with $^X

This is better than recommending running the script directly because
it will ensure the correct version of perl is used.

HACKING: document Perl character class gotcha

It took me years to discover this change in Perl 5.6,
maybe other potential hackers are in the same boat.

listener: warn on some accept()/accept4() errors

We need to warn when hitting file or socket memory limits
or misconfigurations which clear O_NONBLOCK to make it easier
to diagnose configuration problems.  We'll also warn on
some other errors in case bugs creep in...

www: fix absolute URLs when mounted under a subdir

While we avoid generating absolute URLs in most cases, our
"git clone" instructions and URL headers in mboxrd files
contain full URLs.

So do the same thing we do for WwwAtomStream and pre-generate
the full URL before Plack::App::URLMap changes $env->{PATH_INFO}
and $env->{SCRIPT_NAME} back to their original values.

Reported-by: edef <edef@edef.eu>
Link: https://public-inbox.org/meta/cover.0f97c47bb88db8b875be7497289d8fedd3b11991.1569296942.git-series.edef@edef.eu/

doc: avoid redundant mkdir(1) calls

GNU make has order-only prerequisites, so use it to avoid
redundant mkdir(1) calls since our homepage requires GNU
make to build anyways.

TODO: add item for searching based on git-patch-id(1)

I forgot about this feature when I was implementing
blob-ID-based searches :x

TODO: update with "git cat-file" items

Millions of inboxes in an instance is probably not feasible, but
dozens or even hundreds could happen and
/proc/sys/fs/pipe-user-pages-soft is only 16384 on my system,
with each "cat-file --batch" process using 16+1 pages worth
of pipes.

config: use NUL-delimited git-config(1) output

This allows us to deal with newlines in config values,
since git-config(1) acquired "-z" support in git v1.5.3.

I'm not sure if it's actually useful in our case, but
maybe some multi-line texts could be added.  And newlines
in path names are super useful!

qspawn: workaround Perl 5.16.3 leak, re-enable Deflater

The httpd-supplied write callback is the leak culprit under Perl
5.16.3.  undef-ing it immediately after use keeps a repeated
"git fetch" loop from monotonically increasing memory and FD use
on the Perl shipped with RHEL/CentOS 7.x.

Other endpoints tested showed no increase in memory use under
constant load with "ab -HAccept-Encoding:gzip -k", including the
async psgi_qx code path used by $INBOX_URL/$OBJECT_ID/s/ via
SolverGit module.

wwwtext: support $INBOX_URL/_/text/config/raw

This returns a git-config(1)-compatible file to make it easier
to get started on mirroring an existing public-inbox.  Omitting
the "raw" from the URL works, as well, but I'm not sure if
it's very useful.

v2writable: only change $EPOCH.git/config on epoch creation

We don't need to make unnecesary writes to the git config file
and wear out storage devices every time we run
"public-inbox-index"

mbox: update URL for mboxrd info

qmail.org seems unavailable.

hlmod: update for highlight 3.51 API change

Quoting Amitai Schleier, who made this same change in ikiwiki[1],
where lots of the public-inbox highlight code comes from:

> As of 3.51, searchFile() is no longer provided in highlight's Perl
> bindings (at least on NetBSD and OS X, as built from pkgsrc). This
> leaves us falling through to getConfDir(), which has been gone
> rather longer.
>
> From highlight git, it appears searchFile() and getFiletypesConfPath()
> both originated in the 3.14 release. The latter is still available in
> 3.51, and returns the same result searchFile() used to. Switch to it.

So, this should still be compatible with the version of highlight.pm in
Debian, but add support for newer versions as well.

[1]: commit 4d06df9583e6c4145f8c6fc2fd51d7894c0b85ce

Cc: Amitai Schleier <schmonz-web-ikiwiki@schmonz.com>

httpd: disable Deflater middleware by default on Perl <5.18

Testing with perl-5.16.3-294.el7_6 RPM package on RHEL/CentOS 7,
the Deflater middleware triggers a leak when used in conjunction
with our push-based responses from PublicInbox::Qspawn.

I could not find another solution to workaround the memory leak
in this case, and I could not find a specific leak fix in
the perl5180delta manpage[1] which looked like it would
solve our problem.

Attempting to workaround the issue proved futile.  Using
internal Deflater-specific keys to prevent deflating in
GitHTTPBackend and Qspawn did not solve the problem:

        $env->{"plack.skip-deflater"} = 1;
        $env->{"psgix.no-compress"} = 1;

Nor did forcing an invalid encoding via "git fetch":

git -c http.extraheader=Accept-Encoding:gzap fetch

So this appears to be a problem with Plack::Util::response_cb
somewhere.

This does NOT appear to be a problem with ref() leaking as in
DS::next_tick[2], since I couldn't find where
Plack::Middleware::Deflater or Plack::Util::response_cb would be
calling ref() on a blessed reference to trigger a leak.

Also, oddly enough, the ref() use for backwards compatibility at
the top of PublicInbox::GitHTTPBackend::serve does NOT seem to
trigger a leak on 5.16.3 due to [2]:

# XXX compatibility... ugh, can we stop supporting this?
$git = PublicInbox::Git->new($git) unless ref($git);

[1] https://perldoc.perl.org/perl5180delta.html
[2] https://rt.perl.org/Public/Bug/Display.html?id=114340

ds: workaround a memory leak in Perl 5.16.x

The perl-5.16.3-294.el7_6 RPM package on RHEL/CentOS 7 is
affected by a memory leak in Perl when calling `ref' on
blessed references.  This resulted in a very slow leak that
manifests more quickly with a nonstop "git fetch" loop.

Use Scalar::Util::blessed to work around the issue.
Tested overnight on a CentOS 7 VM.

cf. https://rt.perl.org/Public/Bug/Display.html?id=114340

spawnpp: use absolute path for exec

We support "-env" to clear the environment with spawn(),
which causes test failures but no runtime failures
(since "-env" isn't used anywhere in our real code)

Reported-and-tested-by: Alyssa Ross <hi@alyssa.is>

feed: remove unused $cmt->{-html_url} field

It was never used, and will not be needed.

doc: update HACKING and TODO with a few items

Inline::C seems alright, so we might use it more since it still
allows end users to quickly make changes.  Our performance on
rotational disks is also terrible, and could be improved...

wwwatomstream: fix per-feed <id>

We were emitting the same "<id>mailto:name@domain</id>" tag
for every feed (but not per-feed entry).  This could cause
feed readers to mistake the top (news.atom) feed for other
feeds (search results, or per-thread feeds).

This is technically a breaking change for people relying on
per-thread or per-query feeds, but the only alternative is
to remain broken for anybody trying to follow multiple feeds
off the same inbox.

config: boolean handling matches git-config(1)

We need to handle arbitrary integers and case-insensitive
variations of human words to match git-config(1) behavior,
since that's what users would expect given we use config
files parseable by git-config(1).

doc: add release notes directory

The v1.2.0 is a work-in-progress, while the others are copied
out of our mail archives.

Eventually, a NEWS file will be generated from these emails and
distributed in the release tarball.  There'll also be an Atom
feed for the website reusing our feed generation code.

t/httpd-corner.t: don't fail lsof test if stdin is a pipe (try #2)

Actually do the redirect properly

t/httpd-corner.t: don't fail lsof test if stdin is a pipe

We don't want the stdin from the test runner to accidentally
cause this test to fail.

http: remove unnecessary delete

Only removing $http->{env} is needed to prevent circular
references.  $env->{'psgix.io'} does not need to be deleted
since $env will no longer have any references to it when
->close returns.

http: drop unused `$env' variable after delete

And explain why we need to do that delete in a comment.

qspawn: improve variable naming and commenting

Naming $start_cb consistently helps avoid confusing new readers,
and some comments will help with understanding flow

qspawn: shorten lifetime of circular references

All of these circular references are designed to clear
themselves, but these will make actual errors from Devel::Cycle
easier-to-spot.

The circular reference in the limiter {run_queue} is not a real
problem, but we can avoid storing the circular reference until
we actually need to spawn the child, reducing the size of the
Qspawn object while it's in the queue, slightly.

We also do not need to have redundant checks to spawn new
processes, we should only spawn new processes when they're
->start-ed or after waitpid reaps them.

qspawn: log errors for generic PSGI server users

Generic PSGI servers have $env->{'psgi.errors'}, too,
so ensure they can log errors.

qspawn: remove return value from ->finish

We don't use the return value in real code since we do waitpid
asynchronously, now.  So simplify our runtime code at the cost
of making our test slighly more complex.

doc: update config manpage for "publicinbox.grokmanifest"

It's a bit of an esoteric option, but maybe somebody out
there can find it useful.

qspawn: shorten lifetime of environ and opts args

We don't need to hold onto the subprocess environ and
redirects/options for popen_rd after spawning the child process.

I do not expect this to fix problem of leaking unlinked regular
file descriptors (which I still can't reproduce), and it
definitely does not fix the problem of leaking pipe descriptors
(which I also can't reproduce).

This will save an FD sooner on non-public-inbox-httpd servers
which give a non-FD $env->{'psgi.input'}, however

Regardless, it's good to free up memory resources in our own
process ASAP we're done using them.

qspawn: clarify and improve error handling

EINTR should not happen when using non-blocking sockets like we
do in our daemons, but maybe some OSes allow it to happen and
edge-triggered notifications won't notify us again.

So always retry immediately on EINTR without relying on kqueue
or epoll to notify us, and log any other unrecoverable errors
which may happen while we're at it.

t/httpd-corner: use which() sub for detecting curl(1)

We already import `which' for lsof(8), so we might as well
use it to detect curl(1), too.

doc: update nntpd with NNTPS and STARTTLS examples

NNTPS and STARTTLS seems to be working for several months
without incident on news.public-inbox.org, so consider it a
success and maybe others can try using it.

HTTPS technically works, too, but isn't documented at
the moment since I can't recommend production deployments
without varnish protecting it.

t/httpd-corner: check for leaking FDs and pipes

-W0 (no workers) should not create any pipes on its own,
and we shouldn't have any deleted FDs if no clients are
connected.

This can find if leaks which may be triggered by PublicInbox::HTTP
(and not Qspawn or GitHTTPBackend).