www_stream: note existence of IMAP and NNTP URLs

The "mirror" link may not clue users into the existence of
NNTP and IMAP servers, so add a note about them (but don't
list them, in case there are dozens of URLs :>).

www: support publicinbox.imapserver

This allows PublicInbox::WWW hosts to advertise the existence of
IMAP servers in addition to NNTP servers.

inbox: streamline ->nntp_url

We no longer waste a precious hash slot for a per-Inbox
{nntpserver} if it's only configured globally for all inboxes.

support -C (chdir) for most non-daemon commands

Because make(1), git(1), tar(1) all support -C in this form, as
do our newer commands such as lei, public-inbox-{clone,fetch}.

fetch|clone|--mirror: shorten paths for progress output

The full pathname for "curl -o ..." was too noisy and confusing.
Reduce confusion by adding the ".tmp" suffix and relying on
"-C".  We'll also avoid displaying "-C" in run_reap() and
rely on "--git-dir=" with "git fetch" to display progress for
users.

clone|fetch|--mirror: add convenience $INBOX_DIR/Makefile

Since the beginning of time, I've been dropping Makefiles
in $INBOX_DIR (and above hiearchies) to organize groups
of commands.

make(1) is widely available in various flavors and a familiar
tool for our target audience.  It is easy to run in the right
directory, typically has built-in shell completion, and doesn't
silently ignore errors by default like Bourne shell.

TODO: update some items

Some things (extindex) done, many more to do; and -fetch should
set us up for v1 => v2 migrations at some point...

fetch: support --exit-code switch

As noted in the new manpage entry, this is useful for avoiding
public-inbox-index invocations when there's nothing to update.
We use 127 to match "grok-pull", and also because it doesn't
conflict with any of the current curl(1) exit codes.

lei_saved_search: fix prefix for IMAP folders w/ slash

We failed to account for IMAP mailboxes containing `/'
characters when creating saved search files for them.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/meta/20210915123347.knr4qpaei73tjc5q@meerkat.local/

multi_git: hoist out common epoch/alternates handling

IMHO, this greatly improves code sharing and organization
between v2, extindex, and lei/store.  Common git-related
logic for these is lightly-refactored and easier to reason
about.

The impetus for this big change was to ensure inboxes
created+managed by public-inbox-{clone,fetch} could have
alternates and configs setup properly without depending on
SQLite (via V2Writable).  This change does that while
making old code shorter and better factored.

uri_imap: fix ->uidvalidity and ->uid w/ `/' separator

Again, we were failing to account for '/' use in mailbox names :x

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/meta/20210914210547.akdp4cqmwaheayp5@meerkat.local/

doc: update authentication notes for lei

~/.netrc isn't used by default any more, and I'm not sure it's
worthwhile to document the --netrc switch since it's rare for
non-FTP clients to support.

Followup-to: 9d11ed460ce113dd ("lei: do not read ~/.netrc by default")
Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

uri_imap: handle '/' as an IMAP hierarchy separator

Untested at the moment(*), but we were inadvertantly truncating
mailbox names with '/' due to our work-in-progress handling of
"/;UID=$NUM" parameter.

(*) strangely, my dovecot instance doesn't allow '/' by default,
    so the change to xt/net_writer-imap.t is untested.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/meta/20210914175025.eq7s2shkc323itaf@meerkat.local/

spawn+gcf2: improve diagnostics for build failures

I'm not sure why, but I noticed the one of my latest restarts of
public-inbox-httpd wasn't loading the Inline::C .so for Gcf2 nor
Spawn.  I also can't reproduce the problem as both .so files are
loaded fine on a restart with zero config changes.

In any case, some extra, automatic diagnostics for build errors
won't hurt, as no extra noise is introduced for successful builds.
This will also make future development of C code more convenient,
hopefully.

lei up: fix env/cwd mismatches with multiple folders

By moving %ENV localization and fchdir into ->dispatch,
we can maintain a consistent environment across multiple
dispatches while having different clients.

test_common: remove non-hidden files, first

