t/lei-up: use '-q' to silence non-redirected test

We could redirect, too, but just use -q since we don't care
for the output with run_mode => 0.

lei q: improve --limit behavior and progress

Avoid slurping gigantic (e.g. 100000) result sets into a single
response if a giant limit is specified, and instead use 10000
as a window for the mset with a given offset.  We'll also warn
and hint towards about the --limit= switch when the estimated
result set is larger than the default limit.

lei q: update messages to reflect --save default

I wanted to try --dedupe=none for something, but it failed
since I forgot --no-save :x  So hint users towards --no-save
if necessary.

search: drop reopen retry message

It's needless noise in syslogs for daemons and unnecessarily
alarming to users on the command-line.

lei q: show progress on >1s preparation phase

Overwriting existing destinations safe (but slow) by default,
so show a progress message noting what we're doing while
a user waits.

lei: various completion improvements

"lei export-kw" no longer completes for anonymous sources.

More commands use "lei refresh-mail-sync" as a basis for their
completion work, as well.

";AUTH=ANONYMOUS@" is stripped from completions since it was
preventing bash completion from working on AUTH=ANONYMOUS IMAP
URLs.  I'm not sure if there's a better way, but all of our code
works fine without specifying AUTH=ANONYMOUS as a command-line
arg.

Finally, we fallback to using more candidates if none can
be found, allowing multiple URLs to be completed.

lei lcat: support NNTP URLs

NNTP URLs are probably more prevalent in public message archives
than IMAP URLs.

doc: lei-security: section for WIP auth methods

Lots of stuff out there that becomes a pain to setup
configuration for and test...

lei lcat: use single queue for ordering

If lcat-ing multiple argument types (blobs vs folders),
maintain the original order of the arguments instead of
dumping all blobs before folder contents.

lei: simplify internal arg2folder usage

We can set opt->{quiet} for (internal) 'note-event' command
to quiet ->qerr, since we use ->qerr everywhere else.  And
we'll just die() instead of setting a ->{fail} message, since
eval + die are more inline with the rest of our Perl code.

lei_mail_sync: account for non-unique cases

NNTP servers, IMAP servers, and various MUAs may recycle
"unique" identifiers due to software bugs or careless BOFHs.
Warn about them, but always be prepared to account for them.

lei inspect: support NNTP URLs

No reason not to support them, since there's more
public-inbox-nntpd instances than -imapd instances,
currently.

lei inspect: convert to WQ worker

Xapian and SQLite access can be slow when a DB is large and/or
on high-latency storage.

gcf2: fix loading at runtime

We need to waitpid synchronously on pkg-config to use $?.

When loading Gcf2 inside the event loop, implicit dwaitpid
done by PublicInbox::ProcessPipe would not call waitpid in
time to zero $?.  This was causing one of my -httpd to
occasionally fall back to git(1) instead of using Gcf2.

This was noted in:
Link: https://public-inbox.org/meta/20210914085322.25517-1-e@80x24.org/

net_reader: NNTP: remove article numbers from mail_sync folders

NNTP article numbers are stored separately from folder names
in mail_sync.sqlite3.

Recovering from this is optional, worse case is wasting
bandwidth refetching some messages.  To (optionally) recover
from this, use:

lei forget-mail-sync $URL_WITH_ARTNUMS

Some articles will be refetched on the next import, but
duplicate data won't be indexed in Xapian.

doc: lei-config: document various knobs

It's still a work-in-progress, but the basic debug knob
comes in handy for new users; as does proxy support.

net_reader: disallow imap.fetchBatchSize=0

A batch size of zero is nonsensical and causes infinite loops.

lei config --edit: use controlling terminal

As with "lei edit-search", "lei config --edit" may
spawn an interactive editor which works best from
the terminal running script/lei.

So implement LeiConfig as a superclass of LeiEditSearch
so the two commands can share the same verification
hooks and retry logic.

net_reader: no STARTTLS for IMAP localhost or onions

At least not by default, to match existing NNTP behavior.
Tor .onions are already encrypted, and there's no point
in encrypting traffic on localhost outside of testing.

watch: use net_reader->mic_new wrapper for SOCKS+TLS

This brings -watch up to feature parity with lei with
SOCKS support.

xt: add fsck script over over.sqlite3

I'm not sure what caused it, but I've noticed two missing
messages that failed from "lei up" on an https:// external;
and I've also seen some duplicates in the past (which I
think I fixed...).

net_reader: fix single NNTP article fetch, test ranges

While NNTP ranges was already working, fetching a single message
was broken.  We'll also simplify the code a bit and ensure
incremental synchronization is ignored when ranges are
specified.

lei ls-mail-source: pretty JSON support

As with other commands, we enable pretty JSON by default if
stdout is a terminal or if --pretty is specified.  While the
->pretty JSON output has excessive vertical whitespace, too many
lines is preferable to having everything on one line.

lei ls-mail-source: use "high"/"low" for NNTP

The meanings of "hwm" and "lwm" may not be obvious abbreviations
for (high|low) water mark descriptions used by RFC 3977.
"high" and "low" should be obvious to anyone.

