examples: consolidate systemd socket examples

systemd.socket(5) files can actually contain multiple listen
sockets, so shave down inode overhead and simplify config
file management by consolidating all applicable ports into
a single file for each daemon.

doc: drop ancient Apache and WEBrick examples

Having old, unmaintained docs for other HTTP servers is likely
harmful at this point.  public-inbox-httpd is specifically
designed to handle git repos on slow storage and stream giant
mbox.gz files fairly to slow clients.

devel/syscall-list: support non-Linux, show sizeof(pid_t)

While I have no intention of using syscall numbers for
non-Linux, sizeof(pid_t) was useful for OpenBSD.  And maybe
Linux can have real competition from other OSes with stable
syscall numbers someday.

pop3d: enable native fcntl locks on all *BSDs

...as we've already done for the simpler case of mbox locking in lei.
I've just confirmed NetBSD and OpenBSD share the same "struct flock"
with FreeBSD, and assume DragonflyBSD is the same.  sizeof(pid_t) == 4
in all places I've checked, and it's unlikely we'll need 64-bit
pid_t any time soon...

www: inbox: favor "pop3://" over "pop://"

curl only supports "pop3://" and "pop3s://", despite RFC 2384
existing for "pop://".  AFAIK, there's no RFCs for "pop3://"
and "pop3s://", but please let us know if there are.

In any case, real-world cases like curl are more relevant.

doc: add WIP 1.9 release notes

I think "lei reindex" and some doc cleanups will be the last
things before 1.9...

www_text: fix #nntp anchor for there's a single NNTP server

We use "Newsgroup" (singular) when there's only one NNTP
server address configured.

daemon: rely on $SIG{__WARN__} for error output

warn/carp usage is unavoidable given Perl itself and standard
libraries, so just rely on localized $SIG{__WARN__} from
60d262483a4d6ddf (daemon: use per-listener SIG{__WARN__} callbacks, 2022-08-08)
for all error reporting.

While we're in the area, make some of the error handling more
consistent between IMAP/NNTP/POP3.

www_text: add AUTH=ANONYMOUS to IMAP URLs

While the ';' requires escaping on the command-line, the
presence of ";AUTH=ANONYMOUS" communicates clearly that
anonymous access is supported in accordance to RFC 4505.

www_text: clarify the password+username is for POP3

NNTP and IMAP can also exist in the same area, so clarify
that the username + password is only for POP3

www_text: add #nntp, #pop3, and #imap anchors to help HTML

This will make it easier to link to these sections in
3rd-party documentation.

pop3: remove untouched rows on QUIT/disconnect

Some POP3 clients may connect and never retrieve messages nor
trigger deletes.  In that case, save some storage by removing
unused rows from the `deletes' and `users' tables.

imapd|nntpd: drop ->base_url preload

It was never useful for IMAP, and NNTP hasn't needed it since:
1bf653ad139bf7bb (nntp+www: drop List-* and Archived-At headers, 2020-12-10)

imap: mailboxes list across listeners

Since IMAP mailbox lists are tied to the PublicInbox::Config
object, we can share them the same way the config object is
shared when an -imapd or -netd instance has multiple listeners.

This ought to reduce memory use and startup time when binding
multiple sockets which share a common config file.

daemon: cleanup internal data structures

This avoids dangling {''} entries in $xnetd and
%tls_opt hashes.  Furthermore, we can safely undef
%tls_opt once it's associated with each $xnetd object.

daemon: use per-listener SIG{__WARN__} callbacks

This allows "-l $ADDRESS?err=/path/to/err.log to isolate normal
warn() (and carp()) messages for a particular listen address to
track down errors more easily.

daemon: use default address + well-known ports for scheme

This ensures the "bound $URL" diagnostic message at startup
always shows the URL scheme handled if not relying on socket
inheritance.

This also avoids duplicate/unused data structures when binding
sockets ourselves, as bound socket names can expand from short
names to longer names (e.g. "0:119" => "0.0.0.0:119").

README: recommend AUTH=ANONYMOUS on IMAP URLs

public-inbox-imapd prioritizes AUTH=ANONYMOUS clients, nowadays,
since it's a good heuristic for legitimate client traffic.

imap: prioritize AUTH=ANONYMOUS clients

...by deprioritizing clients using a username + password.

As IMAP provides AUTH=ANONYMOUS for designating anonymous
access, we'll rely on it as a heuristic for favoring "good"
clients.  Clients using a username + password seem to (more
often than not) be malicious and looking for info which doesn't
belong in public inboxes.

This copies the technique used by WWW + -httpd to deprioritize
expensive mbox.gz downloads.

