TODO: update linkification notes

Some readers will want to use "HTTPS Everywhere" conveniently;
and I will support it.

git-http-backend: cleanup vestigial the process limiter code

This bit is still being redone to support gigantic repos.

config: use popen_rd when spawning `git config'

We may spawn this in a large server process, so be sure
to take advantage of the optional vfork() support when
for folks who set PERL_INLINE_DIRECTORY.

t/config.t: remove GIT_DIR usage in test

Followup-to: commit 24e0219f364ed402f9136227756e0f196dc651aa
("remove GIT_DIR env usage in favor of --git-dir")

daemon: ignore SIGWINCH when connected to terminal

Users may change terminal sizes if the process is connected to a
terminal, so we can't reasonably expect SIGWINCH to work as
intended.

spawn: note we do not use absolute paths within our code

We can't rely on absolute paths when installed on other
systems.

Unfortunately, mlmmj-* requires them, but none of the core
code will use it.

www: avoid warnings on bad offsets for Xapian

The offset argument must be an integer for Xapian,
however users (or bots) type the darndest things.

AFAIK this has no security implications besides triggering
a warning (which could lead to out-of-space-errors)

git-http-backend: switch to async_pass

This simplifies the code somewhat; but it could probably
still be made simpler.  It will need to support command
queueing for expensive commands so expensive processes
can be queued up.

http: rework async_pass support

Unfortunately, the original design did not work because
middleware can wrap the response body and make `async_pass'
invisible to HTTP.pm

git-http-backend: simplify dumb serving

We can rely entirely on getline + close callbacks
and be compatible with 100% of PSGI servers.

git-http-backend: remove process limit

We will figure out a different way to avoid overloading...

t/spawn.t: additional tests for popen_rd

We need to ensure $? is set properly for users.

http: pass reference to Danga::Socket::write

This can avoid an expensive copy for big strings.

http: fix typo: write_buf => write_buf_size

Otherwise, we get deep recursion as we keep calling
recursively on giant responses

http: async getline supports push_back_read

Sometimes we need to read something to ensure it's a successful
response.

http: support async_pass for Danga::Socket

This will allow us to minimize buffering after we wait
(possibly a long time) for readability.  This also greatly
reduces the amount of Danga::Socket-specific knowledge we
have in our PSGI code, making it easier for others to
understand.

import: avoid needless git update-server-info

We don't need to update-server-info (or read-tree) if fast
import was spawned for removals and no changes were made.

daemon: simplify forking

We shouldn't need sigprocmask unless we're running multiple
native threads or using vfork, neither of which is the case,
here.

localize $/ in more places to avoid potential problems

This hopefully makes the intent of the code clearer, too.
The the HTTP use of the numeric reference for getline
caused problems in Git.pm, already.

mbox: switch generation over to pull model

This allows us to easily provide gigantic inboxes
with proper backpressure handling for slow clients.

It also eliminates public-inbox-httpd and Danga::Socket-specific
knowledge from this class, making it easier to follow for
those used to generic PSGI applications.

http: reduce over-buffering for getline responses

By switching to a "pull"-based I/O model for reading
application responses, we should be able to throttle
buffering to slow clients more effectively and avoid
wasting precious RAM.

This will also allow us to more Danga::Socket-specific
knowledge out of the PSGI application and keep it
confined to PublicInbox::HTTP.

ssoma-replay: use TMPDIR for temporary path

Otherwise, tempfile() will use the current working directory,
which may not be writable.

www: tighten up allowable filenames for attachments

Having a file start with '.' or '-' can be confusing
and for users, so do not allow it.

view: reduce clutter for attachments w/o description

For attachments without a filename or description, reduce
the amount of precious screen space required to display
a link to it.

www: validate and check filenames in URLs

We shall ensure links continue working for this.

msg_iter: workaround broken Email::MIME versions

Email::MIME >= 1.923 and < 1.935 would drop too many newlines
in attachments.  This would lead to ugly text files without
a proper trailing newline if using quoted-printable, 7bit, or
8bit.  Attachments encoded with base64 were not affected.