lei: clamp internal worker processes to 4

"All" my CPUs is only 4, but it's probably ridiculous for
somebody with a 16-core system to have 16 processes for
accessing SQLite DBs.

We do the same thing in Pmdir for parallel Maildir access
(and V2Writable).

ipc: drop dynamic WQ process counts

In retrospect, I don't think it's needed; and trying to wire up
a user interface for lei to manage process counts doesn't seem
worthwhile.  It could be resurrected for public-facing daemon
use in the future, but that's what version control systems are for.

This also lets us automatically avoid setting up broadcast
sockets

Followup-to: 7b7939d47b336fb7 ("lei: lock worker counts")

lei_xsearch: drop Data::Dumper use

We're not using Data::Dumper for JSON output.

lei: simplify sto_done_request

With the switch from pipes to sockets for lei-daemon =>
lei/store IPC, we can send the script/lei client socket to the
lei/store process and rely on reference counting in both Perl
and the kernel to persist the script/lei.

lei/store: use SOCK_SEQPACKET rather than pipe

This has several advantages:

* no need to use ipc.lock to protect a pipe for non-atomic writes

* ability to pass FDs.  In another commit, this will let us
  simplify lei->sto_done_request and pass newly-created
  sockets to lei/store directly.

disadvantages:

- an extra pipe is required for rare messages over several
  hundred KB, this is probably a non-issue, though

The performance delta is unknown, but I expect shards
(which remain pipes) to be the primary bottleneck IPC-wise
for lei/store.

ipc: allow disabling broadcast for wq_workers

Since some lei worker classes only use a single worker,
there's no sense in having broadcast for those cases.

ipc: wq_do: support synchronous waits and responses

This brings the wq_* SOCK_SEQPACKET API functionality
on par with the ipc_do (pipe-based) API.

doc: tuning: note git 2.33+, move libgit2 into Inline::C section

git 2.33+ contains important optimizations for the
thousands-of-inboxes case.  And combine the Inline::C stuff
with libgit2, since our use of libgit2 requires Inline::C.

t/lei-refresh-mail-sync: improve test reliability

We can't assume -imapd will be ready by the time we try to
connect to it after restart when using "-l $ADDR".  So recreate
the (closed-for-testing) listen socket in the parent and hand it
off to -imapd as we do normally

net_reader: quote URL properly for Tor .onion hint

The semicolon in ';AUTH=ANONYMOUS' requires quoting in Bourne shell.

t/config: extra test for imap_url with imaps://

I configured this for public-inbox.org, but wasn't 100% sure it
worked.  This test ensures it stays working :>

lei up: automatically use dt: for remote externals

Since we can't use maxuid for remote externals, automatically
maintaining the last time we got results and appending a dt:
range to the query will prevent HTTP(S) responses from getting
too big.

We could be using "rt:", but no stable release of public-inbox
supports it, yet, so we'll use dt:, instead.

By default, there's a two day fudge factor to account for MTA
downtime and delays; which is hopefully enough.  The fudge
factor may be changed per-invocation with the
--remote-fudge-factor=INTERVAL option

Since different externals can have different message transport
routes, "lastresult" entries are stored on a per-external basis.

net_reader: set SO_KEEPALIVE on all Net::NNTP sockets

SO_KEEPALIVE can prevent stuck processes and is safe to enable
unconditionally on all TCP sockets (like git, and the rest of
public-inbox does).  Verified via strace on both NNTP and NNTPS
with and without nntp.proxy=socks5h://...

net_reader: support imaps:// w/ socks5h:// proxy

While Non-TLS IMAP worked perfectly with IO::Socket::Socks
and Mail::IMAPClient; we need to wrap the IO::Socket::Socks
object with IO::Socket::SSL before handing it to
Mail::IMAPClient.

net_reader: detect IMAP failures earlier

An Mail::IMAPClient object may be returned even on connection
failure, so use IsConnected to check for it.  This ensures
git-credential will no longer prompt for passwords when there's
no connection.

net_reader: tie SocksDebug to {imap,nntp}.Debug

I think tying IO::Socket::Socks debugging to existing debug
switches is enough, and there's no need to introduce a separate
socks.Debug parameter.

ds: support add unique timers

A common pattern we use is to arm a timer once and prevent
it from being armed until it fires.  We'll be using it more
to do polling for saved searches and imports.

lei_mail_sync: set nodatacow on btrfs

As with other SQLite3 databases, copy-on-write with
files experiencing random writes leads to write amplification
and low performance.

lei_mail_sync: rely on flock(2), avoid IPC

Since 44917fdd24a8bec1 ("lei_mail_sync: do not use transactions"),
relying on lei/store to serialize access was a pointless endeavor.

Rely on flock(2) to serialize multiple writers since (in my
experience) it's the easiest way to deal with parallel writers
when using SQLite.  This allows us to simplify existing callers
while speeding up 'lei refresh-mail-sync --all=local' by 5% or
so.

lei: lock worker counts

It doesn't seem worthwhile to change worker counts dynamically
on a per-command-basis with lei, and I don't know how such an
interface would even work...

