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 + diff --git a/lib/PublicInbox/AltId.pm b/lib/PublicInbox/AltId.pm index 4a6ff97cc5e4aca470504123bbc30ce68dac6744..300bdc0b49fbda3d561c4037ab812ce732ac79b1 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 dd3155befefbd2d628683e6099847e72a34aec5a..9baf0e76a3e33c3d32502061c93ceb15b4028e33 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 7fcd7c03554cb7791136ad4a14dc3f917b890f8c..ea07f3d6dd0de1d031012c62372754dbc91acd49 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 6efe5b31d485086b0f4c4825a98b52c5180d9e60..54ccfa05c555ec193f7eea188806d449a9ab1515 100644 --- a/lib/PublicInbox/GitHTTPBackend.pm +++ b/lib/PublicInbox/GitHTTPBackend.pm @@ -2,7 +2,7 @@ # Copyright (C) 2016-2018 all contributors # 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 f923dbb641f518800f937fae68e98500ed2836a5..8cf365d04ced13658fab55b0fa69929bdc2c9d70 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 29c482f9b4339b09089421723f3991b24e57f553..fd4255cf867d6ca1a40dcce1fe19265f536803e6 100644 --- a/lib/PublicInbox/Import.pm +++ b/lib/PublicInbox/Import.pm @@ -2,8 +2,9 @@ # Copyright (C) 2016-2019 all contributors # 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 11b23022ff5ed8270af2f5f70ad0bbf3524c08af..78dbe27e30a0366c7788a6edc004728556312e0e 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 9e2d797fecc240d4f191ba8f3fe7fd84b410148e..eb94d621d73cdbcde4fee70d93a52fe3ba4d8f1d 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 f3ebb6447a9cfe341b381beb9f19671b01caf331..62160233f78d627d0bfc9c2e24b72f634d42005b 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 11e17ede716a0f7effc12080f2461e9ac6344748..0f6dd83bc3f5e3db9716cdce58f93d701dcdfd1f 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 f2071dd56a5b8344d55a8feae824368ec3fb21ca..31f926fa7b11afe467f999d099b7dadeacc93c4f 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 078d2df18d931235bc0f0087e08c6f89342583eb..7fe2120a425488eb0c076aeb35825dd681101081 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 c7787ea1003db61221c6c2aa0d84ab41f60fd59d..32cceb25065cf798ba497f8ea06f5f60c8f02c5f 100644 --- a/lib/PublicInbox/SearchMsg.pm +++ b/lib/PublicInbox/SearchMsg.pm @@ -3,6 +3,8 @@ # License: AGPL-3.0+ # 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 062479d636f3c74785721b9cc96b9a57daa38860..54d54cbcf22989f14da3bda99b0cde924bf865b9 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 a76e920f0210221a6345528c2c8fd8998033789f..88aa5315258c27b8ff7438d478148a29e0fc708d 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 d0df94d0ded0f4cf179a2420a274e13da062be6d..743db224ad0b8609ce80927255c0c61f8f301baf 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 fbab8f70be8a3233f0b4cc2a6d776e7c02c13244..222df5c2ffa6d0cf3dae884ea734ee9973dc1619 100644 --- a/lib/PublicInbox/V2Writable.pm +++ b/lib/PublicInbox/V2Writable.pm @@ -2,6 +2,7 @@ # Copyright (C) 2018 all contributors # 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 38eba2a044832b93c8d55672a92151c24a59da57..712c3dc88e34a3c210d6f74ac2ebd013c2863f91 100644 --- a/lib/PublicInbox/WwwAtomStream.pm +++ b/lib/PublicInbox/WwwAtomStream.pm @@ -2,6 +2,9 @@ # Copyright (C) 2016-2018 all contributors # 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 d39f551176dfe2ecf266ebe8c221512903691cca..e548f00f4a3ed024a9da56263860617b2638e60f 100644 --- a/lib/PublicInbox/WwwStream.pm +++ b/lib/PublicInbox/WwwStream.pm @@ -2,6 +2,10 @@ # Copyright (C) 2016-2018 all contributors # 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 e6d00ea9f00c48e27052f657a812a0e5bc3d3049..b5874cf6bad534a20daf060452884b463628440a 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;