These versions of Email::MIME are widely available in Debian 8
(Jessie) and even Ubuntu LTS distros so we will need to support
this workaround for a while.

www: support downloading attachments

This can be useful for lists where the convention is to
attach (rather than inline) patches into the message body.

switch read-only uses of walk_parts to msg_iter

msg_iter lets us know the index of the attachment,
allow us to make more sensible labels and in a future
commit, hyperlinks to download attachments.

msg_iter: new internal API for iterating through MIME

Unlike Email::MIME::walk_parts, this is non-recursive and gives
depth + index offset information about the part for creating
links for later retrieval

It is intended for read-only access and changes are not
propagated to the parent; however future versions of it
may clobber bodies or the original version as it iterates
to reduce memory overhead.

It is intended for making it easy to locate attachments within a
message in the WWW view.

view: rely on Email::MIME::body_str for decoding

Or is it "encoding"?  Gah, Perl character set handling
confuses me no matter how many times I RTFM :<

This contains placeholders for attachment downloading
which will be in a future commit.

nntpd: avoid uninitialized warning

Oops, but at least it was mostly harmless, just ugly.

Followup-to: 9bfe40e7a4ac 'nntp: use "newsgroup" instead of "name"''

nntpd: reject control characters entirely

There's no place for them in the commands and we don't take
messages; potentially printing them into a log opened in a
terminal is too dangerous.

Hoist out read_til_dot in the test while we're at it.

tests: add check-www-inbox script

This can be useful for hammering a live HTTP server
with requests to ensure it does not fall over under
load.

view: avoid redirect to reply endpoint

Oops, but perhaps the "reply" endpoint should be embedded
into the permalink message view itself to reduce URLs.

feed: inline feed entry generation

Remove unnecessary wrapper subroutines and constants
which are only used once.

http: release resources when idle

This lets us release old git processes so unlinked packs
(leftover from repacking) can be released.  This may also
be helpful for Xapian as indices get rebuilt for tuning.

For SQLite (msgmap), the there may be no benefit besides
reducing FD pressure.

Followup changes will unify the Inbox and NewsGroup
classes and allow better code-sharing between NNTP and
HTTP classes (as well as the planned POP3 class).

view: escape Message-ID for "next" link

Oops, we need to escape Message-IDs since they can contain
bad characters such as '%' in them.  '@' actually seems fine
and does not need to be escaped; however, but we've been
doing it forever.

www: fix for running under mount paths

We try to avoid issues like these by using relative URLs
in hrefs, but we can't avoid the problem with Location:
for redirects and Atom feeds which are likely to be
rehosted elsewhere.

