TODO: various updates

githttpbackend: require IO::File explicitly

This is used all over the place, but may not be in the future,
so ensure we explicitly load it ourselves.

remove GIT_DIR env usage in favor of --git-dir

No need to maintain per-block environment state when we can
localize it to per-command.  We've had --git-dir= in git
since 1.4.2 (2006-08-12) and already use it all over the
place.

remove ssoma dependency

By converting to using ourt git-fast-import-based Import
module.  This should allow us to be more easily installed.

import: extra check for final byte read

The read could fail entirely and leave $lf undefined.

nntp: reduce timers for weakening

Danga::Socket timers are not cheap, so avoid creating up
to 3 timers per-newsgroup by batching resource weakening.
This lets us reduce resource consumption for scheduing
additional resource consumption reduction :)

nntp: remove unused hdr_val subroutine

hdr_val has not been used since commit 1d236e649df1
("nntp: implement OVER/XOVER summary in search document")

split out NNTPD and HTTPD* modules

Hopefully this modularizes things a little and allows us
to work on a combined super server to save RAM.

mda: don't clobber existing List-Id header

We may be importing mail from other lists, so do not
clobber the existing List-Id header.

searchview: add "rel=next" and "rel=prev" here, too

ref: https://www.w3.org/TR/html/links.html#sequential-link-types

Followup-to: c4183f56aab6 ("www: add rel=next and rel=prev navigation hints")

www: add rel=next and rel=prev navigation hints

This can makes navigation easier with some browsers or
or browser extensions.

ref: https://www.w3.org/TR/html/links.html#sequential-link-types

view: fix link generation for replies in threads

Oops, gotta test this :x

view: add extra newline in flat thread view for lynx

This shouldn't show up in other browsers (tested with w3m, too),
but the extra newline makes a difference for delineating
messages when viewed with lynx.

view: more consistent prefixing for thread skeletons

This will allow potential tinkerers to switch away from the '` '
prefix more easily.

mda: reject multiple Message-IDs up front

While ssoma now documents it uses the first Message-ID, they
are confusing and could be a sign of a broken mail software,
and broken mail software is often a sign of spam...

ref: http://public-inbox.org/meta/20160421221128.4910-1-e@80x24.org/

view: show flat thread view in chronological order

Allowing readers new to a topic to follow in chronological order
probably makes the most sense.  Reverse chronological order may
reduce scrolling (e.g. log view); but nearly all non-threaded
conversation displays seem to be chronological so perhaps
there's a good reason for that.

view: thread skeleton tweaks

Allow the Subject: <-> skeleton line to point to each other so
the reader can bounce around between them without refocusing
their browser.

www: redirect /$MESSAGE_ID/f/ endpoints

Quote-folding was a major design mistake pre-1.0.  Since this
project is still in its infancy and unlikely to be in wide
use at the moment, redirect the /f/ endpoints back to the
plain message.

doc: update design notes on WWW development

Start documenting our anchors and CSS classes for in case users
want to write their own CSS or even JavaScript for local usage.

view: drop vestigial elements of quote folding

...And mark quotes as <span class="q"> since it barely
costs us anything and allows users to choose colors
themselves with custom, user-supplied CSS.

Reduce allocations of the Linkify object, too.

www: stop generating /$MESSAGE_ID/f/ links

Quote-folding can be detrimental as it fails to hide the
real problem of over-quoting.

Over-quoting wastes bandwidth and space for all readers, not
just WWW readers of the public-inbox.  So hopefully removing
quote-folding support from the WWW interface can shame those
repliers into quoting only relevant portions of what they reply
to.

view: fix link to view replies from $MESSAGE_ID/f/ links

Oops, $MESSAGE_ID/f/R/ screws up rather badly.

searchview: deal with the removal of rsort

Oops.  While we're at it, simplify the calls to do threading
slightly by reducing the places where we touch Mail::Thread
globals.

Fixes: 56164afc2034 (view: allow topics to be "bumped" by new replies)

mbox: do not clobber existing archive headers in WWW

When serving archives, it's more robust to keep existing
archive links in one server goes down.

view: allow topics to be "bumped" by new replies

This ought to prevent new replies from getting lost for readers
relying on the WWW index interface.

import: filter out [<>] from user names