imap: only give AUTH=ANONYMOUS clients prefetch

Looking at IMAP traffic on public-inbox.org, it seems there is a
fair amount of traffic coming from malicious clients assuming
the IMAP server is compromised and searching for private
information.  Since AUTH=ANONYMOUS clients are more likely to
be legitimate clients looking for publicly-archived mail,
give them priority.

imap: limit ibx_async_prefetch to idle git processes

This improves fairness while having no measurable performance
impact for a single uncached IMAP client (mutt) opening a folder
for the first time.

I noticed this problem with the public-inbox.org IMAP server where
a few IMAP clients were unfairly monopolizing the -netd process.

daemon: dedupe PublicInbox::Config objects by pathname

This means all Inbox, Git, Over, Msgmap, Search objects also get
deduplicated if they belong to the same config file, reducing
memory and FD usage.  This helps save memory and improve cache
hit rates in -netd setups where NNTP, IMAP, HTTP, and POP3
servers run in the same process.

InboxIdle was the only bit which needed adjustment, but there
may be other bugs lurking despite all tests passing.

www: gzip_filter: avoid errors after ->write failure

->zflush must return a string to its caller, not undef.
Additionally, {http_out} may be deleted on ->write if ->close
recurses.

This should fix the following errors:
  Use of uninitialized value $_[1] in string eq at PublicInbox/HTTP.pm line 211.
  E: Can't call method "close" on an undefined value at GzipFilter.pm line 167.

Fixes: a6d50dc1098c01a1 (www: gzip_filter: gracefully handle socket ->write failures, 2022-08-03)

view: avoid intermediate array when streaming thread

We can rely on auto-vivification to avoid an intermediate
array for the map result.

feed: avoid unnecessary map loop in non-over path

We can bless objects while doing the initial insertion to avoid
extra the extra map iteration and temporary array(s).  Fewer ops
means memory savings for the likely case of ->over users, too.

imap: ensure_slices_exist: drop needless map and array

