TODO: add pipelining note

Network latency is painful to deal with.

lei_to_mail: use abs_path for Maildir in mail_sync.sqlite3

lei->rel2abs doesn't resolve symlinks, which could cause
synchronization problems with export-kw or other commands.

lei q|up: support v2:/path/to/inboxdir destination

This allows "lei-managed pseudo mailing lists" as described
by Konstantin.

Alternates use is optional and can be enables via --shared.

This doesn't manage or edit ~/.public-inbox/config; presumably
there'll need to be some tweaking of search parameters before
finalizing and making the inbox publicly accessible via HTTP/NNTP.

Link: https://public-inbox.org/meta/20210426164454.5zd5kgugfhfwfkpo@nitro.local/T/

lei: retry_reopen on read-only Xapian access

Xapian DBs may be modified by a parallel process while we're
reading it, and Xapian's MVCC model places the burden on readers
to retry operations.

We'll also have retry_reopen croak instead of die on errors,
which ought to help us track down some "Document not found"
errors I've occasionally seen when using "lei <q|up>".

script/lei: drop leftover message about fallback

Non-daemon lei isn't implemented, anymore.

lei: restore working directory in more places

Every tick of the event loop can change the working directory,
so we need to restore it for every client if they operate
in different directories.

This would be easier if we had openat(2) and friends in Perl;
but Inline::C is practically required for lei, now.

t/lei-*: better diagnostics for occasional failures

Some of these have been failing occasionally, not sure
how, yet...

lei: handle a single IMAP message in most places

"lei import" can now import a single IMAP message via
<imaps://example.com/MAILBOX/;UID=$UID>

Likewise, "lei inspect" can show the blob information for UID
URLs and "lei lcat" can display the blob without network access
if imported.

"lei lcat" also gets rid of some unused code and supports
"blob:$OIDHEX" syntax as described in the comments (and used by
our "text" output format).

v2: enforce UID in URL, fail without
v3: fix error reporting (s/fail/child_error/)

lei_mail_sync: debug code for uncommitted txn

I'm not 100% sure why, but "lei up" seems to cause uncommitted
transaction errors.  LeiToMail calls sto->set_sync_info, but
LeiXSearch should call sto->done and lms_commit, so I'm not
sure where the uncommited transaction is coming from...

lei: add TODO item for FUSE mount

It seems possible and natural to allow browsing lei/store as
a Maildir (as well as read-write JMAP/IMAP store).

lei: mark reorder-and-rewrite-local-history as a TODO item

This is low priority, for now.

viewdiff: escape '{' and '}' for regexp

Perl 5 doesn't warn on this, yet, but it warns on unescaped
'(' and ')' nowadays, so it's conceivable Perl could start
warning on this in the future.  So future-proof our code and
reduce reader confusion.

viewdiff: make $UNSAFE a variable

There's no sense in using a constant here since it
gets copied into the uri_escape_utf8 function anyways.
Furthermore, inlined constants still leave behind a
subroutine and subs cost several KB of memory.

Finally, add a comment as to why it's different than the default
escape, since I just spent a minute wondering that.

lei rm: new command to remove messages from index

This is similar to "public-inbox-learn rm", but it's
possible to point an entire Maildir/IMAP/mbox*/newsgroup
at it.

lei: require Socket::MsgHdr or Inline::C, drop oneshot

The cost of supporting separate code paths between oneshot and
daemon isn't worth the trouble; especially if there are more
users to support.  The test suite time nearly doubles with
oneshot, so that's hurting developer productivity.

FD passing is currently required to work efficiently with
remote HTTP(S) queries which return large messages, as seen in
commit 708b182a57373172f5523f3dc297659d58e03b58
("ipc: wq: handle >MAX_ARG_STRLEN && <EMSGSIZE case").

Additionally, upcoming support for IMAP IDLE and inotify-based
monitoring of Maildirs cannot work properly without a background
daemon.

ipc: wq: handle >MAX_ARG_STRLEN && <EMSGSIZE case

WQWorkers are limited roughly to MAX_ARG_STRLEN (the kernel
limit of argv + environ) to avoid excessive memory growth.
Occasionally, we need to send larger messages via workqueues
that are too small to hit EMSGSIZE on the sender.