We also reorder some of the code to work around a weird
issue on the psgi-plack mailing list:
<20160516073750.GA11931@dcvr.yhbt.net>
(Somewhere on https://groups.google.com/group/psgi-plack
 but it's probably not bookmarkable)

config: allow taking an existing reference

This should make creating test cases easier and faster.

declare Inbox object for reusability

From the beginning, we've avoided objects here in favor
of faster startup time; but it may not be worth it
since a persistent httpd/nntpd is faster and -mda
isn't hit as often.

doc: sync ~/.spamassassin/user_prefs with my prod machine

This is what I'm running on public-inbox.org as of today.

mbox: support /$INBOX/all.mbox.gz endpoint

Allows easily downloading the entire archive without
special tools.  In any case, it's not yet advertised to via
HTML until we can test it better.  It'll also support range
queries in the future to avoid wasting bandwidth.

mbox: consistent header order when decompressed

This should make validating the output easier
when testing between different servers.

git-http-backend: set cache headers

Mostly stolen from git upstream, these should prevent any caches
such as varnish or squid from acting improperly.

rename most instances of "list" to "inbox"

A public-inbox is NOT necessarily a mailing list, but it
could serve as an input point for zero, one, or infinite
mailing lists :D

nntp: use "newsgroup" instead of "name"

This reduces the cognitive overhead for mapping names of
configuration values to internal field names of our classes.
Further changes along these lines coming...

import ssoma-replay example script I've been using

Unfortunately, most users still prefer their mail delivered
over SMTP; so we'll at least document mlmmj integration for now
until we can popularize pull-based reading over POP3/NNTP/ssoma.

t/nntpd: test for wide characters and UTF-8 mangling

We'll need to test non-UTF-8 messages at some point, too.
There are lots of legacy-encoded messages in old archives
and I would not bet we behave sanely w.r.t. those.

t/nntpd: avoid fork+exec for search indexing

The Xapian search index is required for the NNTP server, so
there's no point in calling system() for it like we do in
other tests.  This should speed up the test a small amount.

build: support eatmydata in "make check" target by default

This should help poor developers who still use rotating disks on
cheap netbooks.

nntp: fixup "Wide character" warnings

We need Perl to believe everything we send is UTF-8,
make it so, even if it may not be.

Fixes: 265e79ff82ce 'Revert "nntp: proper UTF-8 support (hopefully?)"'

Revert "nntp: proper UTF-8 support (hopefully?)"

This reverts commit f81ad477cb013d05b9b11fa051a9ebc5983a5be6.

The raw, undecoded body is probably what should be sent over the
wire anyways for clients to deal with.  We'll need this to avoid
deprecation warnings with Perl 5.24+ since we use
send()/recv()/sysread().

git-http-backend: do not drop connection on successful finish

We can maintain the client HTTP connection if the process exited
with failure as long as we terminated our own response properly.

import: fallback to email if '<>' exists in author name

git doesn't handle '<' and '>' characters in the author
name at all regardless of quoting, not just matched pairs.
So fall back to using the email as the author name since
the commit info isn't critical, anyways (shallow clones
are fine).

import: normalize body by stripping trailing newlines

Mbox formatters may add extra newlines at the end of the
message, and that's not relevant for comparing messages
for deletion.

mbox: sort messages by ascending date

This allows messages to be read in chronological order when
read without a mail client (e.g. with "zcat t.mbox.gz | less")

t/view: note possibly invalid test...

Ugh, I really need to get off my ass to write automated tests for
an Apache2 + mod_perl config.

git-http-backend: reduce memory use for clone/fetch

When serving large static files or large packs, we may call
Danga::Socket::write directly to queue up callbacks to resume
reading and defer firing them until the socket is writable.
This prevents us from scheduling writes or buffering until we
know the socket is writable and prevents needless buffering by
Danga::Socket when faced with slow clients.

For smart clones, this comes at the cost of throttling the
output of "git pack-objects" to the speed of the client
connection.  This is probably not ideal, but is the behavior of
the standard git-daemon, too; and is preferable to running the
httpd out-of-memory.  Buffering to the filesystem may be an
option in the future...

http: move empty string check into write callback

This empty string check is for middlewares such as Deflater
which may write empty strings, not for direct real callers of
Danga::Socket who (presumably) know what they're doing.

spawnpp: use native perl %ENV outside of mod_perl

We only need to use env(1) under mod_perl; since mod_perl
is uncommon nowadays, support native %ENV for a teeny
speedup for folks uncomfortable with running vfork via
Inline::C snippet.

