[PATCH 0/2] POP3 docs + tests for users and BOFHs

[PATCH 0/2] POP3 docs + tests for users and BOFHs

[Eric Wong]

Deployed to: https://yhbt.net/lore/lkml/_/text/help/
(also testing some -netd stuff which ain't quite ready, yet...)

Eric Wong (2):
  doc|www: flesh out POP3 documentation for servers and users
  tests: maintainer test for using mpop

 Documentation/public-inbox-config.pod |  7 +++
 MANIFEST                              |  1 +
 lib/PublicInbox/Inbox.pm              | 30 +++++++++--
 lib/PublicInbox/WwwText.pm            | 26 ++++++---
 xt/pop3d-mpop.t                       | 77 +++++++++++++++++++++++++++
 5 files changed, 131 insertions(+), 10 deletions(-)
 create mode 100644 xt/pop3d-mpop.t

[PATCH 1/2] doc|www: flesh out POP3 documentation for servers and users

[Eric Wong]

Hopefully it makes sense to new users deploying or using POP3...
---
 Documentation/public-inbox-config.pod |  7 +++++++
 lib/PublicInbox/Inbox.pm              | 30 +++++++++++++++++++++++----
 lib/PublicInbox/WwwText.pm            | 26 +++++++++++++++++------
 3 files changed, 53 insertions(+), 10 deletions(-)

diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod
index ed99b188..d8504e61 100644
--- a/Documentation/public-inbox-config.pod
+++ b/Documentation/public-inbox-config.pod
@@ -228,6 +228,13 @@ L<public-inbox-nntpd(1)> instance.
 
 Default: none
 
+=item publicinbox.pop3server
+
+Same as C<publicinbox.imapserver>, but for the hostname(s) of the
+L<public-inbox-pop3d(1)> instance.
+
+Default: none
+
 =item publicinbox.pop3state
 
 See L<public-inbox-pop3d(1)/publicinbox.pop3state>
diff --git a/lib/PublicInbox/Inbox.pm b/lib/PublicInbox/Inbox.pm
index da81fb67..0ad68810 100644
--- a/lib/PublicInbox/Inbox.pm
+++ b/lib/PublicInbox/Inbox.pm
@@ -28,7 +28,7 @@ sub do_cleanup {
 		check_inodes($ibx);
 	} else {
 		delete(@$ibx{qw(over mm description cloneurl
-				-imap_url -nntp_url)});
+				-imap_url -nntp_url -pop3_url)});
 	}
 	my $srch = $ibx->{search} // $ibx;
 	delete @$srch{qw(xdb qp)};
@@ -230,9 +230,9 @@ sub base_url {
 	$url;
 }
 
