]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/technical/data_structures.txt
doc lei: add manpages for new commands
[public-inbox.git] / Documentation / technical / data_structures.txt
1 Internal data structures of public-inbox
2
3 This is a guide for hackers new to our code base.  Do not
4 consider our internal data structures stable for external
5 consumers, this document should be updated when internals
6 change.  I recommend reading this document from the source tree,
7 with the source code easily accessible if you need examples.
8
9 This mainly documents in-memory data structures.  If you're
10 interested in the stable on-filesystem formats, see the
11 public-inbox-config(5), public-inbox-v1-format(5) and
12 public-inbox-v2-format(5) manpages.
13
14 Common abbreviations when used outside of their packages are
15 documented.  `$self' is the common variable name when used
16 within their package.
17
18 PublicInbox::Config
19 -------------------
20
21 PublicInbox::Config is the root class which loads a
22 public-inbox-config file and instantiates PublicInbox::Inbox,
23 PublicInbox::WWW, PublicInbox::NNTPD, and other top-level
24 classes.
25
26 Outside of tests, this is typically a singleton.
27
28 Per-message classes
29 -------------------
30
31 * PublicInbox::Eml - Email::MIME-like class
32   Common abbreviation: $mime, $eml
33   Used by: PublicInbox::WWW, PublicInbox::SearchIdx
34
35   An representation of an entire email, multipart or not.
36   An option to use libgmime or libmailutils may be supported
37   in the future for performance and memory use.
38
39   This can be a memory hog with big messages and giant
40   attachments, so our PublicInbox::WWW interface only keeps
41   one object of this class in memory at-a-time.
42
43   In other words, this is the "meat" of the message, whereas
44   $smsg (below) is just the "skeleton".
45
46   Our PublicInbox::V2Writable class may have two objects of this
47   type in memory at-a-time for deduplication.
48
49   In public-inbox 1.4 and earlier, Email::MIME and its subclass,
50   PublicInbox::MIME were used.  Despite still slurping,
51   PublicInbox::Eml is faster and uses less memory due to
52   lazy header parsing and lazy subpart instantiation with
53   shorter object lifetimes.
54
55 * PublicInbox::Smsg - small message skeleton
56   Used by: PublicInbox::{NNTP,WWW,SearchIdx}
57   Common abbreviation: $smsg
58
59   Represents headers shown in NNTP overview and PSGI message
60   summaries (thread skeleton).
61
62   This is loaded from either the overview DB (over.sqlite3) or
63   the Xapian DB (docdata.glass), though the Xapian docdata
64   is won't hold NNTP-only fields (Cc:/To:)
65
66   There may be hundreds or thousands of these objects in memory
67   at-a-time, so fields are pruned if unneeded.
68
69 * PublicInbox::SearchThread::Msg - subclass of Smsg
70   Common abbreviation: $cont or $node
71   Used by: PublicInbox::WWW
72
73   The structure we use for a non-recursive[1] variant of
74   JWZ's algorithm: <https://www.jwz.org/doc/threading.html>.
75   Nowadays, this is a re-blessed $smsg with additional fields.
76
77   As with $smsg objects, there may be hundreds or thousands
78   of these objects in memory at-a-time.
79
80   We also do not use a linked-list for storing children as JWZ
81   describes, but instead a Perl hashref for {children} which
82   becomes an arrayref upon sorting.
83
84   [1] https://rt.cpan.org/Ticket/Display.html?id=116727
85
86 Per-inbox classes
87 -----------------
88
89 * PublicInbox::Inbox - represents a single public-inbox
90   Common abbreviation: $ibx
91   Used everywhere
92
93   This represents a "publicinbox" section in the config
94   file, see public-inbox-config(5) for details.
95
96 * PublicInbox::Git - represents a single git repository
97   Common abbreviation: $git, $ibx->git
98   Used everywhere.
99
100   Each configured "publicinbox" or "coderepo" has one of these.
101
102 * PublicInbox::Msgmap - msgmap.sqlite3 read-write interface
103   Common abbreviation: $mm, $ibx->mm
104   Used everywhere if SQLite is available.
105
106   Each indexed inbox has one of these, see
107   public-inbox-v1-format(5) and public-inbox-v2-format(5)
108   manpages for details.
109
110 * PublicInbox::Over - over.sqlite3 read-only interface
111   Common abbreviation: $over, $ibx->over
112   Used everywhere if SQLite is available.
113
114   Each indexed inbox has one of these, see
115   public-inbox-v1-format(5) and public-inbox-v2-format(5)
116   manpages for details.
117
118 * PublicInbox::Search - Xapian read-only interface
119   Common abbreviation: $srch, $ibx->search
120   Used everywhere if Search::Xapian (or Xapian.pm) is available.
121
122   Each indexed inbox has one of these, see
123   public-inbox-v1-format(5) and public-inbox-v2-format(5)
124   manpages for details.
125
126 PublicInbox::WWW
127 ----------------
128
129 The main PSGI web interface, uses several other packages to
130 form our web interface.
131
132 PublicInbox::SolverGit
133 ----------------------
134
135 This is instantiated from the $INBOX/$BLOB_OID/s/ WWW endpoint
136 and represents the stages and states for "solving" a blob by
137 searching for and applying patches.  See the code and comments
138 in PublicInbox/SolverGit.pm
139
140 PublicInbox::Qspawn
141 -------------------
142
143 This is instantiated from various WWW endpoints and represents
144 the stages and states for running and managing subprocesses
145 in a way which won't exceed configured process limits defined
146 via "publicinboxlimiter.*" directives in public-inbox-config(5).
147
148 ad-hoc structures shared across packages
149 ----------------------------------------
150
151 * $ctx - PublicInbox::WWW app request context
152   This holds the PSGI $env as well as any internal variables
153   used by various modules of PublicInbox::WWW.
154
155   As with the PSGI $env, there is one per-active WWW
156   request+response cycle.  It does not exist for idle HTTP
157   clients.
158
159 daemon classes
160 --------------
161
162 * PublicInbox::NNTP - a NNTP client socket
163   Common abbreviation: $nntp
164   Used by: PublicInbox::DS, public-inbox-nntpd
165
166   Unlike PublicInbox::HTTP, all of the NNTP client logic for
167   serving to NNTP clients is here, including what would be
168   in $ctx on the HTTP or WWW side.
169
170   There may be thousands of these since we support thousands of
171   NNTP clients.
172
173 * PublicInbox::HTTP - a HTTP client socket
174   Common abbreviation: $http
175   Used by: PublicInbox::DS, public-inbox-httpd
176
177   Unlike PublicInbox::NNTP, this class no knowledge of any of
178   the email or git-specific parts of public-inbox, only PSGI.
179   However, it supports APIs and behaviors (e.g. streaming large
180   responses) which PublicInbox::WWW may take advantage of.
181
182   There may be thousands of these since we support thousands of
183   HTTP clients.
184
185 * PublicInbox::Listener - a SOCK_STREAM listen socket (TCP or Unix)
186   Used by: PublicInbox::DS, public-inbox-httpd, public-inbox-nntpd
187   Common abbreviation: @listeners in PublicInbox::Daemon
188
189   This class calls non-blocking accept(2) or accept4(2) on a
190   listen socket to create new PublicInbox::HTTP and
191   PublicInbox::HTTP instances.
192
193 * PublicInbox::HTTPD
194   Common abbreviation: $httpd
195
196   Represents an HTTP daemon which creates PublicInbox::HTTP
197   wrappers around client sockets accepted from
198   PublicInbox::Listener.
199
200   Since the SERVER_NAME and SERVER_PORT PSGI variables needs to be
201   exposed for HTTP/1.0 requests when Host: headers are missing,
202   this is per-Listener socket.
203
204 * PublicInbox::HTTPD::Async
205   Common abbreviation: $async
206
207   Used for implementing an asynchronous "push" interface for
208   slow, expensive responses which may require spawning
209   git-httpd-backend(1), git-apply(1) or other commands.
210   This will also be used for dealing with future asynchronous
211   operations such as HTTP reverse proxying and slow storage
212   retrieval operations.
213
214 * PublicInbox::NNTPD
215   Common abbreviation: $nntpd
216
217   Represents an NNTP daemon which creates PublicInbox::NNTP
218   wrappers around client sockets accepted from
219   PublicInbox::Listener.
220
221   This is currently a singleton, but it is associated with a
222   given PublicInbox::Config which may be instantiated more than
223   once in the future.
224
225 * PublicInbox::EOFpipe
226
227   Used throughout to trigger a callback when a pipe(7) is closed.
228   This is frequently used to portably detect process exit without
229   relying on a catch-all waitpid(-1, ...) call.