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 keywords, (IMAP|Maildir) flags, mbox Status + X-Status
  71
  72 Private, per-message keywords or flags as described in RFC 8621
  73 section 10.4.  These are conveyed in the C<Status:> and
  74 C<X-Status:> headers for L<mbox(5)>, as system IMAP FLAGS
  75 (RFC 3501 section 2.3.2), or Maildir info flags.
  76
  77 L<public-inbox-watch(1)> ignores drafts and trashed (deleted)
  78 messages.  L<lei-import(1)> ignores trashed (deleted) messages,
  79 but it imports drafts.
  80
  81 =item labels, private JMAP mailboxes
  82
  83 For L<lei(1)> users only.  This will allow lei users to place
  84 the same email into one or more virtual folders for
  85 ease-of-filtering.  This is NOT tied to public-inbox names, as
  86 messages stored by lei may not be public.
  87
  88 These are similar in spirit to arbitrary freeform "tags"
  89 in mail software such as L<notmuch(1)> and non-system IMAP FLAGS.
  90
  91 =item volatile metadata (VMD)
  92
  93 For L<lei(1)> users only, this refers to the combination of
  94 keywords and labels which are subject to frequent change
  95 independently of immutable message content.
  96
  97 =item IMAP INTERNALDATE, JMAP receivedAt, rt: search prefix
  98
  99 The first valid timestamp value of Received: headers (top first).
 100 If no Received: header exists, the Date: header is used, and the
 101 current time if neither header(s) exist.  When mirroring via
 102 git, this is the git commit time.
 103
 104 =item IMAP SENT*, JMAP sentAt, dt: and d: search prefixes
 105
 106 The first valid timestamp value of the Date: header(s).
 107 If no Date: header exists, the time from the Received: header is
 108 used, and then the current time if neither header exists.
 109 When mirroring via git, this is the git author time.
 110
 111 =back
 112
 113 =head1 COPYRIGHT
 114
 115 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 116
 117 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 118
 119 =head1 SEE ALSO
 120
 121 L<public-inbox-v2-format(5)>, L<public-inbox-v1-format(5)>,
 122 L<public-inbox-extindex-format(5)>, L<gitglossary(7)>