It confuses the git ident parser and may not be a great
idea to fix in git since it could break interopability
with older versions.

import: use bytes::length for true data length in bytes

git is byte-oriented and fast-import will not tolerate
miscalculations.  This is necessary for wide characters
in commit messages (email Subjects).

import: set binmode before printing author names

Author names may have wide characters in them, so avoid warnings
as git favors UTF-8 for names and fast-import even requires them
for commit messages

import: initial module + test case

This will allow us to write fast importers for existing
archives as well as eventually removing the ssoma dependency
for performance and ease-of-installation.

git: add support for qx wrapper

This lets us one-line git commands easily like ``, but without
having to remember --git-dir or escape arguments.

mbox: unconditionally add trailing newline

This may be necessary for compatibility with non-mboxrd aware
parsers which expect "\nFrom " for everything but the first
record.

public-inbox-learn: drop leading "From " line from mboxes

It can confuse Email::MIME if we have it.

filter: remove out dated comments

Followup-to commit 5a590bcb6813
("filter: preserve Mail-Followup-To and Mail-Reply-To")

filter: preserve Mail-Followup-To and Mail-Reply-To

Allow users to do wacky things here if they really wish...
It's bad practice, but at least allow other readers to
mock users of these headers :P

view: account for threads lacking a common parent

In the per-message view, we still need to account for threads
lacking a common parent.  This can happen when threads are
broken by some broken clients or if somebody sends the same
message twice to the same inbox with a different Message-ID.

view: shorter link for ghosts in per-message view

Shorten lines used for long Message-IDs in the
inline thread view for per-message views for readability.

view: do not prune ghosts from threads

Keeping readers informed of ghost messages is important,
so do not ever prune them.  Previously, ghosts could get
pruned and sole children would get promoted as the new
root.

view: eliminate dead code and hash fields

These were the vestigial remains of our previous use of
of Message-ID compression.

examples/public-inbox.psgi: add note for our httpd

Default to maximizing compatibility in the example, but document the
potential improvement if possible.  Of course, using
public-inbox-httpd out-of-the-box without a user-specified config
file already enables chunked encoding by default.

http: clarify intent for persistence

We don't actually need to know if a response is chunked or
what the actual Content-Length is; we just need to know if
the PSGI app properly terminated the response so we can
handle persistent connections.

view: link restructuring for index view

The "next/prev" links seem a bit awkward and I don't use them as
much as I expected to.  However, move the "raw" message link
near the top since it's most useful for checking or reinforcing
the validity of the message via GPG or just reading headers.

Turn the Subject line into a permalink to the message, since
that's probably the common behavior anyways for other messaging
systems.  Make the "[threaded|flat]" view links to always
visible for bookmark-ability despite the lack of a "permalink"
label.

http: fix condition for detecting persistence

Oops, we need to watch out for how we handle operator
precedence and ensure responses without a Content-Length
or "Transfer-Encoding: chunked" header will always
disconnect after writing.

www: more explicit "git clone" usage

Little harm in having the entire command-line for users and
avoiding the cognitive overhead of figuring out $URL.

www: various style changes and comment updates

Reduce stack depth of arguments and rely more on state hashref
to store response state.  We may end up shoving everything
in ctx eventually.

httpd: remove reference to callback during close

Avoid wasting memory and the risk of a potential reference
cycles by dropping the callback ASAP.

daemon: expand @ARGV paths for running in '/'

We also require --stdout/--stderr/--pid-file to be absolute
paths for USR2 usage.  However, allow PSGI files for -httpd
to be relative paths for ease-of-use.

feed: fix brain farts in new_oneline removal

Ugh...

Fixes: 476fc666c223 (reduce "PublicInbox::Hval->new_oneline" use)

searchmsg: preserve hard tabs, but drop CR (\r)

Hard tabs *may* be searchable, so preserve them since they do
not take up any more space than a normal space.  However, CR
(carriage return) is worthless and likely a sign of a buggy mail
(or spam) client anyways.

reduce "PublicInbox::Hval->new_oneline" use

It's probably a bad idea to strip extraneous whitespace
from some headers as an extra space may convey useful
information.

Newlines don't seem to be preserved by Email::MIME or
Email::Simple anyways, so there's no danger in breaking
formatting.

http: use Plack::HTTPParser for HTTP parsing