t/*.t: reduce -mda calls

Process startup times are atrocious for fast tests and there's far
too much setup involved.  Rely on git-fast-import instead; but
more work is needed in this area.

t/nntpd.t: stop hard coding message :bytes into test

It limits flexibility and makes it harder to switch
to use PublicImport::Import.

nntp: append Archived-At and List-Archive headers

For readers using NNTP, we should do our best to advertise the
clonable HTTP/HTTPS URLs and the message permalink URL for
ease-of-referencing messages, since we don't want the NNTP server
and it's sequential article numbers to be relied on.

view: disable subject threading

Broken threads should be exposed to hopefully encourage people to
use proper mail clients which set In-Reply-To headers.

http: remove needless binmode call

Unnecessary on *nix, and we won't support systems
which do insane things.

spawn: proper signal handling for vfork

We cannot afford to fire Perl-level signal handlers in the
vforked child process since they're not designed to run in
the child like that.

Thus we need to block all signals before calling vfork, reset
signal dispositions in the child, and restore the signal mask in
the parent.

ref: https://ewontfix.com/7

git-http-backend: use real lseek for Content-Range

Since we use sysread, we must use sysseek for symmetry although
PerlIO may be doing a real lseek with "seek", anyways.

Fixes: 310819ea86ac ("git-http-backend: favor sysread for regular files")

daemon: reduce timer-related allocations

We can reduce the allocation and overhead needed for
Danga::Socket timers for immediately-executed responses by
combining identical timers and reducing anonymous sub creation.

mda: export @BAD_HEADERS variable

This should allow users to change and add headers as needed.
While we're at it, add the X-Original-To header Postfix likes
to add; it seems like pointless bloat with the existence of
(important) Received: headers.

linkify: match more URL characters [:,\$] and schemes

Adding ':' (colon), ',' (comma), '$' (dollar sign) and
supporting TLS-enabled schemes: ftps, nntps variants as
well as gopher :D

linkify: match '~' (tilde) in URLs

Tilde is common for some homepages: http://example.org/~user/
There's probably some other acceptable characters I'm missing.

daemon: graceful shutdown warning and limit removal

git clones may take longer than 30s, much longer...  So prepare
to wait almost indefinitely for sockets to timeout and document
the second signal behavior for immediate shutdown.

While we're at it, move parent death handling to a separate
class to avoid Danga::Socket->AddOtherFds, since that does not
allow proper handling the parent pipe being closed and would
actually misterminate a worker prematurely.  t/nntpd.t is update
to illustrate the failure with workers enabled.

We will work to keep memory usage low and let clients take their
time without interrupting them.

http: graceful shutdown for pi-httpd.async callers

git clones may take a long time and it's wrong to
drop connections in the middle of a transaction.

searchmsg: ensure long subject lines are not broken

Noticed when using a long URL in the subject.

http: avoid lseek if no input

This saves us a system call for common GET/HEAD requests
with no upload body.

TODO: add item for .mailmap support

Email addresses get out-of-date, so make sure they're mapped
properly for future readers.  git and linux-kernel already have
an established convention for this, so we will follow it.

http: improve error handling for aborted responses

We need to abort connections properly if a response is prematurely
truncated.  This includes problems with serving static files, since
a clumsy admin or broken FS could return truncated responses and
inadvertently leave a client waiting (since the client saw
"Content-Length" in the header and expected a certain length).

git-http-backend: check EINTR as well as EAGAIN

The blocking PSGI server may cause EINTR to be hit, here.

http: avoid corking on "Content-Length: 0" response

We must use a normal write instead of send(.., MSG_MORE)
when writing responses of "Content-Length: 0" to avoid
the corking effect MSG_MORE provides.  We only want to
cork headers if we will send a non-empty body.

Fixes: c3eeaf664cf0 ("http: clarify intent for persistence")
This needs a proper test.

githttpbackend: clamp to one smart HTTP request at-a-time

Server admins may not be able to afford to have too many
git-pack-objects processes running at once.  Since PSGI
HTTP servers should already be configured to use multiple
processes for other requests; limit concurrency of smart
backends to one; and fall back to dumb responses if we're
already generating a pack.

githttpbackend: fall back to dumb if smart HTTP is off

Using http.getanyfile still keeps the http-backend process
alive, so it's better to break out of that process and
handle serving entirely within the HTTP server.

import: run git-update-server-info when done

We should update $GIT_DIR/info/refs for dumb HTTP clients
whenever we make changes to the repository.  The best place
to update is immediately after making commits.

This fixes a bug where public-inbox-learn did not properly
update $GIT_DIR/info/refs after inserting or removing
messages.

import: document API for public consumption

This is probably trivial enough to be final?

t/feed.t: run properly without ssoma installed

While we're at it, update some references to ssoma in the
Makefile.PL comment.

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.