inbox: add ->over method to ease access

One small step towards making installing Xapian optional for v2
and providing more WWW and NNTP functionality without it.

tests: get rid of unnecessary Cwd module use

We only need it for tests that chdir, and maybe for ENV{PATH}
portability (dash seems fine, not sure about others).

v2: revert change to solver_git.t for FreeBSD 11.2 and document

t/nntp.t: skip if Data::Dumper is missing

We can revisit this, later; but Data::Dumper requires a separate
package for CentOS-7 users, at least.

t/config.t: remove Data::Dumper dependency

CentOS-7 needs the perl-Data-Dumper package, and the
test is small enough to roll our own escaping, here.

tests: remove unnecessary loading of ::DS and Socket

PublicInbox::DS works for every platform we we care about,
nowadays; so checking for it is a waste of time.  Cleanup a
few POSIX and Socket imports while we're in the area.

httpd: get rid of Deflater warning

Deflating responses may be done by the reverse proxy (e.g. varnish
or nginx), so the warning for it could be invalid.

searchidx: fix incremental index with indexlevel=basic on v1

We were reindexing the full history every invocation of -index
when Xapian was not used because we were incorrectly relying on
'last_commit' metadata stored in Xapian.

Rewrite the indexing logic to be less confusing while we're
at it, since we rely on `git merge-base --is-ancestor' nowadays.

Furthermore, we need to handle message removals from the
overview index correctly when Xapian is not in use.

Co-authored-by: Eric W. Biederman <ebiederm@xmission.com>

v2writable: allow setting nproc via creat options

Avoiding reliance on environment variables is a bit cleaner
for writing tests

v1writable: new wrapper which is closer to v2writable

Import initialization is a little strange from history, but we
also can't change it too much because it's technically a public
API which external code may rely on...

And we may need to support v1 repos indefinitely.  This should
make it easier to write tests for both formats.

ci: include some scripts to make CI easier

This should make it easier to test a bunch of package
installation profiles across whatever OS isolation
one chooses (chroots, containers, jails, VMs).

doc/include.mk: remove git use and redundant declarations

And document that we still have GNU-isms in that
include.mk Makefile (and may continue to do so).
Finally, take advantage of GNU-isms to warn users
to run "gmake" to build all manpages.

Makefile.PL: improve make(1) portability

The `shell' function appears missing, so we'll rely on Bourne
shell expansioN, instead.

Use "$?" instead of "$<" since the latter is only specified
for inference and .DEFAULT rules, not target rules.

Tested on FreeBSD make(1) and bmake(1) on Debian.

doc: give txt files proper titles

We can fix the redundant rule in include.mk which causes
make(1) on FreeBSD to complain; but HTML docs will likely
still require GNU make.

doc: use bullet list for wwwlisting options

Otherwise, pod2man complains about "=item 404" not starting
with a letter and thinking it's part of a numbered list.

t/purge.t: fix unreferenced variable

INSTALL: note xapian-compact(1) tool

The Perl Xapian bindings do not support compacting, yet,
so we rely on the xapian-compact tool.

INSTALL: depend on Encode instead of Encode::MIME::Header

Email::MIME uses Encode::MIME::Header and depends on that
appropriately; however we depend on other parts of the Encode
distribution, but that's bundled with Perl by upstream, anyways;
and should place no additional burden on users.

INSTALL: update with FreeBSD pkg names and reorder

Fortunately, there is a pattern to most of these package names
in all distros I've tested (and hopefully other BSDs have them,
too).

Then, reorder the INSTALL document to mention the top-level
modules, first, so users can avoid needing to type extra
dependencies.  However, we still list some implicit dependencies
in case the upstream package drops dependencies independently of
us.

Finally, Devel::Peek is not a dependency worth making optional
since it's bundled by Perl upstream.  Fedora/RH-based distros
are the only one which turn it into a non-standard package when
Perl5 is installed.

Merge remote-tracking branch 'origin/danga-bundle'

* origin/danga-bundle:
  DS: epoll: fix misordered EPOLL_CTL_DEL call
  DS: drop unused "_undef" sub
  syscall: drop readahead wrapper
  build: do not manify DS and Syscall pods
  DS: handle EINTR in IO::Poll path, too
  DS: workaround IO::Kqueue EINTR (mis-)handling
  DS: drop profiling support
  DS: remove unused fields and functions
  listener: use EPOLLEXCLUSIVE for listen sockets
  bundle Danga::Socket and Sys::Syscall

