doc: add lei-import(1)

doc: lei: prefer 'location' and 'dirname'

This follows the help output change in 52342875 (lei help: split out
into separate file, 2021-02-06).

doc: lei q: use 'mfolder' as --output placeholder

'mfolder' is familiar to mairix users, and 'path' isn't a good choice
because support will be added for IMAP.

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

tests: skip properly with git <2.6

Tested with git 1.8.3.1 on CentOS 7.x

`plan skip_all => ...' doesn't work after some tests have run,
we have to call skip() instead.

search: fix argv handling of quoted phrases

This fixes both an old bug in "lei q" argv handling and one
recent regression introduced with the change to use approxidate.

Field prefixes are also handled correctly inside parenthesized
statements when the field follows "(" without a separation
character.

Fixes: fbb7ccabbf54a405 ("lei q: use git approxidate with d:, dt: and rt: ranges")

lei_external: fix+test handling of escaped braces

While '{' and '}' are rare in path names, somebody may still
use them or deal with software which does (e.g. GNU arch).

net_reader: new package split from -watch

We'll be using some of this for IMAP and NNTP support in lei,
too.  More will need to be done to improve code sharing and
reusability, soon, but this is a start.

lei: note some TODO items (curl, externals)

I don't know if it's worth it to use libcurl directly
(nor the effort to support and maintain tests)

lei ls-external: support --local and --remote

Similar to "lei q", "--local" means only local and "--remote"
means remote only.  I can't think of a reason to have --no-*
variants for these switches.

There's also updates to the TestCommon for more common lei
cases.

test_common: support lei-daemon only testing

Daemon-only tests can be significantly faster due to cached
configs; so give developers a chance to test only daemons to
improve productivity.

The differences between daemon and oneshot modes are minimal,
at this point.

lei_external: remove unnecessary Exporter use

We don't need to export for methods which are only called via
"->" or "->can".

lei *external: glob improvements, ls-external filtering

The "ls-external" now accepts the same glob patterns used by
with lei q --{include,only,exclude}.  If no glob is detected, it
will be treated as a literal substring match (like "grep -F").

Inverting matches is also supported ("grep -v").

tests|lei: fixes for TEST_RUN_MODE=0 and lei oneshot

DESTROY callbacks can clobber $?, so we must take care to
preserve it when exiting.  We'll also try to make an effort to
ensure better DESTROY ordering and delete as much as possible
before x_it finishes.

We also need to load PublicInbox::Config when setting up
public inboxes.

lei: replace "I:"-prefixed info messages with "#"

The "#" is what TAP <https://testanything.org/> uses,
which is also consistent with what our (and many other)
test suites emit.

t/run.perl: drop Cwd dependency

Perl 5.8.8/5.10.0+ can use fchdir(), and we depend on 5.10.1+

lei q: prefix --alert ops with ':' instead of '-'

Using dashed keywords confuses the option parser without
"=" signs (and bash completion doesn't yet work with "=").

So use ":" instead of "-" as the prefix for internal ops,
since ":" is just as unlikely to be the first character of
an executable file in a user's $PATH.

use MdirReader in -watch and InboxWritable

MdirReader now handles files in "$MAILDIR/new" properly and
is stricter about what it accepts.  eml_from_path is also
made robust against FIFOs while eliminating TOCTOU races with
between stat(2) and open(2) calls.

t/run.perl: fix for >128 tests

We need to explicitly close the write-end of the pipe in workers
to ensure they don't prevent each other from seeing EOF.

Also, make a note to keep using the pipe for now since
Linux <3.14 had broken read(2) semantics when file descriptions
are shared across threads/processes.

lei: split out MdirReader package, lazy-require earlier

We'll do more requires in the top-level lei-daemon process to
save work in workers.  We can also work towards aborting on
user errors in lei-daemon rather than worker processes.

"lei import -f mbox*" is finally tested inside t/lei_to_mail.t

git: ->qx: respect caller's $/ in array context

This could lead to bad results when doing ls-tree -z
for v2 import in case there's multiple files.  In any case,
the `local $/ = "\0"' in Import.pm is also eliminated to
reduce potential confusion and surprises.

t/cgi.t: modernizations and style updates

We prefer BAIL_OUT or fail to die in tests (I didn't know
BAIL_OUT existed when I started the project).  We can also
depend on IO::Uncompress::Gunzip being available,

We'll keep the cgi_run wrapper since the .cgi could
use some coverage and remove the FIXME note.  run_script
makes tests fast enough.

test_common: disable fsync on the CLI where possible

