Makefile.PL: "dsyn" target to check syntax of changed files

We have lots of files and syntax-checking every single one of
them is slow.  Enable "perl -w" in the existing syntax check
while we're at it.

doc: update dependencies for CentOS 7.x

Digest::SHA is the most notable missing package at runtime
for a minimal system.

Tests don't run at all without Test::Simple (or Test::More).
Plack::Test is also a separate package, too...

Also, the package for IO::Compress::Gzip should be IO::Compress;
as perl-PerlIO-gzip is a different thing entirely which is not
relevant to our needs.

Test::HTTP::Server::Simple doesn't seem required at all for Plack
tests.

ExtUtils::MakeMaker needs to be documented as a install dependency
for people installing this, too; since AFAIK public-inbox is not
yet in any distros.

t/common.perl: fix error message for git requirements

And enable strict + warnings in the scope of t/common.perl, too.

searchmsg: remove unused ->get subroutine

It's obsolete and unusable since our search schema version 15;
which made the Xapian document ID correspond to the NNTP article
number.

searchidx: improve error message when Xapian fails

Make it easier to detect if a partition is corrupt.

doc: index.pod: fix mismatched =back

doc: generate manpage and HTML from -convert POD

It's been written for over a year, but I forgot to include
it in the build so it did not get installed or put on the site.

doc: clean-doc target removes *.8 manpages

scripts: add README to describe its purpose

Well, it could probably be moved to contrib...

scripts: require ASCII digits in a few places

I haven't touched most these scripts in ages, but we might as well
purge \d usage from here, as well.

tighten up digit matches to ASCII for git output

While I don't expect git to suddenly start spewing non-ASCII
digits in places I'd expect ASCII, this would make things easier
for future hackers and reviewers.

t: avoid "subtest" for Perl 5.10.1 compatibility

The version of Test::More from Perl 5.10.1 did not support
"subtest", and the earliest version which did is Perl 5.12.0

The good news is this gives me an excuse to parallelize
the indexlevels-mirror test by splitting it into two.
(it could be further split, even).

Update t/nntpd. to use PI_TEST_VERSION consistently while
we're at it.

Merge branch 'charclass'

* charclass: (24 commits)
  www: require ASCII word characters for CSS filenames
  www: require ASCII range for mbox downloads
  githttpbackend: require ASCII in path
  require ASCII digits for local FS items
  www: require ASCII digit for git epoch
  solver|viewdiff: restrict digit matches to ASCII
  inbox: require ASCII digits for feedmax var
  filter/rubylang: require ASCII digit for mailcount
  msgtime: require ASCII digits for parsing dates
  searchview: do not allow non-ASCII offsets and limits
  githttpbackend: require Range:, Status: to be ASCII digits
  view: require YYYYmmDD(HHMMSS) timestamps to be ASCII
  newswww: only accept ASCII digits as article numbers
  config: do not accept non-ASCII digits in cgitrc params
  www: require ASCII filenames in git blob downloads
  www: only emit ASCII chars in attachment filenames
  wwwattach: only pass the charset through if ASCII
  wwwlisting: require ASCII digit for port number
  http: require SERVER_PORT to be ASCII digit
  feed: only accept ASCII digits for ref~$N
  ...

MANIFEST: add examples/nginx_proxy

examples: add sample nginx configuration

The sample configuration can be used to proxy-pass requests
to public-inbox-httpd or to a standalone PSGI/Plack server.

www: require ASCII word characters for CSS filenames

Allowing admins to set non-ASCII CSS filenames could
cause unnecessary problems for client and proxies.

www: require ASCII range for mbox downloads

We do not support many mboxrd download range specifications at
the moment; but parsing non-ASCII characters isn't planned.
This makes no difference aside from being able to return 404
slightly earlier than we would've in the past.

githttpbackend: require ASCII in path

We mainly support git-upload-pack; and maybe somebody uses
git-receive-pack with this.  Perhaps other (experimental)
command names are acceptable.  But it's unlikely anybody will
want Unicode command names for git services.

require ASCII digits for local FS items

In case some BOFH decides to randomly create directories
using non-ASCII digits all over the place.

www: require ASCII digit for git epoch