DS: epoll: fix misordered EPOLL_CTL_DEL call

Any operations on an fd after POSIX::close() are invalid, so
epoll_ctl will fail.  Worse off, in a multi-threaded Perl, the
fd may be reused by another thread and EPOLL_CTL_DEL can hit the
wrong file description as a result.

cf. https://rt.cpan.org/Ticket/Display.html?id=129487

DS: drop unused "_undef" sub

No longer used since we removed the *_ip_string fields

syscall: drop readahead wrapper

No backwards compatibility to worry about for us; and fadvise
is superior anyways.

build: do not manify DS and Syscall pods

We don't need to increase our install footprint with
documentation from our internals (which will surely
change).

DS: handle EINTR in IO::Poll path, too

IO::Poll::_poll returns -1, which is "true" to Perl.

cf. https://rt.cpan.org/Ticket/Display.html?id=129484

nntp: avoid uninitialized variable from blank requests

We'll ignore blank lines from clients, since that's what innd
seems to do.

wwwstream: do not load URI.pm

It's unneeded since commit e358bd7a3833f8c5 (2016-07-02)
("inbox: base_url method takes PSGI env hashref instead")

So we only depend on URI::Escape from the "URI" CPAN distribution,
at the moment.

spawn (Inline::C): fix off-by-one error

Noticed while testing on FreeBSD 11.2 amd64 with the optional
Inline::C extension using clang 6.0.0.  The end result on
FreeBSD was spawning processes failed badly and things were
immediately unusable with this enabled.

av_len is a misleading API, and I failed to read the API
comments in perl:/av.c which state:

> Note that, unlike what the name implies, it returns
> the highest index in the array, so to get the size of
> the array you need to use "av_len(av) + 1".
> This is unlike "sv_len", which returns what you would expect.

If this bug affected anybody, it would've only affected users
using both the optional Inline::C module AND set the
PERL_INLINE_DIRECTORY environment variable.

That said, I've never seen any evidence of it on Debian
GNU/Linux + gcc on any x86 variant.  That includes full 64-bit
systems, a full 32-bit system, a 64-bit system with 32-bit
userspace, across multiple gcc versions since 2016.

index: warn with info about the message as context

This can help users track down the source of warnings
when presented with imperfect emails.

While we're at it, make the __WARN__ callback in t/v2writable.t
a no-op since we don't check for warnings, there.

Merge remote-tracking branch 'origin/wwwlisting'

* origin/wwwlisting:
  www: support listing of inboxes
  start depending on Perl 5.10.1+

DS: workaround IO::Kqueue EINTR (mis-)handling

IO::Kqueue seems unmaintained, so workaround a long-standing
bug where it falls over on signals:
https://rt.cpan.org/Ticket/Display.html?id=116615

t/search.t: fix permissions check on FreeBSD

FreeBSD does not allow non-root users to set S_ISGID;
so git skips this bit on FreeBSD and Debian/kFreeBSD
platforms.

DS: drop profiling support

There's other ways to profile and we don't need to add runtime
branches to do this.

DS: remove unused fields and functions

More will likely be dropped in the future, but drop the obvious
ones we aren't using, for now; especially since some of them are
set at ->new time and unavoidable.

This saves 579 bytes per-client on my 64-bit Debian stable
system as measured by Devel::Size::total_size from
PublicInbox::HTTP::event_read.  This adds up in C10K or C100K
situations.

Things we drop are:

* corked - MSG_MORE requires fewer syscalls
* read_push_back - tried to use it, ate CPU with slow clients
* IP/port fields - accept() already returns what we care about

listener: use EPOLLEXCLUSIVE for listen sockets

Since our listen sockets are non-blocking and we may run
multiple httpd|nntpd processes; we need a way to avoid
thundering herds when there are multiple httpd|nntpd worker
processes.

EPOLLEXCLUSIVE was added just for that in Linux 4.5

bundle Danga::Socket and Sys::Syscall

These modules are unmaintained upstream at the moment, but I'll
be able to help with the intended maintainer once/if CPAN
ownership is transferred.  OTOH, we've been waiting for that
transfer for several years, now...

Changes I intend to make:

* EPOLLEXCLUSIVE for Linux
* remove unused fields wasting memory
* kqueue bugfixes e.g. https://rt.cpan.org/Ticket/Display.html?id=116615
* accept4 support

