doc|www: flesh out POP3 documentation for servers and users

Hopefully it makes sense to new users deploying or using POP3...

diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod
index ed99b188beb198a470d52ba179f1f40448261e57..d8504e6119157e88bc4c44ec994437d12138d029 100644 (file)
--- 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 da81fb67ad22efa8248c208a2d65629512153bbe..0ad68810942b42094e76da2de56fb013bfdec21c 100644 (file)
--- 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 2b4e69fe09745e4f3019b122989d363a5ebc467f..2937c3336c3fd40b8d7809b7ad116eab26261d9b 100644 (file)
--- 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
 --------------------