We can reduce ops and temporary objects here by folding the
stringification into the `for' loop and push directly into the
{mailboxlist} array; relying on autovivification to turn it into
a noop for the initial population.

lei_overview: remove pointless map {} op

We can rely on //g and autovivification, here.

isearch: mset_to_artnums: avoid unnecessary ops

We can use DBI's selectcol_arrayref directly (as we do in other
places) to avoid unnecessary arrays and ops on our end.

over: get_xref3: modify rows in-place

There's no need to create two intermediate arrays when we can
modify the existing arrayref.

http: coerce SERVER_PORT to integer

This may save a few bytes with many connected clients.
Noticed while working on the JMAP endpoint.

TODO: remove done items, adjust/add/abandon some

public-inbox-pop3d (and -netd) gives us POP3 support, and
it seems to work.  Proxy support can come independently,
probably after JMAP.

public-inbox-netd provides the multi-protocol "super server"
which allows code memory savings.  Work is ongoing to further
reduce memory use...

Automatically updating on TLS cert and key changes on
inotify/EVFILT_VNODE won't be done, since (IMHO) there's too
much risk of inadvertent updates on incomplete changes.
My same train-of-thought applies to auto-reloading on config
file changes: an admin may save a file halfway through a
multi-step change and auto-reloading can be too surprising and
break things.

I don't think lei+FUSE will be as portable or useful as a
local IMAP server (and maybe JMAP, eventually); but r/w IMAP
support would be nice..

Finally, git SHA-256 repo support will need to be taken into
account.

daemon: handle per-listener options on inherited, well-known ports

We must not clobber already-parsed per-listener options when
handling inherited sockets which are well-known.  Unfortunately,
this isn't easy to test in a non-intrusive way for regular
users.

imapd: use nntpd_cache to speed up startup/reload time

ConfigIter was still too slow despite being fair.  The addition of
ART_MIN in ALL->misc means it can be used as a startup/reload cache
for -imapd, too.

This results in a ~3x faster startup for -imapd with 50K inboxes.

nntp: speed up group listings via ->ALL->misc

By taking advantage of the new ART_MIN/ART_MAX value in MiscIdx,
we can avoid the overhead of opening per-inbox msgmap DB files.
The result gives us a ~40 speedup with 50K newgroups.

miscidx: index inbox min/max article numbers

This will be used to speed up NNTP group listings and IMAP startup
with thousands of inboxes.

nntpd: do not delete newsgroup name from inbox object

While PublicInbox::NNTP doesn't use it, config sharing inside
public-inbox-netd will mean inbox objects also get shared.

daemon: reload TLS certs and keys on SIGHUP

This allows new TLS certificates to be loaded for new clients
without having to timeout nor drop existing clients with
established connections made with the old certs.  This should
benefit users with admins who expire certificates frequently (as
encouraged by Let's Encrypt).

www: simplify GzipFilter->zflush callers

->zflush can take a buffer arg, so there's no need to
make a separate call to ->translate in some cases.

ds: use ->dflush to distinguish from ->zflush

->zflush is already for GzipFilter in PublicInbox::WWW,
while we use DEFLATE for NNTP and IMAP.  This ought to
make the code easier-to-follow.

www: gzip_filter: update a few comments

A few things I noticed while reviewing and evaluating
the PSGI code for JMAP support.

www: gzip_filter: gracefully handle socket ->write failures

Socket ->write failures are expected and common for TCP traffic,
especially if it's facing unreliable remote connections.  So
just bail out silently if our {gz} field was already clobbered
during the small bit of recursion we hit on ->write failures
from async responses.

This ought to fix some GzipFilter::zflush errors (via $forward
->close from PublicInbox::HTTP) I've been noticing on
deployments running -netd.  I'm still unsure as to why I hadn't
seen them before, but it might've only been ignorance on my
part...

Link: https://public-inbox.org/meta/20220802065436.GA13935@dcvr/

daemon: share FDs for identical log paths

We rely on the %logs hash for SIGUSR1 log reopening.  Without this sharing,
some FDs would be hidden inside its respective {HTTP,IMAP,POP3}D
object and not reopened on USR2

daemon: allow listening on well-known ports based on protocol

This allows admins to use "-l nntp://0.0.0.0/" to bind on port 119
without specifying ":119" on the CLI.

daemon: add diagnostics about inherited/bound listeners

These are helpful for diagnosing configuration problems,
as well as a bug (to be fixed in the following commit).

daemon: require absolute cert/key paths with --daemonize

This is preparation for supporting loading new certs on SIGHUP.

daemon: support per-listener env, .psgi, out, err

This allows memory savings by allowing multiple, completely
unrelated-PSGI apps to run within the same process as IMAP,
NNTP, and POP3.

httpd: make internals slightly more generic

This brings the HTTP server closer to the IMAP/NNTP/POP3
implementations and eliminates package-wide globals in
PublicInbox::HTTPD.  The end goal is to be able to host
completely different PSGI applications on different listen
ports.

solver: avoid deprecation warnings in git 2.36.0+

git deprecated core.fsyncObjectFiles in favor of core.fsync
with 2.36.0+, while GIT_TEST_FSYNC was added in 2.35.0.  So
use the environment variable since it's been supported slightly
longer than the new configuration knob.

tests: maintainer test for using mpop

This ought to be a good stress test to ensure our POP3
implementation works against the POP3 client I've found.

doc|www: flesh out POP3 documentation for servers and users

Hopefully it makes sense to new users deploying or using POP3...

doc: httpd: document GIT_HTTP_MAX_REQUEST_BUFFER

We've always shared this environment with git-http-backend(1)
(but don't (yet) support http.maxRequestBuffer anywhere)

www: drop --subject from "git send-email" instructions

Apparently, --subject doesn't work[1] with "git send-email" in
this context.  So drop the CLI arg and add a note to tell the
user to set a "Subject:" line in their response body, instead.

[1] I'm not sure if --subject ever worked as I thought it would,
    or if it's a regression.  In either case, there are current
    versions of git where it doesn't, so just tell users to use
    the currently supported method.

Link: https://80x24.org/lore/git/CAC4O8c-Tf11CpwuRudyrpXv5bGshuyEenV9kKrs0zRWER-+yHA@mail.gmail.com/

add xt/mem-nntpd-tls maintainer test

This ensures memory usage is reasonable when DEFLATE and TLS are
enabled.  It's also our only coverage for NNTP COMPRESS since
Net::NNTP has yet to implement compression support:

https://rt.cpan.org/Public/Bug/Display.html?id=129967

dsdeflate: shorten scope of initial buffer

There's no need to keep the initial buffer alive in package-wide
scope once it's replaced by `$next' in ->write or ->zflush.

xt/mem-imapd-tls: update aliases to DSdeflate subs

Fixes: 23af251dd607c4e7 (imap+nntp: share COMPRESS implementation, 2022-07-23)

nntp: use substr to check for trailing CRLF

Regexps consume more CPU cycles and memory, and aren't
necessary here since we just converted the entire buffer
to CRLF.

pop3: reduce memory use while generating the mailbox cache