This makes tests faster for users on slow TMPDIR (or not using
eatmydata) and forces coverage on a non-default switch.

Unfortunately, this doesn't yet cover InboxWritable usage.

t/thread-index-gap.t: avoid unnecessary map

We only care abount the number of results.

www: stream mboxrd in descending docid order

Order doesn't matter when users are completely downloading
mboxrds onto the FS and then opening them with an MUA.  The
MUA is expected to sort the results in the user's preferred
order.

However, lei can start streaming the results to its destination
Maildir (or eventually IMAP/JMAP mailbox) with an MUA already
open.  This will let users see recent results sooner in their
MUA, as those tend to have a higher docid.  This matches the
behavior of the HTML results, as well.

As a bonus, this is around ~5% faster in a one-off, informal
test case with 66k results.  I expect this to hold true in all
all cases since git has always optimized storage to favor recent
objects.

spawnpp: raise exception on E2BIG errors

This matches the Inline::C version, and lets us test
argv overflow with $search->query_argv_to_string;

search: use one git-rev-parse process for all dates

This is necessary to avoid slowdowns with pathological cases
with many dates in the query, since each rev-parse invocation
takes ~5ms.

This is immeasurably slower with one open-ended range, but
already faster with any closed range featuring two dates which
require parsing via git.

lei q: use git approxidate with d:, dt: and rt: ranges

Instead of having --(sent|received)-(before|after)=s
command-line switches, we'll just try to make sense of argv so
it's usable within parenthesized statements and such.

Given the negligible performance penalty with Inline::C
process spawning, we'll probably wire this up to the
WWW interface, too.

"d:" is for mairix compatibility.  I don't know if "dt:" and
"rt:" will be too useful, but they exist because of IMAP
(and JMAP).

git: implement date_parse method

Users are expected to be familiar with git's "approxidate"
functionality for parsing dates, so we'll expose that
in our UIs.  Xapian itself has limited date parsing functionality
and I can't expect users to learn it.

This takes around 4-5ms on my aging workstation, so it'll
probably be made acceptable for the WWW UI, even.

libgit2 has a git__date_parse function which I expect to have
less overhead, but it's only for internal use at the moment.

lei: drop BSD::Resource usage

It's no longer necessary with the changes to stop doing
FD passing in our backend.

cf. commits 5180ed0a1cd65139 and 7d440bf3667b8ef5
    ("lei q: eliminate $not_done temporary git dir hack")
    ("lei q: reorder internals to reduce FD passing")

lei: avoid racing on unlink + bind + listen

When multiple lei(1) processes are starting in parallel without
lei-daemon already running, it's possible for them to trample
each others' socket path trying to start lei-daemon.  Lock
errors.log before unlink/bind/listen.  We'll add an extra
connect(2) attempt to check if the starter lost the race.

Without this change, a stress script like the following could
easily cause problems:

lei q -o ~/tmp/a foo ... &
lei q -o ~/tmp/b bar ... &
lei q -o ~/tmp/c quux ... &
lei q -o ~/tmp/d baz ... &

lei: start_pager: drop COLUMNS default

It shouldn't be needed since none of our subcommands will care
or attempt to format output.  Once "lei show" is implemented,
we'll run "git show" directly on the result.

ds: improve add_timer usability

Packing args into an arrayref is awkward and we may be using
this API more in lei.

tests: favor IPv6

IPv4 gets plenty of real-world coverage, and apparently there's
Debian buildd hosts which lack IPv4(*).  So ensure everything
can work on IPv6 and not cause problems for odd setups.

(*) https://bugs.debian.org/979432

lei q: support --alert=CMD for early MUA users

For --mua users writing to lock-free -o MFOLDER destinations;
we'll keep -WINCH and send an ASCII terminal bell when results
are complete.  This is intended to let early MUA spawners know
when lei2mail is done writing results.

We'll also support running arbitrary commands.  It may be used
to run play(1) (from SoX), handle pipelines+redirects
(e.g. "/bin/sh -c 'echo search done | wall'") or other commands.

lei q: SIGWINCH process group with the terminal

While using utime on the destination Maildir is enough for mutt
to eventually notice new mail, "eventually" isn't good enough.

Send a SIGWINCH to wake mutt (and likely other MUAs)
immediately.  This is more portable than relying on MUAs to
support inotify or EVFILT_VNODE.

lei_xsearch: quiet Eml warnings from remote mboxrds

This will probably cover full Atom/HTML feed generation or any
outputs which are order-dependent, but those aren't prioritized
at the moment.

lei q: improve remote mboxrd UX + MUA

