lei_input: reduce IPC traffic with multiple inputs

No point in sending a command for every input when a
single one will do.  We'll also trigger LeiStore->done
sooner in the worker rather than later.

lei blob: "--mail" disables solver, use --include/only

Assume a user specifying --mail doesn't want to spend cycles
reconstructing a blob from a code repo.  Also, don't require
users to use add-external or a previous -I or --only to ready an
external for use with ale.git.

doc: lei-overview: favor Maildir for mutt examples

mboxes are generally horrible for interactive read-write use due
to locking.  Describe our parallel behavior with mutt, since
writing mail can take a long while and being able to read
results as they're written is nice.

We'll also use a gzipped mboxrd for the import example, since
we can decompress gzipped mboxrds automatically, now.

doc: add lei-mail-formats(5) manpage

While plenty of online documentation exists, it's good to have
a locally-available summary for users to look at offline.
Fix a URL in Watch.pm while we're at it, too.

lei: fix IMAP auth failure handling

We must use the $ops hashref returned by lei->workers_start,
since it's modified to include extra handlers for auth failures
and whatnot.

Fixes: 954581b8e575966a ("lei: simplify PktOp callers")

lei tag: rename from "lei mark"

I've decided "tag" is a better verb since it seems more
widely-used term for associating metadata with data.

Not only is it analogous to the "notmuch tag" command, but
also makes sense when compared to tooling for manipulating
metadata for non-mail data (e.g. audio metadata tags).

There's even a Wikipedia entry for it:
https://en.wikipedia.org/wiki/Tag_(metadata)
whereas "mark" is used in the description, but has no
entry of its own with regards to metadata.

lei q: avoid redundant default setting for sort with l2m

No point in munging user-supplied $lei->{opt} when %mset_opt
exists.  We'll be depending on docid being in descending order
for saved search support.

lei_to_mail: update some comments and style

Note that update_kw_maybe is critical in preventing accidental
data loss with default "lei q --output" behavior.

Also avoid treating (proposed) MH support as lock-free, since
appears to lack specifications for locking and be even worse
than mbox* in that regard...

git: local_nick: handle trailing or redundant '/' in git_dir

Some cgit configs use trailing slashes in pathnames
which we preserve internally.

Before this change, trailing slashes in cgit config files
was causing ViewVCS (SolverGit) output to show up as "???"
for coderepos without cgitUrl configured.

lei_input: support compressed mboxes

Since "lei q" and "lei convert" already support writing these
compressed inboxes, it makes sense that all mbox readers support
them, as well.

Using compression is one reliable way to know an mboxrd or mboxo
hasn't been unexpectedly truncated.

lei blob: cleanup solver tmpdir on failure

$lei->fail sends SIGTERM which prevents the File::Temp::Dir in
$solver->{tmp} from being cleaned up, so use $lei->child_error
instead.

lei_input: treat ".eml" and ".patch" suffix as "eml"

".eml" is a suffix supported by (/usr/local)/etc/mime.types
on Debian and FreeBSD systems using the "mime-support" package.
".patch" is what "git format-patch" generates by default since
git v1.5.0 in 2007.

lei: use IO::Uncompress::Gunzip MultiStream

This is compatible with default gunzip(1) behavior and
future-proofs us against potential changes in PublicInbox::WWW
to save memory on public-inbox-httpd instances.

lei_input: avoid special case sub for --stdin

We can consistently open /dev/stdin correctly nowadays, so
drop the input_stdin and just use the normal ->path_to_fd
code path.

doc: lei: update description, add warnings

Describing the design details and architecture doesn't seem
appropriate for a section 1 manpage.

We'll also add a warning about it being in the early stages.

doc: lei q: clarify default output as stdout

Seeing a plain "-" may be confusing, especially when we also
support it for --stdin.  Use the C<> POD directive to denote it
as code, too.

doc: lei q: add warning for --output clobbering

The behavior matching mairix still frightens me a bit when it
comes to supporting new users.  On the other hand, I've rarely
ever used --augment with mairix, so I still think the current
(dangerous) behavior makes sense in the context of search results.

doc: lei q: drop NNTP from --output description

We only support NNTP as inputs for convert, import, and
mark|tag.  I'm not sure if supporting NNTP output is worth
it, nor do we have a good way to test it.

t/epoll: explicitly use scalar operator for @events