This fixes "lei q" when using HTTP(S) externals, since that
code path sends large Eml objects from lei_xsearch workers
directly to lei2mail WQ workers.

ipc: avoid potential stack-not-refcounted bug

This fixes a potential problem with Carp::longmess
firing somewhere deeper in the stack.  This is not a known
problem at this time, but something I noticed while chasing
something else.

lei forget-mail-sync: new command to drop sync information

Sometimes a user stops caring to sync an IMAP or Maildir
folder, or wants to force a resync.  Let them run this
command to have lei forget all the sync information about
the mail folder.

This won't delete any stored messages in git, but will
leave "lei index" users with dangling references.

lei_mail_sync: args2folder: common folder lookup sub

This lets us have a more consistent UX for mapping
easily-typed command-line arguments to canonical
folder locations.

lei export-kw: use lei->abs_path instead of rel2abs

This is to match LeiInput behavior when mail-sync is
enabled, since rel2abs won't resolve symlinks.

lei export-kw: fix case-insensitivity typo for IMAP URLs

Fixes: a9bfba8eb31dbb4c ("lei inspect: use LeiMailSync->match_imap_url")

lei_mail_sync: reject IMAP URLs w/o UIDVALIDITY

It's inappropriate to store sync information without
UIDVALIDITY, so add an assertion to prevent it.

lei inspect: use LeiMailSync->match_imap_url

Move match_imap_url into LeiMailSync so it can be used in more
places, such as "lei inspect".  Upcoming commands such as
"lei forget-mail-sync" and {add,forget,pause,resume}-watch will
also support relaxed IMAP matching rules since there's
no reasonable way to expect users use ";UIDVALIDITY=" on the
command-line.

lei <q|up>: set \Recent on non-empty mbox and Maildir

Despite JMAP not supporting the equivalent of the IMAP \Recent
flag, it is useful for "lei q --augment", and "lei up" users to
be able to distinguish new results from old-but-unread messages
in an mbox or Maildir.

For mbox family messages, we'll drop the "O" status flag when
appending to mboxes, and we'll write to the "new" subdirectory
of Maildirs.

Behavior when writing to initially empty Maildirs and mboxes
remains unchanged since there's no need to distinguish between
new and old results in the initial case.  Having users wait
for a rename(2) storm or complete mbox rewrite hurts UX.

With IMAP mailboxes, \Recent is already enforced by the IMAP
server and IMAP clients have no way of changing it(*)

(*) mutt uses the "Old" IMAP flag which isn't part of RFC 3501,
    other MUAs may do similar things.

lei export-kw: relax IMAP URL matching

It's unreasonable to expect UIDVALIDITY= to be specified in
command-line arguments.  We'll also check for cases without
"$USER@" or ";AUTH=", since we accept those forms on the
command-line.

lei export-kw: support exporting keywords to IMAP

We support writing to IMAP stores in other places (just like
Maildir), and it's actually less complex for us to write to
IMAP.  Neither usability nor performance is ideal, but usability
will be addressed in the next commit to relax CLI argument
checking.

Performance is poor due to the synchronous Mail::IMAPClient
API and will need to be addressed with pipelining sometime
further in the future.

net_reader|net_writer: pass URI refs deeper into callbacks

This will give us more flexibility in the future w.r.t.
dealing with UIDVALIDITY and AUTH= info with IMAP.  The LoC
reduction is welcome, too.

lei import: store IMAP user+auth in mail_sync folder URI

Just having UIDVALIDITY in the URI isn't enough, since a single
lei user may have multiple IMAP logins on the same server.

This leads to compatibility problems and forces a reimport for
the few users already using this lei functionality, but it's not
stable nor released, yet.

uri_imap: support uid/auth/user as full accessors

We will need this for mail synchronization

lei export-kw: new command to export keywords to Maildirs

IMAP will eventually be supported.

lei index: support command-line options

This mostly takes after "lei import", and at least --quiet needs
to be supported.

lei_input: fix canonicalization of Maildirs for sync

This is needed for the upcoming "lei export-kw"

lei tag: support tagging index-only messages