And some lower priority experiments:

* switch to EV_ONESHOT / EPOLLONESHOT (incompatible changes)
* nginx-style buffering to tmpfile instead of string array
* sendfile off tmpfile buffers
* io_uring maybe?

wwwstream: drop tor2web URL

It was a MITM hazard and been killed off by the DoS subsystem
last July: https://marc.info/?i=87d0vwwkbs.fsf@riseup.net

doc/standards: add a link to PSGI specs

extmsg: escape ampersands in @EXT_URL array

We already escape the user-provided Message-IDs (so there's no
security problem AFAIK), but the URL templates which exist in
our source code were not escaped properly.

This quiets down tidy(1).

viewdiff: do not break out of DSTATE_CTX on /^$/

It seems a common case for mangled patches is editors or MUAs
dropping trailing whitespace, and lines matching /^ $/ gets
the space dropped to only match /^$/.

cgit: improve handling of cgit data path

Document `publicinbox.cgitdata' config directive, but allow it
to be unspecified and/or missing for installations which do not
wish to serve static data at all.

For users installing cgit from source to their home directory,
we can usually infer the cgit data path based on the cgit.cgi
binary path, even.

examples/cgit-commit-filter.lua: some doc updates

It's been a while since I wrote this, and it needs to be kept
up-to-date with some advances in our Perl code.

examples: cgit filter for use with WwwHighlight

I'm using this as the cgit about-filter and source-filter
in https://80x24.org/public-inbox.git

wwwhighlight: deal with no-op highlight

Not all inputs are highlight-able, so reuse the original
input and just linkify it if it can't be highlighted.

examples/cgit-commit-filter: remove unused variable

wwwhighlight: do linkification, too

Otherwise, there's no reason to use this API over highlight(1).
Maybe this can be an option in the future; but I'm struggling to
find a reason to not do it by default.

view: avoid "1+ messages" in per-message footer of /t/ and /T/

Try to appear gramatically correct and state:
"only message in thread" when there's only one known (to us)
message in the thread.

doc: add standards reference

Incomplete at the moment, but this ought to be a handy reference
for both implementers and users alike.

www: support listing of inboxes

We will still return a 404 by default to '/' for compatibility
with users of Plack::App::Cascade or similar.  Inboxes are
sorted by modification times to help users detect activity
(similar to the /$INBOX/ topic view).

New configuration options:

* publicinbox.wwwlisting - configure the listing type
* publicinbox.<name>.hide - hide a particular inbox from the listing

See changes to public-inbox-config.pod for full descriptions
of the new options.

Requested-by: Leah Neukirchen <leah@vuxu.org>
  https://public-inbox.org/meta/871sdfzy80.fsf@gmail.com/

start depending on Perl 5.10.1+

I mainly want to start using the '//' (defined-or) operator to
simplify code, and Perl 5.10.1 is roughly a decade old at this
point.

"given/when" would've be nice, but it's future is in doubt AFAIK.

I also started using the 'parent' module in WwwHighlight, and
'autodie' in UserContent.pm, both of which were only distributed
with Perl since 5.10.1; and testing with ancient
versions/distros is time-consuming.

Anyways, I think this a small-enough jump to not break any
existing installations, given we already depend on fairly
recent versions of git and Xapian.

Maybe we can use more newish Perl features in the future...

t/hl_mod: workaround w3m not handling &apos;

This fixes a test failure on my Debian buster system.

Bug report filed for w3m to handle "&apos;":

https://bugs.debian.org/927409

and for "highlight" to favor "&#39;" in case other browsers fail:

https://bugs.debian.org/927410

linkify: require parentheses pairs in URLs

Dangling parentheses with trailing punctuation usually means the
parentheses is not intended as part of the URL.

view: show "(no subject)" consistently in HTML

Empty subjects ("") and undefined Subjects: are now both
displayed as "(no subject)" for now.

doc: config: fix braino/typo :x

linkify: don't get confused by URLs in Perl code, at least

The URLs at the top of WwwStream.pm weren't getting linkified
correctly.

inbox: add `modified' sub

For inboxes with SQLite enabled (all v2, and probably most v1);
we can use the overview DB to get the timestamp of the latest
message.  It's faster than scanning git branches for commit times,
but not always the same.

git: calculate modified time of repository

