lei_mail_sync: for bidirectional keyword sync

We'll be using the new class to efficiently propagate keyword
changes from lei/store back to Maildir or IMAP folders.

doc: lei_design_notes: add a bit on WAL usage

net_reader: imap_each: add UIDVALIDITY to URL arg

This will allow the callback to reliably maintain OID <=> UID
mappings between lei/store and the IMAP folder.

URIimap: support ->uidvalidity and ->iuid

These will be useful for keyword synchronization, and perhaps
importing a single IMAP message with ->iuid.

t/lei_to_mail: split "lei import" test $HOME directory

"lei import" behavior will may change w.r.t. keyword
handling.  Use separate $HOME between different test_lei
to ensure isolation between the tests.

lei_input: drop outdated comment w.r.t. compression

Followup-to: 49b036771ef3bf45 ("lei_input: support compressed mboxes")

doc: INSTALL: add Guix to distribution list

public-inbox has been available in Guix since 2019.

lei import: support adding keywords and labels on import

This saves some work and makes it easier to set volatile
metadata on a message at import time.

lei_to_mail: cwd-agnostic Maildir wakeup

Since we don't have *at() syscalls readily available to us,
lei-daemon may call ->poke_dst in the wrong relative directory.
Despite not having *at() syscalls, we can still capture the
"$MAILDIR/cur" directory handle at pre_augment time so we can
reliably call futimes(2) on it using the `utime' perlop.

net_reader: restart on first UID when UIDVALIDITY changes

In other words, treat the same IMAP folder with a different
UIDVALIDITY as a completely different folder.  If the UIDVALIDITY
changes, we can start from UID=1 without falling behind or
losing data.  If the UIDVALIDITY gets reset to a previously
known-good message, we can still resume where we left off
before the first UIDVALIDITY change.

This affects public-inbox-watch and "lei import"

One potential downside of this is for rare altid users, but
that's mainly intended for NNTP article numbers which are/were
often publicized; not IMAP UIDs which are rarely publicized.

The other potential downside is bandwidth waste in in the rare
case UIDVALIDITY changes while IMAP folder contents remain
unchanged.  There's no extra storage used due to existing
(v1|v2|lei/store) deduplication mechanisms.

Before this change, we were matching offlineimap behavior and
stopped synching an IMAP folder when its UIDVALIDITY changed.
offlineimap behavior made sense for IMAP <=> Maildir
synchronization since Maildirs had no sense of UIDVALIDITY and
could only rely on name mapping.

doc: INSTALL: update with more distro info, symlink-install

lei up: support symlinked pathnames

On my default FreeBSD 11.x system, "/home" is a symlink to
"/usr/home", which causes "lei up" path resolution to fail when
I use outputs in $HOME.  Fall back to a slow path of globbing
and matching pathnames based on st_ino+st_dev.

lei: saved searches support --dedupe=<mid|oid>

This is less surprising in case users are used to using --dedupe=
without --save.

lei: XDG_RUNTIME_DIR=/dev/null disables daemon mode

We'll support this mode of operation for now to quiet down
testing of oneshot mode where the daemon doesn't persist.

lei import|convert: drop --no-kw aliases

Supporting --no-keywords and --no-flags aliases is harmful
if users end up assuming "keywords:" and "flags:" are valid
search prefixes (they're not).

lei import: --incremental default for NNTP and IMAP

No point in burning through bandwidth to import stuff we already
saw.  All this logic is shared with -watch but uses a different
pathname for lei since it's tied to lei/store (and not a
public-inbox).

imap_tracker: prepare for use with lei

We'll support nodatacow as we do in other SQLite DBs

lei: flesh out `forwarded' kw support for Maildir and IMAP

Maildir and IMAP can both handle `forwarded'.  Ensure we don't
lose `forwarded' when reading from stores which do not support
it, but ensure we can set it when reading from IMAP and Maildir
stores.

doc: add lei_design_notes.txt and lei-store-format(5)

lei itself is a somewhat weird design, but lei/store is
a fairly normal hybrid of extindex with v2-style storage.

lei: share common *done_wait callbacks