While the cache itself is relatively compact for 50K messages,
generating it was inefficient due to our schema and Over.pm APIs
being designed for NNTP.  While we won't change our schema for
now, we can choose better DBI APIs to use and limit our ephemeral
memory use.

This amounts to a 60% reduction in memory usage and a 5-10%
speedup against org.kernel.vger.git.0:

{
echo 'USER '$(uuidgen)'@org.kernel.vger.git.0'
echo PASS anonymous
echo STAT
echo QUIT
} | nc $HOST $PORT

imap+nntp: share COMPRESS implementation

Their code was nearly identical to begin with, so save some
memory in -netd and disk space for all of our tarball/distro
users, at least.

And I seem to have used multiple inheritance successfully, here,
maybe...

nntp: resolve inboxes immediately on group listings

This prevents potential races between SIGHUP config reloads
while gigantic group listings are streaming, allowing us to
avoid many invalidation checks.

This also reduces send(2) syscalls and avoid Perl internal pad
allocations in a few places where it's not beneficial.  There
might be a slight (0.5%) speedup, but I'm not sure if that's
down to system noise, power/thermal management, or other users
on my VM.

ds: share long_step between NNTP and IMAP

It's not actually used by our POP3 code at the moment,
but it may be soon to reduce memory usage when loading
50K smsg objects into memory.

nntp: inline CRLF in all response lines

This brings NNTP closer to POP3 and IMAP implementations
to allow CoW avoidance on constants.

nntp: listgroup_range_i: remove useless `map' op

No need to iterate through the array twice; and this even seems
a hair faster than what I got with commit 726d6e71aee5d974
(nntp: small speed up for multi-line responses, 2020-12-04)

ds: move requeue_once

It's the same subroutine everywhere.

ds: move no-op ->zflush to common base class

More deduplication, and POP3 never needed it.

ds: support greeting protocols

We can share some common code between IMAP, NNTP, and POP3
without too much trouble, so cut down our LoC.

nntp: remove more() wrapper

Using PublicInbox::DS->msg_more directly can avoid unnecessary
CoW memory traffic since there's no appending "\r\n".

nntp: start adding CRLF to responses natively

With IMAP and POP3, I've started to embed CRLF into constant
response codes to avoid triggering CoW and extra memory traffic
in Perl.

The end goal is to enable more code sharing between IMAP, NNTP,
and POP3 inside one -netd process.

nntp: pass regexp to split() callers

Current implementations of Perl5 don't have optimizations for
single-character field separators.

pop3: drop File::FcntlLock requirement for FreeBSD and Linux

I know Linux has a stable ABI for this, and FreeBSD seems to,
too (*BSDs don't have stable syscall numbers, though).
I suspect this is safe enough for all *BSDs.

This is stricter than the MboxLock one since we use exact byte
ranges with these locks.

www: note "x=m" and "t=1" (mis)use for GET requests

We require "x=m" (requests for mboxes) to be POST requests to
avoid unnecessary traffic from crawlers.  "t=1" only collapses
threads in the summary view, which isn't normally accessible
from <form> elements.

This also fixes the missing "[summary|nested]" element when
"x=m" is used.

gcf2: avoid excessive checks for unlinked files

We were misusing the timer and not expiring it before checking
for unlinked files.  Now, we check for unlinked files every 60s,
instead.

pop3: advertise STLS in CAPA if appropriate

This is documented in RFC 2595, and POP3 clients may rely on
seeing "STLS" in CAPA output to initiate TLS negotiation.

netd: setup TLS bits for well-known STARTTLS ports

Unfortunately, I can't think of an easy way to test this in
our test suite since binding these ports are privileged and
are often in use, anyways.

pop3: TOP requests do not expire messages

RFC 2449 only documents "EXPIRE 0" behavior for RETR requests
which fetch the whole message.  TOP requests only fetch
the headers and top $N lines of the body, so it's probably
harmful for deletions to be triggered in those cases.

pop3: implement IN-USE from RESP-CODES (RFC 2449)

This may help clients communicate to users if they're
making parallel connections or if we have server bugs.

public-inbox-pop3d - a mostly read-only POP3 server

Old account expiry has not been implemented, but it seems to
work well with both mpop(1) and getmail(1).  The strictness of
mpop was particularly helpful in ironing out bugs in our
implementation of (dreaded) message sequence numbers.

"EXPIRE 0" (RFC 2449) can theoretically save numerous "DELE"
commands, but that's untested by real-world clients.  mpop
supports PIPELINING which is effective in hiding latency,
and the core networking functionality is already well-tested
from our NNTP and IMAP implementations.

Configuration requires "publicinbox.pop3state" to point to
a directory writable by the otherwise read-only daemon.
See public-inbox-pop3d(1) manpage for more usage details.

netd: load modules for well-known ports

When inheriting well-known ports from systemd (or similar),
we can auto-load the proper *D.pm file based on the port number
without requiring command-line args.

load_mod also gets fixed to use its argument, instead of implicit
$1 since that won't work for our well-known.

lei note-event: inline note_event_arm_done

This was a single-caller sub since 47d4e53734820b4e
(lei_mail_sync: rely on flock(2), avoid IPC, 2021-09-18)
and unlikely to be used further, so inline it and save
a few KB of memory.

lei: avoid deadlock on inotify/EVFILT_VNODE wakeups

Enqueuing "note-event" requests from the DS event loop must
not wait on workers being able to drain the queue quickly
enough.  Thus we make the SOCK_SEQPACKET writes nonblocking
and rely on the lei-daemon event loop to enqueue writes.

This is a unique problem for "note-event" since it reuses
workers in between commands, while most lei commands currently
fork off new workers.

searchidx: skip "delta $N" sections for base-85

I don't deal with binary patches ever, so I failed to notice
binary deltas are supported in addition to the more common
literals.

A quick check of apply.c in git.git confirms "delta" and
"literal" are the only binary patch classes we can expect.

test_common: avoid uninitialized warning on readlink

Of course, waiting for inotify to become active can't rely on
inotify, so we need to do a busy loop here, instead...

imap: STATUS: count messages properly

This only affects the rarely-used STATUS command, our message
count was consistely zero due to misusing ->imap_exists.

Noticed while implementing POP3 server.

lei: track seen messages to note duplicates

This may help track down deduplication or other bugs in lei
which lead to occasionally missing messages.

Link: https://public-inbox.org/meta/CAL_JsqJH8xx_2NyZffNsRXbGXiv3kjmCETvKXt3Yfb0uToLm9Q@mail.gmail.com/

lei_xsearch: simplify lei/store import check

There's no need to check for two fields when one will suffice.

tree-wide: Fix typo accomodate

This was pointed out by the Debian package linter "lintian".

tree-wide: Fix typo likelyhood

This was pointed out by the Debian package linter "lintian".

searchthread: delete children early while ordering

This allows us to free up some memory sooner rather than later
in case ordersub is expensive.

searchthread: remove + inline single-use cast sub

No point in wasting several kilobytes of memory for a single-use
one-line sub.

doc: lei-q: regenerate for patchid: help

search: add help for patchid: prefix

Noticed-by: Kyle Meyer <kyle@kyleam.com>

search: do not index base-85 binary patches

Base-85 binary patches generated by git lead to many false
positives, so skip over gibberish words which may occur in them.
To avoid regressions in search results, continue to allow
searching for exact size matches (via "literal $SIZE") and the
phrase "GIT binary patch" for the mere presence of a binary
patch.

search: support "patchid:" prefix (git patch-id --stable)

This allows easy searching via patch-id from a git commit.

Currently, abbreviations are not supported, and it seems
needless to support them since AFAIK (git) doesn't generate
nor resolve abbreviated patch-ids anywhere.

searchidx: use regexp as first arg for `split' op