-# imapserver, nntpserver, and pop3server configs are used here:
+# imapserver, nntpserver configs are used here:
 sub _x_url ($$$) {
-	my ($self, $x, $ctx) = @_; # $x is "imap", "nntp", or "pop3"
+	my ($self, $x, $ctx) = @_; # $x is "imap" or "nntp"
 	# no checking for nntp_usable here, we can point entirely
 	# to non-local servers or users run by a different user
 	my $ns = $self->{"${x}server"} //
@@ -276,7 +276,29 @@ EOM
 # my ($self, $ctx) = @_;
 sub imap_url { $_[0]->{-imap_url} //= _x_url($_[0], 'imap', $_[1]) }
 sub nntp_url { $_[0]->{-nntp_url} //= _x_url($_[0], 'nntp', $_[1]) }
-sub pop3_url { $_[0]->{-pop3_url} //= _x_url($_[0], 'pop3', $_[1]) }
+
+sub pop3_url {
+	my ($self, $ctx) = @_;
+	$self->{-pop3_url} //= do {
+		my $ps = $self->{'pop3server'} //
+		       $ctx->{www}->{pi_cfg}->get_all('publicinbox.pop3server');
+		my $group = $self->{newsgroup};
+		my @urls;
+		($ps && $group) and
+			@urls = map { m!\Apops?://! ? $_ : "pop://$_" } @$ps;
+		if (my $mi = $self->{'pop3mirror'}) {
+			my @m = map { m!\Apops?://! ? $_ : "pop://$_" } @$mi;
+			my %seen; # List::Util::uniq requires Perl 5.26+
+			@urls = grep { !$seen{$_}++ } (@urls, @m);
+		}
+		my $n = 0;
+		for (@urls) { $n += s!/+\z!! }
+		warn <<EOM if $n;
+W: pop3server and/or pop3mirror URLs should not end with trailing slash `/'
+EOM
+		\@urls;
+	}
+}
 
 sub nntp_usable {
 	my ($self) = @_;
diff --git a/lib/PublicInbox/WwwText.pm b/lib/PublicInbox/WwwText.pm
index 2b4e69fe..2937c333 100644
--- a/lib/PublicInbox/WwwText.pm
+++ b/lib/PublicInbox/WwwText.pm
@@ -1,4 +1,4 @@
-# Copyright (C) 2016-2021 all contributors <meta@public-inbox.org>
+# Copyright (C) all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
 # used for displaying help texts and other non-mail content
@@ -272,7 +272,7 @@ EOF
 	@ret; # may be empty, this sub is called as an arg for join()
 }
 
-sub _add_imap_nntp_urls ($$) {
+sub _add_non_http_urls ($$) {
 	my ($ctx, $txt) = @_;
 	$ctx->{ibx}->can('nntp_url') or return; # TODO extindex can have IMAP
 	my $urls = $ctx->{ibx}->imap_url($ctx);
@@ -286,11 +286,25 @@ EOM
 	}
 	$urls = $ctx->{ibx}->nntp_url($ctx);
 	if (@$urls) {
-		$$txt .= "\n";
-		$$txt .= @$urls == 1 ? 'Newsgroup' : 'Newsgroups are';
+		$$txt .= @$urls == 1 ? "\nNewsgroup" : "\nNewsgroups are";
 		$$txt .= ' available over NNTP:';
 		$$txt .= "\n  " . join("\n  ", @$urls) . "\n";
 	}
+	$urls = $ctx->{ibx}->pop3_url($ctx);
+	if (@$urls) {
+		$urls = join("\n  ", @$urls);
+		$$txt .= <<EOM;
+
+POP3 access is available:
+  $urls
+
+The password is: anonymous
+The username is: \$(uuidgen)\@$ctx->{ibx}->{newsgroup}
+where \$(uuidgen) in the output of the `uuidgen' command on your system.
+The UUID in the username functions as a private cookie (don't share it).
+Idle accounts will expire periodically.
+EOM
+	}
 }
 
 sub _add_onion_note ($) {
@@ -379,7 +393,7 @@ EOM
 
 Example config snippet for mirrors: $cfg_link
 EOF
-	_add_imap_nntp_urls($ctx, $txt);
+	_add_non_http_urls($ctx, $txt);
 	_add_onion_note($txt);
 
 	my $code_url = prurl($ctx->{env}, $PublicInbox::WwwStream::CODE_URL);
@@ -508,7 +522,7 @@ message threading
 EOF
 	} # $over
 
-	_add_imap_nntp_urls($ctx, \(my $note = ''));
+	_add_non_http_urls($ctx, \(my $note = ''));
 	$note and $note =~ s/^/  /gms and $$txt .= <<EOF;
 additional protocols
 --------------------

POP3 adoption (was: [PATCH 1/2] doc|www: flesh out POP3 documentation for servers) and users

[Eric Wong]

Eric Wong <e@80x24.org> wrote:
> +++ b/lib/PublicInbox/WwwText.pm

<snip>
> +The password is: anonymous
> +The username is: \$(uuidgen)\@$ctx->{ibx}->{newsgroup}
> +where \$(uuidgen) in the output of the `uuidgen' command on your system.
> +The UUID in the username functions as a private cookie (don't share it).
> +Idle accounts will expire periodically.

I just checked my POP3 instance on public-inbox.org; and not a
single user has used it.  I guess POP3 really is unpopular :<

Re: POP3 adoption (was: [PATCH 1/2] doc|www: flesh out POP3 documentation for servers) and users

[Konstantin Ryabitsev]

On Mon, Feb 06, 2023 at 06:03:38AM +0000, Eric Wong wrote:
> > +The password is: anonymous
> > +The username is: \$(uuidgen)\@$ctx->{ibx}->{newsgroup}
> > +where \$(uuidgen) in the output of the `uuidgen' command on your system.
> > +The UUID in the username functions as a private cookie (don't share it).
> > +Idle accounts will expire periodically.
> 
> I just checked my POP3 instance on public-inbox.org; and not a
> single user has used it.  I guess POP3 really is unpopular :<

I think it's because it's not a widely known feature. I intend to make it
available soon via lore.kernel.org, which should allow people to subscribe to
lists via gmail's POP3 integration.

I just need to implement the unified daemon features so we don't manage 5
different systemd services.

-K

[PATCH 2/2] tests: maintainer test for using mpop

[Eric Wong]

This ought to be a good stress test to ensure our POP3
implementation works against the POP3 client I've found.
---
 MANIFEST        |  1 +
 xt/pop3d-mpop.t | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 xt/pop3d-mpop.t

diff --git a/MANIFEST b/MANIFEST
index ce5e08a7..dac6875e 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -605,5 +605,6 @@ xt/perf-msgview.t
 xt/perf-nntpd.t
 xt/perf-obfuscate.t
 xt/perf-threading.t
+xt/pop3d-mpop.t
 xt/solver.t
 xt/stress-sharedkv.t
diff --git a/xt/pop3d-mpop.t b/xt/pop3d-mpop.t
new file mode 100644
index 00000000..8648b953
--- /dev/null
+++ b/xt/pop3d-mpop.t
@@ -0,0 +1,77 @@
+#!perl -w
+# Copyright (C) all contributors <meta@public-inbox.org>
+# License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+# ensure mpop compatibility
+use v5.12;
+use File::Path qw(make_path);
+use PublicInbox::TestCommon;
+use PublicInbox::Spawn qw(which spawn);
+my $inboxdir = $ENV{GIANT_INBOX_DIR};
+(defined($inboxdir) && -d $inboxdir) or
+	plan skip_all => "GIANT_INBOX_DIR not defined for $0";
+plan skip_all => "bad characters in $inboxdir" if $inboxdir =~ m![^\w\.\-/]!;
+my $uuidgen = which('uuidgen') or plan skip_all => 'uuidgen(1) missing';
+require_mods(qw(DBD::SQLite));
+require_git('2.6'); # for v2
+require_mods(qw(File::FcntlLock)) if $^O !~ /\A(?:linux|freebsd)\z/;
+
+my ($tmpdir, $for_destroy) = tmpdir();
+my $cfg = "$tmpdir/cfg";
+my $newsgroup = 'inbox.test';
+my %pids;
+{
+	open my $fh, '>', $cfg or xbail "open: $!";
+	print $fh <<EOF or xbail "print: $!";
+[publicinbox]
+	pop3state = $tmpdir/p3s
+[publicinbox "test"]
+	newsgroup = $newsgroup
+	address = mpop-test\@example.com
+	inboxdir = $inboxdir
+EOF
+	close $fh or xbail "close: $!";
+}
+my ($out, $err) = ("$tmpdir/stdout.log", "$tmpdir/stderr.log");
+my $sock = tcp_server();
+my $cmd = [ '-pop3d', '-W0', "--stdout=$out", "--stderr=$err" ];
+my $env = { PI_CONFIG => $cfg };
+my $td = start_script($cmd, $env, { 3 => $sock }) or xbail "-xbail $?";
+chomp(my $uuid = xqx([$uuidgen]));
+
+make_path("$tmpdir/home/.config/mpop",
+	map { "$tmpdir/md/$_" } qw(new cur tmp));
+
+SKIP: {
+	my $mpop = which('mpop') or skip('mpop(1) missing', 1);
+	open my $fh, '>', "$tmpdir/home/.config/mpop/config"
+		or xbail "open $!";
+	chmod 0600, $fh;
+	print $fh <<EOM or xbail "print $!";
+defaults
+tls off
+delivery maildir $tmpdir/md
+account default
+host ${\$sock->sockhost}
+port ${\$sock->sockport}
+user $uuid\@$newsgroup
+auth user
+password anonymous
+received_header off
+EOM
+	close $fh or xbail "close $!";
+	delete local $ENV{XDG_CONFIG_HOME}; # mpop uses this
+	local $ENV{HOME} = "$tmpdir/home";
+	my $cmd = [ $mpop, '-q' ];
+	my $pid = spawn($cmd, undef, { 1 => 2 });
+	$pids{$pid} = $cmd;
+}
+
+while (scalar keys %pids) {
+	my $pid = waitpid(-1, 0) or next;
+	my $cmd = delete $pids{$pid} or next;
+	is($?, 0, join(' ', @$cmd, 'done'));
+}
+$td->kill;
+$td->join;
+is($?, 0, 'no error on -pop3d exit');
+done_testing;