lib/PublicInbox/WwwText.pm

   1 # Copyright (C) 2016-2021 all contributors <meta@public-inbox.org>
   2 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
   3
   4 # used for displaying help texts and other non-mail content
   5 package PublicInbox::WwwText;
   6 use strict;
   7 use v5.10.1;
   8 use PublicInbox::Linkify;
   9 use PublicInbox::WwwStream;
  10 use PublicInbox::Hval qw(ascii_html prurl);
  11 use HTTP::Date qw(time2str);
  12 use URI::Escape qw(uri_escape_utf8);
  13 use PublicInbox::GzipFilter qw(gzf_maybe);
  14 our $QP_URL = 'https://xapian.org/docs/queryparser.html';
  15 our $WIKI_URL = 'https://en.wikipedia.org/wiki';
  16 my $hl = eval {
  17         require PublicInbox::HlMod;
  18         PublicInbox::HlMod->new
  19 };
  20
  21 # /$INBOX/_/text/$KEY/ # KEY may contain slashes
  22 # For now, "help" is the only supported $KEY
  23 sub get_text {
  24         my ($ctx, $key) = @_;
  25         my $code = 200;
  26
  27         $key //= 'help'; # this 302s to _/text/help/
  28
  29         # get the raw text the same way we get mboxrds
  30         my $raw = ($key =~ s!/raw\z!!);
  31         my $have_tslash = ($key =~ s!/\z!!) if !$raw;
  32
  33         my $txt = '';
  34         my $hdr = [ 'Content-Type', 'text/plain', 'Content-Length', undef ];
  35         if (!_default_text($ctx, $key, $hdr, \$txt)) {
  36                 $code = 404;
  37                 $txt = "404 Not Found ($key)\n";
  38         }
  39         my $env = $ctx->{env};
  40         if ($raw) {
  41                 if ($code == 200) {
  42                         my $gzf = gzf_maybe($hdr, $env);
  43                         $txt = $gzf->translate($txt);
  44                         $txt .= $gzf->zflush;
  45                 }
  46                 $hdr->[3] = length($txt);
  47                 return [ $code, $hdr, [ $txt ] ]
  48         }
  49
  50         # enforce trailing slash for "wget -r" compatibility
  51         if (!$have_tslash && $code == 200) {
  52                 my $url = $ctx->{ibx}->base_url($env);
  53                 $url .= "_/text/$key/";
  54
  55                 return [ 302, [ 'Content-Type', 'text/plain',
  56                                 'Location', $url ],
  57                         [ "Redirecting to $url\n" ] ];
  58         }
  59
  60         # Follow git commit message conventions,
  61         # first line is the Subject/title
  62         my ($title) = ($txt =~ /\A([^\n]*)/s);
  63         $ctx->{-title_html} = ascii_html($title);
  64         my $nslash = ($key =~ tr!/!/!);
  65         $ctx->{-upfx} = '../../../' . ('../' x $nslash);
  66         my $l = PublicInbox::Linkify->new;
  67         $l->linkify_1($txt);
  68         if ($hl) {
  69                 $hl->do_hl_text(\$txt);
  70         } else {
  71                 $txt = ascii_html($txt);
  72         }
  73         $txt = '<pre>' . $l->linkify_2($txt) . '</pre>';
  74         PublicInbox::WwwStream::html_oneshot($ctx, $code, \$txt);
  75 }
  76
  77 sub _srch_prefix ($$) {
  78         my ($ibx, $txt) = @_;
  79         my $pad = 0;
  80         my $htxt = '';
  81         my $help = $ibx->isrch->help;
  82         my $i;
  83         for ($i = 0; $i < @$help; $i += 2) {
  84                 my $pfx = $help->[$i];
  85                 my $n = length($pfx);
  86                 $pad = $n if $n > $pad;
  87                 $htxt .= $pfx . "\0";
  88                 $htxt .= $help->[$i + 1];
  89                 $htxt .= "\f\n";
  90         }
  91         $pad += 2;
  92         my $padding = ' ' x ($pad + 4);
  93         $htxt =~ s/^/$padding/gms;
  94         $htxt =~ s/^$padding(\S+)\0/"    $1".(' ' x ($pad - length($1)))/egms;
  95         $htxt =~ s/\f\n/\n/gs;
  96         $$txt .= $htxt;
  97         1;
  98 }
  99
 100 sub _colors_help ($$) {
 101         my ($ctx, $txt) = @_;
 102         my $ibx = $ctx->{ibx};
 103         my $env = $ctx->{env};
 104         my $base_url = $ibx->base_url($env);
 105         $$txt .= "color customization for $base_url\n";
 106         $$txt .= <<EOF;
 107
 108 public-inbox provides a stable set of CSS classes for users to
 109 customize colors for highlighting diffs and code.
 110
 111 Users of browsers such as dillo, Firefox, or some browser
 112 extensions may start by downloading the following sample CSS file
 113 to control the colors they see:
 114
 115   ${base_url}userContent.css
 116
 117 CSS sample
 118 ----------
 119 ```css
 120 EOF
 121         $$txt .= PublicInbox::UserContent::sample($ibx, $env) . "```\n";
 122 }
 123
 124 # git-config section names are quoted in the config file, so escape them
 125 sub dq_escape ($) {
 126         my ($name) = @_;
 127         $name =~ s/\\/\\\\/g;
 128         $name =~ s/"/\\"/g;
 129         $name;
 130 }
 131
 132 sub _coderepo_config ($$) {
 133         my ($ctx, $txt) = @_;
 134         my $cr = $ctx->{ibx}->{coderepo} // return;
 135         # note: this doesn't preserve cgitrc layout, since we parse cgitrc
 136         # and drop the original structure
 137         $$txt .= "\tcoderepo = $_\n" for @$cr;
 138         $$txt .= <<'EOF';
 139
 140 ; `coderepo' entries allows blob reconstruction via patch emails if
 141 ; the inbox is indexed with Xapian.  `@@ <from-range> <to-range> @@'
 142 ; line number ranges in `[PATCH]' emails link to /$INBOX_NAME/$OID/s/,
 143 ; an HTTP endpoint which reconstructs git blobs via git-apply(1).
 144 EOF
 145         my $pi_cfg = $ctx->{www}->{pi_cfg};
 146         for my $cr_name (@$cr) {
 147                 my $urls = $pi_cfg->get_all("coderepo.$cr_name.cgiturl");
 148                 my $path = "/path/to/$cr_name";
 149                 $cr_name = dq_escape($cr_name);
 150
 151                 $$txt .= qq([coderepo "$cr_name"]\n);
 152                 if ($urls && scalar(@$urls)) {
 153                         $$txt .= "\t; ";
 154                         $$txt .= join(" ||\n\t;\t", map {;
 155                                 my $dst = $path;
 156                                 if ($path !~ m![a-z0-9_/\.\-]!i) {
 157                                         $dst = '"'.dq_escape($dst).'"';
 158                                 }
 159                                 qq(git clone $_ $dst);
 160                         } @$urls);
 161                         $$txt .= "\n";
 162                 }
 163                 $$txt .= "\tdir = $path\n";
 164                 $$txt .= "\tcgiturl = https://example.com/";
 165                 $$txt .= uri_escape_utf8($cr_name, '^A-Za-z0-9\-\._~/')."\n";
 166         }
 167 }
 168
 169 # n.b. this is a perfect candidate for memoization
 170 sub inbox_config ($$$) {
 171         my ($ctx, $hdr, $txt) = @_;
 172         my $ibx = $ctx->{ibx};
 173         push @$hdr, 'Content-Disposition', 'inline; filename=inbox.config';
 174         my $t = eval { $ibx->mm->created_at };
 175         push(@$hdr, 'Last-Modified', time2str($t)) if $t;
 176         my $name = dq_escape($ibx->{name});
 177         my $inboxdir = '/path/to/top-level-inbox';
 178         my $base_url = $ibx->base_url($ctx->{env});
 179         $$txt .= <<EOS;
 180 ; Example public-inbox config snippet for a mirror of
 181 ; $base_url
 182 ; See public-inbox-config(5) manpage for more details:
 183 ; https://public-inbox.org/public-inbox-config.html
 184 [publicinbox "$name"]
 185         inboxdir = $inboxdir
 186         ; note: public-inbox before v1.2.0 used `mainrepo' instead of
 187         ; `inboxdir', both remain supported after 1.2
 188         mainrepo = $inboxdir
 189         url = https://example.com/$name/
 190         url = http://example.onion/$name/
 191 EOS
 192         for my $k (qw(address listid infourl watchheader)) {
 193                 defined(my $v = $ibx->{$k}) or next;
 194                 $$txt .= "\t$k = $_\n" for @$v;
 195         }
 196         if (my $altid = $ibx->{altid}) {
 197                 my $altid_map = $ibx->altid_map;
 198                 $$txt .= <<EOF;
 199         ; altid DBs may be used to provide numeric article ID lookup from
 200         ; old, pre-existing sources.  You can recreate them via curl(1),
 201         ; gzip(1), and sqlite3(1) as documented:
 202 EOF
 203                 for (sort keys %$altid_map) {
 204                         $$txt .= "\t;\tcurl -d '' $base_url$_.sql.gz | \\\n" .
 205                                 "\t;\tgzip -dc | \\\n" .
 206                                 "\t;\tsqlite3 $inboxdir/$_.sqlite3\n";
 207                         $$txt .= "\taltid = serial:$_:file=$_.sqlite3\n";
 208                 }
 209         }
 210
 211         for my $k (qw(filter newsgroup obfuscate replyto)) {
 212                 defined(my $v = $ibx->{$k}) or next;
 213                 $$txt .= "\t$k = $v\n";
 214         }
 215         $$txt .= "\timapmirror = $_\n" for (@{$ibx->imap_url($ctx)});
 216         $$txt .= "\tnntpmirror = $_\n" for (@{$ibx->nntp_url($ctx)});
 217         _coderepo_config($ctx, $txt);
 218         1;
 219 }
 220
 221 # n.b. this is a perfect candidate for memoization
 222 sub extindex_config ($$$) {
 223         my ($ctx, $hdr, $txt) = @_;
 224         my $ibx = $ctx->{ibx};
 225         push @$hdr, 'Content-Disposition', 'inline; filename=extindex.config';
 226         my $name = dq_escape($ibx->{name});
 227         my $base_url = $ibx->base_url($ctx->{env});
 228         $$txt .= <<EOS;
 229 ; Example public-inbox config snippet for the external index (extindex) at:
 230 ; $base_url
 231 ; See public-inbox-config(5)manpage for more details:
 232 ; https://public-inbox.org/public-inbox-config.html
 233 [extindex "$name"]
 234         topdir = /path/to/extindex-topdir
 235         url = https://example.com/$name/
 236         url = http://example.onion/$name/
 237 EOS
 238         for my $k (qw(infourl)) {
 239                 defined(my $v = $ibx->{$k}) or next;
 240                 $$txt .= "\t$k = $v\n";
 241         }
 242         _coderepo_config($ctx, $txt);
 243         1;
 244 }
 245
 246 sub coderepos_raw ($$) {
 247         my ($ctx, $top_url) = @_;
 248         my $cr = $ctx->{ibx}->{coderepo} // return ();
 249         my $cfg = $ctx->{www}->{pi_cfg};
 250         my @ret;
 251         for my $cr_name (@$cr) {
 252                 $ret[0] //= do {
 253                         my $thing = $ctx->{ibx}->can('cloneurl') ?
 254                                 'public inbox' : 'external index';
 255                         <<EOF;
 256 Code repositories for project(s) associated with this $thing
 257 EOF
 258                 };
 259                 my $urls = $cfg->get_all("coderepo.$cr_name.cgiturl");
 260                 if ($urls) {
 261                         for (@$urls) {
 262                                 # relative or absolute URL?, prefix relative
 263                                 # "foo.git" with appropriate number of "../"
 264                                 my $u = m!\A(?:[a-z\+]+:)?//!i ? $_ :
 265                                         $top_url.$_;
 266                                 $ret[0] .= "\n\t" . prurl($ctx->{env}, $u);
 267                         }
 268                 } else {
 269                         $ret[0] .= qq[\n\t$cr_name.git (no URL configured)];
 270                 }
 271         }
 272         @ret; # may be empty, this sub is called as an arg for join()
 273 }
 274
 275 sub _add_imap_nntp_urls ($$) {
 276         my ($ctx, $txt) = @_;
 277         $ctx->{ibx}->can('nntp_url') or return; # TODO extindex can have IMAP
 278         my $urls = $ctx->{ibx}->imap_url($ctx);
 279         if (@$urls) {
 280                 $$txt .= "\nIMAP subfolder(s) are available under:";
 281                 $$txt .= "\n  " . join("\n  ", @$urls);
 282                 $$txt .= <<EOM
 283
 284   # each subfolder (starting with `0') holds 50K messages at most
 285 EOM
 286         }
 287         $urls = $ctx->{ibx}->nntp_url($ctx);
 288         if (@$urls) {
 289                 $$txt .= "\n";
 290                 $$txt .= @$urls == 1 ? 'Newsgroup' : 'Newsgroups are';
 291                 $$txt .= ' available over NNTP:';
 292                 $$txt .= "\n  " . join("\n  ", @$urls) . "\n";
 293         }
 294 }
 295
 296 sub _add_onion_note ($) {
 297         my ($txt) = @_;
 298         $$txt =~ m!\b[^:]+://\w+\.onion/!i and $$txt .= <<EOM
 299
 300 note: .onion URLs require Tor: https://www.torproject.org/
 301
 302 EOM
 303 }
 304
 305 sub _mirror_help ($$) {
 306         my ($ctx, $txt) = @_;
 307         my $ibx = $ctx->{ibx};
 308         my $base_url = $ibx->base_url($ctx->{env});
 309         chop $base_url; # no trailing slash for "git clone"
 310         my $dir = (split(m!/!, $base_url))[-1];
 311         my %seen = ($base_url => 1);
 312         my $top_url = $base_url;
 313         $top_url =~ s!/[^/]+\z!/!;
 314         $$txt .= "public-inbox mirroring instructions\n\n";
 315         if ($ibx->can('cloneurl')) { # PublicInbox::Inbox
 316                 $$txt .=
 317                   "This public inbox may be cloned and mirrored by anyone:\n";
 318                 my @urls;
 319                 my $max = $ibx->max_git_epoch;
 320                 # TODO: some of these URLs may be too long and we may need to
 321                 # do something like code_footer() above, but these are local
 322                 # admin-defined
 323                 if (defined($max)) { # v2
 324                         for my $i (0..$max) {
 325                                 # old epochs my be deleted:
 326                                 -d "$ibx->{inboxdir}/git/$i.git" or next;
 327                                 my $url = "$base_url/$i";
 328                                 $seen{$url} = 1;
 329                                 push @urls, "$url $dir/git/$i.git";
 330                         }
 331                         my $nr = scalar(@urls);
 332                         if ($nr > 1) {
 333                                 chomp($$txt .= <<EOM);
 334
 335   # this inbox consists of $nr epochs: (no need to clone all of them)
 336 EOM
 337                                 $urls[0] .= " # oldest";
 338                                 $urls[-1] .= " # newest";
 339                         }
 340                 } else { # v1
 341                         push @urls, $base_url;
 342                 }
 343                 # FIXME: epoch splits can be different in other repositories,
 344                 # use the "cloneurl" file as-is for now:
 345                 for my $u (@{$ibx->cloneurl}) {
 346                         next if $seen{$u}++;
 347                         push @urls, $u;
 348                 }
 349                 $$txt .= "\n";
 350                 $$txt .= join('', map { "  git clone --mirror $_\n" } @urls);
 351                 my $addrs = $ibx->{address} // 'inbox@example.com';
 352                 my $ng = $ibx->{newsgroup} // '';
 353                 substr($ng, 0, 0, ' --ng ') if $ng;
 354                 $addrs = join(' ', @$addrs) if ref($addrs) eq 'ARRAY';
 355                 my $v = defined $max ? '-V2' : '-V1';
 356                 $$txt .= <<EOF;
 357
 358   # If you have public-inbox 1.1+ installed, you may
 359   # initialize and index your mirror using the following commands:
 360   public-inbox-init $v$ng \\
 361     $ibx->{name} ./$dir $base_url \\
 362     $addrs
 363   public-inbox-index ./$dir
 364 EOF
 365         } else { # PublicInbox::ExtSearch
 366                 $$txt .= <<EOM;
 367 This is an external index which is an amalgamation of several public inboxes.
 368 Each public inbox needs to be mirrored individually.
 369 EOM
 370                 my $v = $ctx->{www}->{pi_cfg}->{lc('publicInbox.wwwListing')};
 371                 if (($v // '') =~ /\A(?:all|match=domain)\z/) {
 372                         $$txt .= <<EOM;
 373 A list of them is available at $top_url
 374 EOM
 375                 }
 376         }
 377         my $cfg_link = "$base_url/_/text/config/raw";
 378         $$txt .= <<EOF;
 379
 380 Example config snippet for mirrors: $cfg_link
 381 EOF
 382         _add_imap_nntp_urls($ctx, $txt);
 383         _add_onion_note($txt);
 384
 385         my $code_url = prurl($ctx->{env}, $PublicInbox::WwwStream::CODE_URL);
 386         $$txt .= join("\n\n",
 387                 coderepos_raw($ctx, $top_url), # may be empty
 388                 "AGPL code for this site:\n  git clone $code_url");
 389         1;
 390 }
 391
 392 sub _default_text ($$$$) {
 393         my ($ctx, $key, $hdr, $txt) = @_;
 394         if ($key eq 'mirror') {
 395                 return _mirror_help($ctx, $txt);
 396         } elsif ($key eq 'color') {
 397                 return _colors_help($ctx, $txt);
 398         } elsif ($key eq 'config') {
 399                 return $ctx->{ibx}->can('cloneurl') ?
 400                         inbox_config($ctx, $hdr, $txt) :
 401                         extindex_config($ctx, $hdr, $txt);
 402         }
 403         return if $key ne 'help'; # TODO more keys?
 404
 405         my $ibx = $ctx->{ibx};
 406         my $base_url = $ibx->base_url($ctx->{env});
 407         $$txt .= <<EOF;
 408 public-inbox help for $base_url
 409
 410 overview
 411 --------
 412
 413   public-inbox uses Message-ID identifiers in URLs.
 414   One may look up messages by substituting Message-IDs
 415   (without the leading '<' or trailing '>') into the URL.
 416   Forward slash ('/') characters in the Message-IDs
 417   need to be escaped as "%2F" (without quotes).
 418
 419   Thus, it is possible to retrieve any message by its
 420   Message-ID by going to:
 421
 422     $base_url<Message-ID>/
 423     (without the '<' or '>')
 424
 425   Message-IDs are described at:
 426
 427     $WIKI_URL/Message-ID
 428
 429 EOF
 430
 431         # n.b. we use the Xapian DB for any regeneratable,
 432         # order-of-arrival-independent data.
 433         if ($ibx->isrch) {
 434                 $$txt .= <<EOF;
 435 search
 436 ------
 437
 438   This public-inbox has search functionality provided by Xapian.
 439
 440   It supports typical AND, OR, NOT, '+', '-' queries present
 441   in other search engines.
 442
 443   We also support search prefixes to limit the scope of the
 444   search to certain fields.
 445
 446   Prefixes supported in this installation include:
 447
 448 EOF
 449                 _srch_prefix($ibx, $txt);
 450                 $$txt .= <<EOF;
 451
 452   Most prefixes are probabilistic, meaning they support stemming
 453   and wildcards ('*').  Ranges (such as 'd:') and boolean prefixes
 454   do not support stemming or wildcards.
 455   The upstream Xapian query parser documentation fully explains
 456   the query syntax:
 457
 458     $QP_URL
 459
 460 EOF
 461         } # $srch
 462         if ($ibx->over) {
 463                 $$txt .= <<EOF;
 464 message threading
 465 -----------------
 466
 467   Message threading is enabled for this public-inbox,
 468   additional endpoints for message threads are available:
 469
 470   * $base_url<Message-ID>/T/#u
 471
 472     Loads the thread belonging to the given <Message-ID>
 473     in flat chronological order.  The "#u" anchor
 474     focuses the browser on the given <Message-ID>.
 475
 476   * $base_url<Message-ID>/t/#u
 477
 478     Loads the thread belonging to the given <Message-ID>
 479     in threaded order with nesting.  For deep threads,
 480     this requires a wide display or horizontal scrolling.
 481
 482   Both of these HTML endpoints are suitable for offline reading
 483   using the thread overview at the bottom of each page.
 484
 485   The gzipped mbox for a thread is available for downloading and
 486   importing into your favorite mail client:
 487
 488   * $base_url<Message-ID>/t.mbox.gz
 489
 490     We use the mboxrd variant of the mbox format described at:
 491
 492     $WIKI_URL/Mbox
 493
 494   Users of feed readers may follow a particular thread using:
 495
 496   * $base_url<Message-ID>/t.atom
 497
 498     Which loads the thread in Atom Syndication Standard
 499     described at Wikipedia and RFC4287:
 500
 501     $WIKI_URL/Atom_(standard)
 502     https://tools.ietf.org/html/rfc4287
 503
 504     Atom Threading Extensions (RFC4685) are supported:
 505
 506     https://tools.ietf.org/html/rfc4685
 507
 508 EOF
 509         } # $over
 510
 511         _add_imap_nntp_urls($ctx, \(my $note = ''));
 512         $note and $note =~ s/^/  /gms and $$txt .= <<EOF;
 513 additional protocols
 514 --------------------
 515 $note
 516 EOF
 517         $$txt .= <<EOF;
 518 contact
 519 -------
 520
 521   This help text is maintained by public-inbox developers
 522   reachable via plain-text email at: meta\@public-inbox.org
 523   Their inbox is archived at: https://public-inbox.org/meta/
 524 EOF
 525         # TODO: support admin contact info in ~/.public-inbox/config
 526         1;
 527 }
 528
 529 1;