For early MUA spawners using lock-free outputs, we we need to
on the startq pipe to silence progress reporting.  For
--augment users, we can start the MUA even earlier by
creating Maildirs in the pre-augment phase.

To improve progress reporting for non-MUA (or late-MUA)
spawners, we'll no longer blindly append "--compressed" to the
curl(1) command when POST-ing for the gzipped mboxrd.
Furthermore, we'll overload stringify ('""') in LeiCurl to
ensure the empty -d '' string shows up properly.

v2: fix startq waiting with --threads
    mset_progress is never shown with early MUA spawning,
    The plan is to still show progress when augmenting and
    deduping.  This fixes all local search cases.
    A leftover debug bit is dropped, too

INSTALL: depend on Text::ParseWords

It's been distributed with Perl since 1994, and we use it for
both -imapd and lei.  It's split out as a separate package in
CentOS 7.x, so we'll depend on it to avoid surprising users
of RPM-based distros.

lei q: fix arbitrary --mua command handling

Perl doesn't seem to warn for shadowed variables, here :x

lei import: support Maildirs

It seems to be working trivially, though I'm probably
going to split out Maildir reading into a separate
package rather than using LeiToMail.

httpd/async: avoid unnecessary on-stack delete

While this doesn't fix a known problem, this was a risky
construct in case somebody uses confess/longmess inside
the user-supplied callback.

cf. commit 0795b0906cc81f40
    ("ds: guard against stack-not-refcounted quirk of Perl 5")

imap: avoid unnecessary on-stack delete

None of the Content-Type attributes are long-lived
(and unlikely to be memory intensive).  While these
callsites won't trigger $DB::args segfaults via
confess or longmess, it'll make future code audits
easier.

cf. commit 0795b0906cc81f40
    ("ds: guard against stack-not-refcounted quirk of Perl 5")

lei: replace --thread with --threads

Nobody is expected to use long options, but for consistency
with mairix(1), we'll use the pluralized option throughout
(including existing PublicInbox::{Search,SearchView}).

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

lei: remove --mua-cmd alias for --mua

While "mua-cmd" may be more accurate, nobody is expected
to type 4 extra characters.  It's a needless ambiguity
with no precedence or prior art to follow.

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

lei: more consistent IPC exit and error handling

We're able to propagate $? from wq_workers in a consistent
manner, now.

ipc: wq_do => wq_io_do

We will have a ->wq_do that doesn't pass FDs for I/O.

Revert "ipc: add support for asynchronous callbacks"

This reverts commit a7e6a8cd68fb6d700337d8dbc7ee2c65ff3d2fc1.

It turns out to be unworkable in the face of multiple producer
processes, since the lock we make has no effect when calculating
pipe capacity.

tests: guard setup_public_inboxes for SQLite and Xapian

This will need some work to before it's generally applicable
to the rest of our code base.

xapcmd: avoid potential die surprise in children

Make some notes about sub usage, this may be converted
to use workqueues once the cmsg dependency is dropped.

Makefile.PL: depend on IO::Uncompress::Gunzip