This will make some of our tests faster and allow users to try
more features of lei without high storage requirements.

lei: drop EOFpipe in favor of PktOp

lei already uses PktOp and SOCK_SEQPACKET throughout; whereas
EOFpipe had one single use in lei.  Since PktOp is a strict
superset of EOFpipe functionality, we may be able to get rid of
EOFpipe entirely.

However, lei is considered a portability canary and I'm not sure
if the stable public-inbox-* code can drop EOFpipe just yet.

treewide: favor open(..., '+<&=', $fd)

Cut down on unnecessary imports of IO::Handle and
method lookup + dispatch overhead.

lei rediff: fix construction of git-diff options

When generating git-diff options, lei-rediff extracts the single
character option from the lei option spec.  However, there's no check
that the regular expression actually matches, leading to an
unintentional git-diff option when there isn't a short option (e.g.,
--inter-hunk-context=1 maps to the invalid `git diff --color -w1').

Check for a match before trying to extract the single character
option.

Fixes: cf0c7ce3ce81b5c3 (lei rediff: regenerate diffs from stdin)

lei: relax rules for "new" in Maildir

mbsync and offlineimap both use ":2," suffixes for filenames in
"new/", however my interpretation of the Maildir spec at
<https://cr.yp.to/proto/maildir.html> is that ":2," is only for
files in "cur/".  My interpretation also matches that of
doveecot, but we'll allow what mbsync and offlineimap do given
their popularity.

lei lcat: fix handling of multiple MSGID_OR_URL arguments

`lei lcat' is documented as being able to display multiple messages,
but this works only with --stdin because the positional argument
MSGID_OR_URL is missing a period.

doc lei: update manpages with new options

doc lei: add manpages for new commands

[ew: MANIFEST: s/lei-cat/lei-lcat/]

doc lei: add manpage for convert

Link: https://public-inbox.org/meta/20210429015738.GA30172@dcvr/

doc lei q: add missing value for --lock

doc lei q: fix a typo

doc lei: resort lei-tag entries