This allows us to reduce installation dependencies while
retaining performance as it favors HTTP::Parser::XS when
it is installed and available.

PLACK_HTTP_PARSER_PP may be set to 1 to force a pure Perl
parser for testing.

examples: disable Chunked response in PSGI example

It seems incompatible with Starman and probably confuses other
HTTP/1.0-only servers, too.  Our -httpd will respect it and
requires it for persistent connections.

http: prevent zero-byte writes

Plack::Middleware::Deflater (and perhaps other middleware)
triggers zero-byte writes which wastes syscalls when
they get passed to Danga::Socket.  This may also trigger
problems when we introduce TLS support in the future.

daemon: fixup usage of the '-l' switch with IP/INET6 sockets

We need to ensure $sock_pkg is preserved outside of the loop.
The variable passed to "for" or "foreach" is implicitly local
and restores the previous value when the loop exits.  This is
documented in the perlsyn manpage in the "Foreach Loops"
section.

Fixes: ea1b6cbd422b ("daemon: allow using IO::Socket::IP over INET6")

daemon: allow using IO::Socket::IP over INET6

IO::Socket::IP is bundled with newer versions of Perl,
so it is more likely to be available.  There should
be no differences between these with our use cases.

http: reject excessively large HTTP request bodies

We cannot risk using all of a users' disk space buffering
gigantic requests.  Use the defaults git gives us since
we primarily host git repositories.

http: ensure errors are printable before PSGI env

We cannot rely on a client socket having a PSGI env before headers
are fully-parsed as we seek to avoid storing hashes for idle
clients.  Sso print errors to the psgi.errors value which belongs to
the httpd listener, instead.

http: reject excessive headers

HTTP::Parser::XS::PP does not reject excessively large
headers like the XS version.  Ensure we reject headers
over 16K since public-inbox should never need such large
request headers.

daemon: sockname detects listeners correctly

This means we can avoid false-positives when inheriting multiple
Unix domain sockets.

daemon: document optional Net::Server dependency

Non-socket activation users will want to install Net::Server
for daemonization, pid file writing, and user/group switching.

doc: add contact/see-also/copyright sections to mda manpage

We need manpages before we can expect people to install this.

httpd: remove unnecessary eval

We have per-middleware evals to deal with them being missing;
no need to put an eval around the whole thing and use an
extra level of indentation.

t/httpd-corner: avoid clobbering existing FDs after fork

Due to the deterministic way reference counting works,
we do not want to drop references to existing FDs
even if we no longer need the glob reference; the actual
FD is all we can pass through on exec.

doc: language-neutral client-side endpoints

Be less specific, client-side code can be written in any
language (and I do not care for JS runtimes implemented in
C++ :P).

doc: varyus speling fickses

Letz trie 2 uphear liter8

feed: remove unnecessary encoding lookup

We handle encoding-related things elsewhere.

daemon: simplify parent death handling

No need to create a new sub which kill ourselves $$ when we can
invoke worker_quit directly.

daemon: avoid cyclic references for once-used callbacks

Not that these subs are repeatedly created, but this makes
the code easier-to-review and these callbacks are idempotent
anyways.

daemon: drop listener sockets ASAP on termination

We do not want to be accepting connections during graceful
shutdown because another new process is likely taking over.
This also allows us to free up the listener case another
(independent) process wants to claim it.

t/httpd-corner: additional callback test

Just to ensure we hit the code path independently of
WWW code.

git-http-backend: favor sysread for regular files

We do not need line buffering, here; so favor sysread to
bypass extra copies which may be done by normal read.

daemon: simplify socket inheriting, slightly

IO::Handle->new_from_fd has existed since at least 1996,
so it should be safe to depend on at this point.

daemon: support listening on Unix domain sockets

Listening on Unix domain sockets can be convenient for running
behind reverse proxies, avoiding port conflicts, limiting access,
or avoiding the overhead (if any) of TCP over loopback.

daemon: introduce host_with_port for identifying sockets

This allows us to share more code between daemons and avoids
having to make additional syscalls for preparing REMOTE_HOST
and REMOTE_PORT in the PSGI env in -httpd.

This will also make supporting HTTP (and NNTP) over Unix sockets
easier in a future commit.

daemon: avoid polluting the main package