We want to remove any inotify-watched files before removing
~/.local/lei/store/ipc.lock, since sto_done_request was failing
on attempts to lock a non-existent lei/store/ipc.lock file.

t/run: TEST_LEI_DAEMON_PERSIST: die if pid changes

While persisting lei-daemon across different test cases isn't
the default anymore, we can notice problems more quickly if
the daemon PID changes since the daemon gets auto-restarted
after failures.

lei: sto_done_request: add eval guard

Failures here can cause the lei-daemon event loop to break
since PktOp doesn't guard dispatch.  Add a guard here (and
not deeper in the stack) so we can use the $lei object to
report errors.

lei: warn on event loop errors

This should help us notice (and fix) bugs more easily.

lei up: fix --mua with single output

Oops :x

Fixes: b584a53f053a7629 ("lei up: support --all for IMAP folders")

lei_xsearch: sensible errors for missing/broken externals

I've been creating and destroying lots of externals, lately...

lei up: localize %ENV in redispatch

We need to restore %ENV of script/lei in case another
lei client has a different %ENV than what daemon has.

use POSIX::PIPE_BUF (instead of _POSIX_PIPE_BUF)

PIPE_BUF accounts for Linux being 4096 (and presumably other
OSes differing), while _POSIX_PIPE_BUF is the minimum 512
value.

lei: stop_pager: restore stdout when done

The reason(s) we had for not restoring stdout haven't been valid
since script/lei (and not lei-daemon) spawns the pager, nowadays.

tests: add require_cmd, require curl when needed

t/v2mirror.t and t/lei-mirror.t are now skipped when curl
is missing (instead of failing in appropriate places).
A bunch of which() checks are updated to use require_cmd
to avoid explicitly loading Spawn.

fetch: drop 304 Not Modified support, simplify comparisons

Timestamp comparisons only have 1 second granularity, which
isn't nearly enough for our test cases, and probably not for
real world use for "git send-email" bursts and fast SMTP
servers.

We'll continue to check modification times inside the manifest,
though, in case an extremely rare SHA-1 collision is found...

fetch: fix and test v2 epoch detection

It was also totally broken by the change to use manifest.js.gz
for v1 :x

Fixes: ffb7fbda6869db4b ("fetch: use manifest.js.gz for v1")

fetch: fix half-baked v1 manifest.js.gz handling

The v1 code path was totally half-baked after the change
to use manifest.js.gz :x

Fixes: ffb7fbda6869db4b ("fetch: use manifest.js.gz for v1")

test_common: only print $@ for Gcf2 failure

Other missing dependencies are more straightforward, but
Gcf2 requires a combination of libgit2-dev, pkg-config,
Inline::C, and proper setup.

This significantly reduces noise in tests with a minimal
set of dependencies installed.

lei sucks: allow it to work without SQLite

And try to improve the message about Inline::C while we're at
it, since Socket::Msghdr isn't widely-packaged, yet.

t/lei-*.t: guard setup_public_inboxes with test_lei

This ensures tests are skipped properly if SQLite or Xapian
are missing and don't bail out.

fetch: use manifest.js.gz for v1

This is gentler to the remote HTTP server in the no-op case and
will allow client migrations to some v2-ish format without
forcing the client to redownload everything.

init: set a useful description

"Unnamed repository" for v1 inboxes was misleading, and having a
non-existent description for v2 was equally annoying, so set a
short description based on the primary address.

We remove descriptions when setting up new test inboxes to
preserve the behavior of the t/lei-mirror.t test case.

import: do not write a "description" file

The default value is worthless to us and git functions fine
without the file.  public-inbox-init will create a useful one
in the next change.

clone|lei_mirror: write description in mirrors

Instead of generic "Unnamed repository" or "missing" messages,
show "mirror of $URL" since it seems like a better default when
creating a mirror.

new public-inbox-{clone,fetch} commands

Setting up and maintaining git-only mirrors of v2 inboxes is
complex since multiple commands are required to clone and fetch
into epochs.