Don't inadvertantly serve git repos containing non-ASCII
digit characters.

solver|viewdiff: restrict digit matches to ASCII

git would not generate non-ASCII digits to describe
hunk offsets, so don't waste more time than necessary
to make sense of non-ASCII digit chars for line offsets.

inbox: require ASCII digits for feedmax var

Don't waste more cycles than necessary if somebody decides to
put non-ASCII digits in their ~/.public-inbox/config

filter/rubylang: require ASCII digit for mailcount

Unlikely to matter, but who knows...

msgtime: require ASCII digits for parsing dates

User input contains the darndest things.  Don't waste more time
than necessary trying to parse dates out of non-ASCII digits.

searchview: do not allow non-ASCII offsets and limits

Non-ASCII digits would be interpreted as zero when used as integers.

githttpbackend: require Range:, Status: to be ASCII digits

Non-ASCII digits would be interpreted as a zeroes as integers.

While we're at it, ensure the Status: code is an ASCII digit,
too; though I would not expect git-http-backend(1) or cgit(1)
start spewing non-ASCII digits at us.

view: require YYYYmmDD(HHMMSS) timestamps to be ASCII

Passing digits to `timegm' which it does not understand would
be a waste of time.

newswww: only accept ASCII digits as article numbers

Non-ASCII digits aren't specified in RFC3977 for article numbers;
so don't waste a trip to SQLite only to turn up empty.

config: do not accept non-ASCII digits in cgitrc params

cgit uses atoi(3), and now we can retain compatibility.

www: require ASCII filenames in git blob downloads

Our Hval::to_filename sub has always been strict about emitting
ASCII-only characters for ViewVCS "raw" links.

However, somebody could manually generate a filename with
non-ASCII words for somebody else to download (we have no
cheap and fast way of mapping filenames back to blobs for
validation).

www: only emit ASCII chars in attachment filenames

We don't want to emit funky URLs which can be lost in
translation or cause problems with non-Unicode-aware
clients.

Then, don't accept non-ASCII filenames in URLs, since
a manually-generated URL/filename in attachment downloads
could be used for Unicode homographs to confuse folks who
down the attachment.

wwwattach: only pass the charset through if ASCII

AFAIK all names of charsets are ASCII, so passing non-ASCII
characters from emails to clients would probably confuse clients.

wwwlisting: require ASCII digit for port number

We only care about the hostname portion for matching,
so this change is probably inconsequential.

http: require SERVER_PORT to be ASCII digit

I'm not sure what middlewares care for for SERVER_PORT; but
allowing non-ASCII digits seems non-sensical, here.

feed: only accept ASCII digits for ref~$N

We don't want to waste cycles passing non-ASCII characters
to git.

mid: id_compress requires ASCII-clean words

Its result is used for HTML anchors and such.

nntp: ensure we only handle ASCII whitespace

RFC3977 does not have provisions for whitespace beyond ASCII
TAB, SP, CR and LF.  I doubt there's any NNTP clients broken
enough to be sending non-ASCII whitespace delimiters.

We're probably excessively liberal regarding TAB acceptance,
even; but it's probably too late to change at this point...

nntp: be explicit about ASCII digit matches

We aren't able to make sense of non-ASCII digits

cf. perlrecharclass(1) / "Digits" section

linkify: support Internationalized Domain Names in URLs

The "\w" character class in Perl matches any word characters
in the Unicode database, not just ASCII characters.  So we
must be prepared for that and generate links to IDNs.

Merge remote-tracking branch 'origin/git-cleanup'

* origin/git-cleanup:
  git: drop the deleted err_c file
  git: unconditional expiry

Merge remote-tracking branch 'origin/ds'

* origin/ds:
  ds: remove PLCMap and per-socket PostLoopCallback
  ds: drop write_set_watch field
  ds: drop unused EVENT: label in epoll code path
  ds: drop checks for invalid descriptors
  ds: drop set_writer_func support
  ds: add a note about planned future changes
  ds: drop more unused subs

ds: remove PLCMap and per-socket PostLoopCallback

We don't need and won't be needing per-socket PostLoopCallbacks.

t/psgi_search.t: require DBD::SQLite

In case we encounter an odd system which has Search::Xapian
but not DBD::SQLite.

ds: drop write_set_watch field

We never enable write watches ourselves for HTTP and NNTP,
and only enable the write watch with EvCleanup because it's
an "always on" watch.

ds: drop unused EVENT: label in epoll code path

This was never used in Danga::Socket 1.61, either.

ds: drop checks for invalid descriptors

I've used Danga::Socket for well over a decade in various
projects at this point and have never seen the need for it.

If such a bug ever happens; the process should fall over so
it gets fixed ASAP.

ds: drop set_writer_func support

This is not used by perlbal for OpenSSL support, either;
and it does not appear to be the right layer for doing
write translations anyways (IO::Socket::SSL uses `tie').