This will be used for generating an HTML listing for v1 inboxes,
at least.  The logic for this follows that of grokmirror,
and we may dynamically generate manifest.js.gz natively...

config: use '$ibx' instead of '$rv' to denote Inbox objects

Followup-to: 6e6f7999361925e4
  ("cleanup: use '$ibx' consistently when referring to Inbox refs")

TODO: add an item for hooks support

and add a note for grokmirror support/integration, too

HACKING: stop advertising mailing list subscription info

It's still available, but no point in advertising something
which increases the dependency on a centralized subscriber list.
In fact, it's actively against the goal of promoting resistance
against centralization.

import: prefix 'inbox' with '-' to denote Inbox ref

This is for consistency with other fields which follow
this pattern w.r.t. field-naming when referring to internal
fields.

cleanup: use '$ibx' consistently when referring to Inbox refs

'$inbox' is more human-readable, so that is for the more
human-readable name in most cases.  Making our variable naming
more consistent should make the code easier-to-review and
harder to screw up.

www: remove unnecessary Git object reference

We access the Git object via the Inbox object nowadays, so
there's no point in having a shortcut to it, anymore.

INSTALL: document Crypt:CBC for PublicInbox::Unsubscribe

I basically forgot about this module, but "make syntax" on a
new chroot trips it up.

config: fix regression in repo.path => coderepo.dir mapping

We parse cgitrc for "repo.path", while we use "coderepo.dir" to
mean the same thing for non-cgit users.  So I ended up confusing
myself, here.

But then again, git uses "--git-dir" and "GIT_DIR", so I suspect
"dir" is the better choice than "path", here

viewdiff: document constants

We'll be building off of this for showing diffs in
the coderepo views.

doc/config: update cgit.cgi scan location

We account for the upstream default location as well as
the Debian-installed one.

config: support more cgit directives for project lists

Hopefully this gets us closer to matching cgit upstream behavior
(which also lacks tests).  We'll still need to support macro
expansion at some point for compatibility...

cgit: serve static css, logo, favicon directly

We can reduce the configuration needed to run cgit by reusing
the static file handling logic of the dumb git HTTP protocol.

I hate logos and icons, so don't expect public-inbox.org or
80x24.org to ever have those to waste users' bandwidth with :P
But I expect other users to find this useful.

config: support cgit scan-path and scan-hidden-path

project_list support still needs to be done

And tests need to be written... :<

doc: fix a few minor typos

www: fix missing cgit fallback after legacy redirects

We need to instate our cgit handler everywhere we use NewsWWW
to catch wildcard requests which our normal endpoints do not
handle.

spawn: require soft and hard entries in RLIMIT_* handling

Our high-level config already treats single limits as a
soft==hard limit for limiters; so stop handling that redundant
in the low-level spawn() sub.

cgit: use a dedicated named limiter

I mainly need this to enforce RLIMIT_CPU (and RLIMIT_CORE)
when requests come which generate giant, unrealistic diffs.

Per-coderepo limiters may be added in the future.  But for now,
I need to prevent cgit from monopolizing resources on my dinky
server.

qspawn: wire up RLIMIT_* handling to limiters

This allows users to configure RLIMIT_{CORE,CPU,DATA} using
our "limiter" config directive when spawning external processes.

www: wire up cgit as a 404 handler if cgitrc is configured

Requests intended for cgit are unlikely to conflict with
requests to inboxes.  So we can safely hand those requests
off to cgit.cgi.

cgit: support running cgit as a standalone CGI

We depend on git-http-backend for smart HTTP clone support,
however; since cgit does not support smart clones natively.
WWW.pm will be able to cascade down to this as a 404 handler in
the future.

spawn: support absolute paths

cgit (and most other CGI executables) is not typically installed
for use via $PATH, so we'll need to support absolute paths to
run it.

githttpbackend: check for other errors and relax CRLF check

Reads to git-http-backend(1) could fail or EOF prematurely,
so we must be ready for that case.

Furthermore, cgit (and possibly other CGI) uses LF instead
of CRLF, so support those programs, too.

githttpbackend: move more psgi.input handling into subroutine

This will be useful for other CGI wrappers we make.
This also fixes a bug with some PSGI servers which did not
present a real IO::Handle in the psgi.input env field.

support publicinbox.cgitrc directive

We can save admins the trouble of declaring [coderepo "..."]
sections in the public-inbox config by parsing the cgitrc
directly.