Unlike grokmirror, these commands do not require any
configuration.  Instead, they rely on existing git config files
and work like "git clone --mirror" and "git fetch",
respectively.

Like grokmirror, they use manifest.js.gz, but only on a
per-inbox basis so users won't have to clone every inbox of a
large instance nor edit config files to include/exclude inboxes
they're interested in.

lei_mirror: fix error message

We're using rename(2) rather than link(2)

lei_mirror: simplify error reporting

Slowly transitioning to using die() more, which hopefully
improves code reusability between lei and non-lei parts of our
code.

www: use ->ALL for per-inbox manifest.js.gz, too

With 11 epochs on LKML, the lkml/manifest.js.gz response time
goes from around 60ms to around 10ms, a significant improvement.
And improve test coverage while we're at it.

manifest.js.gz: avoid long-lived per-epoch cat-file processes

When generating per-inbox manifests, we were forgetting to
cleanup per-epoch "git cat-file --batch" processes.  Our
previous method of generating modified times was also stupidly
inefficient, so replace the pipeline with a single
"git for-each-ref" invocation.

lei q|lcat: support "-f reply" output format

When composing replies in "git format-patch" cover letters,
I'd been relying on "lei q -f text ...", but that still requires
several steps to make it suitable for composing a reply:

* s/^/> / to quote the body
* drop existing In-Reply-To+References
* s/^Message-ID:/In-Reply-To:/;
* add an attribute line
...

"lei q -f reply" takes care of most of that and users will
only have to trim "From " lines, unnecessary results and
over-quoted text (and trimming is likely less error-prone
than doing all the steps above manually).

This should also be a good replacement for
"git format-patch --in-reply-to=...", since copying long
Message-IDs can be error-prone (and this lets you include
quoted text in replies).

lei: normalize whitespace in remote queries

Having redundant "+" in URLs is ugly and can hurt cacheability
of queries.  Even with "quoted phrase searches", Xapian seems
unaffected by redundant spaces, so just normalize the ASCII
white spaces to ' ' (%20) when fed via STDIN or saved-search
config file.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/meta/20210910141157.6u5adehpx7wftkor@meerkat.local/

lei: pass client stderr to git-config in more places

This should improve the users' chances of seeing errors in
various git config files we use.

lei: fix handling of broken lei.saved-search config files

lei shouldn't become unusable if a config file is invalid.
Instead, show the "git config" stderr and attempt to continue
gracefully.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/meta/20210910141157.6u5adehpx7wftkor@meerkat.local/

INSTALL: depend on URI rather than URI::Escape

As far as I can tell, URI::Escape has always been a part of the
`URI' package (aka "distribution" on CPAN) and not distributed
separately (unlike URI::Escape::XS).  So avoid confusing users
with `URI::Escape' and just document `URI' instead.

