]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-glossary.pod
doc: glossary: add a reference for "epoch"
[public-inbox.git] / Documentation / public-inbox-glossary.pod
1 =head1 NAME
2
3 public-inbox-glossary - glossary for public-inbox
4
5 =head1 DESCRIPTION
6
7 public-inbox combines several independently-developed protocols
8 and data formats with overlapping concepts.  This document is
9 intended as a guide to identify and clarify overlapping concepts
10 with different names.
11
12 This is mainly intended for hackers of public-inbox, but may be useful
13 for administrators of public-facing services and/or users building
14 tools.
15
16 =head1 TERMS
17
18 =over 8
19
20 =item IMAP UID, NNTP article number, on-disk Xapian docid
21
22 A sequentially-assigned positive integer.  These integers are per-inbox,
23 or per-extindex.  This is the C<num> column of the C<over> table in
24 C<over.sqlite3>
25
26 =item tid, THREADID
27
28 A sequentially-assigned positive integer.  These integers are
29 per-inbox or per-extindex.  In the future, this may be prefixed
30 with C<T> for JMAP (RFC 8621) and RFC 8474.  This may not be
31 strictly compliant with RFC 8621 since inboxes and extindices
32 are considered independent entities from each other.
33
34 This is the C<tid> column of the C<over> table in C<over.sqlite3>
35
36 =item blob
37
38 For email, this is the git blob object ID (SHA-(1|256)) of an
39 RFC-(822|2822|5322) email message.
40
41 =item IMAP EMAILID, JMAP Email Id
42
43 To-be-decided.  This will likely be the git blob ID prefixed with C<g>
44 rather than the numeric UID to accomodate the same blob showing
45 up in both an extindex and inbox (or multiple extindices).
46
47 =item newsgroup
48
49 The name of the NNTP newsgroup, see L<public-inbox-config(5)>.
50
51 =item IMAP (folder|mailbox) slice
52
53 A 50K slice of a newsgroup to accomodate the limitations of IMAP
54 clients with L<public-inbox-imapd(1)>.  This is the C<newsgroup>
55 name with a C<.$INTEGER_SUFFIX>, e.g. a newsgroup named C<inbox.test>
56 would have its first slice named C<inbox.test.0>, and second slice
57 named C<inbox.test.1> and so forth.
58
59 If implemented, the RFC 8474 MAILBOXID of an IMAP slice will NOT have
60 the same Mailbox Id as the public-facing full JMAP mailbox.
61
62 =item inbox name, public JMAP mailbox name
63
64 The HTTP(S) name of the public-inbox
65 (C<publicinbox.E<lt>nameE<gt>.*>).  JMAP will use this name
66 rather than the newsgroup name since public-facing JMAP will be
67 part of the PSGI code and not need a separate daemon like
68 L<public-inbox-nntpd(1)> or L<public-inbox-imapd(1)>
69
70 =item epoch
71
72 A git repository used for blob storage.  See
73 L<public-inbox-v2-format(5)/GIT EPOCHS>.
74
75 =item keywords, (IMAP|Maildir) flags, mbox Status + X-Status
76
77 Private, per-message keywords or flags as described in RFC 8621
78 section 10.4.  These are conveyed in the C<Status:> and
79 C<X-Status:> headers for L<mbox(5)>, as system IMAP FLAGS
80 (RFC 3501 section 2.3.2), or Maildir info flags.
81
82 L<public-inbox-watch(1)> ignores drafts and trashed (deleted)
83 messages.  L<lei-import(1)> ignores trashed (deleted) messages,
84 but it imports drafts.
85
86 =item labels, private JMAP mailboxes
87
88 For L<lei(1)> users only.  This will allow lei users to place
89 the same email into one or more virtual folders for
90 ease-of-filtering.  This is NOT tied to public-inbox names, as
91 messages stored by lei may not be public.
92
93 These are similar in spirit to arbitrary freeform "tags"
94 in mail software such as L<notmuch(1)> and non-system IMAP FLAGS.
95
96 =item volatile metadata (VMD)
97
98 For L<lei(1)> users only, this refers to the combination of
99 keywords and labels which are subject to frequent change
100 independently of immutable message content.
101
102 =item IMAP INTERNALDATE, JMAP receivedAt, rt: search prefix
103
104 The first valid timestamp value of Received: headers (top first).
105 If no Received: header exists, the Date: header is used, and the
106 current time if neither header(s) exist.  When mirroring via
107 git, this is the git commit time.
108
109 =item IMAP SENT*, JMAP sentAt, dt: and d: search prefixes
110
111 The first valid timestamp value of the Date: header(s).
112 If no Date: header exists, the time from the Received: header is
113 used, and then the current time if neither header exists.
114 When mirroring via git, this is the git author time.
115
116 =back
117
118 =head1 COPYRIGHT
119
120 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
121
122 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
123
124 =head1 SEE ALSO
125
126 L<public-inbox-v2-format(5)>, L<public-inbox-v1-format(5)>,
127 L<public-inbox-extindex-format(5)>, L<gitglossary(7)>