diff options
Diffstat (limited to 'doc/snac.5')
| -rw-r--r-- | doc/snac.5 | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/doc/snac.5 b/doc/snac.5 new file mode 100644 index 0000000..a5311e4 --- /dev/null +++ b/doc/snac.5 @@ -0,0 +1,131 @@ +.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. +.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. +.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 stores all input/output traffic of ActivityPub messages. There +is a different file for each day. This information is only stored if +.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. |