It's another part of the Perl standard library and rarely
split out from Perl (though we can't depend on that fact).

ipc: trim down the Storable checks

It's distributed with Perl and our Makefile.PL even declares a
dependency on it, just like Encode and all the Compress::*
stuff.

ipc: do not die inside wq_worker child process

die() in a child zips up the stack into the parent, which is
undesirable behavior.  We're going to exit anyways, just warn
and let exit(1) happen due to $@ being set.

spawn_pp: die more consistently in child

The default $SIG{__DIE__} inside a forked child doesn't actually
do what we want it to do.  We don't want it to zip up the stack
the parent used, but instead want to exit the child process
after warning.

lei add-external: handle interrupts with --mirror

This also updates lei_xsearch to follow the same pattern for
stopping curl(1) and tail(1) processes it spawns.

spawn: pi_fork_exec: support "pgid"

We'll be using this to allow the "git clone" process hierarchy
to be killed via Ctrl-C.  This also fixes a long-standing bug
in error reporting for the Inline::C version, because we're
actually testing for errors, now!

n.b. strlen(3) is officially async-signal-safe as of
POSIX.1-2016, but I can't think of a reason any previous
implementation prior to that wouldn't be.

spawn: pi_fork_exec: restore parent sigmask in child

We continue to unblock SIGCHLD unconditionally, but also
any signals not blocked by the parent (wq_worker).

This will allow Ctrl-C (SIGINT) to stop "git clone" and allow
git-clone cleanup to be performed and other long-running
processes when pi_fork_exec supports setpgid(2).  This won't
affect existing daemons on systems with signalfd(2) or
EVFILT_SIGNAL at all, since those run with signals blocked
anyways.

lei: remove short switch support for curl(1) options

In particular, -U and -u switches may conflict with diff(1)
options we may need for "lei show" which will use solver
remotely or locally.

lei_curl: replace -K/--config with --curl-config

Seeing --config in the command-line for lei may mislead users
into thinking we support config file overrides that way.  Rename
the option to --curl-config and drop the short switch for now.

lei add-external: reject index and remote opts w/o mirror

Option combinations which make no sense should fail
to prevent misunderstandings and avoid surprises.

lei help: split out into separate file

We'll reword and improve formatting with non-breaking spaces
("\xa0") which is only replaced with SP after wrapping.

Some terminology is shortened (e.g. "URL_OR_PATHNAME" => "LOCATION")
to improve formatting.

This also enables completion for -h/--help and lets us
prioritize favored switch names while attempting to
satisfy users relying on muscle memory from other tools.

lei: add-external --mirror support

This can be useful for users who want to clone and
mirror an existing public-inbox.  This doesn't have
update support, yet, so users will need to run
"git fetch && public-inbox-index" for now.

script/lei: avoid waitpid(-1, ...) to keep tests fast

We only spawn one process to be reaped at the moment.  tests
will run the contents of script/* in the same process if
possible, so any test scripts which spawn -httpd or other
read-only can cause us to stall with waitpid(-1, ...)

treewide: replace confess with croak

The PublicInbox::Eml (and previously Email::MIME) use of confess
was the primary (or only) culprit behind the lei2mail segfaults
fixed by commit 0795b0906cc81f40.
("ds: guard against stack-not-refcounted quirk of Perl 5").

We never care about a backtrace when dealing with Eml objects
anyways, so it was just a worthless waste of CPU cycles.

We can also drop confess in a few other places.  Since we only
use Perl and Inline::C, users will never be without source
and can replace s/croak/Carp::confess/ on a per-callsite basis
to help report problems.

It's also possible to use PERL5OPT=-MCarp=verbose in the
environment though still potentially risky.

Link: https://public-inbox.org/meta/20210201082833.3293-1-e@80x24.org/

tests: split out lei-daemon.t from lei.t

This makes it easier for hackers to find daemon-specific
tests and forces us to always test both daemon and
oneshot mode.

t/tests: split out setup_public_inboxes sub

We'll probably use this in many more existing places
and likely change non-lei tests to use it.

t/lei-externals: split out into separate test

This is still overloaded with "lei q" stuff, but that's
somewhat inevitable.

tests: add test_lei wrapper, split out t/lei-import.t

This will make it easier to maintain and test lei going forward,
we need to be testing against existing read-only daemons.  We'll
also save ourselves some boilerplate by exporting all the
Test::More methods directly in TestCommon

We'll start using this by splitting out the latest "lei import"
tests into its own file.

lei_query: trim curl options

Get rid of short options which will or may conflict with
some of our own.  We may switch over to "git -c http.*"
options since we need to run "git clone" and "git fetch"
anyways.

init: lowercase -j for --jobs

This is taken from common implementations of make(1)
and only affected people using the command-line help
output.

lei: abort lei_import worker on client abort

We'll stuff all the common wq key fields into the
@WQ_KEYS array so it's easier to keep track of what
to kill or reap.

lei: fix completion of --no-kw / --no-keywords

We did not complete --no-* flags properly when multiple options
are allowed.

lei: favor "keywords" over "flags", test --no-kw

JMAP brain says "keywords", IMAP brain says "flags";
JMAP brain wins today.

Since "keywords" is a bit long, support "kw" as a shortcut since
there's no conflict and "kw:" will be our search prefix for
looking up messages by keyword.

lei_overview: drop unnecessary autoflush call

This was actually causing xt/lei-sigpipe.t failures,
presumably due to reused/recycled workers with many
externals.

httpd/async: set O_NONBLOCK correctly

While Perl tie is nice for some things, getting
IO::Handle->blocking to work transparently with it doesn't
seem possible at the moment.

Add some examples in t/spawn.t for future hackers.

Fixes: 22e51bd9da476fa9 ("qspawn: switch to ProcessPipe via popen_rd")

lei import: initial implementation

Only tested with .eml files so far, but Maildir + IMAP
will be supported.

lei_xsearch: drop unused imports

Reaping is handled by the parent PublicInbox::IPC, and we
have no business using PublicInbox::Import since LeiXSearch
won't write to git directly (it will write via LeiStore).

lei_query: remove uneeded dwaitpid import

All process management is handled elsewhere.

lei q: eliminate $not_done temporary git dir hack

Another step towards simplifying lei internals.

None of our current uses of ->wq_do involve FD passing, and the
plan is only rely on FD passing between lei-daemon and lei(1).
Internally, it ought to be possible for lei-daemon internal bits
to be ordered properly to not need FD passing.

eml: handle warning ignores for lei

There's nothing we can do about bad emails in our search
results, so quiet things down and don't fight the MUA for
the terminal.

lei q: reinstate early MUA spawn for Maildir

Once all files are written, we can use utime() to poke Maildirs
to wake up MUAs that fail to account for nanosecond timestamps
resolution.

lei q: only start pager if output is to stdout

No need to be starting a pager if we're writing to a regular file.

lei q: reorder internals to reduce FD passing

While FD passing is critical for script/lei <=> lei-daemon,
lei-daemon doesn't need to use it internally if FDs are
created in the proper order before forking.

ipc: localize fields assignment

We don't want circular references giving surprising behavior
during worker exit.

lei q: delay worker spawn

Now that --stdin support is sorted, we can delay spawning
workers until we know the query is ready-to-run.

t/lei: skip "lei q" tests on missing dependencies

... for now.  It's probably possible to just use send()
recv() without CMSG_* eventually.

pkt_op: do not exit subroutine via "next"

"next" apparently doesn't work in "do {} while" loops,
so just use "while" as it makes no difference, here.

wwwaltid: add missing word to instructions

www: call curl with -d '' in the altid instructions

Nginx doesn't appear to be happy with just -XPOST, so use -d '' to
avoid potential confusion about why the instructions aren't working.

cf. commit 533e1234bc03a1ca8754d249aa8c2ce157e26780
    (lei_xsearch: use curl -d '' for nginx compatibility, 2021-01-24)

tests: guard against missing DBD::SQLite

The features we use for SharedKV could probably be implemented
with GDBM_File or SDBM_File, but that doesn't seem worth it at
the moment since we depend on SQLite elsewhere.

doc: update dependencies (+Storable, Data::Dumper)

The new IPC stuff doesn't work without Storable or Sereal.
Storable is part of the standard library since Perl 5.8, so
we'll put a hard dependency on it for distros that package
it separately.

Data::Dumper is also part of the standard library, and
PublicInbox::MboxReader uses it, and it's frequently useful
during development.

We'll also trim down INSTALL for standard library modules so
it's hopefully less daunting for new users.

Development dependencies are noted in HACKING, now.

Email::MIME is only used for maintainer tests, so it's only
documented in HACKING.

spawn: merge common C code together

There'll probably be more things which work on both GNU and
*BSD systems which we don't need separate strings for.

HACKING: use "just-ahead-of-time" to describe Inline::C

Inline::C works during module load time, so "just-ahead-of-time"
is a better description of it than "just-in-time".  I don't
think "JAOT" is a well-known enough acronym, so it's worth
spelling it out.

lei q: support reading queries from stdin

This will be useful on shared machines when a user doesn't want
search queries visible to other users looking at the ps(1)
output or similar.

lei: use sleep(1) loop for infinite sleep

Perl may internally race and miss signals due to a lack of
self-pipe / eventfd / signalfd / EVFILT_SIGNAL usage.  While our
event loop paths avoid these problems by using signalfd or
EVFILT_SIGNAL, thse sleep() calls are not within the event loop.

lei add-external: completion for existing URL basenames

Given the presence of one external on a certain host or prefix
path, it's logical other inboxes would share a common prefix.
For bash users, attempt to complete that using the "-o nospace"
option of bash

lei: help starts pager

Because some commands have many options which take up
multiple screens.

lei: complete basenames for include|exclude|only

This will make it even easier for RSI-afflicted users to use,
since many externals may share a common prefix.

lei q: -I/--exclude/--only support globs and basenames

We can do basename matching when it's unambiguous.  Since '*?[]'
characters are rare in URLs and pathnames, we'll do glob
matching by default to support a (curl-inspired) --globoff/-g
option to disable globbing.

And fix --exclude while we're at it

lei: propagate curl errors, improve internal consistency

IO::Uncompress::Gunzip seems to be losing $? when closing
PublicInbox::ProcessPipe.  To workaround this, do a synchronous
waitpid ourselves to force proper $? reporting update tests to
use the new --only feature for testing invalid URLs.

This improves internal code consistency by having {pkt_op}
parse the same ASCII-only protocol script/lei understands.

We no longer pass {sock} to worker processes at all,
further reducing FD pressure on per-user limits.

lei: err: avoid uninitialized variable warnings