We've distilled the daemon code into one public function ("run"),
so avoid polluting the main namespace and just have users
prefix with the full package name for this rarely-used class.

t/*.t: use identifiable tempdir names

This should make identifiying leftover directories
due to SIGKILL-ed tests easier.

view: fix stupid typo in inline_dump

Ugh, this enabled-iff-xapian-is-available code really
needs better testing...

use raw header for Message-ID

Message-IDs should not be MIME encoded, but in case they are,
use the raw form for compatibility with ssoma and possibly
other tools.  This prevents a potential problem where a
malicious client could confuse our storage layer into indexing
incorrect contents.

http: better error handling for EMFILE/ENFILE

Better to throw the error back to the client ASAP if we're
out-of-descriptors.  We will need to implement idle client
expiration for long-lived HTTP connections.

httpd: remove unneeded err and out fields from class

Vestigial pieces from the nntpd code which aren't needed because
the psgi env already has the "psgi.errors" key.

httpd: document pi-httpd.async as totally unstable

We'll have to use it some more before deciding it is a public
interface.  I do hope for it to be a usable public interface
one day for other users.

processpipe: preserve native close behavior

We need to ensure close on handles tied to this class
get the same errors a normal "close" in Perl gets.

linkify: do not capture trailing '.' or ';' in URLs

It seems common for users to end statements with URLs,
while it is rare for a URL itself to end with a '.' or ';'.
So make a guess and assume the URL was intended to not
include the trailing '.' or ';'

extract linkification code to a separate package

This will allow us to more easily reuse it elsewhere.

MANIFEST: add examples/apache2_perl_old.conf

Ugh, I wonder if we can/should generate this automatically...

view: consolidate whitespace stripping from messages

We now keep intermediate blank lines in messages, since it
could be used to denote logical gaps in the message
(such as giving readers a chance to opt out of "spoiler"
information).

However leading blank lines, trailing blank lines, and
trailing whitespace have no useful value we can discern;
so drop those entirely to prevent clients from eating up
vertical whitespace.

view: do not hide patches or signatures

It's often not that much information and may be useful
to reduce HTTP requests a reader will want to make.

fixup Plack-related requires

We do not need to load Plack::Request outside of WWW anymore.

t/init.t: avoid spewing directory names in output

This is a step towards having consistent, reproducible
test output. (ugh, but each %hash usage screws that up).

t/search.t: use transactions to reduce I/O load

In case folks do not use eatmydata or tmpfs for testing,
use transactions to reduce the number of fsync calls
made and hopefully prevent drives from wearing out.

git-http-backend: fixes for mod_perl

Apache2 mod_perl does not give us a real file handle, so
we must translate that before giving that to git-http-backend(1).

Also, parse the Status: correctly for errors since we failed to
set %ENV properly before the previous fix for SpawnPP

spawnpp: use env(1) for mod_perl compatibility

We cannot modify %ENV directly under mod_perl (even after forking!),
so use env(1) instead to pass the environment.

git-http-backend: stricter parsing of CRLF

It is not needed as we know git uses CRLF termination.

favor procedural calls for most private functions

This makes for better compile-time checking and also helps
document which calls are private for HTTP and NNTP.

While we're at it, use IO::Handle::* functions procedurally,
too, since we know we're working with native glob handles.

distinguish error messages intended for users vs developers

For error messages intended to show user error (e.g. giving
invalid options), we add a newline ("\n") at the end to
polluting the output with location information.

However, for diagnosing non-user-triggered errors, we should
show the location of where the error occured.

http: avoid needless time2str calls

Checking the time is nearly free on modern systems with
vDSO/vsyscall/similar while sprintf is always expensive.

http: document event_write usage

It may not be obvious where we are when we enter the event_write
callback.  Hopefully this clarifies things.

http: error check for sysseek on input

Just in case we screwed up somewhere, we need to match up
syswrite to sysseek and we also favor procedural calls for
native types.

examples/public-inbox.psgi: relax license to GPL-3.0+

Using the AGPL for server config files is probably overkill.
GPL-3.0+ still requires appliance vendors to disclose
configurations which seems desirable for end users.

examples: various Apache-related doc updates

Plack::Handler::Apache2 exists and seems to work very well.

examples/cgi-webrick.rb: set CGIPathEnv, update comments

webrick clears PATH otherwise, and we rely on git commands.