source/projects/activitypub_relay

ActivityPub Relay

A generic ActivityPub/LitePub compatible with Pleroma and Mastodon.

What is a relay?

A relay is a webserver implementing ActivityPub/LitePub. Normally when posting content on an ActivityPub server, that content is only listed publicly on the feed of the hosting server, and servers to which your server announces that content.

Relays provide a way for ActivityPub servers to announce posts to and receive posts from a wider audience. For instance there are public lists of nodes offering relaying.

Nuts and bolts of ActivityPub

ActivityPub is a protocol by which Actors exchange messages. An actor consists of two key things - an inbox and an outbox. The inbox is a URL to which other actors can POST messages. The outbox is a URL naming a paginated collection which other actors can GET to read messages from.

Any user in an ActivityPub system, for instance @arrdem@macaw.social is an actor with such an inbox outbox pair. ActivityPub messages for follows of users or messages mentioning users are implemented with messages directly to the user's outbox.

In addition, Mastodon ActivityPub servers themselves have "instance actors". These actors communicate using server to server interactions. Instance actors (f. ex. https://macaw.social/actor) emit and receive messages regarding system level activities. New posts (Create) are the major thing, but plenty of other messages flow through too.

The relay "protocol" is a Follow of the relay's actor by an ActivityPub server that wishes to participate in the relay. The relay will acknowledge the follow request, and then itself follow the participating server back. These two follow relationships in place, the participating server will announce any new posts to the relay since the relay follows it. This is just the normal ActivityPub behavior. Likewise, the relay will announce any new posts it gets from elsewhere to the participating server. Same deal.

That's it.

Why relays at all?

In theory, two ActivityPub servers can talk to each other directly. Why relays?

Relays are 1 to N bridges. Follow one relay, get activity from every other host on that bridge. This makes it easier for new, small nodes to participate in a wider network since they only need to follow one host not follow every single other host. Traditional relay/clearing house model.

What is this program?

The relay itself is a webserver providing two major components.

• A hardcoded webfinger implementation for resolving the user acct:relay@your.relay.hostname
• A message relay, which will perform a stateless relay of new activity to connected nodes

The relay offers three moderation capabilities:

• An explicit allowlist mode restricting connected nodes
• A denylist mode restricting connected nodes by name
• A denylist mode restricting connected nodes by self-identified server software

Getting Started

Normally, you would direct your LitePub instance software to follow the LitePub actor found on the relay. In Pleroma this would be something like:

$ MIX_ENV=prod mix relay_follow https://your.relay.hostname/actor

On Mastodon the process is similar, in Administration > Relays > Add New Relay one would list the relay's URL

https://your.relay.hostname/actor

Status

• Works
• Poorly packaged
• Not yet threaded (nor is upstream)
• Not yet tested (nor is upstream)
• Missing web-oriented administrative functionality
• Missing web-oriented configuration/state management

Copyright

This work is derived from https://git.pleroma.social/pleroma/relay, which is published under the terms of the AGPLv3.