Code is the enemy, and there's no need to duplicate things, here.
There may be further opportunities along these lines to further
deduplicate things...

t/lei-daemon: skip inaccessible socket test as root

"chmod 0000" on a Unix socket can't stop root from connecting to it;
so just skip the test for rare cases when testing as root.

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

lei_query: avoid POSIX::lround for older Perls

POSIX.pm shipped with Perl 5.16.3 did not support lround,
at least.  So just rely on built-in core functions.

test_common: fix xbail for Perl 5.16

Our use of `ref' was triggering ambiguity in older versions of
the Perl parser.

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

lei edit-search: command to tweak search parameters

This may be useful for users to tweak search parameters.
This command is also the reason lei.saved-search is a git-config
file rather than JSON.

lei forget-search: new command to forget saved searches

Readers may lose interest in subscription topics.  This lets
them avoid clutter by forgetting a saved search.

This does not and will not destroy the contents of an --output
mailbox.  In other words, this is similar to unsubscribing
from an Atom/RSS feed or NNTP group.

I've also decided we won't support 'mv-search', since it'll
probably be rarely used and "lei convert" can be used, instead.

lei up: support --all=local

Users may wish to update several saved searches at once.  We can
support parallel updates in lei-daemon so users won't have to do
it themselves via xargs or similar.

Supporting IMAP outputs would be significantly more involved
since we'd have to pre-authenticate for every single IMAP
output before entering the redispatch loop.

lei up: more error checking for config loading

We'll support editing the saved search config file, so user
errors may happen and we need to throw sensible errors in that
case.

config: favor ->get_all when possible

It's slightly less code.

lei up: fix help output and ARGV handling

We don't support changing search terms once "lei q --save" is
used.

lei-sigpipe: update and move test from xt => t

We have "lei import" and better test infrastructure for lei,
now, so we can more easily test SIGPIPE without relying on
an already-configured instance.

lei q: --save and --augment may be combined

This necessitated fixing pause_dedupe to release the handle
used by ->lock_for_scope_fast, but otherwise no changes to
the LeiToMail package.

lei_saved_search: split "lei q --save" and "lei up" init paths

They're more different than alike, and having two separate
methods seems less confusing to me.

config: git_config_dump blesses

I don't know if it's worth it to sub (or super)class
PublicInbox::Config into something more generic for
lei, but this change simplifies a good chunk of lei
code that reuses the public-inbox config parsing.

lei_saved_search: avoid needless var shadowing

While perl (5.28) doesn't complain about this, it's confusing to
my easily-confused mind.

lei q: implement import-before default for --save

This makes "lei q --save" as safe as "lei q" to prevent against
accidental data loss when clobbering an existing output,

lei: support unlinked/missing saved searches

It's conceivable a user will want to erase all previous
results but still rerun/refresh a search to get new results.
We probably won't support prune functionality, here, and
instead require explicit removal of saved searches.

doc config: mention obfuscation-related options

Obfuscation has been available since v1.0.0.  Help those that want to
use the feature figure out how.

lei ls-search: command to list saved searches

Going forward, we'll probably support JSON for all the "ls-*"
subcommands.  This also provides the basis for "lei up" shell
completion.

avoid wrong/needless squote_maybe shortcuts

We'll keep it in PublicInbox::Config for now, since I'm not
sure if there's a better place to put it.

lei_saved_search: avoid git-config

Repeated vfork+execv costing us around 20ms on t/lei-q-save.t,
so just learn to quote git-config values and write directly to
the config file.

lei up: further improve Maildir canonicalization

We want to be able to use "lei up ." when inside a Maildir.
We'll also relax Maildir/mbox basenames to be any non-'/'
character after converting relative paths to absolute.  The
old restriction on allowed characters was unnecessary and made
it impossible to reliably map "." when used as the sole argument
for "lei up".

lei up: fix canonicalization of Maildirs

We always represent --output destination directories with a
trailing slash to disambiguate directories from mbox filenames.
Therefore, we must use the trailing slash when mapping the
destination beck from the lei/saved-search/* directory.

"lei up" now relies exclusively on the users --output pathname
or URL for updates.  This ought to be less confusing since
pathnames in ~/.local/store/lei/saved-searches aren't ideal.

lei q: fix MUA spawn after reading query from stdin

Since "lei q" may read queries from stdin, we must reconnect a
known terminal before spawning terminal MUAs.  Attempt to use
stdout as stdin for this purpose, since terminal MUAs tend to
expect stdout to be a terminal.

Reported-By: Kyle Meyer <kyle@kyleam.com>
Link: https://public-inbox.org/meta/87v98klxg3.fsf@kyleam.com/

lei q --save: clobber config file on repeats

A user may wish to clobber/refine existing search parameters
by issuing "lei q --save" again.  Support that by overwriting
the lei.saved-search state file entirely.

We continue to preserve over.sqlite3 for deduplication purposes.

This way, we don't get something redundant like:

[lei]
q = term1
q = term2
q = term1
q = term2
q = term3

...whenever a user wants to refine their search.  Instead,
we'll just have:

[lei]
q = term1
q = term2
q = term3

On the second go.

lei q --save: avoid lei.q.format

It is redundant since we stuff everything into the lei.q.output
config key.

lei up: support output destination as arg

Specifying a directory in ~/.local/share/lei/saved-searches/
is painful, so support (and start encouraging) the use of
the output.

lei: fix rel2abs

We don't want pathnames with "GLOB(0xADD12355)" in them.

lei_query: fix relative path handling on --stdin

Since --stdin could be waiting on user keyboard input or
something else slow, we handle it in the event loop.  That
means other commands can change the working directory of
lei-daemon while a query is being trickled to us via stdin.

Rearranging query handling internals to delay opening the
--output destination in commit 26e0fe73de93f451 meant
another command could throw off our --output pathname if
it is relative.

Fixes: 26e0fe73de93f451 ("lei_query: rearrange internals to capture query early")

test_common: handle '-C' (chdir) spawn option properly

We use it in t/lei-q-save.t, and were inadvertently writing
to the worktree.

v2: fix -C $DIR with TEST_RUN_MODE=0

lei_to_mail: cast to URIimap object early

NetReader->add_url supports URI-like objects, now.  We'll be
relying on the canonicalization for LeiSavedSearch.

lei: saved searches keyed only by path/URL and format

We want users to be able to edit and refine the query over
time while using the same output destination.

lei: expose share_path as a method

Since saved-searches aren't a part of lei/store, nor
could it be considered cache data... (or can it? it
is discardable, after all).

lei q: --save preserves relative time queries

Somebody may want a saved search which consistently asks for
messages within a rolling time period window.  In other words,
we want to support using "lei q --save dt:last.week.." and keeps
the "dt:last.week.." relative to whenever "lei up" is run.  This
ensures relative date-time specifications get used in the future
rather than converting into an absolute date-time from the
initial "lei q" invocation.

search: expand "d:" to "dt:" for precision with approxidate

If a user specifies "d:" with a higher precision than it was
traditionally able to handle, switch transparently to "dt:".
This lowers the learning curve and improves DWIM-ness.

v2: fix "d:YYYYMMDD..$NEEDS_APPROXIDATE" case

doc: technical/whyperl: update w/ (good) news from PSC

It looks like stability and compatibility will prevail, after all.

lei: add "lei up" to complement "lei q --save"

The command isn't finalized, yet, but it's intended to update
an existing saved search.

lei q: start wiring up saved search

This will have a over.sqlite3 for content-based deduplication.
It may exhibit ibxish methods, so serving a read-only (or even
R/W) IMAP or instance or displaying HTML isn't outside the realm
of possibility.

lei_query: rearrange internals to capture query early

To support saved search, we need the query string available to
us before we setup LeiDedupe via (LeiOverview || LeiToMail).

lei_dedupe: adjust to prepare for saved searches

LeiSavedSearch will use a LeiDedupe-like internal API,
so we won't have to make as many changes to callsites
between saved and unsaved searches.

lei_xsearch: use per-external queries when not sorting

We only need the combined mset query when we care about sort
order.  When writing to --output destinations intended for MUA
consumption, sort order is irrelevant as MUAs are expected to
offer their own sorting, so run queries to each external in
parallel.

This prepares us for docid-sort-based saved search support.

It will also become faster than the combined mset query for
users with many externals due to current Xapian exhibiting poor
performance with many shards (the same reason -extindex exists)

lei blob: quiet "git rev-parse --git-dir" stderr w/o --cwd

This seemed to be causing occasional "make check-run" failures
with errors bleeding into other tests.

www: do not obfuscate addresses in URLs

As they are likely Message-IDs.   If an email address ends up in
a URL, then it's likely public, so there's even less reason to
obfuscate that particular address.

[km: add xt/perf-obfuscate.t]
[ew: modernize perf test (5.10.1), use diag instead of print]

This version of the patch avoids the massive slowdown noted by Kyle in
<https://public-inbox.org/meta/87wnt9or6t.fsf@kyleam.com/>.
Performance remains roughly the same, if not slightly faster
(which may be due to me testing this on a busy server).  Results
from xt/perf-obfuscate.t against 6078 messages on a local mirror
of <https://public-inbox.org/meta/>:

before: 6.67 usr + 0.04 sys = 6.71 CPU
 after: 6.64 usr + 0.04 sys = 6.68 CPU

Reported-by: Kyle Meyer <kyle@kyleam.com>
Helped-by: Kyle Meyer <kyle@kyleam.com>
Link: https://public-inbox.org/meta/87a6q8p5qa.fsf@kyleam.com/

import: convert init.defaultBranch to fully qualified ref

init.defaultBranch expects a branch name, not a fully qualified ref.
git-init prepends "refs/heads/" automatically and unconditionally.

PublicInbox::Import::default_branch, however, incorrectly passes on
the init.defaultBranch value as is, leading to it being used in spots
where a fully qualified ref is required.  For example, with an
init.defaultBranch value of "master", public-inbox-index for a v2
repository would lead to an all.git repository where HEAD's content is
"ref: master" instead of "ref: refs/heads/master".

Prepend "refs/heads/" to the incoming init.defaultBranch value.

Fixes: 7c2f36de2fb49dd7 (import: respect init.defaultBranch)

lei_store: use getpwuid and hostname for ident

It's nicer in case a user transfers lei/store across machines
and wants a way to track when/where they imported something.

script/lei: waitpid for git-credential and pager

We need to ensure we reap things we spawn.

lei q: fix auth IMAP --output with remote mboxrd

IMAP authentication info is only shared amongst lei2mail workers,
so we must ensure all IMAP writes go through lei2mail workers
even if we don't have to access the mail through git.

This allows us to decouple the latency of the remote mboxrd from
the latency of the IMAP --output at the expense of extra IPC
overhead within our own processes.

lei_to_mail: improve comments and reduce LoC

We don't need to waste LoC on corner cases, single-use internal
subs, or restoring SIG{__WARN__} when a process exits.  All that
extra code contributes to memory use and startup time, especially
for users who can't use FD passing.

lei: maildir: move shard support to MdirReader

We'll eventually want lei_input users like "lei import" and
"lei tag" to support parallel reads.

lei_tag: fix comments w.r.t support levels

RFC 8621 registers $flagged, $answered, $seen, $draft which
map to IMAP, Maildir, and mbox Status/X-Status flags.

$forwarded is noted in JMAP, but only Maildir and and the
"Lemonade" IMAP profile (RFC 5550) support it

lei_to_mail: trim down imports

We don't need to import so many things.  None of the Errno
constants are in common paths so unlikely to benefit from
constant folding.

lei_search: ignore Resent-Message-ID for indexing

It currently conflicts with the way OverIdx and SearchIdx
index messages, ultimately leading to violating a NOT NULL
constraint on id2num.id in over.sqlite3.

We may allow searching Resent-* fields separately, though I'm
not sure how useful it'll be.

lei/store: (more) synchronous non-fatal error output

Since every command that writes to lei/store calls ->done
to commit its output, we can rely on that to return a
pathname for a readable file with errors in it.

Errors can still get crossed up if multiple lei commands
are writing to the store at once, but reduces the delay
in seeing them and ensures it won't get seen when somebody
is attempting to use shell completion.

lei: improve handling of Message-ID-less draft messages

We need a stable fallback time for digest2mid in the presence
of messages without Received/Date headers.  Furthermore, we
must avoid using uninitialized smsg->{mid} when parsing
References for draft replies.

lei tag: note message mismatches on failure

Just exiting with a failure code and no error message is
confusing :x

test_common: lei_ok: improve diagnostics

$? is useful, as is labeling lei_err since I'm easily-confused :x

lei_store: update alternates on new epoch

We'll just let the ExtSearchIdx code handle this uncommon case
by doing a full commit.

lei: allow progress to non-TTY after MUA spawn

Sometimes I want to save debug info to a file or pipe even when
spawning an MUA.

lei q: don't show remote progress if MUA is running

Remote results can safely use the same mset progress reporting
as local results, despite not knowing the size of the result
set.  We're assuming terminal MUAs, for now.

xt/lei-auth-fail: test more failure cases

Because failures are often overlooked, unfortunately.

net_reader: fix read-only "lei convert" auth failures

"convert" is actually a bit more complicated than "lei import"
since it may need auth for either input or output.

lei_auth: rename {net_merge} to {net_merge_continue}

No reason for the hash key to differ from the subroutine
name, here.

lei tag: fix tagging of IMAP inputs

We need net_merge_all and to lock the number of worker jobs.
Parallel inputs are not supported, yet (is it needed?, I don't
expect this to be used for multiple files very often...).

lei q: ensure wq workers shutdown on IMAP auth failures

Leaving workers running on after auth failures is bad and messy,
cleanup our process management to have consistent worker
teardowns.  Improve error reporting, too, instead of letting
Mail::IMAPClient->exists fail due to undef.

URInntps: add URI 5.08 release note

I wanted to say 2031, but that's probably too aggressive a
removal timeline.

lei: fix git-credential handling

I completely forgot about git-credential prompting when
making lei background the client process for MUA.

Now it backgrounds itself only for the MUA when no FDs are
passed, since the MUA is the final command run.  Otherwise, it
relies on FD passing as before.

Fixes: c790a75439f3a1db ("script/lei: background ourselves on MUA/pager exec")

lei: maildir: handle "forwarded" keyword as "P"

mbox and IMAP seem to have no way of describing this keyword.
but Maildir does with the "P" flagged (for "passed").

lei_store: quiet down per-message related warnings

It's needless noise when doing augment and output preparation
and shows up way too late and out-of-band with lei-daemon.

lei_store: quiet down git user info being unset

lei_store contents aren't intended to become public, so there's
no point in nagging users for their email address for git
committer information like git does.

lei_store: set_xvmd: don't add if no vmd at all

There's no point in adding vmd information for an external
message if it was never stored and there's no vmd at all.

We also don't need to check _docids_for for similar messages,
either, since we always check lse->kw_changed, first.

lei q: reduce lei/store work for kw changes to stored mail

We can tweak lse->kw_changed to return docids and reduce IPC
traffic and reduce work the lei/store worker needs to do.

lei_query: remove unnecessary V2Writable require

AFAIK that was only used for nproc detection, and nproc
is handled by PublicInbox::IPC, nowadays.

lei sucks: sub-command to aid bug reporting

It's a bit of an Easter egg, though it's not possible to hide those
in Free Software...  Anyways, it doesn't cost us an entry in %CMD
of LEI.pm and anybody frustrated enough with lei just might type
"lei sucks" on the command-line :>

build: generate PublicInbox.pm with $VERSION

Thanks to git-describe, we can generate and update this
file to aid users in bug reporting.

script/lei: background ourselves on MUA/pager exec

This ought to give the MUA or pager exclusive access to the
controlling terminal.  The downside is we can only exec the
pager or MUA once per invocation, but I can't imagine a valid
case for running those things multiple times, either.

Note: I'm no expert when it comes to terminal control matters,
but this allows Ctrl-Z-ed mutt instance to come back and is
a nice code reduction, as well.

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.