honk/docs/spec.txt

honk spec

-- references

See security.txt for some notes on security.

See ping.txt for a proposed Ping extension to ActivityPub.

-- retries

If a message can't be delivered, we backoff and retry.

1 - five minutes later in case the servce restarted
2 - one hour later in case the server rebooted
3 - 12 more hours later in case the server was upgraded
4 - 24 more hours later in case there was a catastrophe
5 - it's dead.

A random drift of up to 10% is added to each delay to avoid swarming.

-- federating

Messages are transformed for federation and display. Some transformations
occur send side and some occur receive side because it's more exciting that
way. @mentions and *markdown* are converted to HTML before transmission.
Message :emoji: are converted to inline images after receiving.

Up to four parents of a reply will be fetched.

Attachments for received messages are rescaled before saving.

-- schema

Some notes on the database schema. Mostly for development, but maybe useful
for administration as well.

The config table contains settings, some of which may not be editable via the
normal interface.

For development purposes, adding a config value ('debug', 1) to the database
will disable caching and hot reload the templates. It's not meant to be
harmful in production, just less efficient.

We don't use null, only empty strings. This is easier to work with on the go
side.

The main table is honks. This stores both locally created honks and incoming
ActivityPub notes converted to honks. It is important to differentiate the two
cases so that we don't accidentally publish external honks in the public web
view. (Previously this was accomplished via separate tables. That made some
queries more difficult, but I think it's possible to workaround this. It would
be considerably safer.) The honker column will be empty for local honks.

The what column further refines the type of honk. If a reply, tonk.
If shared, bonk. In particular for the case of bonk, there
aren't enough columns to store original honker and bonker.
This seems to work out okay though.

Attachments are physically saved as files, and logically joined to honks via
the donks table. Emus are saved as donks as well.

The honkers table is used to manage follows and followers. The flavor column
describes what. 'sub' is a follow. We have subscribed to their newsletter.
'dub' is a follower. They get dubbed whenever we honk.

The xonkers table stores info about external accounts that we may interact
with. Their keys, their inboxes, etc. Not user visible.

The zonkers table stores things we do not wish to see, per the wherefore
column. zonkers are bad people, zurls are bad hosts, zonvoys are bad threads.

The xid column generally corresponds to ActivityPub id. For local honks, it
will be a short string, not a complete URL.

Note that some logical seeming joins won't work. The honker column of honks
may not have a corresponding entry in the honkers table, since we frequently
receive messages from people we don't follow. Should we track everybody whose
identity crosses our path? This seems unnecessary. The honkers table is more
like a mapping of active relationships, not a directory of all peoples.

Some deduping of honks is performed. This may not be perfect.