It's slightly easier to test on a machine without Test::More
and I'm hand-rolling my own is() and ok() subs.

doc config: don't render a to-do comment

In the public-inbox-config manpage, the match=domain item under
publicinbox.wwwlisting has a to-do comment that gets rendered as
"support showing cgit listing".  That's potential confusing to
readers, especially given that the "TODO" is dropped.

Change the markup so that the comment isn't rendered.

doc lei overview: better explain routes into local store

doc lei overview: note that lei-init is usually unnecessary

cf. https://public-inbox.org/meta/20210325083207.GA30551@dcvr

doc lei: add manpages for new commands

doc lei: update manpages with new options

doc lei: don't render most to-do comments

The lei manpages have a number of to-dos, but with the exception of
the lei-q's -tt warning, none of them seem worth displaying to the
reader (and some might not be worth addressing at all).

doc lei: drop an unnecessary to-do comment

When a new command is implemented, it is probably clear that it should
be added to lei.pod, but either way, having a to-do comment in lei.pod
isn't likely to help.

doc lei: note --stdin shortcut in synopses

doc lei-q: fix typo in -tt description

treewide: shorten temporary filename

File::Temp only requires four 'X' characters (unlike mkstemp(3),
which requires six).  So only so only give it 4 to avoid an
80-column violation and maybe save metadata space on FSes.

lei: drop coderepo placeholders, submodule TODO

"lei blob" supports --git-dir and -C, and checks if the
current directory has a git directory associated with it.
It will likely support submodules in the future.

I'm inclined to believe declaring coderepos in a command-line
tool is needless clutter and users will rarely want to search
for blobs across different projects when on the command-line.

lei blob: add remote external support

Introduce a new LeiRemote wrapper to provide an internal API
which SolverGit expects.  This lets us use HTTP/HTTPS endpoints
to reconstruct blobs off patches as we would with local
endpoints, just more slowly...

t/lei_store: ensure LeiSearch responds to ->isrch

This is needed for SolverGit, at least, and maybe other
bits we share with PSGI in lei.

lei blob: flesh out help text

This means "lei blob" gets shell completion, too.

lei help: show "NAME=VALUE" properly for -c

lei blob: some extra tests

Most of it already gets tested since most of the logic is in
SolverGit, but make sure it's all wired up properly to lei.

lei blob: fail early if no git dirs

This avoids triggering a "BUG:" message in the solver code.

lei blob: support --no-mail switch

It's possible for a abbreviated OID to be resolved unambiguously
to an email before we attempt to look at externals via xsearch;
so provide a way for a user to force searching coderepos.

If hints (--oid-a, --path-a, --path-b) are present, we'll
assume --no-mail by default, otherwise we'll assume the
user wants to look through mail for a matching blob.

lei blob: dclose if already failed

We must close the socket to trigger pager exit if blob
reconstruction fails.  Not sure how to test this in the
test suite...

lei init: split out into separate file

This is a rarely-needed command, so keep it separate file
so it's easier-to-find and maybe saves a bit of RAM.

lei: simplify PktOp callers

Provide a consistent ->op_wait_event method instead of
forcing callers to loop (or not) at each callsite.
This also avoid a leak possibility by avoiding circular
references.

test_common: require_mods bundles

This makes it easier to manage test dependencies on systems
where optional stuff isn't installed.  This fixes some lei tests
which didn't check for Plack before starting -httpd, and ensures
Parse::RecDescent is available for -imapd in case
Mail::IMAPClient stops using it.

lei mark: relax label requirements

It seems safe to use ALLCAPS labels like "INBOX" with Xapian.
We'll also allow single-character labels.

lei blob: aka "git-show-harder" for blobs

This implements blob reconstruction via SolverGit,
emulating the functionality of /$INBOX/$OID/s/ endpoint
in PublicInbox::WWW.

It uses the current working tree as a coderepo, and
accepts any number of --git-dir=$PATH args.

Remote externals are not yet supported.

v2: use absolute path for git repos

lei_query: hoist out lxs_prepare

We'll be reusing it for "lei blob", as it makes sense
to keep handling of --only, --include, etc. switches
consistent.

lei help: move "lei help" into LeiHelp.pm

We need to load LeiHelp.pm anyways if somebody calls "lei help",
so save a few kB RAM for users who don't need help.

lei_ale: do not create store unnecessarily

We want to be able to read blobs without writing anything to
disk.

