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 accommodate 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 accommodate 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)>