ds: add a note about planned future changes

Sometimes I get bored with the email part of this project and
need a distraction :P

ds: drop more unused subs

ToClose and HaveEpoll are of no use to us and I see no
future use for them, either.

ds: fix and test for FD leaks with kqueue on ->Reset

Even though we currently don't use it repeatedly, ->Reset
should close() kqueue FDs and not cause the process to run
out of descriptors.

Add a close-on-exec test while we're at it.

doc/v2: note that Xapian is now optional in v2

This is true as of e220b8b2ee5cfd458167dc2c6c92726352c4c80e
("Merge remote-tracking branch 'origin/xap-optional' into master")

ds: set close-on-exec flag on epoll descriptors

We should not be leaking these FDs to git(1) processes,
in case git has a bug that causes it to access the wrong FD.

git: drop the deleted err_c file

No reason to leave that (usually) empty file open after killing off
"cat-file --batch-check".  This wasn't an unbound leak, though,
as respawning the --batch-check process would've clobbered the
old err_c file.

git: unconditional expiry

A constant stream of traffic to either httpd/nntpd would mean
git-cat-file processes never expire.  Things can go bad after a
full repack, as a full repack will unlink old pack indices and
git-cat-file does not currently detect unlinked files.

We could do something complicated by recursively stat-ing
objects/pack of every git directory and alternate;
but that's probably not worth the trouble compared to
occasionally restarting the cat-file process.

So simplify the code and let httpd/nntpd expire them
periodically, since spawning a "git-cat-file --batch" process
isn't too expensive.  We already spawn for every request which
hits git-http-backend, cgit, and git-apply.

In the future, we may optionally support the Git::Raw module
to avoid IPC; but we must remain careful to not leave lingering
FDs open to unlinked files after repack.

git: drop the deleted err_c file

No reason to leave that (usually) empty file open after killing off
"cat-file --batch-check".  This wasn't an unbound leak, though,
as respawning the --batch-check process would've clobbered the
old err_c file.

git: unconditional expiry

A constant stream of traffic to either httpd/nntpd would mean
git-cat-file processes never expire.  Things can go bad after a
full repack, as a full repack will unlink old pack indices and
git-cat-file does not currently detect unlinked files.

We could do something complicated by recursively stat-ing
objects/pack of every git directory and alternate;
but that's probably not worth the trouble compared to
occasionally restarting the cat-file process.

So simplify the code and let httpd/nntpd expire them
periodically, since spawning a "git-cat-file --batch" process
isn't too expensive.  We already spawn for every request which
hits git-http-backend, cgit, and git-apply.

In the future, we may optionally support the Git::Raw module
to avoid IPC; but we must remain careful to not leave lingering
FDs open to unlinked files after repack.

TODO: add item for optional Cache::FastMmap

Taking one step out of setting up a performant deployment could
make setup and administration easier (at the cost of installing
an extra-but-common XS module).  This can also be useful for
the day NNTP servers see hug-of-death events.

viewdiff: avoid repeat variable expansion

This is worth a 1-2% speedup in t/perf-msgview.t rendering 2620
messages currently in https://public-inbox.org/meta/

Merge remote-tracking branch 'origin/v2-noop-speedup'

* origin/v2-noop-speedup:
  v2writable: short-circuit is_ancestor check on equality
  v2writable: avoid mm_tmp creation without regen
  v2writable: hoist out index_epoch sub
  v2writable: split off unindex_range mapping

doc/hosted: drop some links and clarify wording