lei mark: disallow '!' in labels

'!' could wreak havoc if exposed to a shell like bash.  It seems
like a rare character for use in file/directory/mailbox names.

lei: support /dev/fd/[0-2] inputs and outputs in daemon

Since lei-daemon won't have the same FDs as the client, we
need to special-case thse mappings and won't be able to open
arbitrary, non-standard FDs.

We also won't attempt to support /proc/self/fd/[0-2] since
that's a Linux-ism.  /dev/fd/[0-2] and /dev/std{in,out,err}
are portable to FreeBSD, at least.  mawk(1) also supports
/dev/std{out,err}, as does gawk(1) (which supports everything
we can support, and arbitrary /dev/fd/$FD).

lei: do not blindly commit to lei/store on close

It may hide errors/bugs, instead do it explicitly for each
worker that writes to it.  For lei_xsearch, it will be better
to close before spawning the MUA for future use since we may
need it again once the user starts changing keywords.

lei q: skip lei/store->write_prepare for JSON outputs

JSON outputs won't write to lei/store at all, so there's
no point in forking the store worker if it's not already
running.

LeiSearch object ($lse) is also fork-safe until it opens a
persistent FD for Xapian/SQLite so we can unconditionally
carry it across fork.

git-send-email-reply: Append subject

I keep copy-pasting the addresses provided,
I keep writing my plaintext reply in a file,
and I keep forgetting to add a subject
(because I am "just" writing a plaintext file)

Teach `git-send-email-reply` to append a `--subject` line.

[ew: avoid URI-encoded subject on command-line, adjust t/reply.t]

Signed-off-by: Stavros Ntentos <133706+stdedos@users.noreply.github.com>

lei: add some labels support

"lei q" now displays labels in JSON output, "lei mark"
can add or remove labels for any messages.

"lei ls-label" is supported, too.

Unfortunately, "lei q" won't hande "kw:" or "L:" for
external messages, they must be imported, first.

lei: _lei_store: use default even if unconfigured

Perhaps leistore.dir doesn't need to have a config file
entry if we're using the default location.

v2: "account for unconfigured leistore.dir" (on reuse)

lei_xsearch: wait for kw updates for non-threaded case, too

We'll also hoist wait_startq out of the per-message loops
since it's not worth having to check every single message
when filling in smsg info is reasonably fast, anyways.

t/lei: add more diagnostics for failures

This seems to error out while looping the test suite and
I'm not 100% sure why.

t/cmd_ipc: workaround signal handling raciness

Perl can't check for interrupts when inside a blocking syscall,
as there's no self-pipe mechanism inside Perl itself.  So fork
a child and have it repeated kill(2) instead of relying on alarm(3).

lei import: force store, improve test diagnostics

"lei import" should never be without a {sto}, and *_done should
not be called multiple times, so ensure we can fail if it's
missing.

Update some existing tests to complain loudly by introducing a
handy "xbail" function which wraps "explain" and BAIL_OUT.
BAIL_OUT was painful to type and concatenating the result of
"explain" doesn't work as I thought it would since "explain"
always returns an array, and BAIL_OUT only accepts a single
scalar arg (unlike "die").

tests: "check-run" uses persistent lei daemon

We'll use a lei-daemon if it's already running and
TEST_LEI_DAEMON_PERSIST_DIR is set, but we can also start
one and manage it from t/run.perl

This drops "make check-run TEST_LEI_DAEMON_ONLY=1"
time by ~10% for me.

