root/db/FORMAT.txt

The basic idea is that the database file is an append-only journal.
For now, there is no "vacuum" or "expire".  The file SHOULD NOT be
edited, only appened to.

The file is a line-oriented text file.  A record consists of a
transaction start line, followed by a record description line, then
zero or more dot-stuffed lines (in the style of RFC 3977), and finally
a transaction end line.  The idea is that a truncated record can (and
MUST) always be detected and ignored.

Lines end with either LF or CRLF.  Readers MUST be able to handle both
formats, and convert between them when required for other media (for
example, NNTP requires CRLF, and so any LF neeeds to be converted to
CRLF before sending over NNTP).

WARNING: The format is not safe for concurrent writing.

A record starts with the line
.BEGIN <datetime>
where <datetime> is in ISO format (yyyymmddThhmmss) and in UTC, indicating the
timestamp of the record.

A record ends with the line
.END

Empty lines between records must be ignored.


                             USER records

.BEGIN <datetime>
USER <userid>
<attribute> <value>
.END

USER MUST NOT be repeated inside the same record.

The attribute lines MAY be repeated and MAY be omitted.

Possible <attributes>:
  - display_name (string)
  - display_email (string)
  - delivery_email (string)
  - delivery_email_verified ("yes" / "no") [default: no]
  - delivery_email_cookie (string)
  - allow_cleartext_password ("yes" / "no")
  - has_read (string: msgid)
  - has_not_read (string: msgid)

If the userid doesn't yet exist, it is created with the given
settings.  If it exists, the included setting changes are made.


                             ROLE records

.BEGIN <datetime>
ROLE <name>
DESCRIPTION <description>
USER ADD <userid>
USER DEL <userid>
.END

The ROLE line is REQUIRED and MUST NOT be repeated.
The other lines are OPTIONAL.
USER lines may be repeated.

If the role doesn't exist yet, it is created with the given settings.
If it exists, the included setting changes are made.

NOTE: The following role names are reserved: anonymous, authenticated,
poster.  Similarly, all names starting with "subscribers:" and
"moderator:" are reserved.  No ROLE records may be given for
"anonymous" and "authenticated".  ROLE records for the other reserved
names are forbidden to include DESCRIPTION.


                           NEWGROUP records

.BEGIN <datetime>
NEWGROUP <groupname>
DESCRIPTION <group description for LIST NEWSGROUPS>
READING <permission-token>
.END

The NEWGROUP MUST NOT be repeated.

<permission-token> is PERMITTED | RESTRICTED (the latter meaning that
the group is available only to authenticated users)


                           ARTICLE records

.BEGIN <datetime>
ARTICLE <msgid>
POSTED BY <userid>
FILE AS <groupname>:<article-number>
FOLLOWS
<article header and body>
.END

The FILE AS line SHOULD occur at least once, and MAY occur multiple times.
POSTED BY is recommended but may be omitted.
The other lines are REQUIRED.

The <article header and body> lines MUST be dot-stuffed as discussed
in RFC 3977.  However, it ends in .END, not a lone dot line.

The article SHOULD NOT contain a Xref header field; if there is one,
it MUST be ignored (and a new one generated based on the actual server
state).


                          MODERATION records

.BEGIN <datetime>
MODERATION <userid>
<verb> <msgid> <reason>
.END

<verb> ::= KILL
         | SPAM
         | CLEAR

<reason> ::= <text not containing line terminator or separator>

The MODERATION line is REQUIRED and MUST NOT be repeated.  The other
lines MAY occur multiple times.  The <userid> indicates the user who
authorized these moderation actions.

The effect of a KILL or SPAM line is to make the message disappear
(the reason is free form text that is intended to be used as
rationale); it will be as if it never existed.  The effect of a CLEAR
line is to undo a previous KILL or SPAM line.