doc: lei-lcat: document --stdin behavior

This is another feature I've found immensely useful,
but I also wonder if I'm the only one who uses it.

git_http_backend: forward HTTP_GIT_PROTOCOL in request headers

It looks like git-http-backend(1) will support
HTTP_GIT_PROTOCOL, soon, and we won't have to add GIT_PROTOCOL
support to support newer versions of the git protocol, either.

Link: https://public-inbox.org/git/YTiXEEEs36NCEr9S@coredump.intra.peff.net/

doc: add lei-security(7) manpage

It seems like a good idea to have a manpage where somebody
can quickly look up and address their concerns as to what
to put on encrypted device/filesystem.

And I probably would've designed lei around make(1) for
parallelization if I didn't have to keep credentials off
the FS :P

script/lei: umask(077) before execve

While my MUA also runs umask(077) unconditionally, not all
MUAs do.  Additionally, pagers may support writing its buffer
to disk, so ensure anything else we spawn has umask(077).

fetch: ignore non-writable epoch dirs

This will eventually be useful for maintaing partial mirrors.

Keeping inline with the original public-inbox-fetch philosophy,
there are no additional config files to manage:
the user merely needs to remove write permissions to an $N.git
directory to prevent it from being updated.

Re-enabling updates just requires restoring write permission.

search: fix rt: w/ approxidate when TZ != UTC

While git respects a user's local timezone and returns
seconds-since-the-Epoch, we were unnecessarily and incorrectly
calling gmtime+strftime on its result.  So ignore calling
gmtime+strftime when the strftime format is "%s", just feed
the output time from git directly to Xapian.

This is mainly for lei, which will likely run in a variety of
timezones.  While we're at it, add a recommendation to use
TZ=UTC in public-inbox-httpd, in case there are (misguided :P)
sysadmins who set a non-UTC TZ.

lei refresh-mail-sync: drop old IMAP folder info

Like with Maildir, IMAP folders can be deleted entirely.
Ensure they can be eliminated, but don't be fooled into
removing them if they're temporarily unreachable.

lei refresh-mail-sync: implicitly remove missing folders

There's no point in keeping mail_sync.sqlite3 entries around
if the folder is gone.  We do keep saved-search configs around,
however, since somebody may decide to blow away a search and
start over.

lei refresh-mail-sync: drop unused {verify} code path

That option was never wired up, and probably not needed...

lei refresh-mail-sync: remove "gone" notices

Those stderr messages are not useful at all, and harmful with
the noise they cause.

lei_mail_sync: don't hold statement handle into callback

This can cause readers and writers to conflict since the
implicit transaction from SELECT in a LeiRefreshMailSync
worker would block the LeiStore process.

lei refresh-mail-sync: replace prune-mail-sync

Merely pruning mail synchronization information was
insufficient for Maildir: renames are common in Maildir
and we need to detect them after-the-fact when lei-daemon
isn't running.

Running this command could make "lei index" far more
useful...

v2: close R/O mail_sync.sqlite3 dbh before fork
  Keeping the DB file handle open across fork can cause bad things
  to happen even if we don't use it since sqlite3 itself still knows
  about it (but doesn't know Perl code doesn't know about it).

doc: glossary: add a reference for "epoch"

It comes up often enough and we need to ensure it's not
confused with IMAP "slices".

lei_pmdir: do not attempt to trigger network auth

Since some commands access both Maildirs and IMAP/NNTP servers
at the same time, LeiPmdir may see the same lei->{auth} and
lei->{net} objects as the sibling LeiInput-based workers.
Delete those at fork and do not attempt to do authentication in
those cases, since "net_merge_continue" will not be a registered
op and cause PktOp to fail even if authentication /can/ work
from a LeiPmdir worker.

doc: lei-mail-formats: add "eml" and expand on git things

While "eml" is not an output format, it seems worthy
to document, here, since users are likely to have experience
with *.patch files from "git format-patch".

net_reader: load IO::Socket::Socks in all workers

This was previously undetected since SOCKS is mainly used for
read-only (single worker) tasks, and worker[0] always loaded
the module.  However, "lei refresh-mail-sync" can bounce reads
to any worker, so we need to ensure worker[1..Inf] load it, too.

lei: git_oid: replace git_blob_id

We'll be using binary SHA-1 and SHA-256 in-memory since that's
what mail_sync.sqlite3 stores.

imapd: sort LIST response

While RFC 3501 doesn't require LIST responses be sorted,
it makes reading protocol dumps easier and we memoize it
once per-refresh, so it shouldn't be too expensive even
with thousands of folders.

lei ls-mail-source: sort IMAP folder names

Otherwise, public-inbox-imapd will emit mailboxes in random
order (as IMAP servers do not need to guarantee any sort of
ordering).  We'll take into account numeric slice numbers
generated by -imapd if they exist, so slice "80" doesn't show up
next to "8".

net_reader: emit .onion help for potential Tor users

We can't easily use torsocks, here, so try to be helpful
when it comes to proxy support.

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.