81 lines
3.8 KiB
Markdown
81 lines
3.8 KiB
Markdown
|
# 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](https://github.com/brodi1/activitypub-relays) of nodes offering relaying.
|
||
|
|
|
||
|
|
### Nuts and bolts of ActivityPub
|
||
|
|
|
||
|
|
[ActivityPub](https://www.w3.org/TR/activitypub/) is a protocol by which [Actors](https://www.w3.org/TR/activitypub/#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"](https://github.com/mastodon/mastodon/issues/10453).
|
||
|
|
These actors communicate using [server to server interactions](https://www.w3.org/TR/activitypub/#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.
|