I don't have time to check and train spam for all these
projects.

Spam filtering is especially difficult on ruby-core: it
enters via Redmine, so it doesn't have a distinct Received:
chain, and also gets mixed with non-spam bug-report text,
throwing off Bayes training.

And I'm not sure if those mirrors did anybody any good, even;
so lets not say its' a "service" to anybody :P

The actual mirrors remain up, for now, but who knows...
I care about decentralization too much to ask anybody
to trust me to keep anything up :P

v2writable: short-circuit is_ancestor check on equality

We don't need to use git to check ancestry if object IDs
match on a string comparison.

This saves 100ms or so and brings down the ~0.5s no-op time on
lore.kernel.org/lkml down to ~0.4s.

v2writable: avoid mm_tmp creation without regen

Creating mm_tmp is an expensive operation with large inboxes
and can be avoided if there are no new messages to process.

Since git-fetch(1) currently lacks an --exit-code option(*),
mirrors will run `public-inbox-index' unconditionally after
fetch, which is an expensive op if it needs to duplicate
a large SQLite DB.

This speeds up the mirror case of:

git --git-dir=git/$EPOCH.git fetch && public-inbox-index

This reduces the no-op `public-inbox-index' time from over 8s to
~0.5s on a (currently) 7-epoch clone of https://lore.kernel.org/lkml/
on my system.

(*) WIP --exit-code for git-fetch:
    https://public-inbox.org/git/87ftphw7mv.fsf@evledraar.gmail.com/

v2writable: hoist out index_epoch sub

This will make future changes easier-to-follow.

v2writable: split off unindex_range mapping

It'll make it easier to detect if we have anything to
unindex and run git-log on, at all.

searchidx: store indexlevel=medium as metadata

And use it from Admin.

It's easy to tell what indexlevel=basic is from unconfigured
inboxes, but distinguishing between 'medium' and 'full' would
require stat()-ing position.* files which is fragile and
Xapian-implementation-dependent.

So use the metadata facility of Xapian and store it in the main
partition so Admin tools can deal better with unconfigured
inboxes copied using generic tools like cp(1) or rsync(1).

index: remove warning on unconfigured inboxes

It's annoying for people using "git fetch && public-inbox-index"
as one user; and running -httpd/-nntpd as a different user
(where users see different config files).

Merge branch 'v2-idx-progress'

* v2-idx-progress:
  v2writable: show progress updates for index_sync
  index: support --verbose option
  v2writable: move index_sync options to sync state
  v2writable: use prototypes for internal subs
  v2writable: localize unindex-range.$EPOCH to $sync state
  v2writable: move {ranges} into $sync state
  v2writable: move {regen} into $sync state
  v2writable: move {reindex} field to $sync state
  v2writable: sync: move delete markers into $sync state
  v2writable: introduce $sync state and put mm_tmp in it

Makefile.PL: enable prove warnings

We already "use warnings" everywhere, but could miss some spots.
This ought to cover that, and usually Perl module authors are
consistent about avoiding warnings that we won't clutter our
test outputs.

Makefile.PL: allow `N' variable to be set in local config.mak

This can useful for limiting test resource use without relying
on remembering the variable command-line.

v2writable: show progress updates for index_sync

We can show progress whenever we commit changes to the FS.

index: support --verbose option

It doesn't implement progress of batches, yet, but it wires
up the parsing of the command-line while preserving output
compatibility.

This output is NOT meant to be stable.

v2writable: move index_sync options to sync state

And use singular `opt' to be consistent with the common name
of 'getopt'.

v2writable: use prototypes for internal subs

Hopefully this improves maintainability by allowing Perl
to do some arg checking for us.

v2writable: localize unindex-range.$EPOCH to $sync state

We don't need to stuff that into $self (V2Writable) which can be
longer-lived than a ->index_sync invocation.

v2writable: move {ranges} into $sync state

Yet another temporary variable with no use outside of index_sync.

v2writable: move {regen} into $sync state

regen is always enabled for index_sync nowadays (and has
been for a while).

Rename `index_prepare' to `sync_prepare' to show it's for
->index_sync; and not the online indexing we do for ->add.

v2writable: move {reindex} field to $sync state