t/*: drop unnecessary v1-specific index calls

Outside of mirrors, we can -init with indexlevel to avoid
calling -index explicitly.

lei_mirror: don't show success on failure

While we were exiting with a error code, showing a successful
"# mirrored $URL" message is misleading and wrong.  Don't show
success until everything is complete and the config is written.

lei add-external: do not initialize writable store

There's no need to create or write lei/store when adding
an external, we just need to write to the config file.

test_common: TEST_LEI_ERR_LOUD does not hide path names

We hide paths by default to reduce noise, but we want
noise with loud errors.

lei: janky $PATH2CFG garbage collection

We need to rely on this to keep our config cache (and lei_store
pipes) under control with tests each creating a new config and
directory.

test_common: cleanup inbox objects after use

This stops us from leaking some more file handles across
test cases.

lei-daemon: do not leak FDs on bogus requests

If a client passes us the incorrect number of FDs, we'll vivify
them into PerlIO objects so they can be auto-closed.  Using
POSIX::close was considered, but it would've been more code to
handle an uncommon case.

lei_mirror: fix circular reference

All of our $lei->workers_start callers can simply rely on
that wrapper to do the right thing and pass fields to
->wq_worker_start children, only.

This could manifest as a unbound memory growth if somebody is
constantly mirroring, and was causing tests to get stuck when
experimenting with a persistent lei-daemon for the entire
test suite.

v2writable: cleanup SQLite handles on --xapian-only

I'm not sure exactly why this is needed with run_script
localizing %SIG and everything else, but explictly cleaning up
seems to fix the occasional test failures I see.

Followup-to: 4c6c853494b49368 ("tests: show lsof output on deleted-file-check failures")

lei_store: give process a better name

We'll prioritize the last two components of the path name
("lei/store") since that's how I often refer to the on-disk
location.  Then, show the XDG_DATA_HOME it belongs to in case
a user changes HOME or XDG_* for testing purposes.

lei: clean up pkt_op consumer on exception, too

We need to consistently ensure pkt_op_c doesn't lead to a
long-lived circular reference if an exception is thrown in
pre_augment.  Maybe the API could be better, but this fixes an
FD leak when attempting to --augment a FIFO.

Followup-to: b9524082ba39e665 ("lei_xsearch: cleanup {pkt_op_p} on exceptions")

lei: update {3} after -C chdirs

This is necessary for lei->rel2abs correctness, and may
eventually be useful if we can use *at syscalls.

lei: drop circular reference in lei_store process

I'm not sure if this was causing real problems, but it's sure ugly.

mbox_lock: dotlock: chdir for relative lock paths

Since lei-daemon will fchdir on every request, we must ensure
we're in the correct directory before unlink(2) is called,
since we can't use unlinkat(2) from pure Perl.

ds: improve DS->Reset fork-safety

None of these fixes affect current public-inbox-* code, or even
normal uses of lei.  However, lei users wanting to switch
between $HOME directories or use alternate store paths may
notice strange behavior and this fixes some of it.

We'll also loop to account for DESTROY callbacks inserting into
container objects and retry appropriately.

lei: improve management around short-lived workers

Instead of creating a short-lived circular reference,
ensure they don't exist in the first place.

Note the following changes to hold an extra ref to $sto:

- $self->_lei_store(1)->write_prepare($self);
+ my $sto = $self->_lei_store(1);
+ $sto->write_prepare($self);

I'm not a perlguts expert, but I actually wanted to switch
to the one-line version for LeiImport, but xt/lei-auth-fail.t
was getting stuck for some reason.  It seems the extra ref
to the LeiStore ($sto) object is necessary.

lei_input: more common code between <mark|convert|import>

"lei convert" is actually a bit of the odd one, since
it uses lei2mail for auth, unlike the others.

lei: persistent workers (lei_store) run in /

Since each lei->event_step can change the directory of
lei-daemon, we need to ensure the lei_store runs in a
directory that is stable.

test_common: check lei/errors.log

This will make it easier to diagnose some large internal
rewrites.

net_reader: nntp_each: pass keywords as `undef'

We'll use `undef' to denote keywords are unknown/unsupported,
instead of an empty arrayref.

This will let callers use the same callback and args for
imap_each.  Passing an empty arrayref to set_eml in LeiStore
causes keywords to be cleared completely, which is not desired
behavior when "lei import" is importing already-seen messages
from NNTP.

lei: hide *_atfork_child from command-line

Otherwise we could get non-sensical results if somebody tries
running "lei atfork_child" from the command-line.

lei mark: add support for (bash) completion

Only lightly tested, this seems to suffer from the same
problem as external completions for network URLs with
colons in them.  In any case, its usable enough for me.

The core LEI module now supports completions for lazy-loaded
commands, too, so we'll be able to do completions for other
commands more easily.

lei mark: command for (un)setting keywords and labels

Only tested for keywords and labels with file inputs, so far;
but it seems to do what it needs to do.  There's a bit more
redundant code than I'd like, and more opportunities for code
sharing in the future

"lei import" will be expanded to support +kw:$KEYWORD and
+L:$LABEL in the future.

lei import: ignore Status headers in "eml" messages

Those headers only have meaning with for mboxes.  Don't surprise
users by trying to make sense of a header that is defined for mboxes.

It's possible to send email with (Status|X-Status) headers and
have those headers show up in a recipient's IMAP mailbox.

This was bad because an IMAP user may want to import a single
message through their MUA and pipe its contents to "lei import"
without noticing a mischievious sender stuck "X-Status: F"
(flagged/important) in there.

lei_input: drop "From " line on single "eml" (message/rfc822)

This matches the long-standing behavior of public-inbox-mda,
public-inbox-learn and our other tools.  It is useful because
mutt, "git format-patch", and likely other tools will
pipe a single message with a "From " header line, but with
no further "From " escaping or Content-Length: header.

lei_input: common filehandle reader for eml + mbox

This improve code regularity, and will let us deal with
the "RFC822" messages with "From " line that mutt pipes
to.

mbox_reader: add ->reads method to avoid nonsensical formats

Relying on UNIVERSAL::can may cause internal helper methods
to be used, which can lead to failures or nonsensical results.

lei: simplify workers_start and callers

Since workers_start is in the common PublicInbox::LEI
package, we can just use \&METHOD_NAME instead of relying
on UNIVERSAL->can to avoid a method dispatch.

Most of our worker code can just use lei->dclose, so default
to doing that unless it's been overridden.

lei: share input code between convert and import

These commands accept mail the same way, and this forces
us to maintain consistent input format support between
commands.

We'll be using this for "lei mark", too.

net_reader: escape nasty chars from Net::NNTP->message

Net::Cmd::message (used by Net::NNTP) does no escaping at all,
so "\r" was causing confusing/nonsensical error messages when
I tried to import from the wrong group.

lei: support -c <name>=<value> to overrides

It's a bit nasty, but seems to mostly work for debugging
IMAP and NNTP commands.

lei: simplify lazy-loading

This makes it slightly easier to implement future commands,
since there'll be a couple more relatively self-contained
ones.

lei: fix some warnings in tests

And then test the contents of $lei_err to ensure it doesn't
happen again.

We'll also make MboxLock emit nicer warnings without the line
number, since the line number is irrelevant to the user fixing
an mbox lock contention problem.

Finally, we'll also allow showing loud warnings via
TEST_LEI_ERR_LOUD=1

lei q: fix warning on remote imports

This will let us tie keywords from remote externals
to those which only exist in local externals.

lei import: vivify external-only messages

Keyword storage for external-only messages was preventing
messages from being explicitly imported.  Teach lei_store
to vivify keyword-only entries into fully-indexed messages
on import.

searchview: collapse Message-ID links in summary

There's no point in showing duplicate links to the same
Message-ID in summary view.  The per-message page will
note the duplication (if any) separately.

Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://public-inbox.org/meta/20210317132723.xx4klonordhsb6ve@chatter.i7.local/

lei q: trim JSON output

Stop showing `docid' since it's not useful with shards.

`bytes' and `lines' are probably noise, but maybe could be
visible in some "fuller" view.

v2: t/lei_xsearch: fix warnings from {docid} removal

lei: tie ALE lifetime to config file

This should make a future change to "lei import" work more
nicely, since we'll be needing ALE to vivify external-only
messages upon explicit "lei import".

lei_to_mail: match mutt order of status headers

These changes may make it easier to do byte-for-byte comparisons
with mail copied out of mutt, a popular MUA for our target
audience.

mutt currently outputs the 'R' (seen) flag before the 'O'
character in the Status: header.  We'll assume that stays
the case (it has been for a while).

Status now comes before X-Status, also matching mutt behavior.

lei q: put keywords on one line in --pretty output

Don't waste precious terminal space when there are only a small
number of possible keywords supported/reserved for JMAP.  In the
future, we may implement more sophisticated wrapping for labels,
but it we'll cross tha bridge when we come to it.

lei q: support vmd for external-only messages

"lei q" now preserves changes per-message keywords across
invocations when it's --output (Maildir or mbox) is reused
(with or without --augment).

In the future, these changes will be monitored via inotify,
EVFILT_VNODE or IMAP IDLE, too.

Unfortunately, this currently prevents "lei import" from ever
importing a message that's in an external.  That will be fixed
in a future change.

lei: All Local Externals: bare git dir for alternates

This will be used for keyword (and label) storage for externals.
We'll be using this to ensure we don't redundantly auto-import
messages into lei/store if they're already in a local external
(they can still be imported explicitly via "lei import").