Current implementations of Perl5 don't have optimizations for
single-character field separators (unlike another non-Perl5 VM
I'm familiar with).

t/spawn: Find invalid PID to try to join its process group

In the container used to build packages of the GNU Guix distribution, PID 1
runs as the same user as the test so this spawn that should fail actually
succeeds.

Fix the problem by going through different PIDs and picking one that
either doesn't exist or we aren't allowed to signal.

Add EditorConfig file

This allows several editors to automatically use the correct settings when
editing public-inbox files.

[ew: add to MANIFEST, too]

view: do not escape first `@' in mailto: URLs

It's probably not a perfect match for RFC 6068 atm, but perfect
is the enemy of good.

Reported-by: Moritz Poldrack <moritz@poldrack.dev>
Link: https://public-inbox.org/meta/CKJSWGSZFKMX.3VUSIYE955Z9X@Archetype/

imapd: update comment for PublicInbox::ConfigIter

config enumeration was split out to a separate class a long time ago.

imap: remove unused args_ok sub

Noticed while reviewing pieces for POP3.

daemon: fix uninitialized variable

And also replace an unnecessary substitution (s///) op with a
match (m//).

Fixes: 93a7b219d58aad86 ("public-inbox-netd: a multi-protocol superserver")

doc: add missing "be" for --key description

Link: https://public-inbox.org/meta/87levfv7hs.fsf@kyleam.com/
Noticed-by: Kyle Meyer <kyle@kyleam.com>