From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS60729 185.220.102.0/24 X-Spam-Status: No, score=-1.8 required=3.0 tests=BAYES_00,RCVD_IN_XBL, RDNS_NONE,SPF_FAIL,SPF_HELO_FAIL shortcircuit=no autolearn=no autolearn_force=no version=3.4.2 Received: from 80x24.org (unknown [185.220.102.6]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id BB11E1F803 for ; Mon, 7 Jan 2019 09:09:57 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH] doc: various overview-level module comments Date: Mon, 7 Jan 2019 09:09:51 +0000 Message-Id: <20190107090951.27088-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: Hopefully this helps people familiarize themselves with the source code. --- lib/PublicInbox/AltId.pm | 9 +++++++++ lib/PublicInbox/ContentId.pm | 5 +++++ lib/PublicInbox/GetlineBody.pm | 4 ++++ lib/PublicInbox/GitHTTPBackend.pm | 2 +- lib/PublicInbox/HTTPD.pm | 2 ++ lib/PublicInbox/Import.pm | 5 +++-- lib/PublicInbox/Mbox.pm | 8 ++++++-- lib/PublicInbox/MsgIter.pm | 3 ++- lib/PublicInbox/MsgTime.pm | 2 ++ lib/PublicInbox/Reply.pm | 2 ++ lib/PublicInbox/SaPlugin/ListMirror.pm | 2 +- lib/PublicInbox/SearchIdxPart.pm | 3 +++ lib/PublicInbox/SearchMsg.pm | 2 ++ lib/PublicInbox/Spamcheck.pm | 2 ++ lib/PublicInbox/Spamcheck/Spamc.pm | 2 ++ lib/PublicInbox/SpawnPP.pm | 3 +++ lib/PublicInbox/V2Writable.pm | 1 + lib/PublicInbox/WwwAtomStream.pm | 3 +++ lib/PublicInbox/WwwStream.pm | 4 ++++ lib/PublicInbox/WwwText.pm | 1 + 20 files changed, 58 insertions(+), 7 deletions(-) diff --git a/lib/PublicInbox/AltId.pm b/lib/PublicInbox/AltId.pm index 4a6ff97..300bdc0 100644 --- a/lib/PublicInbox/AltId.pm +++ b/lib/PublicInbox/AltId.pm @@ -1,12 +1,21 @@ # Copyright (C) 2016-2018 all contributors # License: AGPL-3.0+ +# Used for giving serial numbers to messages. This can be tied to +# the msgmap for live updates to living lists (see +# PublicInbox::Filters::RubyLang), or kept separate for imports +# of defunct NNTP groups (e.g. scripts/xhdr-num2mid) +# +# Introducing NEW uses of serial numbers is discouraged because of +# it leads to reliance on centralization. However, being able +# to use existing serial numbers is beneficial. package PublicInbox::AltId; use strict; use warnings; use URI::Escape qw(uri_unescape); # spec: TYPE:PREFIX:param1=value1¶m2=value2&... +# The PREFIX will be a searchable boolean prefix in Xapian # Example: serial:gmane:file=/path/to/altmsgmap.sqlite3 sub new { my ($class, $inbox, $spec, $writable) = @_; diff --git a/lib/PublicInbox/ContentId.pm b/lib/PublicInbox/ContentId.pm index dd3155b..9baf0e7 100644 --- a/lib/PublicInbox/ContentId.pm +++ b/lib/PublicInbox/ContentId.pm @@ -1,6 +1,11 @@ # Copyright (C) 2018 all contributors # License: AGPL-3.0+ +# Unstable internal API. +# Used for on-the-fly duplicate detection in V2 inboxes. +# This is not stored in any database anywhere and may change +# as changes in duplicate detection are needed. +# See L manpage for more details. package PublicInbox::ContentId; use strict; use warnings; diff --git a/lib/PublicInbox/GetlineBody.pm b/lib/PublicInbox/GetlineBody.pm index 7fcd7c0..ea07f3d 100644 --- a/lib/PublicInbox/GetlineBody.pm +++ b/lib/PublicInbox/GetlineBody.pm @@ -4,6 +4,10 @@ # Wrap a pipe or file for PSGI streaming response bodies and calls the # end callback when the object goes out-of-scope. # This depends on rpipe being _blocking_ on getline. +# +# public-inbox-httpd favors "getline" response bodies to take a +# "pull"-based approach to feeding slow clients (as opposed to a +# more common "push" model) package PublicInbox::GetlineBody; use strict; use warnings; diff --git a/lib/PublicInbox/GitHTTPBackend.pm b/lib/PublicInbox/GitHTTPBackend.pm index 6efe5b3..54ccfa0 100644 --- a/lib/PublicInbox/GitHTTPBackend.pm +++ b/lib/PublicInbox/GitHTTPBackend.pm @@ -2,7 +2,7 @@ # License: AGPL-3.0+ # when no endpoints match, fallback to this and serve a static file -# or smart HTTP +# or smart HTTP. This is our wrapper for git-http-backend(1) package PublicInbox::GitHTTPBackend; use strict; use warnings; diff --git a/lib/PublicInbox/HTTPD.pm b/lib/PublicInbox/HTTPD.pm index f923dbb..8cf365d 100644 --- a/lib/PublicInbox/HTTPD.pm +++ b/lib/PublicInbox/HTTPD.pm @@ -1,6 +1,8 @@ # Copyright (C) 2016-2018 all contributors # License: AGPL-3.0+ +# wraps a listen socket for HTTP and links it to the PSGI app in +# public-inbox-httpd package PublicInbox::HTTPD; use strict; use warnings; diff --git a/lib/PublicInbox/Import.pm b/lib/PublicInbox/Import.pm index 29c482f..fd4255c 100644 --- a/lib/PublicInbox/Import.pm +++ b/lib/PublicInbox/Import.pm @@ -2,8 +2,9 @@ # License: AGPL-3.0+ # # git fast-import-based ssoma-mda MDA replacement -# This is only ever run by public-inbox-mda and public-inbox-learn, -# not the WWW or NNTP code which only requires read-only access. +# This is only ever run by public-inbox-mda, public-inbox-learn +# and public-inbox-watch. Not the WWW or NNTP code which only +# requires read-only access. package PublicInbox::Import; use strict; use warnings; diff --git a/lib/PublicInbox/Mbox.pm b/lib/PublicInbox/Mbox.pm index 11b2302..78dbe27 100644 --- a/lib/PublicInbox/Mbox.pm +++ b/lib/PublicInbox/Mbox.pm @@ -1,8 +1,12 @@ # Copyright (C) 2015-2018 all contributors # License: AGPL-3.0+ -# Streaming interface for formatting messages as an mboxrd. -# Used by the web interface +# Streaming (via getline) interface for formatting messages as an mboxrd. +# Used by the PSGI web interface. +# +# public-inbox-httpd favors "getline" response bodies to take a +# "pull"-based approach to feeding slow clients (as opposed to a +# more common "push" model) package PublicInbox::Mbox; use strict; use warnings; diff --git a/lib/PublicInbox/MsgIter.pm b/lib/PublicInbox/MsgIter.pm index 9e2d797..eb94d62 100644 --- a/lib/PublicInbox/MsgIter.pm +++ b/lib/PublicInbox/MsgIter.pm @@ -1,6 +1,7 @@ # Copyright (C) 2016-2018 all contributors # License: AGPL-3.0+ -# + +# read-only utilities for Email::MIME package PublicInbox::MsgIter; use strict; use warnings; diff --git a/lib/PublicInbox/MsgTime.pm b/lib/PublicInbox/MsgTime.pm index f3ebb64..6216023 100644 --- a/lib/PublicInbox/MsgTime.pm +++ b/lib/PublicInbox/MsgTime.pm @@ -1,5 +1,7 @@ # Copyright (C) 2018 all contributors # License: AGPL-3.0+ + +# Various date/time-related functions package PublicInbox::MsgTime; use strict; use warnings; diff --git a/lib/PublicInbox/Reply.pm b/lib/PublicInbox/Reply.pm index 11e17ed..0f6dd83 100644 --- a/lib/PublicInbox/Reply.pm +++ b/lib/PublicInbox/Reply.pm @@ -1,5 +1,7 @@ # Copyright (C) 2014-2018 all contributors # License: AGPL-3.0+ + +# For reply instructions and address generation in WWW UI package PublicInbox::Reply; use strict; use warnings; diff --git a/lib/PublicInbox/SaPlugin/ListMirror.pm b/lib/PublicInbox/SaPlugin/ListMirror.pm index f2071dd..31f926f 100644 --- a/lib/PublicInbox/SaPlugin/ListMirror.pm +++ b/lib/PublicInbox/SaPlugin/ListMirror.pm @@ -1,7 +1,7 @@ # Copyright (C) 2016-2018 all contributors # License: AGPL-3.0+ -# Rules useful for running a mailing list mirror. We want to: +# SpamAssassin rules useful for running a mailing list mirror. We want to: # * ensure Received: headers are really from the list mail server # users expect. This is to prevent malicious users from # injecting spam into mirrors without going through the expected diff --git a/lib/PublicInbox/SearchIdxPart.pm b/lib/PublicInbox/SearchIdxPart.pm index 078d2df..7fe2120 100644 --- a/lib/PublicInbox/SearchIdxPart.pm +++ b/lib/PublicInbox/SearchIdxPart.pm @@ -1,5 +1,8 @@ # Copyright (C) 2018 all contributors # License: AGPL-3.0+ + +# used to interface with a single Xapian partition in V2 repos. +# See L for more info on how we partition Xapian package PublicInbox::SearchIdxPart; use strict; use warnings; diff --git a/lib/PublicInbox/SearchMsg.pm b/lib/PublicInbox/SearchMsg.pm index c7787ea..32cceb2 100644 --- a/lib/PublicInbox/SearchMsg.pm +++ b/lib/PublicInbox/SearchMsg.pm @@ -3,6 +3,8 @@ # based on notmuch, but with no concept of folders, files or flags # # Wraps a document inside our Xapian search index. +# There may be many of these objects loaded in memory at once +# for large threads in our WWW UI. package PublicInbox::SearchMsg; use strict; use warnings; diff --git a/lib/PublicInbox/Spamcheck.pm b/lib/PublicInbox/Spamcheck.pm index 062479d..54d54cb 100644 --- a/lib/PublicInbox/Spamcheck.pm +++ b/lib/PublicInbox/Spamcheck.pm @@ -1,5 +1,7 @@ # Copyright (C) 2018 all contributors # License: AGPL-3.0+ + +# Spamchecking used by -watch and -mda tools package PublicInbox::Spamcheck; use strict; use warnings; diff --git a/lib/PublicInbox/Spamcheck/Spamc.pm b/lib/PublicInbox/Spamcheck/Spamc.pm index a76e920..88aa531 100644 --- a/lib/PublicInbox/Spamcheck/Spamc.pm +++ b/lib/PublicInbox/Spamcheck/Spamc.pm @@ -1,5 +1,7 @@ # Copyright (C) 2016-2018 all contributors # License: AGPL-3.0+ + +# Default spam filter class for wrapping spamc(1) package PublicInbox::Spamcheck::Spamc; use strict; use warnings; diff --git a/lib/PublicInbox/SpawnPP.pm b/lib/PublicInbox/SpawnPP.pm index d0df94d..743db22 100644 --- a/lib/PublicInbox/SpawnPP.pm +++ b/lib/PublicInbox/SpawnPP.pm @@ -1,5 +1,8 @@ # Copyright (C) 2016-2018 all contributors # License: AGPL-3.0+ + +# Pure-Perl implementation of "spawn". This can't take advantage +# of vfork, so no speedups under Linux for spawning from large processes. package PublicInbox::SpawnPP; use strict; use warnings; diff --git a/lib/PublicInbox/V2Writable.pm b/lib/PublicInbox/V2Writable.pm index fbab8f7..222df5c 100644 --- a/lib/PublicInbox/V2Writable.pm +++ b/lib/PublicInbox/V2Writable.pm @@ -2,6 +2,7 @@ # License: AGPL-3.0+ # This interface wraps and mimics PublicInbox::Import +# Used to write to V2 inboxes (see L). package PublicInbox::V2Writable; use strict; use warnings; diff --git a/lib/PublicInbox/WwwAtomStream.pm b/lib/PublicInbox/WwwAtomStream.pm index 38eba2a..712c3dc 100644 --- a/lib/PublicInbox/WwwAtomStream.pm +++ b/lib/PublicInbox/WwwAtomStream.pm @@ -2,6 +2,9 @@ # License: AGPL-3.0+ # # Atom body stream for which yields getline+close methods +# public-inbox-httpd favors "getline" response bodies to take a +# "pull"-based approach to feeding slow clients (as opposed to a +# more common "push" model) package PublicInbox::WwwAtomStream; use strict; use warnings; diff --git a/lib/PublicInbox/WwwStream.pm b/lib/PublicInbox/WwwStream.pm index d39f551..e548f00 100644 --- a/lib/PublicInbox/WwwStream.pm +++ b/lib/PublicInbox/WwwStream.pm @@ -2,6 +2,10 @@ # License: AGPL-3.0+ # # HTML body stream for which yields getline+close methods +# +# public-inbox-httpd favors "getline" response bodies to take a +# "pull"-based approach to feeding slow clients (as opposed to a +# more common "push" model) package PublicInbox::WwwStream; use strict; use warnings; diff --git a/lib/PublicInbox/WwwText.pm b/lib/PublicInbox/WwwText.pm index e6d00ea..b5874cf 100644 --- a/lib/PublicInbox/WwwText.pm +++ b/lib/PublicInbox/WwwText.pm @@ -1,6 +1,7 @@ # Copyright (C) 2016-2018 all contributors # License: AGPL-3.0+ +# used for displaying help texts and other non-mail content package PublicInbox::WwwText; use strict; use warnings; -- EW