Macro expansion (e.g. $HTTP_HOST) expansion is not supported,
yet; but may be in the future.

spawn: support RLIMIT_CPU, RLIMIT_DATA and RLIMIT_CORE

We'll be spawning cgit and git-diff, which can take gigantic
amounts of CPU time and/or heap given the right (ermm... wrong)
input.  Limit the damage that large/expensive diffs can cause.

viewvcs: match 8000-byte lookup for git

No need to scan the entire string, but prefer to match git
behavior.  This might be faster if/when Perl can create
substrings efficiently using CoW.

Fix a 80-column violation while we're at it.

viewvcs: preliminary support for showing non-blobs

Eventually, we'll have special displays for various git objects
(commit, tree, tag).  But for now, we'll just use git-show
to spew whatever comes from git.

git: add "commit_title" method

This will be useful for extracting titles/subjects from
commit objects when displaying commits.

githttpbackend: serve $GIT_DIR/info/attributes

This will be useful for reproducibility when mirroring
coderepos and generating diffs.

viewvcs: check for premature EOF from git-cat-file

Not entirely sure what is causing this, but it appears to
be causing infinite loops when attempting to display certain
blobs.

Fortunately, the fair scheduling of public-inbox-httpd prevented
this from becoming a real problem aside from increasing CPU
usage.

config: ignore missing config files

There's no reason for us to have git-config(1) warn users when a
config file is entirely missing.

v2writable: index_sync adds new epochs to alternates

Newly-cloned epochs need to be in alternates file of
all.git for the web and NNTP interfaces to work.  So
allow invocations of "public-inbox-index" to idempotently
ensure the epoch is visible from the all.git repo.

v2writable: hoist out fill_alternates

We'll be using this sub to fill $GIT_DIR/objects/info/alternates
if somebody uses clone --mirror, too

v2writable: fix epoch rollover on incremental imports

All of our internal epoch rollover calculations are done using
the estimated unpacked (and uncompressed) size of the repo.  The
importer instance needs to check that unpacked size before
selecting an epoch when an epoch already has packed data.

This bug did not impact the initial mass imports since we only
initialize the Import instance once-per-epoch and did not need
to take existing epochs into account.

Tested manually with -mda on a local clone of LKML

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

www: prevent '!important' in BOFH-specified CSS

CSS specified by the BOFH must never take precedence over
what a user sets in userContent.css.

usercontent.pm: set "!important" to override BOFH prefs

The sample userContent.css needs a higher priority than what
the BOFH specifies.  In other words, user preference must
ALWAYS take precedence.

Reported-by: Dmitry Alexandrov <321942@gmail.com>
cf. https://public-inbox.org/meta/87mumn4kx8.fsf@gmail.com/

ensure bytes::length is available to callers

We were relying on Danga::Socket using the "bytes" pragma,
previously.  Nowadays, the "bytes" pragma is not recommended in
general, but bytes::length remains acceptable for getting the
byte-size of a scalar.

MANIFEST: add newswww.psgi

Fixes: 285b9b4d7de53b0d ("examples/newswww.psgi: demonstrate standalone NewsWWW usage")

t/perf-msgview.t: fix broken performance test

WwwStream started depending on the WWW::style method
for configurable CSS, so mock ::style so the benchmark
runs properly.

Fixes: f026dbdd392c9dd5 ('www: admin-configurable CSS via "publicinbox.css"')

t/perf-msgview: don't warn about --unordered if skipping

No point in making noise about something that isn't used.

examples/newswww.psgi: demonstrate standalone NewsWWW usage

Plack::Builder allows "mounting" on with hostnames as well as
path names to enable virtual hosting.  This example demonstrates
how port 80/443 for "news.example.com" can redirect browser
requests when somebody attempts to use a "nntp://" URL and
the software assumes "http://"

nntp: get rid of long_response_limit constant

Unused since commit b8c41362f2a5c8fcc6b1846a79c72bfa77565297
("nntp: simplify the long_response API")

http: cleanup partial-write handling on readonly values

Don't bother assigning to $_[1]; just let Danga::Socket
do its thing since $_[1] should be out-of-scope soon.

daemon: favor Socket.pm in Perl 5.14+ for IPv6

Users on Perl 5.14+ are common, so we can try the bundled Socket
(not "Socket6") module before attempting Socket6 for IPv6.