The command was renamed in 54da988cfb049ea2 (lei tag: rename from "lei
mark", 2021-03-30).  Relocate its entries in txt2pre and Makefile.PL
to restore alphabetical sorting.

doc lei blob: point to lei-q for shared options

lei-blob shares a good number of options with lei-q.  Refer to lei-q's
manpage rather than repeating the descriptions.

Also, add lei-q to lei-blob's "see also" section.

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

doc: split option variants into separate items

e226f18934eb7291 modified the lei-q manpage so that each variant of an
option gets a dedicated =item to make L</--xyz> look nicer and to
follow the Perl core documentation.  Do the same for the other
manpages.

Note that this still leaves the variants of an option grouped in one
scenario: when a list of options without descriptions is presented as
a pointer to another location.  Splitting the variants in that case
would make it harder for the reader to tell what the distinct options
are.

doc lei blob: avoid combined description of separate options

The next commit will update the manpages to split each option's
variants into separate items.  This change won't mix well with
--oid-a, --path-a, and --path-b.  These different options all share a
single description, and, if each form is on its own line, the link
between the variants of each option would no longer be clear.

Use a dedicated description for each option to avoid confusion.

lei rediff: handle stdin like other commands

`lei rediff' reads from stdin when no argument is specified, but this
is likely unintentional given that other lei commands instead have a
--stdin|- option and that `lei rediff --help' includes --stdin.

Align rediff's handling with the other commands'.

lei rediff: mark --color-moved value as optional

`git-diff --color-moved' can be called without a mode, in which case
it defaults to "zebra".

lei_input: drop misplaced word from error message

dir_idle: support IN_DELETE_SELF|IN_MOVE_SELF, too

We'll treat IN_MOVE_SELF as IN_DELETE_SELF since there
doesn't seem to be a reliable way to distinguish them
with FakeInotify, nor know the new name with kevent.

dir_idle: detect files which are gone

lei now makes use of this to clean up after unlinked sockets
with less delay.  This will also be used to maintain
mail_sync.sqlite3.

lei_mail_sync: do not disable CoW for this DB

This is rather critical data for synchronization,
especially when "lei index" is used instead of "lei import"

git: fix numerous bugs in git_quote and git_unquote

git always quotes with leading zeros to ensure the octal
representation is 3 characters long.  We enforce that to match
low ASCII characters (e.g. [x01-\x06]) that don't need the
range provided by 3 characters.

git_unquote now does a single pass so it won't get fooled by
decoded backslashes into parsing a digit as an octal character.
git_unquote is also capped to "\377" so we don't overflow a
byte.

t/sigfd: use PublicInbox::DS::block_signals

We already use PublicInbox::DS in this test and I've always
found the terminology of sig* APIs confusing :x

syscall: minor yak-shaving updates

FreeBSD (and other *BSDs) do not have stable syscall numbers, so
drop no-op checks for it and add a note to use Inline::C,
instead.  Drop an implicit return for the syscall.ph loading
while we're at it, too.

On Linux, epoll_create(2) ignores the size arg since Linux
2.6.8, so just hard code it to some non-zero value.

On a side note, we can probably drop epoll_create(2) support
soon and just use epoll_create1(2) which appeared in 2.6.27+
(2008-10-09).  Our userspace (Perl and git) requirements are
already further ahead.

lei_xsearch: fix accounting bugs in for remote mboxrd

We must not accumulate mset totals for messages which
have already been counted.  Furthermore, the combined
search was being passed an extra arg and causing the
total to go missing.

lei_mail_sync: Maildir canonicalization omits trailing slash

We use trailing slashes internally, but should not increase
visual noise for users by exposing them in config files or
DB storage (and shell completion/listings).

This fixes a long-standing bug in $lei->rel2abs that prevented
absolute paths from being canonicalized.

lei_rediff: reduce overhead of tmp store

We don't need Xapian positional info when searching
for blob pre/post-images.  Furthermore, rediff will
usually be used for a single email or at most, one
patchset.  So there's little point in parallelizing
or having multiple shards.

lei rediff: do not automatically store patches/mails

We can use a temporary lei/store to avoid cluttering up
future search results.  This is especially useful since
we expect "lei rediff" to be useful for non-email diffs
and individual attachments, too.

lei rediff: capture and regenerate file modes

Don't lose file mode information when regenerating a diff.

script/public-inbox-extindex: chmod +x

Everything else that's intended to be executable at some
point has the executable bit set.  Remove an inaccurate
comment while we're at it.

lei blob: support "lei index"-ed mail

Normal git retrieval don't work for Maildir blobs indexed using
"lei index".  Fortunately, this oddness is limited to the
LeiStore class and we can override smsg_eml with a fallback
to read blobs from Maildirs.

lei rediff: regenerate diffs from stdin

Sometimes a mailed patch is generated with non-ideal output,
(lacking context, noisy whitespace changes, etc.), or a user
wants to use the same external diff viewer they've configured
git to use.

Since we have SolverGit to regenerate arbitrary blobs from
patches; this new command allows us to regenerate a diff with
different options using the blobs SolverGit gives us.

The amount of git-diff(1) options is mind numbing, so it's
likely I missed some favorites or botched the getopt spec
translation.

This also fixes Inbox::base_url to check psgi.url_scheme
before attempting to generate URLs and avoid uninitialized
variable warnings.  Oddly, the "lei blob" tests did not
trigger these uninitialized warnings.

Note: this will automatically import+index the message(s)
it's regenerating, because solver relies on being able
to lookup pre/postimage OIDs and read blobs.

lei index: new command to index mail w/o git storage

Since completely purging blobs from git is slow, users may wish
to index messages in Maildirs (and eventually other local
storage) without storing data in git.

Much code from LeiImport and LeiInput is reused, and a new dummy
FakeImport class supplies a non-storing $im->add and minimize
changes to LeiStore.

The tricky part of this command is to support "lei import"
after a message has gone through "lei index".  Relying on
$smsg->{bytes} == 0 (as we do for external-only vmd storage)
does not work here, since it would break searching for "z:"
byte-ranges when not using externals.

This eventually required PublicInbox::Import::add to use a
SharedKV to keep track of imported blobs and prevent
duplication.

lei: fix mail_sync.sqlite3 folder names for NNTP

We should not have "SCALAR(XXXXXXX)" showing up in SQLite DBs
because we passed a SCALAR ref instead of a non-ref SCALAR.

lei ls-mail-sync: fix handling of non-wildcard filters

If lei_ls_mail_sync() is given a filter without any wildcards
and --globoff is unspecified, glob2re() will return undef,
resulting in the final regular expression being undefined.
Always use a fallback value when there's no RE.

Based-on-patch-by: Kyle Meyer <kyle@kyleam.com>
Link: https://public-inbox.org/meta/20210504044559.12941-5-kyle@kyleam.com/

lei: add help output for --invert match

ls-external and ls-mail-sync accept an --invert-match option.  Show it
in the --help output.

lei ls-mail-sync: accept a filter

lei_ls_mail_sync() is written to accept a filter, and ls-mail-sync has
related command-line options (--globoff, --invert-match), but a
positional argument isn't actually accepted.  Add it.

lei ls-mail-sync: drop repeated -z/0 option

lei ls-mail-sync: update reference to ls-sync

ls-sync was renamed to ls-mail-sync in cb0e9d42b799c748.  Update a
stale reference to the old name.

doc: ignore onion URLs for 80-column check

This failure was also passing under FreeBSD make + /bin/sh;
so we also avoid the '&&' chain is avoided and use '>$@' as a
separate line in the Makefile.

treewide: update to v3 Tor onions

v2 onions are insecure, deprecated and going away.  v3 names are
unfortunately longer and more difficult to remember, but should
be more resistant to attack than v2 ones.

lei up: fix dedupe with remote externals on Maildir + IMAP

LeiToMail Maildir and IMAP write callbacks need to account for
the caller-supplied smsg.  We'll also make better use of the
user-supplied smsg object by ensuring blob deduplication happens
ASAP.

Fixes: e76683309ca4f254 ("lei <q|up>: distinguish between mset and l2m counts")

lei <q|up>: writes to Maildirs and IMAP use mail-sync

This will allow keyword updates from other folders to propagate
to folders where search results may be duplicated.

net_writer: use "FLAGS.SILENT" to set keywords

Instead of "+FLAGS.SILENT" which merely adds to the keywords.
We store all keywords together, so it's unlikely we will rely
on the "+FLAGS.SILENT" or "-FLAGS.SILENT".

lei: simplify workers_start API

In most cases, we just name the worker process based
on the command.  The only change is for LeiMirror
vs "lei add-external --mirror", but I doubt it matters.

lei_input: reject --mail-sync if using HTTP(S) for now

I'm not sure how we'll distinguish JMAP vs read-only HTTPS,
yet; but we'll focus on currently-supported stuff, first.

lei_input: common net_merge_all_done for lei <import|tag>

I suspect there'll be more lei_input-only things in the future.

lei <q|up>: combine written/results into one line

Having multiple lines of output mean they can be interleaved in
daemon mode.  Put stats into one line to reduce screen
real-estate size and improve readability.

lei_auth: s/net_merge_complete/net_merge_all_done/

We use the "done" term elsewhere for similar things, and
my easily-confused mind equates "complete" with shell
completion.

lei edit-search: support relocating lei.q.output

The contents of the old lei.q.output will not be removed,
but will be converted into the new one.

lei import: fix --mail-sync handling in LeiInput

"lei inspect" also shows "mail-sync" as a field name

lei: rename ls-sync to ls-mail-sync

This allows tab-completion for "ls-search" to work with fewer
characters ("ls-s<TAB>" instead of "ls-se<TAB>"), and I expect
"ls-search" to be used more frequently than "ls-mail-sync".

This also matches the --mail-sync switch of "lei import"

lei_saved_search: fix excess indent for first lei.q entry

This was harmless, but ugly and possibly confusing to
users who run "lei edit-search".

lei <q|up>: distinguish between mset and l2m counts

The number of messages we write to --output is usually different
than the mset count due to deduplication from combining multiple
sources.

This change makes the stderr output of "lei up --all=local" way
more useful IMHO.

xt/lei-onion-convert: test for NNTP+IMAP onions

These tests require a running Tor instance (defaulting to
127.0.0.1:9050) and Internet connectivity, but otherwise
work pretty well.

net_reader: support (imap|nntp).proxy in config file

This allows us to use URL-matching config in git and specify
proxies on a per-host basis.  git 2.26+ users may use wildcards
to enable Tor (on 127.0.0.1:9050) for all NNTP and IMAP .onion
domains.

My ~/.config/lei/config file has the following:

[imap "imap://*.onion"]
proxy = socks5h://127.0.0.1:9050
[nntp "nntp://*.onion"]
proxy = socks5h://127.0.0.1:9050

net_reader: Net::NNTP --proxy=socks5h:// support

Since Net::NNTP doesn't support Socket or RawSocket
options/accessors like Mail::IMAPClient does; we must perform
localized @ISA manipulation and massage Net::NNTP into using
IO::Socket::Socks rather than IO::Socket::IP.

This is a bit fragile, but Net::Cmd and Net::NNTP rarely change;
and I keep an eye on them, anyways.

lei: IMAP .onion support via --proxy=s switch

Mail::IMAPClient provides the ability to pass a pre-connected
Socket to it.  We can rely on this functionality to use
IO::Socket::Socks in place whatever socket class
Mail::IMAPClient chooses to use.

The --proxy=s is shared with curl(1), though we only support
socks5h:// at the moment.  Is there any need for SOCKS4 or SOCKS5
without name resolution?  Tor .onions require socks5h:// for
name resolution and to prevent data leakage.

net_reader: {nn,mic}_for: use prototypes for internal subs

We don't use these subs elsewhere, so stick prototypes on them
to give them a little extra checking.

lei: ensure autoflush(1) is on STDERR

This fixes error reporting for oneshot tests in xt/lei-auth-failure.t

lei: kill old PIDs when dropping

This ensures hitting Ctrl-C on a long-running "lei convert" or
similar will stop the WQ worker, even after we've closed
the WQ socketpair in the daemon.

lei_curl: improve correctness of LD_PRELOAD check

LD_PRELOAD sent by a client can't affect lei-daemon.

lei sucks: preserve utsname.machine, add "x86" where appropriate

It's helpful for us to distinguish x86 kernels from x86_64
kernels when using an x86 userspace.  OSes are dropping i386
support and only support i486 and newer, so "x86" is a more
appropriate description for that platform than "i386".

lei_store: fix locking w.r.t epoch creation

Prior to this change, it was possible for oneshot lei processes
to race on epoch creation/rollover.  lei-daemon normally
prevents the problem by funnelling all writes to a single
socket, but oneshot lei has no such protection.

lei import: support shell completion of known folders

This also fixes completion of "lei up" for IMAP folders.

lei import: support UIDVALIDITY in IMAP URL

Specifying a UIDVALIDITY value allows the user to enforce
a strict match and force failure.  This necessitated changes
to NetReader to allow die() and make error reporting more
suitable for CLI usage rather than daemonized usage of -watch.

lei import: avoid IMAPTracker, use LeiMailSync more

IMAPTracker has a UNIQUE constraint on the `url' column,
which may cause compatibility and/or rollback problems
in attempting to deal with UIDVALIDITY changes.

Having multiple sources of truth leads to confusion and bugs,
so relying on LeiMailSync exclusively ought to simplify things.

Furthermore, since LeiMailSync is only written to by LeiStore,
it is safer in that it won't mark a UID or article as imported
until git-fast-import has seen it, and the SQLite commit always
happens after "done\n" is sent to fast-import.

This mostly reverts recent commits to IMAPTracker to support
lei, those are:

1) commit 7632d8f7590daf70c65d4270e750c36552fa9389
   ("net_reader: restart on first UID when UIDVALIDITY changes")
2) commit 311a5d37ad275cd75b1e64d87827c4d13fe4bfab
   ("imap_tracker: prepare for use with lei").

This means public-inbox-watch will not change between 1.6 and
1.7: -watch stops synching a folder when UIDVALIDITY changes.

content_hash: git_sha: allow unblessed SCALAR refs

This will be convenient to avoid the overhead of
PublicInbox::Eml for verifying synchronization in lei.