snac2/doc/snac.5

.Dd $Mdocdate$
.Dt SNAC 5
.Os
.Sh NAME
.Nm snac
.Nd message formatting and file format documentation
.Sh DESCRIPTION
The
.Nm
daemon processes messages from other servers in the Fediverse
using the ActivityPub protocol.
.Pp
This manual describes the allowed formatting of note messages
and the disk storage layout of
.Nm
server and user data. For the operation manual, see
.Xr snac 1 .
For the administration manual, see
.Xr snac 8 .
.Ss Message Formatting
Message notes respect the entered new line breaks rigurously.
A special subset of Markdown is allowed, including:
.Bl -tag -width tenletters
.It bold
**text between two pairs of asterisks**
.It italic
*text between a pair of asterisks*
.It code
Text `between backticks` is formatted as code.
.Bd -literal
```
/* text between lines with only three backticks is preformatted */
int main(int argc, char *argv[])
{
    return 0;
}

```
.Ed
.It links
Standalone URLs.
.It quoted text
Lines starting with >.
.It User Mentions
Strings in the format @user@host are requested using the Webfinger
protocol and converted to links and mentions if something reasonable
is found.
.It Emoticons / Smileys
The following traditional ASCII emoticons or special strings are
converted to related emojis:
.Bd -literal
:-) :-D X-D ;-) B-) :-( :-*
:-/ 8-o %-) :_( :-| :facepalm: :shrug:
.Ed
.El
.Pp
HTML tags are left untouched. This is probably a bad idea that may
change in future versions.
.Pp
.Ss Disk Layout
This section documents version 1 of the disk storage layout. It's still
subject to change.
.Pp
The base directory contains the following files and folders:
.Bl -tag -width tenletters
.It Pa server.json
Server configuration.
.It Pa user/
Directory holding user subdirectories.
.It Pa archive/
If this directory exists, all input and output messages are logged inside it,
including HTTP headers. Only useful for debugging. May grow to enormous sizes.
.El
.Pp
Each user directory is a subdirectory of 
.Pa BASEDIR/user/ ,
has the user id as name and contains the following subdirectories and files:
.Bl -tag -width tenletters
.It Pa user.json
User configuration file.
.It Pa key.json
SHA-1 secret/public key PEM data.
.It Pa actors/
This subdirectory stores cached 'Person' ActivityPub messages as JSON files. Each
file name is an MD5 hash of the actor URL.
.It Pa timeline/
This subdirectory stores the user's timeline. Everytime a valid message arrives,
it's stored in this directory as a JSON object. The file name spec is: a Unix
timestamp followed by a hyphen followed by an MD5 of the message Id. Additionally,
metadata for each message parent and children is stored under the '_snac' field;
parent messages with new children are renamed with an updated timestamp so that
the more recently updated thread is shown at the top. This directory is presented
in the web interface in reverse file name order up to a maximum, hardcoded limit.
These files are purged when they are considered old (this time can be changed by
tweaking the server configuration).
.It Pa local/
This subdirectory stores all activities generated by this user as hardlinks to
their analogue entries in the
.Pa timeline/
subdirectory. These files are never deleted.
.It Pa followers/
This subdirectory stores the 'Follow' ActivityPub message from each
Fediverse user that is following this user as a JSON file. Each file name is
an MD5 hash of the actor that is a follower of this user.
.It Pa following/
This subdirectory stores the 'Follow' (not yet confirmed) or the 'Accept'
(confirmed) ActivityPub message for each actor that is being followed. Each file
name is an MD5 hash of the actor.
.It Pa muted/
This directory contains files which names are MD5 hashes of muted actors. The
content is a line containing the actor URL.
Messages from these actors will be ignored on input and not shown in any timeline.
.It Pa queue/
This directory contains the output queue of messages generated by the user as
JSON files. File names contain timestamps that indicate when the message will
be sent. Messages not accepted by their respective servers will be re-enqueued
for later retransmission until a maximum number of retries is reached,
then discarded.
.It Pa static/
Files in this directory are served as-is when requested from the
.Pa https://HOST/s/...
URL path. A special file named
.Pa style.css
can contain user-specific CSS code to be inserted into the HTML of the
web interface.
.It Pa history/
This directory contains generated HTML files. They may be snapshots of the
local timeline in previous months or other cached data.
.It Pa archive/
This directory is no longer used in version 2.x and later. It can be deleted.
.Nm
is run with a debug level >= 1.
.El
.Sh SEE ALSO
.Xr snac 1 ,
.Xr snac 8
.Sh AUTHORS
.An grunfink
.Sh LICENSE
See the LICENSE file for details.