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