reindexing info is not used outside of the index_sync code path.

v2writable: sync: move delete markers into $sync state

Another small step to reduce parameters passed to reindex_oid.

v2writable: introduce $sync state and put mm_tmp in it

A first step towards making the v2 index_sync code
easier-to-follow.  More fields to follow...

v2: fix reindex skipping NNTP article numbers

`public-inbox-index --reindex' could cause NNTP article number
gaps to form when it also has to deal with new,
never-before-seen commits in mirrors running off `git fetch'.

Fix this by running two distinct invocations of ->index_sync;
once to only reindex old commits, and a second time to index
new commits.

This does not appear to be a problem on v1 at the moment,
but I'll need more time to analyze this.

searchidx: fix obvious typo

We can't pass an empty string to `git merge-base --is-ancestor'
AFAIK, this did NOT present issues in the current test suite.

t/v1reindex.t: fix typo in setting `indexlevel'

It did not cause a test failure because the default fallback
is `indexlevel=full'

viewvcs: keep temporary Solver dir for large streams

Streaming large blobs can take multiple iterations of the event
loop in our -httpd; so we must not let the File::Temp::Dir
result go out-of-scope when streaming large blobs created from
patches.

v2writable: fix assertions around reindexing

Fix a misspelling and ensure line context is printed by
`die' by leaving out the final '\n'.  Also, `delete' was
pointless.

contrib/css: mark as CC0 (public domain)

No reason to copyright colour schemes :P

v2writable: drop unused $last_commits var

Apparently it's never been used and we write to msgmap directly.

t/indexlevels: fix indexlevel of ro_mirror

Don't hard-code "basic", since we already ran -init with the
intended indexlevel.

msgmap: remove double negative

I have never not found double negatives to be confusing...

TODO: more stuff: bundles, synonyms, dogfooding

git bundles could/should make self-hosting easier.

Being able to configure synonym (and spelling) lists would make
some searches more useful.

Might as well dogfood kernel stuff, too, given the overlap and
history between this project, git and the Linux kernel.  Would
be interesting to have *BSD folks throw their hat in the ring,
too.

Building/testing userspace stuff is often the most
time-consuming, but necessary to ensure future compatibility.

MANIFEST: add extman.perl

Oops :x

doc: add URLs for Xapian manpages

Since we go through the effort of hosting these manpages,
link to them.

doc: xcpdb: add switch documentation

In particular, the '--compact' switch is really useful since it
works without holding the inbox-wide lock for minutes at a time
on giant inboxes (inboxes where copies can take dozens, if not
hundreds of minutes).

doc: generate manpages for some Xapian commands

They're nowhere to be found on Xapian.org, and links to
external services are either too long (for manpages.debian.org)
or have privacy-invasive tracking JS on them.

doc: sync .txt mtime to .pod mtime

Otherwise timestamps for .html files get screwed up, too;
and that hurts caching.

doc: don't barf on missing `git set-file-times'

It's not critical, but it's nice to have for cache-friendliness
(otherwise I would not have written it :P)

I guess I should follow up on getting it into 'git contrib/':
https://public-inbox.org/git/20100702033709.GA6818@burratino/

doc: daemon: fix manpage section for nginx

The nginx manpage is in section 8.

doc: index: fix miscapitalization of "SQLite"

Oops :x

search: don't log all warnings on retry_reopen

Some users (or bots :P) can trigger horrible queries which
the caller can choose to either log or ignore.  This prevents
horrible queries from ExtMsg from logging confusing "ref: "
messages when $@ is not a Perl reference.

doc: various updates to reflect current state

-index documentation avoid redundant v1 information and refers
readers to apropriate v1/v2 manpages.  Search::Xapian can also
be optional, now, as only the PSGI search interface uses it.

Favor "INBOX_DIR" where appropriate, since "REPO_DIR" can be
confused for code repos which we also support.

XAPIAN_FLUSH_THRESHOLD is documented for all relevant
bulk commands.

xapcmd: do not reset %SIG until last Xtmpdir is done

To properly handle compact tmpdir cleanup in single process
situations, we need to carefully account for Xtmpdir not
being a singleton and ensuring we don't clobber signal
handlers which belong to other Xtmpdirs.