PUBLIC-INBOX-GLOSSARY(7)

📦
version 2.0.0~20230714git590023f · 5 versions
, in fedora 43, fedora 44

🌸 public-inbox-glossary — bestie's glossary for public-inbox 🌸

okay so this is public-inbox-glossary(7) from the public-inbox user manual, and it's literally the decoder ring you need. no cap.

✨ NAME ✨

public-inbox-glossary — the glossary for public-inbox 💖

💅 DESCRIPTION 💅

so public-inbox is this iconic little mashup of several independently-developed protocols and data formats, and the way they overlap is... a lot. concepts collide, names don't match, and suddenly you're staring at four different words for the same idea. this document is the guide that helps you spot those overlapping concepts and figure out what's actually what. 🦋

it's mainly for hackers of public-inbox (iykyk), but it's also lowkey useful for admins running public-facing services and/or for users out here building tools. 🫶

🌈 TERMS 🌈

⭐ IMAP UID, NNTP article number, on-disk Xapian docid

a sequentially-assigned positive integer, bestie. these integers are per-inbox, or per-extindex. it's the "num" column of the "over" table in "over.sqlite3". periodt.

⭐ tid, THREADID

also a sequentially-assigned positive integer, and also per-inbox or per-extindex. in the future, this may get prefixed with "T" for JMAP (RFC 8621) and RFC 8474. heads up though: this may not be strictly compliant with RFC 8621 since inboxes and extindices are considered independent entities from each other. 😭

this is the "tid" column of the "over" table in "over.sqlite3".

⭐ blob

for email, this is the git blob object ID (SHA-(1|256)) of an RFC-(822|2822|5322) email message. that's it, that's the blob. ✨

⭐ IMAP EMAILID, JMAP Email Id

to-be-decided, bestie. 💀 this will likely be the git blob ID prefixed with "g" rather than the numeric UID, so that the same blob can show up in both an extindex and an inbox (or multiple extindices). iconic problem-solving, honestly.

⭐ newsgroup

the name of the NNTP newsgroup, see public-inbox-config(5). simple. clean. slay.

⭐ IMAP (folder|mailbox) slice

a 50K slice of a newsgroup, created to accommodate the limitations of IMAP clients with public-inbox-imapd(1). it's the "newsgroup" name with a ".$INTEGER_SUFFIX", so like — a newsgroup named "inbox.test" would have its first slice named "inbox.test.0", and second slice named "inbox.test.1" and so forth. 🎀

if implemented, the RFC 8474 MAILBOXID of an IMAP slice will NOT have the same Mailbox Id as the public-facing full JMAP mailbox. important!! don't mix those up.

⭐ inbox name, public JMAP mailbox name

the HTTP(S) name of the public-inbox ("publicinbox.<name>.*"). JMAP will use this name rather than the newsgroup name, since public-facing JMAP will be part of the PSGI code and not need a separate daemon like public-inbox-nntpd(1) or public-inbox-imapd(1). no extra daemon, no extra stress. 💜

⭐ epoch

a git repository used for blob storage. see "GIT EPOCHS" in public-inbox-v2-format(5). 👑

⭐ keywords, (IMAP|Maildir) flags, mbox Status + X-Status

private, per-message keywords or flags as described in RFC 8621 section 10.4. these get conveyed in the "Status:" and "X-Status:" headers for mbox(5), as system IMAP FLAGS (RFC 3501 section 2.3.2), or as Maildir info flags. so many outfits for the same vibe.

real talk: public-inbox-watch(1) ignores drafts and trashed (deleted) messages. lei-import(1) ignores trashed (deleted) messages, but it imports drafts. the way these two differ is genuinely sending me 😭

⭐ labels, private JMAP mailboxes

for lei(1) users only, bestie. this will let lei users place the same email into one or more virtual folders for ease-of-filtering. this is NOT tied to public-inbox names, since messages stored by lei may not be public. 🙈

these are similar in spirit to arbitrary freeform "tags" in mail software such as notmuch(1) and non-system IMAP FLAGS. same energy, different name.

⭐ volatile metadata (VMD)

for lei(1) users only, this refers to the combination of keywords and labels, which are subject to frequent change independently of immutable message content. volatile as in it will not sit still, not as in it's about to explode. 💅

⭐ IMAP INTERNALDATE, JMAP receivedAt, rt: search prefix

the first valid timestamp value of Received: headers (top first). if no Received: header exists, the Date: header is used, and the current time if neither header(s) exist. when mirroring via git, this is the git commit time. ⭐

⭐ IMAP SENT*, JMAP sentAt, dt: and d: search prefixes

the first valid timestamp value of the Date: header(s). if no Date: header exists, the time from the Received: header is used, and then the current time if neither header exists. when mirroring via git, this is the git author time. 🌈

Copyright 2021 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <http://www.gnu.org/licenses/agpl-3.0.txt>

👑 SEE ALSO 👑

and that's the whole glossary, bestie, go forth and know what a tid is 💖

this page came from the public-inbox.git source, version dated 1993-10-02, and it's PUBLIC-INBOX-GLOSSARY(7). mwah, bye 🫶✨

📦 where this page comes from