Along the same lines, we depend on the `Plack' package rather
than Plack::Util or Plack::Builder, after all.

lei up: only delay non-zero "# $NR written to ..."

"# 0 written to $FOLDER" messages aren't important to the
user, so we can show them in real time and allow them to
be lost in the terminal scroll.  When >0 messages are
written to a folder, we'll show them last so a user
will know which folders to open with their MUA.

doc: lei-index manpage

It's a pretty incomplete command, so it's important to document
its incompleteness.

lei: do not read ~/.netrc by default

Since ~/.netrc isn't widely used by most (if any) NNTP and IMAP
clients, we won't read it by default for lei.  AFAIK, ~/.netrc
is mainly by FTP clients (e.g. ftp(1) and lftp(1)).  wget uses
it by default for HTTP(S) (and FTP), but curl does not.

To avoid breaking stable release use cases, public-inbox-watch
continues to read ~/.netrc by default.

The --netrc switch is supported by all existing lei commands
which may use curl.

lei: split out @net_opt for curl/torsocks use

IMAP and NNTP connections share some curl(1) options for TLS,
IPv4/IPv6, or netrc, etc...

lei_query: fix comment about %lei2curl commands

Just a typo.

lei add-external --mirror: quiet unlink error on ENOENT

If the mirror.done file doesn't exist for unlink, it's because
we already got another error, so don't confuse users by noting
an unlink error since the ENOENT is expected in the face of
other errors.

lei add-external --mirror: deduce paths for PSGI mount prefixes

The current manifest.js.gz generation in WWW doesn't account for
PSGI mount prefixes (and grokmirror 1.x appears to work fine).

In other words, <https://yhbt.net/lore/lkml/manifest.js.gz>
currently has keys like "/lkml/git/0.git" and not
"/lore/lkml/git/0.git" where "/lore" is the PSGI mount prefix.
This works fine with the prefix accounted for in my grokmirror
(1.x) repos.conf like this:

site = https://yhbt.net/lore/
manifest = https://yhbt.net/lore/manifest.js.gz

Adding the PSGI mount prefix in manifest.js.gz is probably not
desirable since it would force the prefix into the locally
cloned path by grokmirror, and all the cloned directories
would have the remote PSGI mount prefix prepended to the
toplevel.

So, "lei add-external --mirror" needs to account for PSGI
mount prefixes by deducing the prefix based on available keys
in the manifest.js.gz hash table.

gcf2: die if pkg-config is missing

We can't link properly to libgit2 without pkg-config telling
us which libraries and headers to use.

t/git.t: quiet intentional git-rev-parse failure

It can get confusing, especially when running non-parallel "make test"

Link: https://public-inbox.org/meta/20210909210138.ssiv5tri65mf4l4o@meerkat.local/

test_common: print diagnostic for missing dependencies

The "#" prefix should prevent it from being too alarming if
a dependency is expected to be missing, but still useful if a
dependency is misconfigured.

lei up: print messages before disconnecting

Closing the socket for script/lei needs to be done AFTER the
final message(s) are printed.

net_reader: support Mail::IMAPClient Ignoresizeerrors

Some proprietary servers may do wacky things and give the
wrong size, so Mail::IMAPClient has a knob for this which
we can expose to users to workaround this.

net_reader: improve naming of common args

IMHO this makes things easier-to-follow than before.

net_reader: combine Net::NNTP and IMAPClient args

Since these are keyed by IMAP and NNTP URIs which can never
conflict, it simplifies our internals to keep them in one big
hash since we'll add POP3 and JMAP client support.

net_reader: imap_opt => cfg_opt

Since this our internal IMAP options are keyed by URI section,
there's no need to have separate hashes for NNTP and IMAP
options since they URI already distinguishes them.

This will make future changes to support POP3 and JMAP and
arg caching with lei/store easier.

net_reader: nntp_opt => cfg_opt

Since this our internal NNTP options are keyed by URI section,
there's no need to have separate hashes for NNTP and IMAP
options since they URI already distinguishes them.

This will make future changes to support POP3 and JMAP and
arg caching with lei/store easier.

net_reader: preserve memoized IMAPClient arg for SOCKS

Multiple invocations of mic_new may happen in long-lived
processes, so do not let mic_new make irreversible changes
to the cached args when using a SOCKS proxy.

net_reader: set IMAPClient Keepalive flag late

Since we always enable SO_KEEPALIVE unconditionally, having it
in {mic_arg} leads to unnecessary IPC overhead and memory use.

net_reader: do not set "SSL" fields for non-TLS

This will save a little bit of memory and IPC I/O for users
connecting to localhost and the majority of Tor .onions.

lei prune-mail-sync: ignore missing locations

"lei prune-mail-sync --all" shouldn't abort if a location
isn't available, and maybe it should prune harder...

lei_input: provide hint for bare "L:" and "kw:"

I just made this mistake running "lei import" myself, so
I figure giving a hint makes sense, here.

lei-rm: add man page, support LeiInput args

-F/--in-format and --lock=TYPE(S) are easily supported by
all classes using LeiInput.

news_www: favor ->ALL URL when using ->ALL

This allows us to link to threads spread across multiple inboxes.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/meta/20210907140954.4rlh6pn5fz4ljkxp@meerkat.local/

doc: acknowledge the MMDF mailbox format

While I don't currently see a point in supporting MMDF, we'll
still acknowledge it since mutt actually supports it.  Expand a
bit on MH while we're at it, since MH seems at least relevant.

lei q|up: fix write counter for v2

It's a bit confusing to see "0 written to ..." when we actually
wrote something.

news_www: avoid uninitialized variables

PATH_INFO may not have enough slashes for newsgroup name in the
URL at all, so ensure we don't try to further process requests
which have no chance of having a newsgroup name.

doc: lei-*.pod: update to Tor v3 .onion address

We missed a few when new documentation came in, and there's no
going back to v2 onions.

Followup-to: 0b15dfc58ceaecdc ("treewide: update to v3 Tor onions")

lei up: support --all for IMAP folders

Since "lei up" is expected to be a heavily-used command,
better support for IMAP seems like a reasonable idea.

This is inefficient since we waste an IMAP(S) TCP connection
since it dies when an auth-only LeiUp worker process dies, but
it's better than not working at all, right now.

lei: dump and clear log at exit

This may be helpful for diagnosing errors in case we missed any.

xt/net_writer_imap: test "lei up" on single IMAP output

That's the minimum, at least...

lei_auth: simplify users

There's no need to alias net_merge_all in each WQ class
which uses LeiAuth, `$obj->$sub' works even when `$sub'
is a fully-qualified subroutine name with `::' in it.
perlobj(1) documents it under "Method Call Variations".

lei_auth: remove net_merge_done1 step

It turns out this step is unnecessary, since SOCK_SEQPACKET
ordering is guaranteed and we know wq_broadcast calls will
always be handled sequentially.

lei_auth: diagram for current behavior

Before making potentially major changes, lets clarify readers'
understanding of how LeiAuth currently works.

lei_search: xsmsg_vmd: retry_reopen properly

The deeper eval was preventing retry_reopen from retrying
with readers and writers working in parallel:

  FOO=imaps://example.com/INBOX.huge
  lei lcat $FOO -f mboxcl | lei tag -F mboxcl +L:bar -

Fixes: c7bcfe6cd6648ff0 ("lei: diagnostics for /Document \d+ not found/ errors")

net_reader: don't approve/reject credentials w/o "fill"

Credentials sourced via ~/.netrc should not be written to
git-credential.

lei_to_mail+mbox_reader: fix handling of empty/bogus emails

We may be handling invalid mboxes, so just return no objects in
that case.  While "lei q" on HTTP(S) externals expects a gzipped
mboxrd, there's always a chance something else gzipped can be
sent to us.

There's also changes to lei_to_mail to better handle emails
which lack a body and/or headers (e.g. t/solve/bare.patch)

Link: https://public-inbox.org/meta/20210903151500.h72mzcpqixgtytjs@meerkat.local/

lei: fix read/write IMAP access

xt/net_writer-imap.t was completely broken in recent months and
I completely forgot this test.  net->add_url still only accepts
bare scalars (and not scalar refs), so we must set that up
properly.  Furthermore, our changes to do FLAGS-only
synchronization in lei of old messages was causing us to not
handle FLAGS properly for the test.

lei_xsearch: avoid false-positives on externals w/ L: and kw:

We need to use LeiSearch->qparse_new to handle (and filter out)
"L:" and "kw:" search prefixes to avoid hitting false positives
when externals are involved.  Unfortunately, this doesn't work
for remote HTTP(S) externals, but those aren't enabled by
default.

lei inspect: support reading eml from --stdin

This can be useful inside mutt since I was diagnosing why
a label ("L:$FOO") search was giving me a false-positive
search result...

lei up --all: avoid double-close on shared STDOUT

This is merely to avoid perl setting errors internally which
were not user visible.  The double-close wasn't a problem in
practice since we open a new file hanlde for the mbox or
mbox.gz anyways, so the new t/lei-up.t test case shows no
regressions nor fixes.

lei: use lei->lms in place of lse->lms in a few places

We can golf out some code and refcounts this way.

lei: ->child_error less error-prone

I was calling "child_error(1, ...)" in a few places where I meant
to be calling "child_error(1 << 8, ...)" and inadvertantly
triggering SIGHUP in script/lei.  Since giving a zero exit code
to child_error makes no sense, just allow falsy values to
default to 1 << 8.

lei/store: quiet down link(2) warnings

ENOENT can be too common due to timing and concurrent access
from MUAs and "lei export-kw", and other mail synchronization
tools (e.g. mbsync and offlineimap).

lei: dump errors to syslog, and not to CLI

Dumping errors from the previous run can often get lost, so just
spew to syslog since it's a standard place to put errors that
don't make it to a client.  Note: we don't rely on $SIG{__WARN__}
since some of the Net:: stuff will write directly to STDERR
(as will external processes).

www: handle name-only publicinbox.*.url entries

Apparently URLs can be configured relatively for HTTP(S) setups,
attempt to support them when linking to cross-posted messages.

This also fixes the top-row (mirror/help/color/Atom feed) links
in /$INBOX_URL/$EXTMSG_MSGID/T/ (and /t/) URLs.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/meta/20210902191239.cmbxlmjqcsmdzmqp@meerkat.local/

tests: "make check-run" favors reliability over speed

Sharing a single lei-daemon across multiple processes still
exhibits reliability problems, and reliably checking
lei-daemon's inotify internals seems impossible without.

Even without lei-daemon sharing, "make check-run" is a few
seconds faster than "make check" for me.

t/lei-auto-watch: improve test reliability

On slower systems, even a 100ms delay may not be enough;
so loop and retry in hopes of an early exit for faster
systems.

lei: propagate keyword changes from lei/store

This works with existing inotify/EVFILT_VNODE functionality to
propagate changes made from one Maildir to another Maildir.

I chose the lei/store worker process to handle this since
propagating changes back into lei-daemon on a massive scale
could lead to dead-locking while both processes are attempting
to write to each other.  Eliminating IPC overhead is a nice
side effect, but could hurt performance if Maildirs are slow.

The code for "lei export-kw" is significantly revamped to match
the new code used in the "lei/store" daemon.  It should be more
correct w.r.t. corner-cases and stale entries, but perhaps
better tests need to be written.

squashed:
  t/lei-auto-watch: increase delay for FreeBSD kevent

  My FreeBSD VM seems to need longer for this test than inotify
  under Linux, likely because the kevent support code needs to be
  more complicated.

lei_input: set and prepare watches early

This will be needed as we track changes in real-time, especially
for "lei index" since there's no storage involved.

lei_mail_sync: do not use transactions

For lei-index to work in parallel with MUA access and upcoming
inotify-based updates, mail_sync.sqlite3 needs to always be
up-to-date to read-only worker processes (ahead of everything
else).  So rely on the default auto-commit behavior and hope
SQLite WAL can reduce some of the overheads involved with
writes.

extindex: --gc removes messages from over, too

While messages from removed inboxes were removed from Xapian
search, --gc failed to remove messages from over.sqlite3
entirely.  They no longer show up in the topic summary view.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/20210830201723.dehoul4y6gpqf2cp@nitro.local/

extindex: document --all and indexlevel=basic interaction

Cache is expensive, so help users save on storage by documenting
this behavior.

lei up: only show finmsg in top-level lei-daemon

->DESTROY can get triggered in child processes, which
unnecessarily duplicates messages queued up for display
when lei spawns extra workers.

lei/store: correctly delete entries from over

Some of these errors were inadvertantly lost due to delayed
error reporting in the past.

lei: fix error reporting from lei/store -> lei-daemon

We must set autoflush to ensure timely notification of clients;
and lei-daemon must not block when waiting on reads in case of
spurious wakeups.

Finally, if no clients are connected to lei-daemon, write to
syslog to ensure the error is visible.